spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/functions/admin-data.ts

@@ -1,3 +1,4 @@
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/admin-data.ts"]
 /**
  * @module   admin-data
  * @audience internal
@@ -13,7 +14,6 @@
  *
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="This module handles administrative data operations within the system, providing essential functionalities for managing records and permissions."]
 // CIL[DOC-RESPONSIBILITY responsibility="This module handles administrative data operations within the system, providing essential functionalities for managing records and permissions. It serves as an API handler for various administrative actions, ensuring that only authorized users can perform updates and access sensitive data. INVARIANT: Only users with system admin privileges can execute these operations."]
 // CIL[DOC-CONTEXT module="admin-data" layer="app-specific" related_files="middleware.ts (provides request handling logic).,permissions.ts (manages access control and validation).,db.ts (interfaces with the database for data operations).,principal.ts (determines user roles and permissions)."]
@@ -62,7 +62,6 @@ import { checkTypeSlugRateLimit } from './_shared/security'
  * @stability   stable
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:permissions_all:constant" type="constant" identity="PERMISSIONS_ALL" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="PERMISSIONS_ALL constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the PERMISSIONS_ALL constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -70,11 +69,12 @@ import { checkTypeSlugRateLimit } from './_shared/security'
 // CIL[DOC-MICRO logic_summary="Implements the PERMISSIONS_ALL constant." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:PERMISSIONS_ALL:constant" type="constant" identity="PERMISSIONS_ALL" parent="~/.framework/functions/admin-data.ts"]
 const PERMISSIONS_ALL = {
   record_permissions: { all: ['create', 'read', 'update', 'delete'] },
   fields: {}
 }
-// CIL[END stable_id="~/.framework/functions/admin-data.ts:permissions_all:constant"]
+// CIL[END stable_id="~/.framework/functions/admin-data.ts:PERMISSIONS_ALL:constant"]
 // CIL[DOC-VECTOR type="context" content="purpose='PERMISSIONS_ALL defines a comprehensive set of permissions for record management, including create, read, update, and delete actions.'; No verified external callers" status="ready"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only" status="ready"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified" status="ready"]
@@ -96,7 +96,6 @@ const PERMISSIONS_ALL = {
  * @stability   stable
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:valid_entities:constant" type="constant" identity="VALID_ENTITIES" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="VALID_ENTITIES constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the VALID_ENTITIES constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -104,8 +103,9 @@ const PERMISSIONS_ALL = {
 // CIL[DOC-MICRO logic_summary="Implements the VALID_ENTITIES constant." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:VALID_ENTITIES:constant" type="constant" identity="VALID_ENTITIES" parent="~/.framework/functions/admin-data.ts"]
 const VALID_ENTITIES = ['accounts', 'people', 'items', 'threads', 'messages', 'links', 'attachments', 'watchers', 'item_progress', 'logs', 'test_runs', 'observability', 'test_cases', 'types', 'link_types', 'ai_agents', 'prompt_configs']
-// CIL[END stable_id="~/.framework/functions/admin-data.ts:valid_entities:constant"]
+// CIL[END stable_id="~/.framework/functions/admin-data.ts:VALID_ENTITIES:constant"]
 // CIL[DOC-MACRO purpose="VALID_ENTITIES constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the VALID_ENTITIES constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -134,7 +134,6 @@ const VALID_ENTITIES = ['accounts', 'people', 'items', 'threads', 'messages', 'l
  * @stability   stable
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:raw_entities:constant" type="constant" identity="RAW_ENTITIES" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="RAW_ENTITIES constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the RAW_ENTITIES constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -142,11 +141,14 @@ const VALID_ENTITIES = ['accounts', 'people', 'items', 'threads', 'messages', 'l
 // CIL[DOC-MICRO logic_summary="Implements the RAW_ENTITIES constant." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:RAW_ENTITIES:constant" type="constant" identity="RAW_ENTITIES" parent="~/.framework/functions/admin-data.ts"]
 const RAW_ENTITIES = ['logs', 'test_runs', 'observability', 'test_cases']
+// CIL[END stable_id="~/.framework/functions/admin-data.ts:RAW_ENTITIES:constant"]
 // Entities with no created_by/updated_by columns — audit stamps must be
 // omitted or writes fail with schema-cache errors.
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:UNAUDITED_ENTITIES:constant" type="constant" identity="UNAUDITED_ENTITIES" parent="~/.framework/functions/admin-data.ts"]
 const UNAUDITED_ENTITIES = ['types', 'link_types']
-// CIL[END stable_id="~/.framework/functions/admin-data.ts:raw_entities:constant"]
+// CIL[END stable_id="~/.framework/functions/admin-data.ts:UNAUDITED_ENTITIES:constant"]
 // CIL[DOC-MACRO purpose="RAW_ENTITIES constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the RAW_ENTITIES constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -175,7 +177,6 @@ const UNAUDITED_ENTITIES = ['types', 'link_types']
  * @stability   stable
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:entity_to_kind:constant" type="constant" identity="ENTITY_TO_KIND" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="ENTITY_TO_KIND constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the ENTITY_TO_KIND constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -183,6 +184,7 @@ const UNAUDITED_ENTITIES = ['types', 'link_types']
 // CIL[DOC-MICRO logic_summary="Implements the ENTITY_TO_KIND constant." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:ENTITY_TO_KIND:constant" type="constant" identity="ENTITY_TO_KIND" parent="~/.framework/functions/admin-data.ts"]
 const ENTITY_TO_KIND: Record<string, string> = {
   accounts: 'account',
   people: 'person',
@@ -194,7 +196,7 @@ const ENTITY_TO_KIND: Record<string, string> = {
   watchers: 'watcher',
   item_progress: 'item_progress'
 }
-// CIL[END stable_id="~/.framework/functions/admin-data.ts:entity_to_kind:constant"]
+// CIL[END stable_id="~/.framework/functions/admin-data.ts:ENTITY_TO_KIND:constant"]
 // CIL[DOC-VECTOR type="context" content="purpose='ENTITY_TO_KIND is a mapping of entity names to their corresponding kind identifiers.'; No verified external callers" status="ready"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only" status="ready"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified" status="ready"]
@@ -217,7 +219,6 @@ const ENTITY_TO_KIND: Record<string, string> = {
  * @calls       withAdminLogging, resolveTypeIds, getSearchField
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:list:constant" type="constant" identity="list" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="list constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the list constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -225,8 +226,9 @@ const ENTITY_TO_KIND: Record<string, string> = {
 // CIL[DOC-MICRO logic_summary="Implements the list constant." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:list:constant" type="constant" identity="list" parent="~/.framework/functions/admin-data.ts"]
 export const list = createHandler(async (ctx, _body) => {
-  const { entity, action, method, search, sort_field = 'created_at', sort_direction = 'desc', limit = 50, offset = 0, type_slug, type_slugs, view: viewSlug, flag_only, exclude_flag, ...filters } = ctx.query || {}
+  const { entity, action, method, search, sort_field = 'created_at', sort_direction = 'desc', limit = 50, offset = 0, type_slug, type_slugs, view: viewSlug, flag_only, exclude_flag, include_inactive, ...filters } = ctx.query || {}
 
   return await withAdminLogging(
     ctx,
@@ -292,6 +294,12 @@ export const list = createHandler(async (ctx, _body) => {
         }
       })
 
+      // Soft-deleted rows are hidden by default — pass is_active=false or
+      // include_inactive=true to see them.
+      if (filters.is_active === undefined && include_inactive !== 'true') {
+        query = query.eq('is_active', true)
+      }
+
       // Generic record-flag filters on the row's data jsonb. flag_only=<field>
       // returns only rows where data->>field is 'true'; exclude_flag=<field>
       // hides them (null counts as unset). Flag fields are stamped server-side
@@ -405,7 +413,6 @@ export const list = createHandler(async (ctx, _body) => {
  * @errorHandling returns null on error during data fetching.
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:attachlineage:function" type="function" identity="attachLineage" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="attachLineage function"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the attachLineage function from type-declared lineage config."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -413,6 +420,7 @@ export const list = createHandler(async (ctx, _body) => {
 // CIL[DOC-MICRO logic_summary="Reads functionality.lineage off the record's type design_schema; parents walk declared link_type then parent_fields (5-hop, visited-set cycle guard); children resolve via reverse link_type edges plus per-child-type data field lookups." notable_decisions="['link_type queries are guarded by the declared link_type, parent scan by declared parent_fields, child field lookups by declared children — a type with no lineage block attaches empty arrays with no link/data queries']"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:attachLineage:function" type="function" identity="attachLineage" parent="~/.framework/functions/admin-data.ts"]
 async function attachLineage(record: any, ctx: any): Promise<void> {
   // Lineage is declared per item type in design_schema.functionality.lineage:
   //   { parent_fields: string[], link_type: string, children: { [childTypeSlug]: field } }
@@ -516,7 +524,7 @@ async function attachLineage(record: any, ctx: any): Promise<void> {
   record.parents = parents
   record.children = children
 }
-// CIL[END stable_id="~/.framework/functions/admin-data.ts:attachlineage:function"]
+// CIL[END stable_id="~/.framework/functions/admin-data.ts:attachLineage:function"]
 // CIL[DOC-VECTOR type="context" content="purpose='The attachLineage function retrieves and attaches parent and child records to a given record based on its lineage in a hierarchical structure.'; No verified external callers" status="ready"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only" status="ready"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified" status="ready"]
@@ -540,7 +548,6 @@ async function attachLineage(record: any, ctx: any): Promise<void> {
  * @calls       withAdminLogging, ctx.db.from, sanitizeRecordData, adminDb.from, attachLineage, projectMessageForCustomer
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:get:constant" type="constant" identity="get" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="get constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the get constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -548,6 +555,7 @@ async function attachLineage(record: any, ctx: any): Promise<void> {
 // CIL[DOC-MICRO logic_summary="Implements the get constant." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:get:constant" type="constant" identity="get" parent="~/.framework/functions/admin-data.ts"]
 export const get = createHandler(async (ctx, _body) => {
   const { entity, id, view: viewSlug } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
@@ -639,7 +647,6 @@ export const get = createHandler(async (ctx, _body) => {
  * @calls       withAdminLogging, ctx.db.from, fireCreateTriggers, sanitizeRecordData
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:create:constant" type="constant" identity="create" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="create constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the create constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -647,6 +654,7 @@ export const get = createHandler(async (ctx, _body) => {
 // CIL[DOC-MICRO logic_summary="Implements the create constant." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:create:constant" type="constant" identity="create" parent="~/.framework/functions/admin-data.ts"]
 export const create = createHandler(async (ctx, body) => {
   const entity = body?.entity || ctx.query?.entity
   const type_slug = body?.type_slug
@@ -686,9 +694,14 @@ export const create = createHandler(async (ctx, body) => {
         if (entity === 'observability' && (!raw.metric_name || raw.metric_value === undefined)) { const e: any = new Error('metric_name and metric_value are required for observability'); e.statusCode = 400; throw e }
         if (entity === 'test_cases' && (!raw.slug || !raw.name)) { const e: any = new Error('slug and name are required for test_cases'); e.statusCode = 400; throw e }
 
-        const { data, error: err } = await ctx.db.from(entity).insert(raw).select().single()
+        const rawInsertDb = (ctx.principal?.isInternal || isSystemAdmin(ctx.principal)) ? adminDb : ctx.db
+        const { data, error: err } = await rawInsertDb.from(entity).insert(raw).select().single()
         if (err) throw err
-        fireCreateTriggers(entity, data.id, raw, ctx).catch(console.error)
+        // Await the trigger check: the heavy work already offloads to
+        // pipeline-runner-background, so this only adds eval + queue insert
+        // + dispatch. Detached post-response work is CPU-frozen on Netlify
+        // and silently dropped trigger fires in production.
+        await fireCreateTriggers(entity, data.id, raw, ctx).catch(console.error)
         return await sanitizeRecordData(ctx, data, entity)
       }
 
@@ -798,7 +811,9 @@ export const create = createHandler(async (ctx, body) => {
         throw e
       }
 
-      const insertDb = entity === 'accounts' ? adminDb : ctx.db
+      // Function-side permission check already ran — write via service role.
+      // ctx.db is PostgREST `authenticated` for humans, which holds SELECT only.
+      const insertDb = adminDb
 
       const { data, error: err } = await insertDb.from(entity)
         .insert(dataToInsert)
@@ -808,7 +823,7 @@ export const create = createHandler(async (ctx, body) => {
       if (err) throw err
 
       const entityData = { ...dataToInsert, id: data.id }
-      fireCreateTriggers(entity, data.id, entityData, ctx).catch(console.error)
+      await fireCreateTriggers(entity, data.id, entityData, ctx).catch(console.error)
 
       return await sanitizeRecordData(ctx, data, entity)
     }
@@ -837,7 +852,6 @@ export const create = createHandler(async (ctx, body) => {
  * @calls       withAdminLogging, validateUpdatePermissions, ctx.db.from, fireUpdateTriggers, sanitizeRecordData
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:update:constant" type="constant" identity="update" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="update constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the update constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -845,6 +859,7 @@ export const create = createHandler(async (ctx, body) => {
 // CIL[DOC-MICRO logic_summary="Implements the update constant." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:update:constant" type="constant" identity="update" parent="~/.framework/functions/admin-data.ts"]
 export const update = createHandler(async (ctx, body) => {
   const { entity, id } = ctx.query || {}
   const method = ctx.query?.method || 'PATCH'
@@ -906,7 +921,7 @@ export const update = createHandler(async (ctx, body) => {
             updated_at: new Date().toISOString()
           }
 
-      const { data, error: err } = await ctx.db.from(entity)
+      const { data, error: err } = await adminDb.from(entity)
         .update(dataToUpdate)
         .eq('id', id)
         .select()
@@ -915,7 +930,9 @@ export const update = createHandler(async (ctx, body) => {
       if (err) throw err
 
       const entityData = { ...data, ...dataToUpdate }
-      fireUpdateTriggers(entity, id, entityData, ctx).catch(console.error)
+      // Await the trigger check — see note in the create path. Detached
+      // post-response work is CPU-frozen on Netlify and drops trigger fires.
+      await fireUpdateTriggers(entity, id, entityData, ctx, existing).catch(console.error)
 
       return await sanitizeRecordData(ctx, data, entity)
     }
@@ -944,7 +961,6 @@ export const update = createHandler(async (ctx, body) => {
  * @calls       withAdminLogging, ctx.db.from, resolveFirstSurfacePermissions, entitySupportsSoftDelete, sanitizeRecordData
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:remove:constant" type="constant" identity="remove" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="remove constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the remove constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -952,6 +968,7 @@ export const update = createHandler(async (ctx, body) => {
 // CIL[DOC-MICRO logic_summary="Implements the remove constant." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:remove:constant" type="constant" identity="remove" parent="~/.framework/functions/admin-data.ts"]
 export const remove = createHandler(async (ctx, _body) => {
   const { entity, id, soft = 'true' } = ctx.query || {}
   const method = ctx.query?.method || 'DELETE'
@@ -1000,7 +1017,7 @@ export const remove = createHandler(async (ctx, _body) => {
       const isSoftDelete = soft === 'true'
 
       if (isSoftDelete && entitySupportsSoftDelete(entity)) {
-        const { data, error: err } = await ctx.db.from(entity)
+        const { data, error: err } = await adminDb.from(entity)
           .update({
             is_active: false,
             updated_by: ctx.principal?.type === 'human' ? ctx.principal.id : null,
@@ -1013,7 +1030,7 @@ export const remove = createHandler(async (ctx, _body) => {
         if (err) throw err
         return { deleted: true, soft: true, data: await sanitizeRecordData(ctx, data, entity) }
       } else {
-        const { error: err } = await ctx.db.from(entity)
+        const { error: err } = await adminDb.from(entity)
           .delete()
           .eq('id', id)
 
@@ -1047,7 +1064,6 @@ export const remove = createHandler(async (ctx, _body) => {
  * @stability   stable
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:getsearchfield:function" type="function" identity="getSearchField" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="getSearchField function"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the getSearchField function."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -1055,6 +1071,7 @@ export const remove = createHandler(async (ctx, _body) => {
 // CIL[DOC-MICRO logic_summary="Implements the getSearchField function." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:getSearchField:function" type="function" identity="getSearchField" parent="~/.framework/functions/admin-data.ts"]
 function getSearchField(entity: string): string {
   const searchFields: Record<string, string> = {
     accounts: 'display_name',
@@ -1073,7 +1090,7 @@ function getSearchField(entity: string): string {
   }
   return searchFields[entity] || 'id'
 }
-// CIL[END stable_id="~/.framework/functions/admin-data.ts:getsearchfield:function"]
+// CIL[END stable_id="~/.framework/functions/admin-data.ts:getSearchField:function"]
 // CIL[DOC-VECTOR type="context" content="purpose='Retrieves the appropriate search field name for a given entity type.'; No verified external callers" status="ready"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only" status="ready"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified" status="ready"]
@@ -1097,7 +1114,6 @@ function getSearchField(entity: string): string {
  * @stability   stable
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:entitysupportssoftdelete:function" type="function" identity="entitySupportsSoftDelete" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="entitySupportsSoftDelete function"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the entitySupportsSoftDelete function."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -1105,11 +1121,12 @@ function getSearchField(entity: string): string {
 // CIL[DOC-MICRO logic_summary="Implements the entitySupportsSoftDelete function." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:entitySupportsSoftDelete:function" type="function" identity="entitySupportsSoftDelete" parent="~/.framework/functions/admin-data.ts"]
 function entitySupportsSoftDelete(entity: string): boolean {
   const softDeleteEntities = ['accounts', 'people', 'items', 'threads', 'messages', 'watchers', 'item_progress', 'test_cases']
   return softDeleteEntities.includes(entity)
 }
-// CIL[END stable_id="~/.framework/functions/admin-data.ts:entitysupportssoftdelete:function"]
+// CIL[END stable_id="~/.framework/functions/admin-data.ts:entitySupportsSoftDelete:function"]
 // CIL[DOC-VECTOR type="context" content="purpose='Determines if a given entity supports soft deletion by checking against a predefined list of entities.'; No verified external callers" status="ready"]
 // CIL[DOC-VECTOR type="blast_radius" content="No direct caller data from CIL graph; local impact only" status="ready"]
 // CIL[DOC-VECTOR type="configuration" content="No environment or build configuration dependencies identified" status="ready"]
@@ -1132,7 +1149,6 @@ function entitySupportsSoftDelete(entity: string): boolean {
  * @calls       withAdminLogging, ctx.db.from
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:stats:constant" type="constant" identity="stats" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="stats constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the stats constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -1140,6 +1156,7 @@ function entitySupportsSoftDelete(entity: string): boolean {
 // CIL[DOC-MICRO logic_summary="Implements the stats constant." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:stats:constant" type="constant" identity="stats" parent="~/.framework/functions/admin-data.ts"]
 export const stats = createHandler(async (ctx, _body) => {
   const { entity } = ctx.query || {}
   const method = ctx.query?.method || 'GET'
@@ -1188,7 +1205,6 @@ export const stats = createHandler(async (ctx, _body) => {
  * @calls       list, get, stats, create, update, remove
  * @cil-generated
  */
-// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/admin-data.ts"]
 // CIL[DOC-MACRO purpose="handler constant"]
 // CIL[DOC-RESPONSIBILITY responsibility="Implements the handler constant."]
 // CIL[DOC-CONTEXT module=".framework/functions/admin-data.ts" layer="app-specific" related_files=""]
@@ -1196,6 +1212,7 @@ export const stats = createHandler(async (ctx, _body) => {
 // CIL[DOC-MICRO logic_summary="Implements the handler constant." notable_decisions="[]"]
 // CIL[DOC-CONFIDENCE pass="first" score="0.8" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
+// CIL[BEGIN stable_id="~/.framework/functions/admin-data.ts:handler:constant" type="constant" identity="handler" parent="~/.framework/functions/admin-data.ts"]
 export const handler = createHandler(async (ctx, body) => {
   const { action } = ctx.query || {}
   const method = ctx.query?.method || 'GET'

package/.framework/functions/ai-agents.ts

@@ -30,7 +30,7 @@ import { adminDb } from './_shared/db'
 import { emitLog } from './_shared/audit'
 import { isSystemAdmin } from './_shared/principal'
 import { PermissionEngine, sanitizeRecordData } from './_shared/permissions'
-import { runAgent, kickAgentEpisode } from './_shared/agent-runner'
+import { runAgent, claimAgentEpisode, acquireEpisodeLease } from './_shared/agent-runner'
 import { checkRateLimit } from './_shared/rate-limit'
 import { detectInjection, emitSecurityEvent, getAppSecurityConfig } from './_shared/security'
 // CIL[END stable_id="~/.framework/functions/ai-agents.ts:module_header:module_header"]
@@ -244,7 +244,8 @@ export const create = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
-  const { data, error: err } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data, error: err } = await db
     .from('ai_agents')
     .insert({
       app_id: app_id || null,
@@ -258,7 +259,7 @@ export const create = createHandler(async (ctx, body) => {
       capabilities: capabilities || [],
       constraints: constraints || {},
       metadata: metadata || {},
-      created_by: ctx.principal.id
+      created_by: ctx.principal.type === 'human' ? ctx.principal.id : null
     })
     .select()
     .single()
@@ -325,7 +326,8 @@ export const update = createHandler(async (ctx, body) => {
     if (updates[key] !== undefined) updateData[key] = updates[key]
   }
 
-  const { data, error: err } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data, error: err } = await db
     .from('ai_agents')
     .update(updateData)
     .eq('id', id)
@@ -383,7 +385,8 @@ export const remove = createHandler(async (ctx, _body) => {
     throw new Error('Agent ID is required')
   }
 
-  const { data: current } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data: current } = await db
     .from('ai_agents')
     .select('id, name')
     .eq('id', id)
@@ -391,7 +394,7 @@ export const remove = createHandler(async (ctx, _body) => {
 
   if (!current) throw new Error('Agent not found')
 
-  const { error: err } = await ctx.db
+  const { error: err } = await db
     .from('ai_agents')
     .delete()
     .eq('id', id)
@@ -449,7 +452,8 @@ export const run = createHandler(async (ctx, body) => {
     throw new Error('User context (person and account) required')
   }
 
-  const { data, error: err } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data, error: err } = await db
     .from('threads')
     .select('*, type:types(*)')
     .eq('id', thread_id)
@@ -479,20 +483,27 @@ export const run = createHandler(async (ctx, body) => {
     }
   }
 
+  // Episode mode runs inline up to this budget — the first turns execute
+  // at full request CPU, then the client's step loop continues the
+  // episode under the same lease. Sized to leave headroom under the
+  // platform's synchronous request limit (~26s) even with a slow turn.
+  const EPISODE_INLINE_BUDGET_MS = 8000
+
   const runMode = (mode as 'step' | 'complete' | 'episode') || 'complete'
 
-  // Episode single-flight: the in-flight driver stamps driver_id +
-  // driver_heartbeat_at into research_state. A different driver asking to
-  // step/kick while the lease is fresh gets 'running' instead of a second
-  // interleaved write pass. The owner itself is never refused (its own
-  // staleness check is finer-grained), and a lease expires after
-  // DRIVER_LEASE_MS so a crashed driver can't wedge the thread.
-  const DRIVER_LEASE_MS = 60000
+  // Episode single-flight: arbitration is the atomic episode_leases RPC
+  // (migration 063) — a claim INSERTs/locks the thread's lease row in one
+  // statement, so two entry paths can never both pass. The same driver
+  // re-acquiring renews; a different live driver is refused 'running';
+  // an expired lease is taken over so a crashed driver can't wedge the
+  // thread. When the RPC is absent (un-migrated deployment) the legacy
+  // non-atomic research_state check below runs instead.
   const existingState = (data as any)?.data?.research_state
   const heartbeatAt = Date.parse(existingState?.driver_heartbeat_at || '')
   const leaseHolder = existingState?.driver_id
   const callerToken = (body?.driver_token as string) || null
   const callerId = callerToken || ctx.requestId
+  const DRIVER_LEASE_MS = 60000
   const leaseLive =
     !!leaseHolder &&
     leaseHolder !== callerId &&
@@ -501,32 +512,91 @@ export const run = createHandler(async (ctx, body) => {
     Number.isFinite(heartbeatAt) &&
     Date.now() - heartbeatAt < DRIVER_LEASE_MS
 
-  if ((runMode === 'step' || runMode === 'complete') && leaseLive) {
-    return { ok: true, thread_id, status: 'running', driver_id: leaseHolder }
-  }
-
   if (runMode === 'episode') {
-    if (leaseLive) {
-      return { ok: true, thread_id, status: 'running', detached: true, already_running: true }
+    // Episode mode claims the lease and runs the first turns INLINE
+    // (deadline-bounded complete mode) — detached 'void runAgent' work is
+    // CPU-throttled after the response flush on serverless platforms
+    // (~37s dead window observed before its first persisted message),
+    // which is exactly the stall the caller's quiet-window then "rescues"
+    // by double-driving. stealDetached lets this request take over from
+    // a 'detached:' background kick instantly; the fenced driver aborts
+    // at its next heartbeat without side effects.
+    const kick = await claimAgentEpisode(thread_id, user_message || '', ctx, callerId, (data as any)?.data, { stealDetached: true })
+    if (!kick.claimed && kick.already_done) {
+      // Replay of an already-answered question — return the episode's
+      // existing final rather than 'running' so callers don't poll for
+      // work that isn't coming.
+      const { data: lastOutbound } = await adminDb
+        .from('messages')
+        .select('id, content, data')
+        .eq('thread_id', thread_id)
+        .eq('direction', 'outbound')
+        .order('created_at', { ascending: false })
+        .limit(1)
+      const final = Array.isArray(lastOutbound) ? lastOutbound[0] : lastOutbound
+      return {
+        ok: true,
+        thread_id,
+        status: 'complete',
+        already_done: true,
+        driver_id: kick.driver_id,
+        message_id: final?.id || null,
+        content: final?.content || '',
+        message_type: final?.data?.message_type || null,
+        data: final?.data || null,
+        agent_id: final?.data?.agent_id || (data as any)?.data?.agent_id || null,
+        prompt_config_id: final?.data?.prompt_config_id || (data as any)?.data?.prompt_config_id || null,
+      }
     }
-    // Debit agent_step only when a new driver will actually start work —
-    // lease-refused requests and ticket-creation kicks already debited or
-    // started nothing, and counting them would double-charge each episode.
-    await checkRateLimit(ctx, 'agent_step')
-    // Claim the lease before detaching so a step request landing during
-    // resolveAgentConfig still sees a live driver. Shared implementation lives
-    // in kickAgentEpisode (also used by ticket-creation handlers).
-    const leaseId = callerToken || ctx.requestId
-    const kick = await kickAgentEpisode(thread_id, user_message || '', ctx, leaseId, (data as any)?.data)
     if (!kick.claimed) {
-      return { ok: true, thread_id, status: 'running', detached: true, already_running: true }
+      return { ok: true, thread_id, status: 'running', already_running: true, driver_id: kick.driver_id }
+    }
+    // Debit agent_step only after a claim — refused requests start
+    // nothing and must not double-charge the episode.
+    await checkRateLimit(ctx, 'agent_step')
+    const message = await runAgent(thread_id, user_message || '', ctx, 'complete', kick.driver_id || callerToken || undefined, kick.lease_token, { deadlineMs: EPISODE_INLINE_BUDGET_MS })
+
+    const { data: updatedThread } = await adminDb
+      .from('threads')
+      .select('data')
+      .eq('id', thread_id)
+      .single()
+    const state = updatedThread?.data?.research_state || {}
+    return {
+      ok: true,
+      thread_id,
+      detached: false,
+      message_id: message?.id || null,
+      status: state.status || (message ? 'complete' : 'failed'),
+      turn_count: state.turn_count ?? 0,
+      content: message?.content || '',
+      message_type: message?.data?.message_type || null,
+      data: message?.data || null,
+      agent_id: message?.data?.agent_id || updatedThread?.data?.agent_id || null,
+      prompt_config_id: message?.data?.prompt_config_id || updatedThread?.data?.prompt_config_id || null,
     }
-    return { ok: true, thread_id, status: 'running', detached: true }
   }
 
-  // step/complete modes debit here — same rule: only when work will start.
+  // step/complete: claim the episode lease for this driver. 'held' means
+  // another live driver owns the episode — the caller watches persisted
+  // state instead of interleaving writes. A claimed lease survives a
+  // nonterminal step return so the same driver's next call renews it.
+  // stealDetached lets a request driver take over from a 'detached:'
+  // background kick without waiting out the TTL.
+  const claim = await acquireEpisodeLease(thread_id, ctx.accountId, callerId, undefined, true)
+  let leaseToken: string | undefined
+  if (claim?.outcome === 'held') {
+    return { ok: true, thread_id, status: 'running', driver_id: claim.holder_driver_id }
+  }
+  if (claim === null && leaseLive) {
+    return { ok: true, thread_id, status: 'running', driver_id: leaseHolder }
+  }
+  if (claim?.outcome === 'claimed') leaseToken = claim.lease_token
+
+  // step/complete modes debit here — only when work will start, so
+  // lease-refused requests never double-charge an episode.
   await checkRateLimit(ctx, 'agent_step')
-  const message = await runAgent(thread_id, user_message || '', ctx, runMode, callerToken || undefined)
+  const message = await runAgent(thread_id, user_message || '', ctx, runMode, callerId, leaseToken)
 
   const { data: updatedThread } = await adminDb
     .from('threads')