spine-framework 0.4.2 → 0.4.4

package/.framework/functions/trigger-scheduler.ts

@@ -1,10 +1,70 @@
 // CIL[BEGIN stable_id="~/.framework/functions/trigger-scheduler.ts:module_header:module_header" type="module_header" identity="module_header" parent="~/.framework/functions/trigger-scheduler.ts"]
 // CIL[DOC-MACRO purpose="Scheduled entry point that invokes the shared system-cron runner so Netlify's every-minute trigger dispatches due scheduled actions."]
-// CIL[DOC-RESPONSIBILITY responsibility="Re-export the system-cron handler under the function name registered in netlify.toml."]
-// CIL[DOC-CONTEXT module="trigger-scheduler" layer="functions" related_files=".framework/functions/system-cron.ts, netlify.toml"]
-// CIL[DOC-CONTRACT inputs="Netlify scheduled invocation" outputs="system-cron sweep result" errors="none (delegates)" side_effects="runs due schedule actions across accounts"]
-// CIL[DOC-MICRO logic_summary="Thin alias: netlify.toml schedules trigger-scheduler every minute; the handler is system-cron's." notable_decisions="Separate file so the schedule name stays stable if system-cron internals change."]
+// CIL[DOC-RESPONSIBILITY responsibility="Detect Netlify Clockwork scheduled invocations (which carry no credentials) and run system-cron under the system principal; forward everything else to system-cron's normal middleware auth."]
+// CIL[DOC-CONTEXT module="trigger-scheduler" layer="functions" related_files=".framework/functions/system-cron.ts, .framework/functions/_shared/principal.ts, .framework/functions/_shared/db.ts, netlify.toml"]
+// CIL[DOC-CONTRACT inputs="Netlify scheduled invocation (x-nf-event/x-netlify-event: schedule OR Netlify Clockwork UA, + {\"next_run\"} body) or authenticated HTTP request" outputs="system-cron sweep result" errors="401 for unauthenticated HTTP requests" side_effects="runs due schedule actions across accounts"]
+// CIL[DOC-MICRO logic_summary="Netlify's scheduler invokes this function directly. The header name differs between environments: CLI emulation sends X-NF-Event; production sends x-netlify-event (canonical constant in @netlify/serverless-functions-api). Both are accepted, as is the Netlify Clockwork user-agent, so detection is robust across all invocation paths. The body must contain next_run as a string for both headers. For that path a RequestContext is fabricated with SYSTEM_PRINCIPAL and passed straight into system-cron's handler. Non-scheduled requests fall through to system-cron's createHandler." notable_decisions="x-netlify-event is the production canonical header (NFEvent in @netlify/serverless-functions-api); x-nf-event is the CLI emulation header. Both must be accepted or every scheduled tick 401s in production. Netlify Clockwork UA is a third indicator used only when neither header is present."]
 // CIL[DOC-STABILITY stable]
 // CIL[DOC-AUDIENCE audience="framework maintainers"]
-export { handler } from './system-cron'
+import { handler as cronHandler } from './system-cron'
+import { SYSTEM_PRINCIPAL } from './_shared/principal'
+import { adminDb } from './_shared/db'
+
+// Netlify Clockwork invocation detection. Require BOTH a recognised indicator
+// AND the {"next_run": "..."} body shape so a bare spoofed header or UA alone
+// cannot authenticate.
+//
+// Header variants (both must be handled):
+//   - x-nf-event: schedule   — Netlify CLI emulation (ntl dev / functions:invoke)
+//   - x-netlify-event: schedule — production canonical header
+//     (@netlify/serverless-functions-api NFEvent = "x-netlify-event")
+//
+// Fallback: user-agent "Netlify Clockwork" is accepted when neither header is
+// present, to guard against future header renames.
+function isNetlifyScheduledInvocation(event: any): boolean {
+  const headers = event.headers || {}
+
+  const nfEvent =
+    headers['x-netlify-event'] || headers['X-Netlify-Event'] ||
+    headers['x-nf-event']      || headers['X-NF-Event']
+
+  const ua = headers['user-agent'] || headers['User-Agent'] || ''
+
+  const hasScheduleIndicator =
+    nfEvent === 'schedule' || ua.includes('Netlify Clockwork')
+
+  if (!hasScheduleIndicator) return false
+
+  try {
+    const body = typeof event.body === 'string' ? JSON.parse(event.body) : event.body
+    return typeof body?.next_run === 'string'
+  } catch {
+    return false
+  }
+}
+
+export const handler = async (event: any, context: any) => {
+  if (!isNetlifyScheduledInvocation(event)) {
+    // Not a Clockwork invocation — run the normal middleware auth path.
+    // x-internal-secret resolves to SYSTEM_PRINCIPAL; ?api_key= is checked
+    // inside the cron handler; anything else 401s.
+    return cronHandler(event, context)
+  }
+
+  // Fabricate a RequestContext carrying the system principal. createHandler
+  // short-circuits when event.requestId + event.principal are present, so
+  // this flows straight into the cron handler without re-resolving auth.
+  const ctx = {
+    requestId: crypto.randomUUID(),
+    principal: SYSTEM_PRINCIPAL,
+    db: adminDb,
+    accountId: null,
+    appId: null,
+    query: {},
+    requestPath: event.path || '/.netlify/functions/trigger-scheduler',
+    headers: {},
+    source: 'netlify-scheduler',
+  }
+  return cronHandler(ctx, context)
+}
 // CIL[END stable_id="~/.framework/functions/trigger-scheduler.ts:module_header:module_header"]

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"]

package/.framework/migrations/067_episode_lease_stale_steal.sql

@@ -0,0 +1,93 @@
+-- Migration 067: stale-gated detached-driver steal
+--
+-- 066 let a request-bound driver steal any live 'detached:' lease
+-- unconditionally. That guaranteed a mid-turn displacement on every
+-- guided run (triage kick claims first, the client's episode POST steals
+-- seconds later), fencing a healthy driver and leaving research_state
+-- mid-flight — the residual duplicate-narration class. Steal is a
+-- recovery path for STALLED background work, so it now requires the
+-- holder's heartbeat (updated_at, renewed by heartbeat_episode_lease)
+-- to be older than p_stale_seconds. Healthy detached drivers are
+-- refused 'held' like any other live driver.
+
+-- CIL[BEGIN stable_id="~/.framework/migrations/067_episode_lease_stale_steal.sql:module:migration" type="migration" identity="episode-lease-stale-steal" parent="~/.framework/migrations/067_episode_lease_stale_steal.sql"]
+-- CIL[DOC-MACRO purpose="Gate p_steal_detached on the holder's heartbeat age so request drivers only displace stalled background work"]
+-- CIL[DOC-RESPONSIBILITY responsibility="Redefine acquire_episode_lease with a p_stale_seconds parameter; detach-prefix holders are stealable only when updated_at exceeds the staleness window"]
+-- CIL[DOC-CONTEXT module="episode-concurrency" layer="schema" related_files=".framework/functions/_shared/agent-runner.ts,.framework/functions/ai-agents.ts"]
+-- CIL[DOC-CONTRACT inputs="p_thread_id uuid, p_account_id uuid, p_driver_id text, p_ttl_seconds int default 90, p_steal_detached bool default false, p_stale_seconds int default 30" outputs="jsonb verdict {outcome: claimed|held, lease_token?, holder_driver_id?}" errors="none — fail-open verdict" side_effects="inserts or updates episode_leases"]
+-- CIL[DOC-MICRO logic_summary="Identical to 066 except the steal branch additionally requires v_lease.updated_at to be older than p_stale_seconds; heartbeat renewals keep a healthy detached driver unstealable" notable_decisions="30s default bounds takeover latency well under the 90s TTL while tolerating slow single turns between heartbeats"]
+-- CIL[DOC-CONFIDENCE pass="first" score="0.92" flags="none"]
+-- CIL[DOC-STABILITY stability="stable"]
+-- CIL[DOC-AUDIENCE audience="system-admin"]
+-- CIL[DOC-VECTOR type="context" content="Third lease RPC revision: 063 atomic claim, 066 detached steal, 067 stale-gated steal" status="ready"]
+-- CIL[END stable_id="~/.framework/migrations/067_episode_lease_stale_steal.sql:module:migration"]
+
+DROP FUNCTION IF EXISTS public.acquire_episode_lease(uuid, uuid, text, integer, boolean);
+
+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,
+  p_stale_seconds integer DEFAULT 30
+)
+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
+  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;
+
+  SELECT * INTO v_lease
+  FROM public.episode_leases
+  WHERE thread_id = p_thread_id
+  FOR UPDATE;
+
+  -- Held: a different live driver owns the episode. Steal is allowed
+  -- only for a 'detached:'-prefixed holder whose heartbeat has gone
+  -- stale — a healthy background driver is refused like anyone else so
+  -- request claims stop displacing mid-turn work.
+  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:%'
+              AND v_lease.updated_at < now() - make_interval(secs => p_stale_seconds)) THEN
+    RETURN jsonb_build_object(
+      'outcome', 'held',
+      'holder_driver_id', v_lease.driver_id
+    );
+  END IF;
+
+  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, integer) FROM PUBLIC;
+REVOKE ALL ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer, boolean, integer) FROM anon;
+REVOKE ALL ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer, boolean, integer) FROM authenticated;
+GRANT EXECUTE ON FUNCTION public.acquire_episode_lease(uuid, uuid, text, integer, boolean, integer) TO service_role;