spine-framework 0.4.3 → 0.5.0-rc.4

package/.framework/functions/triggers.ts

@@ -248,7 +248,8 @@ export const getExecutions = createHandler(async (ctx, body) => {
     throw new Error('Account context required')
   }
 
-  const { data, error: err } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data, error: err } = await db
     .from('trigger_executions')
     .select('*')
     .eq('trigger_id', trigger_id)
@@ -275,7 +276,7 @@ export const getExecutions = createHandler(async (ctx, body) => {
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 export const create = createHandler(async (ctx, body) => {
-  const { app_id, name, description, event_type, pipeline_id, config, metadata } = body
+  const { app_id, name, description, event_type, trigger_type, pipeline_id, config, metadata } = body
 
   if (!name || !event_type || !pipeline_id) {
     throw new Error('name, event_type, and pipeline_id are required')
@@ -305,7 +306,8 @@ export const create = createHandler(async (ctx, body) => {
     }
   }
 
-  const { data, error: err } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data, error: err } = await db
     .from('triggers')
     .insert({
       app_id: app_id || null,
@@ -316,7 +318,8 @@ export const create = createHandler(async (ctx, body) => {
       pipeline_id,
       config: config || {},
       metadata: metadata || {},
-      created_by: ctx.principal.id
+      trigger_type: trigger_type || 'event',
+      created_by: ctx.principal.type === 'human' ? ctx.principal.id : null
     })
     .select()
     .single()
@@ -353,13 +356,14 @@ export const update = createHandler(async (ctx, body) => {
     throw new Error('Trigger ID is required')
   }
 
-  const allowed = ['name', 'description', 'config', 'pipeline_id', 'metadata', 'is_active', 'event_type', 'app_id']
+  const allowed = ['name', 'description', 'config', 'pipeline_id', 'metadata', 'is_active', 'event_type', 'trigger_type', 'app_id']
   const updateData: Record<string, any> = { updated_at: new Date().toISOString() }
   for (const key of allowed) {
     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('triggers')
     .update(updateData)
     .eq('id', id)
@@ -397,7 +401,8 @@ export const remove = createHandler(async (ctx, body) => {
     throw new Error('Trigger ID is required')
   }
 
-  const { data: existing } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data: existing } = await db
     .from('triggers')
     .select('name, event_type')
     .eq('id', id)
@@ -407,9 +412,9 @@ export const remove = createHandler(async (ctx, body) => {
     throw new Error('Trigger not found')
   }
 
-  const { error: err } = await ctx.db
+  const { error: err } = await db
     .from('triggers')
-    .update({ 
+    .update({
       is_active: false,
       updated_at: new Date().toISOString()
     })
@@ -446,7 +451,8 @@ export const toggle = createHandler(async (ctx, body) => {
     throw new Error('Trigger ID is required')
   }
 
-  const { data: existing } = await ctx.db
+  const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
+  const { data: existing } = await db
     .from('triggers')
     .select('is_active, name')
     .eq('id', id)
@@ -458,9 +464,9 @@ export const toggle = createHandler(async (ctx, body) => {
 
   const newStatus = !existing.is_active
 
-  const { data, error: err } = await ctx.db
+  const { data, error: err } = await db
     .from('triggers')
-    .update({ 
+    .update({
       is_active: newStatus,
       updated_at: new Date().toISOString()
     })
@@ -497,7 +503,16 @@ export const toggle = createHandler(async (ctx, body) => {
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 export const handler = createHandler(async (ctx, body) => {
-  const { action } = ctx.query || {}
+  const { action, id } = ctx.query || {}
+  const method = ctx.query?.method || 'GET'
+
+  if (!action) {
+    if (method === 'GET') return id ? await get(ctx, body) : await list(ctx, body)
+    if (method === 'POST') return await create(ctx, body)
+    if (method === 'PATCH') return await update(ctx, body)
+    if (method === 'DELETE') return await remove(ctx, body)
+    throw new Error(`Unsupported method: ${method}`)
+  }
 
   switch (action) {
     case 'list':

package/.framework/functions/types.ts

@@ -42,22 +42,27 @@ const permissions = PermissionEngine as any
 // CIL[DOC-MACRO purpose="List active type definitions with optional filters and pagination"]
 // CIL[DOC-RESPONSIBILITY responsibility="Query the public.types table and sanitize records based on the caller principal"]
 // CIL[DOC-CONTEXT module="types function" layer="framework/functions" related_files=".framework/functions/_shared/audit.ts,.framework/functions/_shared/db.ts,.framework/functions/_shared/middleware.ts,.framework/functions/_shared/permissions.ts,.framework/functions/_shared/principal.ts,.framework/functions/_shared/schema-utils.ts,.framework/functions/types.ts"]
-// CIL[DOC-CONTRACT inputs="kind, app_id, ownership, limit, offset, include_schema query parameters" outputs="array of sanitized type rows" errors="Database query errors" side_effects="none"]
-// CIL[DOC-MICRO logic_summary="Builds a filtered, paginated Supabase query against the types table and returns sanitized results" notable_decisions="Returns minimal fields for unauthenticated callers; includes schema only when requested"]
+// CIL[DOC-CONTRACT inputs="kind, app_id, ownership, active, limit, offset, include_schema query parameters" outputs="array of sanitized type rows" errors="Database query errors" side_effects="none"]
+// CIL[DOC-MICRO logic_summary="Builds a filtered, paginated Supabase query against the types table and returns sanitized results" notable_decisions="Returns minimal fields for unauthenticated callers; includes schema only when requested; active defaults to true, 'all' lists active and inactive, 'false' lists inactive only"]
 // CIL[DOC-CONFIDENCE pass="second" score="0.90" flags="none"]
 // CIL[DOC-STABILITY stability="stable"]
 export const list = createHandler(async (ctx, body) => {
-  const { kind, app_id, ownership, limit = '50', offset = '0', include_schema } = ctx.query || {}
+  const { kind, app_id, ownership, active, limit = '50', offset = '0', include_schema } = ctx.query || {}
 
   const db = isSystemAdmin(ctx.principal) ? adminDb : ctx.db
 
   let query = db
     .from('types')
     .select('*')
-    .eq('is_active', true)
     .order('kind')
     .order('name')
 
+  if (active === 'false') {
+    query = query.eq('is_active', false)
+  } else if (active !== 'all') {
+    query = query.eq('is_active', true)
+  }
+
   if (kind) {
     query = query.eq('kind', kind)
   }
@@ -132,7 +137,6 @@ export const get = createHandler(async (ctx, body) => {
     .from('types')
     .select('*')
     .eq('id', id)
-    .eq('is_active', true)
     .single()
 
   if (err) throw err
@@ -237,7 +241,6 @@ export const create = createHandler(async (ctx, body) => {
     app_id = null,
     design_schema = {},
     validation_schema = null,
-    view_config = {},
     description = null,
     icon = null,
     color = null
@@ -272,7 +275,6 @@ export const create = createHandler(async (ctx, body) => {
       app_id,
       design_schema,
       validation_schema: validation,
-      view_config,
       description,
       icon,
       color,
@@ -325,7 +327,6 @@ export const update = createHandler(async (ctx, body) => {
     .from('types')
     .select('*')
     .eq('id', id)
-    .eq('is_active', true)
     .single()
 
   if (!existing) {
@@ -340,7 +341,6 @@ export const update = createHandler(async (ctx, body) => {
     name,
     slug,
     design_schema,
-    view_config,
     description,
     icon,
     color,
@@ -354,7 +354,6 @@ export const update = createHandler(async (ctx, body) => {
 
   if (name !== undefined) updates.name = name
   if (slug !== undefined) updates.slug = slug
-  if (view_config !== undefined) updates.view_config = view_config
   if (description !== undefined) updates.description = description
   if (icon !== undefined) updates.icon = icon
   if (color !== undefined) updates.color = color
@@ -368,6 +367,10 @@ export const update = createHandler(async (ctx, body) => {
     updates.validation_schema = generateValidationSchema(design_schema)
   }
 
+  if (Object.keys(updates).length === 0) {
+    return existing
+  }
+
   const { data, error } = await adminDb
     .from('types')
     .update(updates)

package/.framework/migrations/064_episode_leases.sql

@@ -0,0 +1,196 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/064_episode_leases.sql:episode_leases:file" type="file" identity="episode_leases" parent="~/.framework/migrations/064_episode_leases.sql"]
+-- CIL[DOC-MACRO purpose="Atomic single-flight lease for agent episodes: episode_leases table plus service-role-only acquire/heartbeat/release RPCs. Replaces the check-then-write driver_id claim in agent-runner so concurrent kicks can never both drive a thread. Also adds record_trigger_fire, the atomic trigger bookkeeping RPC that replaces trigger-engine's rpc-Promise-in-UPDATE bug."]
+-- CIL[DOC-RESPONSIBILITY responsibility="Create public.episode_leases (one row per in-flight episode keyed by thread_id), provide acquire_episode_lease/heartbeat_episode_lease/release_episode_lease as the single atomic writers, and fence writes by lease_token."]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/functions/_shared/agent-runner.ts,.framework/functions/ai-agents.ts,.framework/migrations/054_kb_ingest_lease.sql"]
+-- CIL[DOC-CONTRACT inputs="acquire: p_thread_id/p_account_id/p_driver_id/p_ttl_seconds; heartbeat: p_thread_id/p_lease_token/p_ttl_seconds; release: p_thread_id/p_lease_token" outputs="acquire jsonb {outcome: claimed|held, lease_token?, holder_driver_id?}; heartbeat boolean; release boolean" errors="none — all branches return" side_effects="Upserts/updates/deletes episode_leases; agent-runner uses the lease to serialize drivers and fence takeover writes"]
+-- CIL[DOC-MICRO logic_summary="acquire_episode_lease INSERTs ON CONFLICT DO NOTHING; on conflict it SELECTs FOR UPDATE and renews when the caller is the same driver or the lease expired (takeover, fresh token), else returns 'held' with the live holder's driver_id. heartbeat/release are token-gated — a displaced driver's heartbeat fails, which is what fences its pending writes." notable_decisions="Lease is keyed by thread (not episode) because a thread can only ever have one live episode; driver_id is text to carry client-generated session tokens; same-driver re-acquire renews so step-mode drivers persist across HTTP requests; RLS grants service_role FOR ALL and EXECUTE goes to service_role only, matching 049/052/054's service-only convention"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- ── episode_leases ─────────────────────────────────────────────────
+-- One row per in-flight agent episode (threads.id). Entry paths
+-- (ticket-creation kicks, episode-mode POSTs, step/complete POSTs)
+-- acquire before running; the holder heartbeats per turn and releases
+-- on terminal state. A live lease refuses competing drivers atomically —
+-- this replaces the read-then-write research_state claim that allowed
+-- two drivers to race within the same window.
+CREATE TABLE IF NOT EXISTS public.episode_leases (
+  thread_id    uuid        PRIMARY KEY,
+  account_id   uuid        NOT NULL,
+  driver_id    text        NOT NULL,
+  lease_token  uuid        NOT NULL,
+  expires_at   timestamptz NOT NULL,
+  created_at   timestamptz DEFAULT now(),
+  updated_at   timestamptz DEFAULT now()
+);
+
+ALTER TABLE public.episode_leases ENABLE ROW LEVEL SECURITY;
+
+-- Service-role only: all reads/writes flow through _shared/agent-runner.ts
+-- (adminDb) and the three RPCs below.
+DROP POLICY IF EXISTS episode_leases_service_role ON public.episode_leases;
+CREATE POLICY episode_leases_service_role ON public.episode_leases
+  FOR ALL TO service_role USING (true) WITH CHECK (true);
+
+-- ── acquire_episode_lease ──────────────────────────────────────────
+-- Atomic claim. Returns {outcome, lease_token?, holder_driver_id?}:
+--   claimed — caller owns the episode; must heartbeat/release with the token
+--   held    — a live driver owns the thread; caller watches or retries later
+-- The same driver re-acquiring renews (new token, fresh TTL) so a client
+-- step loop can hold the lease across HTTP requests.
+CREATE OR REPLACE FUNCTION public.acquire_episode_lease(
+  p_thread_id uuid,
+  p_account_id uuid,
+  p_driver_id text,
+  p_ttl_seconds integer DEFAULT 90
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_lease        public.episode_leases%ROWTYPE;
+  v_new_token    uuid := gen_random_uuid();
+BEGIN
+  -- Fast path: claim the empty slot. The thread_id PK serializes
+  -- concurrent first-writers — the loser's INSERT is a no-op.
+  INSERT INTO public.episode_leases (thread_id, account_id, driver_id, lease_token, expires_at)
+  VALUES (
+    p_thread_id,
+    p_account_id,
+    p_driver_id,
+    v_new_token,
+    now() + make_interval(secs => p_ttl_seconds)
+  )
+  ON CONFLICT (thread_id) DO NOTHING;
+
+  IF FOUND THEN
+    RETURN jsonb_build_object('outcome', 'claimed', 'lease_token', v_new_token);
+  END IF;
+
+  -- Conflict path: lock the row so a concurrent release/takeover cannot
+  -- interleave between our read and our verdict.
+  SELECT * INTO v_lease
+  FROM public.episode_leases
+  WHERE thread_id = p_thread_id
+  FOR UPDATE;
+
+  -- A live different driver owns the episode — refuse, surfacing the
+  -- holder so the caller can attribute the 'running' status.
+  IF v_lease.driver_id <> p_driver_id AND v_lease.expires_at > now() THEN
+    RETURN jsonb_build_object(
+      'outcome', 'held',
+      'holder_driver_id', v_lease.driver_id
+    );
+  END IF;
+
+  -- Same driver (renew) or expired lease (takeover): fresh token + TTL.
+  -- A displaced driver's later heartbeat/release fails the token check,
+  -- which is what fences its pending writes.
+  UPDATE public.episode_leases SET
+    driver_id   = p_driver_id,
+    lease_token = v_new_token,
+    account_id  = p_account_id,
+    expires_at  = now() + make_interval(secs => p_ttl_seconds),
+    updated_at  = now()
+  WHERE thread_id = p_thread_id;
+
+  RETURN jsonb_build_object('outcome', 'claimed', 'lease_token', v_new_token);
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer) FROM anon;
+REVOKE ALL ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer) TO service_role;
+
+-- ── heartbeat_episode_lease ────────────────────────────────────────
+-- Token-gated TTL extension. Returns false when the lease_token no
+-- longer matches (an expired-lease takeover displaced this driver) —
+-- the caller must treat that as a fence and stop writing, not as an
+-- error to retry.
+CREATE OR REPLACE FUNCTION public.heartbeat_episode_lease(
+  p_thread_id uuid,
+  p_lease_token uuid,
+  p_ttl_seconds integer DEFAULT 90
+)
+RETURNS boolean
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  UPDATE public.episode_leases SET
+    expires_at = now() + make_interval(secs => p_ttl_seconds),
+    updated_at = now()
+  WHERE thread_id = p_thread_id
+    AND lease_token = p_lease_token;
+
+  RETURN FOUND;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.heartbeat_episode_lease(uuid, uuid, integer) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.heartbeat_episode_lease(uuid, uuid, integer) FROM anon;
+REVOKE ALL ON FUNCTION public.heartbeat_episode_lease(uuid, uuid, integer) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.heartbeat_episode_lease(uuid, uuid, integer) TO service_role;
+
+-- ── release_episode_lease ──────────────────────────────────────────
+-- Token-gated release on terminal state. Returns false when the token
+-- no longer matches (a takeover superseded this driver) — warn-only,
+-- never an error.
+CREATE OR REPLACE FUNCTION public.release_episode_lease(
+  p_thread_id uuid,
+  p_lease_token uuid
+)
+RETURNS boolean
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  DELETE FROM public.episode_leases
+  WHERE thread_id = p_thread_id
+    AND lease_token = p_lease_token;
+
+  RETURN FOUND;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.release_episode_lease(uuid, uuid) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.release_episode_lease(uuid, uuid) FROM anon;
+REVOKE ALL ON FUNCTION public.release_episode_lease(uuid, uuid) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.release_episode_lease(uuid, uuid) TO service_role;
+
+-- ── record_trigger_fire ────────────────────────────────────────────
+-- Atomic trigger bookkeeping. trigger-engine previously passed an
+-- adminDb.rpc() Promise as a column value inside an UPDATE payload —
+-- the update failed silently, so trigger_count stayed 0 and
+-- last_triggered stayed null on every fire.
+CREATE OR REPLACE FUNCTION public.record_trigger_fire(
+  p_trigger_id uuid
+)
+RETURNS void
+LANGUAGE sql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+  UPDATE public.triggers SET
+    trigger_count  = COALESCE(trigger_count, 0) + 1,
+    last_triggered = now()
+  WHERE id = p_trigger_id;
+$$;
+
+REVOKE ALL ON FUNCTION public.record_trigger_fire(uuid) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.record_trigger_fire(uuid) FROM anon;
+REVOKE ALL ON FUNCTION public.record_trigger_fire(uuid) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.record_trigger_fire(uuid) TO service_role;
+
+-- CIL[DOC-VECTOR type="context" content="purpose='Atomic single-flight lease for agent episodes keyed by thread_id, plus atomic record_trigger_fire bookkeeping.'; Callers: _shared/agent-runner.ts (kickAgentEpisode, runAgentStep heartbeat, runAgent release), functions/ai-agents.ts (run handler), _shared/trigger-engine.ts (record_trigger_fire); imports: none" status="ready"]
+-- CIL[DOC-VECTOR type="blast_radius" content="Any agent episode entry path now serializes drivers atomically; callers that do not claim proceed unchanged when the RPCs are absent" status="ready"]
+-- CIL[DOC-VECTOR type="configuration" content="Runs after thread/message tables exist; consumed by _shared/agent-runner.ts via adminDb.rpc" status="ready"]
+-- CIL[DOC-VECTOR type="constraint" content="episode_leases and all three RPCs are service-role only; heartbeat and release are fenced by lease_token; same-driver acquire renews; expired leases are taken over with a fresh token" status="ready"]
+-- CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+-- CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+-- CIL[END stable_id="~/.framework/migrations/064_episode_leases.sql:episode_leases:file"]

package/.framework/migrations/065_execution_tables_updated_at.sql

@@ -0,0 +1,20 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/065_execution_tables_updated_at.sql:execution_tables_updated_at:file" type="file" identity="execution_tables_updated_at" parent="~/.framework/migrations/065_execution_tables_updated_at.sql"]
+-- CIL[DOC-MACRO purpose="Add the missing updated_at column to tables that carry the set_*_updated_at trigger but were created without the column — every UPDATE on them fails with 'record NEW has no field updated_at', which is what wedged pipeline_executions rows in 'running' forever."]
+-- CIL[DOC-RESPONSIBILITY responsibility="Backfill updated_at on pipeline_executions (required for terminal bookkeeping writes) and on logs/observability (defensive — same broken trigger, though those tables are append-only today)."]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/migrations/001_core_schema.sql,.framework/functions/_shared/pipeline-runner.ts"]
+-- CIL[DOC-CONTRACT inputs="none" outputs="three tables gain updated_at timestamptz DEFAULT now()" errors="none — idempotent ADD COLUMN IF NOT EXISTS" side_effects="Enables previously-failing UPDATEs on pipeline_executions; trigger set_*_updated_at now has a column to stamp"]
+-- CIL[DOC-MICRO logic_summary="001_core_schema attached updated_at_column() triggers to tables whose CREATE TABLE omitted updated_at; the trigger raises on every UPDATE, so pipeline-runner's terminal status writes silently failed (unchecked .update()). Adding the column makes the trigger a no-op stamp instead of an error." notable_decisions="Column added to all three affected tables for uniformity rather than dropping the triggers on append-only logs/observability — keeps the bookkeeping convention consistent if either table ever becomes updateable."]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+ALTER TABLE public.pipeline_executions ADD COLUMN IF NOT EXISTS updated_at timestamptz DEFAULT now();
+ALTER TABLE public.logs               ADD COLUMN IF NOT EXISTS updated_at timestamptz DEFAULT now();
+ALTER TABLE public.observability      ADD COLUMN IF NOT EXISTS updated_at timestamptz DEFAULT now();
+
+-- CIL[DOC-VECTOR type="context" content="purpose='Fix broken updated_at triggers on execution/log tables.'; Callers: _shared/pipeline-runner.ts terminal bookkeeping; imports: none" status="ready"]
+-- CIL[DOC-VECTOR type="blast_radius" content="pipeline_executions UPDATEs begin succeeding immediately; rows stuck 'running' from the silent failure remain and must be repaired separately" status="ready"]
+-- CIL[DOC-VECTOR type="configuration" content="Applies to any deployment created from 001_core_schema before this fix" status="ready"]
+-- CIL[DOC-VECTOR type="constraint" content="Idempotent; safe to re-run; does not repair historical stuck rows — that is a separate bookkeeping UPDATE" status="ready"]
+-- CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+-- CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+-- CIL[END stable_id="~/.framework/migrations/065_execution_tables_updated_at.sql:execution_tables_updated_at:file"]

package/.framework/migrations/066_episode_steal_thread_merge.sql

@@ -0,0 +1,148 @@
+-- CIL[BEGIN stable_id="~/.framework/migrations/066_episode_steal_thread_merge.sql:episode_steal_thread_merge:file" type="file" identity="episode_steal_thread_merge" parent="~/.framework/migrations/066_episode_steal_thread_merge.sql"]
+-- CIL[DOC-MACRO purpose="Episode-lease steal + fenced thread-data merge: request-bound drivers can immediately take over a thread whose lease is held by a 'detached:'-prefixed background driver, and threads.data writers get an atomic shallow-merge RPC with an optional lease-token fence so terminal research_state checkpoints cannot be clobbered by stale read-modify-write blobs."]
+-- CIL[DOC-RESPONSIBILITY responsibility="Extend acquire_episode_lease with p_steal_detached so live 'detached:' lease holders yield instantly to request-bound drivers, and add merge_thread_data as the single atomic writer for threads.data patches."]
+-- CIL[DOC-CONTEXT module="migrations" layer="database" related_files=".framework/functions/_shared/agent-runner.ts,.framework/functions/ai-agents.ts,.framework/migrations/064_episode_leases.sql"]
+-- CIL[DOC-CONTRACT inputs="acquire: +p_steal_detached boolean; merge_thread_data: p_thread_id/p_patch/p_lease_token" outputs="acquire jsonb {outcome: claimed|held, lease_token?, holder_driver_id?}; merge_thread_data boolean" errors="none — all branches return" side_effects="Updates episode_leases / threads"]
+-- CIL[DOC-MICRO logic_summary="acquire_episode_lease keeps the 064 fast-path INSERT plus FOR UPDATE conflict path; the 'held' verdict is skipped when p_steal_detached and the holder is 'detached:%' — detached background drivers exist to yield. merge_thread_data does data = coalesce(data,'{}'::jsonb) || p_patch with WHERE-fencing: when p_lease_token is provided the write only lands if no differently-tokened lease holds the thread, so a displaced driver's stale checkpoint is dropped." notable_decisions="Detached steal is safer than client-side driver_id adoption: the server decides who yields, and live (non-detached) holders are still never preempted — only TTL expiry displaces them; jsonb || is a shallow merge so siblings written concurrently (escalation_status, research_state) no longer clobber each other; the lease-token fence makes a loser's terminal write a silent no-op rather than a resurrected mid-episode state"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.9" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+
+-- ── acquire_episode_lease: detached-holder steal ────────────────────
+-- 'detached:' drivers are spawned background work (ticket-creation
+-- kicks, trigger-fired episodes) — they exist so an episode survives a
+-- dead client, not to block one. On serverless platforms detached work
+-- is CPU-throttled after the response flush (observed ~37s dead window
+-- before its first persisted message), so a request-bound driver must
+-- be able to take over immediately instead of watching a stalled
+-- driver or waiting out the TTL. Live non-detached holders are never
+-- preempted — only TTL expiry displaces them, exactly as in 064.
+DROP FUNCTION IF EXISTS public.acquire_episode_lease(uuid, uuid, text, integer);
+CREATE FUNCTION public.acquire_episode_lease(
+  p_thread_id uuid,
+  p_account_id uuid,
+  p_driver_id text,
+  p_ttl_seconds integer DEFAULT 90,
+  p_steal_detached boolean DEFAULT false
+)
+RETURNS jsonb
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+DECLARE
+  v_lease        public.episode_leases%ROWTYPE;
+  v_new_token    uuid := gen_random_uuid();
+BEGIN
+  -- Fast path: claim the empty slot. The thread_id PK serializes
+  -- concurrent first-writers — the loser's INSERT is a no-op.
+  INSERT INTO public.episode_leases (thread_id, account_id, driver_id, lease_token, expires_at)
+  VALUES (
+    p_thread_id,
+    p_account_id,
+    p_driver_id,
+    v_new_token,
+    now() + make_interval(secs => p_ttl_seconds)
+  )
+  ON CONFLICT (thread_id) DO NOTHING;
+
+  IF FOUND THEN
+    RETURN jsonb_build_object('outcome', 'claimed', 'lease_token', v_new_token);
+  END IF;
+
+  -- Conflict path: lock the row so a concurrent release/takeover cannot
+  -- interleave between our read and our verdict.
+  SELECT * INTO v_lease
+  FROM public.episode_leases
+  WHERE thread_id = p_thread_id
+  FOR UPDATE;
+
+  -- A live different driver owns the episode — refuse, unless the holder
+  -- is a detached background driver and the caller asked to steal it.
+  -- Detached drivers are a liveness fallback, not a real owner: a live
+  -- request driver always wins over one. The detached driver's next
+  -- heartbeat fails the token check and it aborts cleanly, so the steal
+  -- never produces duplicate side effects.
+  IF v_lease.driver_id <> p_driver_id
+     AND v_lease.expires_at > now()
+     AND NOT (p_steal_detached AND v_lease.driver_id LIKE 'detached:%') THEN
+    RETURN jsonb_build_object(
+      'outcome', 'held',
+      'holder_driver_id', v_lease.driver_id
+    );
+  END IF;
+
+  -- Same driver (renew), expired lease (takeover), or detached steal:
+  -- fresh token + TTL. A displaced driver's later heartbeat/release
+  -- fails the token check, which is what fences its pending writes.
+  UPDATE public.episode_leases SET
+    driver_id   = p_driver_id,
+    lease_token = v_new_token,
+    account_id  = p_account_id,
+    expires_at  = now() + make_interval(secs => p_ttl_seconds),
+    updated_at  = now()
+  WHERE thread_id = p_thread_id;
+
+  RETURN jsonb_build_object('outcome', 'claimed', 'lease_token', v_new_token);
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer, boolean) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer, boolean) FROM anon;
+REVOKE ALL ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer, boolean) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer, boolean) TO service_role;
+
+-- ── merge_thread_data ──────────────────────────────────────────────
+-- Atomic shallow merge into threads.data. The previous pattern —
+-- read threads.data, merge in memory, write the whole blob back —
+-- loses any key written between the read and the write; during the
+-- guided demo a concurrent threads.data write resurrected a stale
+-- research_state over the terminal 'complete' checkpoint, leaving the
+-- thread showing planning/turn 0 after the final answer landed.
+-- jsonb || merges keys atomically so sibling writes never clobber.
+--
+-- Lease fence: when p_lease_token is provided, the write only lands
+-- while no differently-tokened episode_lease holds the thread — a
+-- displaced driver's stale checkpoint becomes a no-op instead of
+-- resurrecting mid-episode state over the takeover owner's terminal
+-- write. Pass NULL (or omit) for writers with no lease identity; the
+-- merge is still atomic, just unfenced.
+--
+-- Returns true when the row was written, false when fenced or the
+-- thread does not exist.
+CREATE OR REPLACE FUNCTION public.merge_thread_data(
+  p_thread_id uuid,
+  p_patch jsonb,
+  p_lease_token uuid DEFAULT null
+)
+RETURNS boolean
+LANGUAGE plpgsql
+SECURITY DEFINER
+SET search_path = public
+AS $$
+BEGIN
+  UPDATE public.threads t SET
+    data       = coalesce(t.data, '{}'::jsonb) || p_patch,
+    updated_at = now()
+  WHERE t.id = p_thread_id
+    AND (p_lease_token IS NULL OR NOT EXISTS (
+      SELECT 1 FROM public.episode_leases l
+      WHERE l.thread_id = p_thread_id
+        AND l.lease_token IS DISTINCT FROM p_lease_token
+    ));
+
+  RETURN FOUND;
+END;
+$$;
+
+REVOKE ALL ON FUNCTION public.merge_thread_data(uuid, jsonb, uuid) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.merge_thread_data(uuid, jsonb, uuid) FROM anon;
+REVOKE ALL ON FUNCTION public.merge_thread_data(uuid, jsonb, uuid) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.merge_thread_data(uuid, jsonb, uuid) TO service_role;
+
+-- CIL[DOC-VECTOR type="context" content="purpose='Detached-driver lease steal plus atomic fenced threads.data merge.'; Callers: _shared/agent-runner.ts (acquireEpisodeLease, mergeThreadData, setResearchState, handleEscalation, claimAgentEpisode/kickAgentEpisode), functions/ai-agents.ts (run handler); imports: none" status="ready"]
+-- CIL[DOC-VECTOR type="blast_radius" content="Episode entry paths can preempt detached fallback drivers instantly; all threads.data writers through merge_thread_data gain atomicity and optional lease fencing" status="ready"]
+-- CIL[DOC-VECTOR type="configuration" content="Runs after 064_episode_leases.sql; consumed by _shared/agent-runner.ts via adminDb.rpc" status="ready"]
+-- CIL[DOC-VECTOR type="constraint" content="service-role only; 'detached:%' driver_id prefix is a contract with kickAgentEpisode; merge_thread_data is a shallow merge — nested objects in p_patch replace wholesale" status="ready"]
+-- CIL[DOC-VECTOR type="implementation_pattern" content="" status="pending_human_input"]
+-- CIL[DOC-VECTOR type="user_journey" content="" status="pending_human_input"]
+-- CIL[END stable_id="~/.framework/migrations/066_episode_steal_thread_merge.sql:episode_steal_thread_merge:file"]