@consiliency/agent-board-schema 1.12.0 → 1.22.0

package/migrations/20260815000100_agent_board_obsgate2_authoring_gates.sql

@@ -0,0 +1,287 @@
+-- OBSGATE-2 (#123) — extend the board posting rule to every thread-authoring RPC.
+--
+-- #78 (OBSGATE) closed the message-authoring door: an observer can no longer post a MESSAGE
+-- into a board-linked thread (the gate _current_agent_can_post_to_thread is enforced in
+-- post_message). But post_message is not the only way to author into a thread. These
+-- authenticated RPCs author thread-scoped content and gated only on _current_agent_can_access_
+-- thread — no posting-rule / send-role check — so an observer with board-thread access could
+-- still author through them (verified live: create_task and delegate_task):
+--
+--   create_task      -> a task + 'created' task_event
+--   delegate_task    -> a task (calls create_task) — closed TRANSITIVELY by gating create_task
+--   add_artifact     -> an artifact (targets thread / task / message / task_event)
+--   raise_conflict   -> a conflict record
+--   raise_escalation -> an escalation record
+--
+-- Maintainer decision: an observer is PURE READ within a board (per-board role — the agent can
+-- still participate on any OTHER board it belongs to, and board-less DM/multicast threads are
+-- ungated), so ALL of the above are gated. The shared #78 predicate is reused: a board-linked
+-- thread requires a non-observer board role; a board-less thread stays access-only; service_role
+-- short-circuits.
+--
+-- Each function is CREATE OR REPLACE'd with the SAME body plus the gate after its existing
+-- access check; grants are re-asserted. delegate_task is intentionally NOT modified — it reaches
+-- create_task(v_parent.thread_id, ...), so the gate fires there.
+--
+-- Additive, forward-only. schema_version stays 8.
+
+-- 1. create_task (also closes delegate_task transitively) --------------------
+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,
+  p_assigned_agent_id uuid default null,
+  p_parent_task_id uuid default null,
+  p_priority text default 'medium',
+  p_orchestration_mode text default 'distributed',
+  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;
+  -- 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;
+
+  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));
+
+  insert into agent_board.task_events(task_id, thread_id, actor_agent_id, event_sequence, event_type, payload)
+  values (v_task_id, p_thread_id, v_actor_agent_id, 1, 'created', jsonb_build_object('title', trim(p_title)))
+  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$;
+revoke all on function agent_board.create_task(uuid, uuid, text, text, uuid, uuid, text, text, jsonb) from public, anon;
+grant execute on function agent_board.create_task(uuid, uuid, text, text, uuid, uuid, text, text, jsonb) to authenticated, service_role;
+
+-- 2. add_artifact -----------------------------------------------------------
+create or replace function agent_board.add_artifact(
+  p_created_by_agent_id uuid,
+  p_uri text,
+  p_artifact_type text default 'url',
+  p_storage_kind text default 'external_url',
+  p_thread_id uuid default null,
+  p_task_id uuid default null,
+  p_message_id uuid default null,
+  p_task_event_id uuid default null,
+  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;
+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;
+
+  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(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$;
+revoke all on function agent_board.add_artifact(uuid, text, text, text, uuid, uuid, uuid, uuid, jsonb) from public, anon;
+grant execute on function agent_board.add_artifact(uuid, text, text, text, uuid, uuid, uuid, uuid, jsonb) to authenticated, service_role;
+
+-- 3. raise_conflict ---------------------------------------------------------
+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',
+  p_severity text default 'medium',
+  p_task_id uuid default null,
+  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;
+  -- 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(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$;
+revoke all on function agent_board.raise_conflict(uuid, uuid, text, text, text, uuid, jsonb) from public, anon;
+grant execute on function agent_board.raise_conflict(uuid, uuid, text, text, text, uuid, jsonb) to authenticated, service_role;
+
+-- 4. raise_escalation -------------------------------------------------------
+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',
+  p_severity text default 'medium',
+  p_task_id uuid default null,
+  p_assigned_agent_id uuid default null,
+  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;
+  -- 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.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(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$;
+revoke all on function agent_board.raise_escalation(uuid, uuid, text, text, text, uuid, uuid, jsonb) from public, anon;
+grant execute on function agent_board.raise_escalation(uuid, uuid, text, text, text, uuid, uuid, jsonb) to authenticated, service_role;

package/migrations/20260816000100_agent_board_obsgate3_task_lifecycle.sql

@@ -0,0 +1,118 @@
+-- OBSGATE-3 (#125) — gate task-lifecycle mutation so a board observer cannot mutate a
+-- board-thread task, WITHOUT over-blocking a legitimate assignee/creator.
+--
+-- #123 (OBSGATE-2) gated content CREATION (create_task/add_artifact/raise_conflict/
+-- raise_escalation). But task-lifecycle STATE mutation is a separate door: append_task_event
+-- (the task_events chokepoint — authenticated + MCP-exposed) authors a task_events row carrying
+-- the task's thread_id AND flips task status/assignment, gating ONLY on
+-- _current_agent_can_access_task. A board observer could call it (and its callers acquire_claim /
+-- resolve_conflict / resolve_escalation, which all append through it) on a board-thread task.
+--
+-- A blanket board-send-role gate is WRONG here: a board-thread task can be assigned to a
+-- NON-board-member, who legitimately needs to work it (verified: such an assignee has
+-- can_access_task=true but can_post_to_thread=false). So the rule is assignee-aware
+-- (maintainer decision — assignee + creator carve-out):
+--
+--   allow mutation of a task iff:
+--     service_role                                   (operator; also the signed_* path)
+--     OR _current_agent_can_post_to_thread(thread)   (non-observer board member; or any
+--                                                      participant on a board-less thread)
+--     OR current_agent_id() = task.assigned_agent_id (the assignee — even a non-member/observer)
+--     OR current_agent_id() = task.created_by_agent_id (the creator)
+--   deny otherwise — i.e. a board observer meddling with a task it is not a party to.
+--
+-- Enforced at the append_task_event CHOKEPOINT, so acquire_claim / resolve_conflict /
+-- resolve_escalation are closed transitively and atomically (they mutate their own table then
+-- append; a denied append rolls the whole call back). create_task does NOT use append_task_event
+-- (it inserts task_events directly) and is already #123-gated, so it is unaffected. The #123
+-- creation RPCs that DO append (add_artifact/raise_conflict/raise_escalation/delegate_task) have
+-- already passed their own gate, so the mutate-task predicate is a consistent no-op for them.
+--
+-- The predicate is derived from the SESSION (current_agent_id / _is_service_role), never the
+-- caller-supplied p_actor_agent_id. Additive, forward-only. schema_version stays 8.
+
+-- 1. predicate --------------------------------------------------------------
+create or replace function agent_board._current_agent_can_mutate_task(p_task_id uuid)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select agent_board._is_service_role()
+    or exists (
+      select 1
+        from agent_board.tasks t
+       where t.id = p_task_id
+         and (
+           agent_board._current_agent_can_post_to_thread(t.thread_id)
+           or agent_board.current_agent_id() = t.assigned_agent_id
+           or agent_board.current_agent_id() = t.created_by_agent_id
+         )
+    )
+$$;
+comment on function agent_board._current_agent_can_mutate_task(uuid) is
+  'OBSGATE-3 (#125): may the current agent mutate this task (append events / change status)? service_role, or a non-observer board sender on the task''s thread (board-less participant via the access fallback), or the task''s assignee, or its creator. A board observer that is not a party to the task is denied. Session-derived; internal-only, PUBLIC EXECUTE revoked.';
+revoke all on function agent_board._current_agent_can_mutate_task(uuid) from public, anon, authenticated;
+
+-- 2. gate the append_task_event chokepoint ----------------------------------
+-- CREATE OR REPLACE with the SAME body plus the mutate-task gate after the access check; grants
+-- re-asserted. The task row is already locked FOR UPDATE above, so the predicate's re-select is
+-- consistent within the transaction.
+create or replace function agent_board.append_task_event(
+  p_task_id uuid,
+  p_actor_agent_id uuid,
+  p_event_type text,
+  p_payload jsonb default '{}'::jsonb,
+  p_status text default null,
+  p_assigned_agent_id uuid default null,
+  p_completed_at timestamp with time zone default null
+)
+returns table(task_id uuid, thread_id uuid, event_id uuid, event_sequence bigint, task_status text, assigned_agent_id uuid, updated_at timestamp with time zone, completed_at timestamp with time zone)
+language plpgsql
+security definer
+set search_path to 'agent_board', 'public'
+as $function$
+declare
+  v_thread_id uuid;
+  v_sequence bigint;
+  v_event_id uuid;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_actor_agent_id, 'p_actor_agent_id');
+
+  select tasks.thread_id into v_thread_id from agent_board.tasks where id = p_task_id for update;
+  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;
+  -- OBSGATE-3 (#125): mutating a board-thread task requires a non-observer board role, or being
+  -- the task's assignee/creator. Closes acquire_claim/resolve_conflict/resolve_escalation
+  -- transitively; the assignee/creator carve-out preserves a legitimate non-member worker.
+  if not agent_board._current_agent_can_mutate_task(p_task_id) then
+    raise exception 'task mutation requires a non-observer board role, or task assignment/creation'
+      using errcode = '42501';
+  end if;
+
+  select coalesce(max(te.event_sequence), 0) + 1 into v_sequence from agent_board.task_events te where te.task_id = p_task_id;
+  insert into agent_board.task_events(task_id, thread_id, actor_agent_id, event_sequence, event_type, payload)
+  values (p_task_id, v_thread_id, v_actor_agent_id, v_sequence, p_event_type, coalesce(p_payload, '{}'::jsonb))
+  returning id into v_event_id;
+
+  update agent_board.tasks
+     set status = coalesce(p_status, tasks.status),
+         assigned_agent_id = coalesce(p_assigned_agent_id, tasks.assigned_agent_id),
+         completed_at = coalesce(p_completed_at, tasks.completed_at),
+         updated_at = now()
+   where id = p_task_id;
+
+  return query
+  select t.id, t.thread_id, v_event_id, v_sequence, t.status, t.assigned_agent_id, t.updated_at, t.completed_at
+    from agent_board.tasks t
+   where t.id = p_task_id;
+end;
+$function$;
+revoke all on function agent_board.append_task_event(uuid, uuid, text, jsonb, text, uuid, timestamp with time zone) from public, anon;
+grant execute on function agent_board.append_task_event(uuid, uuid, text, jsonb, text, uuid, timestamp with time zone) to authenticated, service_role;

package/migrations/20260817000100_agent_board_obsgate4_claims_lifecycle.sql

@@ -0,0 +1,250 @@
+-- OBSGATE-4 (#127) — close the task-resource claim squat + the task-less resolve authz gap.
+--
+-- Found by the #126 (OBSGATE-3) panel. Two remaining task-lifecycle-adjacent doors that skip
+-- the append_task_event chokepoint gated in #125:
+--
+-- (a) CLAIM SQUAT (DoS). acquire_claim on resource_kind='task' with resource_key = a task's id
+--     performs NO task authz when p_task_id is null — verified: ANY authenticated agent (not
+--     only a board observer, and even with no task/thread param) can acquire the claim and, via
+--     the global active-resource uniqueness, block the legitimate claimant; release_claim is
+--     ownership-only so the squat is sticky. Fix: a claim on a TASK resource requires ACCESS +
+--     MUTATE rights (the same composition append_task_event uses) on the task named by
+--     RESOURCE_KEY — the locked task the uniqueness index contends on, NOT p_task_id (whose
+--     association is gated separately by the append below). This closes the squat for every
+--     caller (a squat must key on the victim task's uuid to collide, and that uuid now gates on
+--     access+mutate rights). Non-'task' resource kinds (file/machine/...) are a separate
+--     coordination-authz concern, intentionally out of scope.
+--
+-- (b) TASK-LESS resolve_conflict / resolve_escalation. For a conflict/escalation WITH a task,
+--     the append_task_event('status_changed') already applies the #125 mutate-task gate
+--     (assignee-aware). For a TASK-LESS one, no append runs, so it gated only on
+--     _current_agent_can_access_thread — an authz asymmetry that was fail-closed only by a
+--     latent 55000 "record v_event is not assigned yet" bug (v_event referenced unconditionally
+--     while assigned only on the task branch). Fix: gate the task-less path on the board posting
+--     rule AND repair the v_event bug (nullable sequence, NULL when no task) so fixing the bug
+--     can't silently open the path.
+--
+-- release_claim / renew_claim stay ownership-only (maintainer decision): the acquire gate closes
+-- the squat at its source, so a demoted member retaining its own lease until TTL is a benign edge.
+--
+-- All gates are session-derived. Additive, forward-only. schema_version stays 8.
+
+-- 1. acquire_claim: a task-resource claim requires task-mutate rights ---------
+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,
+  p_thread_id uuid default null,
+  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;
+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;
+
+  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;
+
+  -- 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;
+
+  update agent_board.claims c
+     set status = 'expired',
+         updated_at = now()
+   where c.resource_kind = p_resource_kind
+     and 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 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, coalesce(p_metadata, '{}'::jsonb))
+  returning id into v_claim_id;
+
+  if p_task_id is not null then
+    perform agent_board.append_task_event(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$;
+revoke all on function agent_board.acquire_claim(uuid, text, text, timestamp with time zone, uuid, uuid, jsonb) from public, anon;
+grant execute on function agent_board.acquire_claim(uuid, text, text, timestamp with time zone, uuid, uuid, jsonb) to authenticated, service_role;
+
+-- 2. resolve_conflict: gate the task-less path + fix the v_event 55000 --------
+create or replace function agent_board.resolve_conflict(
+  p_conflict_id uuid,
+  p_resolved_by_agent_id uuid,
+  p_details jsonb default '{}'::jsonb
+)
+returns table(conflict_id uuid, status text, resolved_at timestamp with time zone, updated_at timestamp with time zone, task_event_sequence bigint)
+language plpgsql
+security definer
+set search_path to 'agent_board', 'public'
+as $function$
+declare
+  v_conflict agent_board.conflicts%rowtype;
+  v_event_sequence bigint;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_resolved_by_agent_id, 'p_resolved_by_agent_id');
+
+  select *
+    into v_conflict
+    from agent_board.conflicts c
+   where c.id = p_conflict_id
+     and c.status <> 'resolved';
+  if v_conflict.id is null then
+    raise exception 'conflict not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(v_conflict.thread_id) then
+    raise exception 'conflict not accessible to current agent' using errcode = '42501';
+  end if;
+  -- OBSGATE-4 (#127): a task-bound resolve is gated by append_task_event (#125 mutate-task,
+  -- assignee-aware). A TASK-LESS conflict has no such chokepoint, so gate it on the board
+  -- posting rule here (a board observer may not resolve).
+  if v_conflict.task_id is null
+     and not agent_board._current_agent_can_post_to_thread(v_conflict.thread_id) then
+    raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+  end if;
+
+  update agent_board.conflicts
+     set status = 'resolved',
+         resolved_by_agent_id = v_actor_agent_id,
+         resolved_at = now(),
+         details = details || coalesce(p_details, '{}'::jsonb),
+         updated_at = now()
+   where id = p_conflict_id
+   returning * into v_conflict;
+
+  -- v_event_sequence stays NULL for a task-less conflict (fixes the latent "record not assigned"
+  -- bug; the unconditional v_event.event_sequence reference raised 55000 on this path).
+  if v_conflict.task_id is not null then
+    select event_sequence into v_event_sequence
+      from agent_board.append_task_event(v_conflict.task_id, v_actor_agent_id, 'status_changed', jsonb_build_object('kind', 'conflict_resolved', 'conflict_id', p_conflict_id));
+  end if;
+
+  return query
+  select v_conflict.id, v_conflict.status, v_conflict.resolved_at, v_conflict.updated_at, v_event_sequence;
+end;
+$function$;
+revoke all on function agent_board.resolve_conflict(uuid, uuid, jsonb) from public, anon;
+grant execute on function agent_board.resolve_conflict(uuid, uuid, jsonb) to authenticated, service_role;
+
+-- 3. resolve_escalation: same task-less gate + v_event fix -------------------
+create or replace function agent_board.resolve_escalation(
+  p_escalation_id uuid,
+  p_resolved_by_agent_id uuid,
+  p_details jsonb default '{}'::jsonb
+)
+returns table(escalation_id uuid, status text, resolved_at timestamp with time zone, updated_at timestamp with time zone, task_event_sequence bigint)
+language plpgsql
+security definer
+set search_path to 'agent_board', 'public'
+as $function$
+declare
+  v_escalation agent_board.escalations%rowtype;
+  v_event_sequence bigint;
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_resolved_by_agent_id, 'p_resolved_by_agent_id');
+
+  select *
+    into v_escalation
+    from agent_board.escalations e
+   where e.id = p_escalation_id
+     and e.status <> 'resolved';
+  if v_escalation.id is null then
+    raise exception 'escalation not found' using errcode = 'P0002';
+  end if;
+  if not agent_board._current_agent_can_access_thread(v_escalation.thread_id) then
+    raise exception 'escalation not accessible to current agent' using errcode = '42501';
+  end if;
+  -- OBSGATE-4 (#127): task-less escalation gated on the board posting rule (task-bound is gated
+  -- by the append below).
+  if v_escalation.task_id is null
+     and not agent_board._current_agent_can_post_to_thread(v_escalation.thread_id) then
+    raise exception 'thread posting requires a non-observer board role' using errcode = '42501';
+  end if;
+
+  update agent_board.escalations
+     set status = 'resolved',
+         resolved_by_agent_id = v_actor_agent_id,
+         resolved_at = now(),
+         details = details || coalesce(p_details, '{}'::jsonb),
+         updated_at = now()
+   where id = p_escalation_id
+   returning * into v_escalation;
+
+  if v_escalation.task_id is not null then
+    select event_sequence into v_event_sequence
+      from agent_board.append_task_event(v_escalation.task_id, v_actor_agent_id, 'status_changed', jsonb_build_object('kind', 'escalation_resolved', 'escalation_id', p_escalation_id));
+  end if;
+
+  return query
+  select v_escalation.id, v_escalation.status, v_escalation.resolved_at, v_escalation.updated_at, v_event_sequence;
+end;
+$function$;
+revoke all on function agent_board.resolve_escalation(uuid, uuid, jsonb) from public, anon;
+grant execute on function agent_board.resolve_escalation(uuid, uuid, jsonb) to authenticated, service_role;