@opengeni/db 0.31.1 → 0.36.1

package/src/browser-auth.ts

@@ -3,9 +3,13 @@ import {
   AuthRun,
   AuthRunListResponse,
   AuthRunMutationResponse,
+  BrowserExternalAuthResult,
   CreateInteractionInterventionRequest,
   CreateNetworkRouteRequest,
   CreateSiteAuthConnectionRequest,
+  ExternalAuthInteractiveRequest,
+  ExternalAuthRunRequest,
+  ExternalAuthRunResponse,
   InteractionIntervention,
   InteractionInterventionListResponse,
   InteractionInterventionMutationResponse,
@@ -14,7 +18,15 @@ import {
   NetworkRouteConsistency,
   NetworkRouteListResponse,
   NetworkRouteMutationResponse,
+  interactionPlacementsEqual,
+  networkRoutePlacementCompatibilityIssue,
+  ProtectedAuthFillRequest,
+  ProtectedAuthFillResponse,
   ReportAuthRunRequest,
+  RequestHumanInteractionToolInput,
+  SITE_AUTH_MAINTENANCE_CONNECTION_CONTEXT_KEY,
+  SITE_AUTH_MAINTENANCE_OPERATION_CONTEXT_KEY,
+  SiteAuthAuthority,
   ResolveInteractionInterventionRequest,
   SiteAuthConnection,
   SiteAuthConnectionListResponse,
@@ -22,12 +34,17 @@ import {
   StartAuthRunRequest,
   UpdateNetworkRouteRequest,
   UpdateSiteAuthConnectionRequest,
+  VerifyAuthRunRequest,
   type AuthRun as AuthRunValue,
   type AuthRunListResponse as AuthRunListResponseValue,
   type AuthRunMutationResponse as AuthRunMutationResponseValue,
   type CreateInteractionInterventionRequest as CreateInteractionInterventionRequestValue,
   type CreateNetworkRouteRequest as CreateNetworkRouteRequestValue,
   type CreateSiteAuthConnectionRequest as CreateSiteAuthConnectionRequestValue,
+  type BrowserExternalAuthResult as BrowserExternalAuthResultValue,
+  type ExternalAuthInteractiveRequest as ExternalAuthInteractiveRequestValue,
+  type ExternalAuthRunRequest as ExternalAuthRunRequestValue,
+  type ExternalAuthRunResponse as ExternalAuthRunResponseValue,
   type InteractionCredentialAuthorityRef,
   type InteractionIntervention as InteractionInterventionValue,
   type InteractionInterventionListResponse as InteractionInterventionListResponseValue,
@@ -36,18 +53,23 @@ import {
   type NetworkRouteConfiguration as NetworkRouteConfigurationValue,
   type NetworkRouteListResponse as NetworkRouteListResponseValue,
   type NetworkRouteMutationResponse as NetworkRouteMutationResponseValue,
+  type ProtectedAuthFillRequest as ProtectedAuthFillRequestValue,
+  type ProtectedAuthFillResponse as ProtectedAuthFillResponseValue,
   type ReportAuthRunRequest as ReportAuthRunRequestValue,
   type ResolveInteractionInterventionRequest as ResolveInteractionInterventionRequestValue,
-  type SiteAuthAuthority,
+  type RequestHumanInteractionToolInput as RequestHumanInteractionToolInputValue,
+  type SessionEvent,
+  type SiteAuthAuthority as SiteAuthAuthorityValue,
   type SiteAuthConnection as SiteAuthConnectionValue,
   type SiteAuthConnectionListResponse as SiteAuthConnectionListResponseValue,
   type SiteAuthConnectionMutationResponse as SiteAuthConnectionMutationResponseValue,
   type StartAuthRunRequest as StartAuthRunRequestValue,
   type UpdateNetworkRouteRequest as UpdateNetworkRouteRequestValue,
   type UpdateSiteAuthConnectionRequest as UpdateSiteAuthConnectionRequestValue,
+  type VerifyAuthRunRequest as VerifyAuthRunRequestValue,
 } from "@opengeni/contracts";
 import { and, asc, eq, inArray, sql } from "drizzle-orm";
-import { type Database, setSubjectRlsContext, withRlsContext } from "./database";
+import { type Database, rawRows, setSubjectRlsContext, withRlsContext } from "./database";
 import {
   advanceWorkspaceInteractionRevision,
   readWorkspaceInteractionRevision,
@@ -74,6 +96,7 @@ const CONSISTENT_READ = {
   isolationLevel: "repeatable read",
   accessMode: "read only",
 } as const;
+const MAX_SITE_AUTH_MAINTENANCE_RETRY_MS = 15 * 60 * 1_000;
 
 export class InteractionResourceNotFoundError extends Error {
   readonly name = "InteractionResourceNotFoundError";
@@ -148,6 +171,16 @@ function siteAuthConnectionFromRow(row: SiteAuthConnectionRow): SiteAuthConnecti
     verificationState: row.verificationState,
     lastVerifiedAt: row.lastVerifiedAt ? iso(row.lastVerifiedAt) : null,
     lastVerifiedUrl: row.lastVerifiedUrl,
+    lastCheckedAt: row.lastCheckedAt ? iso(row.lastCheckedAt) : null,
+    nextCheckAt: row.nextCheckAt ? iso(row.nextCheckAt) : null,
+    maintenance: row.maintenanceOperationId
+      ? {
+          action: row.maintenanceAction,
+          sessionId: row.maintenanceStartedAt ? row.maintenanceSessionId : null,
+          dueAt: iso(row.maintenanceDueAt!),
+          startedAt: row.maintenanceStartedAt ? iso(row.maintenanceStartedAt) : null,
+        }
+      : null,
     repairCode: row.repairCode,
     version: row.version,
     createdBySubjectId: row.createdBySubjectId,
@@ -156,6 +189,237 @@ function siteAuthConnectionFromRow(row: SiteAuthConnectionRow): SiteAuthConnecti
   });
 }
 
+function nextMaintainedAuthCheck(
+  status: SiteAuthConnectionRow["status"],
+  policy: SiteAuthConnectionRow["healthPolicy"],
+  lastCheckedAt: Date | null,
+): Date | null {
+  if (status !== "active" || policy.mode !== "maintained" || policy.intervalSeconds === null) {
+    return null;
+  }
+  return lastCheckedAt
+    ? new Date(lastCheckedAt.getTime() + policy.intervalSeconds * 1_000)
+    : new Date();
+}
+
+export type SiteAuthMaintenanceClaim = {
+  operationId: string;
+  sessionId: string;
+  accountId: string;
+  workspaceId: string;
+  siteAuthConnectionId: string;
+  connectionVersion: number;
+  action: "health_check" | "repair";
+  dueAt: Date;
+  claimedAt: Date;
+  name: string;
+  accountLabel: string;
+  loginUrl: string | null;
+  verificationUrlPrefixes: string[];
+  preferredIdentityId: string | null;
+  preferredPlacement: SiteAuthConnectionValue["preferredPlacement"];
+  preferredNetworkRouteId: string | null;
+  healthPolicy: SiteAuthConnectionValue["healthPolicy"];
+  verificationState: SiteAuthConnectionValue["verificationState"];
+};
+
+/** Claim a bounded cross-workspace batch. Stale pre-start claims keep the same
+ * operation/session ids, so worker loss repairs one durable dispatch. */
+export async function claimSiteAuthMaintenance(
+  db: Database,
+  input: { claimTimeoutMs: number; limit: number },
+): Promise<SiteAuthMaintenanceClaim[]> {
+  if (!Number.isSafeInteger(input.claimTimeoutMs) || input.claimTimeoutMs < 0) {
+    throw new Error("site auth maintenance claim timeout must be a non-negative safe integer");
+  }
+  if (!Number.isSafeInteger(input.limit) || input.limit < 1 || input.limit > 1_000) {
+    throw new Error("site auth maintenance claim limit must be between 1 and 1000");
+  }
+  const rows = await rawRows<{
+    operation_id: string;
+    session_id: string;
+    account_id: string;
+    workspace_id: string;
+    site_auth_connection_id: string;
+    connection_version: number;
+    action: "health_check" | "repair";
+    due_at: Date;
+    claimed_at: Date;
+    name: string;
+    account_label: string;
+    login_url: string | null;
+    verification_url_prefixes: string[];
+    preferred_identity_id: string | null;
+    preferred_placement: SiteAuthConnectionValue["preferredPlacement"];
+    preferred_network_route_id: string | null;
+    health_policy: SiteAuthConnectionValue["healthPolicy"];
+    verification_state: SiteAuthConnectionValue["verificationState"];
+  }>(
+    db,
+    sql`
+      select *
+      from opengeni_private.claim_site_auth_maintenance(
+        ${input.claimTimeoutMs},
+        ${input.limit}
+      )
+    `,
+  );
+  return rows.map((row) => ({
+    operationId: row.operation_id,
+    sessionId: row.session_id,
+    accountId: row.account_id,
+    workspaceId: row.workspace_id,
+    siteAuthConnectionId: row.site_auth_connection_id,
+    connectionVersion: Number(row.connection_version),
+    action: row.action,
+    dueAt: new Date(row.due_at),
+    claimedAt: new Date(row.claimed_at),
+    name: row.name,
+    accountLabel: row.account_label,
+    loginUrl: row.login_url,
+    verificationUrlPrefixes: row.verification_url_prefixes,
+    preferredIdentityId: row.preferred_identity_id,
+    preferredPlacement: row.preferred_placement,
+    preferredNetworkRouteId: row.preferred_network_route_id,
+    healthPolicy: row.health_policy,
+    verificationState: row.verification_state,
+  }));
+}
+
+/** Link the exact hidden maintenance claim to its service-created session in
+ * the caller's create transaction. A false result must abort that transaction. */
+export async function confirmSiteAuthMaintenanceSessionInTransaction(
+  tx: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    siteAuthConnectionId: string;
+    operationId: string;
+    sessionId: string;
+  },
+): Promise<boolean> {
+  const [session] = await tx
+    .select({
+      createdByKind: schema.sessions.createdByKind,
+      createdBySubjectId: schema.sessions.createdBySubjectId,
+      createdByContext: schema.sessions.createdByContext,
+    })
+    .from(schema.sessions)
+    .where(
+      and(
+        eq(schema.sessions.workspaceId, input.workspaceId),
+        eq(schema.sessions.id, input.sessionId),
+      ),
+    )
+    .limit(1);
+  if (
+    !session ||
+    session.createdByKind !== "service" ||
+    session.createdBySubjectId !== "site-auth-maintenance" ||
+    session.createdByContext[SITE_AUTH_MAINTENANCE_OPERATION_CONTEXT_KEY] !== input.operationId ||
+    session.createdByContext[SITE_AUTH_MAINTENANCE_CONNECTION_CONTEXT_KEY] !==
+      input.siteAuthConnectionId
+  ) {
+    return false;
+  }
+  const startedAt = new Date();
+  const [confirmed] = await tx
+    .update(schema.siteAuthConnections)
+    .set({
+      maintenanceStartedAt: startedAt,
+      version: sql`${schema.siteAuthConnections.version} + 1`,
+      updatedBySubjectId: "site-auth-maintenance",
+      updatedAt: startedAt,
+    })
+    .where(
+      and(
+        eq(schema.siteAuthConnections.workspaceId, input.workspaceId),
+        eq(schema.siteAuthConnections.id, input.siteAuthConnectionId),
+        eq(schema.siteAuthConnections.maintenanceOperationId, input.operationId),
+        eq(schema.siteAuthConnections.maintenanceSessionId, input.sessionId),
+        sql`${schema.siteAuthConnections.maintenanceStartedAt} is null`,
+      ),
+    )
+    .returning({ id: schema.siteAuthConnections.id });
+  if (!confirmed) {
+    const [existing] = await tx
+      .select({ startedAt: schema.siteAuthConnections.maintenanceStartedAt })
+      .from(schema.siteAuthConnections)
+      .where(
+        and(
+          eq(schema.siteAuthConnections.workspaceId, input.workspaceId),
+          eq(schema.siteAuthConnections.id, input.siteAuthConnectionId),
+          eq(schema.siteAuthConnections.maintenanceOperationId, input.operationId),
+          eq(schema.siteAuthConnections.maintenanceSessionId, input.sessionId),
+        ),
+      )
+      .limit(1);
+    return existing?.startedAt !== null && existing?.startedAt !== undefined;
+  }
+  await advanceWorkspaceInteractionRevision(tx, input.accountId, input.workspaceId);
+  return true;
+}
+
+/** Standalone wrapper retained for exact DB callers and tests. Session creation
+ * uses the in-transaction form so a changed claim cannot leave an empty shell. */
+export async function confirmSiteAuthMaintenanceSession(
+  db: Database,
+  input: Parameters<typeof confirmSiteAuthMaintenanceSessionInTransaction>[1],
+): Promise<boolean> {
+  return await withRlsContext(db, input, async (scopedDb) =>
+    confirmSiteAuthMaintenanceSessionInTransaction(scopedDb, input),
+  );
+}
+
+/** Release an exact claim that failed before a maintenance session started. */
+export async function deferSiteAuthMaintenance(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    siteAuthConnectionId: string;
+    operationId: string;
+    sessionId: string;
+    retryAt: Date;
+  },
+): Promise<boolean> {
+  return await withRlsContext(db, input, async (scopedDb) =>
+    scopedDb.transaction(async (tx) => {
+      const [deferred] = await tx
+        .update(schema.siteAuthConnections)
+        .set({
+          maintenanceOperationId: null,
+          maintenanceAction: null,
+          maintenanceDueAt: null,
+          maintenanceClaimedAt: null,
+          maintenanceSessionId: null,
+          maintenanceStartedAt: null,
+          nextCheckAt: input.retryAt,
+          version: sql`${schema.siteAuthConnections.version} + 1`,
+          updatedBySubjectId: "site-auth-maintenance",
+          updatedAt: new Date(),
+        })
+        .where(
+          and(
+            eq(schema.siteAuthConnections.workspaceId, input.workspaceId),
+            eq(schema.siteAuthConnections.id, input.siteAuthConnectionId),
+            eq(schema.siteAuthConnections.maintenanceOperationId, input.operationId),
+            eq(schema.siteAuthConnections.maintenanceSessionId, input.sessionId),
+            sql`${schema.siteAuthConnections.maintenanceStartedAt} is null`,
+          ),
+        )
+        .returning({ id: schema.siteAuthConnections.id });
+      if (!deferred) return false;
+      await advanceWorkspaceInteractionRevision(
+        tx as unknown as Database,
+        input.accountId,
+        input.workspaceId,
+      );
+      return true;
+    }),
+  );
+}
+
 async function lockOperation(db: Database, operationId: string): Promise<void> {
   await db.execute(
     sql`select pg_advisory_xact_lock(hashtextextended(${`interaction-resource:${operationId}`}, 0))`,
@@ -180,7 +444,7 @@ async function loadOperation(
   return row ?? null;
 }
 
-function assertOperation(
+function assertOperationIdentity(
   operation: ResourceOperationRow,
   expected: {
     resourceKind: ResourceKind;
@@ -201,6 +465,19 @@ function assertOperation(
       "Operation id is already bound to another interaction request",
     );
   }
+}
+
+function assertOperation(
+  operation: ResourceOperationRow,
+  expected: {
+    resourceKind: ResourceKind;
+    resourceId?: string;
+    kind: ResourceOperationKind;
+    requestDigest: string;
+    actorSubjectId: string;
+  },
+): void {
+  assertOperationIdentity(operation, expected);
   if (operation.state !== "completed" || !operation.result || !operation.resultVersion) {
     throw new InteractionResourceStateError("Interaction operation is not complete");
   }
@@ -250,7 +527,7 @@ function credentialRefsFromRoute(
 }
 
 function credentialRefsFromAuthorities(
-  authorities: readonly SiteAuthAuthority[],
+  authorities: readonly SiteAuthAuthorityValue[],
 ): InteractionCredentialAuthorityRef[] {
   return authorities.flatMap((authority) =>
     "credential" in authority && authority.credential ? [authority.credential] : [],
@@ -329,19 +606,74 @@ async function assertActiveNetworkRoute(
   db: Database,
   workspaceId: string,
   routeId: string | null,
-): Promise<void> {
-  if (!routeId) return;
+): Promise<NetworkRouteValue | null> {
+  if (!routeId) return null;
   const [route] = await db
-    .select({ status: schema.networkRoutes.status })
+    .select()
     .from(schema.networkRoutes)
     .where(
       and(eq(schema.networkRoutes.workspaceId, workspaceId), eq(schema.networkRoutes.id, routeId)),
     )
+    .for("share")
     .limit(1);
   if (!route) throw new InteractionResourceNotFoundError("Preferred network route not found");
   if (route.status !== "active") {
     throw new InteractionResourceStateError("Preferred network route is archived");
   }
+  return routeFromRow(route);
+}
+
+async function assertNetworkRouteUpdateCompatibleWithSiteAuthConnections(
+  db: Database,
+  input: {
+    workspaceId: string;
+    routeId: string;
+    status: NetworkRouteValue["status"];
+    configuration: NetworkRouteValue["configuration"];
+    consistency: NetworkRouteValue["consistency"];
+  },
+): Promise<void> {
+  const references = await db
+    .select({ preferredPlacement: schema.siteAuthConnections.preferredPlacement })
+    .from(schema.siteAuthConnections)
+    .where(
+      and(
+        eq(schema.siteAuthConnections.workspaceId, input.workspaceId),
+        eq(schema.siteAuthConnections.preferredNetworkRouteId, input.routeId),
+        eq(schema.siteAuthConnections.status, "active"),
+      ),
+    );
+  if (references.length === 0) return;
+  if (input.status !== "active") {
+    throw new InteractionResourceStateError(
+      "Network route is selected by an active site auth connection",
+    );
+  }
+  for (const reference of references) {
+    const issue = networkRoutePlacementCompatibilityIssue(
+      input.configuration,
+      input.consistency,
+      reference.preferredPlacement,
+    );
+    if (issue) {
+      throw new InteractionResourceStateError(
+        `Network route update is incompatible with an active site auth connection: ${issue}`,
+      );
+    }
+  }
+}
+
+function assertSiteAuthRouteCompatibility(
+  route: NetworkRouteValue | null,
+  placement: SiteAuthConnectionValue["preferredPlacement"],
+): void {
+  if (!route) return;
+  const issue = networkRoutePlacementCompatibilityIssue(
+    route.configuration,
+    route.consistency,
+    placement,
+  );
+  if (issue) throw new InteractionResourceStateError(`Preferred network route: ${issue}`);
 }
 
 export async function listNetworkRoutes(
@@ -481,7 +813,9 @@ export async function createNetworkRoute(
 
 export async function updateNetworkRoute(
   db: Database,
-  input: InteractionMutationScope & { routeId: string } & UpdateNetworkRouteRequestValue,
+  input: InteractionMutationScope & {
+    routeId: string;
+  } & UpdateNetworkRouteRequestValue,
 ): Promise<NetworkRouteMutationResponseValue> {
   const request = UpdateNetworkRouteRequest.parse({
     operationId: input.operationId,
@@ -542,6 +876,19 @@ export async function updateNetworkRoute(
           credentialRefsFromRoute(configuration),
         ),
       );
+      if (
+        request.configuration !== undefined ||
+        request.consistency !== undefined ||
+        (request.status !== undefined && request.status !== current.status)
+      ) {
+        await assertNetworkRouteUpdateCompatibleWithSiteAuthConnections(scopedDb, {
+          workspaceId: input.workspaceId,
+          routeId: input.routeId,
+          status: request.status ?? current.status,
+          configuration,
+          consistency,
+        });
+      }
       const [row] = await scopedDb
         .update(schema.networkRoutes)
         .set({
@@ -620,7 +967,11 @@ export async function listSiteAuthConnections(
 
 export async function getSiteAuthConnection(
   db: Database,
-  input: { accountId: string; workspaceId: string; siteAuthConnectionId: string },
+  input: {
+    accountId: string;
+    workspaceId: string;
+    siteAuthConnectionId: string;
+  },
 ): Promise<SiteAuthConnectionValue> {
   return await withRlsContext(
     db,
@@ -648,7 +999,7 @@ async function validateSiteAuthReferences(
   workspaceId: string,
   connection: Pick<
     SiteAuthConnectionValue,
-    "authorities" | "preferredIdentityId" | "preferredNetworkRouteId"
+    "authorities" | "preferredIdentityId" | "preferredNetworkRouteId" | "preferredPlacement"
   >,
 ): Promise<void> {
   await assertCredentialAuthorities(
@@ -657,7 +1008,8 @@ async function validateSiteAuthReferences(
     credentialRefsFromAuthorities(connection.authorities),
   );
   await assertActiveBrowserIdentity(db, workspaceId, connection.preferredIdentityId);
-  await assertActiveNetworkRoute(db, workspaceId, connection.preferredNetworkRouteId);
+  const route = await assertActiveNetworkRoute(db, workspaceId, connection.preferredNetworkRouteId);
+  assertSiteAuthRouteCompatibility(route, connection.preferredPlacement);
 }
 
 async function validateSiteAuthUpdateReferences(
@@ -677,8 +1029,21 @@ async function validateSiteAuthUpdateReferences(
   if (candidate.preferredIdentityId !== current.preferredIdentityId) {
     await assertActiveBrowserIdentity(db, workspaceId, candidate.preferredIdentityId);
   }
-  if (candidate.preferredNetworkRouteId !== current.preferredNetworkRouteId) {
-    await assertActiveNetworkRoute(db, workspaceId, candidate.preferredNetworkRouteId);
+  if (
+    candidate.status === "active" &&
+    (current.status !== "active" ||
+      candidate.preferredNetworkRouteId !== current.preferredNetworkRouteId ||
+      (candidate.preferredPlacement === null) !== (current.preferredPlacement === null) ||
+      (candidate.preferredPlacement !== null &&
+        current.preferredPlacement !== null &&
+        !interactionPlacementsEqual(candidate.preferredPlacement, current.preferredPlacement)))
+  ) {
+    const route = await assertActiveNetworkRoute(
+      db,
+      workspaceId,
+      candidate.preferredNetworkRouteId,
+    );
+    assertSiteAuthRouteCompatibility(route, candidate.preferredPlacement);
   }
 }
 
@@ -725,6 +1090,7 @@ export async function createSiteAuthConnection(
       await validateSiteAuthReferences(scopedDb, input.workspaceId, {
         authorities: request.authorities,
         preferredIdentityId: request.preferredIdentityId,
+        preferredPlacement: request.preferredPlacement,
         preferredNetworkRouteId: request.preferredNetworkRouteId,
       });
       const id = randomUUID();
@@ -745,6 +1111,7 @@ export async function createSiteAuthConnection(
           preferredPlacement: request.preferredPlacement,
           preferredNetworkRouteId: request.preferredNetworkRouteId,
           healthPolicy: request.healthPolicy,
+          nextCheckAt: nextMaintainedAuthCheck("active", request.healthPolicy, null),
           createOperationId: request.operationId,
           createdBySubjectId: input.actorSubjectId,
           updatedBySubjectId: input.actorSubjectId,
@@ -860,6 +1227,10 @@ export async function updateSiteAuthConnection(
       const candidate = SiteAuthConnection.parse({
         ...currentValue,
         ...candidatePatch,
+        // Any configuration change invalidates the scheduler's frozen prompt.
+        // The already-created session remains auditable but can no longer bind
+        // a maintenance AuthRun to this connection.
+        maintenance: null,
         id: current.id,
         accountId: current.accountId,
         workspaceId: current.workspaceId,
@@ -884,6 +1255,17 @@ export async function updateSiteAuthConnection(
           preferredPlacement: candidate.preferredPlacement,
           preferredNetworkRouteId: candidate.preferredNetworkRouteId,
           healthPolicy: candidate.healthPolicy,
+          nextCheckAt: nextMaintainedAuthCheck(
+            candidate.status,
+            candidate.healthPolicy,
+            current.lastCheckedAt,
+          ),
+          maintenanceOperationId: null,
+          maintenanceAction: null,
+          maintenanceDueAt: null,
+          maintenanceClaimedAt: null,
+          maintenanceSessionId: null,
+          maintenanceStartedAt: null,
           version: candidate.version,
           updatedBySubjectId: input.actorSubjectId,
           updatedAt: sql`now()`,
@@ -940,6 +1322,7 @@ function authRunFromRow(row: AuthRunRow): AuthRunValue {
     controllerGeneration: row.controllerGeneration,
     targetGeneration: row.targetGeneration,
     documentGeneration: row.documentGeneration,
+    purpose: row.purpose,
     methodId: row.methodId,
     authorityId: row.authorityId,
     state: row.state,
@@ -958,6 +1341,111 @@ function authRunFromRow(row: AuthRunRow): AuthRunValue {
   });
 }
 
+/**
+ * Project only terminal authentication evidence. `healthSequence` is allocated
+ * by PostgreSQL when a run starts, so an older browser may finish later without
+ * overwriting evidence from a newer run. A cancelled run carries no evidence.
+ */
+async function projectSettledAuthRunHealth(
+  db: Database,
+  input: { run: AuthRunRow; actorSubjectId: string },
+): Promise<boolean> {
+  const { run } = input;
+  if (!run.settledAt) return false;
+  const carriesEvidence = run.state === "verified" || run.state === "failed";
+  if (!carriesEvidence && (run.state !== "cancelled" || !run.maintenanceOperationId)) {
+    return false;
+  }
+  const [connection] = await db
+    .select()
+    .from(schema.siteAuthConnections)
+    .where(
+      and(
+        eq(schema.siteAuthConnections.workspaceId, run.workspaceId),
+        eq(schema.siteAuthConnections.id, run.siteAuthConnectionId),
+      ),
+    )
+    .for("update")
+    .limit(1);
+  if (!connection) throw new InteractionResourceNotFoundError("Site auth connection not found");
+  const checkedAt = run.settledAt;
+  const maintenanceMatches =
+    run.maintenanceOperationId !== null &&
+    connection.maintenanceOperationId === run.maintenanceOperationId;
+  const evidenceAdvances =
+    carriesEvidence &&
+    connection.healthSequence < run.healthSequence &&
+    (run.maintenanceOperationId === null || maintenanceMatches);
+  if (!maintenanceMatches && !evidenceAdvances) return false;
+  const intervalSeconds = connection.healthPolicy.intervalSeconds;
+  const nextEvidenceCheckAt =
+    connection.status === "active" &&
+    connection.healthPolicy.mode === "maintained" &&
+    intervalSeconds !== null
+      ? run.state === "failed" &&
+        run.purpose === "health_check" &&
+        connection.healthPolicy.automaticRepair
+        ? checkedAt
+        : new Date(checkedAt.getTime() + intervalSeconds * 1_000)
+      : null;
+  const failureState = run.purpose === "repair" ? "failed" : "needs_repair";
+  const cancelledMaintenanceCheckAt =
+    connection.status === "active" &&
+    connection.healthPolicy.mode === "maintained" &&
+    intervalSeconds !== null
+      ? new Date(
+          checkedAt.getTime() +
+            Math.min(intervalSeconds * 1_000, MAX_SITE_AUTH_MAINTENANCE_RETRY_MS),
+        )
+      : null;
+  const [projected] = await db
+    .update(schema.siteAuthConnections)
+    .set({
+      ...(evidenceAdvances
+        ? {
+            verificationState: run.state === "verified" ? "verified" : failureState,
+            ...(run.state === "verified"
+              ? {
+                  lastVerifiedAt: checkedAt,
+                  lastVerifiedUrl: run.verifiedUrl,
+                  repairCode: null,
+                }
+              : { repairCode: run.failureCode }),
+            lastCheckedAt: checkedAt,
+            nextCheckAt: nextEvidenceCheckAt,
+            healthSequence: run.healthSequence,
+          }
+        : maintenanceMatches && run.state === "cancelled"
+          ? { nextCheckAt: cancelledMaintenanceCheckAt }
+          : {}),
+      ...(maintenanceMatches
+        ? {
+            maintenanceOperationId: null,
+            maintenanceAction: null,
+            maintenanceDueAt: null,
+            maintenanceClaimedAt: null,
+            maintenanceSessionId: null,
+            maintenanceStartedAt: null,
+          }
+        : {}),
+      version: sql`${schema.siteAuthConnections.version} + 1`,
+      updatedBySubjectId: input.actorSubjectId,
+      updatedAt: checkedAt,
+    })
+    .where(
+      and(
+        eq(schema.siteAuthConnections.workspaceId, run.workspaceId),
+        eq(schema.siteAuthConnections.id, run.siteAuthConnectionId),
+        sql`(
+          ${schema.siteAuthConnections.healthSequence} < ${run.healthSequence}
+          or ${schema.siteAuthConnections.maintenanceOperationId} = ${run.maintenanceOperationId}
+        )`,
+      ),
+    )
+    .returning({ id: schema.siteAuthConnections.id });
+  return Boolean(projected);
+}
+
 async function loadAuthRunRow(
   db: Database,
   workspaceId: string,
@@ -1040,6 +1528,274 @@ const AUTH_RUN_TRANSITIONS: Readonly<
   cancelled: new Set(),
 };
 
+type ProtectedAuthOperationMetadata = {
+  schemaVersion: 1;
+  authRunVersion: number;
+  authority: SiteAuthAuthorityValue;
+  origins: string[];
+  fields: Array<{
+    id: string;
+    purpose: "identifier" | "password" | "secret" | "totp";
+  }>;
+  credentialVersion: number | null;
+};
+
+type ExternalAuthOperationMetadata = {
+  schemaVersion: 1;
+  authRunVersion: number;
+  authority: Extract<SiteAuthAuthorityValue, { kind: "external_provider" }>;
+};
+
+export type ExternalAuthPreparation = {
+  run: AuthRunValue;
+  authority: ExternalAuthOperationMetadata["authority"];
+  operationState: ResourceOperationRow["state"];
+  response: ExternalAuthRunResponseValue | null;
+  replayed: boolean;
+};
+
+export type ProtectedAuthFillPreparation = {
+  run: AuthRunValue;
+  authority: SiteAuthAuthorityValue;
+  origins: string[];
+  credentialVersion: number | null;
+  operationState: ResourceOperationRow["state"];
+  response: ProtectedAuthFillResponseValue | null;
+  replayed: boolean;
+};
+
+function protectedAuthFillDigest(
+  authRunId: string,
+  request: ProtectedAuthFillRequestValue,
+  actorSubjectId: string,
+): string {
+  const { operationId: _operationId, ...digestRequest } = request;
+  return operationDigest({
+    version: 1,
+    authRunId,
+    request: digestRequest,
+    actorSubjectId,
+  });
+}
+
+function parseExternalAuthRunRequest(
+  input: ExternalAuthRunRequestValue,
+): ExternalAuthRunRequestValue {
+  return ExternalAuthRunRequest.parse({
+    operationId: input.operationId,
+    expectedVersion: input.expectedVersion,
+    action: input.action,
+  });
+}
+
+function externalAuthDigest(
+  authRunId: string,
+  request: ExternalAuthRunRequestValue,
+  actorSubjectId: string,
+): string {
+  const { operationId: _operationId, ...digestRequest } = request;
+  return operationDigest({
+    version: 1,
+    authRunId,
+    request: digestRequest,
+    actorSubjectId,
+  });
+}
+
+function externalAuthOperationMetadata(value: unknown): ExternalAuthOperationMetadata {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new InteractionResourceStateError("External-auth operation metadata is invalid");
+  }
+  const record = value as Record<string, unknown>;
+  const authority = SiteAuthAuthority.parse(record.authority);
+  if (
+    record.schemaVersion !== 1 ||
+    !Number.isSafeInteger(record.authRunVersion) ||
+    (record.authRunVersion as number) < 1 ||
+    authority.kind !== "external_provider"
+  ) {
+    throw new InteractionResourceStateError("External-auth operation metadata is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    authRunVersion: record.authRunVersion as number,
+    authority,
+  };
+}
+
+function externalAuthPreparationFromOperation(
+  operation: ResourceOperationRow,
+  run: AuthRunRow,
+): ExternalAuthPreparation {
+  const metadata = externalAuthOperationMetadata(operation.metadata);
+  return {
+    run: authRunFromRow(run),
+    authority: metadata.authority,
+    operationState: operation.state,
+    response:
+      operation.state === "completed" && operation.result
+        ? {
+            ...ExternalAuthRunResponse.parse(operation.result),
+            replayed: true,
+          }
+        : null,
+    replayed: operation.state === "completed",
+  };
+}
+
+function parseProtectedAuthFillRequest(
+  input: ProtectedAuthFillRequestValue,
+): ProtectedAuthFillRequestValue {
+  return ProtectedAuthFillRequest.parse({
+    operationId: input.operationId,
+    expectedVersion: input.expectedVersion,
+    expectedTargetGeneration: input.expectedTargetGeneration,
+    expectedDocumentGeneration: input.expectedDocumentGeneration,
+    expectedFrameId: input.expectedFrameId,
+    authorityId: input.authorityId,
+    fields: input.fields,
+    submit: input.submit,
+  });
+}
+
+function protectedAuthPreparationFromOperation(
+  operation: ResourceOperationRow,
+  run: AuthRunRow,
+): ProtectedAuthFillPreparation {
+  const metadata = protectedAuthOperationMetadata(operation.metadata);
+  return {
+    run: authRunFromRow(run),
+    authority: metadata.authority,
+    origins: metadata.origins,
+    credentialVersion: metadata.credentialVersion,
+    operationState: operation.state,
+    response:
+      operation.state === "completed" && operation.result
+        ? {
+            ...ProtectedAuthFillResponse.parse(operation.result),
+            replayed: true,
+          }
+        : null,
+    replayed: operation.state === "completed",
+  };
+}
+
+export async function getProtectedAuthFillPreparation(
+  db: Database,
+  input: InteractionMutationScope & {
+    authRunId: string;
+  } & ProtectedAuthFillRequestValue,
+): Promise<ProtectedAuthFillPreparation | null> {
+  const request = parseProtectedAuthFillRequest(input);
+  const digest = protectedAuthFillDigest(input.authRunId, request, input.actorSubjectId);
+  return await withRlsContext(
+    db,
+    input,
+    async (scopedDb) => {
+      const operation = await loadOperation(scopedDb, input.workspaceId, request.operationId);
+      if (!operation) return null;
+      assertOperationIdentity(operation, {
+        resourceKind: "auth_run",
+        resourceId: input.authRunId,
+        kind: "protected_fill",
+        requestDigest: digest,
+        actorSubjectId: input.actorSubjectId,
+      });
+      const run = await loadAuthRunRow(scopedDb, input.workspaceId, input.authRunId);
+      if (!run) throw new InteractionResourceNotFoundError("Auth run not found");
+      return protectedAuthPreparationFromOperation(operation, run);
+    },
+    CONSISTENT_READ,
+  );
+}
+
+function protectedAuthOperationMetadata(value: unknown): ProtectedAuthOperationMetadata {
+  if (!value || typeof value !== "object" || Array.isArray(value)) {
+    throw new InteractionResourceStateError("Protected-fill operation metadata is invalid");
+  }
+  const record = value as Record<string, unknown>;
+  const authority = SiteAuthAuthority.parse(record.authority);
+  if (
+    record.schemaVersion !== 1 ||
+    !Number.isSafeInteger(record.authRunVersion) ||
+    (record.authRunVersion as number) < 1 ||
+    !Array.isArray(record.origins) ||
+    record.origins.some(
+      (origin) =>
+        typeof origin !== "string" ||
+        (() => {
+          try {
+            return new URL(origin).origin !== origin;
+          } catch {
+            return true;
+          }
+        })(),
+    ) ||
+    !Array.isArray(record.fields) ||
+    record.fields.length < 1 ||
+    record.fields.length > 32 ||
+    !(
+      record.credentialVersion === null ||
+      (Number.isSafeInteger(record.credentialVersion) && (record.credentialVersion as number) > 0)
+    )
+  ) {
+    throw new InteractionResourceStateError("Protected-fill operation metadata is invalid");
+  }
+  const purposes = new Set(["identifier", "password", "secret", "totp"]);
+  const fields = record.fields.map((field) => {
+    if (!field || typeof field !== "object" || Array.isArray(field)) {
+      throw new InteractionResourceStateError("Protected-fill operation metadata is invalid");
+    }
+    const candidate = field as Record<string, unknown>;
+    if (
+      typeof candidate.id !== "string" ||
+      candidate.id.length < 1 ||
+      candidate.id.length > 512 ||
+      typeof candidate.purpose !== "string" ||
+      !purposes.has(candidate.purpose)
+    ) {
+      throw new InteractionResourceStateError("Protected-fill operation metadata is invalid");
+    }
+    return {
+      id: candidate.id,
+      purpose: candidate.purpose as ProtectedAuthOperationMetadata["fields"][number]["purpose"],
+    };
+  });
+  if (new Set(fields.map((field) => field.id)).size !== fields.length) {
+    throw new InteractionResourceStateError("Protected-fill operation metadata is invalid");
+  }
+  if ((authority.kind === "connection_fields") !== (record.credentialVersion !== null)) {
+    throw new InteractionResourceStateError("Protected-fill credential metadata is invalid");
+  }
+  return {
+    schemaVersion: 1,
+    authRunVersion: record.authRunVersion as number,
+    authority,
+    origins: [...(record.origins as string[])],
+    fields,
+    credentialVersion: record.credentialVersion as number | null,
+  };
+}
+
+function protectedAuthFields(
+  authority: SiteAuthAuthorityValue,
+  requested: readonly ProtectedAuthFillRequestValue["fields"][number][],
+): ProtectedAuthOperationMetadata["fields"] {
+  if (authority.kind === "external_provider") {
+    throw new InteractionResourceStateError(
+      "External auth providers cannot use protected field fill",
+    );
+  }
+  const configured = new Map(authority.fields.map((field) => [field.id, field]));
+  return requested.map((field) => {
+    const match = configured.get(field.fieldId);
+    if (!match) {
+      throw new InteractionResourceStateError("Protected-fill field is not configured");
+    }
+    return { id: match.id, purpose: match.purpose };
+  });
+}
+
 export async function listAuthRuns(
   db: Database,
   input: {
@@ -1089,31 +1845,112 @@ export async function getAuthRun(
   );
 }
 
-export async function startAuthRun(
+export type ExternalAuthInteractiveContext = {
+  run: AuthRunValue;
+  authority: Extract<SiteAuthAuthorityValue, { kind: "external_provider" }>;
+};
+
+/** Resolve only the durable authority needed to reveal an external provider's
+ * hosted login UI. The hosted URL itself is deliberately never persisted. */
+export async function getExternalAuthInteractiveContext(
   db: Database,
-  input: InteractionMutationScope & { browserSessionId: string } & StartAuthRunRequestValue,
-): Promise<AuthRunMutationResponseValue> {
-  const request = StartAuthRunRequest.parse({
+  input: InteractionMutationScope & {
+    authRunId: string;
+  } & ExternalAuthInteractiveRequestValue,
+): Promise<ExternalAuthInteractiveContext> {
+  const request = ExternalAuthInteractiveRequest.parse({
     operationId: input.operationId,
-    siteAuthConnectionId: input.siteAuthConnectionId,
-    targetId: input.targetId,
-    expectedTargetGeneration: input.expectedTargetGeneration,
-    expectedDocumentGeneration: input.expectedDocumentGeneration,
-    ...(input.methodId !== undefined ? { methodId: input.methodId } : {}),
-    ...(input.authorityId !== undefined ? { authorityId: input.authorityId } : {}),
-  });
-  const { operationId: _operationId, ...digestRequest } = request;
-  const digest = operationDigest({
-    version: 1,
-    browserSessionId: input.browserSessionId,
-    request: digestRequest,
-    actorSubjectId: input.actorSubjectId,
+    expectedVersion: input.expectedVersion,
   });
-  try {
-    return await withRlsContext(db, input, async (scopedDb) => {
-      await assertWorkspaceAccount(scopedDb, input.accountId, input.workspaceId);
-      await lockOperation(scopedDb, request.operationId);
-      const existing = await loadOperation(scopedDb, input.workspaceId, request.operationId);
+  return await withRlsContext(
+    db,
+    input,
+    async (scopedDb) => {
+      const run = await loadAuthRunRow(scopedDb, input.workspaceId, input.authRunId);
+      if (!run) throw new InteractionResourceNotFoundError("Auth run not found");
+      if (run.settledAt || run.version !== request.expectedVersion) {
+        throw new InteractionResourceConflictError(
+          "Auth run changed before its hosted login flow was opened",
+        );
+      }
+      if (run.state !== "awaiting_external_action" || !run.externalAction || !run.interventionId) {
+        throw new InteractionResourceStateError("Auth run is not waiting for a hosted login flow");
+      }
+      const [browser] = await scopedDb
+        .select({
+          lifecycle: schema.browserSessions.lifecycle,
+          controllerGeneration: schema.browserSessions.controllerGeneration,
+        })
+        .from(schema.browserSessions)
+        .where(
+          and(
+            eq(schema.browserSessions.workspaceId, input.workspaceId),
+            eq(schema.browserSessions.id, run.browserSessionId),
+          ),
+        )
+        .limit(1);
+      if (
+        !browser ||
+        browser.lifecycle !== "active" ||
+        browser.controllerGeneration !== run.controllerGeneration
+      ) {
+        throw new InteractionResourceConflictError(
+          "Hosted login belongs to a stale browser controller",
+        );
+      }
+      const connectionRow = await getSiteAuthConnectionRow(
+        scopedDb,
+        input.workspaceId,
+        run.siteAuthConnectionId,
+      );
+      if (connectionRow.status !== "active") {
+        throw new InteractionResourceStateError("Site auth connection is archived");
+      }
+      const connection = siteAuthConnectionFromRow(connectionRow);
+      const authority = connection.authorities.find(
+        (candidate) => candidate.id === run.authorityId,
+      );
+      if (!authority || authority.kind !== "external_provider") {
+        throw new InteractionResourceStateError("Auth run has no external provider authority");
+      }
+      return { run: authRunFromRow(run), authority };
+    },
+    CONSISTENT_READ,
+  );
+}
+
+export async function startAuthRun(
+  db: Database,
+  input: InteractionMutationScope & {
+    browserSessionId: string;
+    controllerGeneration: string;
+    /** Trusted attempt provenance supplied by the API grant. */
+    originatingSessionId?: string | null;
+  } & StartAuthRunRequestValue,
+): Promise<AuthRunMutationResponseValue> {
+  const request = StartAuthRunRequest.parse({
+    operationId: input.operationId,
+    siteAuthConnectionId: input.siteAuthConnectionId,
+    targetId: input.targetId,
+    expectedTargetGeneration: input.expectedTargetGeneration,
+    expectedDocumentGeneration: input.expectedDocumentGeneration,
+    ...(input.purpose !== undefined ? { purpose: input.purpose } : {}),
+    ...(input.methodId !== undefined ? { methodId: input.methodId } : {}),
+    ...(input.authorityId !== undefined ? { authorityId: input.authorityId } : {}),
+  });
+  const { operationId: _operationId, ...digestRequest } = request;
+  const digest = operationDigest({
+    version: 1,
+    browserSessionId: input.browserSessionId,
+    controllerGeneration: input.controllerGeneration,
+    request: digestRequest,
+    actorSubjectId: input.actorSubjectId,
+  });
+  try {
+    return await withRlsContext(db, input, async (scopedDb) => {
+      await assertWorkspaceAccount(scopedDb, input.accountId, input.workspaceId);
+      await lockOperation(scopedDb, request.operationId);
+      const existing = await loadOperation(scopedDb, input.workspaceId, request.operationId);
       if (existing) {
         assertOperation(existing, {
           resourceKind: "auth_run",
@@ -1136,7 +1973,11 @@ export async function startAuthRun(
         .for("update")
         .limit(1);
       if (!browser) throw new InteractionResourceNotFoundError("Browser session not found");
-      if (browser.lifecycle !== "active" || !browser.controllerGeneration) {
+      if (
+        browser.lifecycle !== "active" ||
+        !browser.controllerGeneration ||
+        browser.controllerGeneration !== input.controllerGeneration
+      ) {
         throw new InteractionResourceStateError("Browser session is not active");
       }
       const authConnection = await getSiteAuthConnectionRow(
@@ -1152,6 +1993,55 @@ export async function startAuthRun(
         methodId: request.methodId ?? null,
         authorityId: request.authorityId ?? null,
       });
+      let originatingMaintenanceOperationId: string | null = null;
+      if (input.originatingSessionId) {
+        const [originatingSession] = await scopedDb
+          .select({
+            createdByKind: schema.sessions.createdByKind,
+            createdBySubjectId: schema.sessions.createdBySubjectId,
+            createdByContext: schema.sessions.createdByContext,
+          })
+          .from(schema.sessions)
+          .where(
+            and(
+              eq(schema.sessions.workspaceId, input.workspaceId),
+              eq(schema.sessions.id, input.originatingSessionId),
+            ),
+          )
+          .limit(1);
+        const contextOperationId =
+          originatingSession?.createdByContext[SITE_AUTH_MAINTENANCE_OPERATION_CONTEXT_KEY];
+        const contextConnectionId =
+          originatingSession?.createdByContext[SITE_AUTH_MAINTENANCE_CONNECTION_CONTEXT_KEY];
+        if (
+          originatingSession?.createdByKind === "service" &&
+          originatingSession.createdBySubjectId === "site-auth-maintenance" &&
+          typeof contextOperationId === "string"
+        ) {
+          if (contextConnectionId !== request.siteAuthConnectionId) {
+            throw new InteractionResourceStateError(
+              "Site auth maintenance session belongs to another connection",
+            );
+          }
+          originatingMaintenanceOperationId = contextOperationId;
+        }
+      }
+      if (
+        originatingMaintenanceOperationId &&
+        (input.originatingSessionId !== authConnection.maintenanceSessionId ||
+          originatingMaintenanceOperationId !== authConnection.maintenanceOperationId)
+      ) {
+        throw new InteractionResourceStateError("Site auth maintenance claim is no longer active");
+      }
+      const maintenanceOperationId = originatingMaintenanceOperationId;
+      if (
+        maintenanceOperationId &&
+        (request.purpose ?? "authenticate") !== authConnection.maintenanceAction
+      ) {
+        throw new InteractionResourceStateError(
+          "Maintenance auth run purpose does not match its durable claim",
+        );
+      }
       const id = randomUUID();
       const [row] = await scopedDb
         .insert(schema.authRuns)
@@ -1165,6 +2055,8 @@ export async function startAuthRun(
           controllerGeneration: browser.controllerGeneration,
           targetGeneration: request.expectedTargetGeneration,
           documentGeneration: request.expectedDocumentGeneration,
+          purpose: request.purpose ?? "authenticate",
+          maintenanceOperationId,
           methodId: request.methodId ?? null,
           authorityId: request.authorityId ?? null,
           operationId: request.operationId,
@@ -1193,6 +2085,11 @@ export async function startAuthRun(
       return response;
     });
   } catch (error) {
+    if (postgresConstraint(error) === "auth_runs_workspace_maintenance_operation_uq") {
+      throw new InteractionResourceConflictError(
+        "This maintenance session already has an auth run",
+      );
+    }
     if (postgresConstraint(error) === "auth_runs_active_browser_target_uq") {
       throw new InteractionResourceConflictError(
         "This browser target already has an active auth run",
@@ -1202,6 +2099,131 @@ export async function startAuthRun(
   }
 }
 
+export type SettleSessionMaintenanceResult = {
+  cancelledAuthRuns: number;
+  releasedClaim: boolean;
+};
+
+/** A terminal-for-now maintenance session cannot leave an AuthRun or its claim
+ * pinned. Interventions settle linked runs first; this covers every other path. */
+export async function settleSessionMaintenanceInTransaction(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+  },
+): Promise<SettleSessionMaintenanceResult> {
+  const [session] = await db
+    .select({
+      createdByKind: schema.sessions.createdByKind,
+      createdBySubjectId: schema.sessions.createdBySubjectId,
+      createdByContext: schema.sessions.createdByContext,
+    })
+    .from(schema.sessions)
+    .where(
+      and(
+        eq(schema.sessions.workspaceId, input.workspaceId),
+        eq(schema.sessions.id, input.sessionId),
+      ),
+    )
+    .limit(1);
+  const maintenanceOperationId =
+    session?.createdByContext[SITE_AUTH_MAINTENANCE_OPERATION_CONTEXT_KEY];
+  const siteAuthConnectionId =
+    session?.createdByContext[SITE_AUTH_MAINTENANCE_CONNECTION_CONTEXT_KEY];
+  if (
+    session?.createdByKind !== "service" ||
+    session.createdBySubjectId !== "site-auth-maintenance" ||
+    typeof maintenanceOperationId !== "string" ||
+    typeof siteAuthConnectionId !== "string"
+  ) {
+    return { cancelledAuthRuns: 0, releasedClaim: false };
+  }
+  const settledAt = new Date();
+  const cancelled = await db
+    .update(schema.authRuns)
+    .set({
+      state: "cancelled",
+      choices: [],
+      pendingFields: [],
+      externalAction: null,
+      verifiedUrl: null,
+      failureCode: null,
+      version: sql`${schema.authRuns.version} + 1`,
+      updatedAt: settledAt,
+      settledAt,
+    })
+    .where(
+      and(
+        eq(schema.authRuns.workspaceId, input.workspaceId),
+        eq(schema.authRuns.siteAuthConnectionId, siteAuthConnectionId),
+        eq(schema.authRuns.maintenanceOperationId, maintenanceOperationId),
+        sql`${schema.authRuns.settledAt} is null`,
+      ),
+    )
+    .returning();
+  for (const run of cancelled) {
+    await projectSettledAuthRunHealth(db, {
+      run,
+      actorSubjectId: "site-auth-maintenance",
+    });
+  }
+  const [orphanedClaim] = await db
+    .select()
+    .from(schema.siteAuthConnections)
+    .where(
+      and(
+        eq(schema.siteAuthConnections.workspaceId, input.workspaceId),
+        eq(schema.siteAuthConnections.id, siteAuthConnectionId),
+        eq(schema.siteAuthConnections.maintenanceOperationId, maintenanceOperationId),
+        eq(schema.siteAuthConnections.maintenanceSessionId, input.sessionId),
+      ),
+    )
+    .for("update")
+    .limit(1);
+  let releasedClaim = false;
+  if (orphanedClaim) {
+    const intervalSeconds = orphanedClaim.healthPolicy.intervalSeconds;
+    const retryAt =
+      orphanedClaim.status === "active" &&
+      orphanedClaim.healthPolicy.mode === "maintained" &&
+      intervalSeconds !== null
+        ? new Date(
+            settledAt.getTime() +
+              Math.min(intervalSeconds * 1_000, MAX_SITE_AUTH_MAINTENANCE_RETRY_MS),
+          )
+        : null;
+    const [released] = await db
+      .update(schema.siteAuthConnections)
+      .set({
+        maintenanceOperationId: null,
+        maintenanceAction: null,
+        maintenanceDueAt: null,
+        maintenanceClaimedAt: null,
+        maintenanceSessionId: null,
+        maintenanceStartedAt: null,
+        nextCheckAt: retryAt,
+        version: sql`${schema.siteAuthConnections.version} + 1`,
+        updatedBySubjectId: "site-auth-maintenance",
+        updatedAt: settledAt,
+      })
+      .where(
+        and(
+          eq(schema.siteAuthConnections.workspaceId, input.workspaceId),
+          eq(schema.siteAuthConnections.id, orphanedClaim.id),
+          eq(schema.siteAuthConnections.maintenanceOperationId, maintenanceOperationId),
+        ),
+      )
+      .returning({ id: schema.siteAuthConnections.id });
+    releasedClaim = released !== undefined;
+  }
+  if (cancelled.length > 0 || releasedClaim) {
+    await advanceWorkspaceInteractionRevision(db, input.accountId, input.workspaceId);
+  }
+  return { cancelledAuthRuns: cancelled.length, releasedClaim };
+}
+
 export async function reportAuthRun(
   db: Database,
   input: InteractionMutationScope & {
@@ -1298,10 +2320,1159 @@ export async function reportAuthRun(
           eq(schema.authRuns.controllerGeneration, input.controllerGeneration),
         ),
       )
-      .returning();
-    if (!row) throw new InteractionResourceConflictError("Auth run report lost its fence");
+      .returning();
+    if (!row) throw new InteractionResourceConflictError("Auth run report lost its fence");
+    await projectSettledAuthRunHealth(scopedDb, {
+      run: row,
+      actorSubjectId: input.actorSubjectId,
+    });
+    const response = AuthRunMutationResponse.parse({
+      run: authRunFromRow(row),
+      operationId: request.operationId,
+      replayed: false,
+    });
+    await insertCompletedOperation(scopedDb, {
+      operationId: request.operationId,
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      resourceKind: "auth_run",
+      resourceId: input.authRunId,
+      kind: "report",
+      requestDigest: digest,
+      resultVersion: row.version,
+      result: response,
+      actorSubjectId: input.actorSubjectId,
+    });
+    await advanceWorkspaceInteractionRevision(scopedDb, input.accountId, input.workspaceId);
+    return response;
+  });
+}
+
+export async function getExternalAuthPreparation(
+  db: Database,
+  input: InteractionMutationScope & {
+    authRunId: string;
+  } & ExternalAuthRunRequestValue,
+): Promise<ExternalAuthPreparation | null> {
+  const request = parseExternalAuthRunRequest(input);
+  const digest = externalAuthDigest(input.authRunId, request, input.actorSubjectId);
+  return await withRlsContext(
+    db,
+    input,
+    async (scopedDb) => {
+      const operation = await loadOperation(scopedDb, input.workspaceId, request.operationId);
+      if (!operation) return null;
+      assertOperationIdentity(operation, {
+        resourceKind: "auth_run",
+        resourceId: input.authRunId,
+        kind: "external_auth",
+        requestDigest: digest,
+        actorSubjectId: input.actorSubjectId,
+      });
+      const run = await loadAuthRunRow(scopedDb, input.workspaceId, input.authRunId);
+      if (!run) throw new InteractionResourceNotFoundError("Auth run not found");
+      return externalAuthPreparationFromOperation(operation, run);
+    },
+    CONSISTENT_READ,
+  );
+}
+
+export async function prepareExternalAuth(
+  db: Database,
+  input: InteractionMutationScope & {
+    authRunId: string;
+  } & ExternalAuthRunRequestValue,
+): Promise<ExternalAuthPreparation> {
+  const request = parseExternalAuthRunRequest(input);
+  const digest = externalAuthDigest(input.authRunId, request, input.actorSubjectId);
+  return await withRlsContext(db, input, async (scopedDb) => {
+    await assertWorkspaceAccount(scopedDb, input.accountId, input.workspaceId);
+    await setSubjectRlsContext(scopedDb, input.actorSubjectId);
+    await lockOperation(scopedDb, request.operationId);
+    const existing = await loadOperation(scopedDb, input.workspaceId, request.operationId);
+    if (existing) {
+      assertOperationIdentity(existing, {
+        resourceKind: "auth_run",
+        resourceId: input.authRunId,
+        kind: "external_auth",
+        requestDigest: digest,
+        actorSubjectId: input.actorSubjectId,
+      });
+      const run = await loadAuthRunRow(scopedDb, input.workspaceId, input.authRunId);
+      if (!run) throw new InteractionResourceNotFoundError("Auth run not found");
+      return externalAuthPreparationFromOperation(existing, run);
+    }
+
+    const [run] = await scopedDb
+      .select()
+      .from(schema.authRuns)
+      .where(
+        and(
+          eq(schema.authRuns.workspaceId, input.workspaceId),
+          eq(schema.authRuns.id, input.authRunId),
+        ),
+      )
+      .for("update")
+      .limit(1);
+    if (!run) throw new InteractionResourceNotFoundError("Auth run not found");
+    if (run.settledAt) throw new InteractionResourceStateError("Auth run is already settled");
+    if (run.version !== request.expectedVersion) {
+      throw new InteractionResourceConflictError("Auth run changed before external authentication");
+    }
+    const [browser] = await scopedDb
+      .select({
+        lifecycle: schema.browserSessions.lifecycle,
+        controllerGeneration: schema.browserSessions.controllerGeneration,
+      })
+      .from(schema.browserSessions)
+      .where(
+        and(
+          eq(schema.browserSessions.workspaceId, input.workspaceId),
+          eq(schema.browserSessions.id, run.browserSessionId),
+        ),
+      )
+      .for("update")
+      .limit(1);
+    if (
+      !browser ||
+      browser.lifecycle !== "active" ||
+      browser.controllerGeneration !== run.controllerGeneration
+    ) {
+      throw new InteractionResourceConflictError(
+        "External authentication belongs to a stale browser controller",
+      );
+    }
+    const connectionRow = await getSiteAuthConnectionRow(
+      scopedDb,
+      input.workspaceId,
+      run.siteAuthConnectionId,
+    );
+    if (connectionRow.status !== "active") {
+      throw new InteractionResourceStateError("Site auth connection is archived");
+    }
+    const connection = siteAuthConnectionFromRow(connectionRow);
+    if (!run.authorityId) {
+      throw new InteractionResourceStateError(
+        "Auth run must select an external authority before it can start",
+      );
+    }
+    assertAuthSelection(connection, {
+      methodId: run.methodId,
+      authorityId: run.authorityId,
+    });
+    const selected = connection.authorities.find((authority) => authority.id === run.authorityId);
+    if (!selected || selected.kind !== "external_provider") {
+      throw new InteractionResourceStateError(
+        "Selected auth authority is not an external provider",
+      );
+    }
+    const metadata: ExternalAuthOperationMetadata = {
+      schemaVersion: 1,
+      authRunVersion: run.version,
+      authority: selected,
+    };
+    await scopedDb.insert(schema.interactionResourceOperations).values({
+      operationId: request.operationId,
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      resourceKind: "auth_run",
+      resourceId: input.authRunId,
+      kind: "external_auth",
+      requestDigest: digest,
+      metadata,
+      state: "prepared",
+      actorSubjectId: input.actorSubjectId,
+    });
+    return {
+      run: authRunFromRow(run),
+      authority: selected,
+      operationState: "prepared",
+      response: null,
+      replayed: false,
+    };
+  });
+}
+
+export async function dispatchExternalAuth(
+  db: Database,
+  input: InteractionMutationScope & { authRunId: string; operationId: string },
+): Promise<ResourceOperationRow["state"]> {
+  return await withRlsContext(db, input, async (scopedDb) => {
+    await lockOperation(scopedDb, input.operationId);
+    const operation = await loadOperation(scopedDb, input.workspaceId, input.operationId);
+    if (!operation) throw new InteractionResourceNotFoundError("External-auth operation not found");
+    assertExternalAuthOperationBinding(operation, input);
+    if (operation.state !== "prepared") return operation.state;
+    const [dispatched] = await scopedDb
+      .update(schema.interactionResourceOperations)
+      .set({ state: "dispatched" })
+      .where(
+        and(
+          eq(schema.interactionResourceOperations.operationId, input.operationId),
+          eq(schema.interactionResourceOperations.state, "prepared"),
+        ),
+      )
+      .returning({ state: schema.interactionResourceOperations.state });
+    if (!dispatched) {
+      throw new InteractionResourceConflictError("External-auth dispatch lost its fence");
+    }
+    return dispatched.state;
+  });
+}
+
+export async function completeExternalAuth(
+  db: Database,
+  input: InteractionMutationScope & {
+    authRunId: string;
+    operationId: string;
+    result: BrowserExternalAuthResultValue;
+    target?: {
+      id: string;
+      targetGeneration: string;
+      documentGeneration: string | null;
+    };
+    intervention?: {
+      originatingSessionId: string;
+      originatingTurnId?: string | null;
+      originatingAttemptId?: string | null;
+      originatingToolOperationId?: string | null;
+      expiresInSeconds: number;
+    };
+  },
+): Promise<ExternalAuthRunResponseValue> {
+  const providerResult = BrowserExternalAuthResult.parse(input.result);
+  try {
+    return await withRlsContext(db, input, async (scopedDb) => {
+      await lockOperation(scopedDb, input.operationId);
+      const operation = await loadOperation(scopedDb, input.workspaceId, input.operationId);
+      if (!operation)
+        throw new InteractionResourceNotFoundError("External-auth operation not found");
+      assertExternalAuthOperationBinding(operation, input);
+      if (operation.state === "completed" && operation.result) {
+        return {
+          ...ExternalAuthRunResponse.parse(operation.result),
+          replayed: true,
+        };
+      }
+      if (operation.state !== "dispatched") {
+        throw new InteractionResourceStateError(
+          `External-auth operation is ${operation.state.replace("_", " ")}`,
+        );
+      }
+      const metadata = externalAuthOperationMetadata(operation.metadata);
+      const [run] = await scopedDb
+        .select()
+        .from(schema.authRuns)
+        .where(
+          and(
+            eq(schema.authRuns.workspaceId, input.workspaceId),
+            eq(schema.authRuns.id, input.authRunId),
+          ),
+        )
+        .for("update")
+        .limit(1);
+      if (!run) throw new InteractionResourceNotFoundError("Auth run not found");
+      if (run.version !== metadata.authRunVersion || run.settledAt) {
+        throw new InteractionResourceConflictError("Auth run changed after external auth began");
+      }
+      if ((providerResult.state === "authenticated") !== Boolean(input.target)) {
+        throw new InteractionResourceStateError(
+          "Authenticated external auth requires the current browser target",
+        );
+      }
+      if ((providerResult.state === "needs_human") !== Boolean(input.intervention)) {
+        throw new InteractionResourceStateError(
+          "Human external auth requires intervention provenance",
+        );
+      }
+      const nextState =
+        providerResult.state === "needs_human"
+          ? "awaiting_external_action"
+          : providerResult.state === "failed"
+            ? "failed"
+            : "working";
+      if (!AUTH_RUN_TRANSITIONS[run.state].has(nextState)) {
+        throw new InteractionResourceStateError(
+          `Auth run cannot transition from ${run.state} to ${nextState}`,
+        );
+      }
+
+      if (providerResult.profileLoaded) {
+        const otherRuns = await scopedDb
+          .update(schema.authRuns)
+          .set({
+            state: "failed",
+            choices: [],
+            pendingFields: [],
+            externalAction: null,
+            interventionId: null,
+            verifiedUrl: null,
+            failureCode: "browser_profile_reconfigured",
+            version: sql`${schema.authRuns.version} + 1`,
+            updatedAt: sql`now()`,
+            settledAt: sql`now()`,
+          })
+          .where(
+            and(
+              eq(schema.authRuns.workspaceId, input.workspaceId),
+              eq(schema.authRuns.browserSessionId, run.browserSessionId),
+              sql`${schema.authRuns.id} <> ${run.id}`,
+              sql`${schema.authRuns.settledAt} is null`,
+            ),
+          )
+          .returning();
+        if (otherRuns.length > 0) {
+          const otherIds = otherRuns.map((entry) => entry.id);
+          await scopedDb
+            .update(schema.interactionResourceOperations)
+            .set({
+              state: "failed",
+              errorCode: "browser_profile_reconfigured",
+              settledAt: sql`now()`,
+            })
+            .where(
+              and(
+                eq(schema.interactionResourceOperations.workspaceId, input.workspaceId),
+                eq(schema.interactionResourceOperations.resourceKind, "auth_run"),
+                inArray(schema.interactionResourceOperations.resourceId, otherIds),
+                inArray(schema.interactionResourceOperations.state, ["prepared", "dispatched"]),
+              ),
+            );
+          await scopedDb
+            .update(schema.interactionInterventions)
+            .set({
+              status: "cancelled",
+              responseActorSubjectId: input.actorSubjectId,
+              version: sql`${schema.interactionInterventions.version} + 1`,
+              updatedAt: sql`now()`,
+              settledAt: sql`now()`,
+            })
+            .where(
+              and(
+                eq(schema.interactionInterventions.workspaceId, input.workspaceId),
+                inArray(schema.interactionInterventions.authRunId, otherIds),
+                eq(schema.interactionInterventions.status, "open"),
+              ),
+            );
+          for (const other of otherRuns) {
+            await projectSettledAuthRunHealth(scopedDb, {
+              run: other,
+              actorSubjectId: input.actorSubjectId,
+            });
+          }
+        }
+      }
+
+      let interventionId: string | null = null;
+      if (providerResult.state === "needs_human") {
+        const currentIntervention = run.interventionId
+          ? (
+              await scopedDb
+                .select()
+                .from(schema.interactionInterventions)
+                .where(
+                  and(
+                    eq(schema.interactionInterventions.workspaceId, input.workspaceId),
+                    eq(schema.interactionInterventions.id, run.interventionId),
+                  ),
+                )
+                .for("update")
+                .limit(1)
+            )[0]
+          : null;
+        if (currentIntervention?.status === "open" && currentIntervention.expiresAt > new Date()) {
+          interventionId = currentIntervention.id;
+        } else {
+          if (currentIntervention?.status === "open") {
+            await scopedDb
+              .update(schema.interactionInterventions)
+              .set({
+                status: "expired",
+                version: currentIntervention.version + 1,
+                updatedAt: sql`now()`,
+                settledAt: sql`now()`,
+              })
+              .where(
+                and(
+                  eq(schema.interactionInterventions.id, currentIntervention.id),
+                  eq(schema.interactionInterventions.version, currentIntervention.version),
+                  eq(schema.interactionInterventions.status, "open"),
+                ),
+              );
+          }
+          const intervention = input.intervention!;
+          if (
+            (intervention.originatingAttemptId && !intervention.originatingTurnId) ||
+            (intervention.originatingToolOperationId && !intervention.originatingAttemptId)
+          ) {
+            throw new InteractionResourceStateError(
+              "External-auth intervention provenance is incomplete",
+            );
+          }
+          interventionId = randomUUID();
+          const [created] = await scopedDb
+            .insert(schema.interactionInterventions)
+            .values({
+              id: interventionId,
+              accountId: input.accountId,
+              workspaceId: input.workspaceId,
+              resourceKind: "browser_session",
+              resourceId: run.browserSessionId,
+              targetId: run.targetId,
+              controllerGeneration: run.controllerGeneration,
+              targetGeneration: run.targetGeneration,
+              documentGeneration: run.documentGeneration,
+              kind: "external_action",
+              reason: providerResult.externalAction!.label,
+              authRunId: run.id,
+              originatingSessionId: intervention.originatingSessionId,
+              originatingTurnId: intervention.originatingTurnId ?? null,
+              originatingAttemptId: intervention.originatingAttemptId ?? null,
+              originatingToolOperationId: intervention.originatingToolOperationId ?? null,
+              operationId: input.operationId,
+              expiresAt: providerResult.externalAction!.expiresAt
+                ? new Date(providerResult.externalAction!.expiresAt)
+                : sql`now() + (${intervention.expiresInSeconds} * interval '1 second')`,
+            })
+            .returning({ id: schema.interactionInterventions.id });
+          if (!created) throw new Error("External-auth intervention insert returned no row");
+        }
+      } else if (run.interventionId) {
+        await scopedDb
+          .update(schema.interactionInterventions)
+          .set({
+            status: "completed",
+            responseActorSubjectId: input.actorSubjectId,
+            version: sql`${schema.interactionInterventions.version} + 1`,
+            updatedAt: sql`now()`,
+            settledAt: sql`now()`,
+          })
+          .where(
+            and(
+              eq(schema.interactionInterventions.workspaceId, input.workspaceId),
+              eq(schema.interactionInterventions.id, run.interventionId),
+              eq(schema.interactionInterventions.status, "open"),
+            ),
+          );
+      }
+
+      const [updated] = await scopedDb
+        .update(schema.authRuns)
+        .set({
+          authorityId: metadata.authority.id,
+          state: nextState,
+          targetId: input.target?.id ?? run.targetId,
+          targetGeneration: input.target?.targetGeneration ?? run.targetGeneration,
+          documentGeneration: input.target?.documentGeneration ?? run.documentGeneration,
+          choices: [],
+          pendingFields: [],
+          externalAction:
+            providerResult.state === "needs_human" ? providerResult.externalAction : null,
+          interventionId,
+          verifiedUrl: null,
+          failureCode: providerResult.state === "failed" ? providerResult.failureCode : null,
+          version: run.version + 1,
+          updatedAt: sql`now()`,
+          settledAt: providerResult.state === "failed" ? sql`now()` : null,
+        })
+        .where(
+          and(
+            eq(schema.authRuns.workspaceId, input.workspaceId),
+            eq(schema.authRuns.id, input.authRunId),
+            eq(schema.authRuns.version, metadata.authRunVersion),
+            sql`${schema.authRuns.settledAt} is null`,
+          ),
+        )
+        .returning();
+      if (!updated) {
+        throw new InteractionResourceConflictError("External-auth settlement lost its auth fence");
+      }
+      await projectSettledAuthRunHealth(scopedDb, {
+        run: updated,
+        actorSubjectId: input.actorSubjectId,
+      });
+      const status =
+        providerResult.state === "authenticated"
+          ? "ready_to_verify"
+          : providerResult.state === "needs_human"
+            ? "needs_human"
+            : providerResult.state === "failed"
+              ? "failed"
+              : "working";
+      const response = ExternalAuthRunResponse.parse({
+        run: authRunFromRow(updated),
+        status,
+        operationId: input.operationId,
+        replayed: false,
+      });
+      const [completed] = await scopedDb
+        .update(schema.interactionResourceOperations)
+        .set({
+          state: "completed",
+          resultVersion: updated.version,
+          result: response,
+          settledAt: sql`now()`,
+        })
+        .where(
+          and(
+            eq(schema.interactionResourceOperations.operationId, input.operationId),
+            eq(schema.interactionResourceOperations.state, "dispatched"),
+          ),
+        )
+        .returning({ operationId: schema.interactionResourceOperations.operationId });
+      if (!completed) {
+        throw new InteractionResourceConflictError(
+          "External-auth settlement lost its operation fence",
+        );
+      }
+      await advanceWorkspaceInteractionRevision(scopedDb, input.accountId, input.workspaceId);
+      return response;
+    });
+  } catch (error) {
+    if (
+      postgresConstraint(error) === "interaction_interventions_workspace_operation_uq" ||
+      postgresConstraint(error) === "interaction_interventions_open_target_kind_uq" ||
+      postgresConstraint(error) === "interaction_interventions_open_auth_run_uq"
+    ) {
+      throw new InteractionResourceConflictError(
+        "A matching interaction intervention is already open",
+      );
+    }
+    throw error;
+  }
+}
+
+function assertExternalAuthOperationBinding(
+  operation: ResourceOperationRow,
+  input: { authRunId: string; actorSubjectId: string },
+): void {
+  if (
+    operation.resourceKind !== "auth_run" ||
+    operation.resourceId !== input.authRunId ||
+    operation.kind !== "external_auth" ||
+    operation.actorSubjectId !== input.actorSubjectId
+  ) {
+    throw new InteractionResourceConflictError(
+      "Operation id is bound to another external-auth request",
+    );
+  }
+}
+
+export async function prepareProtectedAuthFill(
+  db: Database,
+  input: InteractionMutationScope & {
+    authRunId: string;
+    credentialVersion: number | null;
+  } & ProtectedAuthFillRequestValue,
+): Promise<ProtectedAuthFillPreparation> {
+  const request = parseProtectedAuthFillRequest(input);
+  const digest = protectedAuthFillDigest(input.authRunId, request, input.actorSubjectId);
+  return await withRlsContext(db, input, async (scopedDb) => {
+    await assertWorkspaceAccount(scopedDb, input.accountId, input.workspaceId);
+    await setSubjectRlsContext(scopedDb, input.actorSubjectId);
+    await lockOperation(scopedDb, request.operationId);
+    const existing = await loadOperation(scopedDb, input.workspaceId, request.operationId);
+    if (existing) {
+      assertOperationIdentity(existing, {
+        resourceKind: "auth_run",
+        resourceId: input.authRunId,
+        kind: "protected_fill",
+        requestDigest: digest,
+        actorSubjectId: input.actorSubjectId,
+      });
+      const run = await loadAuthRunRow(scopedDb, input.workspaceId, input.authRunId);
+      if (!run) throw new InteractionResourceNotFoundError("Auth run not found");
+      return protectedAuthPreparationFromOperation(existing, run);
+    }
+
+    const [run] = await scopedDb
+      .select()
+      .from(schema.authRuns)
+      .where(
+        and(
+          eq(schema.authRuns.workspaceId, input.workspaceId),
+          eq(schema.authRuns.id, input.authRunId),
+        ),
+      )
+      .for("update")
+      .limit(1);
+    if (!run) throw new InteractionResourceNotFoundError("Auth run not found");
+    if (run.settledAt) throw new InteractionResourceStateError("Auth run is already settled");
+    if (run.version !== request.expectedVersion) {
+      throw new InteractionResourceConflictError("Auth run changed before protected fill");
+    }
+    if (
+      run.targetGeneration !== request.expectedTargetGeneration ||
+      run.documentGeneration !== request.expectedDocumentGeneration ||
+      !request.expectedDocumentGeneration ||
+      !request.expectedFrameId
+    ) {
+      throw new InteractionResourceConflictError(
+        "Protected fill does not match the exact auth-run document",
+      );
+    }
+    const [browser] = await scopedDb
+      .select({
+        lifecycle: schema.browserSessions.lifecycle,
+        controllerGeneration: schema.browserSessions.controllerGeneration,
+      })
+      .from(schema.browserSessions)
+      .where(
+        and(
+          eq(schema.browserSessions.workspaceId, input.workspaceId),
+          eq(schema.browserSessions.id, run.browserSessionId),
+        ),
+      )
+      .for("update")
+      .limit(1);
+    if (
+      !browser ||
+      browser.lifecycle !== "active" ||
+      browser.controllerGeneration !== run.controllerGeneration
+    ) {
+      throw new InteractionResourceConflictError(
+        "Protected fill belongs to a stale browser controller",
+      );
+    }
+    const connectionRow = await getSiteAuthConnectionRow(
+      scopedDb,
+      input.workspaceId,
+      run.siteAuthConnectionId,
+    );
+    if (connectionRow.status !== "active") {
+      throw new InteractionResourceStateError("Site auth connection is archived");
+    }
+    const connection = siteAuthConnectionFromRow(connectionRow);
+    assertAuthSelection(connection, {
+      methodId: run.methodId,
+      authorityId: request.authorityId,
+    });
+    if (run.authorityId && run.authorityId !== request.authorityId) {
+      throw new InteractionResourceConflictError("Auth run selected another authority");
+    }
+    const authority = connection.authorities.find(
+      (candidate) => candidate.id === request.authorityId,
+    );
+    if (!authority) throw new InteractionResourceStateError("Auth authority is not configured");
+    const fields = protectedAuthFields(authority, request.fields);
+    if (
+      (authority.kind === "connection_fields" &&
+        (!Number.isSafeInteger(input.credentialVersion) || input.credentialVersion! < 1)) ||
+      (authority.kind !== "connection_fields" && input.credentialVersion !== null)
+    ) {
+      throw new InteractionResourceStateError("Protected-fill credential version is invalid");
+    }
+    const metadata: ProtectedAuthOperationMetadata = {
+      schemaVersion: 1,
+      authRunVersion: run.version,
+      authority,
+      origins: [...connection.origins],
+      fields,
+      credentialVersion: input.credentialVersion,
+    };
+    await scopedDb.insert(schema.interactionResourceOperations).values({
+      operationId: request.operationId,
+      accountId: input.accountId,
+      workspaceId: input.workspaceId,
+      resourceKind: "auth_run",
+      resourceId: input.authRunId,
+      kind: "protected_fill",
+      requestDigest: digest,
+      metadata,
+      state: "prepared",
+      actorSubjectId: input.actorSubjectId,
+    });
+    return {
+      run: authRunFromRow(run),
+      authority,
+      origins: [...connection.origins],
+      credentialVersion: input.credentialVersion,
+      operationState: "prepared",
+      response: null,
+      replayed: false,
+    };
+  });
+}
+
+export async function dispatchProtectedAuthFill(
+  db: Database,
+  input: InteractionMutationScope & { authRunId: string; operationId: string },
+): Promise<ResourceOperationRow["state"]> {
+  return await withRlsContext(db, input, async (scopedDb) => {
+    await lockOperation(scopedDb, input.operationId);
+    const [operation] = await scopedDb
+      .select()
+      .from(schema.interactionResourceOperations)
+      .where(
+        and(
+          eq(schema.interactionResourceOperations.workspaceId, input.workspaceId),
+          eq(schema.interactionResourceOperations.operationId, input.operationId),
+        ),
+      )
+      .for("update")
+      .limit(1);
+    if (!operation)
+      throw new InteractionResourceNotFoundError("Protected-fill operation not found");
+    assertProtectedFillOperationBinding(operation, input);
+    if (operation.state === "prepared") {
+      const [dispatched] = await scopedDb
+        .update(schema.interactionResourceOperations)
+        .set({ state: "dispatched" })
+        .where(
+          and(
+            eq(schema.interactionResourceOperations.operationId, input.operationId),
+            eq(schema.interactionResourceOperations.state, "prepared"),
+          ),
+        )
+        .returning({ state: schema.interactionResourceOperations.state });
+      if (!dispatched) {
+        throw new InteractionResourceConflictError("Protected-fill dispatch lost its fence");
+      }
+      return dispatched.state;
+    }
+    return operation.state;
+  });
+}
+
+export async function completeProtectedAuthFill(
+  db: Database,
+  input: InteractionMutationScope & {
+    authRunId: string;
+    operationId: string;
+    status: ProtectedAuthFillResponseValue["status"];
+    targetGeneration?: string;
+    documentGeneration?: string | null;
+    failureCode?: string;
+    intervention?: {
+      originatingSessionId: string;
+      originatingTurnId?: string | null;
+      originatingAttemptId?: string | null;
+      originatingToolOperationId?: string | null;
+      kind: "manual_login" | "mfa" | "external_action" | "confirmation" | "other";
+      reason: string;
+      expiresInSeconds: number;
+    };
+  },
+): Promise<ProtectedAuthFillResponseValue> {
+  try {
+    return await withRlsContext(db, input, async (scopedDb) => {
+      await lockOperation(scopedDb, input.operationId);
+      const [operation] = await scopedDb
+        .select()
+        .from(schema.interactionResourceOperations)
+        .where(
+          and(
+            eq(schema.interactionResourceOperations.workspaceId, input.workspaceId),
+            eq(schema.interactionResourceOperations.operationId, input.operationId),
+          ),
+        )
+        .for("update")
+        .limit(1);
+      if (!operation)
+        throw new InteractionResourceNotFoundError("Protected-fill operation not found");
+      assertProtectedFillOperationBinding(operation, input);
+      if (operation.state === "completed" && operation.result) {
+        return {
+          ...ProtectedAuthFillResponse.parse(operation.result),
+          replayed: true,
+        };
+      }
+      if (operation.state === "failed" || operation.state === "outcome_unknown") {
+        throw new InteractionResourceStateError(
+          `Protected-fill operation is ${operation.state.replace("_", " ")}`,
+        );
+      }
+      if (
+        (input.status === "submitted" || input.status === "working") &&
+        operation.state !== "dispatched"
+      ) {
+        throw new InteractionResourceStateError("Protected fill was not dispatched");
+      }
+      const metadata = protectedAuthOperationMetadata(operation.metadata);
+      const [run] = await scopedDb
+        .select()
+        .from(schema.authRuns)
+        .where(
+          and(
+            eq(schema.authRuns.workspaceId, input.workspaceId),
+            eq(schema.authRuns.id, input.authRunId),
+          ),
+        )
+        .for("update")
+        .limit(1);
+      if (!run) throw new InteractionResourceNotFoundError("Auth run not found");
+      if (run.version !== metadata.authRunVersion || run.settledAt) {
+        throw new InteractionResourceConflictError("Auth run changed after protected fill began");
+      }
+      if (input.targetGeneration && input.targetGeneration !== run.targetGeneration) {
+        throw new InteractionResourceConflictError("Protected-fill result targets another tab");
+      }
+      const submitted = input.status === "submitted" || input.status === "working";
+      const needsHuman = input.status === "needs_human";
+      if (needsHuman !== Boolean(input.intervention)) {
+        throw new InteractionResourceStateError(
+          "Human protected fill requires one durable intervention",
+        );
+      }
+      if (needsHuman && metadata.authority.kind !== "human") {
+        throw new InteractionResourceStateError(
+          "Only a human auth authority can request human intervention",
+        );
+      }
+      let interventionId: string | null = null;
+      if (needsHuman) {
+        const intervention = input.intervention!;
+        if (
+          (intervention.originatingAttemptId && !intervention.originatingTurnId) ||
+          (intervention.originatingToolOperationId && !intervention.originatingAttemptId)
+        ) {
+          throw new InteractionResourceStateError(
+            "Protected-fill intervention provenance is incomplete",
+          );
+        }
+        const request = CreateInteractionInterventionRequest.parse({
+          operationId: input.operationId,
+          resourceKind: "browser_session",
+          resourceId: run.browserSessionId,
+          targetId: run.targetId,
+          expectedControllerGeneration: run.controllerGeneration,
+          expectedTargetGeneration: run.targetGeneration,
+          expectedDocumentGeneration: run.documentGeneration,
+          kind: intervention.kind,
+          reason: intervention.reason,
+          authRunId: run.id,
+          expiresInSeconds: intervention.expiresInSeconds,
+        });
+        interventionId = randomUUID();
+        const [created] = await scopedDb
+          .insert(schema.interactionInterventions)
+          .values({
+            id: interventionId,
+            accountId: input.accountId,
+            workspaceId: input.workspaceId,
+            resourceKind: request.resourceKind,
+            resourceId: request.resourceId,
+            targetId: request.targetId,
+            controllerGeneration: request.expectedControllerGeneration,
+            targetGeneration: request.expectedTargetGeneration,
+            documentGeneration: request.expectedDocumentGeneration,
+            kind: request.kind,
+            reason: request.reason,
+            authRunId: run.id,
+            originatingSessionId: intervention.originatingSessionId,
+            originatingTurnId: intervention.originatingTurnId ?? null,
+            originatingAttemptId: intervention.originatingAttemptId ?? null,
+            originatingToolOperationId: intervention.originatingToolOperationId ?? null,
+            operationId: input.operationId,
+            expiresAt: sql`now() + (${request.expiresInSeconds} * interval '1 second')`,
+          })
+          .returning({ id: schema.interactionInterventions.id });
+        if (!created) {
+          throw new Error("Protected-fill intervention insert returned no row");
+        }
+      }
+      const failureCode =
+        submitted || needsHuman ? null : (input.failureCode ?? "protected_fill_failed");
+      const [updated] = await scopedDb
+        .update(schema.authRuns)
+        .set({
+          authorityId: metadata.authority.id,
+          state: submitted ? "working" : needsHuman ? "awaiting_secret" : "failed",
+          choices: [],
+          pendingFields: needsHuman
+            ? metadata.fields.map((field) => ({
+                id: field.id,
+                label: field.id,
+                purpose: field.purpose,
+              }))
+            : [],
+          externalAction: null,
+          interventionId,
+          verifiedUrl: null,
+          failureCode,
+          documentGeneration:
+            submitted && input.documentGeneration !== undefined
+              ? input.documentGeneration
+              : run.documentGeneration,
+          version: run.version + 1,
+          updatedAt: sql`now()`,
+          settledAt: failureCode ? sql`now()` : null,
+        })
+        .where(
+          and(
+            eq(schema.authRuns.workspaceId, input.workspaceId),
+            eq(schema.authRuns.id, input.authRunId),
+            eq(schema.authRuns.version, metadata.authRunVersion),
+            sql`${schema.authRuns.settledAt} is null`,
+          ),
+        )
+        .returning();
+      if (!updated) {
+        throw new InteractionResourceConflictError("Protected-fill settlement lost its auth fence");
+      }
+      await projectSettledAuthRunHealth(scopedDb, {
+        run: updated,
+        actorSubjectId: input.actorSubjectId,
+      });
+      const response = ProtectedAuthFillResponse.parse({
+        run: authRunFromRow(updated),
+        status: input.status,
+        operationId: input.operationId,
+        replayed: false,
+      });
+      const [completed] = await scopedDb
+        .update(schema.interactionResourceOperations)
+        .set({
+          state: "completed",
+          resultVersion: updated.version,
+          result: response,
+          settledAt: sql`now()`,
+        })
+        .where(
+          and(
+            eq(schema.interactionResourceOperations.operationId, input.operationId),
+            inArray(schema.interactionResourceOperations.state, ["prepared", "dispatched"]),
+          ),
+        )
+        .returning({
+          operationId: schema.interactionResourceOperations.operationId,
+        });
+      if (!completed) {
+        throw new InteractionResourceConflictError(
+          "Protected-fill settlement lost its operation fence",
+        );
+      }
+      await advanceWorkspaceInteractionRevision(scopedDb, input.accountId, input.workspaceId);
+      return response;
+    });
+  } catch (error) {
+    if (
+      postgresConstraint(error) === "interaction_interventions_workspace_operation_uq" ||
+      postgresConstraint(error) === "interaction_interventions_open_target_kind_uq" ||
+      postgresConstraint(error) === "interaction_interventions_open_auth_run_uq"
+    ) {
+      throw new InteractionResourceConflictError(
+        "A matching interaction intervention is already open",
+      );
+    }
+    throw error;
+  }
+}
+
+export async function markProtectedAuthFillOutcomeUnknown(
+  db: Database,
+  input: InteractionMutationScope & {
+    authRunId: string;
+    operationId: string;
+    errorCode: string;
+  },
+): Promise<void> {
+  await withRlsContext(db, input, async (scopedDb) => {
+    await lockOperation(scopedDb, input.operationId);
+    const [operation] = await scopedDb
+      .select()
+      .from(schema.interactionResourceOperations)
+      .where(
+        and(
+          eq(schema.interactionResourceOperations.workspaceId, input.workspaceId),
+          eq(schema.interactionResourceOperations.operationId, input.operationId),
+        ),
+      )
+      .for("update")
+      .limit(1);
+    if (!operation)
+      throw new InteractionResourceNotFoundError("Protected-fill operation not found");
+    assertProtectedFillOperationBinding(operation, input);
+    if (
+      operation.state === "completed" ||
+      operation.state === "failed" ||
+      operation.state === "outcome_unknown"
+    ) {
+      return;
+    }
+    const [marked] = await scopedDb
+      .update(schema.interactionResourceOperations)
+      .set({
+        state: "outcome_unknown",
+        errorCode: input.errorCode,
+        settledAt: sql`now()`,
+      })
+      .where(
+        and(
+          eq(schema.interactionResourceOperations.operationId, input.operationId),
+          inArray(schema.interactionResourceOperations.state, ["prepared", "dispatched"]),
+        ),
+      )
+      .returning({
+        operationId: schema.interactionResourceOperations.operationId,
+      });
+    if (!marked) {
+      throw new InteractionResourceConflictError(
+        "Protected-fill unknown outcome lost its operation fence",
+      );
+    }
+    const metadata = protectedAuthOperationMetadata(operation.metadata);
+    const [failedRun] = await scopedDb
+      .update(schema.authRuns)
+      .set({
+        state: "failed",
+        choices: [],
+        pendingFields: [],
+        externalAction: null,
+        verifiedUrl: null,
+        failureCode: input.errorCode,
+        version: sql`${schema.authRuns.version} + 1`,
+        updatedAt: sql`now()`,
+        settledAt: sql`now()`,
+      })
+      .where(
+        and(
+          eq(schema.authRuns.workspaceId, input.workspaceId),
+          eq(schema.authRuns.id, input.authRunId),
+          eq(schema.authRuns.version, metadata.authRunVersion),
+          sql`${schema.authRuns.settledAt} is null`,
+        ),
+      )
+      .returning();
+    if (failedRun) {
+      await projectSettledAuthRunHealth(scopedDb, {
+        run: failedRun,
+        actorSubjectId: input.actorSubjectId,
+      });
+    }
+    await advanceWorkspaceInteractionRevision(scopedDb, input.accountId, input.workspaceId);
+  });
+}
+
+function assertProtectedFillOperationBinding(
+  operation: ResourceOperationRow,
+  input: { authRunId: string; actorSubjectId: string },
+): void {
+  if (
+    operation.resourceKind !== "auth_run" ||
+    operation.resourceId !== input.authRunId ||
+    operation.kind !== "protected_fill" ||
+    operation.actorSubjectId !== input.actorSubjectId
+  ) {
+    throw new InteractionResourceConflictError(
+      "Operation id is bound to another protected-fill request",
+    );
+  }
+}
+
+export async function verifyAuthRun(
+  db: Database,
+  input: InteractionMutationScope & {
+    authRunId: string;
+    controllerGeneration: string;
+    targetId: string;
+    targetGeneration: string;
+    documentGeneration: string | null;
+    url: string;
+  } & VerifyAuthRunRequestValue,
+): Promise<AuthRunMutationResponseValue> {
+  const request = VerifyAuthRunRequest.parse({
+    operationId: input.operationId,
+    expectedVersion: input.expectedVersion,
+  });
+  const digest = operationDigest({
+    version: 1,
+    authRunId: input.authRunId,
+    controllerGeneration: input.controllerGeneration,
+    targetId: input.targetId,
+    targetGeneration: input.targetGeneration,
+    documentGeneration: input.documentGeneration,
+    url: input.url,
+    expectedVersion: request.expectedVersion,
+    actorSubjectId: input.actorSubjectId,
+  });
+  return await withRlsContext(db, input, async (scopedDb) => {
+    await assertWorkspaceAccount(scopedDb, input.accountId, input.workspaceId);
+    await lockOperation(scopedDb, request.operationId);
+    const existing = await loadOperation(scopedDb, input.workspaceId, request.operationId);
+    if (existing) {
+      assertOperation(existing, {
+        resourceKind: "auth_run",
+        resourceId: input.authRunId,
+        kind: "verify",
+        requestDigest: digest,
+        actorSubjectId: input.actorSubjectId,
+      });
+      return {
+        ...AuthRunMutationResponse.parse(existing.result),
+        replayed: true,
+      };
+    }
+    const [run] = await scopedDb
+      .select()
+      .from(schema.authRuns)
+      .where(
+        and(
+          eq(schema.authRuns.workspaceId, input.workspaceId),
+          eq(schema.authRuns.id, input.authRunId),
+        ),
+      )
+      .for("update")
+      .limit(1);
+    if (!run) throw new InteractionResourceNotFoundError("Auth run not found");
+    if (run.version !== request.expectedVersion) {
+      throw new InteractionResourceConflictError("Auth run changed before verification");
+    }
+    if (
+      run.controllerGeneration !== input.controllerGeneration ||
+      run.targetId !== input.targetId ||
+      run.targetGeneration !== input.targetGeneration
+    ) {
+      throw new InteractionResourceConflictError("Verification targets another browser tab");
+    }
+    const connection = await getSiteAuthConnectionRow(
+      scopedDb,
+      input.workspaceId,
+      run.siteAuthConnectionId,
+    );
+    const verified = connection.verificationUrlPrefixes.some((prefix) =>
+      input.url.startsWith(prefix),
+    );
+    let resultRun = run;
+    if (verified) {
+      if (run.settledAt && run.state !== "verified") {
+        throw new InteractionResourceStateError("Auth run is already settled");
+      }
+      if (!run.settledAt) {
+        const [updated] = await scopedDb
+          .update(schema.authRuns)
+          .set({
+            state: "verified",
+            choices: [],
+            pendingFields: [],
+            externalAction: null,
+            interventionId: null,
+            documentGeneration: input.documentGeneration,
+            verifiedUrl: input.url,
+            failureCode: null,
+            version: run.version + 1,
+            updatedAt: sql`now()`,
+            settledAt: sql`now()`,
+          })
+          .where(
+            and(
+              eq(schema.authRuns.workspaceId, input.workspaceId),
+              eq(schema.authRuns.id, input.authRunId),
+              eq(schema.authRuns.version, request.expectedVersion),
+            ),
+          )
+          .returning();
+        if (!updated)
+          throw new InteractionResourceConflictError("Auth verification lost its fence");
+        resultRun = updated;
+        await projectSettledAuthRunHealth(scopedDb, {
+          run: updated,
+          actorSubjectId: input.actorSubjectId,
+        });
+      }
+    }
     const response = AuthRunMutationResponse.parse({
-      run: authRunFromRow(row),
+      run: authRunFromRow(resultRun),
       operationId: request.operationId,
       replayed: false,
     });
@@ -1311,13 +3482,15 @@ export async function reportAuthRun(
       workspaceId: input.workspaceId,
       resourceKind: "auth_run",
       resourceId: input.authRunId,
-      kind: "report",
+      kind: "verify",
       requestDigest: digest,
-      resultVersion: row.version,
+      resultVersion: resultRun.version,
       result: response,
       actorSubjectId: input.actorSubjectId,
     });
-    await advanceWorkspaceInteractionRevision(scopedDb, input.accountId, input.workspaceId);
+    if (verified && !run.settledAt) {
+      await advanceWorkspaceInteractionRevision(scopedDb, input.accountId, input.workspaceId);
+    }
     return response;
   });
 }
@@ -1493,12 +3666,16 @@ async function settleLinkedAuthRun(
         eq(schema.authRuns.interventionId, input.interventionId),
       ),
     )
-    .returning({ id: schema.authRuns.id });
+    .returning();
   if (!settled) {
     throw new InteractionResourceConflictError(
       "Linked auth run changed before intervention settlement",
     );
   }
+  await projectSettledAuthRunHealth(db, {
+    run: settled,
+    actorSubjectId: run.createdBySubjectId,
+  });
 }
 
 async function expireInterventionsInScope(
@@ -1517,6 +3694,10 @@ async function expireInterventionsInScope(
       and(
         eq(schema.interactionInterventions.workspaceId, input.workspaceId),
         eq(schema.interactionInterventions.status, "open"),
+        // Model-owned interventions are also pending approvals. Only the
+        // owning session workflow may expire those rows, because it must append
+        // the exact rejection that resumes the frozen RunState atomically.
+        sql`${schema.interactionInterventions.originatingToolCallId} is null`,
         sql`${schema.interactionInterventions.expiresAt} <= now()`,
       ),
     )
@@ -1586,6 +3767,242 @@ export async function getInteractionIntervention(
   });
 }
 
+export type AttemptInteractionInterventionRequest = {
+  id: string;
+  operationId: string;
+  accountId: string;
+  workspaceId: string;
+  originatingSessionId: string;
+  originatingTurnId: string;
+  originatingAttemptId: string;
+  toolCallId: string;
+  input: RequestHumanInteractionToolInputValue;
+};
+
+/**
+ * Persist one interaction interruption inside the same transaction as its
+ * frozen Agent RunState. This is deliberately transaction-local: callers must
+ * already hold the session/turn/attempt settlement locks and RLS context.
+ */
+export async function persistAttemptInteractionInterventionInTransaction(
+  db: Database,
+  raw: AttemptInteractionInterventionRequest,
+): Promise<InteractionInterventionValue> {
+  const input = RequestHumanInteractionToolInput.parse(raw.input);
+  if (Buffer.byteLength(raw.toolCallId) < 1 || Buffer.byteLength(raw.toolCallId) > 1_024) {
+    throw new InteractionResourceStateError("Interaction tool call id is invalid");
+  }
+  if (input.operation === "wait") {
+    const [current] = await db
+      .select()
+      .from(schema.interactionInterventions)
+      .where(
+        and(
+          eq(schema.interactionInterventions.workspaceId, raw.workspaceId),
+          eq(schema.interactionInterventions.id, input.interventionId),
+        ),
+      )
+      .for("update")
+      .limit(1);
+    if (!current) throw new InteractionResourceNotFoundError("Interaction intervention not found");
+    if (current.status !== "open" || current.expiresAt.getTime() <= Date.now()) {
+      throw new InteractionResourceStateError("Interaction intervention is no longer open");
+    }
+    if (
+      current.originatingSessionId !== raw.originatingSessionId ||
+      current.originatingTurnId !== raw.originatingTurnId
+    ) {
+      throw new InteractionResourceConflictError(
+        "Interaction intervention belongs to another agent operation",
+      );
+    }
+    if (
+      current.originatingToolCallId !== null &&
+      current.originatingToolCallId !== raw.toolCallId
+    ) {
+      throw new InteractionResourceConflictError(
+        "Interaction intervention already has another waiting tool call",
+      );
+    }
+    const row =
+      current.originatingToolCallId === raw.toolCallId
+        ? current
+        : (
+            await db
+              .update(schema.interactionInterventions)
+              .set({
+                originatingToolCallId: raw.toolCallId,
+                updatedAt: sql`now()`,
+              })
+              .where(
+                and(
+                  eq(schema.interactionInterventions.workspaceId, raw.workspaceId),
+                  eq(schema.interactionInterventions.id, current.id),
+                  eq(schema.interactionInterventions.version, current.version),
+                  eq(schema.interactionInterventions.status, "open"),
+                  sql`${schema.interactionInterventions.originatingToolCallId} is null`,
+                ),
+              )
+              .returning()
+          )[0];
+    if (!row) throw new InteractionResourceConflictError("Intervention wait lost its fence");
+    return interventionFromRow(row);
+  }
+
+  await assertActiveInteractionResource(db, {
+    workspaceId: raw.workspaceId,
+    resourceKind: input.resourceKind,
+    resourceId: input.resourceId,
+    expectedControllerGeneration: input.expectedControllerGeneration,
+  });
+  let authRun: AuthRunRow | null = null;
+  if (input.authRunId) {
+    if (input.resourceKind !== "browser_session") {
+      throw new InteractionResourceStateError("Only browser interventions can belong to auth runs");
+    }
+    authRun = await loadAuthRunRow(db, raw.workspaceId, input.authRunId);
+    if (!authRun) throw new InteractionResourceNotFoundError("Auth run not found");
+    if (
+      authRun.browserSessionId !== input.resourceId ||
+      authRun.targetId !== input.targetId ||
+      authRun.controllerGeneration !== input.expectedControllerGeneration ||
+      authRun.targetGeneration !== input.expectedTargetGeneration ||
+      authRun.documentGeneration !== input.expectedDocumentGeneration ||
+      authRun.settledAt
+    ) {
+      throw new InteractionResourceConflictError(
+        "Interaction intervention does not match the active auth run",
+      );
+    }
+  }
+  const [existing] = await db
+    .select()
+    .from(schema.interactionInterventions)
+    .where(
+      and(
+        eq(schema.interactionInterventions.workspaceId, raw.workspaceId),
+        eq(schema.interactionInterventions.id, raw.id),
+      ),
+    )
+    .for("update")
+    .limit(1);
+  if (existing) {
+    if (
+      existing.operationId !== raw.operationId ||
+      existing.originatingSessionId !== raw.originatingSessionId ||
+      existing.originatingTurnId !== raw.originatingTurnId ||
+      existing.originatingToolCallId !== raw.toolCallId ||
+      existing.resourceKind !== input.resourceKind ||
+      existing.resourceId !== input.resourceId ||
+      existing.targetId !== input.targetId ||
+      existing.controllerGeneration !== input.expectedControllerGeneration ||
+      existing.targetGeneration !== input.expectedTargetGeneration ||
+      existing.documentGeneration !== input.expectedDocumentGeneration ||
+      existing.kind !== input.kind ||
+      existing.reason !== input.reason ||
+      existing.authRunId !== (input.authRunId ?? null) ||
+      existing.status !== "open"
+    ) {
+      throw new InteractionResourceConflictError("Interaction interruption replay changed");
+    }
+    return interventionFromRow(existing);
+  }
+  const [row] = await db
+    .insert(schema.interactionInterventions)
+    .values({
+      id: raw.id,
+      accountId: raw.accountId,
+      workspaceId: raw.workspaceId,
+      resourceKind: input.resourceKind,
+      resourceId: input.resourceId,
+      targetId: input.targetId,
+      controllerGeneration: input.expectedControllerGeneration,
+      targetGeneration: input.expectedTargetGeneration,
+      documentGeneration: input.expectedDocumentGeneration,
+      kind: input.kind,
+      reason: input.reason,
+      authRunId: input.authRunId ?? null,
+      originatingSessionId: raw.originatingSessionId,
+      originatingTurnId: raw.originatingTurnId,
+      originatingAttemptId: raw.originatingAttemptId,
+      originatingToolOperationId: raw.operationId,
+      originatingToolCallId: raw.toolCallId,
+      operationId: raw.operationId,
+      expiresAt: sql`now() + (${input.expiresInSeconds} * interval '1 second')`,
+    })
+    .returning();
+  if (!row) throw new Error("Interaction interruption insert returned no row");
+  if (authRun) {
+    const linked = await db
+      .update(schema.authRuns)
+      .set({
+        interventionId: row.id,
+        version: authRun.version + 1,
+        updatedAt: sql`now()`,
+      })
+      .where(
+        and(
+          eq(schema.authRuns.workspaceId, raw.workspaceId),
+          eq(schema.authRuns.id, authRun.id),
+          eq(schema.authRuns.version, authRun.version),
+          sql`${schema.authRuns.settledAt} is null`,
+        ),
+      )
+      .returning({ id: schema.authRuns.id });
+    if (linked.length !== 1) {
+      throw new InteractionResourceConflictError("Auth run changed before intervention link");
+    }
+  }
+  await advanceWorkspaceInteractionRevision(db, raw.accountId, raw.workspaceId);
+  return interventionFromRow(row);
+}
+
+export async function getInteractionInterventionApprovalTarget(
+  db: Database,
+  input: { accountId: string; workspaceId: string; interventionId: string },
+): Promise<{ sessionId: string; toolCallId: string } | null> {
+  return await withRlsContext(db, input, async (scopedDb) => {
+    const row = await loadInterventionRow(scopedDb, input.workspaceId, input.interventionId);
+    return row?.originatingToolCallId
+      ? {
+          sessionId: row.originatingSessionId,
+          toolCallId: row.originatingToolCallId,
+        }
+      : null;
+  });
+}
+
+export async function getInteractionInterventionResumeForEvent(
+  db: Database,
+  workspaceId: string,
+  sessionId: string,
+  event: Pick<SessionEvent, "type" | "payload">,
+): Promise<{
+  toolCallId: string;
+  intervention: InteractionInterventionValue;
+} | null> {
+  if (event.type !== "user.approvalDecision") return null;
+  const payload = event.payload as { approvalId?: unknown; decision?: unknown };
+  if (typeof payload.approvalId !== "string" || payload.decision !== "approve") return null;
+  const [row] = await db
+    .select()
+    .from(schema.interactionInterventions)
+    .where(
+      and(
+        eq(schema.interactionInterventions.workspaceId, workspaceId),
+        eq(schema.interactionInterventions.originatingSessionId, sessionId),
+        eq(schema.interactionInterventions.originatingToolCallId, payload.approvalId),
+      ),
+    )
+    .orderBy(asc(schema.interactionInterventions.createdAt))
+    .limit(1);
+  if (!row || row.status !== "completed") return null;
+  return {
+    toolCallId: payload.approvalId,
+    intervention: interventionFromRow(row),
+  };
+}
+
 export async function createInteractionIntervention(
   db: Database,
   input: InteractionMutationScope &
@@ -1744,7 +4161,7 @@ export async function createInteractionIntervention(
   }
 }
 
-export async function resolveInteractionIntervention(
+export async function resolveInteractionInterventionInTransaction(
   db: Database,
   input: InteractionMutationScope & {
     interventionId: string;
@@ -1762,92 +4179,152 @@ export async function resolveInteractionIntervention(
     request: digestRequest,
     actorSubjectId: input.actorSubjectId,
   });
-  return await withRlsContext(db, input, async (scopedDb) => {
-    await assertWorkspaceAccount(scopedDb, input.accountId, input.workspaceId);
-    await lockOperation(scopedDb, request.operationId);
-    const existing = await loadOperation(scopedDb, input.workspaceId, request.operationId);
-    if (existing) {
-      assertOperation(existing, {
-        resourceKind: "intervention",
-        resourceId: input.interventionId,
-        kind: "resolve",
-        requestDigest: digest,
-        actorSubjectId: input.actorSubjectId,
-      });
-      const response = InteractionInterventionMutationResponse.parse(existing.result);
-      return { ...response, replayed: true };
-    }
-    const [current] = await scopedDb
-      .select()
-      .from(schema.interactionInterventions)
-      .where(
-        and(
-          eq(schema.interactionInterventions.workspaceId, input.workspaceId),
-          eq(schema.interactionInterventions.id, input.interventionId),
-        ),
-      )
-      .for("update")
-      .limit(1);
-    if (!current) {
-      throw new InteractionResourceNotFoundError("Interaction intervention not found");
-    }
-    if (current.version !== request.expectedVersion) {
-      throw new InteractionResourceConflictError(
-        "Interaction intervention changed before this response",
-      );
-    }
-    if (current.status !== "open") {
-      throw new InteractionResourceStateError("Interaction intervention is already settled");
-    }
-    const expired = current.expiresAt.getTime() <= Date.now();
-    const status = expired ? "expired" : request.outcome;
-    const [row] = await scopedDb
-      .update(schema.interactionInterventions)
-      .set({
-        status,
-        responseActorSubjectId: expired ? null : input.actorSubjectId,
-        version: current.version + 1,
-        updatedAt: sql`now()`,
-        settledAt: sql`now()`,
-      })
-      .where(
-        and(
-          eq(schema.interactionInterventions.workspaceId, input.workspaceId),
-          eq(schema.interactionInterventions.id, input.interventionId),
-          eq(schema.interactionInterventions.version, request.expectedVersion),
-          eq(schema.interactionInterventions.status, "open"),
-        ),
-      )
-      .returning();
-    if (!row) {
-      throw new InteractionResourceConflictError("Intervention response lost its fence");
-    }
-    await settleLinkedAuthRun(scopedDb, {
-      workspaceId: input.workspaceId,
-      authRunId: row.authRunId,
-      interventionId: row.id,
-      outcome: status,
-    });
-    const response = InteractionInterventionMutationResponse.parse({
-      intervention: interventionFromRow(row),
-      operationId: request.operationId,
-      replayed: false,
-    });
-    await insertCompletedOperation(scopedDb, {
-      operationId: request.operationId,
-      accountId: input.accountId,
-      workspaceId: input.workspaceId,
+  const scopedDb = db;
+  await assertWorkspaceAccount(scopedDb, input.accountId, input.workspaceId);
+  await lockOperation(scopedDb, request.operationId);
+  const existing = await loadOperation(scopedDb, input.workspaceId, request.operationId);
+  if (existing) {
+    assertOperation(existing, {
       resourceKind: "intervention",
       resourceId: input.interventionId,
       kind: "resolve",
       requestDigest: digest,
-      resultVersion: row.version,
-      result: response,
       actorSubjectId: input.actorSubjectId,
     });
-    await advanceWorkspaceInteractionRevision(scopedDb, input.accountId, input.workspaceId);
-    return response;
+    const response = InteractionInterventionMutationResponse.parse(existing.result);
+    return { ...response, replayed: true };
+  }
+  const [current] = await scopedDb
+    .select()
+    .from(schema.interactionInterventions)
+    .where(
+      and(
+        eq(schema.interactionInterventions.workspaceId, input.workspaceId),
+        eq(schema.interactionInterventions.id, input.interventionId),
+      ),
+    )
+    .for("update")
+    .limit(1);
+  if (!current) {
+    throw new InteractionResourceNotFoundError("Interaction intervention not found");
+  }
+  if (current.version !== request.expectedVersion) {
+    throw new InteractionResourceConflictError(
+      "Interaction intervention changed before this response",
+    );
+  }
+  if (current.status !== "open") {
+    throw new InteractionResourceStateError("Interaction intervention is already settled");
+  }
+  const expired = current.expiresAt.getTime() <= Date.now();
+  const status = expired ? "expired" : request.outcome;
+  const [row] = await scopedDb
+    .update(schema.interactionInterventions)
+    .set({
+      status,
+      responseActorSubjectId: expired ? null : input.actorSubjectId,
+      version: current.version + 1,
+      updatedAt: sql`now()`,
+      settledAt: sql`now()`,
+    })
+    .where(
+      and(
+        eq(schema.interactionInterventions.workspaceId, input.workspaceId),
+        eq(schema.interactionInterventions.id, input.interventionId),
+        eq(schema.interactionInterventions.version, request.expectedVersion),
+        eq(schema.interactionInterventions.status, "open"),
+      ),
+    )
+    .returning();
+  if (!row) {
+    throw new InteractionResourceConflictError("Intervention response lost its fence");
+  }
+  await settleLinkedAuthRun(scopedDb, {
+    workspaceId: input.workspaceId,
+    authRunId: row.authRunId,
+    interventionId: row.id,
+    outcome: status,
+  });
+  const response = InteractionInterventionMutationResponse.parse({
+    intervention: interventionFromRow(row),
+    operationId: request.operationId,
+    replayed: false,
+  });
+  await insertCompletedOperation(scopedDb, {
+    operationId: request.operationId,
+    accountId: input.accountId,
+    workspaceId: input.workspaceId,
+    resourceKind: "intervention",
+    resourceId: input.interventionId,
+    kind: "resolve",
+    requestDigest: digest,
+    resultVersion: row.version,
+    result: response,
+    actorSubjectId: input.actorSubjectId,
   });
+  await advanceWorkspaceInteractionRevision(scopedDb, input.accountId, input.workspaceId);
+  return response;
+}
+
+export async function resolveInteractionIntervention(
+  db: Database,
+  input: InteractionMutationScope & {
+    interventionId: string;
+  } & ResolveInteractionInterventionRequestValue,
+): Promise<InteractionInterventionMutationResponseValue> {
+  return await withRlsContext(
+    db,
+    input,
+    async (scopedDb) => await resolveInteractionInterventionInTransaction(scopedDb, input),
+  );
+}
+
+/**
+ * Cancel every still-open intervention created by a logical agent turn when
+ * that turn becomes terminal. The caller already owns the turn-settlement
+ * transaction, so no resource can outlive the terminal session truth.
+ */
+export async function cancelTurnInteractionInterventionsInTransaction(
+  db: Database,
+  input: {
+    accountId: string;
+    workspaceId: string;
+    sessionId: string;
+    turnId: string;
+  },
+): Promise<number> {
+  const cancelled = await db
+    .update(schema.interactionInterventions)
+    .set({
+      status: "cancelled",
+      version: sql`${schema.interactionInterventions.version} + 1`,
+      updatedAt: sql`now()`,
+      settledAt: sql`now()`,
+    })
+    .where(
+      and(
+        eq(schema.interactionInterventions.workspaceId, input.workspaceId),
+        eq(schema.interactionInterventions.originatingSessionId, input.sessionId),
+        eq(schema.interactionInterventions.originatingTurnId, input.turnId),
+        eq(schema.interactionInterventions.status, "open"),
+      ),
+    )
+    .returning({
+      id: schema.interactionInterventions.id,
+      authRunId: schema.interactionInterventions.authRunId,
+    });
+  for (const intervention of cancelled) {
+    await settleLinkedAuthRun(db, {
+      workspaceId: input.workspaceId,
+      authRunId: intervention.authRunId,
+      interventionId: intervention.id,
+      outcome: "cancelled",
+    });
+  }
+  if (cancelled.length > 0) {
+    await advanceWorkspaceInteractionRevision(db, input.accountId, input.workspaceId);
+  }
+  return cancelled.length;
 }
 
 export async function cancelOpenInteractionInterventions(