@opengeni/db 5.0.1 → 6.0.0

package/src/provision-roles.ts

@@ -540,6 +540,7 @@ async function grantAppRoleIfSchemaExists(
     "get_organization_administration_overview(uuid,text)",
     "get_workspace_kind(uuid,uuid)",
     "resolve_workspace_codex_subscription_source(uuid,uuid)",
+    "capture_legacy_codex_turn_sources(uuid,uuid)",
     "list_organization_workspace_ids(uuid)",
     "list_organization_codex_workspace_ids(uuid)",
     "organization_workspace_command(jsonb)",
@@ -588,6 +589,10 @@ async function grantAppRoleIfSchemaExists(
     .map(literal)
     .join(", ")}]`;
   const managedAuthSessionSetRoutines = `ARRAY[${[
+    "assert_managed_sign_in_recovery(text,text,uuid,jsonb)",
+    "replay_managed_sign_in_method(text,text,jsonb)",
+    "claim_managed_sign_in_notification(uuid,text,text,integer)",
+    "settle_managed_sign_in_notification(uuid,uuid,text)",
     "get_canonical_human_exact_login_binding(text,text)",
     "managed_auth_session_set_authority_state(text)",
     "managed_auth_session_set_snapshot(text,text,boolean,boolean,boolean)",
@@ -626,6 +631,9 @@ BEGIN
       EXECUTE format('GRANT EXECUTE ON FUNCTION %I.mcp_operation_command(jsonb,text,jsonb) TO %I', ${literal(schema)}, ${literal(role)});
     END IF;
     EXECUTE format('GRANT USAGE ON SCHEMA %I TO %I', ${literal(schema)}, ${literal(role)});
+    IF to_regprocedure('opengeni_private.codex_credential_serves_turn(uuid,uuid,uuid,uuid)') IS NOT NULL THEN
+      EXECUTE format('GRANT EXECUTE ON FUNCTION opengeni_private.codex_credential_serves_turn(uuid,uuid,uuid,uuid) TO %I', ${literal(role)});
+    END IF;
     EXECUTE format('REVOKE CREATE ON SCHEMA %I FROM %I', ${literal(schema)}, ${literal(role)});
     EXECUTE format('REVOKE ALL PRIVILEGES ON ALL TABLES IN SCHEMA %I FROM %I', ${literal(schema)}, ${literal(role)});
     FOREACH runtime_table IN ARRAY ${runtimeFullDmlTables} LOOP
@@ -1325,6 +1333,9 @@ BEGIN
         ${literal(role)}
       );
     END IF;
+    IF to_regprocedure(format('%I.mutate_managed_sign_in_method(text,text,jsonb)', ${literal(schema)})) IS NOT NULL THEN
+      EXECUTE format('GRANT EXECUTE ON FUNCTION %I.mutate_managed_sign_in_method(text,text,jsonb) TO %I', ${literal(schema)}, ${literal(role)});
+    END IF;
     FOREACH routine_signature IN ARRAY ${managedAuthSessionSetRoutines} LOOP
       IF to_regprocedure(format('%I.%s', ${literal(schema)}, routine_signature)) IS NOT NULL THEN
         EXECUTE format(
@@ -1716,6 +1727,10 @@ BEGIN
         ${literal(role)}
       );
     END IF;
+    IF to_regprocedure(format('%I.list_owned_connection_accounts(uuid,uuid)', ${literal(schema)})) IS NOT NULL THEN
+      EXECUTE format('REVOKE ALL ON FUNCTION %I.list_owned_connection_accounts(uuid,uuid) FROM PUBLIC', ${literal(schema)});
+      EXECUTE format('GRANT EXECUTE ON FUNCTION %I.list_owned_connection_accounts(uuid,uuid) TO %I', ${literal(schema)}, ${literal(role)});
+    END IF;
     IF to_regprocedure(format('%I.list_self_user_resource_authorities(uuid,uuid,text,uuid,integer)', ${literal(schema)}))
       IS NOT NULL THEN
       EXECUTE format('REVOKE ALL ON FUNCTION %I.list_self_user_resource_authorities(uuid) FROM PUBLIC', ${literal(schema)});
@@ -1733,29 +1748,9 @@ BEGIN
       EXECUTE format('REVOKE ALL ON FUNCTION %I.authorize_session_attempt_personal_resource_reads(uuid, uuid, uuid) FROM PUBLIC', ${literal(schema)});
       EXECUTE format('GRANT EXECUTE ON FUNCTION %I.authorize_session_attempt_personal_resource_reads(uuid, uuid, uuid) TO %I', ${literal(schema)}, ${literal(role)});
     END IF;
-    IF to_regprocedure(format('%I.issue_self_local_connection_use_grant(uuid,uuid,uuid,text,boolean)', ${literal(schema)}))
-      IS NOT NULL THEN
-      EXECUTE format('REVOKE ALL ON FUNCTION %I.issue_self_local_connection_use_grant(uuid, uuid, uuid, text, boolean) FROM PUBLIC', ${literal(schema)});
-      EXECUTE format('GRANT EXECUTE ON FUNCTION %I.issue_self_local_connection_use_grant(uuid, uuid, uuid, text, boolean) TO %I', ${literal(schema)}, ${literal(role)});
-    END IF;
-    IF to_regprocedure(format('%I.resolve_connection_use_authority(uuid,uuid,uuid,jsonb)', ${literal(schema)}))
-      IS NOT NULL THEN
-      EXECUTE format('REVOKE ALL ON FUNCTION %I.list_self_connection_authorities(uuid) FROM PUBLIC', ${literal(schema)});
-      EXECUTE format('REVOKE ALL ON FUNCTION %I.list_self_connection_authorities(uuid) FROM %I', ${literal(schema)}, ${literal(role)});
-      EXECUTE format('REVOKE ALL ON FUNCTION %I.issue_self_connection_use_grant(uuid, uuid, uuid, text, text, uuid, boolean) FROM PUBLIC', ${literal(schema)});
-      EXECUTE format('REVOKE ALL ON FUNCTION %I.issue_self_connection_use_grant(uuid, uuid, uuid, text, text, uuid, boolean) FROM %I', ${literal(schema)}, ${literal(role)});
-      EXECUTE format('REVOKE ALL ON FUNCTION %I.revoke_self_connection_use_grant(uuid, uuid) FROM PUBLIC', ${literal(schema)});
-      EXECUTE format('REVOKE ALL ON FUNCTION %I.revoke_self_connection_use_grant(uuid, uuid) FROM %I', ${literal(schema)}, ${literal(role)});
-      EXECUTE format('REVOKE ALL ON FUNCTION %I.resolve_connection_use_authority(uuid, uuid, uuid, jsonb) FROM PUBLIC', ${literal(schema)});
-      EXECUTE format('GRANT EXECUTE ON FUNCTION %I.resolve_connection_use_authority(uuid, uuid, uuid, jsonb) TO %I', ${literal(schema)}, ${literal(role)});
-      IF to_regprocedure(format('%I.resolve_personal_connection_authority_selection(uuid,uuid,text,uuid,jsonb)', ${literal(schema)})) IS NOT NULL THEN
-        EXECUTE format('REVOKE ALL ON FUNCTION %I.resolve_personal_connection_authority_selection(uuid, uuid, text, uuid, jsonb) FROM PUBLIC', ${literal(schema)});
-        EXECUTE format('GRANT EXECUTE ON FUNCTION %I.resolve_personal_connection_authority_selection(uuid, uuid, text, uuid, jsonb) TO %I', ${literal(schema)}, ${literal(role)});
-      END IF;
-      IF to_regprocedure(format('%I.resolve_accepted_connection_use(uuid,uuid,uuid,uuid,uuid,integer,uuid,text,text,uuid,text,text,text,text)', ${literal(schema)})) IS NOT NULL THEN
-        EXECUTE format('REVOKE ALL ON FUNCTION %I.resolve_accepted_connection_use(uuid, uuid, uuid, uuid, uuid, integer, uuid, text, text, uuid, text, text, text, text) FROM PUBLIC', ${literal(schema)});
-        EXECUTE format('GRANT EXECUTE ON FUNCTION %I.resolve_accepted_connection_use(uuid, uuid, uuid, uuid, uuid, integer, uuid, text, text, uuid, text, text, text, text) TO %I', ${literal(schema)}, ${literal(role)});
-      END IF;
+    IF to_regprocedure(format('%I.resolve_accepted_connection_use(uuid,uuid,uuid,uuid,uuid,integer,uuid,text,text,uuid,text,text,text,text)', ${literal(schema)})) IS NOT NULL THEN
+      EXECUTE format('REVOKE ALL ON FUNCTION %I.resolve_accepted_connection_use(uuid, uuid, uuid, uuid, uuid, integer, uuid, text, text, uuid, text, text, text, text) FROM PUBLIC', ${literal(schema)});
+      EXECUTE format('GRANT EXECUTE ON FUNCTION %I.resolve_accepted_connection_use(uuid, uuid, uuid, uuid, uuid, integer, uuid, text, text, uuid, text, text, text, text) TO %I', ${literal(schema)}, ${literal(role)});
     END IF;
     IF to_regprocedure(
       format('%I.get_self_personal_github_repository_selection(uuid,uuid,text,uuid)', ${literal(schema)})
@@ -1885,20 +1880,7 @@ BEGIN
         ${literal(schema)},
         ${literal(role)}
       );
-      IF to_regprocedure(
-        format(
-          '%I.refresh_scheduled_task_personal_resources_clone_connections(uuid,uuid,uuid,bigint,bigint)',
-          ${literal(schema)}
-        )
-      ) IS NOT NULL THEN
-        EXECUTE format(
-          'REVOKE ALL ON FUNCTION %I.refresh_scheduled_task_personal_resources_clone_connections(uuid, uuid, uuid, bigint, bigint) FROM PUBLIC',
-          ${literal(schema)}
-        );
-        EXECUTE format(
-          'GRANT EXECUTE ON FUNCTION %I.refresh_scheduled_task_personal_resources_clone_connections(uuid, uuid, uuid, bigint, bigint) TO %I',
-          ${literal(schema)}, ${literal(role)}
-        );
+      IF to_regprocedure(format('%I.create_scheduled_agent_run_with_admission(uuid,uuid,uuid,uuid,bigint,text,text,text,timestamp with time zone,timestamp with time zone,jsonb)', ${literal(schema)})) IS NOT NULL THEN
         EXECUTE format(
           'REVOKE ALL ON FUNCTION %I.create_scheduled_agent_run_with_admission(uuid, uuid, uuid, uuid, bigint, text, text, text, timestamp with time zone, timestamp with time zone, jsonb) FROM PUBLIC',
           ${literal(schema)}
@@ -2089,6 +2071,34 @@ BEGIN
     EXECUTE format('GRANT USAGE ON SCHEMA opengeni_private TO %I', ${literal(role)});
     EXECUTE format('REVOKE CREATE ON SCHEMA opengeni_private FROM %I', ${literal(role)});
     EXECUTE format('GRANT EXECUTE ON ALL FUNCTIONS IN SCHEMA opengeni_private TO %I', ${literal(role)});
+    IF to_regclass('opengeni_private.modal_inventory_read_capabilities') IS NOT NULL THEN
+      -- Inventory is the only capability mint. Reprovisioning must repair
+      -- accidental table and column grants, never expose its private ledger.
+      EXECUTE format('REVOKE ALL ON TABLE opengeni_private.modal_inventory_read_capabilities FROM %I', ${literal(role)});
+      EXECUTE format('REVOKE ALL (backend_pid, transaction_id, data_schema) ON TABLE opengeni_private.modal_inventory_read_capabilities FROM %I', ${literal(role)});
+      REVOKE ALL ON TABLE opengeni_private.modal_inventory_read_capabilities FROM PUBLIC;
+      REVOKE ALL (backend_pid, transaction_id, data_schema) ON TABLE opengeni_private.modal_inventory_read_capabilities FROM PUBLIC;
+      REVOKE ALL ON FUNCTION opengeni_private.list_live_modal_sandbox_leases() FROM PUBLIC;
+    END IF;
+    IF to_regclass('opengeni_private.sandbox_recovery_rollout') IS NOT NULL THEN
+      -- Migration may precede this role's creation. Converge only read access;
+      -- runtime identities and PUBLIC never receive recovery activation writes.
+      EXECUTE format('REVOKE ALL ON TABLE opengeni_private.sandbox_recovery_rollout FROM %I', ${literal(role)});
+      EXECUTE format('REVOKE ALL (singleton, consent_enabled, release_evidence) ON TABLE opengeni_private.sandbox_recovery_rollout FROM %I', ${literal(role)});
+      REVOKE ALL ON TABLE opengeni_private.sandbox_recovery_rollout FROM PUBLIC;
+      REVOKE ALL (singleton, consent_enabled, release_evidence) ON TABLE opengeni_private.sandbox_recovery_rollout FROM PUBLIC;
+      EXECUTE format('GRANT SELECT ON TABLE opengeni_private.sandbox_recovery_rollout TO %I', ${literal(role)});
+    END IF;
+    IF to_regclass('opengeni_private.organization_usage_read_capabilities') IS NOT NULL THEN
+      EXECUTE format('REVOKE ALL ON TABLE opengeni_private.organization_usage_read_capabilities FROM %I', ${literal(role)});
+      REVOKE ALL ON TABLE opengeni_private.organization_usage_read_capabilities FROM PUBLIC;
+      REVOKE ALL ON FUNCTION opengeni_private.organization_usage_summary(uuid,timestamptz,timestamptz,text,uuid,boolean) FROM PUBLIC;
+    END IF;
+    IF to_regclass('opengeni_private.session_file_attachments') IS NOT NULL THEN
+      EXECUTE format('REVOKE ALL ON TABLE opengeni_private.session_file_attachments, opengeni_private.session_file_read_capabilities FROM %I', ${literal(role)});
+      REVOKE ALL ON TABLE opengeni_private.session_file_attachments, opengeni_private.session_file_read_capabilities FROM PUBLIC;
+      REVOKE ALL ON FUNCTION opengeni_private.session_file_read_allowed(uuid,uuid,uuid), opengeni_private.accept_session_file_attachments(uuid,uuid,uuid,uuid,text,uuid[]), opengeni_private.read_session_file_attachments(uuid,uuid,uuid,integer,uuid[],jsonb) FROM PUBLIC;
+    END IF;
     IF to_regclass('opengeni_private.sandbox_file_publications') IS NOT NULL THEN
       EXECUTE format('REVOKE ALL ON TABLE opengeni_private.sandbox_file_publications FROM %I', ${literal(role)});
       REVOKE ALL ON TABLE opengeni_private.sandbox_file_publications FROM PUBLIC;
@@ -2096,6 +2106,9 @@ BEGIN
       REVOKE ALL ON FUNCTION opengeni_private.list_sandbox_file_publications(uuid,uuid,jsonb) FROM PUBLIC;
     END IF;
     FOREACH routine_signature IN ARRAY ARRAY[
+      'read_sender_connection(uuid,uuid,uuid,text)',
+      'validate_mcp_account_bindings(jsonb,jsonb)',
+      'fence_mcp_account_bindings()',
       'guard_mcp_operation_immutable()',
       'mcp_operation_command_scoped(jsonb,text,jsonb)',
       'guard_workspace_owned_skill_head_delete()',

package/src/retained-provider-commands.ts

@@ -1,10 +1,17 @@
-import { and, eq } from "drizzle-orm";
+import { and, eq, sql } from "drizzle-orm";
 import { isDeepStrictEqual } from "node:util";
-import { SandboxProviderCommand } from "@opengeni/contracts";
-import { withRlsContext, type Database } from "./database";
+import {
+  SandboxProviderCommand,
+  ModalRouterProviderCommand,
+  CommandSupervisionReceipt,
+  type SessionEvent,
+} from "@opengeni/contracts";
+import { withRlsContext, withSessionActivityRlsContext, type Database } from "./database";
+import { lockSessionEventWriteRows } from "./session-control";
+import { appendSessionCommandOutput } from "./session-command-output";
 import * as schema from "./schema";
 
-type ProcessScope = {
+export type ProcessScope = {
   accountId: string;
   workspaceId: string;
   sessionId: string;
@@ -12,12 +19,28 @@ type ProcessScope = {
 };
 
 /** Bound to an already-authorized exact process scope by runtime wiring. */
-export function retainedProviderCommandPersistence(db: Database, scope: ProcessScope) {
+export function retainedProviderCommandPersistence(
+  db: Database,
+  scope: ProcessScope,
+  publish?: (events: SessionEvent[]) => Promise<void>,
+) {
   return {
+    recordSupervisionReceipt: (receipt: SupervisionReceipt) =>
+      recordRetainedSupervisionReceipt(db, scope, receipt),
+    loadSupervisionReceipt: () => loadRetainedSupervisionReceipt(db, scope),
+    requestCancellation: (reason: "provider_deadline" | "explicit_stop") =>
+      requestRetainedProcessCancellation(db, scope, reason),
+    cancellationRequested: () => retainedProcessCancellationRequested(db, scope),
     load: () => getRetainedProviderCommand(db, scope),
     acknowledge: (command: SandboxProviderCommand) =>
       acknowledgeRetainedProviderOutput(db, scope, command),
-    reserveInput: () => reserveRetainedProviderInput(db, scope),
+    reserveInput: (byteLength?: number) => reserveRetainedProviderInput(db, scope, byteLength),
+    captureRouterPage: async (page: RetainedRouterOutputPage) => {
+      const result = await captureRetainedRouterOutput(db, scope, page);
+      // A committed capture is authoritative even if live fanout fails.
+      if (result.events.length && publish) await publish(result.events).catch(() => undefined);
+      return { command: result.command, captured: result.captured };
+    },
   };
 }
 
@@ -36,7 +59,8 @@ function sameExecution(a: SandboxProviderCommand, b: SandboxProviderCommand): bo
     a.sandboxId === b.sandboxId &&
     a.taskId === b.taskId &&
     a.execId === b.execId &&
-    Boolean(a.pty) === Boolean(b.pty)
+    Boolean(a.pty) === Boolean(b.pty) &&
+    isDeepStrictEqual(supervisionDescriptor(a), supervisionDescriptor(b))
   );
 }
 
@@ -110,6 +134,8 @@ export async function acknowledgeRetainedProviderOutput(
   candidate: SandboxProviderCommand,
 ): Promise<SandboxProviderCommand> {
   const next = SandboxProviderCommand.parse(candidate);
+  if (next.kind !== "modal-control-v1")
+    throw new Error("Byte-offset command output requires atomic capture");
   return withRlsContext(db, scope, async (tx) => {
     const [row] = await tx
       .select()
@@ -119,6 +145,8 @@ export async function acknowledgeRetainedProviderOutput(
       .limit(1);
     if (!row?.providerCommand) throw new Error("Retained provider command is unavailable");
     const previous = SandboxProviderCommand.parse(row.providerCommand);
+    if (previous.kind !== "modal-control-v1")
+      throw new Error("Legacy acknowledgment cannot advance byte-offset output");
     if (!sameExecution(previous, next))
       throw new Error("Output acknowledgment changed provider execution identity");
     const merged = structuredClone(previous);
@@ -141,11 +169,119 @@ export async function acknowledgeRetainedProviderOutput(
   });
 }
 
+export type RetainedRouterOutputPage = {
+  expected: ModalRouterProviderCommand;
+  command: ModalRouterProviderCommand;
+  stdout: string;
+  stderr: string;
+};
+
+export function validateRouterOutputAdvance(page: RetainedRouterOutputPage): void {
+  const before = ModalRouterProviderCommand.parse(page.expected);
+  const after = ModalRouterProviderCommand.parse(page.command);
+  if (!sameExecution(before, after)) throw new Error("Output capture changed execution identity");
+  for (const stream of ["stdout", "stderr"] as const) {
+    const oldCursor = before.streams[stream],
+      cursor = after.streams[stream];
+    if (
+      cursor.byteOffset < oldCursor.byteOffset ||
+      (oldCursor.eof && (!cursor.eof || cursor.byteOffset !== oldCursor.byteOffset)) ||
+      (oldCursor.exitCode !== null && !isDeepStrictEqual(oldCursor, cursor))
+    )
+      throw new Error("Output capture cannot regress or rewrite terminal evidence");
+    if (
+      cursor.byteOffset === oldCursor.byteOffset &&
+      !(!oldCursor.eof && cursor.eof) &&
+      (page[stream].length > 0 || cursor.utf8Remainder !== oldCursor.utf8Remainder)
+    )
+      throw new Error("Output without byte advancement requires the first EOF");
+    if (cursor.eof && cursor.utf8Remainder !== "")
+      throw new Error("EOF must flush pending UTF-8 bytes");
+    if (Buffer.byteLength(page[stream]) > 4 * 1024 * 1024)
+      throw new Error("Command output page exceeds its capture bound");
+  }
+}
+
+/** Capture and offsets commit atomically. The session lock is acquired before
+ * the process lock, matching the event-write lock order. A concurrent reader
+ * with a stale cursor discards its page and reloads; it never appends overlapping
+ * output or silently advances the other reader's cursor. */
+export async function captureRetainedRouterOutput(
+  db: Database,
+  scope: ProcessScope,
+  page: RetainedRouterOutputPage,
+): Promise<{ command: ModalRouterProviderCommand; events: SessionEvent[]; captured: boolean }> {
+  validateRouterOutputAdvance(page);
+  return await withSessionActivityRlsContext(db, scope, async (tx) => {
+    const locks = await lockSessionEventWriteRows(tx, {
+      workspaceId: scope.workspaceId,
+      sessionIds: [scope.sessionId],
+      controlLock: "share",
+    });
+    if (locks.sessions[0]?.accountId !== scope.accountId)
+      throw new Error("Command output session not found");
+    const [row] = await tx
+      .select()
+      .from(schema.sandboxRetainedProcesses)
+      .where(processWhere(scope))
+      .for("update")
+      .limit(1);
+    if (!row?.providerCommand || row.providerBackend !== "modal")
+      throw new Error("Retained provider command is unavailable");
+    const current = ModalRouterProviderCommand.parse(row.providerCommand);
+    if (!sameExecution(current, page.expected))
+      throw new Error("Output capture does not own this execution");
+    if (!isDeepStrictEqual(current, page.expected))
+      return { command: current, events: [], captured: false };
+    const events: SessionEvent[] = [];
+    for (const stream of ["stdout", "stderr"] as const) {
+      const before = current.streams[stream],
+        after = page.command.streams[stream];
+      if (page[stream])
+        events.push(
+          ...(await appendSessionCommandOutput(tx, {
+            ...scope,
+            commandId: scope.processId,
+            stream,
+            streamFidelity: current.pty ? "merged" : "separate",
+            chunkId: `modal-router:${current.execId}:${stream}:${before.byteOffset}:${after.byteOffset}:${after.eof ? 1 : 0}`,
+            chunk: page[stream],
+          })),
+        );
+    }
+    if (supervisionDescriptor(page.command)) {
+      await tx.execute(
+        sql`select set_config('opengeni.supervised_output_capture_process_id', ${scope.processId}, true)`,
+      );
+    }
+    await tx
+      .update(schema.sandboxRetainedProcesses)
+      .set({
+        providerCommand: page.command,
+        ...(supervisionDescriptor(page.command) &&
+        page.command.streams.stdout.eof &&
+        page.command.streams.stderr.eof &&
+        page.command.streams.stdout.exitCode === 0 &&
+        page.command.streams.stderr.exitCode === 0
+          ? { supervisionOutputCaptured: true }
+          : {}),
+      })
+      .where(processWhere(scope));
+    if (supervisionDescriptor(page.command)) {
+      await tx.execute(
+        sql`select set_config('opengeni.supervised_output_capture_process_id', '', true)`,
+      );
+    }
+    return { command: page.command, events, captured: true };
+  });
+}
+
 /** Reserve a strictly increasing provider stdin index before dispatch. An
  * ambiguous send consumes its index and is never silently replayed. */
 export async function reserveRetainedProviderInput(
   db: Database,
   scope: ProcessScope,
+  byteLength?: number,
 ): Promise<number> {
   return withRlsContext(db, scope, async (tx) => {
     const [row] = await tx
@@ -156,12 +292,153 @@ export async function reserveRetainedProviderInput(
       .limit(1);
     if (!row?.providerCommand || row.state !== "active")
       throw new Error("Active retained provider command is unavailable");
-    const index = row.providerCommandInputIndex + 1;
+    if (row.cancellationRequestedAt || row.supervisionReceipt)
+      throw new Error("Retained command input is closed");
+    const router = row.providerCommand.kind === "modal-router-v1";
+    if (router && (!Number.isSafeInteger(byteLength) || byteLength! <= 0))
+      throw new Error("Byte-offset stdin requires a positive byte reservation");
+    const index = row.providerCommandInputIndex + (router ? byteLength! : 1);
     if (!Number.isSafeInteger(index)) throw new Error("Provider stdin sequence exhausted");
     await tx
       .update(schema.sandboxRetainedProcesses)
       .set({ providerCommandInputIndex: index })
       .where(processWhere(scope));
-    return index;
+    return router ? row.providerCommandInputIndex : index;
+  });
+}
+
+export type SupervisionReceipt = CommandSupervisionReceipt;
+
+function supervisionDescriptor(command: SandboxProviderCommand) {
+  return command.kind === "modal-router-v1" ? command.supervision : undefined;
+}
+
+/** Fail before provider start, not after discovering an unprotected DB at retention. */
+export async function supervisedCommandProtocolReady(db: Database): Promise<boolean> {
+  const [row] = await db.execute<{ ready: boolean }>(sql`
+    select count(*) = 5 as ready from pg_catalog.pg_trigger
+    where (tgrelid, tgname) in (
+      ('sandbox_retained_processes'::regclass, 'supervised_command_guard'),
+      ('sandbox_retained_processes'::regclass, 'supervised_provider_loss_commit_guard'),
+      ('sandbox_workspace_mutation_admissions'::regclass, 'supervised_command_admission_guard'),
+      ('sandbox_lease_holders'::regclass, 'supervised_command_holder_guard'),
+      ('sandbox_leases'::regclass, 'supervised_command_capture_guard')
+    ) and tgenabled in ('O', 'A') and not tgisinternal
+  `);
+  return row?.ready === true;
+}
+
+/** Only an authenticated control-channel receipt; never parsed stdout/stderr.
+ * ACK the supervisor only after this transaction returns successfully. */
+export async function recordRetainedSupervisionReceipt(
+  db: Database,
+  scope: ProcessScope,
+  receipt: SupervisionReceipt,
+): Promise<void> {
+  const proof = CommandSupervisionReceipt.parse(receipt);
+  await withRlsContext(db, scope, async (tx) => {
+    const [row] = await tx
+      .select()
+      .from(schema.sandboxRetainedProcesses)
+      .where(processWhere(scope))
+      .for("update")
+      .limit(1);
+    if (!row?.providerCommand || !supervisionDescriptor(row.providerCommand))
+      throw new Error("Supervised retained command is unavailable");
+    // Trigger validates invocation binding, immutable replay and unsettled input.
+    await tx
+      .update(schema.sandboxRetainedProcesses)
+      .set({ supervisionReceipt: proof })
+      .where(processWhere(scope));
+  });
+}
+
+export async function loadRetainedSupervisionReceipt(
+  db: Database,
+  scope: ProcessScope,
+): Promise<SupervisionReceipt | null> {
+  return withRlsContext(db, scope, async (tx) => {
+    const [row] = await tx
+      .select({ receipt: schema.sandboxRetainedProcesses.supervisionReceipt })
+      .from(schema.sandboxRetainedProcesses)
+      .where(processWhere(scope))
+      .limit(1);
+    if (!row) throw new Error("Retained command is unavailable");
+    return row.receipt ? CommandSupervisionReceipt.parse(row.receipt) : null;
+  });
+}
+
+export async function requestRetainedProcessCancellation(
+  db: Database,
+  scope: ProcessScope,
+  reason: "provider_deadline" | "explicit_stop",
+): Promise<void> {
+  if (reason !== "provider_deadline" && reason !== "explicit_stop")
+    throw new Error("Invalid cancellation reason");
+  await withRlsContext(db, scope, async (tx) => {
+    const [row] = await tx
+      .select()
+      .from(schema.sandboxRetainedProcesses)
+      .where(processWhere(scope))
+      .for("update")
+      .limit(1);
+    if (!row) throw new Error("Retained command is unavailable");
+    if (row.cancellationRequestedAt || row.state !== "active") return;
+    await tx
+      .update(schema.sandboxRetainedProcesses)
+      .set({ cancellationRequestedAt: new Date(), cancellationReason: reason })
+      .where(processWhere(scope));
+  });
+}
+
+export async function retainedProcessCancellationRequested(
+  db: Database,
+  scope: ProcessScope,
+): Promise<boolean> {
+  return withRlsContext(db, scope, async (tx) => {
+    const [row] = await tx
+      .select({ at: schema.sandboxRetainedProcesses.cancellationRequestedAt })
+      .from(schema.sandboxRetainedProcesses)
+      .where(processWhere(scope))
+      .limit(1);
+    if (!row) throw new Error("Retained command is unavailable");
+    return row.at !== null;
+  });
+}
+
+/** Called by the reaper for an exact retained command. Ordinary completed turns
+ * are intentionally irrelevant. Lock order remains process -> lease. */
+export async function requestRetainedProcessDeadlineCancellation(
+  db: Database,
+  scope: ProcessScope,
+): Promise<boolean> {
+  return withRlsContext(db, scope, async (tx) => {
+    const [row] = await tx
+      .select()
+      .from(schema.sandboxRetainedProcesses)
+      .where(processWhere(scope))
+      .for("update")
+      .limit(1);
+    if (
+      !row ||
+      row.state !== "active" ||
+      !row.providerCommand ||
+      !supervisionDescriptor(row.providerCommand)
+    )
+      return false;
+    const [lease] = await tx.execute<{ id: string }>(sql`
+      select id from sandbox_leases where id = ${row.leaseId}
+        and account_id = ${row.accountId} and workspace_id = ${row.workspaceId}
+        and sandbox_group_id = ${row.sandboxGroupId} and lease_epoch = ${row.leaseEpoch}
+        and backend = ${row.providerBackend} and instance_id = ${row.providerInstanceId}
+        and rotation_requested_at is not null and rotation_reason = 'provider_deadline' for update
+    `);
+    if (!lease) return false;
+    if (!row.cancellationRequestedAt)
+      await tx
+        .update(schema.sandboxRetainedProcesses)
+        .set({ cancellationRequestedAt: new Date(), cancellationReason: "provider_deadline" })
+        .where(processWhere(scope));
+    return true;
   });
 }

package/src/retired-session-create-metadata.ts

@@ -0,0 +1,16 @@
+const key = "_opengeni_session_create_host_delegations_v1";
+
+/** New creates cannot write a retired authority-selection identity. */
+export function withoutRetiredSessionCreateMetadata(
+  metadata: Record<string, unknown>,
+): Record<string, unknown> {
+  const next = { ...metadata };
+  delete next[key];
+  return next;
+}
+
+/** Historical nonempty or malformed selections must not replay as native creates. */
+export function hasRetiredSessionCreateSelection(metadata: Record<string, unknown>): boolean {
+  const value = metadata[key];
+  return value != null && !(Array.isArray(value) && value.length === 0);
+}