@opengeni/db 0.22.2 → 0.23.0

package/src/index.ts

@@ -217,11 +217,25 @@ import {
   serializeEffectiveSessionControl,
   type SessionDiscoveryControl,
   type SessionCommandActor,
+  SessionControlConflictError,
   SessionControlInvariantError,
   updateSessionCommandReceiptResult,
   type SessionTurnAttemptOutcome,
   type WorkspaceControlRow,
 } from "./session-control";
+import {
+  sessionRealtimeIsActiveInTransaction,
+  settleExpiredSessionRealtimeInTransaction,
+} from "./session-realtime";
+import {
+  isSessionRealtimeDelegationTurnMetadata,
+  projectSessionRealtimeDelegationProgressInTransaction,
+  projectSessionRealtimeDelegationTerminalInTransaction,
+} from "./session-realtime-ledger";
+import {
+  listSessionRealtimeContinuityEntriesInTransaction,
+  type SessionRealtimeContinuityEntry,
+} from "./session-realtime-context";
 import * as schema from "./schema";
 import {
   AGENT_VISIBLE_MEMORY_STATUSES,
@@ -243,6 +257,9 @@ import {
 export { sql as dbSql } from "drizzle-orm";
 export * from "./session-control";
 export * from "./session-queue-commands";
+export * from "./session-realtime";
+export * from "./session-realtime-context";
+export * from "./session-realtime-ledger";
 export * from "./new-session-drafts";
 export * from "./workspace-instruction-policies";
 export * from "./preference-registry";
@@ -5388,6 +5405,7 @@ export type SlackBotUserLink = {
 export type SlackInteractionTriggerKind =
   | "app_mention"
   | "dm"
+  | "reaction"
   | "slash_command"
   | "message_shortcut"
   | "thread_reply";
@@ -5412,6 +5430,7 @@ export type SlackInteractionInboxEntry = {
   attemptCount: number;
   retryAt: Date | null;
   lastErrorCode: string | null;
+  reactionContextCheckpoint: unknown | null;
   processedAt: Date | null;
   createdAt: Date;
   updatedAt: Date;
@@ -5557,6 +5576,7 @@ export async function enqueueSlackInteractionInbox(
     | "attemptCount"
     | "retryAt"
     | "lastErrorCode"
+    | "reactionContextCheckpoint"
     | "processedAt"
     | "createdAt"
     | "updatedAt"
@@ -5619,6 +5639,7 @@ export async function settleSlackInteractionInbox(
         claimHolderId: null,
         claimExpiresAt: null,
         retryAt: null,
+        reactionContextCheckpoint: null,
         processedAt: sql`now()`,
         lastErrorCode: input.errorCode ?? null,
         updatedAt: sql`now()`,
@@ -5635,6 +5656,42 @@ export async function settleSlackInteractionInbox(
   });
 }
 
+export async function saveSlackInteractionInboxReactionCheckpoint(
+  db: Database,
+  input: {
+    entry: Pick<
+      SlackInteractionInboxEntry,
+      "id" | "accountId" | "workspaceId" | "connectionId" | "providerEventId" | "providerMessageId"
+    >;
+    claimHolderId: string;
+    checkpoint: unknown;
+  },
+): Promise<boolean> {
+  return await withRlsContext(db, input.entry, async (scopedDb) => {
+    const rows = await scopedDb
+      .update(schema.slackInteractionInbox)
+      .set({
+        reactionContextCheckpoint: input.checkpoint,
+        updatedAt: sql`now()`,
+      })
+      .where(
+        and(
+          eq(schema.slackInteractionInbox.id, input.entry.id),
+          eq(schema.slackInteractionInbox.accountId, input.entry.accountId),
+          eq(schema.slackInteractionInbox.workspaceId, input.entry.workspaceId),
+          eq(schema.slackInteractionInbox.connectionId, input.entry.connectionId),
+          eq(schema.slackInteractionInbox.providerEventId, input.entry.providerEventId),
+          eq(schema.slackInteractionInbox.providerMessageId, input.entry.providerMessageId),
+          eq(schema.slackInteractionInbox.triggerKind, "reaction"),
+          eq(schema.slackInteractionInbox.claimHolderId, input.claimHolderId),
+          eq(schema.slackInteractionInbox.status, "processing"),
+        ),
+      )
+      .returning({ id: schema.slackInteractionInbox.id });
+    return rows.length === 1;
+  });
+}
+
 export async function releaseSlackInteractionInbox(
   db: Database,
   input: {
@@ -5731,6 +5788,57 @@ export async function getSlackInteractionByRoute(
   });
 }
 
+/**
+ * Resolve an already-durable Slack task to its canonical interaction.
+ *
+ * Client event ids are unique only inside one session, so this lookup also
+ * fences the exact workspace and Slack connection. The reservation id is the
+ * canonical Slack session identity both before and after binding; joining it
+ * lets a retry repair a crash after the task committed but before the route was
+ * bound. Two matches indicate a cross-session collision and fail closed rather
+ * than choosing an arbitrary route.
+ */
+export async function getSlackInteractionByClientEventId(
+  db: Database,
+  workspaceId: string,
+  connectionId: string,
+  clientEventId: string,
+): Promise<{ interaction: SlackInteraction; eventSessionId: string } | null> {
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const rows = await scopedDb
+      .select({
+        interaction: schema.slackInteractions,
+        eventSessionId: schema.sessionEvents.sessionId,
+      })
+      .from(schema.slackInteractions)
+      .innerJoin(
+        schema.sessionEvents,
+        and(
+          eq(schema.sessionEvents.workspaceId, schema.slackInteractions.workspaceId),
+          eq(schema.sessionEvents.sessionId, schema.slackInteractions.sessionReservationId),
+        ),
+      )
+      .where(
+        and(
+          eq(schema.slackInteractions.workspaceId, workspaceId),
+          eq(schema.slackInteractions.connectionId, connectionId),
+          eq(schema.sessionEvents.clientEventId, clientEventId),
+          eq(schema.sessionEvents.type, "user.message"),
+        ),
+      )
+      .limit(2);
+    if (rows.length > 1) {
+      throw new Error("Slack client event id resolved to multiple canonical interactions");
+    }
+    const row = rows[0];
+    if (!row) return null;
+    return {
+      interaction: mapSlackInteraction(row.interaction),
+      eventSessionId: row.eventSessionId,
+    };
+  });
+}
+
 export async function getSlackInteractionSessionAccess(
   db: Database,
   workspaceId: string,
@@ -6178,6 +6286,8 @@ function mapSlackInteractionInbox(
     attemptCount: slackRowNumber(row, "attemptCount", "attempt_count"),
     retryAt: slackRowNullableDate(row, "retryAt", "retry_at"),
     lastErrorCode: slackRowNullableString(row, "lastErrorCode", "last_error_code"),
+    reactionContextCheckpoint:
+      slackRowValue(row, "reactionContextCheckpoint", "reaction_context_checkpoint") ?? null,
     processedAt: slackRowNullableDate(row, "processedAt", "processed_at"),
     createdAt: slackRowDate(row, "createdAt", "created_at"),
     updatedAt: slackRowDate(row, "updatedAt", "updated_at"),
@@ -16693,6 +16803,7 @@ export type SessionCreateInput = {
   firstPartyMcpPermissions?: Permission[] | null;
   firstPartyMcpTools?: FirstPartyMcpToolName[];
   instructions?: string | null;
+  policyRole?: string | null;
   parentSessionId?: string | null;
   createIdempotencyKey?: string | null;
   sandboxGroupId?: string | null;
@@ -16849,6 +16960,9 @@ async function resolveSessionDepthDecision(
     if (!parent) {
       throw new Error(`Parent session not found: ${parentSessionId}`);
     }
+    if (parent.status === "cancelled") {
+      throw new SessionControlConflictError("Cancelled session subtree cannot create children");
+    }
   }
 
   const currentParentDepth = parent?.nestedAgentDepth ?? 0;
@@ -17104,6 +17218,7 @@ async function createSessionInTransaction(
       firstPartyMcpTools: input.firstPartyMcpTools ?? [...DEFAULT_FIRST_PARTY_MCP_TOOLS],
       initialPersonalConnectionDelegations: input.personalConnectionDelegations ?? [],
       instructions: input.instructions ?? null,
+      policyRole: input.policyRole ?? null,
       parentSessionId: input.parentSessionId ?? null,
       parentTurnId,
       createIdempotencyKey,
@@ -21298,6 +21413,29 @@ export async function getActiveSessionHistoryItems(
   });
 }
 
+/** Bounded finalized voice turns used only to resume a later realtime call. */
+export async function getSessionRealtimeContinuityEntries(
+  db: Database,
+  workspaceId: string,
+  sessionId: string,
+  maximumEntries = 20,
+): Promise<SessionRealtimeContinuityEntry[]> {
+  return await withWorkspaceRls(db, workspaceId, async (scopedDb) => {
+    const [session] = await scopedDb
+      .select({ accountId: schema.sessions.accountId })
+      .from(schema.sessions)
+      .where(and(eq(schema.sessions.workspaceId, workspaceId), eq(schema.sessions.id, sessionId)))
+      .limit(1);
+    if (!session) return [];
+    return await listSessionRealtimeContinuityEntriesInTransaction(scopedDb, {
+      accountId: session.accountId,
+      workspaceId,
+      sessionId,
+      maximumEntries,
+    });
+  });
+}
+
 /**
  * Count of ACTIVE (live, model-facing) history rows for a session. This is the
  * length of the history the next turn is seeded from — the dual-write slice
@@ -36074,6 +36212,8 @@ export type InitializeSessionStartInput = {
     subjectId: string;
     expectedRevision: number;
   } | null;
+  /** Persist session.created only; realtime will supply the first human turn. */
+  deferInitialTurn?: boolean;
 };
 
 export type InitializeSessionStartResult = {
@@ -36159,6 +36299,95 @@ export async function initializeSessionStartAtomically(
           if (!goal) throw new Error("Failed to create initial session goal");
         }
 
+        if (input.deferInitialTurn) {
+          const [existingCreatedEvent] = await tx
+            .select({ id: schema.sessionEvents.id })
+            .from(schema.sessionEvents)
+            .where(
+              and(
+                eq(schema.sessionEvents.workspaceId, input.workspaceId),
+                eq(schema.sessionEvents.sessionId, session.id),
+                eq(schema.sessionEvents.type, "session.created"),
+              ),
+            )
+            .limit(1);
+          let sequence = session.lastSequence;
+          let initializedNow = false;
+          let insertedEvents: Array<typeof schema.sessionEvents.$inferSelect> = [];
+          if (!existingCreatedEvent) {
+            insertedEvents = await tx
+              .insert(schema.sessionEvents)
+              .values([
+                {
+                  accountId: session.accountId,
+                  workspaceId: input.workspaceId,
+                  sessionId: session.id,
+                  sequence: ++sequence,
+                  type: "session.created",
+                  payload: sanitizeEventPayload({
+                    ...input.createdEventPayload,
+                    status: "idle",
+                    createdBy: creator.initiator,
+                  }),
+                },
+                ...(goal
+                  ? [
+                      {
+                        accountId: session.accountId,
+                        workspaceId: input.workspaceId,
+                        sessionId: session.id,
+                        sequence: ++sequence,
+                        type: "goal.set" as const,
+                        payload: sanitizeEventPayload({
+                          goalId: goal.id,
+                          text: goal.text,
+                          ...(goal.successCriteria
+                            ? { successCriteria: goal.successCriteria }
+                            : {}),
+                          version: goal.version,
+                          actor: "api",
+                          replaced: false,
+                        }),
+                      },
+                    ]
+                  : []),
+              ])
+              .returning();
+            initializedNow = true;
+          }
+          await tx
+            .update(schema.sessions)
+            .set({
+              temporalWorkflowId,
+              lastSequence: sequence,
+              ...(initializedNow && session.status === "queued" ? { status: "idle" } : {}),
+              updatedAt: new Date(),
+            })
+            .where(
+              and(
+                eq(schema.sessions.workspaceId, input.workspaceId),
+                eq(schema.sessions.id, session.id),
+              ),
+            );
+          if (initializedNow && input.consumeNewSessionDraft) {
+            await setSubjectRlsContext(
+              tx as unknown as Database,
+              input.consumeNewSessionDraft.subjectId,
+            );
+            await seedNewSessionDraftInTransaction(tx as unknown as Database, {
+              workspaceId: input.workspaceId,
+              subjectId: input.consumeNewSessionDraft.subjectId,
+              expectedRevision: input.consumeNewSessionDraft.expectedRevision,
+            });
+          }
+          return {
+            events: insertedEvents.map(mapEvent),
+            turn: null,
+            temporalWorkflowId,
+            workflowWakeRevision: null,
+          };
+        }
+
         const existingUserEvents = await tx
           .select()
           .from(schema.sessionEvents)
@@ -36262,6 +36491,7 @@ export async function initializeSessionStartAtomically(
         let queueTailPosition = Number(session.queueTailPosition);
         if (!turn) {
           queueTailPosition += 1;
+          const acceptedAt = new Date();
           [turn] = await tx
             .insert(schema.sessionTurns)
             .values({
@@ -36293,10 +36523,14 @@ export async function initializeSessionStartAtomically(
                 : {},
               lineage: {},
               ...initiatorColumns(creator),
+              initiatingHumanSubjectId:
+                creator.initiator.kind === "subject" ? creator.initiator.subjectId : null,
               personalConnectionDelegations: parsedPersonalConnectionDelegations(
                 session.initialPersonalConnectionDelegations,
                 `sessions:${session.workspaceId}:${session.id}:initial`,
               ),
+              createdAt: acceptedAt,
+              updatedAt: acceptedAt,
             })
             .returning();
           if (!turn) throw new Error("Failed to create initial session turn");
@@ -36430,6 +36664,7 @@ export async function enqueueSessionTurn(
         const position = atHead
           ? Number(lockedSession.queueHeadPosition) - 1
           : Number(lockedSession.queueTailPosition) + 1;
+        const acceptedAt = new Date();
         const [row] = await tx
           .insert(schema.sessionTurns)
           .values({
@@ -36457,7 +36692,11 @@ export async function enqueueSessionTurn(
               initiator: input.initiator,
               context: input.initiatorContext ?? {},
             }),
+            initiatingHumanSubjectId:
+              input.initiator.kind === "subject" ? input.initiator.subjectId : null,
             personalConnectionDelegations: input.personalConnectionDelegations ?? [],
+            createdAt: acceptedAt,
+            updatedAt: acceptedAt,
           })
           .returning();
         if (!row) {
@@ -36893,8 +37132,14 @@ export async function claimSessionWorkForAttempt(
           sessionId,
           { workspaceControl },
         );
-        const session = prefix.sessions[0];
+        let session = prefix.sessions[0];
         if (!session) return { action: "unclaimed", reason: "no-work" };
+        // Work and realtime may coexist, but claim remains the lazy lifecycle
+        // cleanup point for an expired voice lease.
+        session = await settleExpiredSessionRealtimeInTransaction(
+          tx as unknown as Database,
+          session,
+        );
         if (effectiveControl.state !== "active") {
           return { action: "unclaimed", reason: "gate-closed" };
         }
@@ -36974,7 +37219,37 @@ export async function claimSessionWorkForAttempt(
           if (connectorPolicyRows.length > 2048) {
             throw new Error("Connector action policy snapshot exceeds the 2048-row bound");
           }
-          return await registerSessionTurnAttemptClaim(tx as unknown as Database, {
+          // New queued, compaction, and internal-update executions are born
+          // while the locked session still has no active-turn pointer. Publish
+          // that ownership edge before freezing governance so the database
+          // functions can require the complete exact-current-attempt chain.
+          // The enclosing transaction keeps this invisible unless every later
+          // claim/event/session settlement step succeeds.
+          if (session.activeTurnId !== turn.id) {
+            if (session.activeTurnId !== null) {
+              throw new SessionControlInvariantError(
+                `Attempt ${input.attemptId} cannot replace active turn ${session.activeTurnId}`,
+              );
+            }
+            const [claimedSession] = await tx
+              .update(schema.sessions)
+              .set({ activeTurnId: turn.id })
+              .where(
+                and(
+                  eq(schema.sessions.accountId, session.accountId),
+                  eq(schema.sessions.workspaceId, workspaceId),
+                  eq(schema.sessions.id, sessionId),
+                  isNull(schema.sessions.activeTurnId),
+                ),
+              )
+              .returning({ id: schema.sessions.id });
+            if (!claimedSession) {
+              throw new SessionControlInvariantError(
+                `Attempt ${input.attemptId} could not establish active turn ${turn.id}`,
+              );
+            }
+          }
+          const attempt = await registerSessionTurnAttemptClaim(tx as unknown as Database, {
             id: input.attemptId,
             accountId: session.accountId,
             workspaceId,
@@ -36988,6 +37263,42 @@ export async function claimSessionWorkForAttempt(
             mcpApprovalPolicies,
             connectorActionPolicies: connectorPolicyRows,
           });
+          // Freeze governance only after this exact attempt is durably claimed,
+          // while the claim transaction still owns the session/turn/attempt
+          // locks. Later policy or preference activation applies to a future
+          // attempt and can never move accepted queued/in-flight work.
+          await tx.execute(sql`
+            SELECT snapshot.id
+            FROM workspace_instruction_policy_get_or_create_snapshot(
+              ${session.accountId}::uuid,
+              ${workspaceId}::uuid,
+              ${sessionId}::uuid,
+              ${turn.id}::uuid,
+              ${input.attemptId}::uuid,
+              ${turn.executionGeneration}
+            ) snapshot
+          `);
+          const initiatingHumanSubjectId =
+            turn.initiatingHumanSubjectId ??
+            (turn.initiatorKind === "subject" ? turn.initiatorSubjectId : null);
+          if (initiatingHumanSubjectId) {
+            await tx.execute(sql`
+              SELECT snapshot.id
+              FROM preference_registry_get_or_create_snapshot(
+                ${session.accountId}::uuid,
+                ${workspaceId}::uuid,
+                ${sessionId}::uuid,
+                ${turn.id}::uuid,
+                ${input.attemptId}::uuid,
+                ${turn.executionGeneration}
+              ) snapshot
+            `);
+            // The preference function applies the immutable initiating human
+            // only transaction-locally. Clear it before the rest of claim
+            // settlement so no unrelated subject-scoped read inherits it.
+            await tx.execute(sql`SELECT set_config('opengeni.subject_id', '', true)`);
+          }
+          return attempt;
         };
         if (session.activeTurnId !== null) {
           const [activeTurnPreview] = await tx
@@ -37335,6 +37646,9 @@ export async function claimSessionWorkForAttempt(
                 latencyMode: schema.sessionTurns.latencyMode,
                 sandboxBackend: schema.sessionTurns.sandboxBackend,
                 sandboxOs: schema.sessionTurns.sandboxOs,
+                initiatingHumanSubjectId: schema.sessionTurns.initiatingHumanSubjectId,
+                initiatorKind: schema.sessionTurns.initiatorKind,
+                initiatorSubjectId: schema.sessionTurns.initiatorSubjectId,
               })
               .from(schema.sessionTurns)
               .where(
@@ -37384,8 +37698,15 @@ export async function claimSessionWorkForAttempt(
                   },
                 ),
                 ...initiatorColumns(compactionInitiator),
+                initiatingHumanSubjectId:
+                  latestStarted?.initiatingHumanSubjectId ??
+                  (latestStarted?.initiatorKind === "subject"
+                    ? latestStarted.initiatorSubjectId
+                    : null),
                 personalConnectionDelegations: [],
                 startedAt: now,
+                createdAt: now,
+                updatedAt: now,
               })
               .returning();
             if (!compactionTurn) throw new Error("Failed to create context compaction execution");
@@ -37634,6 +37955,9 @@ export async function claimSessionWorkForAttempt(
               tools: schema.sessionTurns.tools,
               sandboxBackend: schema.sessionTurns.sandboxBackend,
               sandboxOs: schema.sessionTurns.sandboxOs,
+              initiatingHumanSubjectId: schema.sessionTurns.initiatingHumanSubjectId,
+              initiatorKind: schema.sessionTurns.initiatorKind,
+              initiatorSubjectId: schema.sessionTurns.initiatorSubjectId,
             })
             .from(schema.sessionTurns)
             .where(
@@ -37668,6 +37992,39 @@ export async function claimSessionWorkForAttempt(
             typeof goalPolicy?.sandboxBackend === "string"
               ? goalPolicy.sandboxBackend
               : (latestStarted?.sandboxBackend ?? session.sandboxBackend);
+          let initiatingHumanSubjectId =
+            internalInitiator.initiator.kind === "subject"
+              ? internalInitiator.initiator.subjectId
+              : null;
+          if (!initiatingHumanSubjectId && routingGoalUpdate) {
+            const causalTurnIdValue =
+              routingGoalUpdate.lineage &&
+              typeof routingGoalUpdate.lineage === "object" &&
+              !Array.isArray(routingGoalUpdate.lineage)
+                ? (routingGoalUpdate.lineage as Record<string, unknown>).causalTurnId
+                : null;
+            const causalTurnId = typeof causalTurnIdValue === "string" ? causalTurnIdValue : null;
+            if (causalTurnId) {
+              const [causalTurn] = await tx
+                .select({
+                  initiatingHumanSubjectId: schema.sessionTurns.initiatingHumanSubjectId,
+                  initiatorKind: schema.sessionTurns.initiatorKind,
+                  initiatorSubjectId: schema.sessionTurns.initiatorSubjectId,
+                })
+                .from(schema.sessionTurns)
+                .where(
+                  and(
+                    eq(schema.sessionTurns.workspaceId, workspaceId),
+                    eq(schema.sessionTurns.sessionId, sessionId),
+                    eq(schema.sessionTurns.id, causalTurnId),
+                  ),
+                )
+                .limit(1);
+              initiatingHumanSubjectId =
+                causalTurn?.initiatingHumanSubjectId ??
+                (causalTurn?.initiatorKind === "subject" ? causalTurn.initiatorSubjectId : null);
+            }
+          }
           await tx.execute(sql`set local opengeni.session_inference_claim = '1'`);
           const [internalTurn] = await tx
             .insert(schema.sessionTurns)
@@ -37699,8 +38056,11 @@ export async function claimSessionWorkForAttempt(
                 { id: input.dispatchId, generation: 1, triggerEventId },
               ),
               ...initiatorColumns(internalInitiator),
+              initiatingHumanSubjectId,
               personalConnectionDelegations: internalPersonalConnectionDelegations,
               startedAt: now,
+              createdAt: now,
+              updatedAt: now,
             })
             .returning();
           if (!internalTurn) throw new Error("Failed to create internal update inference");
@@ -37820,13 +38180,28 @@ export async function claimSessionWorkForAttempt(
           }),
           producerCodexCredentialId: null,
         });
-        const delivered = await deliverPendingUpdates(
-          session.accountId,
-          row.id,
-          row.executionGeneration,
-          session.lastSequence + 1,
-          now,
-        );
+        const providerDelegatedTurn = isSessionRealtimeDelegationTurnMetadata(row.metadata);
+        // Cross-session updates are already projected through
+        // delegation.context.append. Keep them pending instead of consuming
+        // them as hidden context on the provider-delegated ordinary turn.
+        const delivered = providerDelegatedTurn
+          ? {
+              count: 0,
+              lastSequence: session.lastSequence,
+              triggerEventId: null,
+              historyItemId: null,
+              historyItem: null,
+              updates: [] as Array<typeof schema.sessionSystemUpdates.$inferSelect>,
+              events: [] as Array<typeof schema.sessionEvents.$inferInsert>,
+              event: null,
+            }
+          : await deliverPendingUpdates(
+              session.accountId,
+              row.id,
+              row.executionGeneration,
+              session.lastSequence + 1,
+              now,
+            );
         await persistDeliveredUpdateBatch(delivered, session.accountId, row.id);
         if (delivered.events.length > 0) {
           await tx.insert(schema.sessionEvents).values(delivered.events);
@@ -38400,15 +38775,23 @@ export async function settleSessionAttemptInterruptions(
         throw new Error(`Live interrupted attempt ${attemptId} lost its exact turn ownership`);
       }
 
-      const steer = interruptions.some((interruption) => interruption.kind === "steer");
-      const outcome: SessionTurnAttemptOutcome = steer ? "superseded" : "interrupted_recoverable";
-      const reason = steer
-        ? "steer"
-        : interruptions.some((interruption) => interruption.kind === "workspace_pause")
-          ? "workspace_pause"
-          : interruptions.some((interruption) => interruption.kind === "maintenance")
-            ? "maintenance"
-            : "session_pause";
+      const terminalCancel = session.status === "cancelled";
+      const steer =
+        !terminalCancel && interruptions.some((interruption) => interruption.kind === "steer");
+      const outcome: SessionTurnAttemptOutcome = terminalCancel
+        ? "cancelled"
+        : steer
+          ? "superseded"
+          : "interrupted_recoverable";
+      const reason = terminalCancel
+        ? "session_cancelled"
+        : steer
+          ? "steer"
+          : interruptions.some((interruption) => interruption.kind === "workspace_pause")
+            ? "workspace_pause"
+            : interruptions.some((interruption) => interruption.kind === "maintenance")
+              ? "maintenance"
+              : "session_pause";
       let sequence = session.lastSequence;
       const closedTools = await closePendingSessionToolCallsInTransaction(
         tx as unknown as Database,
@@ -38433,38 +38816,14 @@ export async function settleSessionAttemptInterruptions(
         outcome,
         closedAt: now,
       });
-      const eventValues: Array<typeof schema.sessionEvents.$inferInsert> = steer
+      const eventValues: Array<typeof schema.sessionEvents.$inferInsert> = terminalCancel
         ? [
             {
               accountId: session.accountId,
               workspaceId,
               sessionId,
               sequence: ++sequence,
-              type: "turn.superseded",
-              turnId: turn.id,
-              turnGeneration: turn.executionGeneration,
-              turnAttemptId: attemptId,
-              turnAssociation: "current",
-              payload: sanitizeEventPayload({ reason: "steer" }),
-              occurredAt: now,
-            },
-            {
-              accountId: session.accountId,
-              workspaceId,
-              sessionId,
-              sequence: ++sequence,
-              type: "session.status.changed",
-              payload: sanitizeEventPayload({ status: "queued" }),
-              occurredAt: now,
-            },
-          ]
-        : [
-            {
-              accountId: session.accountId,
-              workspaceId,
-              sessionId,
-              sequence: ++sequence,
-              type: "turn.recovery.requested",
+              type: "turn.cancelled",
               turnId: turn.id,
               turnGeneration: turn.executionGeneration,
               turnAttemptId: attemptId,
@@ -38472,50 +38831,101 @@ export async function settleSessionAttemptInterruptions(
               payload: sanitizeEventPayload({ reason }),
               occurredAt: now,
             },
-            {
-              accountId: session.accountId,
-              workspaceId,
-              sessionId,
-              sequence: ++sequence,
-              type: "session.status.changed",
-              turnId: turn.id,
-              turnGeneration: turn.executionGeneration,
-              turnAttemptId: attemptId,
-              turnAssociation: "current",
-              payload: sanitizeEventPayload({ status: "recovering" }),
-              occurredAt: now,
-            },
-          ];
+          ]
+        : steer
+          ? [
+              {
+                accountId: session.accountId,
+                workspaceId,
+                sessionId,
+                sequence: ++sequence,
+                type: "turn.superseded",
+                turnId: turn.id,
+                turnGeneration: turn.executionGeneration,
+                turnAttemptId: attemptId,
+                turnAssociation: "current",
+                payload: sanitizeEventPayload({ reason: "steer" }),
+                occurredAt: now,
+              },
+              {
+                accountId: session.accountId,
+                workspaceId,
+                sessionId,
+                sequence: ++sequence,
+                type: "session.status.changed",
+                payload: sanitizeEventPayload({ status: "queued" }),
+                occurredAt: now,
+              },
+            ]
+          : [
+              {
+                accountId: session.accountId,
+                workspaceId,
+                sessionId,
+                sequence: ++sequence,
+                type: "turn.recovery.requested",
+                turnId: turn.id,
+                turnGeneration: turn.executionGeneration,
+                turnAttemptId: attemptId,
+                turnAssociation: "current",
+                payload: sanitizeEventPayload({ reason }),
+                occurredAt: now,
+              },
+              {
+                accountId: session.accountId,
+                workspaceId,
+                sessionId,
+                sequence: ++sequence,
+                type: "session.status.changed",
+                turnId: turn.id,
+                turnGeneration: turn.executionGeneration,
+                turnAttemptId: attemptId,
+                turnAssociation: "current",
+                payload: sanitizeEventPayload({ status: "recovering" }),
+                occurredAt: now,
+              },
+            ];
       const eventRows = await tx.insert(schema.sessionEvents).values(eventValues).returning();
       await tx
         .update(schema.sessionTurns)
         .set(
-          steer
+          terminalCancel
             ? {
-                status: "superseded",
+                status: "cancelled",
                 activeAttemptId: null,
                 metadata: metadataWithoutTurnDispatchAttempt(turn.metadata),
+                cancelledBy: "system:session_cancelled",
+                cancelReason: reason,
                 version: turn.version + 1,
                 finishedAt: turn.finishedAt ?? now,
                 updatedAt: now,
               }
-            : {
-                status: "recovering",
-                activeAttemptId: null,
-                metadata: metadataWithoutTurnDispatchAttempt(turn.metadata),
-                cancelledBy: null,
-                cancelReason: null,
-                version: turn.version + 1,
-                finishedAt: null,
-                updatedAt: now,
-              },
+            : steer
+              ? {
+                  status: "superseded",
+                  activeAttemptId: null,
+                  metadata: metadataWithoutTurnDispatchAttempt(turn.metadata),
+                  version: turn.version + 1,
+                  finishedAt: turn.finishedAt ?? now,
+                  updatedAt: now,
+                }
+              : {
+                  status: "recovering",
+                  activeAttemptId: null,
+                  metadata: metadataWithoutTurnDispatchAttempt(turn.metadata),
+                  cancelledBy: null,
+                  cancelReason: null,
+                  version: turn.version + 1,
+                  finishedAt: null,
+                  updatedAt: now,
+                },
         )
         .where(eq(schema.sessionTurns.id, turn.id));
       await tx
         .update(schema.sessions)
         .set({
-          status: steer ? "queued" : "recovering",
-          activeTurnId: steer ? null : turn.id,
+          status: terminalCancel ? "cancelled" : steer ? "queued" : "recovering",
+          activeTurnId: terminalCancel || steer ? null : turn.id,
           lastSequence: sequence,
           updatedAt: now,
         })
@@ -39348,6 +39758,13 @@ export type ApplySessionTurnSettlementResult =
       activeTurnId: string | null;
     };
 
+export type ApplySessionTurnSettlementHooks = {
+  /** Test-only failure injection after terminal projection but before commit. */
+  afterRealtimeDelegationProjection?:
+    | ((projection: { entryId: string; turnId: string }) => void | Promise<void>)
+    | undefined;
+};
+
 function attemptOutcomeForTurnStatus(status: SessionTurnStatus): SessionTurnAttemptOutcome | null {
   switch (status) {
     case "completed":
@@ -39361,6 +39778,40 @@ function attemptOutcomeForTurnStatus(status: SessionTurnStatus): SessionTurnAtte
   }
 }
 
+type TerminalSessionTurnStatus = "completed" | "failed" | "cancelled" | "superseded";
+type TerminalSessionTurnEventType =
+  | "turn.completed"
+  | "turn.failed"
+  | "turn.cancelled"
+  | "turn.superseded";
+
+function terminalSessionTurnEventType(
+  status: TerminalSessionTurnStatus,
+): TerminalSessionTurnEventType {
+  switch (status) {
+    case "completed":
+      return "turn.completed";
+    case "failed":
+      return "turn.failed";
+    case "cancelled":
+      return "turn.cancelled";
+    case "superseded":
+      return "turn.superseded";
+  }
+}
+
+function isTerminalSessionTurnStatus(
+  status: SessionTurnStatus,
+): status is TerminalSessionTurnStatus {
+  return ["completed", "failed", "cancelled", "superseded"].includes(status);
+}
+
+function sessionEventPayloadRecord(payload: unknown): Record<string, unknown> {
+  return payload && typeof payload === "object" && !Array.isArray(payload)
+    ? (payload as Record<string, unknown>)
+    : {};
+}
+
 /**
  * Atomically append terminal/requires-action truth, update the exact turn, and
  * transition the owning session. A superseded dispatch or closed control gate
@@ -39371,6 +39822,7 @@ export async function applySessionTurnSettlement(
   db: Database,
   workspaceId: string,
   input: ApplySessionTurnSettlementInput,
+  hooks: ApplySessionTurnSettlementHooks = {},
 ): Promise<ApplySessionTurnSettlementResult> {
   const fromStatuses = input.fromStatuses ?? ["running", "requires_action"];
   const eventTypes = [
@@ -39799,11 +40251,37 @@ export async function applySessionTurnSettlement(
       });
       const inserted =
         values.length > 0 ? await tx.insert(schema.sessionEvents).values(values).returning() : [];
-      const terminal =
-        input.turnStatus === "completed" ||
-        input.turnStatus === "cancelled" ||
-        input.turnStatus === "failed" ||
-        input.turnStatus === "superseded";
+      const terminal = isTerminalSessionTurnStatus(input.turnStatus);
+      if (isTerminalSessionTurnStatus(input.turnStatus)) {
+        const terminalType = terminalSessionTurnEventType(input.turnStatus);
+        const persistedTerminal = inserted.find((event) => event.type === terminalType);
+        const projection = await projectSessionRealtimeDelegationTerminalInTransaction(
+          tx as unknown as Database,
+          {
+            accountId: session.accountId,
+            workspaceId,
+            sessionId: input.sessionId,
+            turnId: input.turnId,
+            turnStatus: input.turnStatus,
+            terminalEvent: {
+              type: terminalType,
+              payload: persistedTerminal
+                ? sessionEventPayloadRecord(persistedTerminal.payload)
+                : {
+                    code: "delegation_terminal_event_missing",
+                    error: `Delegated turn reached ${input.turnStatus} without its canonical terminal event.`,
+                  },
+            },
+            now,
+          },
+        );
+        if (projection) {
+          await hooks.afterRealtimeDelegationProjection?.({
+            entryId: projection.entry.id,
+            turnId: input.turnId,
+          });
+        }
+      }
       if (input.turnStatus === "running") {
         // Approval resume re-enters the same logical turn after a new fenced
         // dispatch has advanced its trigger. It is an authorized inference
@@ -40092,6 +40570,20 @@ export async function settleCodexCredentialLeaseLoss(
         if (!settlementEvent) {
           throw new Error("Codex lease-loss settlement did not persist its checkpoint event");
         }
+        if (!input.checkpointDurable) {
+          await projectSessionRealtimeDelegationTerminalInTransaction(tx as unknown as Database, {
+            accountId: input.accountId,
+            workspaceId: input.workspaceId,
+            sessionId: input.sessionId,
+            turnId: input.turnId,
+            turnStatus: "failed",
+            terminalEvent: {
+              type: "turn.failed",
+              payload: sessionEventPayloadRecord(settlementEvent.payload),
+            },
+            now,
+          });
+        }
 
         await tx
           .update(schema.sessionTurns)
@@ -40821,6 +41313,22 @@ export async function recoverSessionDispatch(
             },
           ])
           .returning();
+        const failedEvent = inserted.find((event) => event.type === "turn.failed");
+        if (!failedEvent) {
+          throw new Error("Worker-death exhaustion did not persist its terminal event");
+        }
+        await projectSessionRealtimeDelegationTerminalInTransaction(tx as unknown as Database, {
+          accountId: session.accountId,
+          workspaceId,
+          sessionId: input.sessionId,
+          turnId: turn.id,
+          turnStatus: "failed",
+          terminalEvent: {
+            type: "turn.failed",
+            payload: sessionEventPayloadRecord(failedEvent.payload),
+          },
+          now,
+        });
         await tx
           .update(schema.sessionTurns)
           .set({
@@ -41559,8 +42067,14 @@ export async function enqueueSessionWorkflowWakeIfRunnable(
           .for("update")
           .limit(1);
         if (!workspace || !session) throw new Error(`Session not found: ${input.sessionId}`);
+        const realtimeActive = await sessionRealtimeIsActiveInTransaction(
+          tx as unknown as Database,
+          input.workspaceId,
+          input.sessionId,
+        );
         const runnable =
           session.status !== "cancelled" &&
+          !realtimeActive &&
           session.activeTurnId === null &&
           effectiveControl.state === "active";
         return runnable
@@ -42053,7 +42567,13 @@ export async function addSessionSystemUpdateWithSourceMutation(
           .returning();
         if (!event) throw new Error("Failed to create system-update pending event");
         await mutateSource(tx as unknown as Database, event.id);
-        const shouldWake = session.activeTurnId === null && effectiveControl.state === "active";
+        const realtimeActive = await sessionRealtimeIsActiveInTransaction(
+          tx as unknown as Database,
+          input.workspaceId,
+          input.sessionId,
+        );
+        const shouldWake =
+          !realtimeActive && session.activeTurnId === null && effectiveControl.state === "active";
         const wake = shouldWake
           ? await registerInternalUpdateWakeInTransaction(tx as unknown as Database, {
               accountId: session.accountId,
@@ -42617,6 +43137,21 @@ export async function appendSessionEventsForTurnAttempt(
           };
         });
         const inserted = await tx.insert(schema.sessionEvents).values(values).returning();
+        if (fence.allowed) {
+          await projectSessionRealtimeDelegationProgressInTransaction(tx as unknown as Database, {
+            accountId: session.accountId,
+            workspaceId,
+            sessionId,
+            turnId,
+            events: inserted.map((event) => ({
+              id: event.id,
+              sequence: event.sequence,
+              type: event.type,
+              payload: event.payload,
+            })),
+            now,
+          });
+        }
         await tx
           .update(schema.sessions)
           .set({
@@ -43041,6 +43576,7 @@ function mapSession(
     title: row.title ?? null,
     titleSource: (row.titleSource as "user" | "agent" | null) ?? null,
     instructions: row.instructions ?? null,
+    policyRole: row.policyRole ?? null,
     resources: row.resources as ResourceRef[],
     skills: (row.skills as SessionSkill[]) ?? [],
     tools: row.tools as ToolRef[],