@opengeni/contracts 0.50.0 → 2.2.0-canary.0

package/src/index.ts

@@ -1,4 +1,5 @@
 import { z } from "zod";
+import { Permission } from "./permissions";
 import { ScopedKnowledgeScope } from "./scoped-knowledge";
 import {
   boundSessionEventPayload,
@@ -10,11 +11,14 @@ import { MemorySlackPublicationDistribution } from "./memory-slack-delivery";
 import { WorkspaceInstructionPolicyRoleKeyInput } from "./workspace-instruction-policies";
 import { ClientResumableVoiceInputConfig } from "./transcription-recordings";
 import { MediaGenerationResult } from "./video-generation";
+import { KnowledgeProviderCitation } from "./knowledge";
+import { XaiProviderAccountAuthoritySnapshotV1 } from "./xai-provider-account-authority";
 
 export * from "./slack-bot-scopes";
 export * from "./slack-task-policy";
 export * from "./atlassian";
 export * from "./connector-destinations";
+export * from "./connector-attachments";
 export * from "./memory-slack-delivery";
 export * from "./image-generation";
 export * from "./video-generation";
@@ -22,7 +26,10 @@ export * from "./editable-artifacts";
 export * from "./editable-artifact-committed-transaction";
 export * from "./editable-artifact-serialized-commit";
 export * from "./tool-catalog";
+export * from "./tool-result-spill";
 export * from "./interaction";
+export * from "./sandbox-file-artifacts";
+export * from "./permissions";
 
 export {
   CreateWorkspaceArtifactRequest,
@@ -118,15 +125,21 @@ export {
 export {
   NATIVE_SNAPSHOT_PREFIXES,
   WORKSPACE_ARCHIVE_DESCRIPTOR_VERSION,
+  WORKSPACE_ARCHIVE_OBJECT_REF_SCHEMA,
   backendForNativeSnapshotProvider,
   decodeNativeSnapshotRef,
   encodeNativeSnapshotRef,
+  omitInlineWorkspaceArchiveWhenObjectRefPresent,
   parseWorkspaceArchiveDescriptor,
+  parseWorkspaceArchiveObjectRef,
+  workspaceArchiveObjectKey,
+  workspaceArchivePayloadPresent,
   type NativeSnapshotDescriptor,
   type NativeSnapshotProvider,
   type NativeSnapshotRef,
   type TarWorkspaceArchiveDescriptor,
   type WorkspaceArchiveDescriptor,
+  type WorkspaceArchiveObjectRef,
   type WorkspaceTreeFingerprint,
 } from "./sandbox-snapshots";
 
@@ -147,11 +160,12 @@ export const SessionStatus = z.enum([
 ]);
 export type SessionStatus = z.infer<typeof SessionStatus>;
 
-// 11 backends; 3-way enum parity (contracts / sdk / deployment) is pinned by
+// 12 backends; 3-way enum parity (contracts / sdk / deployment) is pinned by
 // `packages/sdk/test/contract-parity.test.ts`. Every member is ADDITIVE AT THE
 // END (the parity test pins positions): the original four, then the six cloud
 // backends, then `selfhosted` (bring-your-own-compute — a user's own machine
-// enrolled as a first-class sandbox).
+// enrolled as a first-class sandbox), then `opensandbox` (an optional
+// Kubernetes-native provisioned sandbox provider).
 export const SandboxBackend = z.enum([
   "docker",
   "modal",
@@ -164,6 +178,7 @@ export const SandboxBackend = z.enum([
   "cloudflare",
   "vercel",
   "selfhosted",
+  "opensandbox",
 ]);
 export type SandboxBackend = z.infer<typeof SandboxBackend>;
 
@@ -189,6 +204,7 @@ export const SANDBOX_PROVIDER_INSTANCE_ID_FIELDS_BY_BACKEND = {
   cloudflare: ["sandboxId"],
   vercel: ["sandboxId"],
   selfhosted: ["agentId"],
+  opensandbox: ["sandboxId"],
 } as const satisfies Record<SandboxBackend, readonly string[]>;
 export const LEGACY_SANDBOX_PROVIDER_INSTANCE_ID_FIELDS = [
   "sandboxId",
@@ -593,6 +609,36 @@ export const CAPABILITY_DESCRIPTORS: Record<SandboxBackend, CapabilityDescriptor
     persistable: false,
     supportsRunAs: false,
   },
+  // Optional Kubernetes-native provisioned sandbox through OpenSandbox.
+  // Desktop-class when the box image includes ttyd/browserd/Xvfb: PTY over ttyd,
+  // noVNC and browserd over signed URI-mode ingress. OpenGeni owns persistence
+  // through its portable tar checkpoint path in object storage; native
+  // OpenSandbox pause/resume and snapshots are deliberately not used.
+  opensandbox: {
+    backend: "opensandbox",
+    backendId: "opensandbox",
+    tier: "desktop",
+    os: { supported: ["linux"], default: "linux" },
+    capabilities: {
+      FileSystem: { available: true, readOnly: false },
+      Terminal: { available: true, transport: "sse-events", pty: true },
+      Git: { available: true },
+      DesktopStream: { available: true, transport: "vnc-ws" },
+      Recording: { available: true },
+    },
+    lifetime: {
+      requiresSnapshotRollover: false,
+      hasIdleKiller: false,
+      supportsSuspendResume: false,
+      resumeIsLockFree: true,
+    },
+    snapshot: { kind: "tar-only", hasTarFallback: true },
+    portExposure: { kind: "provider-tunnel", supportsOnDemandPorts: true },
+    workspaceRoot: "/workspace",
+    nativeBucketMount: false,
+    persistable: true,
+    supportsRunAs: false,
+  },
 };
 
 export const ReasoningEffort = z.enum(["none", "minimal", "low", "medium", "high", "xhigh", "max"]);
@@ -672,91 +718,6 @@ export const SessionSpawnDenial = z.object({
 });
 export type SessionSpawnDenial = z.infer<typeof SessionSpawnDenial>;
 
-export const Permission = z.enum([
-  "account:read",
-  "account:admin",
-  "members:manage",
-  "workspace:create",
-  "billing:read",
-  "billing:manage",
-  "workspace:read",
-  "workspace:admin",
-  "sessions:create",
-  "sessions:read",
-  "sessions:control",
-  // sandbox workspace (sandbox contract §C.3 / crosscut PART 1.2). stream:view is a
-  // REAL, distinct permission — strictly BROADER than sessions:read — because the
-  // pixel plane (Channel B) exposes raw pixels: a viewer can see content the
-  // structured Channel-A event log never captured. sessions:read is NOT
-  // permission to watch raw pixels.
-  "stream:view",
-  // SEPARATE from stream:view: raw input to the desktop (bypasses approvalQueue /
-  // interrupt). NEVER granted by default in v1 (the input plane is OFF —
-  // streamControlEnabled=false); the permission exists so later hardening is a
-  // flag flip, not a redesign.
-  "stream:control",
-  // Accept the pixel-plane secret-leak acknowledgment (consent gate before the
-  // un-redacted desktop URL is handed out).
-  "stream:acknowledge",
-  "files:upload",
-  "files:read",
-  // Channel-A structured write surface (FS writes / apply-patch); distinct from
-  // files:read so a read-only viewer can't mutate the box filesystem.
-  "files:write",
-  // Attach to an interactive PTY (terminal-as-pty, Channel A); distinct from
-  // sessions:read which only reads the command-output firehose.
-  "terminal:attach",
-  "documents:manage",
-  "documents:search",
-  "scheduled_tasks:manage",
-  "scheduled_tasks:run",
-  "github:manage",
-  "github:use",
-  "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:list",
-  "variable-sets:read",
-  "variable-sets:write",
-  "variable-sets:manage",
-  "variable-sets:use",
-  "secrets:list",
-  "secrets:read",
-  "secrets:write",
-  // 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.
-  "mcp_servers:attach",
-  // Programmatic sandbox -> tool access through the first-party MCP gate. This is
-  // intentionally narrow and is never part of first-party MCP defaults; callers
-  // must receive it through an explicit delegated `ogd_` mint carrying sessionId.
-  "codemode:call",
-  "goals:manage",
-  // Bring-your-own-compute (M5). enrollments:read lists a workspace's machines;
-  // enrollments:manage approves a device-flow enrollment (the LOUD whole-machine
-  // consent) + revokes a machine. Distinct from sessions/stream perms because an
-  // enrollment grants WHOLE-MACHINE access to a user's own hardware — a high-trust,
-  // admin-shaped action. workspace:admin is the super-wildcard over both.
-  "enrollments:read",
-  "enrollments:manage",
-  // 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",
-  // Workspace-published HTML artifacts. Read permits listing/source retrieval;
-  // publish permits create, version publication, and rollback.
-  "artifacts:read",
-  "artifacts:publish",
-]);
-export type Permission = z.infer<typeof Permission>;
-
 /**
  * Capability-first permissions signed into a session's first-party OpenGeni
  * MCP token when a top-level creator does not explicitly narrow them.
@@ -780,8 +741,12 @@ export const DEFAULT_FIRST_PARTY_MCP_PERMISSIONS = [
   // tools resolve an already-installed workspace principal. Credentials stay
   // inside the broker and remain subject to each tool's own authorization.
   "connections:read",
+  "variable-sets:list",
+  "variable-sets:write",
+  "variable-sets:attach",
   "variable-sets:use",
-  "variable-sets:manage",
+  "secrets:list",
+  "secrets:write",
   "rigs:use",
   "github:use",
   "artifacts:read",
@@ -801,6 +766,7 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "goal_set",
   "goal_update",
   "goal_progress",
+  "goal_wait",
   "goal_complete",
   "goal_pause",
   "memory_search",
@@ -811,6 +777,18 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "task_notes_list",
   "task_note_save",
   "task_note_archive",
+  "task_note_replace",
+  "knowledge_propose",
+  "knowledge_correct",
+  "task_note_promote_knowledge",
+  "task_note_promote_instruction_policy",
+  "task_note_promote_preference",
+  "instruction_policy_propose",
+  "preference_propose",
+  "remember",
+  "remember_confirm",
+  "company_profile_propose",
+  "company_profile_confirm",
   "sandboxes_list",
   "sandbox_attach",
   "sandbox_swap",
@@ -825,11 +803,13 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "sessions_list",
   "session_get",
   "session_events",
+  "session_wait",
   "session_create",
   "session_send_message",
   "session_pause",
   "session_resume",
   "session_steer",
+  "session_human_input_respond",
   "set_other_session_title",
   "interaction_discover",
   "browser_open",
@@ -888,6 +868,7 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "scheduled_tasks_delete",
   "scheduled_task_runs_list",
   "slack_bot_list_channels",
+  "slack_bot_search",
   "slack_bot_channel_history",
   "slack_bot_thread_replies",
   "slack_bot_list_users",
@@ -914,6 +895,7 @@ export const FIRST_PARTY_MCP_TOOL_NAMES = [
   "artifacts_create",
   "artifacts_publish",
   "artifacts_rollback",
+  "sandbox_file_publish",
   "editable_artifact_list",
   "editable_artifact_create",
   "editable_artifact_import",
@@ -964,8 +946,15 @@ const FIRST_PARTY_IN_PROCESS_TOOL_NAME_SET = new Set<FirstPartyMcpToolName>(
  * trustworthy logical-delivery identity. Server-owned Slack delivery paths
  * call the internal client directly with their own durable operation IDs.
  */
+// Names kept so previously written data still parses - immutable scheduled-task
+// execution snapshots recorded the tool set that was default at the time, and
+// they are strictly re-parsed on replay. Retiring a tool must not strand an
+// accepted occurrence. These are never registered, never default, and never
+// authorized; they exist so history stays readable.
 const FIRST_PARTY_COMPATIBILITY_ONLY_TOOL_NAMES = [
   "slack_bot_post_message",
+  "memory_save",
+  "memory_correct",
 ] as const satisfies readonly FirstPartyMcpToolName[];
 
 const FIRST_PARTY_COMPATIBILITY_ONLY_TOOL_NAME_SET = new Set<FirstPartyMcpToolName>(
@@ -998,6 +987,10 @@ export const EDITABLE_ARTIFACT_MCP_CODEMODE_PATHS = {
  */
 export const DEFAULT_FIRST_PARTY_MCP_TOOLS = FIRST_PARTY_MCP_TOOL_NAMES.filter(
   (name) =>
+    // Memory V1 writes are retired entirely; `remember` and task-note
+    // promotion own durable agent writes.
+    name !== "memory_save" &&
+    name !== "memory_correct" &&
     !name.startsWith("social_") &&
     !name.startsWith("x_") &&
     !name.startsWith("reddit_") &&
@@ -1053,6 +1046,178 @@ export const PersonalResourceRetentionMode = z.enum(["retain", "delete_after"]);
 export type PersonalResourceRetentionMode = z.infer<typeof PersonalResourceRetentionMode>;
 
 export const SessionTenancyVisibility = z.enum(["user_private", "workspace_shared"]);
+
+export const UserResourceAuthorityScope = z.literal("user");
+export const UserResourceKind = z.enum([
+  "connection",
+  "document",
+  "variable_set",
+  "rig",
+  "connected_machine",
+]);
+export type UserResourceKind = z.infer<typeof UserResourceKind>;
+
+export const USER_RESOURCE_ACTION_BY_KIND = {
+  connection: "connection.use",
+  document: "document.read",
+  variable_set: "variable_set.use",
+  rig: "rig.use",
+  connected_machine: "connected_machine.use",
+} as const satisfies Record<UserResourceKind, string>;
+
+export const UserResourceLifecycleGrantMode = z.enum(["once", "session", "always"]);
+export const PERSONAL_RESOURCE_SHARED_OUTPUT_WARNING_VERSION = 1 as const;
+export const PERSONAL_RESOURCE_SHARED_OUTPUT_WARNING =
+  "Personal resources used in a workspace-shared session may influence outputs visible to other workspace members. The underlying credentials and secret values are not shared by the attachment itself.";
+
+/**
+ * Owner-authored issuance intent for the fixed personal Variable Set/Rig/
+ * Connected Machine closure selected by one session. The server derives every resource,
+ * authority and action from the locked session; callers never nominate grants.
+ */
+export const PersonalResourceAttachmentIntent = z
+  .object({
+    mode: UserResourceLifecycleGrantMode,
+    expectedAuthorityEpoch: z.number().int().positive().optional(),
+    workspaceSharedAcknowledged: z.boolean().default(false),
+    sharedOutputWarningVersion: z.literal(PERSONAL_RESOURCE_SHARED_OUTPUT_WARNING_VERSION),
+  })
+  .strict();
+export type PersonalResourceAttachmentIntent = z.infer<typeof PersonalResourceAttachmentIntent>;
+
+function requireEstablishedPersonalResourceEpoch(
+  value: {
+    personalResourceAttachment?: PersonalResourceAttachmentIntent | undefined;
+  },
+  context: z.RefinementCtx,
+): void {
+  if (
+    value.personalResourceAttachment !== undefined &&
+    value.personalResourceAttachment.expectedAuthorityEpoch === undefined
+  ) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["personalResourceAttachment", "expectedAuthorityEpoch"],
+      message: "established-session attachment requires expectedAuthorityEpoch",
+    });
+  }
+}
+
+/** Credential-free accepted-work projection. Resource ids remain private. */
+export const PersonalResourceAttachmentSummary = z
+  .object({
+    mode: UserResourceLifecycleGrantMode,
+    context: SessionTenancyVisibility,
+    resourceCount: z.number().int().positive(),
+    resourceKinds: z
+      .array(z.enum(["variable_set", "rig", "connected_machine"]))
+      .min(1)
+      .max(3),
+    sharedOutputWarningVersion: z.literal(PERSONAL_RESOURCE_SHARED_OUTPUT_WARNING_VERSION),
+  })
+  .strict();
+export type PersonalResourceAttachmentSummary = z.infer<typeof PersonalResourceAttachmentSummary>;
+/** Public owner-management deliberately excludes race-prone standalone `once`. */
+export const ManagedUserResourceGrantMode = z.enum(["session", "always"]);
+export const UserResourceAuthorityGrant = z.object({
+  grantId: z.string().uuid(),
+  targetWorkspaceId: z.string().uuid(),
+  targetSessionId: z.string().uuid().nullable(),
+  action: z.enum([
+    "connection.use",
+    "document.read",
+    "variable_set.use",
+    "rig.use",
+    "connected_machine.use",
+  ]),
+  mode: UserResourceLifecycleGrantMode,
+  context: SessionTenancyVisibility,
+  authorityEpoch: z.number().int().positive().nullable(),
+  generation: z.number().int().positive(),
+  status: z.enum(["active", "consumed", "revoked", "expired"]),
+  expiresAt: z.string().datetime().nullable(),
+  delegation: z.lazy(() => UserResourceDelegation),
+});
+export const UserResourceAuthoritySummary = z.object({
+  authorityId: z.string().uuid(),
+  resourceKind: UserResourceKind,
+  resourceId: z.string().uuid(),
+  originWorkspaceId: z.string().uuid().nullable(),
+  generation: z.number().int().positive(),
+  status: z.enum(["active", "retained", "revoked"]),
+  grants: z.array(UserResourceAuthorityGrant),
+});
+export const ListUserResourceAuthoritiesQuery = z.object({
+  scope: UserResourceAuthorityScope,
+  resourceKind: UserResourceKind,
+  cursor: z.string().uuid().optional(),
+  limit: z.coerce.number().int().min(1).max(100).default(50),
+});
+export const ListUserResourceAuthoritiesResponse = z.object({
+  scope: UserResourceAuthorityScope,
+  authorities: z.array(UserResourceAuthoritySummary),
+  nextCursor: z.string().uuid().nullable(),
+});
+export const IssueUserResourceGrantRequest = z
+  .object({
+    scope: UserResourceAuthorityScope,
+    resourceKind: UserResourceKind,
+    mode: ManagedUserResourceGrantMode,
+    context: SessionTenancyVisibility,
+    sessionId: z.string().uuid().nullable().optional(),
+    expectedAuthorityEpoch: z.number().int().positive().nullable().optional(),
+    workspaceSharedAcknowledged: z.boolean().default(false),
+  })
+  .superRefine((value, context) => {
+    if (value.context === "workspace_shared" && !value.workspaceSharedAcknowledged) {
+      context.addIssue({
+        code: "custom",
+        path: ["workspaceSharedAcknowledged"],
+        message: "workspace_shared requires durable shared-output acknowledgement",
+      });
+    }
+    if (value.mode === "always" && (value.sessionId || value.expectedAuthorityEpoch)) {
+      context.addIssue({
+        code: "custom",
+        path: ["sessionId"],
+        message: "always is unbound from session authority",
+      });
+    }
+    if (value.mode === "session" && (!value.sessionId || !value.expectedAuthorityEpoch)) {
+      context.addIssue({
+        code: "custom",
+        path: ["sessionId"],
+        message: "session grants require a target session and expectedAuthorityEpoch",
+      });
+    }
+  });
+export const UserResourceGrantMutationResponse = z.object({
+  scope: UserResourceAuthorityScope,
+  grant: UserResourceAuthorityGrant,
+});
+export const UserResourceGrantRevocationResponse = z.object({
+  scope: UserResourceAuthorityScope,
+  grant: z.object({
+    grantId: z.string().uuid(),
+    generation: z.number().int().positive(),
+    status: z.literal("revoked"),
+    revokedAt: z.string().datetime(),
+  }),
+});
+export const RevokeUserResourceGrantQuery = z.object({
+  scope: UserResourceAuthorityScope,
+});
+export type UserResourceAuthorityGrant = z.infer<typeof UserResourceAuthorityGrant>;
+export type UserResourceAuthoritySummary = z.infer<typeof UserResourceAuthoritySummary>;
+export type ListUserResourceAuthoritiesQuery = z.infer<typeof ListUserResourceAuthoritiesQuery>;
+export type ListUserResourceAuthoritiesResponse = z.infer<
+  typeof ListUserResourceAuthoritiesResponse
+>;
+export type IssueUserResourceGrantRequest = z.infer<typeof IssueUserResourceGrantRequest>;
+export type UserResourceGrantMutationResponse = z.infer<typeof UserResourceGrantMutationResponse>;
+export type UserResourceGrantRevocationResponse = z.infer<
+  typeof UserResourceGrantRevocationResponse
+>;
 export type SessionTenancyVisibility = z.infer<typeof SessionTenancyVisibility>;
 
 /** Public/session API vocabulary. Persistence keeps the explicit tenancy names. */
@@ -1274,6 +1439,100 @@ export const SessionTenancyPublicProjection = z.object({
 });
 export type SessionTenancyPublicProjection = z.infer<typeof SessionTenancyPublicProjection>;
 
+export const SessionTenancyBlocker = z.enum([
+  "nonterminal_turn",
+  "nonterminal_attempt",
+  "unsettled_interruption",
+  "pending_system_update",
+  "pending_human_input",
+  "pending_tool_receipt",
+  "run_state",
+  "active_goal",
+  "capacity_waiter",
+  "active_realtime",
+  "active_scheduled_task",
+  "workspace_mutation_admission",
+  "retained_process",
+  "active_sandbox_access",
+  "shared_sandbox_group",
+]);
+export type SessionTenancyBlocker = z.infer<typeof SessionTenancyBlocker>;
+
+export const SESSION_OPERATION_KEY_MAX_CHARS = 256;
+const SessionTenancyIdempotencyKey = z.string().trim().min(1).max(SESSION_OPERATION_KEY_MAX_CHARS);
+
+export const UpdateSessionVisibilityRequest = z
+  .object({
+    visibility: SessionVisibility,
+    expectedAuthorityEpoch: z.number().int().positive().max(Number.MAX_SAFE_INTEGER),
+    idempotencyKey: SessionTenancyIdempotencyKey,
+  })
+  .strict();
+export type UpdateSessionVisibilityRequest = z.infer<typeof UpdateSessionVisibilityRequest>;
+
+export const UpdateSessionVisibilityResponse = z
+  .object({
+    operationId: z.string().uuid(),
+    eventId: z.string().uuid().nullable(),
+    eventSequence: z.number().int().positive().nullable(),
+    visibility: SessionVisibility,
+    authorityEpoch: z.number().int().positive(),
+    changed: z.boolean(),
+    replay: z.boolean(),
+    revokedGrantCount: z.number().int().nonnegative(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.changed !== (value.eventId !== null && value.eventSequence !== null)) {
+      context.addIssue({
+        code: "custom",
+        path: ["changed"],
+        message: "changed must match the presence of the durable event receipt",
+      });
+    }
+    if ((value.eventId === null) !== (value.eventSequence === null)) {
+      context.addIssue({
+        code: "custom",
+        path: ["eventId"],
+        message: "eventId and eventSequence must be present or absent together",
+      });
+    }
+  });
+export type UpdateSessionVisibilityResponse = z.infer<typeof UpdateSessionVisibilityResponse>;
+
+export const ForkSessionRequest = z
+  .object({
+    idempotencyKey: SessionTenancyIdempotencyKey,
+    visibility: SessionVisibility,
+    workspaceSharedAcknowledged: z.boolean(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (value.visibility === "private" && value.workspaceSharedAcknowledged) {
+      context.addIssue({
+        code: "custom",
+        path: ["workspaceSharedAcknowledged"],
+        message: "workspaceSharedAcknowledged must be false for a private destination",
+      });
+    }
+  });
+export type ForkSessionRequest = z.infer<typeof ForkSessionRequest>;
+
+export const ForkSessionResponse = z
+  .object({
+    operationId: z.string().uuid(),
+    eventId: z.string().uuid(),
+    eventSequence: z.number().int().positive(),
+    sessionId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    visibility: SessionVisibility,
+    authorityEpoch: z.literal(1),
+    copiedHistoryItemCount: z.number().int().nonnegative(),
+    replay: z.boolean(),
+  })
+  .strict();
+export type ForkSessionResponse = z.infer<typeof ForkSessionResponse>;
+
 export const ManagedAccount = z.object({
   id: z.string().uuid(),
   name: z.string(),
@@ -1621,6 +1880,37 @@ export const WorkspaceVoiceInputSettings = z
   .strict();
 export type WorkspaceVoiceInputSettings = z.infer<typeof WorkspaceVoiceInputSettings>;
 
+/** Model policy inherited by newly created chats and scheduled tasks. */
+export const WorkspaceSessionDefaults = z
+  .object({
+    model: z.string().trim().min(1).max(256),
+    reasoningEffort: ReasoningEffort,
+  })
+  .strict();
+export type WorkspaceSessionDefaults = z.infer<typeof WorkspaceSessionDefaults>;
+
+/**
+ * Exact capability selection inherited by new top-level sessions.
+ *
+ * The product UI presents understandable capability groups, but persistence
+ * stays source-of-truth exact: MCP server ids and first-party tool names. This
+ * keeps the runtime independent from presentation labels and lets a session
+ * narrow the resulting policy without changing the workspace default.
+ */
+export const WorkspaceSessionToolDefaults = z
+  .object({
+    mcpServerIds: z
+      .array(z.string().trim().min(1).max(128))
+      .max(128)
+      .transform((ids) => [...new Set(ids)]),
+    firstPartyMcpTools: z
+      .array(FirstPartyMcpToolName)
+      .max(512)
+      .transform((tools) => [...new Set(tools)]),
+  })
+  .strict();
+export type WorkspaceSessionToolDefaults = z.infer<typeof WorkspaceSessionToolDefaults>;
+
 /** Client-safe voice-input capability projection. Never includes provider secrets. */
 export const ClientVoiceInputConfig = z
   .object({
@@ -1714,17 +2004,79 @@ export const DEFAULT_WORKSPACE_SLACK_REACTION_SUMMON_SETTINGS = {
   channelPolicy: { mode: "bot_member" },
 } as const satisfies WorkspaceSlackReactionSummonSettings;
 
+/**
+ * Per-workspace switches for the two Slack orchestration notices: a pointer
+ * card when a child worker of a Slack-originated session blocks on human input
+ * or a tool approval, and a one-line notice when that session's goal pauses for
+ * budget or the continuation cap.
+ *
+ * Both are OFF unless this workspace explicitly turned them on. An unsolicited
+ * Slack post is worse than a missed one, and the in-app rail and priority feed
+ * already surface a blocked child, so an absent, malformed, or partially
+ * invalid setting resolves to both disabled - see
+ * `resolveWorkspaceSlackOrchestrationNoticeSettings`.
+ *
+ * Deliberately not `.strict()`: this is a KNOWN key of the stored settings bag,
+ * so rejecting it rejects the whole bag and silently reverts memoryEnabled,
+ * agentHumanInputEnabled, codexCompactionDefault, voiceInput, and the Slack
+ * reaction shortcut to their defaults too. An unknown key here is a notice a
+ * newer release added, and a rollback must not cost five unrelated settings.
+ * An invalid VALUE still fails the bag, and therefore fails closed to silence.
+ */
+export const WorkspaceSlackOrchestrationNoticeSettings = z.object({
+  childRequiresAction: z.boolean().optional(),
+  goalPaused: z.boolean().optional(),
+});
+export type WorkspaceSlackOrchestrationNoticeSettings = z.infer<
+  typeof WorkspaceSlackOrchestrationNoticeSettings
+>;
+
+/**
+ * The resolved answer: every notice is an explicit boolean, never absent.
+ * Spelled out rather than derived with `Required<>`, which would keep the
+ * `| undefined` that the optional zod fields carry into their inferred type.
+ */
+export type ResolvedWorkspaceSlackOrchestrationNoticeSettings = {
+  childRequiresAction: boolean;
+  goalPaused: boolean;
+};
+
+export const DEFAULT_WORKSPACE_SLACK_ORCHESTRATION_NOTICE_SETTINGS = {
+  childRequiresAction: false,
+  goalPaused: false,
+} as const satisfies ResolvedWorkspaceSlackOrchestrationNoticeSettings;
+
+// Memory V1's standing prompt block is retired, but the enum deliberately still
+// ACCEPTS `legacy_standing`. `.passthrough()` only preserves unknown keys - it
+// does not rescue a known key holding a value the enum rejects - so collapsing
+// this to one value would fail the whole settings parse for any workspace that
+// opted in. Every resolver here is "parse the bag, fall back on failure", so
+// that single rejection would silently revert memoryEnabled,
+// agentHumanInputEnabled, codexCompactionDefault, voiceInput and Slack summon
+// to their defaults. The value is accepted and then ignored: see
+// resolveWorkspaceMemoryPromptMode.
 export const WorkspaceMemoryPromptMode = z.enum(["legacy_standing", "retrieval_only"]);
 export type WorkspaceMemoryPromptMode = z.infer<typeof WorkspaceMemoryPromptMode>;
 
+/**
+ * What an already-accepted turn recorded. Snapshots and receipts are immutable,
+ * so turns accepted before the standing block was retired still read back
+ * `legacy_standing`. That is a fact about history, not a mode anyone can pick -
+ * keep the two apart so retiring the setting never rewrites the record.
+ */
+export const HistoricalMemoryPromptMode = z.enum(["legacy_standing", "retrieval_only"]);
+export type HistoricalMemoryPromptMode = z.infer<typeof HistoricalMemoryPromptMode>;
+
 // Validates the KNOWN keys of workspaces.settings; passthrough keeps unknown
 // (future) keys rather than stripping them. memoryEnabled defaults off and the
-// reversible Memory V1 containment rollout defaults to legacy standing context;
+// Memory V1 prompt mode is always retrieval-only composition;
 // voiceInput defaults to enabled when the deployment has a provider.
 export const WorkspaceSettingsSchema = z
   .object({
     memoryEnabled: z.boolean().optional(),
     memoryPromptMode: WorkspaceMemoryPromptMode.optional(),
+    sessionDefaults: WorkspaceSessionDefaults.optional(),
+    sessionToolDefaults: WorkspaceSessionToolDefaults.optional(),
     /** Preferred workspace voice-input toggle. */
     voiceInput: WorkspaceVoiceInputSettings.optional(),
     /**
@@ -1744,6 +2096,11 @@ export const WorkspaceSettingsSchema = z
     // Optional Slack reaction invocation. Absent/invalid fails closed to the
     // disabled default via resolveWorkspaceSlackReactionSummonSettings.
     slackReactionSummon: WorkspaceSlackReactionSummonSettings.optional(),
+    // Optional Slack orchestration notices (blocked child worker, paused goal).
+    // BOTH DEFAULT OFF: absent, malformed, or partially invalid settings fail
+    // closed to disabled via resolveWorkspaceSlackOrchestrationNoticeSettings,
+    // because an unsolicited Slack post is worse than a missed one.
+    slackOrchestrationNotices: WorkspaceSlackOrchestrationNoticeSettings.optional(),
   })
   .passthrough();
 export type WorkspaceSettings = z.infer<typeof WorkspaceSettingsSchema>;
@@ -1754,10 +2111,31 @@ export function resolveWorkspaceMemoryEnabled(settings: unknown): boolean {
   return parsed.success ? parsed.data.memoryEnabled === true : false;
 }
 
-/** Reversible Memory V1 prompt rollout. Absent preserves legacy composition. */
-export function resolveWorkspaceMemoryPromptMode(settings: unknown): WorkspaceMemoryPromptMode {
+/** Explicit defaults for new chats/schedules, or null for deployment defaults. */
+export function resolveWorkspaceSessionDefaults(
+  settings: unknown,
+): WorkspaceSessionDefaults | null {
+  const parsed = WorkspaceSettingsSchema.safeParse(settings ?? {});
+  return parsed.success ? (parsed.data.sessionDefaults ?? null) : null;
+}
+
+/** Exact capability defaults for new sessions, or null for deployment defaults. */
+export function resolveWorkspaceSessionToolDefaults(
+  settings: unknown,
+): WorkspaceSessionToolDefaults | null {
   const parsed = WorkspaceSettingsSchema.safeParse(settings ?? {});
-  return parsed.success ? (parsed.data.memoryPromptMode ?? "legacy_standing") : "legacy_standing";
+  return parsed.success ? (parsed.data.sessionToolDefaults ?? null) : null;
+}
+
+/**
+ * Memory V1 prompt mode. Always `retrieval_only`: the standing pinned/recency
+ * block is retired, so an absent, unrecognized, or stored-`legacy_standing`
+ * setting all resolve the same way. Kept as a function so the call sites and
+ * the frozen SQL snapshot keep agreeing without each one having to learn that
+ * the choice is gone.
+ */
+export function resolveWorkspaceMemoryPromptMode(): "retrieval_only" {
+  return "retrieval_only";
 }
 
 /** Default Codex compaction mode for new Codex sessions (remote_v2 when unset). */
@@ -1814,6 +2192,30 @@ export function resolveWorkspaceSlackReactionSummonSettings(
     : { ...configured, channelPolicy: { mode: "bot_member" } };
 }
 
+/**
+ * Resolve the two Slack orchestration notice switches, failing closed.
+ *
+ * Off is the product decision, not a placeholder: the in-app rail and priority
+ * feed already surface a blocked child worker and a paused goal, so a missed
+ * Slack post costs a delay while an unsolicited one costs the thread's
+ * credibility. Absent settings, a settings bag this schema rejects, and a
+ * partially invalid notice object therefore all resolve to both disabled -
+ * only an explicit `true` on a valid bag turns a notice on.
+ */
+export function resolveWorkspaceSlackOrchestrationNoticeSettings(
+  settings: unknown,
+): ResolvedWorkspaceSlackOrchestrationNoticeSettings {
+  const parsed = WorkspaceSettingsSchema.safeParse(settings ?? {});
+  const configured = parsed.success ? parsed.data.slackOrchestrationNotices : undefined;
+  return {
+    childRequiresAction:
+      configured?.childRequiresAction ??
+      DEFAULT_WORKSPACE_SLACK_ORCHESTRATION_NOTICE_SETTINGS.childRequiresAction,
+    goalPaused:
+      configured?.goalPaused ?? DEFAULT_WORKSPACE_SLACK_ORCHESTRATION_NOTICE_SETTINGS.goalPaused,
+  };
+}
+
 export function workspaceSlackReactionChannelAllowed(
   settings: WorkspaceSlackReactionSummonSettings,
   channelId: string,
@@ -1831,6 +2233,8 @@ export const UpdateWorkspaceSettingsRequest = z
   .object({
     memoryEnabled: z.boolean().optional(),
     memoryPromptMode: WorkspaceMemoryPromptMode.optional(),
+    sessionDefaults: WorkspaceSessionDefaults.optional(),
+    sessionToolDefaults: WorkspaceSessionToolDefaults.optional(),
     voiceInput: WorkspaceVoiceInputSettings.optional(),
     /** @deprecated Prefer `voiceInput`. Kept for one compatibility release. */
     transcription: WorkspaceTranscriptionPolicy.optional(),
@@ -1838,6 +2242,7 @@ export const UpdateWorkspaceSettingsRequest = z
     codexCompactionDefault: CodexCompactionMode.optional(),
     agentHumanInputEnabled: z.boolean().optional(),
     slackReactionSummon: WorkspaceSlackReactionSummonSettings.optional(),
+    slackOrchestrationNotices: WorkspaceSlackOrchestrationNoticeSettings.optional(),
   })
   .passthrough();
 export type UpdateWorkspaceSettingsRequest = z.infer<typeof UpdateWorkspaceSettingsRequest>;
@@ -2348,6 +2753,17 @@ export const StreamTokenPayload = z.object({
   // Short TTL (120s default); rotation is event-driven under the epoch fence,
   // not on a keepalive clock.
   exp: z.number().int().positive(),
+  // The authenticated subject the token was minted for (0281). Optional for
+  // rolling compatibility: old verifiers strip it, old mints omit it.
+  subjectId: z.string().min(1).max(512).optional(),
+  // The session authority epoch observed at mint (0281). The relay tracks the
+  // highest value presented per LIVE channel and rejects tokens below that
+  // floor. The floor is defense-in-depth, not the revocation authority: it
+  // lives only as long as the channel does (both sides detached, the
+  // half-open reaper, or a relay restart reset it), so a stale in-TTL token
+  // can still attach to a fresh channel. Real revocation is the mint refusing
+  // to issue new tokens plus the 120 s TTL bounding the old ones.
+  authorityEpoch: z.number().int().positive().optional(),
 });
 export type StreamTokenPayload = z.infer<typeof StreamTokenPayload>;
 
@@ -2509,6 +2925,7 @@ export const ApiKey = z.object({
   accountId: z.string().uuid(),
   workspaceId: z.string().uuid().nullable(),
   name: z.string(),
+  description: z.string().nullable(),
   prefix: z.string(),
   permissions: z.array(Permission),
   expiresAt: z.string().nullable(),
@@ -2521,6 +2938,7 @@ export type ApiKey = z.infer<typeof ApiKey>;
 
 export const CreateApiKeyRequest = z.object({
   name: z.string().min(1),
+  description: z.string().trim().min(1).max(500).optional(),
   workspaceId: z.string().uuid().optional(),
   permissions: z.array(Permission).min(1),
   expiresAt: z.string().datetime({ offset: true }).optional(),
@@ -2674,6 +3092,59 @@ export type InsightsBillingPath = z.infer<typeof InsightsBillingPath>;
 export const InsightsPricingSource = z.enum(["configured_list_price", "gateway_reported"]);
 export type InsightsPricingSource = z.infer<typeof InsightsPricingSource>;
 
+export const ModelContextContributionSource = z.enum([
+  "workspace_instruction_policy",
+  "legacy_workspace_instructions",
+  "preference_registry_descriptor",
+  "company_profile",
+  "legacy_memory_v1",
+  "runtime_skill_catalog",
+]);
+export type ModelContextContributionSource = z.infer<typeof ModelContextContributionSource>;
+
+/** Content-free per-call summary of model-visible Company Brain material. */
+export const ModelContextContributionSummary = z
+  .object({
+    source: ModelContextContributionSource,
+    items: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    utf8Bytes: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+    estimatedTokens: z.number().int().nonnegative().max(Number.MAX_SAFE_INTEGER),
+  })
+  .strict();
+export type ModelContextContributionSummary = z.infer<typeof ModelContextContributionSummary>;
+
+export const ModelContextContributionSummaries = z
+  .array(ModelContextContributionSummary)
+  .max(6)
+  .superRefine((summaries, context) => {
+    const seen = new Set<ModelContextContributionSource>();
+    for (const [index, summary] of summaries.entries()) {
+      if (seen.has(summary.source)) {
+        context.addIssue({
+          code: "custom",
+          message: "Model context contribution sources must be unique",
+          path: [index, "source"],
+        });
+      }
+      seen.add(summary.source);
+    }
+  });
+
+export const InsightsPromptContributionRow = ModelContextContributionSummary.extend({
+  calls: z.number().int().nonnegative(),
+});
+export type InsightsPromptContributionRow = z.infer<typeof InsightsPromptContributionRow>;
+
+export const InsightsPromptContributions = z.object({
+  /** Sum of UTF-8 byte / 4 estimates across calls with contribution receipts. */
+  estimatedTokens: z.number().int().nonnegative(),
+  utf8Bytes: z.number().int().nonnegative(),
+  coveredCalls: z.number().int().nonnegative(),
+  totalCalls: z.number().int().nonnegative(),
+  sources: z.array(InsightsPromptContributionRow),
+});
+export type InsightsPromptContributions = z.infer<typeof InsightsPromptContributions>;
+
 export const InsightsModelUsageRow = z.object({
   id: z.string().min(1),
   model: z.string().min(1),
@@ -2840,6 +3311,13 @@ export const WorkspaceInsightsSnapshot = z.object({
   drivers: z.array(InsightsSpendDriver),
   schedules: z.array(InsightsScheduleRow),
   recentCalls: z.array(InsightsModelCallRow),
+  promptContributions: InsightsPromptContributions.default({
+    estimatedTokens: 0,
+    utf8Bytes: 0,
+    coveredCalls: 0,
+    totalCalls: 0,
+    sources: [],
+  }),
   warmSeconds: z.number().nonnegative(),
   priorWarmSeconds: z.number().nonnegative(),
   warmGroups: z.array(InsightsWarmGroupRow),
@@ -2988,6 +3466,11 @@ export const GitCredentialRepositoryRef = z.object({
   access: GitRepositoryAccess.optional(),
   uri: z.string().min(1),
   ref: z.string().min(1),
+  /** Immutable commit the caller expects `ref` to materialize. */
+  expectedCommitSha: z
+    .string()
+    .regex(/^[0-9a-f]{40}$/)
+    .optional(),
   repositoryId: GitProviderRepositoryId.optional(),
   installationId: GitProviderRepositoryId.optional(),
   projectId: GitProviderRepositoryId.optional(),
@@ -3112,9 +3595,25 @@ export type GitCredentials = {
 export type SandboxSecretsRequest = {
   accountId: string;
   workspaceId: string;
-  // The variable set the run's session declares (null = unattached;
-  // the provider, like the self-mint path, returns null values for it).
+  // Exact live attempt authority. Hosts MUST revalidate this tuple, the
+  // session's selected resource identity, and any personal-resource grant
+  // immediately before returning plaintext.
+  sessionId: string;
+  turnId: string;
+  attemptId: string;
+  executionGeneration: number;
+  // Organization/workspace Variable Sets may be materialized by a pure
+  // service turn (for example, the scheduler). Personal Variable Sets still
+  // require this causal human and an exact personal-resource grant.
+  initiator: TurnInitiator;
+  initiatingHumanSubjectId: string | null;
   variableSetId: string;
+  /**
+   * Exact accepted scheduled-occurrence generation. Present only for scheduled
+   * attempts; ordinary live turns omit it, so hosts that predate this field keep
+   * working unchanged for those.
+   */
+  expectedGeneration?: number | null;
 };
 
 export type SandboxSecrets = {
@@ -3122,8 +3621,19 @@ export type SandboxSecrets = {
   // `environmentsEncryptionKeyBytes` decrypt. Same shape the self-mint path
   // produces (plaintext name→value).
   values: Record<string, string>;
-  // workspace-scope cross-check echo: the workspace the provider scoped these secrets to.
+  // Exact scope/resource echoes are mandatory so a host routing bug cannot
+  // inject a sibling tenant, resource, or stale attempt's plaintext.
+  accountId: string;
   workspaceId: string;
+  sessionId: string;
+  turnId: string;
+  attemptId: string;
+  executionGeneration: number;
+  variableSetId: string;
+  /** Must echo the request's `expectedGeneration` when one was supplied. */
+  expectedGeneration?: number | null;
+  scope: VariableSetScope;
+  generation: number;
   // 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).
@@ -3287,12 +3797,127 @@ export const McpPersonalConnectionDelegation = z
   .object({
     serverId: z.string().min(1).max(256),
     connectionId: z.string().uuid(),
+    /**
+     * Immutable physical workspace that owns an activated common-user
+     * connection. It is server-resolved from the selected authority and lets
+     * provider adapters load only that exact row when the accepted turn runs
+     * in another workspace of the same organization.
+     */
+    originWorkspaceId: z.string().uuid().optional(),
     ownerSubjectId: z.string().min(1).max(512),
     providerDomain: z.string().min(1).max(2048),
     kind: z.enum(["oauth2", "api_key", "app_install", "delegated"]).optional(),
-    connectionType: z.enum(["mcp", "social", "atlassian"]).optional(),
+    connectionType: z.enum(["mcp", "social", "atlassian", "github_personal"]).optional(),
+    /**
+     * Explicit common-authority grant selected by the owning human. Omission is
+     * retained only for legacy_user connections that cannot yet participate in
+     * the organization-user authority lifecycle.
+     */
+    userDelegation: UserResourceDelegation.optional(),
+    /**
+     * Personal GitHub only: the exact repository authority frozen when this
+     * accepted work was admitted. The credential binding is evidence, not an
+     * authorization; physical provider use must revalidate every mutable
+     * connection/grant/selection fence against this snapshot.
+     */
+    personalGitHubRepositorySelection: z
+      .object({
+        credentialBindingId: z.string().uuid(),
+        connectionAuthorityGeneration: z.number().int().positive(),
+        selectionGeneration: z.number().int().positive(),
+        repositories: z
+          .array(
+            z
+              .object({
+                repositoryId: z.string().regex(/^[1-9]\d*$/u),
+                fullName: z.string().min(3).max(140),
+                canonicalUrl: z.string().url().max(512),
+                ref: z.string().min(1).max(255),
+                access: GitRepositoryAccess,
+                selectionGeneration: z.number().int().positive(),
+              })
+              .strict(),
+          )
+          .min(1)
+          .max(100),
+      })
+      .strict()
+      .optional(),
+    /**
+     * Google Drive publication only: the exact output destination frozen when
+     * this delegation was accepted, so a later connection-settings change can
+     * never redirect an already-accepted turn's publication. Structurally
+     * mirrors GoogleDriveOutputDestination (defined in ./google-drive, which
+     * imports this module - hence the inline shape). Absent on pre-freeze
+     * turns, which keep the bounded legacy live-resolution behavior.
+     */
+    outputDestination: z
+      .object({
+        folderId: z.string().min(1).max(256),
+        folderName: z.string().min(1).max(1024),
+        driveId: z.string().min(1).max(256).nullable(),
+        location: z.enum(["my_drive", "shared_drive"]),
+        selectedAt: z.string().datetime({ offset: true }),
+      })
+      .strict()
+      .optional(),
   })
-  .strict();
+  .strict()
+  .superRefine((delegation, context) => {
+    const personalGitHub = delegation.connectionType === "github_personal";
+    if (personalGitHub !== (delegation.personalGitHubRepositorySelection !== undefined)) {
+      context.addIssue({
+        code: "custom",
+        path: ["personalGitHubRepositorySelection"],
+        message: "personal GitHub delegation requires one repository authority snapshot",
+      });
+    }
+    if (!personalGitHub) return;
+    if (
+      delegation.serverId !== "github:personal" ||
+      delegation.providerDomain !== "github.com" ||
+      delegation.kind !== "oauth2" ||
+      !delegation.originWorkspaceId ||
+      !delegation.userDelegation
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: "personal GitHub delegation requires exact user-owned connection authority",
+      });
+    }
+    const repositories = delegation.personalGitHubRepositorySelection?.repositories ?? [];
+    const repositoryIds = new Set<string>();
+    const canonicalUrls = new Set<string>();
+    repositories.forEach((repository, index) => {
+      const canonicalUrl = repository.canonicalUrl.toLowerCase();
+      if (
+        !/^[A-Za-z0-9](?:[A-Za-z0-9-]{0,38})\/[A-Za-z0-9_.-]{1,100}$/u.test(repository.fullName) ||
+        repository.canonicalUrl !== `https://github.com/${repository.fullName}`
+      ) {
+        context.addIssue({
+          code: "custom",
+          path: ["personalGitHubRepositorySelection", "repositories", index, "canonicalUrl"],
+          message: "personal GitHub repository identity must be canonical",
+        });
+      }
+      if (repositoryIds.has(repository.repositoryId)) {
+        context.addIssue({
+          code: "custom",
+          path: ["personalGitHubRepositorySelection", "repositories", index, "repositoryId"],
+          message: "personal GitHub repositories must be unique by provider id",
+        });
+      }
+      if (canonicalUrls.has(canonicalUrl)) {
+        context.addIssue({
+          code: "custom",
+          path: ["personalGitHubRepositorySelection", "repositories", index, "canonicalUrl"],
+          message: "personal GitHub repositories must be unique by canonical URL",
+        });
+      }
+      repositoryIds.add(repository.repositoryId);
+      canonicalUrls.add(canonicalUrl);
+    });
+  });
 export type McpPersonalConnectionDelegation = z.infer<typeof McpPersonalConnectionDelegation>;
 
 /**
@@ -3317,12 +3942,44 @@ export const McpPersonalConnectionDelegations = z
     }
   });
 
-export const McpPersonalConnectionSummary = McpPersonalConnectionDelegation.pick({
-  serverId: true,
-  providerDomain: true,
-});
+export const McpPersonalConnectionSummary = z
+  .object({
+    serverId: z.string().min(1).max(256),
+    providerDomain: z.string().min(1).max(2048),
+  })
+  .strict();
 export type McpPersonalConnectionSummary = z.infer<typeof McpPersonalConnectionSummary>;
 
+/**
+ * Public, credential-free selection of one exact personal connection grant for
+ * one selected MCP/first-party server. The owner is always derived server-side.
+ */
+export const McpConnectionAuthoritySelection = z
+  .object({
+    serverId: z.string().min(1).max(256),
+    connectionId: z.string().uuid(),
+    userDelegation: UserResourceDelegation,
+  })
+  .strict();
+export type McpConnectionAuthoritySelection = z.infer<typeof McpConnectionAuthoritySelection>;
+
+export const McpConnectionAuthoritySelections = z
+  .array(McpConnectionAuthoritySelection)
+  .max(128)
+  .superRefine((selections, context) => {
+    const seen = new Set<string>();
+    for (const [index, selection] of selections.entries()) {
+      if (seen.has(selection.serverId)) {
+        context.addIssue({
+          code: "custom",
+          message: "connection authority selections must be unique by serverId",
+          path: [index, "serverId"],
+        });
+      }
+      seen.add(selection.serverId);
+    }
+  });
+
 export type McpCredentialsRequest = {
   accountId: string;
   workspaceId: string;
@@ -3353,6 +4010,10 @@ export type McpCredentialsRequest = {
   toolName?: string;
   connectionRef: McpServerConnectionRef;
   forceRefresh: boolean;
+  /** Canonical credential-free authority frozen on the accepted turn. */
+  connectionUseAuthority?: unknown;
+  /** Stable idempotency key for this one physical provider request. */
+  connectionUseRequestId?: string;
 };
 
 export type McpCredentialAuthNeededReason =
@@ -3551,13 +4212,35 @@ export const CreateCheckoutResponse = z.object({
 });
 export type CreateCheckoutResponse = z.infer<typeof CreateCheckoutResponse>;
 
+export const CreateBillingPortalRequest = z.object({
+  accountId: z.string().uuid().optional(),
+  returnUrl: z.string().url().optional(),
+});
+export type CreateBillingPortalRequest = z.infer<typeof CreateBillingPortalRequest>;
+
+export const CreateBillingPortalResponse = z.object({
+  portalSessionId: z.string(),
+  url: z.string().url(),
+});
+export type CreateBillingPortalResponse = z.infer<typeof CreateBillingPortalResponse>;
+
 export const RepositoryResourceRef = z.object({
   kind: z.literal("repository"),
   uri: z.string().min(1),
   ref: z.string().min(1),
+  /**
+   * Optional immutable Git object fence. Repository materialization must fail
+   * when the checked-out HEAD is not this exact commit. Event-driven sessions
+   * use it to prevent a mutable PR branch from changing underneath a review.
+   */
+  expectedCommitSha: z
+    .string()
+    .regex(/^[0-9a-f]{40}$/)
+    .optional(),
   mountPath: z.string().min(1).optional(),
   subpath: z.string().min(1).optional(),
   provider: GitCredentialProvider.optional(),
+  connectionType: z.literal("github_personal").optional(),
   credentialBindingId: GitCredentialBindingId.optional(),
   access: GitRepositoryAccess.optional(),
   repositoryId: GitProviderRepositoryId.optional(),
@@ -3717,6 +4400,8 @@ export type FileResourceRef = z.infer<typeof FileResourceRef>;
  * reconstruct the same typed attachment input after a model switch or retry.
  */
 export const MODEL_ATTACHMENT_REFS_FIELD = "opengeni_attachment_refs" as const;
+/** Private marker for the compact attachment-reference carrier created by compaction. */
+export const MODEL_ATTACHMENT_CATALOG_MARKER = "opengeni_attachment_catalog" as const;
 /**
  * Structured timeline annotations retained beside the deterministic user-text
  * projection in canonical history. Provider adapters remove this OpenGeni
@@ -3816,6 +4501,25 @@ export function defaultRepositoryMountPath(
   );
 }
 
+/** Durable SDK/UI artifact root. Provisioned boxes also mount this path;
+ * Connected Machine execution does not treat it as an alias. */
+export const VIRTUAL_WORKSPACE_ROOT = "/workspace" as const;
+
+/**
+ * Cwd-relative path for shell/exec prompts. Durable receipts and `sandbox:` UI
+ * links keep the durable `/workspace/...` form. Tool receipts use the relative
+ * projection so they remain usable from either a provisioned box root or a
+ * Connected Machine's truthful host-native cwd.
+ */
+export function sandboxShellPath(virtualPath: string): string {
+  if (virtualPath === VIRTUAL_WORKSPACE_ROOT) return ".";
+  if (virtualPath.startsWith(`${VIRTUAL_WORKSPACE_ROOT}/`)) {
+    const relative = virtualPath.slice(VIRTUAL_WORKSPACE_ROOT.length + 1);
+    return relative.length > 0 ? relative : ".";
+  }
+  return virtualPath;
+}
+
 /** Resolve the exact mount used by API normalization, manifests, and clone hooks. */
 export const DEFAULT_FILE_RESOURCE_MOUNT_ROOT = ".opengeni/files" as const;
 
@@ -3984,6 +4688,9 @@ export const Document = z.object({
   authorityKind: DocumentAuthorityKind,
   authorityWorkspaceId: z.string().uuid().nullable(),
   authoritySubjectId: z.string().nullable(),
+  // Opaque handle used by the owning human to issue explicit personal-scope
+  // grants. Organization/workspace and legacy anchored personal rows are null.
+  authorityId: z.string().uuid().nullable().optional(),
   visibility: DocumentVisibility,
   createdBy: z.string().nullable(),
   agentAccess: z.boolean(),
@@ -4025,6 +4732,7 @@ export const DocumentSearchResult = z.object({
   authorityKind: DocumentAuthorityKind,
   authorityWorkspaceId: z.string().uuid().nullable(),
   authoritySubjectId: z.string().nullable(),
+  citation: KnowledgeProviderCitation.nullable().optional(),
 });
 export type DocumentSearchResult = z.infer<typeof DocumentSearchResult>;
 
@@ -4054,6 +4762,7 @@ export const IndexedDocumentProvenance = z.object({
   authoritySubjectId: z.string().nullable(),
   createdBy: z.string().nullable(),
   createdAt: z.string(),
+  citation: KnowledgeProviderCitation.nullable().optional(),
 });
 export type IndexedDocumentProvenance = z.infer<typeof IndexedDocumentProvenance>;
 
@@ -4134,6 +4843,77 @@ export const MoveDocumentRequest = z.object({
 });
 export type MoveDocumentRequest = z.infer<typeof MoveDocumentRequest>;
 
+export const DocumentAuthorityTuple = z.object({
+  kind: DocumentAuthorityKind,
+  workspaceId: z.string().uuid().nullable(),
+  subjectId: z.string().nullable(),
+  authorityId: z.string().uuid().nullable(),
+});
+export type DocumentAuthorityTuple = z.infer<typeof DocumentAuthorityTuple>;
+
+export const ReclassifyDocumentAuthorityRequest = z.object({
+  operationId: z.string().uuid(),
+  expectedAuthority: DocumentAuthorityTuple,
+  targetAuthorityKind: DocumentAuthorityKind,
+});
+export type ReclassifyDocumentAuthorityRequest = z.infer<typeof ReclassifyDocumentAuthorityRequest>;
+
+export const DocumentAuthorityReclassification = z.object({
+  operationId: z.string().uuid(),
+  documentId: z.string().uuid(),
+  previousAuthority: DocumentAuthorityTuple,
+  authority: DocumentAuthorityTuple,
+  createdAt: z.string().datetime({ offset: true }),
+});
+export type DocumentAuthorityReclassification = z.infer<typeof DocumentAuthorityReclassification>;
+
+export const DOCUMENT_AUTHORITY_RECLASSIFICATION_LIST_DEFAULT_LIMIT = 50;
+export const DOCUMENT_AUTHORITY_RECLASSIFICATION_LIST_MAX_LIMIT = 100;
+export const DOCUMENT_AUTHORITY_RECLASSIFICATION_CURSOR_MAX_CHARS = 1_024;
+
+export const ListDocumentAuthorityReclassificationsQuery = z.object({
+  limit: z.coerce
+    .number()
+    .int()
+    .positive()
+    .max(DOCUMENT_AUTHORITY_RECLASSIFICATION_LIST_MAX_LIMIT)
+    .default(DOCUMENT_AUTHORITY_RECLASSIFICATION_LIST_DEFAULT_LIMIT),
+  cursor: z.string().min(1).max(DOCUMENT_AUTHORITY_RECLASSIFICATION_CURSOR_MAX_CHARS).optional(),
+});
+export type ListDocumentAuthorityReclassificationsQuery = z.infer<
+  typeof ListDocumentAuthorityReclassificationsQuery
+>;
+
+export const ListDocumentAuthorityReclassificationsResponse = z.object({
+  receipts: z.array(DocumentAuthorityReclassification),
+  hasMore: z.boolean(),
+  nextCursor: z.string().max(DOCUMENT_AUTHORITY_RECLASSIFICATION_CURSOR_MAX_CHARS).nullable(),
+});
+export type ListDocumentAuthorityReclassificationsResponse = z.infer<
+  typeof ListDocumentAuthorityReclassificationsResponse
+>;
+
+export const RunDocumentDefaultCollectionBackfillRequest = z.object({
+  runId: z.string().uuid(),
+  operationId: z.string().uuid(),
+  batchSize: z.number().int().min(1).max(100).default(50),
+});
+export type RunDocumentDefaultCollectionBackfillRequest = z.infer<
+  typeof RunDocumentDefaultCollectionBackfillRequest
+>;
+
+export const DocumentDefaultCollectionBackfill = z.object({
+  runId: z.string().uuid(),
+  operationId: z.string().uuid(),
+  status: z.enum(["running", "completed"]),
+  lastWorkspaceId: z.string().uuid().nullable(),
+  processedCount: z.number().int().nonnegative(),
+  createdCount: z.number().int().nonnegative(),
+  adoptedCount: z.number().int().nonnegative(),
+  completedAt: z.string().datetime({ offset: true }).nullable(),
+});
+export type DocumentDefaultCollectionBackfill = z.infer<typeof DocumentDefaultCollectionBackfill>;
+
 export const DocumentSearchRequest = z.object({
   query: z.string().min(1),
   baseIds: z.array(z.string().uuid()).optional(),
@@ -4279,9 +5059,15 @@ export type WorkspaceMemorySearchResponse = z.infer<typeof WorkspaceMemorySearch
 export const ToolRef = z.object({
   kind: z.literal("mcp"),
   id: z.string().min(1),
+  // Session-scoped startup choice. `true` prepares this server's authorized
+  // schemas before the first model request; absent/false keeps it behind
+  // progressive discovery. This never grants a server or tool permission.
+  eager: z.boolean().optional(),
   // Non-fatal-on-connect marker for MCP server refs that can degrade
   // gracefully. On new input, absent/false is STRICT: the id must be configured
-  // and an unavailable registered server fails the turn. Persisted refs are
+  // and an unavailable registered server fails closed when its preparation is
+  // demanded. Only the independent eager marker makes that a startup failure.
+  // Persisted refs are
   // intersected with the current registry at each turn boundary, so a server
   // disconnected after admission is retained in policy/audit truth but skipped
   // until it is registered again. `optional:true` additionally makes runtime
@@ -4478,10 +5264,14 @@ export function mergeToolRefs(existing: ToolRef[], additions: ToolRef[]): ToolRe
     // strict occurrence upgrades the merged ref so an unavailable server fails
     // the turn. This preserves the fail-loud default when defaults, packs, and
     // per-turn tool selections are combined.
-    if (prior.optional === true && tool.optional !== true) {
-      const { optional: _dropped, ...strict } = prior;
-      byKey.set(key, strict);
-    }
+    const optional = prior.optional === true && tool.optional === true ? true : undefined;
+    const eager = prior.eager === true || tool.eager === true ? true : undefined;
+    byKey.set(key, {
+      kind: "mcp",
+      id: prior.id,
+      ...(optional ? { optional } : {}),
+      ...(eager ? { eager } : {}),
+    });
   }
   return order.map((key) => byKey.get(key)!);
 }
@@ -4635,6 +5425,9 @@ export const SESSION_GOAL_TEXT_MAX_BYTES = 8 * 1024;
 export const SESSION_GOAL_SUCCESS_CRITERIA_MAX_BYTES = 8 * 1024;
 export const SESSION_GOAL_RATIONALE_MAX_BYTES = 2 * 1024;
 export const SESSION_GOAL_PROGRESS_MAX_BYTES = 4 * 1024;
+export const SESSION_GOAL_ROOT_CONSTRAINT_MAX_BYTES = 512;
+export const SESSION_GOAL_ROOT_CONSTRAINTS_MAX_BYTES = 4 * 1024;
+export const SESSION_GOAL_ROOT_CONSTRAINTS_MAX_ITEMS = 16;
 
 export function sessionGoalUtf8Bytes(value: string): number {
   return new TextEncoder().encode(value).byteLength;
@@ -4649,6 +5442,43 @@ function boundedSessionGoalString(maxBytes: number, field: string) {
     });
 }
 
+function compareUtf8(left: string, right: string): number {
+  const encoder = new TextEncoder();
+  const leftBytes = encoder.encode(left);
+  const rightBytes = encoder.encode(right);
+  const length = Math.min(leftBytes.length, rightBytes.length);
+  for (let index = 0; index < length; index += 1) {
+    const difference = leftBytes[index]! - rightBytes[index]!;
+    if (difference !== 0) return difference;
+  }
+  return leftBytes.length - rightBytes.length;
+}
+
+export function normalizeSessionGoalRootConstraints(values: readonly string[]): string[] {
+  // PostgreSQL btrim(text) removes U+0020 at both ends. Keep the public
+  // projector byte-equivalent with the storage trigger instead of using
+  // JavaScript trim(), whose Unicode whitespace set is broader.
+  return [...new Set(values.map((value) => value.replace(/^ +| +$/g, "")))].sort(compareUtf8);
+}
+
+export const SessionGoalRootConstraintsWrite = z
+  .array(boundedSessionGoalString(SESSION_GOAL_ROOT_CONSTRAINT_MAX_BYTES, "goal root constraint"))
+  .transform(normalizeSessionGoalRootConstraints)
+  .pipe(
+    z
+      .array(z.string().min(1))
+      .max(SESSION_GOAL_ROOT_CONSTRAINTS_MAX_ITEMS)
+      .refine(
+        (values) =>
+          values.reduce((total, value) => total + sessionGoalUtf8Bytes(value), 0) <=
+          SESSION_GOAL_ROOT_CONSTRAINTS_MAX_BYTES,
+        {
+          message: `goal root constraints exceed ${SESSION_GOAL_ROOT_CONSTRAINTS_MAX_BYTES} aggregate UTF-8 bytes`,
+        },
+      ),
+  );
+export type SessionGoalRootConstraintsWrite = z.infer<typeof SessionGoalRootConstraintsWrite>;
+
 const SessionGoalTextWrite = boundedSessionGoalString(SESSION_GOAL_TEXT_MAX_BYTES, "goal text");
 const SessionGoalSuccessCriteriaWrite = boundedSessionGoalString(
   SESSION_GOAL_SUCCESS_CRITERIA_MAX_BYTES,
@@ -4667,6 +5497,7 @@ export const SessionGoalSnapshot = z.discriminatedUnion("state", [
     objectiveRevision: z.number().int().positive(),
     text: SessionGoalTextWrite,
     successCriteria: SessionGoalSuccessCriteriaWrite.nullable(),
+    rootConstraints: SessionGoalRootConstraintsWrite.default([]),
     mutationPolicy: SessionGoalMutationPolicy,
     capturedAt: z.string(),
   }),
@@ -4685,22 +5516,57 @@ export const SessionGoalRevision = z.object({
   resultObjectiveRevision: z.number().int().positive().nullable(),
   text: z.string().min(1),
   successCriteria: z.string().nullable(),
+  rootConstraints: z.array(z.string().min(1)).default([]),
   mutationPolicy: SessionGoalMutationPolicy,
   rationale: z.string().min(1),
   actor: z.enum(["agent", "api", "scheduled_task"]),
   actorTurnId: z.string().uuid().nullable(),
   actorAttemptId: z.string().uuid().nullable(),
   proposalId: z.string().uuid().nullable(),
+  rollbackOfRevisionId: z.string().uuid().nullable(),
   createdAt: z.string(),
 });
 export type SessionGoalRevision = z.infer<typeof SessionGoalRevision>;
 
+export const SESSION_GOAL_REVISION_LIST_DEFAULT_LIMIT = 50;
+export const SESSION_GOAL_REVISION_LIST_MAX_LIMIT = 100;
+
+export const ListSessionGoalRevisionsQuery = z.object({
+  limit: z.coerce
+    .number()
+    .int()
+    .positive()
+    .max(SESSION_GOAL_REVISION_LIST_MAX_LIMIT)
+    .default(SESSION_GOAL_REVISION_LIST_DEFAULT_LIMIT),
+  before: z.string().uuid().optional(),
+});
+export type ListSessionGoalRevisionsQuery = z.infer<typeof ListSessionGoalRevisionsQuery>;
+
+export const ListSessionGoalRevisionsResponse = z.object({
+  revisions: z.array(SessionGoalRevision),
+  hasMore: z.boolean(),
+  nextCursor: z.string().uuid().nullable(),
+});
+export type ListSessionGoalRevisionsResponse = z.infer<typeof ListSessionGoalRevisionsResponse>;
+
 export const ApplySessionGoalRevisionRequest = z.object({
   expectedObjectiveRevision: z.number().int().positive(),
   rationale: SessionGoalRationaleWrite.optional(),
 });
 export type ApplySessionGoalRevisionRequest = z.infer<typeof ApplySessionGoalRevisionRequest>;
 
+export const RejectSessionGoalRevisionRequest = z.object({
+  expectedObjectiveRevision: z.number().int().positive(),
+  rationale: SessionGoalRationaleWrite,
+});
+export type RejectSessionGoalRevisionRequest = z.infer<typeof RejectSessionGoalRevisionRequest>;
+
+export const RollbackSessionGoalRevisionRequest = z.object({
+  expectedObjectiveRevision: z.number().int().positive(),
+  rationale: SessionGoalRationaleWrite,
+});
+export type RollbackSessionGoalRevisionRequest = z.infer<typeof RollbackSessionGoalRevisionRequest>;
+
 export const SessionGoalPausedReason = z.enum([
   "agent",
   "user_pause",
@@ -4732,10 +5598,41 @@ export const SessionGoalContinuationReason = z.enum([
   "provider_backpressure",
   "session_cancelled",
   "system_work_pending",
+  "held_for_input",
+  // Idle backoff: consecutive no-input continuations are paced, and the next
+  // evaluation is armed as a delayed workflow wake at `nextAttemptAt`.
+  "backoff_pending",
   "missing_obligation",
 ]);
 export type SessionGoalContinuationReason = z.infer<typeof SessionGoalContinuationReason>;
 
+/**
+ * Why a paused goal became active again. `api` is the operator PATCH; the
+ * system resumes only a `max_auto_continuations` pause, and only because new
+ * external input arrived: a child result, scheduled occurrence, media result,
+ * Agent message, Agent Steer, or human/API Send/Steer. The cap is pacing,
+ * never user intent, so a `user_pause`/`api`/`agent`/`limits` pause is never
+ * auto-resumed.
+ */
+export const SessionGoalResumedReason = z.enum(["api", "external_input"]);
+export type SessionGoalResumedReason = z.infer<typeof SessionGoalResumedReason>;
+
+export const SessionGoalResumedEventPayload = z
+  .object({
+    goalId: z.string().uuid(),
+    actor: z.enum(["api", "system"]),
+    reason: SessionGoalResumedReason,
+    cause: z
+      .object({
+        kind: z.string().min(1),
+        updateId: z.string().uuid().optional(),
+        turnId: z.string().uuid().optional(),
+      })
+      .optional(),
+  })
+  .passthrough();
+export type SessionGoalResumedEventPayload = z.infer<typeof SessionGoalResumedEventPayload>;
+
 export const SessionGoalContinuation = z.object({
   state: SessionGoalContinuationState,
   reason: SessionGoalContinuationReason,
@@ -4743,6 +5640,12 @@ export const SessionGoalContinuation = z.object({
   observedRevision: z.number().int().nonnegative(),
   nextAttemptAt: z.string().datetime({ offset: true }).nullable(),
   lastError: z.string().nullable(),
+  /**
+   * The agent's stated reason for a `held_for_input` hold (`goal_wait`), so a
+   * human can see why the goal is waiting and until when (`nextAttemptAt`).
+   * Null for every other state; omitted by older servers.
+   */
+  holdReason: z.string().nullable().optional(),
 });
 export type SessionGoalContinuation = z.infer<typeof SessionGoalContinuation>;
 
@@ -4754,6 +5657,7 @@ export const SessionGoal = z.object({
   status: SessionGoalStatus,
   text: z.string(),
   successCriteria: z.string().nullable(),
+  rootConstraints: z.array(z.string().min(1)).default([]),
   evidence: z.string().nullable(),
   rationale: z.string().nullable(),
   pausedReason: z.string().nullable(),
@@ -4776,6 +5680,7 @@ export type SessionGoal = z.infer<typeof SessionGoal>;
 export const GoalSpec = z.object({
   text: SessionGoalTextWrite,
   successCriteria: SessionGoalSuccessCriteriaWrite.optional(),
+  rootConstraints: SessionGoalRootConstraintsWrite.optional(),
   maxAutoContinuations: z.number().int().positive().optional(),
   mutationPolicy: SessionGoalMutationPolicy.optional(),
 });
@@ -4789,6 +5694,7 @@ export const UpdateSessionGoalRequest = z.union([
   z.object({
     text: SessionGoalTextWrite,
     successCriteria: SessionGoalSuccessCriteriaWrite.nullable().optional(),
+    rootConstraints: SessionGoalRootConstraintsWrite.optional(),
     mutationPolicy: SessionGoalMutationPolicy.optional(),
     rationale: SessionGoalRationaleWrite,
     expectedObjectiveRevision: z.number().int().positive(),
@@ -4836,6 +5742,40 @@ export const UpdateSessionPinRequest = z.object({
 });
 export type UpdateSessionPinRequest = z.infer<typeof UpdateSessionPinRequest>;
 
+/**
+ * A member's durable follow-up state for one session. Reading the session does
+ * not acknowledge it: `unread` changes only through this explicit mutation.
+ * A foreground reader may provide `acknowledgedThroughSequence` with
+ * `unread: false` so later server events remain unread instead of being
+ * consumed by a delayed acknowledgement request.
+ * `activelyWorking` is an independent personal label that survives read state.
+ */
+export const UpdateSessionAttentionRequest = z
+  .object({
+    unread: z.boolean().optional(),
+    acknowledgedThroughSequence: z.number().int().nonnegative().optional(),
+    activelyWorking: z.boolean().optional(),
+    expectedVersion: z.number().int().nonnegative().optional(),
+  })
+  .strict()
+  .refine((value) => value.unread !== undefined || value.activelyWorking !== undefined, {
+    message: "unread or activelyWorking is required",
+  })
+  .refine((value) => value.acknowledgedThroughSequence === undefined || value.unread === false, {
+    message: "acknowledgedThroughSequence requires unread false",
+    path: ["acknowledgedThroughSequence"],
+  });
+export type UpdateSessionAttentionRequest = z.infer<typeof UpdateSessionAttentionRequest>;
+
+/** A member's personal archive state for a root chat. */
+export const UpdateSessionArchiveRequest = z
+  .object({
+    archived: z.boolean(),
+    expectedVersion: z.number().int().nonnegative().optional(),
+  })
+  .strict();
+export type UpdateSessionArchiveRequest = z.infer<typeof UpdateSessionArchiveRequest>;
+
 // 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`.
@@ -4890,6 +5830,34 @@ export function isClearedRunStateBlob(serialized: string | null | undefined): bo
   }
 }
 
+/**
+ * Sentinel written on a requires_action pause. Resume must not call
+ * `RunState.fromString` on it; the open suffix on `session_pending_tool_calls`
+ * plus paired history is the resume authority.
+ */
+export const OPEN_SUFFIX_RUN_STATE_MARKER = "$opengeniOpenSuffix" as const;
+
+/** Canonical sentinel serializedRunState for a requires_action pause. */
+export const OPEN_SUFFIX_RUN_STATE_BLOB = JSON.stringify({
+  [OPEN_SUFFIX_RUN_STATE_MARKER]: true,
+});
+
+export function isOpenSuffixRunStateBlob(serialized: string | null | undefined): boolean {
+  if (!serialized) {
+    return false;
+  }
+  try {
+    const parsed = JSON.parse(serialized) as unknown;
+    return (
+      typeof parsed === "object" &&
+      parsed !== null &&
+      (parsed as Record<string, unknown>)[OPEN_SUFFIX_RUN_STATE_MARKER] === true
+    );
+  } catch {
+    return false;
+  }
+}
+
 /** Trigger conversation compaction now. No body fields today (forward-room). */
 export const CompactSessionContextRequest = z.object({}).strict();
 export type CompactSessionContextRequest = z.infer<typeof CompactSessionContextRequest>;
@@ -5089,8 +6057,26 @@ export const SessionRealtimeInboundEntry = z
     delegationItemId: z.string().max(1024).nullable().optional(),
     text: z.string().max(131_072).nullable().optional(),
     payload: z.record(z.string(), z.unknown()).optional(),
+    // Application context attached to the exact delegation/transcript message.
+    // It is ordinary model-visible user-message content when materialized, not
+    // a secret or instruction-authority boundary.
+    modelContext: z.string().trim().min(1).max(32768).optional(),
   })
-  .strict();
+  .strict()
+  .superRefine((entry, context) => {
+    if (
+      entry.modelContext !== undefined &&
+      entry.kind !== "delegation_call" &&
+      entry.kind !== "user_transcript" &&
+      entry.kind !== "assistant_transcript"
+    ) {
+      context.addIssue({
+        code: "custom",
+        path: ["modelContext"],
+        message: "modelContext requires a delegation or finalized transcript entry",
+      });
+    }
+  });
 export type SessionRealtimeInboundEntry = z.infer<typeof SessionRealtimeInboundEntry>;
 
 export const SyncSessionRealtimeLedgerRequest = SessionRealtimeOwnerProof.extend({
@@ -5153,7 +6139,12 @@ export type WorkspaceRealtimeModelCatalogResponse = z.infer<
 export const SessionRealtimeState = z.enum(["active", "ended"]);
 export type SessionRealtimeState = z.infer<typeof SessionRealtimeState>;
 
-export const SessionRealtimeEndReason = z.enum(["user_stop", "browser_unload", "lease_expired"]);
+export const SessionRealtimeEndReason = z.enum([
+  "user_stop",
+  "browser_unload",
+  "lease_expired",
+  "authority_revoked",
+]);
 export type SessionRealtimeEndReason = z.infer<typeof SessionRealtimeEndReason>;
 
 export const SessionRealtimeMode = z.object({
@@ -5221,6 +6212,9 @@ export const SessionAuthorizationOperation = z.enum([
   "session.secret.read",
   "session.codemode.call",
   "session.pin.write",
+  "session.attention.write",
+  "session.archive.write",
+  "session.delete",
   "session.codex_account.write",
   "session.realtime.start",
   "session.realtime.control",
@@ -5237,6 +6231,7 @@ export const SessionAuthorizationOperation = z.enum([
   "session.child.create",
   "session.visibility.write",
   "session.fork.create",
+  "session.personal_resource.grant",
 ]);
 export type SessionAuthorizationOperation = z.infer<typeof SessionAuthorizationOperation>;
 
@@ -5559,6 +6554,69 @@ export function renderTimelineAnnotationsForModel(
   ].join("\n");
 }
 
+export const MODEL_CONTEXT_LABEL = "[Application context attached to this user message]" as const;
+export const SESSION_GOAL_CONTEXT_LABEL =
+  "[Session goal frozen when this turn was accepted]" as const;
+
+/**
+ * Render the exact goal authority frozen with one accepted logical turn. Goal
+ * state belongs at the chronological input boundary, not in the mutable
+ * Agent.instructions prefix.
+ */
+export function renderSessionGoalContext(snapshot?: SessionGoalSnapshot): string | undefined {
+  if (!snapshot || snapshot.state === "none") return undefined;
+  const rootConstraints = snapshot.rootConstraints.length
+    ? `\nRoot constraints (must remain satisfied):\n${snapshot.rootConstraints.map((constraint) => `- ${constraint}`).join("\n")}`
+    : "";
+  if (snapshot.state === "completed") {
+    return `Previous session goal (frozen at logical-turn acceptance; objective revision ${snapshot.objectiveRevision}; status completed): ${snapshot.text}\nSuccess criteria: ${snapshot.successCriteria ?? "none specified"}.${rootConstraints} This goal is complete and remains as historical context. If the user provides a new long-running objective, create it with opengeni__goal_set; goal_update cannot revise a completed goal.`;
+  }
+  const policy =
+    snapshot.mutationPolicy === "review_changes"
+      ? "Semantic changes are proposals until a user applies them."
+      : snapshot.mutationPolicy === "preserve_intent"
+        ? "You may directly refine wording without changing intent; adaptations and replacements are proposals until a user applies them."
+        : "You may autonomously refine, adapt, or replace the goal when explicit user direction or material new evidence justifies it.";
+  return `Standing session goal (frozen at logical-turn acceptance; objective revision ${snapshot.objectiveRevision}; status ${snapshot.state}): ${snapshot.text}\nSuccess criteria: ${snapshot.successCriteria ?? "none specified"}.${rootConstraints}\nMutation policy: ${snapshot.mutationPolicy}. ${policy} Treat later ordinary messages as additional context unless they explicitly redirect this objective. Root constraints are user/API authority and cannot be widened, removed, or rewritten by an agent. Semantic goal changes use opengeni__goal_update with the expected objective revision, change kind, and rationale.`;
+}
+
+/**
+ * Build one canonical user-role message body. `modelContext` is ordinary
+ * message content, while `goalSnapshot` is the exact goal authority frozen at
+ * turn acceptance. Both remain in the visible message's chronological
+ * position, and presentation layers may omit their leading parts.
+ */
+export function renderUserMessageContentForModel(
+  text: string,
+  annotations: readonly TimelineAnnotation[],
+  modelContext?: string | null,
+  goalSnapshot?: SessionGoalSnapshot,
+): string | Array<{ type: "input_text"; text: string }> {
+  const visibleContent = renderTimelineAnnotationsForModel(text, annotations);
+  const context = modelContext?.trim();
+  const goalContext = renderSessionGoalContext(goalSnapshot);
+  if (!context && !goalContext) return visibleContent;
+  return [
+    ...(goalContext
+      ? [
+          {
+            type: "input_text" as const,
+            text: `${SESSION_GOAL_CONTEXT_LABEL}\n${goalContext}`,
+          },
+        ]
+      : []),
+    ...(context
+      ? [
+          {
+            type: "input_text" as const,
+            text: `${MODEL_CONTEXT_LABEL}\n${context}`,
+          },
+        ]
+      : []),
+    { type: "input_text", text: visibleContent },
+  ];
+}
+
 export const SessionTurn = z
   .object({
     id: z.string().uuid(),
@@ -5579,7 +6637,7 @@ export const SessionTurn = z
     toolsProvided: z.boolean().optional(),
     model: z.string().min(1),
     reasoningEffort: ReasoningEffort,
-    latencyMode: LatencyMode.default("standard"),
+    latencyMode: LatencyMode,
     sandboxBackend: SandboxBackend,
     // Per-turn OS override. NULL = inherit the session's sandboxOs.
     sandboxOs: SandboxOs.nullable(),
@@ -5592,6 +6650,8 @@ export const SessionTurn = z
     initiatorContext: TurnInitiatorContext,
     /** Secret-safe projection of the exact personal authority frozen on this turn. */
     personalConnections: z.array(McpPersonalConnectionSummary).default([]),
+    /** Safe summary only; opaque resource/grant identity remains private. */
+    personalResources: PersonalResourceAttachmentSummary.nullable().default(null),
     cancelledBy: z.string().nullable(),
     cancelReason: z.string().nullable(),
     startedAt: z.string().nullable(),
@@ -5653,10 +6713,18 @@ export const EffectiveSessionControl = z.object({
       quiescencePendingCount: z.number().int().nonnegative(),
     })
     .nullable(),
+  /** Independent command-cancellation settlement. Session pause/turn state is
+   *  intentionally not overloaded with process lifecycle. */
+  backgroundCommandSettlement: z
+    .object({
+      state: z.literal("stopping"),
+      commandCount: z.number().int().positive(),
+    })
+    .nullable()
+    .optional(),
 });
 export type EffectiveSessionControl = z.infer<typeof EffectiveSessionControl>;
 
-export const SESSION_OPERATION_KEY_MAX_CHARS = 256;
 const SessionOperationKey = z.string().min(1).max(SESSION_OPERATION_KEY_MAX_CHARS);
 
 export const SessionCommandReceipt = z.object({
@@ -5673,6 +6741,14 @@ export const SessionCommandReceipt = z.object({
 });
 export type SessionCommandReceipt = z.infer<typeof SessionCommandReceipt>;
 
+/** The server-owned destination of an accepted human prompt at admission time. */
+export const SessionPromptRouting = z.enum([
+  "accepted_for_execution",
+  "queued_for_execution",
+  "accepted_for_steering",
+]);
+export type SessionPromptRouting = z.infer<typeof SessionPromptRouting>;
+
 export const ComposerDraft = z.object({
   revision: z.number().int().nonnegative(),
   text: z.string(),
@@ -5680,7 +6756,7 @@ export const ComposerDraft = z.object({
   resources: z.array(ResourceRef),
   model: z.string().min(1),
   reasoningEffort: ReasoningEffort,
-  latencyMode: LatencyMode.default("standard"),
+  latencyMode: LatencyMode,
   sourceTurnId: z.string().uuid().nullable(),
   sourceTurnVersion: z.number().int().positive().nullable(),
   updatedAt: z.string().nullable(),
@@ -5726,12 +6802,39 @@ export const SaveComposerDraftRequest = ComposerDraft.pick({
 }).extend({ expectedRevision: z.number().int().nonnegative() });
 export type SaveComposerDraftRequest = z.infer<typeof SaveComposerDraftRequest>;
 
+/**
+ * Submit one exact established-session draft. Content is repeated only as an
+ * integrity fence for outcome-unknown idempotent replay; the matching durable
+ * draft revision remains authoritative and is atomically rotated on acceptance.
+ */
+export const SubmitComposerDraftRequest = ComposerDraft.pick({
+  text: true,
+  annotations: true,
+  resources: true,
+  model: true,
+  reasoningEffort: true,
+  latencyMode: true,
+})
+  .extend({
+    expectedDraftRevision: z.number().int().positive(),
+    clientEventId: SessionOperationKey,
+    delivery: z.enum(["send", "steer"]),
+    controlEtag: z.string().min(1).optional(),
+    modelContext: z.string().trim().min(1).max(32768).optional(),
+    mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional(),
+    connectionAuthorities: McpConnectionAuthoritySelections.default([]),
+    personalResourceAttachment: PersonalResourceAttachmentIntent.optional(),
+  })
+  .superRefine(requireEstablishedPersonalResourceEpoch);
+export type SubmitComposerDraftRequest = z.infer<typeof SubmitComposerDraftRequest>;
+
 /**
  * Create-only options saved with an actor's private pre-session draft. This is
  * deliberately narrower than CreateSessionRequest: idempotency/event keys and
  * credential-bearing MCP server inputs are per-attempt data, never draft state.
  */
 export const NewSessionDraftOptions = z.object({
+  visibility: SessionVisibility.optional(),
   sandboxBackend: SandboxBackend.optional(),
   targetSandboxId: z.string().uuid().optional(),
   workingDir: z.string().min(1).optional(),
@@ -5743,6 +6846,31 @@ export const NewSessionDraftOptions = z.object({
 });
 export type NewSessionDraftOptions = z.infer<typeof NewSessionDraftOptions>;
 
+/**
+ * Actor-private successful-create history for the new-session composer. Project
+ * entries and their machine entries are MRU ordered. A null target means the
+ * managed sandbox; a null working directory means the machine's launch root.
+ */
+export const NewSessionSelectionHistory = z.object({
+  projects: z
+    .array(
+      z.object({
+        channelId: z.string().uuid().nullable(),
+        targetSandboxId: z.string().uuid().nullable(),
+        machines: z
+          .array(
+            z.object({
+              sandboxId: z.string().uuid(),
+              workingDir: z.string().min(1).max(4096).nullable(),
+            }),
+          )
+          .max(20),
+      }),
+    )
+    .max(50),
+});
+export type NewSessionSelectionHistory = z.infer<typeof NewSessionSelectionHistory>;
+
 /** Actor-private, server-authoritative composer state before a session exists. */
 export const NewSessionDraft = z.object({
   revision: z.number().int().nonnegative(),
@@ -5753,8 +6881,9 @@ export const NewSessionDraft = z.object({
   toolsProvided: z.boolean().default(false),
   model: z.string().min(1),
   reasoningEffort: ReasoningEffort,
-  latencyMode: LatencyMode.default("standard"),
+  latencyMode: LatencyMode,
   options: NewSessionDraftOptions,
+  selectionHistory: NewSessionSelectionHistory.default({ projects: [] }),
   updatedAt: z.string().nullable(),
 });
 export type NewSessionDraft = z.infer<typeof NewSessionDraft>;
@@ -5993,40 +7122,211 @@ export const SessionSystemUpdateKind = z.enum([
   "agent_steer_instruction",
   "child_terminal_result",
   "media_generation_result",
+  "child_requires_action",
+  "child_requires_action_resolved",
+  "child_paused",
+  "child_waiting_capacity",
+  "child_progress",
 ]);
 export type SessionSystemUpdateKind = z.infer<typeof SessionSystemUpdateKind>;
 
-export const SessionSystemUpdatePayload = z.discriminatedUnion("type", [
-  z
-    .object({
-      type: z.literal("scheduled_occurrence"),
-      text: z.string().min(1),
-      scheduledTaskId: z.string().uuid(),
-      scheduledTaskRunId: z.string().uuid(),
-      resources: z.array(ResourceRef).optional(),
-      tools: z.array(ToolRef).optional(),
-    })
-    .passthrough(),
-  z
-    .object({
-      type: z.literal("goal_continuation"),
-      goalId: z.string().uuid(),
-      goalVersion: z.number().int().positive(),
-      prompt: z.string().min(1),
-      reason: z.string().optional(),
-    })
-    .passthrough(),
-  z
-    .object({
-      type: z.literal("agent_message"),
-      text: z.string().min(1),
-      operationId: z.string().uuid(),
-    })
-    .passthrough(),
-  z
-    .object({
-      type: z.literal("agent_steer_instruction"),
-      instruction: z.string().min(1),
+/**
+ * How a newly pending machine input affects an idle receiving session.
+ * `immediate` registers a workflow wake in the same commit (the behaviour of
+ * every pre-existing kind) and ends a `goal_wait` hold at the next idle
+ * evaluation; `deferred` only inserts the durable pending row plus its
+ * `system.update.pending` event and is delivered coalesced with the next claim.
+ */
+export type SessionSystemUpdateWakeClass = "immediate" | "deferred";
+
+export const SESSION_SYSTEM_UPDATE_WAKE_CLASS: Record<
+  SessionSystemUpdateKind,
+  SessionSystemUpdateWakeClass
+> = {
+  scheduled_occurrence: "immediate",
+  goal_continuation: "immediate",
+  agent_message: "immediate",
+  agent_steer_instruction: "immediate",
+  child_terminal_result: "immediate",
+  media_generation_result: "immediate",
+  child_requires_action: "immediate",
+  child_requires_action_resolved: "deferred",
+  child_paused: "deferred",
+  child_waiting_capacity: "deferred",
+  child_progress: "deferred",
+};
+
+/**
+ * Kinds a child session's lifecycle produces for its parent. Every one of them
+ * travels through `session_system_update_outbox`, and none of them may
+ * autonomously wake a parent whose goal is not active.
+ */
+export const CHILD_LIFECYCLE_SYSTEM_UPDATE_KINDS = [
+  "child_terminal_result",
+  "child_requires_action",
+  "child_requires_action_resolved",
+  "child_paused",
+  "child_waiting_capacity",
+  "child_progress",
+] as const satisfies readonly SessionSystemUpdateKind[];
+export type ChildLifecycleSystemUpdateKind = (typeof CHILD_LIFECYCLE_SYSTEM_UPDATE_KINDS)[number];
+
+const CHILD_LIFECYCLE_SYSTEM_UPDATE_KIND_SET: ReadonlySet<string> = new Set(
+  CHILD_LIFECYCLE_SYSTEM_UPDATE_KINDS,
+);
+
+export function isChildLifecycleSystemUpdateKind(
+  kind: string,
+): kind is ChildLifecycleSystemUpdateKind {
+  return CHILD_LIFECYCLE_SYSTEM_UPDATE_KIND_SET.has(kind);
+}
+
+/** A child_paused notice requested by a human/API is action-required; an agent pause is informational. */
+export function childPausedClassification(
+  actorKind: "human" | "api" | "agent",
+): "action_required" | "info" {
+  return actorKind === "agent" ? "info" : "action_required";
+}
+
+/** Whole child_requires_action payload bound (UTF-8 JSON bytes). */
+export const CHILD_REQUIRES_ACTION_PAYLOAD_MAX_BYTES = 8 * 1024;
+/** Bounded first-question preview inside a child_requires_action notice. */
+export const CHILD_REQUIRES_ACTION_QUESTION_PREVIEW_MAX_BYTES = 512;
+export const CHILD_REQUIRES_ACTION_MAX_REQUESTS = 20;
+export const CHILD_PAUSED_REASON_MAX_BYTES = 2 * 1024;
+export const CHILD_PROGRESS_NOTE_MAX_BYTES = 4 * 1024;
+
+const boundedUtf8String = (maxBytes: number) =>
+  z.string().refine((value) => new TextEncoder().encode(value).byteLength <= maxBytes, {
+    message: `must be at most ${maxBytes} UTF-8 bytes`,
+  });
+
+export const ChildRequiresActionRequest = z.discriminatedUnion("kind", [
+  z.object({
+    kind: z.literal("human_input"),
+    requestId: z.string().uuid(),
+    questionCount: z.number().int().nonnegative(),
+    firstQuestion: boundedUtf8String(CHILD_REQUIRES_ACTION_QUESTION_PREVIEW_MAX_BYTES),
+    allowSkip: z.boolean(),
+    expiresAt: z.string().nullable(),
+  }),
+  z.object({
+    kind: z.literal("approval"),
+    approvalId: boundedUtf8String(256),
+    toolName: boundedUtf8String(128).nullable(),
+  }),
+]);
+export type ChildRequiresActionRequest = z.infer<typeof ChildRequiresActionRequest>;
+
+export const ChildRequiresActionPayload = z
+  .object({
+    type: z.literal("child_requires_action"),
+    childSessionId: z.string().uuid(),
+    childTurnId: z.string().uuid(),
+    childTurnGeneration: z.number().int().positive(),
+    requests: z.array(ChildRequiresActionRequest).max(CHILD_REQUIRES_ACTION_MAX_REQUESTS),
+    truncated: z.boolean(),
+  })
+  .passthrough();
+export type ChildRequiresActionPayload = z.infer<typeof ChildRequiresActionPayload>;
+
+export const ChildRequiresActionResolvedOutcome = z.enum([
+  "answered",
+  "skipped",
+  "expired",
+  "cancelled",
+  "approved",
+  "rejected",
+]);
+export type ChildRequiresActionResolvedOutcome = z.infer<typeof ChildRequiresActionResolvedOutcome>;
+
+export const ChildRequiresActionRespondedByKind = z.enum([
+  "human",
+  "api",
+  "agent_attempt",
+  "system",
+]);
+export type ChildRequiresActionRespondedByKind = z.infer<typeof ChildRequiresActionRespondedByKind>;
+
+export const ChildRequiresActionResolvedPayload = z
+  .object({
+    type: z.literal("child_requires_action_resolved"),
+    childSessionId: z.string().uuid(),
+    childTurnId: z.string().uuid(),
+    childTurnGeneration: z.number().int().positive(),
+    requestId: z.string().uuid().nullable(),
+    approvalId: boundedUtf8String(256).nullable(),
+    outcome: ChildRequiresActionResolvedOutcome,
+    respondedByKind: ChildRequiresActionRespondedByKind,
+  })
+  .passthrough();
+export type ChildRequiresActionResolvedPayload = z.infer<typeof ChildRequiresActionResolvedPayload>;
+
+export const ChildPausedPayload = z
+  .object({
+    type: z.literal("child_paused"),
+    childSessionId: z.string().uuid(),
+    operationId: z.string().uuid(),
+    actorKind: z.enum(["human", "api", "agent"]),
+    reason: boundedUtf8String(CHILD_PAUSED_REASON_MAX_BYTES).nullable(),
+  })
+  .passthrough();
+export type ChildPausedPayload = z.infer<typeof ChildPausedPayload>;
+
+export const ChildWaitingCapacityPayload = z
+  .object({
+    type: z.literal("child_waiting_capacity"),
+    childSessionId: z.string().uuid(),
+    childTurnId: z.string().uuid(),
+    provider: z.enum(["codex", "xai"]),
+    nextCheckAt: z.string().nullable(),
+  })
+  .passthrough();
+export type ChildWaitingCapacityPayload = z.infer<typeof ChildWaitingCapacityPayload>;
+
+export const ChildProgressPayload = z
+  .object({
+    type: z.literal("child_progress"),
+    childSessionId: z.string().uuid(),
+    goalId: z.string().uuid(),
+    objectiveRevision: z.number().int().nonnegative(),
+    operationId: z.string().uuid(),
+    progressNote: boundedUtf8String(CHILD_PROGRESS_NOTE_MAX_BYTES),
+  })
+  .passthrough();
+export type ChildProgressPayload = z.infer<typeof ChildProgressPayload>;
+
+export const SessionSystemUpdatePayload = z.discriminatedUnion("type", [
+  z
+    .object({
+      type: z.literal("scheduled_occurrence"),
+      text: z.string().min(1),
+      scheduledTaskId: z.string().uuid(),
+      scheduledTaskRunId: z.string().uuid(),
+      resources: z.array(ResourceRef).optional(),
+      tools: z.array(ToolRef).optional(),
+    })
+    .passthrough(),
+  z
+    .object({
+      type: z.literal("goal_continuation"),
+      goalId: z.string().uuid(),
+      goalVersion: z.number().int().positive(),
+      prompt: z.string().min(1),
+      reason: z.string().optional(),
+    })
+    .passthrough(),
+  z
+    .object({
+      type: z.literal("agent_message"),
+      text: z.string().min(1),
+      operationId: z.string().uuid(),
+    })
+    .passthrough(),
+  z
+    .object({
+      type: z.literal("agent_steer_instruction"),
+      instruction: z.string().min(1),
       operationId: z.string().uuid(),
     })
     .passthrough(),
@@ -6038,6 +7338,11 @@ export const SessionSystemUpdatePayload = z.discriminatedUnion("type", [
     })
     .passthrough(),
   MediaGenerationResult,
+  ChildRequiresActionPayload,
+  ChildRequiresActionResolvedPayload,
+  ChildPausedPayload,
+  ChildWaitingCapacityPayload,
+  ChildProgressPayload,
 ]);
 export type SessionSystemUpdatePayload = z.infer<typeof SessionSystemUpdatePayload>;
 
@@ -6154,11 +7459,16 @@ export function renderSessionSystemUpdateBatch(
 
 export function sessionSystemUpdateBatchHistoryItem(
   updates: Parameters<typeof renderSessionSystemUpdateBatch>[0],
+  goalSnapshot?: SessionGoalSnapshot,
 ): { type: "message"; role: "system"; content: string } {
+  const goalContext = renderSessionGoalContext(goalSnapshot);
   return {
     type: "message",
     role: "system",
-    content: renderSessionSystemUpdateBatch(updates),
+    content: [
+      ...(goalContext ? [`${SESSION_GOAL_CONTEXT_LABEL}\n${goalContext}`] : []),
+      renderSessionSystemUpdateBatch(updates),
+    ].join("\n\n"),
   };
 }
 
@@ -6168,12 +7478,16 @@ export const VariableSetVariableName = z
   .max(128);
 export type VariableSetVariableName = z.infer<typeof VariableSetVariableName>;
 
-function withVariableSetIdAlias<T extends z.ZodRawShape>(shape: T) {
+function withVariableSetIdAlias<T extends z.ZodRawShape>(
+  shape: T,
+  options: { rejectKeys?: readonly string[] } = {},
+) {
   return z.preprocess((input) => {
     if (!input || typeof input !== "object" || Array.isArray(input)) {
       return input;
     }
     const record = input as Record<string, unknown>;
+    if (options.rejectKeys?.some((key) => Object.hasOwn(record, key))) return null;
     if (record.variableSetId !== undefined || record.environmentId === undefined) {
       return record;
     }
@@ -6204,10 +7518,16 @@ export const VariableSetSecret = z.object({
 });
 export type VariableSetSecret = z.infer<typeof VariableSetSecret>;
 
+export const VariableSetScope = z.enum(["organization", "workspace", "user"]);
+export type VariableSetScope = z.infer<typeof VariableSetScope>;
+
 export const VariableSet = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
   workspaceId: z.string().uuid(),
+  scope: VariableSetScope,
+  generation: z.number().int().positive(),
+  status: z.enum(["active", "revoked"]),
   name: z.string(),
   description: z.string().nullable(),
   variables: z.array(VariableSetVariableMetadata),
@@ -6221,6 +7541,8 @@ export const WorkspaceEnvironment = VariableSet;
 export type WorkspaceEnvironment = VariableSet;
 
 export const CreateVariableSetRequest = z.object({
+  // Omitted remains the legacy workspace-owned creation path.
+  scope: VariableSetScope.default("workspace"),
   name: z.string().min(1).max(120),
   description: z.string().max(2000).optional(),
   variables: z
@@ -6419,6 +7741,9 @@ export const Rig = z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
   workspaceId: z.string().uuid(),
+  scope: ResourceAuthorityScope,
+  generation: z.number().int().positive(),
+  status: z.enum(["active", "revoked"]),
   name: z.string(),
   description: z.string().nullable(),
   createdBy: z.string().nullable(),
@@ -6477,6 +7802,8 @@ export const RigChange = z.object({
 export type RigChange = z.infer<typeof RigChange>;
 
 export const CreateRigRequest = z.object({
+  // Omitted remains the compatibility workspace-owned creation path.
+  scope: ResourceAuthorityScope.default("workspace"),
   name: z.string().min(1).max(120),
   description: z.string().max(2000).optional(),
   // Initial (version 1) content, inline.
@@ -6503,6 +7830,8 @@ export const Channel = z.object({
   workspaceId: z.string().uuid(),
   name: z.string(),
   description: z.string().nullable(),
+  pinned: z.boolean(),
+  sortOrder: z.number().int().nonnegative(),
   createdBy: z.string().nullable(),
   createdAt: z.string(),
   updatedAt: z.string(),
@@ -6518,9 +7847,16 @@ export type CreateChannelRequest = z.infer<typeof CreateChannelRequest>;
 export const UpdateChannelRequest = z.object({
   name: z.string().trim().min(1).max(80).optional(),
   description: z.string().max(2000).nullable().optional(),
+  pinned: z.boolean().optional(),
 });
 export type UpdateChannelRequest = z.infer<typeof UpdateChannelRequest>;
 
+/** Complete workspace project order. It is replaced atomically after a drag. */
+export const ReorderChannelsRequest = z
+  .object({ channelIds: z.array(z.string().uuid()).min(1).max(200) })
+  .strict();
+export type ReorderChannelsRequest = z.infer<typeof ReorderChannelsRequest>;
+
 // Re-files one session (rail organization only). null moves it back to the
 // unfiled inbox.
 export const UpdateSessionChannelRequest = z.object({
@@ -6686,25 +8022,313 @@ export const ScheduledTaskScheduleSpec = /* @__PURE__ */ z.discriminatedUnion("t
 ]);
 export type ScheduledTaskScheduleSpec = z.infer<typeof ScheduledTaskScheduleSpec>;
 
-export const ScheduledTaskAgentConfig = /* @__PURE__ */ z.object({
-  prompt: z.string().min(1),
-  resources: z.array(ResourceRef).default([]),
-  tools: z.array(ToolRef).default([]),
-  metadata: z.record(z.string(), z.unknown()).default({}),
-  // Explicit workspace-shared OpenGeni Slack bot binding for scheduled runs.
-  // The worker copies this non-secret pointer into session metadata; the
-  // first-party Slack tools never fall back to a personal hosted-MCP grant.
-  slackBotConnectionId: z.string().uuid().optional(),
-  model: z.string().min(1).optional(),
-  reasoningEffort: ReasoningEffort.optional(),
-  sandboxBackend: SandboxBackend.optional(),
-  goal: GoalSpec.optional(),
-  // Durable task override. Scheduled dispatch is trusted to preserve this
-  // snapshot even if the workspace/deployment policy narrows later.
-  maxNestedAgentDepth: NestedAgentDepthValue.optional(),
-});
+export const IncidentTelemetryExecutionClass = z.literal("incident_telemetry");
+export type IncidentTelemetryExecutionClass = z.infer<typeof IncidentTelemetryExecutionClass>;
+
+const IncidentTelemetryIdentifier = z.string().trim().min(1).max(200);
+const IncidentTelemetryMetricName = z
+  .string()
+  .trim()
+  .min(1)
+  .max(200)
+  .regex(/^[A-Za-z_:][A-Za-z0-9_:]*$/);
+const IncidentTelemetryLabelName = z
+  .string()
+  .trim()
+  .min(1)
+  .max(200)
+  .regex(/^[A-Za-z_][A-Za-z0-9_]*$/);
+
+export const IncidentTelemetrySeriesMetadata = z
+  .object({
+    metric: IncidentTelemetryMetricName,
+    labels: z.array(IncidentTelemetryLabelName).min(1).max(64),
+  })
+  .strict();
+export type IncidentTelemetrySeriesMetadata = z.infer<typeof IncidentTelemetrySeriesMetadata>;
+
+export const IncidentTelemetryDataRoute = z.discriminatedUnion("kind", [
+  z
+    .object({
+      kind: z.literal("mcp"),
+      serverId: SessionMcpServerId,
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("first_party"),
+      tool: FirstPartyMcpToolName,
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("variable_set"),
+      variableSetName: z.string().trim().min(1).max(120),
+      variableNames: z.array(VariableSetVariableName).min(1).max(100),
+    })
+    .strict(),
+  z
+    .object({
+      kind: z.literal("rig_credential_hook"),
+      credentialHookId: IncidentTelemetryIdentifier,
+    })
+    .strict(),
+]);
+export type IncidentTelemetryDataRoute = z.infer<typeof IncidentTelemetryDataRoute>;
+
+export const IncidentTelemetryPreflight = z
+  .object({
+    // These are exact selected resource refs, not discovery hints. The core
+    // validator requires every entry to already be present in agentConfig.
+    requiredResources: z.array(ResourceRef).max(100).default([]),
+    requiredMcpServerIds: z.array(SessionMcpServerId).max(64).default([]),
+    requiredFirstPartyMcpTools: z.array(FirstPartyMcpToolName).max(100).default([]),
+    requiredFirstPartyMcpPermissions: z.array(Permission).max(100).default([]),
+    requiredRig: z
+      .object({
+        name: z.string().trim().min(1).max(120),
+        credentialHookIds: z.array(IncidentTelemetryIdentifier).max(50).default([]),
+      })
+      .strict()
+      .nullable()
+      .default(null),
+    // Names only. The dispatch preflight never reads or decrypts values.
+    requiredVariableSetNames: z.array(z.string().trim().min(1).max(120)).max(25).default([]),
+    requiredVariableNames: z.array(VariableSetVariableName).max(100).default([]),
+    dataSource: z
+      .object({
+        kind: z.literal("prometheus"),
+        // Exposition endpoints such as /metrics are deliberately excluded.
+        queryPath: z.enum(["/api/v1/query", "/api/v1/query_range"]),
+        workspaceLabel: IncidentTelemetryLabelName,
+        // Exact non-workspace labels whose values come from the validated
+        // structured alert occurrence and bound every telemetry query.
+        alertSelectorLabels: z.array(IncidentTelemetryLabelName).min(1).max(16),
+        route: IncidentTelemetryDataRoute,
+        requiredSeries: z.array(IncidentTelemetrySeriesMetadata).min(1).max(100),
+        availableSeries: z.array(IncidentTelemetrySeriesMetadata).min(1).max(500),
+      })
+      .strict(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    for (const [index, label] of value.dataSource.alertSelectorLabels.entries()) {
+      if (label === value.dataSource.workspaceLabel) {
+        context.addIssue({
+          code: "custom",
+          path: ["dataSource", "alertSelectorLabels", index],
+          message: "alert selector labels must be non-workspace labels",
+        });
+      }
+    }
+    for (const [index, series] of value.dataSource.requiredSeries.entries()) {
+      if (!series.labels.includes(value.dataSource.workspaceLabel)) {
+        context.addIssue({
+          code: "custom",
+          path: ["dataSource", "requiredSeries", index, "labels"],
+          message: "required incident series must include the workspace label",
+        });
+      }
+      for (const label of value.dataSource.alertSelectorLabels) {
+        if (!series.labels.includes(label)) {
+          context.addIssue({
+            code: "custom",
+            path: ["dataSource", "requiredSeries", index, "labels"],
+            message: "required incident series must include every alert selector label",
+          });
+        }
+      }
+    }
+  });
+export type IncidentTelemetryPreflight = z.infer<typeof IncidentTelemetryPreflight>;
+
+/**
+ * Canonical UTF-8 ingress limits for newly written scheduled execution truth.
+ * They bound create/update requests and freshly accepted occurrence snapshots;
+ * already-stored tasks are read back through the unbounded storage shape so a
+ * legacy row can never become unreadable or undispatchable by a later cap.
+ */
+export const SCHEDULED_TASK_NAME_MAX_BYTES = 512;
+export const SCHEDULED_TASK_PROMPT_MAX_BYTES = 64 * 1024;
+export const SCHEDULED_TASK_METADATA_MAX_BYTES = 32 * 1024;
+export const SCHEDULED_TASK_AGENT_CONFIG_MAX_BYTES = 128 * 1024;
+export const SCHEDULED_TASK_ACCEPTED_EXECUTION_MAX_BYTES = 512 * 1024;
+/**
+ * A scheduled occurrence is delivered as one durable internal update whose
+ * payload (`scheduled_occurrence` text + resources + tools + ids) must fit the
+ * canonical internal-update bound. Bounding it here at ingress means every
+ * stored task that passed validation can also be delivered.
+ */
+export const SCHEDULED_TASK_OCCURRENCE_PAYLOAD_MAX_BYTES = 64 * 1024;
+/**
+ * Ingress reserves headroom below that bound for what the worker adds to the
+ * delivered payload (the first-party `opengeni` MCP tool ref and real ids), so
+ * a request that passes validation can always be delivered.
+ */
+export const SCHEDULED_TASK_OCCURRENCE_PAYLOAD_INGRESS_HEADROOM_BYTES = 1024;
+export const SCHEDULED_TASK_PRODUCER_KEY_MAX_BYTES = 512;
+export const SCHEDULED_TASK_RESOURCE_MAX_COUNT = 100;
+export const SCHEDULED_TASK_TOOL_MAX_COUNT = 128;
+
+const scheduledTaskUtf8Encoder = new TextEncoder();
+
+function scheduledTaskUtf8Bytes(value: string): number {
+  return scheduledTaskUtf8Encoder.encode(value).byteLength;
+}
+
+function scheduledTaskJsonUtf8Bytes(value: unknown): number {
+  try {
+    const encoded = JSON.stringify(value);
+    return encoded === undefined ? Number.POSITIVE_INFINITY : scheduledTaskUtf8Bytes(encoded);
+  } catch {
+    return Number.POSITIVE_INFINITY;
+  }
+}
+
+/**
+ * UTF-8 size of the exact `scheduled_occurrence` internal-update payload the
+ * worker delivers for one occurrence of this agent config (ids use fixed-width
+ * placeholder UUIDs). Shared by ingress validation and worker admission.
+ */
+export function scheduledOccurrencePayloadUtf8Bytes(agentConfig: {
+  prompt: string;
+  resources?: readonly unknown[] | undefined;
+  tools?: readonly unknown[] | undefined;
+}): number {
+  const placeholder = "00000000-0000-4000-8000-000000000000";
+  return scheduledTaskJsonUtf8Bytes({
+    type: "scheduled_occurrence",
+    text: agentConfig.prompt,
+    scheduledTaskId: placeholder,
+    scheduledTaskRunId: placeholder,
+    ...(agentConfig.resources?.length ? { resources: agentConfig.resources } : {}),
+    ...(agentConfig.tools?.length ? { tools: agentConfig.tools } : {}),
+  });
+}
+
+function scheduledTaskBoundedJsonObject(maxBytes: number, label: string) {
+  return z.record(z.string(), z.unknown()).superRefine((value, context) => {
+    if (scheduledTaskJsonUtf8Bytes(value) > maxBytes) {
+      context.addIssue({
+        code: "custom",
+        message: `${label} exceeds ${maxBytes} UTF-8 bytes`,
+      });
+    }
+  });
+}
+
+function scheduledTaskBoundedString(maxBytes: number, label: string) {
+  return z
+    .string()
+    .min(1)
+    .superRefine((value, context) => {
+      if (scheduledTaskUtf8Bytes(value) > maxBytes) {
+        context.addIssue({
+          code: "custom",
+          message: `${label} exceeds ${maxBytes} UTF-8 bytes`,
+        });
+      }
+    });
+}
+
+/** Ingress-bounded task name for create/update requests. */
+export const ScheduledTaskNameInput = /* @__PURE__ */ scheduledTaskBoundedString(
+  SCHEDULED_TASK_NAME_MAX_BYTES,
+  "scheduled task name",
+);
+/** Ingress-bounded task metadata for create/update requests. */
+export const ScheduledTaskMetadataInput = /* @__PURE__ */ scheduledTaskBoundedJsonObject(
+  SCHEDULED_TASK_METADATA_MAX_BYTES,
+  "scheduled task metadata",
+);
+
+function scheduledTaskAgentConfigShape(bounded: boolean) {
+  return {
+    prompt: bounded
+      ? scheduledTaskBoundedString(SCHEDULED_TASK_PROMPT_MAX_BYTES, "scheduled task prompt")
+      : z.string().min(1),
+    resources: bounded
+      ? z.array(ResourceRef).max(SCHEDULED_TASK_RESOURCE_MAX_COUNT).default([])
+      : z.array(ResourceRef).default([]),
+    tools: bounded
+      ? z
+          .array(ToolRef)
+          .max(SCHEDULED_TASK_TOOL_MAX_COUNT - 1)
+          .default([])
+      : z.array(ToolRef).default([]),
+    metadata: bounded
+      ? ScheduledTaskMetadataInput.default({})
+      : z.record(z.string(), z.unknown()).default({}),
+    // Explicit workspace-shared OpenGeni Slack bot binding for scheduled runs.
+    // The worker copies this non-secret pointer into session metadata; the
+    // first-party Slack tools never fall back to a personal hosted-MCP grant.
+    slackBotConnectionId: z.string().uuid().optional(),
+    model: bounded
+      ? scheduledTaskBoundedString(512, "scheduled task model").optional()
+      : z.string().min(1).optional(),
+    reasoningEffort: ReasoningEffort.optional(),
+    sandboxBackend: SandboxBackend.optional(),
+    goal: GoalSpec.optional(),
+    // Incident telemetry is the only special execution class. Omission keeps
+    // every existing task on the byte-compatible ordinary dispatch path.
+    executionClass: IncidentTelemetryExecutionClass.optional(),
+    incidentTelemetryPreflight: IncidentTelemetryPreflight.optional(),
+    // Durable task override. Scheduled dispatch is trusted to preserve this
+    // snapshot even if the workspace/deployment policy narrows later.
+    maxNestedAgentDepth: NestedAgentDepthValue.optional(),
+  };
+}
+
+function refineScheduledTaskAgentConfig(
+  value: { executionClass?: unknown; incidentTelemetryPreflight?: unknown },
+  context: z.RefinementCtx,
+): void {
+  if (value.executionClass === "incident_telemetry" && !value.incidentTelemetryPreflight) {
+    context.addIssue({
+      code: "custom",
+      path: ["incidentTelemetryPreflight"],
+      message: "incident telemetry tasks require incidentTelemetryPreflight",
+    });
+  }
+  if (value.executionClass !== "incident_telemetry" && value.incidentTelemetryPreflight) {
+    context.addIssue({
+      code: "custom",
+      path: ["executionClass"],
+      message: "incidentTelemetryPreflight requires executionClass=incident_telemetry",
+    });
+  }
+}
+
+/** Storage/projection shape. Deliberately unbounded so stored rows always parse. */
+export const ScheduledTaskAgentConfig = /* @__PURE__ */ z
+  .object(scheduledTaskAgentConfigShape(false))
+  .superRefine(refineScheduledTaskAgentConfig);
 export type ScheduledTaskAgentConfig = z.infer<typeof ScheduledTaskAgentConfig>;
 
+/** Ingress-bounded agent config for create/update requests. */
+export const ScheduledTaskAgentConfigInput = /* @__PURE__ */ z
+  .object(scheduledTaskAgentConfigShape(true))
+  .superRefine((value, context) => {
+    if (scheduledTaskJsonUtf8Bytes(value) > SCHEDULED_TASK_AGENT_CONFIG_MAX_BYTES) {
+      context.addIssue({
+        code: "custom",
+        message: `scheduled task agent config exceeds ${SCHEDULED_TASK_AGENT_CONFIG_MAX_BYTES} UTF-8 bytes`,
+      });
+    }
+    if (
+      scheduledOccurrencePayloadUtf8Bytes(value) >
+      SCHEDULED_TASK_OCCURRENCE_PAYLOAD_MAX_BYTES -
+        SCHEDULED_TASK_OCCURRENCE_PAYLOAD_INGRESS_HEADROOM_BYTES
+    ) {
+      context.addIssue({
+        code: "custom",
+        message: `scheduled task prompt, resources, and tools exceed the ${SCHEDULED_TASK_OCCURRENCE_PAYLOAD_MAX_BYTES - SCHEDULED_TASK_OCCURRENCE_PAYLOAD_INGRESS_HEADROOM_BYTES} UTF-8 byte occurrence payload`,
+      });
+    }
+    refineScheduledTaskAgentConfig(value, context);
+  });
+export type ScheduledTaskAgentConfigInput = z.infer<typeof ScheduledTaskAgentConfigInput>;
+
 export const ScheduledTask = /* @__PURE__ */ z.object({
   id: z.string().uuid(),
   accountId: z.string().uuid(),
@@ -6723,6 +8347,8 @@ export const ScheduledTask = /* @__PURE__ */ z.object({
   }),
   createdByContext: TurnInitiatorContext.default({}),
   personalConnections: z.array(McpPersonalConnectionSummary).default([]),
+  authorityRevision: z.number().int().positive().default(1),
+  executionDigest: z.string().regex(/^[0-9a-f]{64}$/u),
   reusableSessionId: z.string().uuid().nullable(),
   targetSessionId: z.string().uuid().nullable().default(null),
   variableSetId: z.string().uuid().nullable().default(null),
@@ -6738,31 +8364,177 @@ export const ScheduledTask = /* @__PURE__ */ z.object({
 });
 export type ScheduledTask = z.infer<typeof ScheduledTask>;
 
-export const KnowledgeSourceSyncFailure = /* @__PURE__ */ z.object({
-  externalObjectId: KnowledgeSourceSyncSubject,
-  code: z.enum([
-    "authority_changed",
-    "connection_reconnect_required",
-    "provider_unavailable",
-    "provider_rejected",
-    "provider_payload_invalid",
-    "content_unsupported",
-    "content_too_large",
-    "resource_limit",
-    "item_processing_failed",
-    "indexing_failed",
-    "internal_failure",
-  ]),
-  retryable: z.boolean(),
-  message: z.string().min(1).max(1000),
-});
-export type KnowledgeSourceSyncFailure = z.infer<typeof KnowledgeSourceSyncFailure>;
-
-export const KnowledgeSourceSyncRunSummary = /* @__PURE__ */ z.object({
-  phase: z
-    .enum(["queued", "inventory", "transfer", "index", "checkpoint", "completed", "failed"])
-    .default("queued"),
-  scanned: KnowledgeSourceSyncZeroInteger,
+/**
+ * Complete credential-free execution truth accepted for one scheduled agent
+ * occurrence. Retries consume this immutable snapshot instead of a mutable
+ * scheduled-task head.
+ */
+export const ScheduledTaskRunAcceptedExecution = /* @__PURE__ */ z
+  .object({
+    version: z.literal(1),
+    task: ScheduledTask,
+    resolvedModel: z.string().min(1),
+    resolvedReasoningEffort: ReasoningEffort,
+    resolvedLatencyMode: LatencyMode,
+    resolvedSandboxBackend: SandboxBackend,
+    resolvedSandboxOs: SandboxOs,
+    resolvedTools: z.array(ToolRef).max(SCHEDULED_TASK_TOOL_MAX_COUNT),
+    resolvedFirstPartyMcpTools: z.array(FirstPartyMcpToolName),
+    resolvedFirstPartyMcpPermissions: z.array(Permission),
+    resolvedVariableSet: z
+      .object({
+        id: z.string().uuid(),
+        generation: z.number().int().positive(),
+      })
+      .strict()
+      .nullable(),
+    resolvedRig: z
+      .object({
+        id: z.string().uuid(),
+        versionId: z.string().uuid(),
+        defaultVariableSets: z
+          .array(
+            z
+              .object({
+                id: z.string().uuid(),
+                generation: z.number().int().positive(),
+              })
+              .strict(),
+          )
+          .max(25),
+      })
+      .strict()
+      .nullable(),
+    resolvedSlackBotConnection: z
+      .object({
+        id: z.string().uuid(),
+        version: z.number().int().positive(),
+        verifiedInstallVersion: z.number().int().positive(),
+        metadata: z
+          .object({
+            credentialRole: z.literal("opengeni_slack_bot"),
+            credentialLabel: z.literal("OpenGeni Slack bot"),
+            slackTeamId: z.string().min(1).max(64),
+            slackTeamName: z.string().min(1).max(256),
+            botUserId: z.string().min(1).max(64),
+            botId: z.string().min(1).max(64),
+            botDisplayName: z.enum(["OpenGeni", "OpenGeni Staging"]),
+            verifiedAt: z.string().datetime({ offset: true }),
+          })
+          .passthrough(),
+      })
+      .strict()
+      .nullable(),
+    /**
+     * The effective policy that an existing or already-materialized reusable
+     * session will execute. Generated sessions carry null because their
+     * accepted task policy is used to create the session itself.
+     */
+    targetSessionExecution: z
+      .object({
+        sessionId: z.string().uuid(),
+        visibility: z.enum(["user_private", "workspace_shared"]),
+        authorityEpoch: z.number().int().positive(),
+        model: z.string().min(1),
+        reasoningEffort: ReasoningEffort,
+        latencyMode: LatencyMode,
+        tools: z.array(ToolRef).max(SCHEDULED_TASK_TOOL_MAX_COUNT),
+        sandboxBackend: SandboxBackend,
+        sandboxOs: SandboxOs,
+        firstPartyMcpTools: z.array(FirstPartyMcpToolName),
+        firstPartyMcpPermissions: z.array(Permission).nullable(),
+        toolPolicy: SessionToolPolicy,
+        mcpServerIds: z.array(z.string().min(1).max(256)).max(SCHEDULED_TASK_TOOL_MAX_COUNT),
+        effectiveMcpServerIds: z
+          .array(z.string().min(1).max(256))
+          .max(SCHEDULED_TASK_TOOL_MAX_COUNT),
+        toolPolicyVersion: z.number().int().nonnegative(),
+        variableSetId: z.string().uuid().nullable(),
+        variableSetGeneration: z.number().int().positive().nullable(),
+        rigId: z.string().uuid().nullable(),
+        rigVersionId: z.string().uuid().nullable(),
+        rigDefaultVariableSets: z
+          .array(
+            z
+              .object({
+                id: z.string().uuid(),
+                generation: z.number().int().positive(),
+              })
+              .strict(),
+          )
+          .max(25),
+        maxNestedAgentDepthOverride: NestedAgentDepthValue.nullable(),
+        effectiveMaxNestedAgentDepth: NestedAgentDepthValue,
+      })
+      .strict()
+      .nullable(),
+    generatedSessionBinding: z
+      .object({
+        createIdempotencyKey: z.string().min(1).max(512),
+        effectiveMaxNestedAgentDepth: NestedAgentDepthValue,
+        nestedAgentDepthPolicySource: NestedAgentDepthPolicySource,
+        codexCompactionMode: CodexCompactionMode,
+      })
+      .strict()
+      .nullable(),
+    personalConnectionDelegations: McpPersonalConnectionDelegations,
+    personalResourceAuthoritySubjectId: z.string().min(1).nullable(),
+    /** One accepted human principal for every resource-bearing scheduled run. */
+    causalHumanSubjectId: z.string().min(1).nullable().default(null),
+    /** Exact revision-bound human membership proof; never inferred at execution. */
+    causalHumanAuthority: z
+      .object({
+        subjectId: z.string().min(1),
+        organizationMembershipId: z.string().uuid(),
+        membershipAuthorizationRevision: z.number().int().positive(),
+      })
+      .strict()
+      .nullable()
+      .default(null),
+    xaiProviderAccountAuthoritySnapshot: XaiProviderAccountAuthoritySnapshotV1,
+    xaiAuthoritySubjectId: z.string().min(1).nullable(),
+    connectionAuthoritySubjectId: z.string().min(1).nullable(),
+    triggerInitiator: TurnInitiator,
+    agentRunUsageIdempotencyKey: z.string().min(1).max(512).nullable(),
+    incidentPreflightRequired: z.boolean(),
+    alertOccurrenceLabels: z.record(z.string(), z.string()).nullable(),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if (scheduledTaskJsonUtf8Bytes(value) > SCHEDULED_TASK_ACCEPTED_EXECUTION_MAX_BYTES) {
+      context.addIssue({
+        code: "custom",
+        message: `scheduled accepted execution exceeds ${SCHEDULED_TASK_ACCEPTED_EXECUTION_MAX_BYTES} UTF-8 bytes`,
+      });
+    }
+  });
+export type ScheduledTaskRunAcceptedExecution = z.infer<typeof ScheduledTaskRunAcceptedExecution>;
+
+export const KnowledgeSourceSyncFailure = /* @__PURE__ */ z.object({
+  externalObjectId: KnowledgeSourceSyncSubject,
+  code: z.enum([
+    "authority_changed",
+    "connection_reconnect_required",
+    "provider_unavailable",
+    "provider_rejected",
+    "provider_payload_invalid",
+    "content_unsupported",
+    "content_too_large",
+    "resource_limit",
+    "item_processing_failed",
+    "indexing_failed",
+    "internal_failure",
+  ]),
+  retryable: z.boolean(),
+  message: z.string().min(1).max(1000),
+});
+export type KnowledgeSourceSyncFailure = z.infer<typeof KnowledgeSourceSyncFailure>;
+
+export const KnowledgeSourceSyncRunSummary = /* @__PURE__ */ z.object({
+  phase: z
+    .enum(["queued", "inventory", "transfer", "index", "checkpoint", "completed", "failed"])
+    .default("queued"),
+  scanned: KnowledgeSourceSyncZeroInteger,
   imported: KnowledgeSourceSyncZeroInteger,
   unchanged: KnowledgeSourceSyncZeroInteger,
   skipped: KnowledgeSourceSyncZeroInteger,
@@ -6788,6 +8560,12 @@ export const ScheduledTaskRun = /* @__PURE__ */ z.object({
   accountId: z.string().uuid(),
   workspaceId: z.string().uuid(),
   taskId: z.string().uuid(),
+  taskAuthorityRevision: z.number().int().positive().nullable().default(null),
+  taskExecutionDigest: z
+    .string()
+    .regex(/^[0-9a-f]{64}$/u)
+    .nullable()
+    .default(null),
   status: ScheduledTaskRunStatus,
   triggerType: ScheduledTaskTriggerType,
   scheduledAt: z.string().nullable(),
@@ -6805,7 +8583,7 @@ export const ScheduledTaskRun = /* @__PURE__ */ z.object({
 export type ScheduledTaskRun = z.infer<typeof ScheduledTaskRun>;
 
 const CreateAgentScheduledTaskRequest = /* @__PURE__ */ withVariableSetIdAlias({
-  name: z.string().min(1),
+  name: ScheduledTaskNameInput,
   schedule: ScheduledTaskScheduleSpec,
   action: z
     .object({ kind: z.literal("agent_turn") })
@@ -6814,13 +8592,14 @@ const CreateAgentScheduledTaskRequest = /* @__PURE__ */ withVariableSetIdAlias({
   runMode: ScheduledTaskRunMode.default("new_session_per_run"),
   overlapPolicy: ScheduledTaskOverlapPolicy.default("allow_concurrent"),
   targetSessionId: z.string().uuid().nullable().optional(),
-  agentConfig: ScheduledTaskAgentConfig,
+  connectionAuthorities: McpConnectionAuthoritySelections.default([]),
+  agentConfig: ScheduledTaskAgentConfigInput,
   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({}),
+  metadata: ScheduledTaskMetadataInput.default({}),
 }).superRefine((value, context) => {
   if (value.runMode === "existing_session" && !value.targetSessionId) {
     context.addIssue({
@@ -6868,6 +8647,7 @@ const CreateKnowledgeSourceSyncScheduledTaskRequest = /* @__PURE__ */ z
     variableSetId: null,
     environmentId: null,
     rigId: null,
+    connectionAuthorities: [],
   }));
 
 export const CreateScheduledTaskRequest = /* @__PURE__ */ z.union([
@@ -6876,59 +8656,393 @@ export const CreateScheduledTaskRequest = /* @__PURE__ */ z.union([
 ]);
 export type CreateScheduledTaskRequest = z.infer<typeof CreateScheduledTaskRequest>;
 
-export const UpdateScheduledTaskRequest =
-  /* @__PURE__ */ withVariableSetIdAlias({
-    name: z.string().min(1).optional(),
-    schedule: ScheduledTaskScheduleSpec.optional(),
-    runMode: ScheduledTaskRunMode.optional(),
-    overlapPolicy: ScheduledTaskOverlapPolicy.optional(),
-    action: ScheduledTaskAction.optional(),
-    targetSessionId: z.string().uuid().nullable().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(),
-  }).superRefine((value, context) => {
-    if (value.targetSessionId && value.runMode && value.runMode !== "existing_session") {
+export const UpdateScheduledTaskRequest = /* @__PURE__ */ withVariableSetIdAlias({
+  name: ScheduledTaskNameInput.optional(),
+  schedule: ScheduledTaskScheduleSpec.optional(),
+  runMode: ScheduledTaskRunMode.optional(),
+  overlapPolicy: ScheduledTaskOverlapPolicy.optional(),
+  action: ScheduledTaskAction.optional(),
+  targetSessionId: z.string().uuid().nullable().optional(),
+  connectionAuthorities: McpConnectionAuthoritySelections.optional(),
+  agentConfig: ScheduledTaskAgentConfigInput.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(),
+}).superRefine((value, context) => {
+  if (value.targetSessionId && value.runMode && value.runMode !== "existing_session") {
+    context.addIssue({
+      code: "custom",
+      path: ["targetSessionId"],
+      message: "targetSessionId requires runMode=existing_session",
+    });
+  }
+  if (value.runMode === "existing_session" && value.targetSessionId === null) {
+    context.addIssue({
+      code: "custom",
+      path: ["targetSessionId"],
+      message: "targetSessionId cannot be null when runMode=existing_session",
+    });
+  }
+  if (
+    value.agentConfig?.goal &&
+    (value.runMode === "existing_session" || Boolean(value.targetSessionId))
+  ) {
+    context.addIssue({
+      code: "custom",
+      path: ["agentConfig", "goal"],
+      message: "agentConfig.goal cannot be used with an existing-session target",
+    });
+  }
+});
+export type UpdateScheduledTaskRequest = z.infer<typeof UpdateScheduledTaskRequest>;
+
+/**
+ * Manual-trigger body. `triggerId` is a client-supplied idempotency token: a
+ * retried trigger that reuses the same token charges once and starts one run.
+ * Omitting it makes each call a distinct trigger (the server mints a token).
+ */
+export const TriggerScheduledTaskRequest = z.object({
+  triggerId: z.string().min(1).max(128).optional(),
+});
+export type TriggerScheduledTaskRequest = z.infer<typeof TriggerScheduledTaskRequest>;
+
+// ============ Event-triggered automations ============
+
+export const AUTOMATION_WEBHOOK_MAX_BYTES = 2 * 1024 * 1024;
+export const AUTOMATION_EVENT_PAYLOAD_MAX_BYTES = 256 * 1024;
+export const AUTOMATION_SESSION_TEMPLATE_MAX_BYTES = 512 * 1024;
+export const AUTOMATION_MAX_MATCHED_TRIGGERS = 32;
+
+const AutomationBoundedJson = z.record(z.string(), z.unknown()).superRefine((value, context) => {
+  let bytes = Number.POSITIVE_INFINITY;
+  try {
+    bytes = new TextEncoder().encode(JSON.stringify(value)).byteLength;
+  } catch {
+    // The shared JSON/protocol boundary reports the exact runtime path later;
+    // this public ingress still fails closed on an unserializable value.
+  }
+  if (bytes > AUTOMATION_EVENT_PAYLOAD_MAX_BYTES) {
+    context.addIssue({
+      code: "custom",
+      message: `automation JSON exceeds ${AUTOMATION_EVENT_PAYLOAD_MAX_BYTES} UTF-8 bytes`,
+    });
+  }
+});
+
+export const AutomationAdapterId = z
+  .string()
+  .min(1)
+  .max(128)
+  .regex(/^[a-z0-9](?:[a-z0-9._/-]*[a-z0-9])?$/);
+export type AutomationAdapterId = z.infer<typeof AutomationAdapterId>;
+
+export const AutomationSourceStatus = z.enum(["active", "disabled"]);
+export type AutomationSourceStatus = z.infer<typeof AutomationSourceStatus>;
+
+export const AutomationTriggerStatus = z.enum(["active", "paused", "disabled"]);
+export type AutomationTriggerStatus = z.infer<typeof AutomationTriggerStatus>;
+
+export const AutomationRunStatus = z.enum([
+  "queued",
+  "dispatching",
+  "dispatched",
+  "skipped",
+  "failed",
+]);
+export type AutomationRunStatus = z.infer<typeof AutomationRunStatus>;
+
+export const AutomationEventStatus = z.enum(["accepted", "ignored", "failed"]);
+export type AutomationEventStatus = z.infer<typeof AutomationEventStatus>;
+
+export const SignedJsonAutomationEnvelope = z
+  .object({
+    id: z.string().trim().min(1).max(1024).optional(),
+    type: z.string().trim().min(1).max(256),
+    occurrenceKey: z.string().trim().min(1).max(1024).optional(),
+    occurredAt: z.string().datetime({ offset: true }).nullable().optional(),
+    subject: z.string().trim().min(1).max(512).nullable().optional(),
+    resource: z.string().trim().min(1).max(1024).nullable().optional(),
+    data: z.record(z.string(), z.unknown()).default({}),
+  })
+  .strict();
+export type SignedJsonAutomationEnvelope = z.infer<typeof SignedJsonAutomationEnvelope>;
+
+const AutomationSessionSkill = z
+  .object({
+    name: z
+      .string()
+      .min(1)
+      .max(64)
+      .regex(/^[A-Za-z0-9][A-Za-z0-9._-]*$/),
+    description: z.string().min(1).max(2048).optional(),
+    files: z
+      .array(
+        z.object({
+          path: z
+            .string()
+            .min(1)
+            .max(512)
+            .refine(
+              (path) =>
+                !path.startsWith("/") &&
+                !path.includes("\\") &&
+                path
+                  .split("/")
+                  .every((segment) => segment.length > 0 && segment !== "." && segment !== ".."),
+              "automation skill file path must be a safe relative POSIX path",
+            ),
+          content: z.string().max(256 * 1024),
+        }),
+      )
+      .min(1)
+      .max(64),
+  })
+  .superRefine((skill, context) => {
+    if (!skill.files.some((file) => file.path === "SKILL.md")) {
       context.addIssue({
         code: "custom",
-        path: ["targetSessionId"],
-        message: "targetSessionId requires runMode=existing_session",
+        path: ["files"],
+        message: "automation skill must include a top-level SKILL.md file",
       });
     }
-    if (value.runMode === "existing_session" && value.targetSessionId === null) {
+  });
+
+export const AutomationSessionTemplate = z
+  .object({
+    prompt: z
+      .string()
+      .trim()
+      .min(1)
+      .max(64 * 1024),
+    instructions: z
+      .string()
+      .trim()
+      .min(1)
+      .max(64 * 1024)
+      .nullable()
+      .default(null),
+    resources: z.array(ResourceRef).max(100).default([]),
+    skills: z.array(AutomationSessionSkill).max(32).default([]),
+    tools: z.array(ToolRef).max(128).default([]),
+    firstPartyMcpTools: z.array(FirstPartyMcpToolName).max(128).default([]),
+    firstPartyMcpPermissions: z.array(Permission).max(128).default([]),
+    model: z.string().trim().min(1).max(512).nullable().default(null),
+    reasoningEffort: ReasoningEffort.nullable().default(null),
+    sandboxBackend: SandboxBackend.nullable().default(null),
+    policyRole: z.string().trim().min(1).max(128).nullable().default(null),
+    metadata: AutomationBoundedJson.default({}),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    let bytes = Number.POSITIVE_INFINITY;
+    try {
+      bytes = new TextEncoder().encode(JSON.stringify(value)).byteLength;
+    } catch {
+      // Fail through the size issue below.
+    }
+    if (bytes > AUTOMATION_SESSION_TEMPLATE_MAX_BYTES) {
       context.addIssue({
         code: "custom",
-        path: ["targetSessionId"],
-        message: "targetSessionId cannot be null when runMode=existing_session",
+        message: `automation session template exceeds ${AUTOMATION_SESSION_TEMPLATE_MAX_BYTES} UTF-8 bytes`,
       });
     }
-    if (
-      value.agentConfig?.goal &&
-      (value.runMode === "existing_session" || Boolean(value.targetSessionId))
-    ) {
+  });
+export type AutomationSessionTemplate = z.infer<typeof AutomationSessionTemplate>;
+
+export const AutomationNormalizedEvent = z
+  .object({
+    adapterId: AutomationAdapterId,
+    eventType: z.string().trim().min(1).max(256),
+    occurrenceKey: z.string().trim().min(1).max(1024),
+    occurredAt: z.string().datetime({ offset: true }).nullable().default(null),
+    subject: z.string().trim().min(1).max(512).nullable().default(null),
+    resource: z.string().trim().min(1).max(1024).nullable().default(null),
+    payload: AutomationBoundedJson,
+  })
+  .strict();
+export type AutomationNormalizedEvent = z.infer<typeof AutomationNormalizedEvent>;
+
+export const AutomationAcceptedExecution = z
+  .object({
+    version: z.literal(1),
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sourceId: z.string().uuid(),
+    sourceVersion: z.number().int().positive(),
+    triggerId: z.string().uuid(),
+    triggerRevision: z.number().int().positive(),
+    eventId: z.string().uuid(),
+    adapterId: AutomationAdapterId,
+    occurrenceKey: z.string().min(1).max(1024),
+    initialMessage: z
+      .string()
+      .min(1)
+      .max(256 * 1024),
+    sessionTemplate: AutomationSessionTemplate,
+    serviceSubjectId: z.string().min(1).max(512),
+    serviceLabel: z.string().min(1).max(200),
+    provenance: AutomationBoundedJson,
+  })
+  .strict();
+export type AutomationAcceptedExecution = z.infer<typeof AutomationAcceptedExecution>;
+
+export const CreateAutomationSourceRequest = z
+  .object({
+    name: z.string().trim().min(1).max(200),
+    adapterId: AutomationAdapterId.default("signed-json.v1"),
+    webhookSecret: z.string().min(16).max(65_536),
+    configuration: AutomationBoundedJson.default({}),
+  })
+  .strict();
+export type CreateAutomationSourceRequest = z.infer<typeof CreateAutomationSourceRequest>;
+
+export const UpdateAutomationSourceRequest = z
+  .object({
+    name: z.string().trim().min(1).max(200).optional(),
+    webhookSecret: z.string().min(16).max(65_536).optional(),
+    configuration: AutomationBoundedJson.optional(),
+    status: AutomationSourceStatus.optional(),
+  })
+  .strict()
+  .refine((value) => Object.keys(value).length > 0, "automation source update is empty");
+export type UpdateAutomationSourceRequest = z.infer<typeof UpdateAutomationSourceRequest>;
+
+export const AutomationSource = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  name: z.string(),
+  adapterId: AutomationAdapterId,
+  configuration: z.record(z.string(), z.unknown()),
+  status: AutomationSourceStatus,
+  version: z.number().int().positive(),
+  packInstallationId: z.string().uuid().nullable(),
+  packConnectorId: z.string().min(1).max(128).nullable(),
+  hasWebhookSecret: z.boolean(),
+  webhookPath: z.string().min(1),
+  createdBySubjectId: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type AutomationSource = z.infer<typeof AutomationSource>;
+
+export const CreateAutomationTriggerRequest = z
+  .object({
+    sourceId: z.string().uuid(),
+    name: z.string().trim().min(1).max(200),
+    eventTypes: z.array(z.string().trim().min(1).max(256)).min(1).max(64),
+    configuration: AutomationBoundedJson.default({}),
+    parameters: AutomationBoundedJson.default({}),
+    sessionTemplate: AutomationSessionTemplate,
+    status: AutomationTriggerStatus.default("active"),
+    packInstallationId: z.string().uuid().nullable().default(null),
+    packTemplateId: z.string().trim().min(1).max(128).nullable().default(null),
+  })
+  .strict()
+  .superRefine((value, context) => {
+    if ((value.packInstallationId === null) !== (value.packTemplateId === null)) {
       context.addIssue({
         code: "custom",
-        path: ["agentConfig", "goal"],
-        message: "agentConfig.goal cannot be used with an existing-session target",
+        path: ["packTemplateId"],
+        message: "packInstallationId and packTemplateId must be supplied together",
       });
     }
   });
-export type UpdateScheduledTaskRequest = z.infer<typeof UpdateScheduledTaskRequest>;
+export type CreateAutomationTriggerRequest = z.infer<typeof CreateAutomationTriggerRequest>;
 
-/**
- * Manual-trigger body. `triggerId` is a client-supplied idempotency token: a
- * retried trigger that reuses the same token charges once and starts one run.
- * Omitting it makes each call a distinct trigger (the server mints a token).
- */
-export const TriggerScheduledTaskRequest = z.object({
-  triggerId: z.string().min(1).max(128).optional(),
+export const UpdateAutomationTriggerRequest = z
+  .object({
+    expectedRevision: z.number().int().positive(),
+    name: z.string().trim().min(1).max(200).optional(),
+    eventTypes: z.array(z.string().trim().min(1).max(256)).min(1).max(64).optional(),
+    configuration: AutomationBoundedJson.optional(),
+    parameters: AutomationBoundedJson.optional(),
+    sessionTemplate: AutomationSessionTemplate.optional(),
+    status: AutomationTriggerStatus.optional(),
+  })
+  .strict()
+  .refine((value) => Object.keys(value).some((key) => key !== "expectedRevision"), {
+    message: "automation trigger update is empty",
+  });
+export type UpdateAutomationTriggerRequest = z.infer<typeof UpdateAutomationTriggerRequest>;
+
+export const AutomationTrigger = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  sourceId: z.string().uuid(),
+  name: z.string(),
+  adapterId: AutomationAdapterId,
+  eventTypes: z.array(z.string()),
+  configuration: z.record(z.string(), z.unknown()),
+  parameters: z.record(z.string(), z.unknown()),
+  sessionTemplate: AutomationSessionTemplate,
+  status: AutomationTriggerStatus,
+  revision: z.number().int().positive(),
+  packInstallationId: z.string().uuid().nullable(),
+  packTemplateId: z.string().nullable(),
+  createdBySubjectId: z.string(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
 });
-export type TriggerScheduledTaskRequest = z.infer<typeof TriggerScheduledTaskRequest>;
+export type AutomationTrigger = z.infer<typeof AutomationTrigger>;
+
+export const AutomationRun = z.object({
+  id: z.string().uuid(),
+  accountId: z.string().uuid(),
+  workspaceId: z.string().uuid(),
+  sourceId: z.string().uuid(),
+  triggerId: z.string().uuid(),
+  triggerRevision: z.number().int().positive(),
+  eventId: z.string().uuid(),
+  occurrenceKey: z.string(),
+  status: AutomationRunStatus,
+  sessionId: z.string().uuid().nullable(),
+  errorCode: z.string().nullable(),
+  createdAt: z.string(),
+  updatedAt: z.string(),
+});
+export type AutomationRun = z.infer<typeof AutomationRun>;
+
+export const AutomationWebhookResult = z.object({
+  accepted: z.boolean(),
+  duplicate: z.boolean(),
+  ignoredReason: z.string().nullable(),
+  eventId: z.string().uuid().nullable(),
+  runIds: z.array(z.string().uuid()),
+});
+export type AutomationWebhookResult = z.infer<typeof AutomationWebhookResult>;
+
+export const TriggerAutomationManuallyRequest = z
+  .object({
+    deliveryId: z.string().trim().min(1).max(512).optional(),
+    eventType: z.string().trim().min(1).max(256),
+    occurrenceKey: z.string().trim().min(1).max(1024),
+    payload: AutomationBoundedJson.default({}),
+    occurredAt: z.string().datetime({ offset: true }).nullable().default(null),
+    subject: z.string().trim().min(1).max(512).nullable().default(null),
+    resource: z.string().trim().min(1).max(1024).nullable().default(null),
+  })
+  .strict();
+export type TriggerAutomationManuallyRequest = z.infer<typeof TriggerAutomationManuallyRequest>;
+
+export const CapabilityPackAutomationTemplate = z
+  .object({
+    id: z.string().min(1).max(128),
+    name: z.string().min(1).max(200),
+    description: z.string().min(1).max(4096),
+    adapterId: AutomationAdapterId,
+    eventTypes: z.array(z.string().min(1).max(256)).min(1).max(64),
+    sessionTemplate: AutomationSessionTemplate,
+    configuration: AutomationBoundedJson.default({}),
+    connectionRequirement: z.string().min(1).max(128).nullable().default(null),
+  })
+  .strict();
+export type CapabilityPackAutomationTemplate = z.infer<typeof CapabilityPackAutomationTemplate>;
 
 export const CapabilityPackConnectorAuthModel = z.enum([
   "oauth2_authorization_code_pkce",
@@ -7235,6 +9349,7 @@ export const CapabilityPack = z.preprocess(
       connectors: z.array(CapabilityPackConnector).default([]),
       knowledge: z.array(CapabilityPackKnowledge).default([]),
       scheduledTaskTemplates: z.array(CapabilityPackScheduledTaskTemplate).default([]),
+      automationTemplates: z.array(CapabilityPackAutomationTemplate).max(64).optional(),
       variableSet: CapabilityPackVariableSet.optional(),
       metadata: z.record(z.string(), z.unknown()).default({}),
     })
@@ -7261,6 +9376,17 @@ export const CapabilityPack = z.preprocess(
         }
         componentKeys.add(key);
       });
+      const automationTemplateIds = new Set<string>();
+      pack.automationTemplates?.forEach((template, index) => {
+        if (automationTemplateIds.has(template.id)) {
+          ctx.addIssue({
+            code: "custom",
+            message: `duplicate Pack automation template id: ${template.id}`,
+            path: ["automationTemplates", index, "id"],
+          });
+        }
+        automationTemplateIds.add(template.id);
+      });
       if (!pack.sandboxProviderImages?.modal) {
         return;
       }
@@ -7326,6 +9452,204 @@ export const PackInstallation = z.object({
 });
 export type PackInstallation = z.infer<typeof PackInstallation>;
 
+// ============ OpenGeni Review Bot — provider-neutral pull-request review automation ============
+
+export const OPENGENI_PR_REVIEW_PACK_ID = "pr-review" as const;
+export const OPENGENI_PR_REVIEW_SESSION_ROLE = "pull_request_review" as const;
+
+export const PrReviewProvider = GitCredentialProvider;
+export type PrReviewProvider = z.infer<typeof PrReviewProvider>;
+
+export const PrReviewCredentialKind = /* @__PURE__ */ z.enum(["github_app", "provider_token"]);
+export type PrReviewCredentialKind = z.infer<typeof PrReviewCredentialKind>;
+
+export const PrReviewWebhookAuthKind = /* @__PURE__ */ z.enum([
+  "hmac_sha256",
+  "shared_token",
+  "basic",
+]);
+export type PrReviewWebhookAuthKind = z.infer<typeof PrReviewWebhookAuthKind>;
+
+const PrReviewSecretInput = /* @__PURE__ */ (() => z.string().min(16).max(65_536))();
+
+export const CreatePrReviewAppRegistrationRequest = /* @__PURE__ */ (() =>
+  z
+    .object({
+      name: z.string().trim().min(1).max(200),
+      provider: PrReviewProvider,
+      providerBaseUrl: z.string().url().max(2048).optional(),
+      appId: z.string().trim().min(1).max(512).optional(),
+      credentialKind: PrReviewCredentialKind,
+      privateKey: PrReviewSecretInput.optional(),
+      accessToken: PrReviewSecretInput.optional(),
+      accessTokenExpiresAt: z.string().datetime().nullable().optional(),
+      webhookSecret: PrReviewSecretInput,
+      webhookUsername: z.string().min(1).max(512).optional(),
+    })
+    .strict()
+    .superRefine((value, context) => {
+      if (value.provider === "github" && value.credentialKind !== "github_app") {
+        context.addIssue({
+          code: "custom",
+          path: ["credentialKind"],
+          message: "GitHub PR Review registrations require a dedicated GitHub App",
+        });
+      }
+      if (value.provider === "github" && (!value.appId || !value.privateKey)) {
+        context.addIssue({
+          code: "custom",
+          path: [!value.appId ? "appId" : "privateKey"],
+          message: "GitHub PR Review registrations require the dedicated App ID and private key",
+        });
+      }
+      if (value.provider !== "github" && value.credentialKind !== "provider_token") {
+        context.addIssue({
+          code: "custom",
+          path: ["credentialKind"],
+          message: "GitLab and Azure DevOps PR Review registrations require a provider token",
+        });
+      }
+      if (value.credentialKind === "provider_token" && !value.accessToken) {
+        context.addIssue({
+          code: "custom",
+          path: ["accessToken"],
+          message: "provider_token credentials require accessToken",
+        });
+      }
+      if (
+        value.credentialKind === "github_app" &&
+        (value.accessToken !== undefined || value.privateKey === undefined)
+      ) {
+        context.addIssue({
+          code: "custom",
+          path: [value.accessToken !== undefined ? "accessToken" : "privateKey"],
+          message: "GitHub App credentials require privateKey and cannot include accessToken",
+        });
+      }
+      if (value.credentialKind === "provider_token" && value.privateKey !== undefined) {
+        context.addIssue({
+          code: "custom",
+          path: ["privateKey"],
+          message: "provider_token credentials cannot include a GitHub privateKey",
+        });
+      }
+      if (value.provider === "github" && value.accessTokenExpiresAt !== undefined) {
+        context.addIssue({
+          code: "custom",
+          path: ["accessTokenExpiresAt"],
+          message: "GitHub App registrations do not use accessTokenExpiresAt",
+        });
+      }
+      if (value.provider === "azure_devops" && !value.webhookUsername) {
+        context.addIssue({
+          code: "custom",
+          path: ["webhookUsername"],
+          message: "Azure DevOps service hooks require a Basic authentication username",
+        });
+      }
+    }))();
+export type CreatePrReviewAppRegistrationRequest = z.infer<
+  typeof CreatePrReviewAppRegistrationRequest
+>;
+
+export const UpdatePrReviewAppRegistrationRequest = /* @__PURE__ */ (() =>
+  z
+    .object({
+      name: z.string().trim().min(1).max(200).optional(),
+      accessToken: PrReviewSecretInput.optional(),
+      privateKey: PrReviewSecretInput.optional(),
+      accessTokenExpiresAt: z.string().datetime().nullable().optional(),
+      webhookSecret: PrReviewSecretInput.optional(),
+      webhookUsername: z.string().min(1).max(512).optional(),
+      status: z.enum(["active", "disabled"]).optional(),
+    })
+    .strict()
+    .refine((value) => Object.keys(value).length > 0, {
+      message: "PR Review registration update must change at least one field",
+    }))();
+export type UpdatePrReviewAppRegistrationRequest = z.infer<
+  typeof UpdatePrReviewAppRegistrationRequest
+>;
+
+export const PrReviewAppRegistration = /* @__PURE__ */ (() =>
+  z.object({
+    id: z.string().uuid(),
+    sourceId: z.string().uuid(),
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    name: z.string(),
+    provider: PrReviewProvider,
+    providerBaseUrl: z.string().url(),
+    appId: z.string().nullable(),
+    credentialKind: PrReviewCredentialKind,
+    hasCredential: z.boolean(),
+    accessTokenExpiresAt: z.string().nullable(),
+    webhookAuthKind: PrReviewWebhookAuthKind,
+    hasWebhookSecret: z.boolean(),
+    webhookUsername: z.string().nullable(),
+    webhookPath: z.string(),
+    status: z.enum(["active", "disabled"]),
+    createdBySubjectId: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+  }))();
+export type PrReviewAppRegistration = z.infer<typeof PrReviewAppRegistration>;
+
+export const CreatePrReviewRepositoryBindingRequest = /* @__PURE__ */ (() =>
+  z
+    .object({
+      registrationId: z.string().uuid(),
+      repositoryUri: z.string().url().max(2048),
+      repositoryFullName: z.string().trim().min(1).max(1024),
+      providerRepositoryId: z.union([z.string().min(1).max(512), z.number().int().positive()]),
+      installationId: z.union([z.string().min(1).max(512), z.number().int().positive()]).optional(),
+      projectId: z.union([z.string().min(1).max(512), z.number().int().positive()]).optional(),
+      model: z.string().min(1).max(512).nullable().optional(),
+      additionalInstructions: z.string().max(16_384).nullable().optional(),
+      status: z.enum(["active", "disabled"]).default("active"),
+    })
+    .strict())();
+export type CreatePrReviewRepositoryBindingRequest = z.infer<
+  typeof CreatePrReviewRepositoryBindingRequest
+>;
+
+export const UpdatePrReviewRepositoryBindingRequest = /* @__PURE__ */ (() =>
+  z
+    .object({
+      model: z.string().min(1).max(512).nullable().optional(),
+      additionalInstructions: z.string().max(16_384).nullable().optional(),
+      status: z.enum(["active", "disabled"]).optional(),
+    })
+    .strict()
+    .refine((value) => Object.keys(value).length > 0, {
+      message: "PR Review repository update must change at least one field",
+    }))();
+export type UpdatePrReviewRepositoryBindingRequest = z.infer<
+  typeof UpdatePrReviewRepositoryBindingRequest
+>;
+
+export const PrReviewRepositoryBinding = /* @__PURE__ */ (() =>
+  z.object({
+    id: z.string().uuid(),
+    triggerId: z.string().uuid(),
+    accountId: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    registrationId: z.string().uuid(),
+    provider: PrReviewProvider,
+    repositoryUri: z.string(),
+    repositoryFullName: z.string(),
+    providerRepositoryId: z.string(),
+    installationId: z.string().nullable(),
+    projectId: z.string().nullable(),
+    model: z.string().nullable(),
+    additionalInstructions: z.string().nullable(),
+    status: z.enum(["active", "disabled"]),
+    createdBySubjectId: z.string(),
+    createdAt: z.string(),
+    updatedAt: z.string(),
+  }))();
+export type PrReviewRepositoryBinding = z.infer<typeof PrReviewRepositoryBinding>;
+
 export const EnablePackRequest = withVariableSetIdAlias({
   variableSetId: z.string().uuid().optional(),
   environmentId: z.string().uuid().optional(),
@@ -7547,6 +9871,8 @@ export const OPENGENI_PERSONAL_SLACK_MCP_URL = "https://mcp.slack.com/mcp" as co
 export const OPENGENI_SLACK_BOT_CREDENTIAL_ROLE = "opengeni_slack_bot" as const;
 export const OPENGENI_SLACK_BOT_CREDENTIAL_LABEL = "OpenGeni Slack bot" as const;
 export const OPENGENI_SLACK_BOT_SESSION_METADATA_KEY = "opengeniSlackBotConnectionId" as const;
+export const OpenGeniSlackBotDisplayName = z.enum(["OpenGeni", "OpenGeni Staging"]);
+export type OpenGeniSlackBotDisplayName = z.infer<typeof OpenGeniSlackBotDisplayName>;
 export const OpenGeniSlackBotConnectionMetadata = z
   .object({
     credentialRole: z.literal(OPENGENI_SLACK_BOT_CREDENTIAL_ROLE),
@@ -7555,7 +9881,7 @@ export const OpenGeniSlackBotConnectionMetadata = z
     slackTeamName: z.string().min(1).max(256),
     botUserId: z.string().min(1).max(64),
     botId: z.string().min(1).max(64),
-    botDisplayName: z.literal("OpenGeni"),
+    botDisplayName: OpenGeniSlackBotDisplayName,
     verifiedAt: z.string().datetime({ offset: true }),
   })
   .passthrough();
@@ -7605,6 +9931,8 @@ export type FikenOAuthStartResponse = z.infer<typeof FikenOAuthStartResponse>;
 
 export const ConnectionMetadata = z.object({
   id: z.string().uuid(),
+  /** Opaque owner-only handle used to manage this personal connection's grants. */
+  authorityId: z.string().uuid().optional(),
   accountId: z.string().uuid(),
   workspaceId: z.string().uuid(),
   subjectId: z.string().nullable(),
@@ -7734,7 +10062,7 @@ export const SlackInstallationBinding = z.object({
   slackTeamName: z.string().min(1).max(256),
   botId: z.string().min(1).max(64),
   botUserId: z.string().min(1).max(64),
-  botDisplayName: z.literal("OpenGeni"),
+  botDisplayName: OpenGeniSlackBotDisplayName,
   state: SlackInstallationBindingState,
   quarantineReason: z.string().min(1).nullable(),
   version: z.number().int().positive(),
@@ -8240,6 +10568,43 @@ export const IntegrationFacetDefinitionSummary = z
   .strict();
 export type IntegrationFacetDefinitionSummary = z.infer<typeof IntegrationFacetDefinitionSummary>;
 
+/**
+ * Presentation-only consent copy for an integration or connector. Never grants
+ * a scope, selects a connection, or replaces server-side authorization; the UI
+ * falls back to generic copy for any omitted field.
+ */
+export const IntegrationPresentation = z
+  .object({
+    providerName: z.string().min(1).max(120).optional(),
+    icon: z.enum(["calendar", "cloud", "contacts", "files", "mail"]).optional(),
+    introduction: z.string().min(1).max(500).optional(),
+    capabilities: z
+      .array(
+        z
+          .object({
+            title: z.string().min(1).max(160),
+            description: z.string().min(1).max(500),
+          })
+          .strict(),
+      )
+      .max(8)
+      .optional(),
+    permissionSummary: z.string().min(1).max(500).optional(),
+    scopeLabels: z
+      .record(
+        z.string().min(1).max(1024),
+        z
+          .object({
+            label: z.string().min(1).max(160),
+            description: z.string().min(1).max(500),
+          })
+          .strict(),
+      )
+      .optional(),
+  })
+  .strict();
+export type IntegrationPresentation = z.infer<typeof IntegrationPresentation>;
+
 export const IntegrationDefinitionSummary = z
   .object({
     id: z.string().min(1).max(128),
@@ -8258,6 +10623,7 @@ export const IntegrationDefinitionSummary = z
         scopes: z.array(z.string().min(1).max(1024)).max(256),
       })
       .strict(),
+    presentation: IntegrationPresentation.optional(),
     facets: z.array(IntegrationFacetDefinitionSummary).max(128),
   })
   .strict();
@@ -8291,6 +10657,8 @@ export const IntegrationFacetBindingSummary = z
     lastErrorCode: z.string().min(1).max(120).nullable(),
     createdAt: z.string().datetime({ offset: true }),
     updatedAt: z.string().datetime({ offset: true }),
+    directlyOwned: z.boolean(),
+    owners: z.array(CapabilityComponentOwner),
   })
   .strict();
 export type IntegrationFacetBindingSummary = z.infer<typeof IntegrationFacetBindingSummary>;
@@ -8813,11 +11181,59 @@ export const UninstallPluginResult = z
   .strict();
 export type UninstallPluginResult = z.infer<typeof UninstallPluginResult>;
 
+export const SessionBackgroundCommandState = z.enum(["running", "stopping", "exited", "lost"]);
+export type SessionBackgroundCommandState = z.infer<typeof SessionBackgroundCommandState>;
+
+export const SessionBackgroundCommandProvider = z.enum(["managed", "connected_machine"]);
+export type SessionBackgroundCommandProvider = z.infer<typeof SessionBackgroundCommandProvider>;
+
+export const SessionBackgroundCommandActivity = z
+  .object({
+    state: z.enum(["running", "stopping"]),
+    count: z.number().int().positive(),
+  })
+  .strict();
+export type SessionBackgroundCommandActivity = z.infer<typeof SessionBackgroundCommandActivity>;
+
+export const SessionBackgroundCommand = z
+  .object({
+    id: z.string().uuid(),
+    workspaceId: z.string().uuid(),
+    sessionId: z.string().uuid(),
+    provider: SessionBackgroundCommandProvider,
+    state: SessionBackgroundCommandState,
+    commandPreview: z.string().max(512),
+    cancelRequestedAt: z.string().nullable(),
+    exitCode: z.number().int().nullable(),
+    settlementReason: z.string().nullable(),
+    startedAt: z.string(),
+    settledAt: z.string().nullable(),
+    updatedAt: z.string(),
+  })
+  .strict();
+export type SessionBackgroundCommand = z.infer<typeof SessionBackgroundCommand>;
+
+export const SessionBackgroundCommandListResponse = z
+  .object({ commands: z.array(SessionBackgroundCommand).max(1000) })
+  .strict();
+export type SessionBackgroundCommandListResponse = z.infer<
+  typeof SessionBackgroundCommandListResponse
+>;
+
+export const CancelSessionBackgroundCommandResult = z
+  .object({ command: SessionBackgroundCommand, accepted: z.boolean() })
+  .strict();
+export type CancelSessionBackgroundCommandResult = z.infer<
+  typeof CancelSessionBackgroundCommandResult
+>;
+
 export const Session = z.object({
   id: z.string().uuid(),
   workspaceId: z.string().uuid(),
   accountId: z.string().uuid(),
   status: SessionStatus,
+  /** Additive list projection. Detail reads may omit it. */
+  backgroundCommandActivity: SessionBackgroundCommandActivity.optional(),
   initialMessage: z.string(),
   title: z.string().nullable(),
   titleSource: z.enum(["user", "agent"]).nullable(),
@@ -8846,6 +11262,8 @@ export const Session = z.object({
   createdBy: TurnInitiator,
   createdByContext: TurnInitiatorContext,
   model: z.string(),
+  reasoningEffort: ReasoningEffort,
+  latencyMode: LatencyMode,
   sandboxBackend: SandboxBackend,
   // The OS the session's box runs. Defaults to 'linux' (today's only OS).
   sandboxOs: SandboxOs,
@@ -8929,6 +11347,17 @@ export const Session = z.object({
   pinnedAt: z.string().nullable().default(null),
   /** Optimistic pin-state revision; zero represents an absent pin relation. */
   pinVersion: z.number().int().nonnegative().default(0),
+  /** Personal explicit acknowledgment state; opening the session never clears it. */
+  unread: z.boolean().default(false),
+  /** Personal power-user label for work the member intends to continue. */
+  activelyWorking: z.boolean().default(false),
+  /** Optimistic revision for unread/actively-working state. */
+  attentionVersion: z.number().int().nonnegative().default(0),
+  /** Personal archive state. Archived roots and their descendants leave the ordinary list. */
+  archived: z.boolean().default(false),
+  archivedAt: z.string().nullable().default(null),
+  /** Optimistic archive-state revision; zero represents an absent personal relation. */
+  archiveVersion: 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
@@ -8943,10 +11372,24 @@ export const Session = z.object({
       attentionDescendants: z.number().int().nonnegative(),
       pausedDescendants: z.number().int().nonnegative(),
       failedDescendants: z.number().int().nonnegative(),
+      unreadDescendants: z.number().int().nonnegative().optional(),
+      activelyWorkingDescendants: z.number().int().nonnegative().optional(),
+      /**
+       * Earliest moment one of the counted `attentionDescendants` entered
+       * `requires_action` (the oldest still-open `requires_action` turn among
+       * those descendants). Null when none is waiting; omitted by older servers.
+       */
+      attentionSince: z.string().nullable().optional(),
       /** Counts are lower bounds rather than exact totals when true. */
       truncated: z.boolean().default(false),
     })
     .optional(),
+  /**
+   * When this session's own open turn entered `requires_action`. Populated by
+   * list and lineage reads for sessions whose status is `requires_action`;
+   * null otherwise and omitted by older servers or detail reads.
+   */
+  requiresActionSince: z.string().nullable().optional(),
   createdAt: z.string(),
   updatedAt: z.string(),
 });
@@ -9055,6 +11498,7 @@ export type SessionLineageResponse = z.infer<typeof SessionLineageResponse>;
 
 export const SessionEventType = z.enum([
   "session.created",
+  "session.personal_resources.attached",
   "session.visibility.changed",
   // Defensive read/transport projection for a malformed or historically
   // oversized retained event envelope. The original row stays durable; this
@@ -9083,13 +11527,20 @@ export const SessionEventType = z.enum([
   "turn.superseded",
   "turn.recovery.requested",
   "turn.capacity_waiting",
+  // Compact, attempt-fenced user-visible worker preparation checkpoints. The
+  // payload phase is a closed enum and terminal events carry durationMs; no
+  // session-specific value is ever promoted into Prometheus labels.
+  "turn.startup.phase.started",
+  "turn.startup.phase.completed",
+  "turn.startup.phase.failed",
   "agent.message.delta",
   "agent.message.completed",
   "agent.reasoning.delta",
   "agent.toolCall.created",
   "agent.toolCall.output",
-  // Attempt-fenced Codex Responses lifecycle metadata (request identity,
-  // deadlines, first-byte/terminal phase, provider request id). Never body/auth.
+  // Attempt-fenced provider Responses lifecycle metadata (request identity,
+  // liveness policy, first-event/terminal phase, provider request id). Never
+  // request body, credentials, or model output.
   "agent.model.request",
   "agent.model.usage",
   "tool.auth_needed",
@@ -9102,6 +11553,8 @@ export const SessionEventType = z.enum([
   "sandbox.operation.started",
   "sandbox.operation.completed",
   "sandbox.operation.failed",
+  "session.command.backgrounded",
+  "session.command.finished",
   "sandbox.command.output.delta",
   "artifact.created",
   "goal.set",
@@ -9113,6 +11566,7 @@ export const SessionEventType = z.enum([
   "goal.paused",
   "goal.resumed",
   "goal.cleared",
+  "goal.held",
   "goal.continuation",
   "system.update.pending",
   "system.update.delivered",
@@ -9305,6 +11759,7 @@ export const SESSION_EVENT_RAW_DELTA_TYPES = [
 export const SESSION_EVENT_SEMANTIC_CLASS_TYPES = {
   control: [
     "session.status.changed",
+    "session.command.backgrounded",
     "session.requiresAction",
     "session.humanInput.requested",
     "user.pause",
@@ -9319,6 +11774,7 @@ export const SESSION_EVENT_SEMANTIC_CLASS_TYPES = {
     "goal.paused",
     "goal.resumed",
     "goal.cleared",
+    "goal.held",
     "goal.continuation",
     "system.update.pending",
     "system.update.delivered",
@@ -9351,6 +11807,7 @@ export const SESSION_EVENT_SEMANTIC_CLASS_TYPES = {
     "recording.available",
     "recording.failed",
     "terminal.pty.exited",
+    "session.command.finished",
   ],
   failure: [
     "session.event.envelope_omitted",
@@ -9677,7 +12134,9 @@ export type FsNodeType = z.infer<typeof FsNodeType>;
 // depth>0; the tree lazy-expands via repeated depth-1 lists at deeper paths.
 export interface FsTreeNode {
   name: string;
-  path: string; // workspace-relative POSIX, no leading slash
+  // Same namespace as the request: workspace-relative for relative requests,
+  // canonical target path for requests rooted at FileSystem.root.
+  path: string;
   type: z.infer<typeof FsNodeType>;
   sizeBytes: number | null; // null for dirs
   mtimeMs: number | null;
@@ -9699,7 +12158,9 @@ export const FsTreeNode: z.ZodType<FsTreeNode> = z.lazy(() =>
 ) as z.ZodType<FsTreeNode>;
 
 export const FsListRequest = z.object({
-  path: z.string().default(""), // "" = workspace root
+  // "" = workspace root; canonical absolute paths must stay within the
+  // selected target's advertised FileSystem.root.
+  path: z.string().default(""),
   depth: z.number().int().min(0).max(8).default(1),
   maxEntries: z.number().int().positive().max(20_000).default(2_000),
   includeHidden: z.boolean().default(true),
@@ -11221,134 +13682,154 @@ export const SessionControlResponse = z.object({
 });
 export type SessionControlResponse = z.infer<typeof SessionControlResponse>;
 
-export const CreateSessionRequest = withVariableSetIdAlias({
-  /**
-   * Optional UUID preallocated by an embedding host. This lets the host durably
-   * link its own projection before OpenGeni admits the initial turn. Replays
-   * must pair it with the same idempotency key; OpenGeni never derives host
-   * identity or authorization from the UUID.
-   */
-  requestedSessionId: z.string().uuid().optional(),
-  initialMessage: z.string().min(1).optional(),
-  // Creates the durable session shell without fabricating a user message or
-  // starting an underlying agent turn. Realtime can then become the first
-  // interaction and use the ordinary Send/Steer path when it delegates.
-  startMode: z.literal("realtime").optional(),
-  // System-level host context for the initial turn only. Unlike `instructions`,
-  // this does not persist into later turns and is never emitted as a user event.
-  turnInstructions: z.string().trim().min(1).max(32768).optional(),
-  // Per-session agent persona/system instructions (org-visible metadata, NOT a
-  // secret). Rides the SAME system-level instructions channel the per-workspace
-  // agentInstructions rides, composed AFTER the workspace persona so it refines
-  // it for this one session — how a host delivers per-agent-type prompts without
-  // 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
-  // variable set variable values). Absent ⇒ byte-identical to today.
-  instructions: z.string().trim().min(1).max(32768).optional(),
-  // Immutable prompt-policy role binding for matching one activated role
-  // policy. This never derives from or grants a human workspace membership
-  // role. Existing callers may continue to use normalized metadata.role as a
-  // compatibility fallback by omitting this field.
-  policyRole: WorkspaceInstructionPolicyRoleKeyInput.optional(),
-  // For an agent-created child, omission inherits the trusted immediate
-  // parent's repository/file context. An explicit array, including [], is
-  // authoritative. Top-level omission remains []. Presence is resolved from
-  // the raw request because this Zod default erases absent-vs-empty.
-  resources: z.array(ResourceRef).default([]),
-  // Inline skills are fixed onto the session. Child omission inherits the
-  // trusted parent's selection; an explicit array, including [], wins.
-  skills: SessionSkills.default([]),
-  // The same child omission rule applies to selected MCP tool refs. Top-level
-  // omission still applies workspace-default capability MCP tools; explicit []
-  // suppresses those defaults (the first-party OpenGeni server remains added).
-  tools: z.array(ToolRef).default([]),
-  metadata: z.record(z.string(), z.unknown()).default({}),
-  model: z.string().min(1).optional(),
-  reasoningEffort: ReasoningEffort.optional(),
-  latencyMode: LatencyMode.optional(),
-  sandboxBackend: SandboxBackend.optional(),
-  // The enrolled machine (a sandbox id) to run this session on; seeds the
-  // active-sandbox pointer at creation so the FIRST turn routes to the chosen
-  // machine (race-free: the pointer is committed before the worker turn
-  // workflow can read it). An invalid/unowned/offline target fails the create.
-  targetSandboxId: z.string().uuid().optional(),
-  // The working directory the targeted machine runs the session under — the
-  // path/cwd base for its agent exec, terminal, and file dock. Free-form pass-
-  // through: a launch-workspace_root-relative subdir or an absolute machine path
-  // (the agent's resolve_cwd handles both). Only valid WITH targetSandboxId
-  // (workingDir alone is a 422); omitted ⇒ the machine's default workspace_root.
-  workingDir: z.string().min(1).optional(),
-  // 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 ⇒ inherit the workspace default;
-  // null ⇒ explicitly create a rig-less session; UUID ⇒ bind that exact rig.
-  // An id that does not name a rig in the workspace is a 422.
-  rigId: z.string().uuid().nullable().optional(),
-  // The workspace channel to file this session under (rail organization only).
-  // Omitted/null ⇒ unfiled (inbox). An id that does not name a channel in the
-  // workspace is a 422.
-  channelId: z.string().uuid().nullable().optional(),
-  goal: GoalSpec.optional(),
-  clientEventId: SessionOperationKey.optional(),
-  // Workspace-scoped CREATE idempotency key: collapses concurrent/retried
-  // create calls carrying the same key to a single session (partial unique
-  // index on (workspace_id, create_idempotency_key)). Distinct from
-  // clientEventId, whose uniqueness is per-session and so cannot dedup the
-  // creation of a brand-new session. Absent means no create-dedup (each call
-  // is an independent create).
-  idempotencyKey: z.string().min(1).max(200).optional(),
-  // The exact actor-private pre-session draft revision represented by this
-  // create. The durable initializer consumes only this revision. A newer draft
-  // written by a sibling tab survives, while every failed pre-initialization
-  // create leaves the submitted draft intact.
-  expectedNewSessionDraftRevision: z.number().int().nonnegative().optional(),
-  // A child may lower its inherited limit freely; an increase requires
-  // workspace:admin and is checked again at the DB transaction boundary.
-  maxNestedAgentDepth: NestedAgentDepthValue.optional(),
-  // Permissions the session's first-party MCP token should carry. A top-level
-  // omission uses the deployment's worker default; a child omission inherits
-  // the creating session's effective grant. An explicit set is capped at
-  // creation: every requested permission must be held by the creating grant.
-  // A goal-bearing session whose explicit/effective set omits goals:manage is
-  // rejected; creation never silently expands a child beyond that set.
-  firstPartyMcpPermissions: z.array(Permission).optional(),
-  // Exact model-visible selection from the broad first-party OpenGeni MCP
-  // catalog. Omission selects the safe non-connector default; [] intentionally
-  // exposes none.
-  // This does not grant authority: every registered tool is permission-gated.
-  firstPartyMcpTools: z.array(FirstPartyMcpToolName).optional(),
-  // Third-party MCP servers attached only to this session. For an agent-created
-  // child, omission snapshots its trusted immediate parent's server definitions,
-  // policies, connection refs, and encrypted credentials. Explicit arrays,
-  // including [], are authoritative; non-empty explicit arrays require attach
-  // permission. Credential headers are write-only: create responses and events
-  // expose only SessionMcpServerMetadata.
-  mcpServers: z.array(SessionMcpServerInput).max(SESSION_MCP_SERVERS_MAX).default([]),
-  // Shared-sandbox placement (addendum 05 §D.1). Three-way union; OMITTED ⇒
-  // today's behavior (a context-dependent default resolved server-side: from
-  // inside a session → "shared" with the creator's box, top-level → "new").
-  //   - "shared":  join the CREATOR's box. Requires a parent session (inferred
-  //                from the worker-signed sessionId claim, never caller-supplied);
-  //                top-level "shared" is a 422.
-  //   - "new":     mint a fresh singleton box (group ≡ the new session's id).
-  //   - {groupId}: join a SPECIFIC sibling group in THIS workspace (manager
-  //                fan-out). Validated workspace-scoped (cross-workspace → 404).
-  // A shared spawn inherits the box's (backend, os) — it is literally the same
-  // box; the child cannot pick its own backend. Cross-workspace sharing is
-  // forbidden by construction (the parent/group reads are RLS-workspace-scoped).
-  // ENV-AWARE: the box's 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(),
-}).superRefine((value, context) => {
+export const SESSION_INSTRUCTIONS_MAX_CHARACTERS = 65_536;
+
+export const CreateSessionRequest = withVariableSetIdAlias(
+  {
+    /**
+     * Optional UUID preallocated by an embedding host. This lets the host durably
+     * link its own projection before OpenGeni admits the initial turn. Replays
+     * must pair it with the same idempotency key; OpenGeni never derives host
+     * identity or authorization from the UUID.
+     */
+    requestedSessionId: z.string().uuid().optional(),
+    /** Top-level omission is workspace-visible. Agent-child omission inherits
+     * the exact parent visibility; cross-visibility child creation is rejected.
+     * Top-level private creation is an activated managed-cookie owning-human
+     * capability, while a private child uses an exact live-parent-attempt
+     * database capability. Both commit atomically. */
+    visibility: SessionVisibility.default("workspace"),
+    initialMessage: z.string().min(1).optional(),
+    // Creates the durable session shell without fabricating a user message or
+    // starting an underlying agent turn. Realtime can then become the first
+    // interaction and use the ordinary Send/Steer path when it delegates.
+    startMode: z.literal("realtime").optional(),
+    // Model-visible application context attached to the initial user message.
+    // Standard timeline rendering omits it, while full event/audit reads retain
+    // it. This is ordinary user-role content, not secret or privileged input.
+    modelContext: z.string().trim().min(1).max(32768).optional(),
+    // Per-session agent persona/system instructions (org-visible metadata, NOT a
+    // secret). Rides the SAME system-level instructions channel the per-workspace
+    // agentInstructions rides, composed AFTER the workspace persona so it refines
+    // it for this one session — how a host delivers per-agent-type prompts without
+    // leaking them into the user-visible timeline (it is NEVER emitted as an
+    // event, unlike goal/initialMessage). Trimmed, non-empty, and bounded by the
+    // shared durable session-instruction contract. Absent ⇒ byte-identical to
+    // today.
+    instructions: z.string().trim().min(1).max(SESSION_INSTRUCTIONS_MAX_CHARACTERS).optional(),
+    // Immutable prompt-policy role binding for matching one activated role
+    // policy. This never derives from or grants a human workspace membership
+    // role. Existing callers may continue to use normalized metadata.role as a
+    // compatibility fallback by omitting this field.
+    policyRole: WorkspaceInstructionPolicyRoleKeyInput.optional(),
+    // For an agent-created child, omission inherits the trusted immediate
+    // parent's repository/file context. An explicit array, including [], is
+    // authoritative. Top-level omission remains []. Presence is resolved from
+    // the raw request because this Zod default erases absent-vs-empty.
+    resources: z.array(ResourceRef).default([]),
+    // Inline skills are fixed onto the session. Child omission inherits the
+    // trusted parent's selection; an explicit array, including [], wins.
+    skills: SessionSkills.default([]),
+    // The same child omission rule applies to selected MCP tool refs. Top-level
+    // omission still applies workspace-default capability MCP tools; explicit []
+    // suppresses those defaults (the first-party OpenGeni server remains added).
+    tools: z.array(ToolRef).default([]),
+    metadata: z.record(z.string(), z.unknown()).default({}),
+    model: z.string().min(1).optional(),
+    reasoningEffort: ReasoningEffort.optional(),
+    latencyMode: LatencyMode.optional(),
+    sandboxBackend: SandboxBackend.optional(),
+    // The enrolled machine (a sandbox id) to run this session on; seeds the
+    // active-sandbox pointer at creation so the FIRST turn routes to the chosen
+    // machine (race-free: the pointer is committed before the worker turn
+    // workflow can read it). An invalid/unowned/offline target fails the create.
+    targetSandboxId: z.string().uuid().optional(),
+    // The working directory the targeted machine runs the session under. It may
+    // be absolute or relative to the machine's persisted Hello root; the server
+    // stores the resolved absolute value. Tilde is rejected because the control
+    // plane has no authenticated home-directory fact. Only valid WITH
+    // targetSandboxId; omitted selects the reported root.
+    workingDir: z.string().min(1).optional(),
+    // 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 ⇒ inherit the workspace default;
+    // null ⇒ explicitly create a rig-less session; UUID ⇒ bind that exact rig.
+    // An id that does not name a rig in the workspace is a 422.
+    rigId: z.string().uuid().nullable().optional(),
+    // The workspace channel to file this session under (rail organization only).
+    // Omitted/null ⇒ unfiled (inbox). An id that does not name a channel in the
+    // workspace is a 422.
+    channelId: z.string().uuid().nullable().optional(),
+    goal: GoalSpec.optional(),
+    clientEventId: SessionOperationKey.optional(),
+    // Workspace-scoped CREATE idempotency key: collapses concurrent/retried
+    // create calls carrying the same key to a single session (partial unique
+    // index on (workspace_id, create_idempotency_key)). Distinct from
+    // clientEventId, whose uniqueness is per-session and so cannot dedup the
+    // creation of a brand-new session. Absent means no create-dedup (each call
+    // is an independent create).
+    idempotencyKey: z.string().min(1).max(200).optional(),
+    // The exact actor-private pre-session draft revision represented by this
+    // create. An ordinary create consumes only this revision. A realtime create
+    // preserves the editable draft and atomically updates only successful-create
+    // selection history. A newer sibling draft survives, while every failed
+    // pre-initialization create leaves the submitted draft intact.
+    expectedNewSessionDraftRevision: z.number().int().nonnegative().optional(),
+    // A child may lower its inherited limit freely; an increase requires
+    // workspace:admin and is checked again at the DB transaction boundary.
+    maxNestedAgentDepth: NestedAgentDepthValue.optional(),
+    // Permissions the session's first-party MCP token should carry. A top-level
+    // omission uses the deployment's worker default; a child omission inherits
+    // the creating session's effective grant. An explicit set is capped at
+    // creation: every requested permission must be held by the creating grant.
+    // A goal-bearing session whose explicit/effective set omits goals:manage is
+    // rejected; creation never silently expands a child beyond that set.
+    firstPartyMcpPermissions: z.array(Permission).optional(),
+    // Exact model-visible selection from the broad first-party OpenGeni MCP
+    // catalog. Omission selects the safe non-connector default; [] intentionally
+    // exposes none.
+    // This does not grant authority: every registered tool is permission-gated.
+    firstPartyMcpTools: z.array(FirstPartyMcpToolName).optional(),
+    // Third-party MCP servers attached only to this session. For an agent-created
+    // child, omission snapshots its trusted immediate parent's server definitions,
+    // policies, connection refs, and encrypted credentials. Explicit arrays,
+    // including [], are authoritative; non-empty explicit arrays require attach
+    // permission. Credential headers are write-only: create responses and events
+    // expose only SessionMcpServerMetadata.
+    mcpServers: z.array(SessionMcpServerInput).max(SESSION_MCP_SERVERS_MAX).default([]),
+    /** Explicit personal-connection grants for the initial accepted turn. */
+    connectionAuthorities: McpConnectionAuthoritySelections.default([]),
+    /** Atomic owner issuance for the selected personal Variable Set/Rig closure. */
+    personalResourceAttachment: PersonalResourceAttachmentIntent.optional(),
+    // Shared-sandbox placement (addendum 05 §D.1). Three-way union; OMITTED ⇒
+    // today's behavior (a context-dependent default resolved server-side: from
+    // inside a session → "shared" with the creator's box, top-level → "new"),
+    // except a named targetSandboxId is always an own-box create ("new") because
+    // a machine target is a different compute home. Explicit "shared"/{groupId}
+    // plus a machine target is a 422.
+    //   - "shared":  join the CREATOR's box. Requires a parent session (inferred
+    //                from the worker-signed sessionId claim, never caller-supplied);
+    //                top-level "shared" is a 422.
+    //   - "new":     mint a fresh singleton box (group ≡ the new session's id).
+    //   - {groupId}: join a SPECIFIC sibling group in THIS workspace (manager
+    //                fan-out). Validated workspace-scoped (cross-workspace → 404).
+    // A shared spawn inherits the box's (backend, os) — it is literally the same
+    // box; the child cannot pick its own backend. Cross-workspace sharing is
+    // forbidden by construction (the parent/group reads are RLS-workspace-scoped).
+    // ENV-AWARE: the box's 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(),
+  },
+  { rejectKeys: ["turnInstructions"] },
+).superRefine((value, context) => {
   if (value.startMode !== "realtime" && value.initialMessage === undefined) {
     context.addIssue({
       code: z.ZodIssueCode.custom,
@@ -11363,9 +13844,46 @@ export const CreateSessionRequest = withVariableSetIdAlias({
       message: "initialMessage must be omitted when startMode is realtime",
     });
   }
+  if (value.startMode === "realtime" && value.modelContext !== undefined) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["modelContext"],
+      message: "modelContext requires an initialMessage; attach it to a realtime entry instead",
+    });
+  }
+  if (value.startMode === "realtime" && value.connectionAuthorities.length > 0) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["connectionAuthorities"],
+      message:
+        "connectionAuthorities require an accepted initial turn and are not supported by realtime session staging",
+    });
+  }
+  if (value.startMode === "realtime" && value.personalResourceAttachment !== undefined) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["personalResourceAttachment"],
+      message:
+        "personalResourceAttachment requires an accepted initial turn and is not supported by realtime session staging",
+    });
+  }
+  if (value.personalResourceAttachment?.expectedAuthorityEpoch !== undefined) {
+    context.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["personalResourceAttachment", "expectedAuthorityEpoch"],
+      message: "new-session attachment authority epoch is derived by the server",
+    });
+  }
 });
 export type CreateSessionRequest = z.infer<typeof CreateSessionRequest>;
 
+export const SessionTenancyCreateCapabilities = z.object({
+  activated: z.boolean(),
+  canCreatePrivate: z.boolean(),
+  reason: z.enum(["available", "not_activated", "managed_session_required", "unavailable"]),
+});
+export type SessionTenancyCreateCapabilities = z.infer<typeof SessionTenancyCreateCapabilities>;
+
 // Generic, host-neutral structured human input. One model tool call creates one
 // request containing one or more questions; the durable response resumes that
 // exact call. This is deliberately distinct from tool approval: an answer,
@@ -11389,6 +13907,9 @@ export const HumanInputQuestion = z
     helpText: z.string().max(2048).nullable().optional(),
     options: z.array(HumanInputOption).max(20).default([]),
     required: z.boolean().default(true),
+    // Retained on the wire for older hosts. OpenGeni's stock runtime and
+    // surfaces always expose Other for choice questions, including requests
+    // that were persisted before that became the default behavior.
     allowOther: z.boolean().default(false),
     // Selection bounds only — agents invent useless text char mins/maxes.
     // Answer strings stay platform-capped on HumanInputAnswer (~8192).
@@ -11549,9 +14070,9 @@ export const SessionUserMessagePayload = z
   .object({
     text: z.string().default(""),
     annotations: SubmittedTimelineAnnotations.default([]),
-    // System-level host context for this exact turn only. Persisted on the
-    // turn for retry/recovery, never copied into the visible user message.
-    turnInstructions: z.string().trim().min(1).max(32768).optional(),
+    // Model-visible application context attached to this exact user message.
+    // It is retained in full event/history data but omitted by standard UI.
+    modelContext: z.string().trim().min(1).max(32768).optional(),
     resources: z.array(ResourceRef).default([]),
     model: z.string().min(1).optional(),
     reasoningEffort: ReasoningEffort.optional(),
@@ -11561,9 +14082,13 @@ export const SessionUserMessagePayload = z
     // Header-value rotation only. URL/name/tool settings are immutable after
     // session create; persisted events expose metadata, never header values.
     mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional(),
+    /** Explicit personal-connection grants for this exact logical turn. */
+    connectionAuthorities: McpConnectionAuthoritySelections.default([]),
+    personalResourceAttachment: PersonalResourceAttachmentIntent.optional(),
   })
   .strict()
-  .superRefine(requireMessageTextOrAnnotations);
+  .superRefine(requireMessageTextOrAnnotations)
+  .superRefine(requireEstablishedPersonalResourceEpoch);
 export type SessionUserMessagePayload = z.infer<typeof SessionUserMessagePayload>;
 
 export const ClientSessionEvent = z.discriminatedUnion("type", [
@@ -11596,8 +14121,8 @@ export const SteerSessionMessageRequest = z
   .object({
     text: z.string().default(""),
     annotations: SubmittedTimelineAnnotations.default([]),
-    // Same per-turn system-level context as a queued user.message.
-    turnInstructions: z.string().trim().min(1).max(32768).optional(),
+    // Same model-visible message context as a queued user.message.
+    modelContext: z.string().trim().min(1).max(32768).optional(),
     resources: z.array(ResourceRef).default([]),
     model: z.string().min(1).optional(),
     reasoningEffort: ReasoningEffort.optional(),
@@ -11606,17 +14131,36 @@ export const SteerSessionMessageRequest = z
     controlEtag: z.string().min(1).optional(),
     expectedDraftRevision: z.number().int().nonnegative().optional(),
     mcpCredentialUpdates: z.array(SessionMcpCredentialUpdateInput).optional(),
+    /** Explicit personal-connection grants for this exact steered turn. */
+    connectionAuthorities: McpConnectionAuthoritySelections.default([]),
+    personalResourceAttachment: PersonalResourceAttachmentIntent.optional(),
   })
   .strict()
-  .superRefine(requireMessageTextOrAnnotations);
+  .superRefine(requireMessageTextOrAnnotations)
+  .superRefine(requireEstablishedPersonalResourceEpoch);
 export type SteerSessionMessageRequest = z.infer<typeof SteerSessionMessageRequest>;
 
 export const SteerSessionMessageResponse = z.object({
   accepted: SessionEvent,
   turn: SessionTurn,
+  receipt: SessionCommandReceipt,
+  routing: SessionPromptRouting,
+  interruptionCount: z.number().int().nonnegative(),
+  replay: z.boolean(),
 });
 export type SteerSessionMessageResponse = z.infer<typeof SteerSessionMessageResponse>;
 
+export const SubmitComposerDraftResponse = z.object({
+  accepted: SessionEvent,
+  turn: SessionTurn,
+  draft: ComposerDraft,
+  receipt: SessionCommandReceipt,
+  routing: SessionPromptRouting,
+  interruptionCount: z.number().int().nonnegative(),
+  replay: z.boolean(),
+});
+export type SubmitComposerDraftResponse = z.infer<typeof SubmitComposerDraftResponse>;
+
 export const SessionBusMessage = z.object({
   workspaceId: z.string().uuid(),
   sessionId: z.string().uuid(),
@@ -11707,6 +14251,7 @@ export const ClientAuthConfig = z.discriminatedUnion("mode", [
   z.object({
     mode: z.literal("managedSession"),
     session: z.literal("cookie"),
+    emailVerificationRequired: z.boolean().default(true),
   }),
 ]);
 export type ClientAuthConfig = z.infer<typeof ClientAuthConfig>;
@@ -11971,6 +14516,9 @@ export type DeviceEnrollmentStartResponse = z.infer<typeof DeviceEnrollmentStart
 export const DeviceEnrollmentApproveRequest = z.object({
   userCode: z.string().min(1).max(64),
   allowScreenControl: z.boolean().default(false),
+  // Human-approved machines are private by default. Workspace/organization
+  // publication is an explicit consent choice at this same loud boundary.
+  scope: ResourceAuthorityScope.default("user"),
 });
 export type DeviceEnrollmentApproveRequest = z.infer<typeof DeviceEnrollmentApproveRequest>;
 
@@ -12043,6 +14591,8 @@ export type DeviceEnrollmentPollResponse = z.infer<typeof DeviceEnrollmentPollRe
 // GET /enrollments — a workspace's machines (the Machines dashboard surface).
 export const EnrollmentSummary = z.object({
   id: z.string().uuid(),
+  scope: ResourceAuthorityScope,
+  generation: z.number().int().positive(),
   pubkey: z.string(),
   exposure: z.literal("whole-machine"),
   hasDisplay: z.boolean(),
@@ -12239,9 +14789,137 @@ export const MachineState = z.enum([
 ]);
 export type MachineState = z.infer<typeof MachineState>;
 
-export const MachineKind = z.enum(["modal", "selfhosted"]);
+export const MachineKind = z.enum(["modal", "selfhosted", "opensandbox"]);
 export type MachineKind = z.infer<typeof MachineKind>;
 
+/** Diagnostic projection of the single live Connected-Machine runner authority.
+ * It contains no bearer or NATS subject material. `supersededCount` is derived
+ * from the monotonic generation; duplicate-denial evidence records valid
+ * competing processes that were prevented from receiving work. */
+export const MachineConnectionAuthority = z.object({
+  state: z.enum(["not_applicable", "unclaimed", "active", "expired"]),
+  generation: z.number().int().nonnegative(),
+  supersededCount: z.number().int().nonnegative(),
+  leaseExpiresAt: z.string().nullable(),
+  duplicateRunnerDeniedCount: z.number().int().nonnegative(),
+  duplicateRunnerDeniedAt: z.string().nullable(),
+});
+export type MachineConnectionAuthority = z.infer<typeof MachineConnectionAuthority>;
+
+export const MachineRuntimeCapabilities = z.object({
+  exec: z.boolean(),
+  filesystem: z.boolean(),
+  git: z.boolean(),
+  pty: z.boolean(),
+  desktop: z.boolean(),
+  opStream: z.boolean(),
+  browserBridge: z.boolean(),
+  operationResourcePolicy: z.boolean(),
+  operationCpuQuota: z.boolean(),
+});
+export type MachineRuntimeCapabilities = z.infer<typeof MachineRuntimeCapabilities>;
+
+export const MachineUpdateStatus = z.enum([
+  "requested",
+  "accepted",
+  "waiting_for_idle",
+  "downloading",
+  "verifying",
+  "applying",
+  "restarting",
+  "succeeded",
+  "failed",
+]);
+export type MachineUpdateStatus = z.infer<typeof MachineUpdateStatus>;
+
+export const MachineUpdateState = z.object({
+  operationId: z.string().uuid(),
+  status: MachineUpdateStatus,
+  targetVersion: z.string(),
+  expectedBinarySha256: z
+    .string()
+    .regex(/^[0-9a-f]{64}$/)
+    .nullable(),
+  errorCode: z.string().nullable(),
+  retryable: z.boolean(),
+  rolledBack: z.boolean(),
+  requestedAt: z.string(),
+  updatedAt: z.string(),
+  completedAt: z.string().nullable(),
+});
+export type MachineUpdateState = z.infer<typeof MachineUpdateState>;
+
+export const MachineRuntime = z.object({
+  installedVersion: z.string().nullable(),
+  binarySha256: z
+    .string()
+    .regex(/^[0-9a-f]{64}$/)
+    .nullable(),
+  updateChannel: z.enum(["stable", "beta"]).nullable(),
+  desiredVersion: z.string().nullable(),
+  versionState: z.enum(["unknown", "current", "outdated", "ahead", "updating", "update_failed"]),
+  capabilities: MachineRuntimeCapabilities,
+  update: MachineUpdateState.nullable(),
+});
+export type MachineRuntime = z.infer<typeof MachineRuntime>;
+
+export const UpdateMachineAgentResponse = z.object({
+  operationId: z.string().uuid(),
+  accepted: z.boolean(),
+  targetVersion: z.string(),
+});
+export type UpdateMachineAgentResponse = z.infer<typeof UpdateMachineAgentResponse>;
+
+const OperationMemoryBytes = z.number().int().positive().max(Number.MAX_SAFE_INTEGER).nullable();
+const OperationCpuMillicores = z.number().int().positive().max(0xffff_ffff).nullable();
+
+function operationPolicyShape(
+  value: {
+    memoryMaxBytes: number | null;
+    memoryHighBytes: number | null;
+    cpuMaxMillicores?: number | null | undefined;
+  },
+  ctx: z.RefinementCtx,
+): void {
+  if (
+    value.memoryMaxBytes !== null &&
+    value.memoryHighBytes !== null &&
+    value.memoryHighBytes > value.memoryMaxBytes
+  ) {
+    ctx.addIssue({
+      code: z.ZodIssueCode.custom,
+      path: ["memoryHighBytes"],
+      message: "memoryHighBytes cannot exceed memoryMaxBytes",
+    });
+  }
+}
+
+/** Optional per-connection command resource policy. CPU is a period-independent
+ * millicore ratio; runners choose a documented representable cgroup period. Null
+ * values are unrestricted; revision is the optimistic concurrency fence. */
+export const MachineOperationPolicy = z
+  .object({
+    memoryMaxBytes: OperationMemoryBytes,
+    memoryHighBytes: OperationMemoryBytes,
+    cpuMaxMillicores: OperationCpuMillicores,
+    revision: z.number().int().nonnegative(),
+    updatedAt: z.string().nullable(),
+  })
+  .superRefine(operationPolicyShape);
+export type MachineOperationPolicy = z.infer<typeof MachineOperationPolicy>;
+
+export const UpdateMachineOperationPolicyRequest = z
+  .object({
+    memoryMaxBytes: OperationMemoryBytes,
+    memoryHighBytes: OperationMemoryBytes,
+    cpuMaxMillicores: OperationCpuMillicores.optional(),
+    expectedRevision: z.number().int().nonnegative(),
+  })
+  .superRefine(operationPolicyShape);
+export type UpdateMachineOperationPolicyRequest = z.infer<
+  typeof UpdateMachineOperationPolicyRequest
+>;
+
 /**
  * A machine as the Machines dashboard renders it. The workspace's enrolled
  * selfhosted machines PLUS the session's synthetic Modal group box
@@ -12253,6 +14931,8 @@ export type MachineKind = z.infer<typeof MachineKind>;
 export const MachineView = z.object({
   sandboxId: z.string(),
   enrollmentId: z.string().nullable(),
+  scope: ResourceAuthorityScope.default("workspace"),
+  generation: z.number().int().positive().default(1),
   name: z.string(),
   kind: MachineKind,
   state: MachineState,
@@ -12271,6 +14951,12 @@ export const MachineView = z.object({
   allowScreenControl: z.boolean(),
   sharedSessionCount: z.number().int(),
   lastSeenAt: z.string().nullable(),
+  connectionAuthority: MachineConnectionAuthority,
+  // Exact connected-agent build/capabilities and current update operation. Null
+  // for managed/session sandboxes and pre-runtime-reporting synthetic rows.
+  runtime: MachineRuntime.nullable().default(null),
+  // Per-enrollment desired policy. Null for managed/session sandboxes.
+  operationPolicy: MachineOperationPolicy.nullable().default(null),
   metrics: MetricSample.nullable(),
 });
 export type MachineView = z.infer<typeof MachineView>;
@@ -12347,8 +15033,9 @@ function defineModelContractSchema<Schema>(factory: () => Schema): Schema {
   return factory();
 }
 
-export const ModelCapabilitySupportV1 =
-  /* @__PURE__ */ defineModelContractSchema(() => z.enum(["supported", "unsupported", "unknown"]));
+export const ModelCapabilitySupportV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.enum(["supported", "unsupported", "unknown"]),
+);
 export type ModelCapabilitySupportV1 = z.infer<typeof ModelCapabilitySupportV1>;
 
 export const ModelCapabilityStateV1 = /* @__PURE__ */ defineModelContractSchema(() =>
@@ -12396,60 +15083,65 @@ export const ModelCapabilitiesV1 = /* @__PURE__ */ defineModelContractSchema(()
 );
 export type ModelCapabilitiesV1 = z.infer<typeof ModelCapabilitiesV1>;
 
-export const ModelCredentialSourceV1 =
-  /* @__PURE__ */ defineModelContractSchema(() =>
-    z.union([
-      z
-        .object({
-          kind: z.literal("deployment"),
-          mechanism: z.enum(["api_key", "azure_ad_bearer"]),
-        })
-        .strict(),
-      z
-        .object({
-          kind: z.literal("connected_subscription"),
-          provider: z.enum(["codex", "xai"]),
-        })
-        .strict(),
-      z
-        .object({
-          kind: z.literal("workspace_connection"),
-          mechanism: z.literal("api_key"),
-        })
-        .strict(),
-    ]),
-  );
-export type ModelCredentialSourceV1 = z.infer<typeof ModelCredentialSourceV1>;
-
-export const ModelBillingAttributionV1 =
-  /* @__PURE__ */ defineModelContractSchema(() =>
+export const ModelCredentialSourceV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.union([
     z
       .object({
-        upstreamPayer: z.enum(["deployment", "workspace", "connected_subscription"]),
-        metering: z.enum(["opengeni_credits", "external"]),
+        kind: z.literal("deployment"),
+        mechanism: z.enum(["api_key", "azure_ad_bearer"]),
       })
       .strict(),
-  );
+    z
+      .object({
+        kind: z.literal("connected_subscription"),
+        provider: z.enum(["codex", "xai"]),
+      })
+      .strict(),
+    z
+      .object({
+        kind: z.literal("workspace_connection"),
+        mechanism: z.literal("api_key"),
+      })
+      .strict(),
+  ]),
+);
+export type ModelCredentialSourceV1 = z.infer<typeof ModelCredentialSourceV1>;
+
+const TurnExecutionCredentialSourceV1 = z.union([
+  ModelCredentialSourceV1,
+  z
+    .object({
+      kind: z.literal("deployment"),
+      mechanism: z.literal("none"),
+    })
+    .strict(),
+]);
+
+export const ModelBillingAttributionV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z
+    .object({
+      upstreamPayer: z.enum(["deployment", "workspace", "connected_subscription"]),
+      metering: z.enum(["opengeni_credits", "external"]),
+    })
+    .strict(),
+);
 export type ModelBillingAttributionV1 = z.infer<typeof ModelBillingAttributionV1>;
 
 export const TURN_EXECUTION_POLICY_METADATA_KEY = "turnExecutionPolicyV1" as const;
 
-export const TurnExecutionModelSourceV1 =
-  /* @__PURE__ */ defineModelContractSchema(() =>
-    z.enum(["explicit", "session", "deployment", "continuation"]),
-  );
+export const TurnExecutionModelSourceV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.enum(["explicit", "session", "deployment", "continuation"]),
+);
 export type TurnExecutionModelSourceV1 = z.infer<typeof TurnExecutionModelSourceV1>;
 
-export const TurnExecutionReasoningSourceV1 =
-  /* @__PURE__ */ defineModelContractSchema(() =>
-    z.enum(["explicit", "session", "deployment", "continuation"]),
-  );
+export const TurnExecutionReasoningSourceV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.enum(["explicit", "session", "deployment", "continuation"]),
+);
 export type TurnExecutionReasoningSourceV1 = z.infer<typeof TurnExecutionReasoningSourceV1>;
 
-export const TurnExecutionLatencyModeSourceV1 =
-  /* @__PURE__ */ defineModelContractSchema(() =>
-    z.enum(["explicit", "session", "deployment", "continuation"]),
-  );
+export const TurnExecutionLatencyModeSourceV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.enum(["explicit", "session", "deployment", "continuation"]),
+);
 export type TurnExecutionLatencyModeSourceV1 = z.infer<typeof TurnExecutionLatencyModeSourceV1>;
 
 /**
@@ -12477,7 +15169,7 @@ export const TurnExecutionPolicyV1 = /* @__PURE__ */ defineModelContractSchema((
       providerId: z.string().min(1),
       upstreamModelId: z.string().min(1),
       wireApi: z.enum(["responses", "chat"]),
-      credentialSource: ModelCredentialSourceV1,
+      credentialSource: TurnExecutionCredentialSourceV1,
       billing: ModelBillingAttributionV1,
       definitionVersion: z.string().regex(/^sha256:[a-f0-9]{64}$/u),
     })
@@ -12651,60 +15343,59 @@ export const ClientModel = /* @__PURE__ */ defineModelContractSchema(() =>
 );
 export type ClientModel = z.infer<typeof ClientModel>;
 
-export const ModelCredentialReadinessV1 =
-  /* @__PURE__ */ defineModelContractSchema(() =>
-    z
-      .object({
-        status: z.enum(["ready", "not_ready", "error"]),
-        reason: z
-          .enum([
-            "missing_credential",
-            "needs_reauth",
-            "prerequisites_missing",
-            "resolver_error",
-            "observation_stale",
-          ])
-          .nullable(),
-        basis: z.enum(["configuration", "connection", "resolver"]),
-        checkedAt: z.string().datetime().nullable(),
-      })
-      .strict()
-      .superRefine((readiness, context) => {
-        if ((readiness.status === "ready") !== (readiness.reason === null)) {
-          context.addIssue({
-            code: "custom",
-            path: ["reason"],
-            message: "ready credential state requires no reason; non-ready state requires a reason",
-          });
-        }
-        if ((readiness.status === "error") !== (readiness.reason === "resolver_error")) {
-          context.addIssue({
-            code: "custom",
-            path: ["reason"],
-            message:
-              "credential errors require resolver_error and resolver_error requires error status",
-          });
-        }
-        if (
-          readiness.basis === "resolver" &&
-          readiness.status === "ready" &&
-          readiness.checkedAt === null
-        ) {
-          context.addIssue({
-            code: "custom",
-            path: ["checkedAt"],
-            message: "resolver readiness requires an observation timestamp",
-          });
-        }
-        if (readiness.reason === "observation_stale" && readiness.checkedAt === null) {
-          context.addIssue({
-            code: "custom",
-            path: ["checkedAt"],
-            message: "a stale observation requires its observation timestamp",
-          });
-        }
-      }),
-  );
+export const ModelCredentialReadinessV1 = /* @__PURE__ */ defineModelContractSchema(() =>
+  z
+    .object({
+      status: z.enum(["ready", "not_ready", "error"]),
+      reason: z
+        .enum([
+          "missing_credential",
+          "needs_reauth",
+          "prerequisites_missing",
+          "resolver_error",
+          "observation_stale",
+        ])
+        .nullable(),
+      basis: z.enum(["configuration", "connection", "resolver"]),
+      checkedAt: z.string().datetime().nullable(),
+    })
+    .strict()
+    .superRefine((readiness, context) => {
+      if ((readiness.status === "ready") !== (readiness.reason === null)) {
+        context.addIssue({
+          code: "custom",
+          path: ["reason"],
+          message: "ready credential state requires no reason; non-ready state requires a reason",
+        });
+      }
+      if ((readiness.status === "error") !== (readiness.reason === "resolver_error")) {
+        context.addIssue({
+          code: "custom",
+          path: ["reason"],
+          message:
+            "credential errors require resolver_error and resolver_error requires error status",
+        });
+      }
+      if (
+        readiness.basis === "resolver" &&
+        readiness.status === "ready" &&
+        readiness.checkedAt === null
+      ) {
+        context.addIssue({
+          code: "custom",
+          path: ["checkedAt"],
+          message: "resolver readiness requires an observation timestamp",
+        });
+      }
+      if (readiness.reason === "observation_stale" && readiness.checkedAt === null) {
+        context.addIssue({
+          code: "custom",
+          path: ["checkedAt"],
+          message: "a stale observation requires its observation timestamp",
+        });
+      }
+    }),
+);
 export type ModelCredentialReadinessV1 = z.infer<typeof ModelCredentialReadinessV1>;
 
 export const ModelAvailabilityV1 = /* @__PURE__ */ defineModelContractSchema(() =>
@@ -12727,21 +15418,21 @@ export const ModelAvailabilityV1 = /* @__PURE__ */ defineModelContractSchema(()
 );
 export type ModelAvailabilityV1 = z.infer<typeof ModelAvailabilityV1>;
 
-export const WorkspaceModelCatalogModel =
-  /* @__PURE__ */ defineModelContractSchema(() =>
-    ClientModel.extend({
-      credentialReadiness: ModelCredentialReadinessV1,
-      availability: ModelAvailabilityV1,
-    }),
-  );
+export const WorkspaceModelCatalogModel = /* @__PURE__ */ defineModelContractSchema(() =>
+  ClientModel.extend({
+    credentialReadiness: ModelCredentialReadinessV1,
+    /** Exact workspace-policy verdict without exposing provider identity. */
+    policyAllowed: z.boolean().optional(),
+    availability: ModelAvailabilityV1,
+  }),
+);
 export type WorkspaceModelCatalogModel = z.infer<typeof WorkspaceModelCatalogModel>;
 
-export const WorkspaceModelCatalogResponse =
-  /* @__PURE__ */ defineModelContractSchema(() =>
-    z.object({
-      models: z.array(WorkspaceModelCatalogModel),
-    }),
-  );
+export const WorkspaceModelCatalogResponse = /* @__PURE__ */ defineModelContractSchema(() =>
+  z.object({
+    models: z.array(WorkspaceModelCatalogModel),
+  }),
+);
 export type WorkspaceModelCatalogResponse = z.infer<typeof WorkspaceModelCatalogResponse>;
 
 /**
@@ -12752,7 +15443,7 @@ export type WorkspaceModelCatalogResponse = z.infer<typeof WorkspaceModelCatalog
  * that rollout boundary. Mutating clients send this value in
  * `x-opengeni-api-contract`; the API rejects any other value before routing.
  */
-export const OPENGENI_API_CONTRACT_REVISION = "2026-08-social-provider-tools-v1" as const;
+export const OPENGENI_API_CONTRACT_REVISION = "2026-08-atomic-session-fork-visibility-v1" as const;
 export const OPENGENI_API_CONTRACT_HEADER = "x-opengeni-api-contract" as const;
 /** Bounded request/response identifier shared by browser, ingress, and API diagnostics. */
 export const OPENGENI_CORRELATION_HEADER = "x-opengeni-correlation-id" as const;
@@ -12926,10 +15617,18 @@ export * from "./codex-fleet-policy";
 export * from "./xai-provider-account-authority";
 export * from "./workspace-instruction-policies";
 export * from "./company-profile";
+export * from "./company-brain";
 export * from "./workspace-learning-policy";
+export * from "./workspace-learning-administration";
 export * from "./workspace-state";
 export * from "./preference-registry";
 export * from "./scoped-knowledge";
+export * from "./company-brain-governed-writes";
+export * from "./governed-learning-evaluator";
+export * from "./governed-learning-activation";
 export * from "./knowledge";
 export * from "./task-notes";
 export * from "./canonical-human-identities";
+export * from "./organization-membership-lifecycle";
+export * from "./remember";
+export * from "./agent-authored-durable-text";