@opengeni/core 0.4.6 → 0.4.7

package/src/domain/sessions.ts

@@ -1,7 +1,8 @@
 import { CODEX_MODEL_ID_PREFIX } from "@opengeni/codex";
-import { configuredAllowedModels, type Settings } from "@opengeni/config";
+import { configuredAllowedModels, policyProviderIdForModel, type Settings } from "@opengeni/config";
 import {
   CreateSessionRequest,
+  evaluateWorkspaceModelPolicy,
   reasoningEffortForMetadata,
   type AccessGrant,
   type GoalSpec,
@@ -17,36 +18,47 @@ import {
   type ToolRef,
 } from "@opengeni/contracts";
 import {
-  appendSessionEventsWithLockedSessionUpdate,
   createSession,
-  createSessionGoal,
   createSessionWithIdempotencyKey,
-  enqueueSessionTurn,
-  encryptEnvironmentValue,
+  enqueueSessionMessageAtomically,
+  encryptVariableSetValue,
   getAnySessionInGroup,
   getEnrollment,
-  listDistinctEnvironmentIdsInGroup,
+  getRig,
+  getWorkspaceDefaultRigId,
+  listDistinctVariableSetIdsInGroup,
+  listDistinctRigVersionIdsInGroup,
   getSandbox,
   getSession,
   getSessionByCreateIdempotencyKey,
+  getSessionLineage,
   getSessionTurn,
+  getWorkspaceModelPolicy,
+  initializeSessionStartAtomically,
   requireSession,
-  setTemporalWorkflowId,
   updateSessionTitle as updateSessionTitleRow,
   type CreateSessionMcpServerInput,
   type Database,
   type UpdateSessionMcpServerCredentialsInput,
+  SessionQueueConflictError,
 } from "@opengeni/db";
-import { appendAndPublishEvents, type EventBus } from "@opengeni/events";
+import {
+  appendAndPublishEvents,
+  publishDurableSessionEvents,
+  type EventBus,
+} from "@opengeni/events";
 import { HTTPException } from "hono/http-exception";
 import { hasPermission, requirePermission } from "../access";
 import { recordWorkspaceUsage, requireLimit } from "../billing/limits";
-import type { ApiRouteDeps, SessionWorkflowClient } from "../dependencies";
+import type {
+  AcceptSessionUserMessageDependencies,
+  ApiRouteDeps,
+  SessionWorkflowClient,
+} from "../dependencies";
 import { swapActiveSandbox, type FleetContext } from "../sandbox/fleet";
 import { settingsWithEnabledCapabilityMcpServers } from "./capabilities";
-import { requireEnvironmentEncryption, validateEnvironmentAttachment } from "./environments";
+import { requireVariableSetEncryption, validateVariableSetAttachment } from "./environments";
 import {
-  mergeResourceRefs,
   mergeToolRefs,
   normalizeResources,
   validateFileResources,
@@ -67,13 +79,19 @@ type ValidatedSessionMcpServers = {
   metadata: SessionMcpServerMetadata[];
 };
 
-function normalizedSessionMcpCredentialHeaders(headers: Record<string, string> | undefined): Record<string, string> {
+function normalizedSessionMcpCredentialHeaders(
+  headers: Record<string, string> | undefined,
+): Record<string, string> {
   if (!headers) {
     return {};
   }
-  const entries = Object.entries(headers).map(([name, value]) => [name.trim(), value] as const).filter(([name]) => name.length > 0);
+  const entries = Object.entries(headers)
+    .map(([name, value]) => [name.trim(), value] as const)
+    .filter(([name]) => name.length > 0);
   if (entries.length > maxSessionMcpCredentialHeaders) {
-    throw new HTTPException(422, { message: `a session MCP server supports at most ${maxSessionMcpCredentialHeaders} credential headers` });
+    throw new HTTPException(422, {
+      message: `a session MCP server supports at most ${maxSessionMcpCredentialHeaders} credential headers`,
+    });
   }
   const seen = new Set<string>();
   for (const [name, value] of entries) {
@@ -86,12 +104,16 @@ function normalizedSessionMcpCredentialHeaders(headers: Record<string, string> |
     }
     seen.add(lower);
     if (value.length === 0 || value.length > maxSessionMcpCredentialHeaderValueLength) {
-      throw new HTTPException(422, { message: `credential header ${name} must be 1-${maxSessionMcpCredentialHeaderValueLength} characters` });
+      throw new HTTPException(422, {
+        message: `credential header ${name} must be 1-${maxSessionMcpCredentialHeaderValueLength} characters`,
+      });
     }
     // RFC 9110 §5.5: field values are HTAB / printable characters.
     // eslint-disable-next-line no-control-regex
     if (/[\u0000-\u0008\u000A-\u001F\u007F]/.test(value)) {
-      throw new HTTPException(422, { message: `credential header ${name} contains forbidden control characters` });
+      throw new HTTPException(422, {
+        message: `credential header ${name} contains forbidden control characters`,
+      });
     }
   }
   return Object.fromEntries(entries);
@@ -109,7 +131,9 @@ function mcpServerConfigFromInput(server: SessionMcpServerInput): Settings["mcpS
   };
 }
 
-function mcpServerConfigFromMetadata(server: SessionMcpServerMetadata): Settings["mcpServers"][number] {
+function mcpServerConfigFromMetadata(
+  server: SessionMcpServerMetadata,
+): Settings["mcpServers"][number] {
   return {
     id: server.id,
     ...(server.name ? { name: server.name } : {}),
@@ -118,21 +142,24 @@ function mcpServerConfigFromMetadata(server: SessionMcpServerMetadata): Settings
   };
 }
 
-function settingsWithSessionMcpServerConfigs(settings: Settings, servers: Settings["mcpServers"]): Settings {
+function settingsWithSessionMcpServerConfigs(
+  settings: Settings,
+  servers: Settings["mcpServers"],
+): Settings {
   if (servers.length === 0) {
     return settings;
   }
   const sessionIds = new Set(servers.map((server) => server.id));
   return {
     ...settings,
-    mcpServers: [
-      ...settings.mcpServers.filter((server) => !sessionIds.has(server.id)),
-      ...servers,
-    ],
+    mcpServers: [...settings.mcpServers.filter((server) => !sessionIds.has(server.id)), ...servers],
   };
 }
 
-export function settingsWithSessionMcpServerMetadata(settings: Settings, servers: SessionMcpServerMetadata[]): Settings {
+export function settingsWithSessionMcpServerMetadata(
+  settings: Settings,
+  servers: SessionMcpServerMetadata[],
+): Settings {
   return settingsWithSessionMcpServerConfigs(settings, servers.map(mcpServerConfigFromMetadata));
 }
 
@@ -145,7 +172,7 @@ function validateSessionMcpServersForCreate(
     return { runtimeServers: [], dbServers: [], metadata: [] };
   }
   requirePermission(grant, "mcp_servers:attach");
-  const encryptionKey = requireEnvironmentEncryption(settings);
+  const encryptionKey = requireVariableSetEncryption(settings);
   const existingIds = new Set(settings.mcpServers.map((server) => server.id));
   const seenIds = new Set<string>();
   const runtimeServers: Settings["mcpServers"] = [];
@@ -161,7 +188,10 @@ function validateSessionMcpServersForCreate(
     }
     const headers = normalizedSessionMcpCredentialHeaders(server.headers);
     const headersEncrypted = Object.fromEntries(
-      Object.entries(headers).map(([name, value]) => [name, encryptEnvironmentValue(encryptionKey, value)]),
+      Object.entries(headers).map(([name, value]) => [
+        name,
+        encryptVariableSetValue(encryptionKey, value),
+      ]),
     );
     runtimeServers.push(mcpServerConfigFromInput(server));
     dbServers.push({
@@ -195,12 +225,14 @@ function validateSessionMcpCredentialUpdates(input: {
     return [];
   }
   requirePermission(input.grant, "mcp_servers:attach");
-  const encryptionKey = requireEnvironmentEncryption(input.settings);
+  const encryptionKey = requireVariableSetEncryption(input.settings);
   const knownIds = new Set(input.session.mcpServers.map((server) => server.id));
   const seenIds = new Set<string>();
   const encryptedUpdates = input.updates.map((update) => {
     if (seenIds.has(update.id)) {
-      throw new HTTPException(422, { message: `duplicate session MCP credential update id: ${update.id}` });
+      throw new HTTPException(422, {
+        message: `duplicate session MCP credential update id: ${update.id}`,
+      });
     }
     seenIds.add(update.id);
     if (!knownIds.has(update.id)) {
@@ -210,7 +242,10 @@ function validateSessionMcpCredentialUpdates(input: {
     return {
       id: update.id,
       headersEncrypted: Object.fromEntries(
-        Object.entries(headers).map(([name, value]) => [name, encryptEnvironmentValue(encryptionKey, value)]),
+        Object.entries(headers).map(([name, value]) => [
+          name,
+          encryptVariableSetValue(encryptionKey, value),
+        ]),
       ),
     };
   });
@@ -232,7 +267,12 @@ export async function createAndStartSession(input: {
   sandboxBackend: Settings["sandboxBackend"];
   metadata: Record<string, unknown>;
   // Names/ids only; the session.created payload never carries variable values.
-  environment?: { id: string; name: string } | null;
+  variableSet?: { id: string; name: string } | null;
+  // The rig + frozen active rig version resolved at create (M3). Both null ⇒ a
+  // rig-less session (byte-for-byte today's behavior). Frozen here so a later
+  // rig promote never moves an existing session's version.
+  rigId?: string | null;
+  rigVersionId?: string | null;
   goal?: GoalSpec | null;
   // Per-session agent persona/system instructions (org-visible metadata, not a
   // secret). Persisted on the session row and composed system-level AFTER the
@@ -251,8 +291,8 @@ export async function createAndStartSession(input: {
   parentSessionId?: string | null;
   // Workspace-scoped CREATE idempotency key. When present, a double-fire with
   // the same key (sequential retry OR concurrent race) collapses to a single
-  // session: a prior winner is returned as-is and the start flow below is
-  // skipped, so the dup never re-emits events / re-enqueues a turn.
+  // session. Every caller repairs or re-delivers the winner's one atomic start;
+  // the durable initializer prevents duplicate events or turns.
   createIdempotencyKey?: string | null;
   // The shared-sandbox group this session's box joins (addendum 05 §D). Null/
   // omitted ⇒ a singleton group (the new row's own id, today's 1:1 behavior); a
@@ -281,14 +321,23 @@ export async function createAndStartSession(input: {
   // Fast path with a key: return a session already created under this key
   // (the sequential retry / double-submit case) without inserting again.
   if (input.createIdempotencyKey) {
-    const existing = await getSessionByCreateIdempotencyKey(input.db, input.workspaceId, input.createIdempotencyKey);
+    const existing = await getSessionByCreateIdempotencyKey(
+      input.db,
+      input.workspaceId,
+      input.createIdempotencyKey,
+    );
     if (existing) {
-      return existing;
+      return await finishStartSession(
+        existing.temporalWorkflowId ? { ...input, seedTargetSandbox: null } : input,
+        existing,
+      );
     }
     // No prior session: insert under the key, racing concurrent creates. The
     // partial unique index lets exactly one insert win; a loser gets back the
-    // winner's row with created=false and must NOT run the start flow (the
-    // winner owns the events/turn/workflow), so we return it as-is.
+    // winner's row with created=false. Both callers may enter the idempotent
+    // initializer; exactly one creates the first events/turn. Each retry
+    // advances the coalesced wake revision so an in-flight stale delivery can
+    // never acknowledge work committed by the other caller.
     const { session: keyed, created } = await createSessionWithIdempotencyKey(input.db, {
       accountId: input.accountId,
       workspaceId: input.workspaceId,
@@ -298,7 +347,9 @@ export async function createAndStartSession(input: {
       metadata: sessionMetadata,
       model: input.model,
       sandboxBackend: input.sandboxBackend,
-      environmentId: input.environment?.id ?? null,
+      variableSetId: input.variableSet?.id ?? null,
+      rigId: input.rigId ?? null,
+      rigVersionId: input.rigVersionId ?? null,
       firstPartyMcpPermissions: input.firstPartyMcpPermissions ?? null,
       instructions: input.instructions ?? null,
       parentSessionId: input.parentSessionId ?? null,
@@ -308,7 +359,10 @@ export async function createAndStartSession(input: {
       mcpServers: input.mcpServers ?? [],
     });
     if (!created) {
-      return keyed;
+      return await finishStartSession(
+        keyed.temporalWorkflowId ? { ...input, seedTargetSandbox: null } : input,
+        keyed,
+      );
     }
     return await finishStartSession(input, keyed);
   }
@@ -321,7 +375,9 @@ export async function createAndStartSession(input: {
     metadata: sessionMetadata,
     model: input.model,
     sandboxBackend: input.sandboxBackend,
-    environmentId: input.environment?.id ?? null,
+    variableSetId: input.variableSet?.id ?? null,
+    rigId: input.rigId ?? null,
+    rigVersionId: input.rigVersionId ?? null,
     firstPartyMcpPermissions: input.firstPartyMcpPermissions ?? null,
     instructions: input.instructions ?? null,
     parentSessionId: input.parentSessionId ?? null,
@@ -333,81 +389,37 @@ export async function createAndStartSession(input: {
 }
 
 /**
- * The post-insert half of {@link createAndStartSession}: durable goal row,
- * the initial event batch (session.created / goal.set / user.message /
- * status.changed), turn enqueue, and the workflow wake. Split out so the
- * idempotency-key winner and the key-less create share one body, and the
- * idempotency-key loser/dup can skip it entirely.
+ * Complete or repair the post-insert half of {@link createAndStartSession}.
+ * All durable initial state is installed by one idempotent transaction; every
+ * caller may then advance and deliver the coalesced wake revision without
+ * duplicating the goal, events, or first turn.
  */
-async function finishStartSession(input: {
-  db: Database;
-  bus: EventBus;
-  workflowClient: SessionWorkflowClient;
-  initialMessage: string;
-  resources: ResourceRef[];
-  tools: ToolRef[];
-  clientEventId?: string;
-  model: string;
-  reasoningEffort: Settings["openaiReasoningEffort"];
-  sandboxBackend: Settings["sandboxBackend"];
-  environment?: { id: string; name: string } | null;
-  goal?: GoalSpec | null;
-  sessionMcpServers?: SessionMcpServerMetadata[];
-  seedTargetSandbox?: { sandboxId: string; settings: Settings; workingDir?: string | null } | null;
-}, session: Session): Promise<Session> {
-  // The goal row is durable session state; the workflow picks it up from the
-  // database once the first turn completes — no extra workflow plumbing here.
-  const goal = input.goal
-    ? await createSessionGoal(input.db, {
-      accountId: session.accountId,
-      workspaceId: session.workspaceId,
-      sessionId: session.id,
-      text: input.goal.text,
-      successCriteria: input.goal.successCriteria ?? null,
-      maxAutoContinuations: input.goal.maxAutoContinuations ?? null,
-      createdBy: "api",
-    })
-    : null;
-  const initialPayload = {
-    text: input.initialMessage,
-    ...(input.resources.length ? { resources: input.resources } : {}),
-    ...(input.tools.length ? { tools: input.tools } : {}),
-  };
-  const events = await appendAndPublishEvents(input.db, input.bus, session.workspaceId, session.id, [
-    {
-      type: "session.created",
-      payload: {
-        status: "queued",
-        ...(input.environment ? { environmentId: input.environment.id, environmentName: input.environment.name } : {}),
-        ...(input.sessionMcpServers?.length ? { mcpServers: input.sessionMcpServers } : {}),
-      },
-    },
-    ...(goal ? [{
-      type: "goal.set" as const,
-      payload: {
-        goalId: goal.id,
-        text: goal.text,
-        ...(goal.successCriteria ? { successCriteria: goal.successCriteria } : {}),
-        version: goal.version,
-        actor: "api",
-        replaced: false,
-      },
-    }] : []),
-    {
-      type: "user.message",
-      payload: initialPayload,
-      ...(input.clientEventId ? { clientEventId: input.clientEventId } : {}),
-    },
-    { type: "session.status.changed", payload: { status: "queued" } },
-  ]);
-  const userEvent = events.find((event) => event.type === "user.message");
-  if (!userEvent) {
-    throw new HTTPException(500, { message: "failed to append initial user event" });
-  }
+async function finishStartSession(
+  input: {
+    db: Database;
+    bus: EventBus;
+    workflowClient: SessionWorkflowClient;
+    initialMessage: string;
+    resources: ResourceRef[];
+    tools: ToolRef[];
+    clientEventId?: string;
+    model: string;
+    reasoningEffort: Settings["openaiReasoningEffort"];
+    sandboxBackend: Settings["sandboxBackend"];
+    variableSet?: { id: string; name: string } | null;
+    goal?: GoalSpec | null;
+    sessionMcpServers?: SessionMcpServerMetadata[];
+    seedTargetSandbox?: {
+      sandboxId: string;
+      settings: Settings;
+      workingDir?: string | null;
+    } | null;
+  },
+  session: Session,
+): Promise<Session> {
   // Create-time machine targeting (A-2a): seed the active-sandbox pointer BEFORE
-  // the first turn is enqueued + the workflow woken, so the FIRST turn routes to
-  // the chosen machine. Race-free: the epoch-fenced setActiveSandbox commits here,
-  // before wakeSessionWorkflow below signals the worker. swapActiveSandbox does
+  // the atomic initial turn transaction, so the FIRST turn routes to the chosen
+  // machine. swapActiveSandbox does
   // the same ownership+liveness validation as the live swap; an invalid/unowned/
   // offline target FAILS the create (422) — never a silent fall-back to the box.
   if (input.seedTargetSandbox) {
@@ -437,29 +449,40 @@ async function finishStartSession(input: {
       });
     }
   }
-  const workflowId = workflowIdForSession(session.id);
-  await setTemporalWorkflowId(input.db, session.workspaceId, session.id, workflowId);
-  const turn = await enqueueSessionTurn(input.db, {
+  const started = await initializeSessionStartAtomically(input.db, {
     accountId: session.accountId,
     workspaceId: session.workspaceId,
     sessionId: session.id,
-    triggerEventId: userEvent.id,
-    temporalWorkflowId: workflowId,
-    source: "user",
-    prompt: input.initialMessage,
-    resources: input.resources,
-    tools: input.tools,
-    model: input.model,
-    reasoningEffort: input.reasoningEffort,
-    sandboxBackend: input.sandboxBackend,
-    metadata: {},
+    ...(input.clientEventId ? { clientEventId: input.clientEventId } : {}),
+    reasoningEffortFallback: input.reasoningEffort,
+    createdEventPayload: {
+      ...(input.variableSet
+        ? { variableSetId: input.variableSet.id, variableSetName: input.variableSet.name }
+        : {}),
+      ...(input.sessionMcpServers?.length ? { mcpServers: input.sessionMcpServers } : {}),
+    },
+    goal: input.goal
+      ? {
+          text: input.goal.text,
+          ...(input.goal.successCriteria !== undefined
+            ? { successCriteria: input.goal.successCriteria }
+            : {}),
+          ...(input.goal.maxAutoContinuations !== undefined
+            ? { maxAutoContinuations: input.goal.maxAutoContinuations }
+            : {}),
+        }
+      : null,
   });
-  await appendAndPublishEvents(input.db, input.bus, session.workspaceId, session.id, [{
-    type: "turn.queued",
-    turnId: turn.id,
-    payload: { turnId: turn.id, triggerEventId: userEvent.id, source: turn.source },
-  }]);
-  await input.workflowClient.wakeSessionWorkflow({ accountId: session.accountId, workspaceId: session.workspaceId, sessionId: session.id, workflowId });
+  await publishDurableSessionEvents(input.bus, session.workspaceId, session.id, started.events);
+  if (started.workflowWakeRevision !== null) {
+    await input.workflowClient.wakeSessionWorkflow({
+      accountId: session.accountId,
+      workspaceId: session.workspaceId,
+      sessionId: session.id,
+      workflowId: started.temporalWorkflowId,
+      wakeRevision: started.workflowWakeRevision,
+    });
+  }
   return await requireSession(input.db, session.workspaceId, session.id);
 }
 
@@ -502,18 +525,64 @@ export function assertConfiguredModel(settings: Settings, model: string | null |
   throw new HTTPException(422, { message: `model is not available: ${model}` });
 }
 
-export async function requireQueuedTurnForApi(db: Database, workspaceId: string, sessionId: string, turnId: string): Promise<SessionTurn> {
+/**
+ * Reject a model the WORKSPACE's model policy blocks, at the same choke points
+ * as assertConfiguredModel — a 422 at the edge instead of a queued turn the
+ * worker's authoritative post-resolution gate would fail. `model` is the
+ * EFFECTIVE value the caller is about to persist: pass the explicit value at
+ * message/turn-update/scheduled-task edges (omitted inherits an
+ * already-validated stored default), but at session CREATION pass
+ * `payload.model ?? settings.openaiModel` — an omitted model stamps the
+ * deployment default onto the session, and under a restricted policy that
+ * default may be exactly the provider the policy exists to block.
+ */
+export async function assertWorkspaceModelPolicyAllows(
+  db: Database,
+  settings: Settings,
+  workspaceId: string,
+  model: string | null | undefined,
+): Promise<void> {
+  if (model === null || model === undefined) {
+    return;
+  }
+  const policy = await getWorkspaceModelPolicy(db, workspaceId);
+  if (!policy) {
+    return;
+  }
+  const providerId = policyProviderIdForModel(settings, model);
+  const verdict = evaluateWorkspaceModelPolicy(policy, { providerId, modelId: model });
+  if (!verdict.allowed) {
+    throw new HTTPException(422, {
+      message:
+        verdict.reason === "provider"
+          ? `model "${model}" is not allowed by this workspace's model policy: provider "${providerId}" is not in the allowed providers`
+          : `model "${model}" is not allowed by this workspace's model policy`,
+    });
+  }
+}
+
+export async function requireQueuedTurnForApi(
+  db: Database,
+  workspaceId: string,
+  sessionId: string,
+  turnId: string,
+): Promise<SessionTurn> {
   const turn = await getSessionTurn(db, workspaceId, turnId);
   if (!turn || turn.sessionId !== sessionId) {
     throw new HTTPException(404, { message: "session turn not found" });
   }
   if (turn.status !== "queued") {
-    throw new HTTPException(409, { message: `turn is ${turn.status}; only queued turns can be changed` });
+    throw new HTTPException(409, {
+      message: `turn is ${turn.status}; only queued turns can be changed`,
+    });
   }
   return turn;
 }
 
-export function reasoningEffortForSession(metadata: Record<string, unknown>, fallback: Settings["openaiReasoningEffort"]): Settings["openaiReasoningEffort"] {
+export function reasoningEffortForSession(
+  metadata: Record<string, unknown>,
+  fallback: Settings["openaiReasoningEffort"],
+): Settings["openaiReasoningEffort"] {
   return reasoningEffortForMetadata(metadata, fallback);
 }
 
@@ -527,7 +596,7 @@ export function reasoningEffortForSession(metadata: Record<string, unknown>, fal
 export async function postUserMessageTurn(input: {
   db: Database;
   bus: EventBus;
-  workflowClient: SessionWorkflowClient;
+  workflowClient: Pick<SessionWorkflowClient, "wakeSessionWorkflow" | "signalSessionControl">;
   settings: Settings;
   accountId: string;
   workspaceId: string;
@@ -539,6 +608,11 @@ export async function postUserMessageTurn(input: {
   reasoningEffort?: Settings["openaiReasoningEffort"] | null;
   clientEventId?: string;
   mcpCredentialUpdates?: UpdateSessionMcpServerCredentialsInput[];
+  delivery?: "queue" | "steer";
+  origin?: "human" | "operator";
+  actor?: string;
+  expectedControlGeneration?: number;
+  expectedWorkspaceInferenceGeneration?: number;
 }): Promise<{ accepted: SessionEvent; turn: SessionTurn }> {
   const { db, bus, workflowClient, settings, accountId, workspaceId, sessionId } = input;
   const requestedModel = input.model ?? null;
@@ -546,85 +620,79 @@ export async function postUserMessageTurn(input: {
   // Reject an explicit per-message model the host does not expose; an omitted
   // model inherits the session's model downstream (always a configured id).
   assertConfiguredModel(settings, requestedModel);
-  const appended = await appendSessionEventsWithLockedSessionUpdate(db, workspaceId, sessionId, async (lockedSession, lockedUpdate) => {
-    // Cancelled is the one terminal state: an explicit user act. A FAILED
-    // session stays revivable by talking to it — conversation truth lives in
-    // session_history_items, so a failed turn does not invalidate history,
-    // and the manager channel of record must always answer when spoken to.
-    // The new message transitions failed -> queued (clearing the stale
-    // activeTurnId) and the signalWithStart below starts a fresh workflow
-    // run for the completed (failed) one, exactly as for idle sessions.
-    if (lockedSession.status === "cancelled") {
-      throw new HTTPException(409, { message: `session is ${lockedSession.status}; cannot accept a new user message` });
+  await assertWorkspaceModelPolicyAllows(db, settings, workspaceId, requestedModel);
+  let result;
+  try {
+    result = await enqueueSessionMessageAtomically(db, {
+      accountId,
+      workspaceId,
+      sessionId,
+      actor: input.actor ?? accountId,
+      origin: input.origin ?? "human",
+      text: input.text,
+      resources: input.resources,
+      tools: input.tools,
+      model: requestedModel,
+      reasoningEffort: requestedReasoningEffort,
+      clientEventId: input.clientEventId ?? null,
+      mcpCredentialUpdates: input.mcpCredentialUpdates ?? [],
+      delivery: input.delivery ?? "queue",
+      ...(input.expectedControlGeneration !== undefined
+        ? { expectedControlGeneration: input.expectedControlGeneration }
+        : {}),
+      ...(input.expectedWorkspaceInferenceGeneration !== undefined
+        ? {
+            expectedWorkspaceInferenceGeneration: input.expectedWorkspaceInferenceGeneration,
+          }
+        : {}),
+      reasoningEffortFallback: settings.openaiReasoningEffort,
+    });
+  } catch (error) {
+    if (error instanceof SessionQueueConflictError) {
+      throw new HTTPException(409, { message: error.message });
     }
-    const mcpCredentialUpdates = input.mcpCredentialUpdates?.length
-      ? await lockedUpdate.updateSessionMcpServerCredentials(input.mcpCredentialUpdates)
-      : { servers: [], missingIds: [] };
-    if (mcpCredentialUpdates.missingIds.length > 0) {
-      throw new HTTPException(422, { message: `unknown session MCP server id: ${mcpCredentialUpdates.missingIds[0]}` });
+    if (error instanceof Error && error.message.includes("cancelled")) {
+      throw new HTTPException(409, { message: error.message });
     }
-    const nextResources = mergeResourceRefs(lockedSession.resources, input.resources);
-    const nextTools = mergeToolRefs(lockedSession.tools, input.tools);
-    const shouldQueueSession = lockedSession.status === "idle" || lockedSession.status === "failed";
-    return {
-      events: [
-        {
-          type: "user.message",
-          payload: {
-            text: input.text,
-            ...(input.resources.length ? { resources: input.resources } : {}),
-            ...(input.tools.length ? { tools: input.tools } : {}),
-            ...(requestedModel ? { model: requestedModel } : {}),
-            ...(requestedReasoningEffort ? { reasoningEffort: requestedReasoningEffort } : {}),
-            ...(mcpCredentialUpdates.servers.length ? { mcpCredentialUpdates: mcpCredentialUpdates.servers } : {}),
-          },
-          ...(input.clientEventId ? { clientEventId: input.clientEventId } : {}),
-        },
-        ...(shouldQueueSession ? [{ type: "session.status.changed" as const, payload: { status: "queued" } }] : []),
-      ],
-      update: {
-        resources: nextResources,
-        tools: nextTools,
-        ...(shouldQueueSession ? { status: "queued" as const, activeTurnId: null } : {}),
-      },
-    };
-  }).then(async (events) => {
-    await bus.publish(workspaceId, sessionId, events);
-    return events;
-  });
-  const accepted = appended[0];
-  if (!accepted) {
-    throw new HTTPException(500, { message: "failed to append client event" });
-  }
-  const workflowId = workflowIdForSession(sessionId);
-  const session = await requireSession(db, workspaceId, sessionId);
-  const turn = await enqueueSessionTurn(db, {
-    accountId,
-    workspaceId,
-    sessionId,
-    triggerEventId: accepted.id,
-    temporalWorkflowId: workflowId,
-    source: "user",
-    prompt: input.text,
-    resources: input.resources,
-    tools: input.tools,
-    model: requestedModel ?? session.model,
-    reasoningEffort: requestedReasoningEffort ?? reasoningEffortForSession(session.metadata, settings.openaiReasoningEffort),
-    sandboxBackend: session.sandboxBackend,
-    metadata: {},
-  });
-  await appendAndPublishEvents(db, bus, workspaceId, sessionId, [{
-    type: "turn.queued",
-    turnId: turn.id,
-    payload: { turnId: turn.id, triggerEventId: accepted.id, source: turn.source },
-  }]);
-  await workflowClient.wakeSessionWorkflow({ accountId, workspaceId, sessionId, workflowId });
-  return { accepted, turn };
+    if (error instanceof Error && error.message.startsWith("Unknown session MCP server")) {
+      throw new HTTPException(422, { message: error.message });
+    }
+    throw error;
+  }
+  await bus.publish(workspaceId, sessionId, result.events);
+  if (result.shouldSignalControl && result.controlEvent) {
+    if (result.workflowWakeRevision === null) {
+      throw new Error("Steer control has no workflow wake revision");
+    }
+    await workflowClient.signalSessionControl({
+      accountId,
+      workspaceId,
+      sessionId,
+      eventId: result.controlEvent.id,
+      workflowId: result.temporalWorkflowId,
+      workflowWakeRevision: result.workflowWakeRevision,
+    });
+  } else if (result.shouldWake) {
+    if (result.workflowWakeRevision === null) {
+      throw new Error("Runnable prompt has no workflow wake revision");
+    }
+    await workflowClient.wakeSessionWorkflow({
+      accountId,
+      workspaceId,
+      sessionId,
+      workflowId: result.temporalWorkflowId,
+      wakeRevision: result.workflowWakeRevision,
+    });
+  }
+  return {
+    accepted: result.accepted,
+    turn: result.turn,
+  };
 }
 
 /**
  * Full create-session flow shared by `POST /sessions` and the first-party MCP
- * `session_create` tool: payload validation, resource/tool/environment
+ * `session_create` tool: payload validation, resource/tool/variableSet
  * checks, usage limits, session start, and usage recording. `rawPayload` is
  * the unparsed request body so absent-vs-empty `tools` keeps its meaning
  * (absent applies the workspace's default capability MCP tools).
@@ -637,9 +705,20 @@ export async function createSessionForRequest(
 ): Promise<Session> {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
   const payload = CreateSessionRequest.parse(rawPayload);
-  const capabilityRuntimeSettings = await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings);
-  const sessionMcpServers = validateSessionMcpServersForCreate(capabilityRuntimeSettings, grant, payload.mcpServers);
-  const runtimeSettings = settingsWithSessionMcpServerConfigs(capabilityRuntimeSettings, sessionMcpServers.runtimeServers);
+  const capabilityRuntimeSettings = await settingsWithEnabledCapabilityMcpServers(
+    db,
+    workspaceId,
+    settings,
+  );
+  const sessionMcpServers = validateSessionMcpServersForCreate(
+    capabilityRuntimeSettings,
+    grant,
+    payload.mcpServers,
+  );
+  const runtimeSettings = settingsWithSessionMcpServerConfigs(
+    capabilityRuntimeSettings,
+    sessionMcpServers.runtimeServers,
+  );
   const resources = normalizeResources(payload.resources);
   const requestedTools = validateToolRefs(payload.tools, runtimeSettings);
   const defaultedTools = hasOwnProperty(rawPayload, "tools")
@@ -647,7 +726,7 @@ export async function createSessionForRequest(
     : withDefaultEnabledCapabilityMcpTools(requestedTools, settings, capabilityRuntimeSettings);
   // The first-party MCP server is attached to EVERY session. It hosts the
   // session's own metadata tool (set_session_title) + goal tools, and — only
-  // when the grant carries the permission — the orchestration/environment/
+  // when the grant carries the permission — the orchestration/variableSet/
   // github tools. Capability is gated per-tool by permission, never by whether
   // the server is attached, so a bare chat still gets titling while the
   // dangerous tools stay off by default.
@@ -657,13 +736,57 @@ export async function createSessionForRequest(
     throw new HTTPException(503, { message: "object storage is not configured" });
   }
   await validateFileResources(db, workspaceId, resources);
-  // Environment attachment requires environments:use on the calling grant
-  // (validateEnvironmentAttachment enforces it), preserving the invariant
+  // VariableSet attachment requires variable-sets:use on the calling grant
+  // (validateVariableSetAttachment enforces it), preserving the invariant
   // that sandboxed agents cannot self-attach workspace secrets.
-  const environment = payload.environmentId
-    ? await validateEnvironmentAttachment({ settings, db }, grant, workspaceId, payload.environmentId)
+  const variableSet = payload.variableSetId
+    ? await validateVariableSetAttachment(
+        { settings, db },
+        grant,
+        workspaceId,
+        payload.variableSetId,
+      )
     : null;
+  // RIG BINDING (M3). Resolve the rig this session rides — the EXPLICIT payload
+  // rigId when given, else the workspace default rig (workspaces.default_rig_id)
+  // — and FREEZE both the rig id and its currently-ACTIVE version onto the row.
+  // The session then rides that exact version for its whole life; a later
+  // promote never moves it. Rig-less (both null) when neither resolves, which is
+  // byte-for-byte today's behavior (zero extra work, zero row change).
+  //   - An EXPLICIT unknown/inactive rigId is a caller error → 422.
+  //   - A stale workspace-default rig (deleted → FK-nulled, or somehow with no
+  //     active version) degrades SILENTLY to rig-less: an operator-side default
+  //     must never brick every create in the workspace.
+  const requestedRigId = payload.rigId ?? (await getWorkspaceDefaultRigId(db, workspaceId));
+  let frozenRigId: string | null = null;
+  let frozenRigVersionId: string | null = null;
+  if (requestedRigId) {
+    const rig = await getRig(db, workspaceId, requestedRigId);
+    if (!rig || !rig.activeVersion) {
+      if (payload.rigId) {
+        throw new HTTPException(422, {
+          message: rig
+            ? `rig ${payload.rigId} has no active version to bind`
+            : `unknown rigId: ${payload.rigId}`,
+        });
+      }
+      // else: workspace-default fallback that no longer resolves → rig-less.
+    } else {
+      frozenRigId = rig.id;
+      frozenRigVersionId = rig.activeVersion.id;
+    }
+  }
   assertConfiguredModel(settings, payload.model);
+  // Session creation persists the EFFECTIVE model — an omitted payload.model
+  // stamps the deployment default onto the session — so the policy must vet
+  // that effective value, not just explicit ones (a restricted workspace's
+  // default-model session would otherwise be born blocked).
+  await assertWorkspaceModelPolicyAllows(
+    db,
+    settings,
+    workspaceId,
+    payload.model ?? settings.openaiModel,
+  );
   const model = payload.model ?? settings.openaiModel;
   const reasoningEffort = payload.reasoningEffort ?? settings.openaiReasoningEffort;
   // A session's first-party MCP token can carry a non-default permission set
@@ -674,11 +797,16 @@ export async function createSessionForRequest(
   if (firstPartyMcpPermissions && firstPartyMcpPermissions.length === 0) {
     // An empty set would sign an unusable zero-permission token; the default
     // worker set is expressed by omitting the field.
-    throw new HTTPException(422, { message: "firstPartyMcpPermissions must not be empty; omit it for the default worker permission set" });
+    throw new HTTPException(422, {
+      message:
+        "firstPartyMcpPermissions must not be empty; omit it for the default worker permission set",
+    });
   }
   for (const permission of firstPartyMcpPermissions ?? []) {
     if (!hasPermission(grant.permissions, permission)) {
-      throw new HTTPException(403, { message: `cannot grant first-party MCP permission beyond the creating grant: ${permission}` });
+      throw new HTTPException(403, {
+        message: `cannot grant first-party MCP permission beyond the creating grant: ${permission}`,
+      });
     }
   }
   // Invariant: a goal-bearing session always carries goals:manage in its
@@ -690,7 +818,11 @@ export async function createSessionForRequest(
   // spawned session itself via the worker-signed sessionId claim, so a
   // worker managing its OWN goal is not an escalation of the spawner's
   // authority.
-  if (payload.goal && firstPartyMcpPermissions && !firstPartyMcpPermissions.includes("goals:manage")) {
+  if (
+    payload.goal &&
+    firstPartyMcpPermissions &&
+    !firstPartyMcpPermissions.includes("goals:manage")
+  ) {
     firstPartyMcpPermissions = [...firstPartyMcpPermissions, "goals:manage"];
   }
   // Parent linkage: a worker is linked to its manager ONLY from the
@@ -704,7 +836,10 @@ export async function createSessionForRequest(
   // its completion wake injects a user.message + queued turn into that session
   // without holding sessions:control on it (a cross-session write escalation).
   // The claim is the only trustworthy parent source.
-  const parentSessionId = typeof grant.metadata?.["sessionId"] === "string" ? grant.metadata["sessionId"] as string : null;
+  const parentSessionId =
+    typeof grant.metadata?.["sessionId"] === "string"
+      ? (grant.metadata["sessionId"] as string)
+      : null;
   // Shared-sandbox placement (addendum 05 §D.2/§D.3, decision I10/OD-S1).
   //
   // The DEFAULT rule is context-dependent and resolved server-side from the
@@ -724,39 +859,75 @@ export async function createSessionForRequest(
   const sandboxChoice = payload.sandbox ?? (parentSessionId ? "shared" : "new");
   let sandboxGroupId: string | null = null;
   let inheritedBackend: Session["sandboxBackend"] | undefined;
-  // ENV-AWARE GROUPING: under the CURRENT mechanics the workspace Environment is
+  // ENV-AWARE GROUPING: under the CURRENT mechanics the workspace VariableSet is
   // creation-time box state — the box's manifest env is fixed when it is cold-
   // created, and the SDK's provided-session guard rejects any manifest-env delta
-  // at attach. A session carrying a DIFFERENT Environment than the box it joins
+  // at attach. A session carrying a DIFFERENT VariableSet than the box it joins
   // is therefore a genuine shared-state conflict TODAY: its first turn on a warm
-  // box dies with "Live sandbox sessions cannot change manifest environment
-  // variables" (proven live, sessions 5aee77e9 + 63d18823). Until the Environment
+  // box dies with "Live sandbox sessions cannot change manifest variableSet
+  // variables" (proven live, sessions 5aee77e9 + 63d18823). Until the VariableSet
   // is evicted from the manifest (per-exec, like the git token), grouping must be
   // env-aware: the INHERITED default falls back to an own box on mismatch (a
   // credentialed worker spawned from a credential-less manager just works), and
-  // an EXPLICIT shared/{groupId} request with a mismatched Environment fails
+  // an EXPLICIT shared/{groupId} request with a mismatched VariableSet fails
   // fast at create (422) instead of poisoning the session's first turn.
   // The env conflict is a BOX property, so a boxless group is exempt: a
   // backend:"none" session runs in-process with no sandbox, no manifest, and no
   // provided-session attach — no shared box state exists to conflict, and
   // env-differing spawns from such parents shared safely before the env-aware
   // check. They keep sharing (and keep inheriting "none").
-  const requestedEnvironmentId = payload.environmentId ?? null;
-  const environmentMatchesGroup = (memberEnvironmentId: string | null): boolean =>
-    memberEnvironmentId === requestedEnvironmentId;
+  const requestedVariableSetId = payload.variableSetId ?? null;
+  const variableSetMatchesGroup = (memberVariableSetId: string | null): boolean =>
+    memberVariableSetId === requestedVariableSetId;
+  // RIG-AWARE GROUPING (M3), the exact sibling of the env-aware gate above: the
+  // box's rig-baked setup/tooling is fixed at cold-create, so a session joining a
+  // shared box must ride the SAME frozen rig_version_id. A mismatch is a genuine
+  // shared-state conflict (the box was set up for a different rig) — the INHERITED
+  // default falls back to an own box, an EXPLICIT shared/{groupId} request 422s at
+  // create rather than poisoning the first turn on the lease's rig-conflict guard.
+  // null on either side = compatible (a rig-less session shares with a rig-less
+  // box exactly as today); the boxless backend:'none' exemption is shared with the
+  // env gate (no box state to conflict).
+  const rigVersionMatchesGroup = (memberRigVersionId: string | null): boolean =>
+    memberRigVersionId === frozenRigVersionId;
   if (sandboxChoice === "shared") {
     if (!parentSessionId) {
-      throw new HTTPException(422, { message: "sandbox:'shared' requires a parent session (spawn from inside a session); use 'new' for a top-level create." });
+      throw new HTTPException(422, {
+        message:
+          "sandbox:'shared' requires a parent session (spawn from inside a session); use 'new' for a top-level create.",
+      });
     }
     const parent = await getSession(db, workspaceId, parentSessionId);
     if (!parent) {
-      throw new HTTPException(404, { message: `parent session not found in workspace: ${parentSessionId}` });
+      throw new HTTPException(404, {
+        message: `parent session not found in workspace: ${parentSessionId}`,
+      });
+    }
+    const parentBoxed = parent.sandboxBackend !== "none";
+    const variableSetMismatch =
+      parentBoxed && !variableSetMatchesGroup(parent.variableSetId ?? null);
+    let rigMismatch = parentBoxed && !rigVersionMatchesGroup(parent.rigVersionId ?? null);
+    if (parentBoxed && !rigMismatch) {
+      const memberRigVersionIds = await listDistinctRigVersionIdsInGroup(
+        db,
+        workspaceId,
+        parent.sandboxGroupId,
+      );
+      rigMismatch = !memberRigVersionIds.every((memberRigVersionId) =>
+        rigVersionMatchesGroup(memberRigVersionId),
+      );
     }
-    if (parent.sandboxBackend !== "none" && !environmentMatchesGroup(parent.environmentId ?? null)) {
+    if (variableSetMismatch || rigMismatch) {
       if (payload.sandbox === "shared") {
         // The caller explicitly asked to share while carrying a different
-        // Environment — surface the conflict at create time, not turn time.
-        throw new HTTPException(422, { message: "sandbox:'shared' requires the same environment as the creator's box (the box environment is fixed at creation); omit sandbox or pass 'new' when attaching a different environment." });
+        // VariableSet / rig — surface the conflict at create time, not turn time.
+        // VariableSet is checked first so its (pre-rig) message is unchanged for
+        // the env-only mismatch the existing gate already covered.
+        throw new HTTPException(422, {
+          message: variableSetMismatch
+            ? "sandbox:'shared' requires the same variableSet / same environment as the creator's box (the box variable set/environment is fixed at creation); omit sandbox or pass 'new' when attaching a different variableSet/environment."
+            : "sandbox:'shared' requires the same rig as the creator's box (the box's rig setup is fixed at creation); omit sandbox or pass 'new' when binding a different rig.",
+        });
       }
       // Inherited default: deterministic separation on the genuine shared-state
       // conflict — the worker gets its own box (resolved like a top-level
@@ -769,17 +940,46 @@ export async function createSessionForRequest(
   } else if (typeof sandboxChoice === "object") {
     const member = await getAnySessionInGroup(db, workspaceId, sandboxChoice.groupId);
     if (!member) {
-      throw new HTTPException(404, { message: `sandbox group not found in workspace: ${sandboxChoice.groupId}` });
+      throw new HTTPException(404, {
+        message: `sandbox group not found in workspace: ${sandboxChoice.groupId}`,
+      });
     }
     if (member.sandboxBackend !== "none") {
       // Compare against EVERY member, not one arbitrary row: a legacy env-blind
-      // group can carry mixed environmentIds, and an any-member read would make
+      // group can carry mixed variableSetIds, and an any-member read would make
       // the join verdict nondeterministic. Post-env-aware groups are homogeneous
       // (both join paths enforce equality), so this reads one distinct value in
       // the common case; a mixed legacy group deterministically rejects.
-      const memberEnvironmentIds = await listDistinctEnvironmentIdsInGroup(db, workspaceId, sandboxChoice.groupId);
-      if (!memberEnvironmentIds.every((memberEnvironmentId) => environmentMatchesGroup(memberEnvironmentId))) {
-        throw new HTTPException(422, { message: `sandbox group ${sandboxChoice.groupId} runs a different environment (the box environment is fixed at creation); create with the group's environment or omit sandbox for an own box.` });
+      const memberVariableSetIds = await listDistinctVariableSetIdsInGroup(
+        db,
+        workspaceId,
+        sandboxChoice.groupId,
+      );
+      if (
+        !memberVariableSetIds.every((memberVariableSetId) =>
+          variableSetMatchesGroup(memberVariableSetId),
+        )
+      ) {
+        throw new HTTPException(422, {
+          message: `sandbox group ${sandboxChoice.groupId} runs a different variableSet / different environment (the box variable set/environment is fixed at creation); create with the group's variableSet/environment or omit sandbox for an own box.`,
+        });
+      }
+      // Same deterministic all-members check for the frozen rig version (M3): the
+      // box's rig setup is fixed at creation, so every member must ride the rig
+      // this create resolved (or the group is rig-less and so is this create).
+      const memberRigVersionIds = await listDistinctRigVersionIdsInGroup(
+        db,
+        workspaceId,
+        sandboxChoice.groupId,
+      );
+      if (
+        !memberRigVersionIds.every((memberRigVersionId) =>
+          rigVersionMatchesGroup(memberRigVersionId),
+        )
+      ) {
+        throw new HTTPException(422, {
+          message: `sandbox group ${sandboxChoice.groupId} runs a different rig (the box's rig setup is fixed at creation); create with the group's rig or omit sandbox for an own box.`,
+        });
       }
     }
     sandboxGroupId = sandboxChoice.groupId;
@@ -791,7 +991,10 @@ export async function createSessionForRequest(
   // — reject it at the edge (mirrors the backend:'none' guard) rather than silently
   // dropping it, since the default group box has no working-dir seam yet.
   if (payload.workingDir !== undefined && !payload.targetSandboxId) {
-    throw new HTTPException(422, { message: "workingDir requires targetSandboxId (it is the targeted machine's working directory)" });
+    throw new HTTPException(422, {
+      message:
+        "workingDir requires targetSandboxId (it is the targeted machine's working directory)",
+    });
   }
   // Honest-label (Stage-D closure): a top-level session TARGETED at a Connected
   // Machine (a selfhosted sandbox) runs machine-primary every turn, so its HOME
@@ -821,23 +1024,32 @@ export async function createSessionForRequest(
   let machineHomeBackend: Session["sandboxBackend"] | undefined;
   let machineHomeOs: Session["sandboxOs"] | undefined;
   if (
-    payload.targetSandboxId
-    && inheritedBackend === undefined
-    && settings.sandboxOwnershipEnabled
-    && settings.sandboxSelfhostedEnabled
+    payload.targetSandboxId &&
+    inheritedBackend === undefined &&
+    settings.sandboxOwnershipEnabled &&
+    settings.sandboxSelfhostedEnabled
   ) {
     const targetSandbox = await getSandbox(db, workspaceId, payload.targetSandboxId);
     if (targetSandbox?.kind === "selfhosted") {
       machineHomeBackend = "selfhosted";
       if (targetSandbox.enrollmentId) {
         const enrollment = await getEnrollment(db, workspaceId, targetSandbox.enrollmentId);
-        if (enrollment && (enrollment.os === "macos" || enrollment.os === "windows" || enrollment.os === "linux")) {
+        if (
+          enrollment &&
+          (enrollment.os === "macos" || enrollment.os === "windows" || enrollment.os === "linux")
+        ) {
           machineHomeOs = enrollment.os;
         }
       }
     }
   }
-  await requireLimit(deps, { accountId: grant.accountId, workspaceId, action: "agent_run:create", quantity: 1, model });
+  await requireLimit(deps, {
+    accountId: grant.accountId,
+    workspaceId,
+    action: "agent_run:create",
+    quantity: 1,
+    model,
+  });
   const session = await createAndStartSession({
     db,
     bus,
@@ -855,14 +1067,18 @@ export async function createSessionForRequest(
     // machine-targeted top-level create labels the home "selfhosted"
     // (machineHomeBackend), overriding the caller/deployment default so the row
     // matches where the session actually runs.
-    sandboxBackend: inheritedBackend ?? machineHomeBackend ?? payload.sandboxBackend ?? settings.sandboxBackend,
+    sandboxBackend:
+      inheritedBackend ?? machineHomeBackend ?? payload.sandboxBackend ?? settings.sandboxBackend,
     // Mirror the backend relabel on the OS axis: only a machine-targeted
     // top-level create carries a derived OS; everything else is omitted and the
     // "linux" default holds (shared spawns keep the parent-box behavior).
     ...(machineHomeOs ? { sandboxOs: machineHomeOs } : {}),
     sandboxGroupId,
     metadata: payload.metadata,
-    environment: environment ? { id: environment.id, name: environment.name } : null,
+    variableSet: variableSet ? { id: variableSet.id, name: variableSet.name } : null,
+    // Frozen rig binding (M3): both null for a rig-less session (today's path).
+    rigId: frozenRigId,
+    rigVersionId: frozenRigVersionId,
     goal: payload.goal ?? null,
     // Per-session persona instructions (already trimmed/validated by the
     // contracts schema). Persisted on the row; composed system-level at turn
@@ -903,7 +1119,7 @@ export async function createSessionForRequest(
  * workspace's default capability MCP tools, matching an absent `tools` key.
  */
 export async function acceptSessionUserMessage(
-  deps: ApiRouteDeps,
+  deps: AcceptSessionUserMessageDependencies,
   grant: AccessGrant,
   workspaceId: string,
   sessionId: string,
@@ -916,15 +1132,26 @@ export async function acceptSessionUserMessage(
     reasoningEffort?: ReasoningEffort | null;
     clientEventId?: string;
     mcpCredentialUpdates?: SessionMcpCredentialUpdateInput[];
+    delivery?: "queue" | "steer";
+    origin?: "human" | "operator";
+    expectedControlGeneration?: number;
+    expectedWorkspaceInferenceGeneration?: number;
   },
 ): Promise<{ accepted: SessionEvent; turn: SessionTurn }> {
   const { settings, db, bus, workflowClient, objectStorage } = deps;
-  const capabilityRuntimeSettings = await settingsWithEnabledCapabilityMcpServers(db, workspaceId, settings);
+  const capabilityRuntimeSettings = await settingsWithEnabledCapabilityMcpServers(
+    db,
+    workspaceId,
+    settings,
+  );
   // Hoisted above requireLimit so the codex-billed predicate can resolve the
   // turn's effective model (a follow-up turn inherits the session's model). A
   // pure read with no side effects.
   const existingSession = await requireSession(db, workspaceId, sessionId);
-  const runtimeSettings = settingsWithSessionMcpServerMetadata(capabilityRuntimeSettings, existingSession.mcpServers);
+  const runtimeSettings = settingsWithSessionMcpServerMetadata(
+    capabilityRuntimeSettings,
+    existingSession.mcpServers,
+  );
   const requestedResources = normalizeResources(input.resources ?? []);
   const validatedTools = validateToolRefs(input.tools ?? [], runtimeSettings);
   const requestedTools = input.toolsProvided
@@ -941,7 +1168,10 @@ export async function acceptSessionUserMessage(
     throw new HTTPException(503, { message: "object storage is not configured" });
   }
   await validateFileResources(db, workspaceId, requestedResources);
-  await validateGitHubRepositorySelection(db, workspaceId, [...existingSession.resources, ...requestedResources]);
+  await validateGitHubRepositorySelection(db, workspaceId, [
+    ...existingSession.resources,
+    ...requestedResources,
+  ]);
   const mcpCredentialUpdates = validateSessionMcpCredentialUpdates({
     settings,
     grant,
@@ -962,6 +1192,17 @@ export async function acceptSessionUserMessage(
     model: input.model ?? null,
     reasoningEffort: input.reasoningEffort ?? null,
     mcpCredentialUpdates,
+    delivery: input.delivery ?? "queue",
+    origin: input.origin ?? "human",
+    actor: grant.subjectId,
+    ...(input.expectedControlGeneration !== undefined
+      ? { expectedControlGeneration: input.expectedControlGeneration }
+      : {}),
+    ...(input.expectedWorkspaceInferenceGeneration !== undefined
+      ? {
+          expectedWorkspaceInferenceGeneration: input.expectedWorkspaceInferenceGeneration,
+        }
+      : {}),
     ...(input.clientEventId ? { clientEventId: input.clientEventId } : {}),
   });
   await recordWorkspaceUsage(deps, {
@@ -997,18 +1238,31 @@ export async function updateSessionTitle(
   const { db, bus } = deps;
   const result = await updateSessionTitleRow(db, { workspaceId, sessionId, title, source });
   if (result.updated) {
-    await appendAndPublishEvents(db, bus, workspaceId, sessionId, [{
-      type: "session.title_set",
-      payload: {
-        title: result.title ?? title,
-        source,
+    await appendAndPublishEvents(db, bus, workspaceId, sessionId, [
+      {
+        type: "session.title_set",
+        payload: {
+          title: result.title ?? title,
+          source,
+        },
       },
-    }]);
+    ]);
   }
   return result;
 }
 
-function withFirstPartyTools(tools: ToolRef[], runtimeSettings: { mcpServers: Array<{ id: string }> }): ToolRef[] {
+export async function readSessionLineage(db: Database, workspaceId: string, sessionId: string) {
+  const lineage = await getSessionLineage(db, workspaceId, sessionId);
+  if (!lineage) {
+    throw new HTTPException(404, { message: "session not found" });
+  }
+  return lineage;
+}
+
+function withFirstPartyTools(
+  tools: ToolRef[],
+  runtimeSettings: { mcpServers: Array<{ id: string }> },
+): ToolRef[] {
   if (!runtimeSettings.mcpServers.some((server) => server.id === "opengeni")) {
     return tools;
   }
@@ -1016,5 +1270,7 @@ function withFirstPartyTools(tools: ToolRef[], runtimeSettings: { mcpServers: Ar
 }
 
 function hasOwnProperty(value: unknown, key: string): boolean {
-  return Boolean(value && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, key));
+  return Boolean(
+    value && typeof value === "object" && Object.prototype.hasOwnProperty.call(value, key),
+  );
 }