@consiliency/agent-board-schema 1.68.0 → 1.74.0

package/migrations/20261026000100_agent_board_thread_association.sql

@@ -0,0 +1,1287 @@
+-- Enforce board/thread identity and serialize first association with private-history writers.
+-- Serialize first association and inspect committed history in fresh VOLATILE statements.
+create or replace function agent_board._associate_empty_thread(p_thread_id uuid, p_board_id uuid)
+returns void language plpgsql volatile security definer
+set search_path = agent_board, public as $$
+declare v_board_id uuid;
+begin
+  if p_thread_id is null or p_board_id is null then
+    raise exception 'thread and board are required' using errcode = '22023';
+  end if;
+  perform 1 from agent_board.threads where id = p_thread_id for no key update;
+  if not found then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  select board_id into v_board_id from agent_board.threads where id = p_thread_id;
+  if v_board_id is not null then
+    if v_board_id <> p_board_id then
+      raise exception 'thread belongs to a different board' using errcode = '42501';
+    end if;
+    return;
+  end if;
+  if current_setting('transaction_isolation') <> 'read committed' then
+    raise exception 'first thread association requires read committed isolation' using errcode = '0A000';
+  end if;
+  if exists (select 1 from agent_board.messages where thread_id = p_thread_id)
+    or exists (select 1 from agent_board.tasks where thread_id = p_thread_id)
+    or exists (select 1 from agent_board.task_events where thread_id = p_thread_id)
+    or exists (select 1 from agent_board.artifacts where thread_id = p_thread_id)
+    or exists (select 1 from agent_board.claims where thread_id = p_thread_id)
+    or exists (select 1 from agent_board.conflicts where thread_id = p_thread_id)
+    or exists (select 1 from agent_board.escalations where thread_id = p_thread_id)
+    or exists (select 1 from agent_board.presence where thread_id = p_thread_id)
+    or exists (select 1 from agent_board.thread_memberships where thread_id = p_thread_id)
+  then
+    raise exception 'thread has private history' using errcode = '42501';
+  end if;
+  update agent_board.threads set board_id = p_board_id
+   where id = p_thread_id and board_id is null;
+end;
+$$;
+revoke all on function agent_board._associate_empty_thread(uuid, uuid) from public, anon, authenticated, service_role;
+comment on function agent_board._associate_empty_thread(uuid, uuid) is 'Internal first-association boundary; caller validates board and actor.';
+
+
+CREATE OR REPLACE FUNCTION agent_board.post_board_message(p_thread_id uuid, p_author_agent_id uuid, p_board_id uuid, p_subject text, p_body text, p_message_type text DEFAULT 'comment'::text, p_priority text DEFAULT 'medium'::text, p_idempotency_key text DEFAULT NULL::text, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(message_id uuid, board_id uuid, delivered_recipient_count integer, callback_outbox_count integer, created_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_message agent_board.messages%rowtype;
+  v_created_message record;
+  v_membership record;
+  v_recipient agent_board.delivery_recipients%rowtype;
+  v_inbox agent_board.inbox_items%rowtype;
+  v_delivered_count integer := 0;
+  v_callback_count integer := 0;
+  v_metadata jsonb;
+  v_preview text;
+  v_fetch_descriptor jsonb;
+  v_idempotency_key text := nullif(trim(p_idempotency_key), '');
+  v_actor_agent_id uuid;
+  v_is_author boolean;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_author_agent_id, 'p_author_agent_id');
+
+  if nullif(trim(p_subject), '') is null or nullif(trim(p_body), '') is null then
+    raise exception 'subject and body are required' using errcode = '22023';
+  end if;
+  if p_priority not in ('low', 'medium', 'high', 'urgent') then
+    raise exception 'invalid priority' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  if not exists (select 1 from agent_board.boards where id = p_board_id) then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  if not agent_board._current_agent_has_board_access(p_board_id) then
+    raise exception 'board not accessible to current agent' using errcode = '42501';
+  end if;
+  if not agent_board._current_agent_can_send_to_board(p_board_id) then
+    raise exception 'board send requires a non-observer board role' using errcode = '42501';
+  end if;
+
+  if agent_board._is_service_role() then
+    perform agent_board._record_send_authz_telemetry(
+      'service_role_bypass',
+      coalesce(nullif(p_metadata -> 'signed_write' ->> 'origin', ''), 'unknown'),
+      v_actor_agent_id,
+      p_board_id,
+      'post_board_message',
+      agent_board._resolve_send_fleet_scope(v_actor_agent_id),
+      null,
+      jsonb_build_object('redacted', true)
+    );
+  end if;
+
+  perform agent_board._lock_idempotency_key(
+    'post_board_message:' || p_thread_id::text || ':' || v_actor_agent_id::text || ':' || p_board_id::text,
+    v_idempotency_key
+  );
+
+  if p_board_id is not null then
+    perform agent_board._associate_empty_thread(p_thread_id, p_board_id);
+    -- Both checks are new statements after the thread-lock wait.
+    if not agent_board._current_agent_can_access_thread(p_thread_id) then
+      raise exception 'thread not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_has_board_access(p_board_id) then
+      raise exception 'board not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_can_send_to_board(p_board_id) then
+      raise exception 'board send requires a non-observer board role' using errcode = '42501';
+    end if;
+  end if;
+
+  if v_idempotency_key is not null then
+    select *
+      into v_message
+      from agent_board.messages
+     where thread_id = p_thread_id
+       and author_agent_id = v_actor_agent_id
+       and metadata ->> 'rpcName' = 'post_board_message'
+       and metadata ->> 'idempotencyKey' = v_idempotency_key
+     order by created_at desc, id desc
+     limit 1;
+  end if;
+
+  if v_message.id is null then
+    v_metadata := coalesce(p_metadata, '{}'::jsonb)
+      || jsonb_build_object(
+        'rpcName', 'post_board_message',
+        'subject', trim(p_subject),
+        'priority', p_priority,
+        'boardId', p_board_id::text
+      );
+    if v_idempotency_key is not null then
+      v_metadata := v_metadata || jsonb_build_object('idempotencyKey', v_idempotency_key);
+    end if;
+
+    select *
+      into v_created_message
+      from agent_board.post_message(
+        p_thread_id,
+        v_actor_agent_id,
+        p_body,
+        p_message_type,
+        null,
+        v_metadata
+      );
+
+    select *
+      into v_message
+      from agent_board.messages
+     where id = v_created_message.message_id;
+  end if;
+
+  v_preview := agent_board._trim_inbox_text(p_body, 280);
+  v_fetch_descriptor := agent_board._build_fetch_descriptor(
+    'board',
+    p_board_id,
+    'agent_board.v_board_feed',
+    'board delivery',
+    jsonb_build_object('messageId', v_message.id::text)
+  );
+
+  for v_membership in
+    select bm.id, bm.agent_id
+      from agent_board.board_memberships bm
+     where bm.board_id = p_board_id
+       and bm.membership_state in ('joined', 'subscribed')
+     order by bm.created_at
+  loop
+    -- #608: the author is not a recipient of its own post. Its row stays, FEED-ONLY
+    -- (visible_in_inbox = false), because v_board_feed is built from these rows and a post on a
+    -- board whose only member is its author would otherwise vanish from the feed. A feed-only
+    -- row is outside v_agent_inbox, v_agent_wake_recovery and v_agent_inbox_counts by their own
+    -- `visible_in_inbox` filter, and _queue_inbox_callbacks queues nothing for it.
+    v_is_author := v_membership.agent_id is not distinct from v_actor_agent_id;
+    v_recipient := agent_board._upsert_delivery_recipient(
+      'board',
+      v_membership.agent_id,
+      'message',
+      v_message.id,
+      null,
+      null,
+      p_board_id,
+      v_membership.id,
+      jsonb_build_object('priority', p_priority)
+    );
+
+    v_inbox := agent_board._upsert_inbox_item(
+      v_recipient.id,
+      v_membership.agent_id,
+      p_board_id,
+      v_recipient.delivery_mode,
+      'message',
+      v_message.id,
+      null,
+      null,
+      trim(p_subject),
+      v_preview,
+      p_priority,
+      not v_is_author,
+      true,
+      v_fetch_descriptor,
+      jsonb_build_object('threadId', p_thread_id::text, 'boardId', p_board_id::text)
+    );
+
+    -- delivered_recipient_count counts RECIPIENTS; the author's feed-only row is not one.
+    if not v_is_author then
+      v_delivered_count := v_delivered_count + 1;
+    end if;
+    v_callback_count := v_callback_count + agent_board._queue_inbox_callbacks(v_inbox.id, 'inbox.item.delivered');
+  end loop;
+
+  v_callback_count := v_callback_count + agent_board._queue_board_post_callbacks(
+    p_board_id,
+    v_message.id,
+    trim(p_subject),
+    v_preview,
+    p_priority,
+    v_fetch_descriptor
+  );
+
+  return query
+  select v_message.id, p_board_id, v_delivered_count, v_callback_count, v_message.created_at;
+end;
+$function$
+;
+
+CREATE OR REPLACE FUNCTION agent_board.create_tasking_delivery(p_thread_id uuid, p_created_by_agent_id uuid, p_title text, p_details text DEFAULT NULL::text, p_recipient_agent_ids uuid[] DEFAULT NULL::uuid[], p_board_id uuid DEFAULT NULL::uuid, p_priority text DEFAULT 'medium'::text, p_orchestration_mode text DEFAULT 'distributed'::text, p_idempotency_key text DEFAULT NULL::text, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(task_id uuid, created_event_id uuid, delivered_recipient_count integer, inbox_item_count integer, callback_outbox_count integer, created_at timestamp with time zone, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_task agent_board.tasks%rowtype;
+  v_created_event_id uuid;
+  v_created_task record;
+  v_recipient_ids uuid[];
+  v_recipient_id uuid;
+  v_membership record;
+  v_recipient agent_board.delivery_recipients%rowtype;
+  v_inbox agent_board.inbox_items%rowtype;
+  v_delivered_count integer := 0;
+  v_inbox_count integer := 0;
+  v_callback_count integer := 0;
+  v_metadata jsonb;
+  v_preview text;
+  v_fetch_descriptor jsonb;
+  v_idempotency_key text := nullif(trim(p_idempotency_key), '');
+  v_actor_agent_id uuid;
+  v_is_creator boolean;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_created_by_agent_id, 'p_created_by_agent_id');
+
+  if nullif(trim(p_title), '') is null then
+    raise exception 'task title is required' using errcode = '22023';
+  end if;
+  if p_priority not in ('low', 'medium', 'high', 'urgent') then
+    raise exception 'invalid priority' using errcode = '22023';
+  end if;
+  if p_orchestration_mode not in ('distributed', 'hierarchical', 'hybrid') then
+    raise exception 'invalid orchestration mode' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  if (p_recipient_agent_ids is null or cardinality(p_recipient_agent_ids) = 0) and p_board_id is null then
+    raise exception 'tasking delivery requires explicit recipients or a board target' using errcode = '22023';
+  end if;
+  if p_recipient_agent_ids is not null and array_position(p_recipient_agent_ids, null) is not null then
+    raise exception 'recipient_agent_ids must not contain nulls' using errcode = '22023';
+  end if;
+  if p_board_id is not null then
+    if not exists (select 1 from agent_board.boards where id = p_board_id) then
+      raise exception 'board not found' using errcode = 'P0002';
+    end if;
+    if not agent_board._current_agent_has_board_access(p_board_id) then
+      raise exception 'board not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_can_send_to_board(p_board_id) then
+      raise exception 'board send requires a non-observer board role' using errcode = '42501';
+    end if;
+  end if;
+
+  select array_agg(distinct recipient_id)
+    into v_recipient_ids
+    from unnest(coalesce(p_recipient_agent_ids, '{}'::uuid[])) as recipient_id;
+
+  if v_recipient_ids is not null and (
+    select count(*)
+      from agent_board.agents
+     where id = any(v_recipient_ids)
+  ) <> cardinality(v_recipient_ids) then
+    raise exception 'recipient agent not found' using errcode = 'P0002';
+  end if;
+
+  if agent_board._is_service_role() then
+    perform agent_board._record_send_authz_telemetry(
+      'service_role_bypass',
+      coalesce(nullif(p_metadata -> 'signed_write' ->> 'origin', ''), 'unknown'),
+      v_actor_agent_id,
+      p_board_id,
+      'create_tasking_delivery',
+      agent_board._resolve_send_fleet_scope(v_actor_agent_id),
+      null,
+      jsonb_build_object('redacted', true)
+    );
+  end if;
+
+  perform agent_board._lock_idempotency_key(
+    'create_tasking_delivery:' || p_thread_id::text || ':' || v_actor_agent_id::text,
+    v_idempotency_key
+  );
+
+  if p_board_id is not null then
+    perform agent_board._associate_empty_thread(p_thread_id, p_board_id);
+    -- Both checks are new statements after the thread-lock wait.
+    if not agent_board._current_agent_can_access_thread(p_thread_id) then
+      raise exception 'thread not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_has_board_access(p_board_id) then
+      raise exception 'board not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_can_send_to_board(p_board_id) then
+      raise exception 'board send requires a non-observer board role' using errcode = '42501';
+    end if;
+  end if;
+
+  if v_idempotency_key is not null then
+    select *
+      into v_task
+      from agent_board.tasks
+     where thread_id = p_thread_id
+       and created_by_agent_id = v_actor_agent_id
+       and metadata ->> 'rpcName' = 'create_tasking_delivery'
+       and metadata ->> 'idempotencyKey' = v_idempotency_key
+     order by created_at desc, id desc
+     limit 1;
+  end if;
+
+  if v_task.id is null then
+    v_metadata := coalesce(p_metadata, '{}'::jsonb)
+      || jsonb_build_object(
+        'rpcName', 'create_tasking_delivery',
+        'priority', p_priority
+      );
+    if p_board_id is not null then
+      v_metadata := v_metadata || jsonb_build_object('boardId', p_board_id::text);
+    end if;
+    if v_idempotency_key is not null then
+      v_metadata := v_metadata || jsonb_build_object('idempotencyKey', v_idempotency_key);
+    end if;
+
+    select *
+      into v_created_task
+      from agent_board.create_task(
+        p_thread_id,
+        v_actor_agent_id,
+        trim(p_title),
+        p_details,
+        null,
+        null,
+        p_priority,
+        p_orchestration_mode,
+        v_metadata
+      );
+
+    v_created_event_id := v_created_task.created_event_id;
+
+    select *
+      into v_task
+      from agent_board.tasks
+     where id = v_created_task.task_id;
+  else
+    select te.id
+      into v_created_event_id
+      from agent_board.task_events te
+     where te.task_id = v_task.id
+       and te.event_sequence = 1;
+  end if;
+
+  v_preview := agent_board._trim_inbox_text(coalesce(p_details, p_title), 280);
+  v_fetch_descriptor := agent_board._build_fetch_descriptor(
+    'task',
+    v_task.id,
+    'agent_board.v_task_tree',
+    'tasking delivery',
+    jsonb_build_object('threadId', p_thread_id::text)
+  );
+
+  if v_recipient_ids is not null then
+    foreach v_recipient_id in array v_recipient_ids loop
+      v_recipient := agent_board._upsert_delivery_recipient(
+        'tasking',
+        v_recipient_id,
+        'task',
+        null,
+        v_task.id,
+        null,
+        null,
+        null,
+        jsonb_build_object('priority', p_priority)
+      );
+
+      v_inbox := agent_board._upsert_inbox_item(
+        v_recipient.id,
+        v_recipient_id,
+        null,
+        v_recipient.delivery_mode,
+        'task',
+        null,
+        v_task.id,
+        null,
+        trim(p_title),
+        v_preview,
+        p_priority,
+        true,
+        false,
+        v_fetch_descriptor,
+        jsonb_build_object('threadId', p_thread_id::text)
+      );
+
+      v_delivered_count := v_delivered_count + 1;
+      v_inbox_count := v_inbox_count + 1;
+      v_callback_count := v_callback_count + agent_board._queue_inbox_callbacks(v_inbox.id, 'inbox.item.delivered');
+    end loop;
+  end if;
+
+  if p_board_id is not null then
+    for v_membership in
+      select bm.id, bm.agent_id
+        from agent_board.board_memberships bm
+       where bm.board_id = p_board_id
+         and bm.membership_state in ('joined', 'subscribed')
+       order by bm.created_at
+    loop
+      -- #608: the board fan-out does not deliver a task to the agent that created it. The
+      -- creator's row is KEPT, feed-only, exactly as a board post's author row is. Before #667,
+      -- _upsert_delivery_recipient was the only board-stamp path; skipping that row
+      -- left a creator-only board's thread unlinked and post_message on the access-only branch of
+      -- the observer gate (codex and grok seats, PR #615 round 1). It also keeps the board
+      -- directory's activity and delegate visibility as they were. An explicit recipient list
+      -- naming the creator still delivers to it: that is the caller addressing itself, and the
+      -- board loop must not then demote the row the explicit loop wrote. It shares that row (the
+      -- delivery upsert keeps the explicit row's null board_id), so demoting it wrote both
+      -- visibility flags false and violated inbox_items_visibility_shape, aborting the whole task
+      -- (every seat on PR #615 round 2).
+      v_is_creator := v_membership.agent_id is not distinct from v_actor_agent_id
+        and not (v_membership.agent_id = any(coalesce(v_recipient_ids, '{}'::uuid[])));
+      v_recipient := agent_board._upsert_delivery_recipient(
+        'tasking',
+        v_membership.agent_id,
+        'task',
+        null,
+        v_task.id,
+        null,
+        p_board_id,
+        v_membership.id,
+        jsonb_build_object('priority', p_priority)
+      );
+
+      v_inbox := agent_board._upsert_inbox_item(
+        v_recipient.id,
+        v_membership.agent_id,
+        v_recipient.board_id,
+        v_recipient.delivery_mode,
+        'task',
+        null,
+        v_task.id,
+        null,
+        trim(p_title),
+        v_preview,
+        p_priority,
+        not v_is_creator,
+        v_recipient.board_id is not null,
+        v_fetch_descriptor,
+        jsonb_build_object('threadId', p_thread_id::text, 'boardId', p_board_id::text)
+      );
+
+      -- The counts are of RECIPIENTS; the creator's feed-only row is not one.
+      if not v_is_creator then
+        v_delivered_count := v_delivered_count + 1;
+        v_inbox_count := v_inbox_count + 1;
+      end if;
+      v_callback_count := v_callback_count + agent_board._queue_inbox_callbacks(v_inbox.id, 'inbox.item.delivered');
+    end loop;
+  end if;
+
+  return query
+  select v_task.id, v_created_event_id, v_delivered_count, v_inbox_count, v_callback_count, v_task.created_at, v_task.updated_at;
+end;
+$function$
+;
+
+CREATE OR REPLACE FUNCTION agent_board._upsert_delivery_recipient(p_delivery_mode text, p_recipient_agent_id uuid, p_source_kind text, p_source_message_id uuid DEFAULT NULL::uuid, p_source_task_id uuid DEFAULT NULL::uuid, p_source_delegation_id uuid DEFAULT NULL::uuid, p_board_id uuid DEFAULT NULL::uuid, p_board_membership_id uuid DEFAULT NULL::uuid, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS agent_board.delivery_recipients
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_row agent_board.delivery_recipients%rowtype;
+begin
+  -- HOSTED (D16): a delivery reaches a hosted delegate only through a board it is active on
+  -- (the board-post fan-out to members). It can read nothing without a board.
+  perform agent_board._refuse_delegate_addressee(p_recipient_agent_id, p_board_id, 'delivery');
+  if p_board_id is not null then
+    perform agent_board._associate_empty_thread(coalesce(
+      (select m.thread_id from agent_board.messages m where m.id = p_source_message_id),
+      (select tk.thread_id from agent_board.tasks tk where tk.id = p_source_task_id),
+      (select tk.thread_id from agent_board.delegations d
+       join agent_board.tasks tk on tk.id = d.child_task_id where d.id = p_source_delegation_id)
+    ), p_board_id);
+  end if;
+
+  insert into agent_board.delivery_recipients(
+    delivery_mode,
+    recipient_agent_id,
+    source_kind,
+    source_message_id,
+    source_task_id,
+    source_delegation_id,
+    board_id,
+    board_membership_id,
+    metadata
+  )
+  values (
+    p_delivery_mode,
+    p_recipient_agent_id,
+    p_source_kind,
+    p_source_message_id,
+    p_source_task_id,
+    p_source_delegation_id,
+    p_board_id,
+    p_board_membership_id,
+    coalesce(p_metadata, '{}'::jsonb)
+  )
+  on conflict (recipient_agent_id, canonical_source_key) do update
+    set metadata = coalesce(agent_board.delivery_recipients.metadata, '{}'::jsonb) || coalesce(excluded.metadata, '{}'::jsonb)
+  returning * into v_row;
+
+  return v_row;
+end;
+$function$
+;
+
+CREATE OR REPLACE FUNCTION agent_board.post_message(p_thread_id uuid, p_author_agent_id uuid, p_body text, p_message_type text DEFAULT 'comment'::text, p_task_id uuid DEFAULT NULL::uuid, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(message_id uuid, thread_id uuid, task_id uuid, message_sequence bigint, created_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_sequence bigint;
+  v_actor_agent_id uuid;
+  v_metadata jsonb;
+  v_instance agent_board.delegate_instances%rowtype;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_author_agent_id, 'p_author_agent_id');
+
+  if nullif(trim(p_body), '') is null then
+    raise exception 'message body is required' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  -- OBSGATE (#78): a board-linked thread under 'inherit' requires a non-observer board role.
+  -- post_message is the sole authenticated writer to messages, so this gate cannot be bypassed
+  -- by any send path. Board-less threads and service_role fall through (access check above).
+  if not agent_board._current_agent_can_post_to_thread(p_thread_id) then
+    raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+  end if;
+  if p_task_id is not null and not exists (select 1 from agent_board.tasks where id = p_task_id and tasks.thread_id = p_thread_id) then
+    raise exception 'task not found in thread' using errcode = '22023';
+  end if;
+
+  -- HOSTED attribution: the `delegate` key is written by the server, never by a caller. A
+  -- hosted delegate's post carries it (overwriting anything supplied); every other author's
+  -- caller-supplied `delegate` key is removed, so no keyed agent can forge the mark.
+  -- client_verified is always false: under dynamic client registration anyone can name a client.
+  v_metadata := coalesce(p_metadata, '{}'::jsonb);
+  if jsonb_typeof(v_metadata) = 'object' then
+    v_metadata := v_metadata - 'delegate';
+  end if;
+  select di.* into v_instance
+    from agent_board.agents a
+    join agent_board.delegate_instances di on di.agent_id = a.id
+   where a.id = v_actor_agent_id
+     and a.is_delegate;
+  if found then
+    if jsonb_typeof(v_metadata) <> 'object' then
+      raise exception 'a hosted delegate''s message metadata must be a JSON object' using errcode = '22023';
+    end if;
+    v_metadata := v_metadata || jsonb_build_object('delegate', jsonb_build_object(
+      'delegate', true,
+      'instance_id', v_instance.instance_id,
+      'owner_agent_id', agent_board._delegate_principal_agent_id(v_actor_agent_id),
+      'client_id', v_instance.client_id,
+      'client_verified', false));
+  end if;
+
+  v_sequence := agent_board._next_thread_message_sequence(p_thread_id);
+  -- The sequence update may have waited for an association; re-read after that wait.
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  if not agent_board._current_agent_can_post_to_thread(p_thread_id) then
+    raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+  end if;
+
+  return query
+  insert into agent_board.messages(thread_id, author_agent_id, task_id, message_sequence, message_type, body, metadata)
+  values (p_thread_id, v_actor_agent_id, p_task_id, v_sequence, coalesce(p_message_type, 'comment'), p_body, v_metadata)
+  returning id, messages.thread_id, messages.task_id, messages.message_sequence, messages.created_at;
+end;
+$function$
+;
+
+CREATE OR REPLACE FUNCTION agent_board.create_task(p_thread_id uuid, p_created_by_agent_id uuid, p_title text, p_details text DEFAULT NULL::text, p_assigned_agent_id uuid DEFAULT NULL::uuid, p_parent_task_id uuid DEFAULT NULL::uuid, p_priority text DEFAULT 'medium'::text, p_orchestration_mode text DEFAULT 'distributed'::text, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(task_id uuid, parent_task_id uuid, root_task_id uuid, created_event_id uuid, created_event_sequence bigint, status text, created_at timestamp with time zone, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_task_id uuid;
+  v_root_task_id uuid;
+  v_event_id uuid;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_created_by_agent_id, 'p_created_by_agent_id');
+
+  if nullif(trim(p_title), '') is null then
+    raise exception 'task title is required' using errcode = '22023';
+  end if;
+  if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+    raise exception 'thread not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  if (select board_id is null from agent_board.threads where id = p_thread_id) then
+    perform 1 from agent_board.threads where id = p_thread_id for no key update;
+    if not agent_board._current_agent_can_access_thread(p_thread_id) then
+      raise exception 'thread not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+  -- OBSGATE-2 (#123): a board-linked thread requires a non-observer board role to author.
+  if not agent_board._current_agent_can_post_to_thread(p_thread_id) then
+    raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+  end if;
+  if p_assigned_agent_id is not null and not exists (select 1 from agent_board.agents where id = p_assigned_agent_id) then
+    raise exception 'assigned agent not found' using errcode = 'P0002';
+  end if;
+  -- HOSTED (D16): a hosted delegate can act on no task, so it is never an assignee.
+  perform agent_board._refuse_delegate_addressee(p_assigned_agent_id, null, 'task assignment');
+
+  if p_parent_task_id is not null then
+    select coalesce(tasks.root_task_id, tasks.id)
+      into v_root_task_id
+      from agent_board.tasks
+     where id = p_parent_task_id and tasks.thread_id = p_thread_id;
+    if v_root_task_id is null then
+      raise exception 'parent task not found in thread' using errcode = '22023';
+    end if;
+    if not agent_board._current_agent_can_access_task(p_parent_task_id) then
+      raise exception 'parent task not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+
+  v_task_id := gen_random_uuid();
+  if p_parent_task_id is null then
+    v_root_task_id := v_task_id;
+  end if;
+
+  insert into agent_board.tasks(id, thread_id, created_by_agent_id, assigned_agent_id, parent_task_id, root_task_id, title, details, priority, orchestration_mode, metadata)
+  values (v_task_id, p_thread_id, v_actor_agent_id, p_assigned_agent_id, p_parent_task_id, v_root_task_id, trim(p_title), p_details, coalesce(p_priority, 'medium'), coalesce(p_orchestration_mode, 'distributed'), coalesce(p_metadata, '{}'::jsonb));
+
+  -- #288: create_task is the ONE writer that inserts into task_events directly rather than
+  -- through the funnel, which is why a fix instrumenting only append_task_event's callers
+  -- would miss it. Its own declared posture is signed-metadata (it declares p_metadata and the
+  -- client signs it). No parameter is threaded here deliberately -- see the plan's section 5:
+  -- where a signed wrapper is involved (signed_create_tasking_delivery keys its evidence to
+  -- THIS event, two levels up), a real signature_evidence row exists and v_task_tree already
+  -- surfaces it, which is the stronger signal. A threaded parameter would change no answer.
+  insert into agent_board.task_events(task_id, thread_id, actor_agent_id, event_sequence, event_type, payload, origin_posture)
+  values (v_task_id, p_thread_id, v_actor_agent_id, 1, 'created', jsonb_build_object('title', trim(p_title)), 'unattested:signed-metadata-rpc')
+  returning id into v_event_id;
+
+  return query
+  select t.id, t.parent_task_id, t.root_task_id, v_event_id, 1::bigint, t.status, t.created_at, t.updated_at
+    from agent_board.tasks t
+   where t.id = v_task_id;
+end;
+$function$
+;
+
+CREATE OR REPLACE FUNCTION agent_board.raise_conflict(p_thread_id uuid, p_raised_by_agent_id uuid, p_summary text, p_conflict_type text DEFAULT 'other'::text, p_severity text DEFAULT 'medium'::text, p_task_id uuid DEFAULT NULL::uuid, p_details jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(conflict_id uuid, status text, task_event_sequence bigint, created_at timestamp with time zone, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_conflict_id uuid;
+  v_event_sequence bigint;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_raised_by_agent_id, 'p_raised_by_agent_id');
+
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  if (select board_id is null from agent_board.threads where id = p_thread_id) then
+    perform 1 from agent_board.threads where id = p_thread_id for no key update;
+    if not agent_board._current_agent_can_access_thread(p_thread_id) then
+      raise exception 'thread not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+  -- OBSGATE-2 (#123): a board-linked thread requires a non-observer board role.
+  if not agent_board._current_agent_can_post_to_thread(p_thread_id) then
+    raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+  end if;
+
+  insert into agent_board.conflicts(thread_id, task_id, raised_by_agent_id, summary, conflict_type, severity, details)
+  values (p_thread_id, p_task_id, v_actor_agent_id, p_summary, coalesce(p_conflict_type, 'other'), coalesce(p_severity, 'medium'), coalesce(p_details, '{}'::jsonb))
+  returning id into v_conflict_id;
+
+  -- v_event_sequence stays NULL for a thread-level conflict (no task) — fixes the same latent
+  -- "record not assigned yet" bug on the no-task path.
+  if p_task_id is not null then
+    select event_sequence into v_event_sequence
+      from agent_board._append_task_event('unattested:unsigned-deliberate-rpc', p_task_id, v_actor_agent_id, 'conflict_raised', jsonb_build_object('conflict_id', v_conflict_id));
+  end if;
+
+  return query
+  select c.id, c.status, v_event_sequence, c.created_at, c.updated_at
+    from agent_board.conflicts c
+   where c.id = v_conflict_id;
+end;
+$function$
+;
+
+CREATE OR REPLACE FUNCTION agent_board.raise_escalation(p_thread_id uuid, p_raised_by_agent_id uuid, p_summary text, p_escalation_type text DEFAULT 'other'::text, p_severity text DEFAULT 'medium'::text, p_task_id uuid DEFAULT NULL::uuid, p_assigned_agent_id uuid DEFAULT NULL::uuid, p_details jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(escalation_id uuid, status text, task_event_sequence bigint, created_at timestamp with time zone, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_escalation_id uuid;
+  v_event_sequence bigint;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_raised_by_agent_id, 'p_raised_by_agent_id');
+
+  if not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+  if (select board_id is null from agent_board.threads where id = p_thread_id) then
+    perform 1 from agent_board.threads where id = p_thread_id for no key update;
+    if not agent_board._current_agent_can_access_thread(p_thread_id) then
+      raise exception 'thread not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+  -- OBSGATE-2 (#123): a board-linked thread requires a non-observer board role.
+  if not agent_board._current_agent_can_post_to_thread(p_thread_id) then
+    raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+  end if;
+
+  -- HOSTED (D16): a hosted delegate can act on no escalation, so it is never an assignee.
+  perform agent_board._refuse_delegate_addressee(p_assigned_agent_id, null, 'escalation assignment');
+
+  insert into agent_board.escalations(thread_id, task_id, raised_by_agent_id, assigned_agent_id, summary, escalation_type, severity, details)
+  values (p_thread_id, p_task_id, v_actor_agent_id, p_assigned_agent_id, p_summary, coalesce(p_escalation_type, 'other'), coalesce(p_severity, 'medium'), coalesce(p_details, '{}'::jsonb))
+  returning id into v_escalation_id;
+
+  -- v_event_sequence stays NULL for a thread-level escalation (no task) — fixes the same latent
+  -- "record not assigned yet" bug on the no-task path.
+  if p_task_id is not null then
+    select event_sequence into v_event_sequence
+      from agent_board._append_task_event('unattested:unsigned-deliberate-rpc', p_task_id, v_actor_agent_id, 'escalated', jsonb_build_object('escalation_id', v_escalation_id));
+  end if;
+
+  return query
+  select e.id, e.status, v_event_sequence, e.created_at, e.updated_at
+    from agent_board.escalations e
+   where e.id = v_escalation_id;
+end;
+$function$
+;
+
+
+CREATE OR REPLACE FUNCTION agent_board.add_artifact(p_created_by_agent_id uuid, p_uri text, p_artifact_type text DEFAULT 'url'::text, p_storage_kind text DEFAULT 'external_url'::text, p_thread_id uuid DEFAULT NULL::uuid, p_task_id uuid DEFAULT NULL::uuid, p_message_id uuid DEFAULT NULL::uuid, p_task_event_id uuid DEFAULT NULL::uuid, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(artifact_id uuid, task_event_sequence bigint, created_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_artifact_id uuid;
+  v_event_sequence bigint;
+  v_actor_agent_id uuid;
+  v_thread_id uuid;
+  v_anchor_thread uuid;
+  v_anchor_threads uuid[];
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_created_by_agent_id, 'p_created_by_agent_id');
+
+  if p_thread_id is null and p_task_id is null and p_message_id is null and p_task_event_id is null then
+    raise exception 'artifact target is required' using errcode = '22023';
+  end if;
+
+  if p_task_id is not null then
+    if not agent_board._current_agent_can_access_task(p_task_id) then
+      raise exception 'task not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+
+  if p_thread_id is not null and not agent_board._current_agent_can_access_thread(p_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+
+  if p_message_id is not null then
+    select m.thread_id into v_thread_id from agent_board.messages m where m.id = p_message_id;
+    if v_thread_id is null or not agent_board._current_agent_can_access_thread(v_thread_id) then
+      raise exception 'message not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+
+  if p_task_event_id is not null then
+    select te.thread_id into v_thread_id from agent_board.task_events te where te.id = p_task_event_id;
+    if v_thread_id is null or not agent_board._current_agent_can_access_thread(v_thread_id) then
+      raise exception 'task event not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+
+  -- OBSGATE-2 (#123): apply the posting gate to the artifact's effective thread (resolved from
+  -- whichever target was supplied). A board-linked thread requires a non-observer board role.
+  v_thread_id := coalesce(
+    p_thread_id,
+    v_thread_id,
+    (select tk.thread_id from agent_board.tasks tk where tk.id = p_task_id)
+  );
+  if v_thread_id is not null and not agent_board._current_agent_can_post_to_thread(v_thread_id) then
+    raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+  end if;
+
+  -- Every supplied anchor can persist a reference, even when another anchor is also
+  -- supplied. Lock all distinct thread identities in deterministic order before task locks.
+  select array_agg(anchor_thread order by anchor_thread) into v_anchor_threads
+    from (select distinct anchor_thread from (
+      select p_thread_id as anchor_thread
+      union all select thread_id from agent_board.tasks where id = p_task_id
+      union all select thread_id from agent_board.messages where id = p_message_id
+      union all select thread_id from agent_board.task_events where id = p_task_event_id
+    ) anchors where anchor_thread is not null) distinct_anchors;
+  foreach v_anchor_thread in array coalesce(v_anchor_threads, '{}'::uuid[]) loop
+    if (select board_id is null from agent_board.threads where id = v_anchor_thread) then
+      perform 1 from agent_board.threads where id = v_anchor_thread for no key update;
+      if not agent_board._current_agent_can_access_thread(v_anchor_thread) then
+        raise exception 'thread not accessible to current agent' using errcode = '42501';
+      end if;
+      if not agent_board._current_agent_can_post_to_thread(v_anchor_thread) then
+        raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+      end if;
+    end if;
+  end loop;
+
+  insert into agent_board.artifacts(thread_id, task_id, message_id, task_event_id, created_by_agent_id, artifact_type, storage_kind, uri, metadata)
+  values (p_thread_id, p_task_id, p_message_id, p_task_event_id, v_actor_agent_id, coalesce(p_artifact_type, 'url'), coalesce(p_storage_kind, 'external_url'), p_uri, coalesce(p_metadata, '{}'::jsonb))
+  returning id into v_artifact_id;
+
+  -- v_event_sequence stays NULL when there is no task (a thread/message/task_event artifact).
+  -- The prior `v_event record` + unconditional `v_event.event_sequence` raised
+  -- "record not assigned yet" on that no-task path — a latent bug fixed here while these
+  -- functions are being rewritten for the gate.
+  if p_task_id is not null then
+    select event_sequence into v_event_sequence
+      from agent_board._append_task_event('unattested:signed-metadata-rpc', p_task_id, v_actor_agent_id, 'artifact_added', jsonb_build_object('artifact_id', v_artifact_id));
+  end if;
+
+  return query
+  select v_artifact_id, v_event_sequence, now();
+end;
+$function$
+;
+
+CREATE OR REPLACE FUNCTION agent_board.acquire_claim(p_agent_id uuid, p_resource_kind text, p_resource_key text, p_lease_expires_at timestamp with time zone, p_task_id uuid DEFAULT NULL::uuid, p_thread_id uuid DEFAULT NULL::uuid, p_metadata jsonb DEFAULT '{}'::jsonb)
+ RETURNS TABLE(claim_id uuid, task_id uuid, thread_id uuid, agent_id uuid, resource_kind text, resource_key text, status text, lease_token uuid, lease_expires_at timestamp with time zone, released_at timestamp with time zone, created_at timestamp with time zone, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_thread_id uuid;
+  v_claim_id uuid;
+  v_actor_agent_id uuid;
+  v_shadow_authorized boolean;
+  v_ownerless boolean;
+  v_active_ownerless int;
+  v_board_id uuid;
+  v_board_policy text;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_agent_id, 'p_agent_id');
+
+  if nullif(trim(p_resource_key), '') is null then
+    raise exception 'resource key is required' using errcode = '22023';
+  end if;
+
+  -- CLAIMKEY (#133): normalize the resource key to its canonical, fleet-fingerprint-carrying
+  -- form BEFORE any lookup/insert, so the row stored (and the uniqueness index contended)
+  -- carry canonical identity. NORMALIZE-ONLY — this never rejects (rejection is ENFORCE).
+  p_resource_key := agent_board._canonical_claim_key(p_resource_kind, p_resource_key);
+
+  if p_task_id is not null then
+    select tasks.thread_id into v_thread_id from agent_board.tasks where id = p_task_id;
+    if v_thread_id is null then
+      raise exception 'task not found' using errcode = 'P0002';
+    end if;
+    if not agent_board._current_agent_can_access_task(p_task_id) then
+      raise exception 'task not accessible to current agent' using errcode = '42501';
+    end if;
+  else
+    v_thread_id := p_thread_id;
+  end if;
+
+  if v_thread_id is not null and not agent_board._current_agent_can_access_thread(v_thread_id) then
+    raise exception 'thread not accessible to current agent' using errcode = '42501';
+  end if;
+
+  -- message-board#291: the SUBJECT gate. The checks above answer "may this SESSION touch the
+  -- task/thread" and are short-circuited true for service_role; this one answers "does the
+  -- agent the claim is ABOUT already have access". Without it a service_role caller could name
+  -- any agent, and the resulting claims row -- itself an access disjunct, and a PERMANENT one
+  -- -- would MINT thread access (and, through the thread disjunct of
+  -- _current_agent_can_access_task, task access) rather than record a lock on something the
+  -- subject could already see.
+  --
+  -- UNCONDITIONAL IN *WHO*. DO NOT "optimize" this into `if _is_service_role() and not ...` or
+  -- `if v_actor_agent_id is distinct from agent_board.current_agent_id()`. For an authenticated
+  -- caller v_actor_agent_id IS current_agent_id() and the session check above already
+  -- established this same expression, so the redundancy is PROVABLE rather than suspected; it
+  -- is the price of an invariant this function states for itself instead of borrowing from
+  -- _resolved_actor_agent_id continuing to raise on a subject mismatch.
+  --
+  -- CONDITIONAL ON *THREAD PRESENCE*, which is not a loophole. A claim bound to neither a task
+  -- nor a thread stores thread_id = null, is a disjunct of nothing and mints no access.
+  -- _agent_can_access_thread answers false for a null thread, so gating unconditionally would
+  -- refuse every machine / repository / repo_file / ownerless claim in the fleet. This covers
+  -- exactly the claims that are keys.
+  --
+  -- PLACED AFTER THE TASK LOOKUP so a nonexistent task still answers P0002, not 42501 -- that
+  -- ordering IS test-pinned. Placed BEFORE the sweep only to match the predicate-before-side-
+  -- effects convention CLAIMGATE/ENFORCE states below; it is NOT what makes a denial free of
+  -- side effects. `raise exception` unwinds the whole call, so a refused caller changes no state
+  -- wherever this sits -- measured, by moving the gate below the sweep and observing the test
+  -- file stay entirely green.
+  if v_thread_id is not null
+     and not agent_board._agent_can_access_thread(v_thread_id, v_actor_agent_id) then
+    raise exception 'claim subject has no access to thread' using errcode = '42501';
+  end if;
+
+  -- OBSGATE-4 (#127): a claim on a TASK resource is authorized on the LOCKED task = the task
+  -- named by RESOURCE_KEY (resource_kind='task'). The active-resource uniqueness is on
+  -- (resource_kind, resource_key), so that is the task a squat contends for — gating resource_key
+  -- (NOT p_task_id, which only associates the claim/event) prevents locking task B's key while
+  -- authorizing on an unrelated task A passed as p_task_id. A non-uuid 'task' key cannot collide
+  -- with a uuid-keyed legitimate claim.
+  --
+  -- The composition MIRRORS append_task_event's: ACCESS then MUTATE. mutate alone is
+  -- insufficient — _current_agent_can_mutate_task admits any non-observer board member via
+  -- _current_agent_can_post_to_thread (board send-role), which is NOT thread access; on a
+  -- RESTRICTED thread a board member lacking thread access would pass mutate but must still be
+  -- denied (they cannot access the task). Requiring access too closes that gap and matches the
+  -- authorization a task-BOUND acquire already gets through append_task_event.
+  if p_resource_kind = 'task'
+     and p_resource_key ~ '^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{4}-[0-9a-fA-F]{12}$' then
+    if not agent_board._current_agent_can_access_task(p_resource_key::uuid) then
+      raise exception 'task not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_can_mutate_task(p_resource_key::uuid) then
+      raise exception 'claiming a task resource requires a non-observer board role, or task assignment/creation'
+        using errcode = '42501';
+    end if;
+  end if;
+
+  -- CLAIMGATE/SHADOW (#133): compute the fleet-graph authority verdict BEFORE the sweep (so
+  -- ENFORCE can flip this same point fail-closed with no observable side effect leaking to an
+  -- unauthorized caller). The verdict is stamped below regardless of enforcement.
+  v_shadow_authorized := agent_board._can_claim_resource(p_resource_kind, p_resource_key);
+
+  -- CLAIMGATE/ENFORCE (#133): per-kind GATED DENIAL, BEFORE the sweep (predicate-before-side-
+  -- effects). When this fleet-backed kind's flag is ON and the actor is UNAUTHORIZED, DENY —
+  -- no state has changed yet (sweep/insert are below). When OFF, fall through to the shadow-
+  -- stamp only (SHADOW behavior; blocks nothing). Non-fleet kinds never kind-enforce (resolver
+  -- returns FALSE). service_role is authorized by the predicate (wrapper short-circuit), so the
+  -- operator carve-out holds. Fail-closed-on-unknown is automatic: an unresolvable fleet resource
+  -- makes v_shadow_authorized FALSE, so an enforced acquire of it denies.
+  if p_resource_kind in ('machine', 'repository', 'repo_file')
+     and agent_board._claimgate_kind_enforced(p_resource_kind)
+     and not v_shadow_authorized then
+    raise exception 'not authorized to claim this % resource (fleet authority required)', p_resource_kind
+      using errcode = '42501';
+  end if;
+
+  -- CLAIMGATE/ENFORCE (#133): max-lease horizon. For an ENFORCED fleet-backed kind, CLAMP the
+  -- lease to now()+horizon (default 30d, operator-configurable) — a bound on lease term, NOT an
+  -- authority block. Clamp (not reject) so an over-long lease reconciles here / at its next renew.
+  -- service_role exempt (operator carve-out). Only reached by an AUTHORIZED acquire (unauthorized
+  -- was denied above), or when the flag is OFF (then the guard below is skipped entirely).
+  if p_resource_kind in ('machine', 'repository', 'repo_file')
+     and not agent_board._is_service_role()
+     and agent_board._claimgate_kind_enforced(p_resource_kind)
+     and p_lease_expires_at > now() + agent_board._claimgate_max_lease_horizon() then
+    p_lease_expires_at := now() + agent_board._claimgate_max_lease_horizon();
+  end if;
+
+  -- Ownerless tail (file/tool/custom): the ONE guard SHADOW carries — GATED OFF BY DEFAULT.
+  -- _claimgate_ownerless_guards_enabled() is false unless an operator flips it post-census, so in
+  -- SHADOW this block is skipped entirely and NOTHING is blocked (only the stamp above lands).
+  -- service_role is also exempt (operator carve-out, consistent with the predicate short-circuit).
+  v_ownerless := p_resource_kind in ('file', 'tool', 'custom');
+  if v_ownerless
+     and not agent_board._is_service_role()
+     and agent_board._claimgate_ownerless_guards_enabled() then
+    -- #405 THE BOARD LOCK, BEFORE THE POLICY DECISION AND ON THE PATH THAT SKIPS EVERYTHING.
+    -- The board opt-out USED TO BE a conjunct of the `if` above, which put the policy read before
+    -- any lock and — worse — before the agent-scoped quota lock that lives INSIDE this block. An
+    -- acquire that read a stale 'advisory' skipped the whole block and therefore took no lock at
+    -- all, so ordering against the agent lock was meaningless. The lock is hoisted OUT of the
+    -- decision and taken first, on every path through it.
+    --
+    -- THREE STATEMENTS, DELIBERATELY. Under READ COMMITTED each of these takes a FRESH SNAPSHOT,
+    -- so the policy read below observes a revert that committed while the lock was being waited
+    -- for. Fused into one statement it would not: a single statement's snapshot is taken before
+    -- the lock is granted. `_claimgate_lock_board_policy` REFUSES any other isolation level for
+    -- exactly this reason (see its comment) rather than silently reading stale policy.
+    v_board_id := agent_board._claimgate_board_of_thread(v_thread_id);
+    perform agent_board._claimgate_lock_board_policy(v_board_id);
+    -- RESOLVED FROM THE BOARD WE LOCKED, not from the thread again. `threads.board_id` is
+    -- first-board-wins (_associate_empty_thread stamps it only `where board_id is null`), so a
+    -- board can never MOVE — but a null board can be STAMPED during the wait. Re-resolving through
+    -- the thread would then read a board whose lock we do not hold, which is the same race one
+    -- level down. Resolving from v_board_id makes a stamp arriving mid-wait resolve to 'inherit',
+    -- the ENFORCING answer, so the drift is conservative by construction.
+    v_board_policy := agent_board._claimgate_board_claim_policy_of(v_board_id);
+
+    -- BOARD OPT-OUT: a board whose work is coordinated by SOMEONE ELSE'S locking (a repo lock, a
+    -- scheduler lease, an external mutex) can set claim_policy='advisory'. Our claims are then
+    -- RECORDED for visibility and never ENFORCED, so we cannot reject an acquire that their own
+    -- lock already permitted. Resolved from the claim's thread; a claim with no thread, or a
+    -- thread with no board, has no board to ask and falls back to the fleet-wide flags.
+    if v_board_policy <> 'advisory' then
+      -- TTL CAP: an ownerless lease may not exceed the max horizon. Rejects an over-long acquire;
+      -- this is a lease-length bound, NOT an authority block.
+      if p_lease_expires_at > now() + agent_board._claimgate_ownerless_ttl_cap() then
+        raise exception 'ownerless claim lease horizon exceeds cap (%)', agent_board._claimgate_ownerless_ttl_cap()
+          using errcode = '22023';
+      end if;
+
+      -- QUOTA (transactionally serialized): an actor-scoped advisory XACT lock serializes this
+      -- actor's concurrent acquisitions (on DIFFERENT keys, which the row-level uniqueness index
+      -- does NOT), so a count-before-insert cannot race two claims past the cap. The lock releases
+      -- at commit; it does not block other actors (the key mixes in the actor id). TAKEN AFTER THE
+      -- BOARD LOCK, never before it: board-then-agent is the one order every path here uses.
+      perform pg_advisory_xact_lock(hashtext('agent_board.claimgate_ownerless_quota'), hashtext(v_actor_agent_id::text));
+      -- #388: THE COUNT IS THE SHARED HELPER NOW, not an inline predicate. renew_claim asks the
+      -- same question one line of arithmetic away, and two hand-copies of a predicate across two
+      -- enforcement paths is rule 1's own failure shape. The ADVISORY LOCK ABOVE STAYS HERE AND IS
+      -- NOT MIRRORED INTO RENEW, deliberately: it exists because acquire COUNTS THEN INSERTS, and a
+      -- renew inserts nothing (see 20260928000100's header).
+      v_active_ownerless := agent_board._claimgate_active_ownerless_claims(v_actor_agent_id);
+      if v_active_ownerless >= agent_board._claimgate_ownerless_quota() then
+        raise exception 'ownerless active-claim quota reached (% per agent)', agent_board._claimgate_ownerless_quota()
+          using errcode = '54000';
+      end if;
+    end if;
+  end if;
+
+  -- Task-bound claims store the thread resolved from the task above. Thread-only
+  -- claims create independent history and must serialize with first association.
+  -- This is after the existing board/actor advisory locks and before claim writes.
+  if p_task_id is null and v_thread_id is not null
+     and (select board_id is null from agent_board.threads where id = v_thread_id) then
+    perform 1 from agent_board.threads where id = v_thread_id for no key update;
+    if not agent_board._current_agent_can_access_thread(v_thread_id) then
+      raise exception 'thread not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._agent_can_access_thread(v_thread_id, v_actor_agent_id) then
+      raise exception 'claim subject has no access to thread' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_can_post_to_thread(v_thread_id) then
+      raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+    end if;
+  end if;
+
+  -- CLAIMKEY (#133) MUST-FIX 3: the sweep AND the conflict check are ALIAS-AWARE. p_resource_key
+  -- is already canonical (above); comparing against the CANONICAL form of each existing row's key
+  -- matches both a canonical row AND an un-healed LEGACY row for the same physical resource. Without
+  -- this, acquire('machine','machine:fpDH') would normalize to 'fpDH', see no exact-'fpDH' conflict
+  -- against a still-active legacy 'machine:fpDH' row, and INSERT a second live hold — breaking mutual
+  -- exclusion during the legacy window. Closing it here in code does NOT depend on the operator-owned
+  -- live census.
+  update agent_board.claims c
+     set status = 'expired',
+         updated_at = now()
+   where c.resource_kind = p_resource_kind
+     and agent_board._canonical_claim_key(c.resource_kind, c.resource_key) = p_resource_key
+     and c.status = 'active'
+     and c.released_at is null
+     and c.lease_expires_at <= now();
+
+  if exists (
+    select 1 from agent_board.claims
+     where claims.resource_kind = p_resource_kind
+       and agent_board._canonical_claim_key(claims.resource_kind, claims.resource_key) = p_resource_key
+       and claims.status = 'active'
+       and claims.released_at is null
+       and claims.lease_expires_at > now()
+  ) then
+    raise exception 'conflicting active claim' using errcode = '23505';
+  end if;
+
+  insert into agent_board.claims(task_id, thread_id, agent_id, resource_kind, resource_key, lease_expires_at, metadata)
+  values (
+    p_task_id, v_thread_id, v_actor_agent_id, p_resource_kind, p_resource_key, p_lease_expires_at,
+    -- SHADOW stamp: record the authority verdict alongside any caller metadata. Merged last so it
+    -- is authoritative over a caller-supplied claimgate_shadow key.
+    coalesce(p_metadata, '{}'::jsonb)
+      || jsonb_build_object(
+           'claimgate_shadow',
+           jsonb_build_object('kind', p_resource_kind, 'authorized', v_shadow_authorized)
+         )
+  )
+  returning id into v_claim_id;
+
+  if p_task_id is not null then
+    perform agent_board._append_task_event('unattested:signed-metadata-rpc', p_task_id, v_actor_agent_id, 'claimed', jsonb_build_object('claim_id', v_claim_id, 'resource_kind', p_resource_kind, 'resource_key', p_resource_key));
+  end if;
+
+  return query
+  select c.id, c.task_id, c.thread_id, c.agent_id, c.resource_kind, c.resource_key, c.status, c.lease_token, c.lease_expires_at, c.released_at, c.created_at, c.updated_at
+    from agent_board.claims c
+   where c.id = v_claim_id;
+end;
+$function$
+;
+
+CREATE OR REPLACE FUNCTION agent_board.heartbeat(p_agent_id uuid DEFAULT NULL::uuid, p_thread_id uuid DEFAULT NULL::uuid, p_availability text DEFAULT NULL::text, p_activity_summary text DEFAULT NULL::text, p_expires_in interval DEFAULT '00:05:00'::interval, p_metadata jsonb DEFAULT NULL::jsonb)
+ RETURNS TABLE(agent_id uuid, availability text, thread_id uuid, last_heartbeat_at timestamp with time zone, expires_at timestamp with time zone, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_actor_agent_id uuid;
+  v_effective_thread uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_agent_id, 'p_agent_id');
+
+  -- Unchanged: a supplied thread must exist and be reachable by the caller. A NULL thread now
+  -- means "leave my thread as it is", so it is not a claim about any thread and needs no check.
+  if p_thread_id is not null then
+    if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+      raise exception 'thread not found' using errcode = 'P0002';
+    end if;
+    if not agent_board._current_agent_can_access_thread(p_thread_id) then
+      raise exception 'thread not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+
+  -- Serialize presence changes for the actor before resolving a retained thread. A
+  -- NULL argument preserves the stored thread while changing caller text/metadata.
+  perform pg_advisory_xact_lock(hashtext('agent_board.heartbeat_thread'), hashtext(v_actor_agent_id::text));
+  select coalesce(p_thread_id, pr.thread_id) into v_effective_thread
+    from agent_board.presence pr where pr.agent_id = v_actor_agent_id;
+  v_effective_thread := coalesce(v_effective_thread, p_thread_id);
+  if v_effective_thread is not null
+     and (select board_id is null from agent_board.threads where id = v_effective_thread) then
+    perform 1 from agent_board.threads where id = v_effective_thread for no key update;
+    if not agent_board._current_agent_can_access_thread(v_effective_thread) then
+      raise exception 'thread not accessible to current agent' using errcode = '42501';
+    end if;
+    if not agent_board._current_agent_can_post_to_thread(v_effective_thread) then
+      raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+    end if;
+  end if;
+
+  return query
+  insert into agent_board.presence(agent_id, thread_id, availability, activity_summary, last_heartbeat_at, expires_at, metadata, updated_at)
+  values (
+    v_actor_agent_id,
+    p_thread_id,
+    -- INSERT: a null still lands the documented starting value, so a first heartbeat behaves
+    -- exactly as it did before this migration.
+    coalesce(p_availability, 'ready'),
+    p_activity_summary,
+    now(),
+    now() + coalesce(p_expires_in, interval '5 minutes'),
+    coalesce(p_metadata, '{}'::jsonb),
+    now()
+  )
+  on conflict on constraint presence_pkey do update
+    -- UPDATE: null preserves. `presence.<col>` is the EXISTING row; `excluded.<col>` is what this
+    -- call proposed. Coalescing onto the existing value is the whole fix -- it is what lets a
+    -- lease refresh say nothing about availability.
+    set thread_id        = coalesce(excluded.thread_id, presence.thread_id),
+        availability     = coalesce(p_availability, presence.availability),
+        activity_summary = coalesce(excluded.activity_summary, presence.activity_summary),
+        metadata         = coalesce(p_metadata, presence.metadata),
+        -- These three are the POINT of a heartbeat and always advance.
+        last_heartbeat_at = excluded.last_heartbeat_at,
+        expires_at        = excluded.expires_at,
+        updated_at        = excluded.updated_at
+  returning presence.agent_id, presence.availability, presence.thread_id, presence.last_heartbeat_at, presence.expires_at, presence.updated_at;
+end;
+$function$
+;
+
+-- Restate canonical permissions and catalog comments with every replacement.
+-- These declarations preserve the grants from a fresh build of the prior tree.
+revoke all on function agent_board._upsert_delivery_recipient(text,uuid,text,uuid,uuid,uuid,uuid,uuid,jsonb) from public, anon, authenticated, service_role, agent_board_delegate;
+grant execute on function agent_board._upsert_delivery_recipient(text,uuid,text,uuid,uuid,uuid,uuid,uuid,jsonb) to "service_role";
+comment on function agent_board._upsert_delivery_recipient(text,uuid,text,uuid,uuid,uuid,uuid,uuid,jsonb) is 'Enforces thread/board identity and the locked empty-history boundary for message, task and delegation delivery sources. Supplying a source ID does not exempt its private history. The sending RPC validates caller authority before its own writes.';
+
+revoke all on function agent_board.acquire_claim(uuid,text,text,timestamp with time zone,uuid,uuid,jsonb) from public, anon, authenticated, service_role, agent_board_delegate;
+grant execute on function agent_board.acquire_claim(uuid,text,text,timestamp with time zone,uuid,uuid,jsonb) to "service_role";
+grant execute on function agent_board.acquire_claim(uuid,text,text,timestamp with time zone,uuid,uuid,jsonb) to "authenticated";
+comment on function agent_board.acquire_claim(uuid,text,text,timestamp with time zone,uuid,uuid,jsonb) is 'Takes an exclusive lease on (resource_kind, resource_key), optionally bound to a task and/or a thread. The subject is _resolved_actor_agent_id(p_agent_id): authenticated callers are forced to current_agent_id() and fail closed on mismatch; service_role may claim on behalf of another agent. A CLAIM IS A LOCK, NEVER A KEY (message-board#291): because a claims row for (thread_id, agent_id) is itself a disjunct of _agent_can_access_thread, a claim bound to a thread requires the NAMED agent to already pass that predicate, or the call raises 42501 ''claim subject has no access to thread''. This closes the only route to a claims row (no role holds INSERT on agent_board.claims by any route, and acquire_claim is the only agent_board function that inserts one), and with it the only route by which service_role could hand an arbitrary agent durable access to an inherit thread -- and, through the thread disjunct of _current_agent_can_access_task, to its tasks. The gate is UNCONDITIONAL in who (never branched on _is_service_role() or on the subject differing from the session agent) and applies only when the claim is bound to a thread: a task-less, thread-less claim stores thread_id = null, is a disjunct of nothing and mints no access, so gating it would refuse every machine/repository/repo_file/ownerless claim in the fleet. It sits after the task lookup, so a nonexistent task still answers P0002; it also sits before the expiry sweep, by CLAIMGATE convention rather than necessity (a raise unwinds the whole call, so a refused caller changes no state wherever the check sits). On the authenticated path it is provably a no-op: the session check just evaluated the same expression for the same agent. ONE ERROR CODE CHANGES, deliberately: for a service_role caller on a thread-bound claim, a nonexistent p_thread_id -- or a nonexistent named subject -- used to reach the insert and surface as 23503 on the claims foreign keys, and now answers 42501 here instead. That is one rule with two instances, not two changes, and 23503 is NOT restored: preserving it would require probing thread existence before the access gate, which leaks existence to a caller with no access. A THREAD-LESS claim for a nonexistent subject still answers 23503, which is the boundary. THE CLAIM IT MINTS IS PERMANENT, AND THAT IS RATIFIED, NOT AN OVERSIGHT -- see the comment on _current_agent_can_access_thread. Other gates on this function are unchanged: OBSGATE-4 task-resource authorization (#127), CLAIMKEY canonicalization and CLAIMGATE shadow/enforce fleet authority (#133).';
+
+revoke all on function agent_board.add_artifact(uuid,text,text,text,uuid,uuid,uuid,uuid,jsonb) from public, anon, authenticated, service_role, agent_board_delegate;
+grant execute on function agent_board.add_artifact(uuid,text,text,text,uuid,uuid,uuid,uuid,jsonb) to "service_role";
+grant execute on function agent_board.add_artifact(uuid,text,text,text,uuid,uuid,uuid,uuid,jsonb) to "authenticated";
+comment on function agent_board.add_artifact(uuid,text,text,text,uuid,uuid,uuid,uuid,jsonb) is 'Records an artifact using its supplied thread, message, task and event anchors. Unassociated anchor threads are locked in deterministic order and access is rechecked after waiting.';
+
+revoke all on function agent_board.create_task(uuid,uuid,text,text,uuid,uuid,text,text,jsonb) from public, anon, authenticated, service_role, agent_board_delegate;
+grant execute on function agent_board.create_task(uuid,uuid,text,text,uuid,uuid,text,text,jsonb) to "service_role";
+grant execute on function agent_board.create_task(uuid,uuid,text,text,uuid,uuid,text,text,jsonb) to "authenticated";
+comment on function agent_board.create_task(uuid,uuid,text,text,uuid,uuid,text,text,jsonb) is 'Creates a task under the existing access and posting gates. Writes to an unassociated thread serialize with first board association and recheck access after waiting.';
+
+revoke all on function agent_board.create_tasking_delivery(uuid,uuid,text,text,uuid[],uuid,text,text,text,jsonb) from public, anon, authenticated, service_role, agent_board_delegate;
+grant execute on function agent_board.create_tasking_delivery(uuid,uuid,text,text,uuid[],uuid,text,text,text,jsonb) to "service_role";
+grant execute on function agent_board.create_tasking_delivery(uuid,uuid,text,text,uuid[],uuid,text,text,text,jsonb) to "authenticated";
+comment on function agent_board.create_tasking_delivery(uuid,uuid,text,text,uuid[],uuid,text,text,text,jsonb) is 'Creates or reuses a tasking send after validating the session actor and any board target. First board association precedes its own task and event writes; explicit recipient delivery rows preserve their private scope.';
+
+revoke all on function agent_board.heartbeat(uuid,uuid,text,text,interval,jsonb) from public, anon, authenticated, service_role, agent_board_delegate;
+grant execute on function agent_board.heartbeat(uuid,uuid,text,text,interval,jsonb) to "service_role";
+grant execute on function agent_board.heartbeat(uuid,uuid,text,text,interval,jsonb) to "authenticated";
+comment on function agent_board.heartbeat(uuid,uuid,text,text,interval,jsonb) is '#366/F1+F4: asserts liveness for the acting agent. Every optional field defaults to NULL and NULL means LEAVE UNCHANGED on an existing row -- so a caller refreshing only the lease does not reset availability to ''ready'' or clear thread_id/activity_summary/metadata. On a FIRST heartbeat a null still lands the documented starting value (''ready'', ''{}''). Consequence, deliberate: thread_id and activity_summary cannot be CLEARED through this RPC, because null is how a caller declines to change them. Before this migration p_availability defaulted to ''ready'', which made "not supplied" indistinguishable from "supplied as ready" and made an implicit activity-coupled heartbeat destructive. p_agent_id also gains a null default (#366/F1): it was required by the SIGNATURE though the body already resolves the actor from the session via _resolved_actor_agent_id, so an authenticated caller may now omit it entirely. service_role must still supply it -- that resolver raises 22023 for a null id under service_role, unchanged.';
+
+revoke all on function agent_board.post_board_message(uuid,uuid,uuid,text,text,text,text,text,jsonb) from public, anon, authenticated, service_role, agent_board_delegate;
+grant execute on function agent_board.post_board_message(uuid,uuid,uuid,text,text,text,text,text,jsonb) to "service_role";
+grant execute on function agent_board.post_board_message(uuid,uuid,uuid,text,text,text,text,text,jsonb) to "authenticated";
+grant execute on function agent_board.post_board_message(uuid,uuid,uuid,text,text,text,text,text,jsonb) to "agent_board_delegate";
+comment on function agent_board.post_board_message(uuid,uuid,uuid,text,text,text,text,text,jsonb) is 'Creates or reuses a canonical board post after validating the session actor, board authority and locked thread association; delivery fan-out and downstream effects are transactional.';
+
+revoke all on function agent_board.post_message(uuid,uuid,text,text,uuid,jsonb) from public, anon, authenticated, service_role, agent_board_delegate;
+grant execute on function agent_board.post_message(uuid,uuid,text,text,uuid,jsonb) to "service_role";
+grant execute on function agent_board.post_message(uuid,uuid,text,text,uuid,jsonb) to "authenticated";
+grant execute on function agent_board.post_message(uuid,uuid,text,text,uuid,jsonb) to "agent_board_delegate";
+comment on function agent_board.post_message(uuid,uuid,text,text,uuid,jsonb) is 'Posts to an accessible thread after the message-sequence lock and a fresh posting-authority check, preserving session-derived author and hosted-delegate metadata.';
+
+revoke all on function agent_board.raise_conflict(uuid,uuid,text,text,text,uuid,jsonb) from public, anon, authenticated, service_role, agent_board_delegate;
+grant execute on function agent_board.raise_conflict(uuid,uuid,text,text,text,uuid,jsonb) to "service_role";
+grant execute on function agent_board.raise_conflict(uuid,uuid,text,text,text,uuid,jsonb) to "authenticated";
+comment on function agent_board.raise_conflict(uuid,uuid,text,text,text,uuid,jsonb) is 'Records a conflict after validating access and serializing an unassociated target thread with first board association, including taskful conflicts whose target thread differs from the task thread.';
+
+revoke all on function agent_board.raise_escalation(uuid,uuid,text,text,text,uuid,uuid,jsonb) from public, anon, authenticated, service_role, agent_board_delegate;
+grant execute on function agent_board.raise_escalation(uuid,uuid,text,text,text,uuid,uuid,jsonb) to "service_role";
+grant execute on function agent_board.raise_escalation(uuid,uuid,text,text,text,uuid,uuid,jsonb) to "authenticated";
+comment on function agent_board.raise_escalation(uuid,uuid,text,text,text,uuid,uuid,jsonb) is 'Records an escalation under the existing actor and assignee gates after serializing an unassociated target thread with first board association.';