@consiliency/agent-board-schema 1.28.0 → 1.38.0

package/migrations/20260914000100_agent_board_claim_subject_gate.sql

@@ -0,0 +1,500 @@
+-- Consiliency/message-board#291 — a claim is a LOCK, never a KEY. And the key it already
+-- handed out is never taken back, which is now a RULING rather than an accident.
+--
+-- Sibling of #287 (20260912000100), which closed the identical shape on read_receipts. The
+-- owner ruled on both halves of #291 on 2026-08-14; both the outcome and the REJECTED
+-- alternatives are recorded here, because the second half is a decision to LEAVE a surprising
+-- behaviour in place and a future reader must not be able to mistake it for an oversight.
+--
+-- ============================================================================
+-- HALF 1 — THE MEASURED DEFECT (closed here)
+-- ============================================================================
+-- `agent_board.claims` is an access KEY: `_agent_can_access_thread` accepts "there is a claims
+-- row for (thread, agent)" as one of the seven disjuncts that grant access to an
+-- `access_mode = 'inherit'` thread. `acquire_claim` is the ONLY route to such a row —
+-- service_role and authenticated hold SELECT and only SELECT on the table (no INSERT by any
+-- route incl. PUBLIC), and it is the only agent_board function that INSERTs into it, so this
+-- SECURITY DEFINER body is the whole surface.
+--
+-- The subject of the claim is `p_agent_id` and nothing gated it. The checks `acquire_claim`
+-- did apply — `_current_agent_can_access_task(p_task_id)` and
+-- `_current_agent_can_access_thread(v_thread_id)` — are evaluated for the SESSION, and
+-- `_is_service_role()` short-circuits both; `_resolved_actor_agent_id` then returns
+-- `p_agent_id` verbatim for a service_role caller. Measured on a live replay inside
+-- BEGIN … ROLLBACK: an agent B with no relationship to an inherit thread T went
+-- `_agent_can_access_thread(T,B) = false` -> service_role calls
+-- `acquire_claim(B, 'file', k, now()+1h, null, T)` -> `true`, without B calling anything.
+--
+-- IT MINTED TASK ACCESS TOO, which the receipt route did not. `_current_agent_can_access_task`
+-- accepts `_current_agent_can_access_thread(t.thread_id)` as a disjunct, so the same measured
+-- mint flipped `_current_agent_can_access_task(task-on-T)` from false to true for B in the
+-- same call. Closing the thread subject closes both; there is no separate task-key row to gate,
+-- because no function writes a task-access row at all.
+--
+-- Under `authenticated` there was never a gap, and this is the fact that decides the shape of
+-- the fix (see THE FIRST-ACCESS QUESTION). Measured, all three shapes, agent with no access:
+--     acquire_claim(B,'file',k,…, p_thread_id => T)        -> 42501 thread not accessible
+--     acquire_claim(B,'task',<task uuid>,…)                -> 42501 task not accessible
+--     acquire_claim(B,'file',k,…, p_task_id => <task>)     -> 42501 task not accessible
+-- The asymmetry was service_role-only.
+--
+-- ============================================================================
+-- THE FIRST-ACCESS QUESTION — asked before the fix was written, because a wrong answer here
+-- would have made the fix a CAPABILITY REMOVAL rather than a hole closure
+-- ============================================================================
+-- A read receipt is a memo: gating it on prior access is obviously safe, because reading
+-- presupposes access. A CLAIM need not be — if any legitimate flow uses `acquire_claim` to
+-- grant FIRST access (claiming a task from a pool is how a worker comes to be allowed to see
+-- it), then requiring prior access breaks the feature. Three legs, each checked rather than
+-- assumed:
+--
+--   1. BY CONSTRUCTION on the authenticated path. The session check already evaluates
+--      `_agent_can_access_thread(v_thread_id, current_agent_id())` — that is what
+--      `_current_agent_can_access_thread` reduces to for a non-service_role caller — and
+--      `_resolved_actor_agent_id` forces `v_actor_agent_id = current_agent_id()`. So the new
+--      gate re-evaluates an expression the function has just proved true. Confirmed by the
+--      three measurements above: claim-as-first-access does not exist for authenticated, and
+--      never did.
+--   2. NO IN-SCHEMA CALLER. A catalog scan of every `agent_board` function body for
+--      `acquire_claim\s*\(` returns ZERO. Enrollment, delegation and task dispatch do not mint
+--      claims on an agent's behalf; there is no server-side flow to break.
+--   3. NO THIRD-PARTY SHIPPED CALLER. client/CLI/MCP all default `p_agent_id` to the session's
+--      own acting agent (`USER_SCOPED_ACTOR_DEFAULTS` in packages/agent-board-client/src/
+--      client.ts), and a repo-wide search finds no service_role caller naming another agent.
+--
+-- The legitimate dispatch shape SURVIVES, and that is the point: a dispatcher that DELIVERS
+-- first — `delegate_task`, `send_direct_message` — gives the subject an `inbox_items` row,
+-- which is itself a disjunct, after which the claim passes the gate. Delivery grants access;
+-- the claim then records a lock on something already visible. `scripts/client-smoke/
+-- two-agent-claim.ts` is exactly this flow and is untouched: its second agent reaches the
+-- thread through the direct-message inbox item, so its conflicting acquire still answers 23505
+-- rather than 42501.
+--
+-- ============================================================================
+-- THE FIX — gate the SUBJECT, reusing #287's predicate rather than a second copy
+-- ============================================================================
+-- `_agent_can_access_thread(p_thread_id, p_agent_id)` already exists (20260912000100). It is
+-- subject-explicit and carries NO `_is_service_role()` short-circuit — that absence is what
+-- makes a subject gate real, and reintroducing the short-circuit there would make BOTH this
+-- gate and #287's vacuous while every allow-side test stayed green. It is not re-derived here;
+-- there is exactly one definition of the disjunct set and the two gates cannot drift from it.
+--
+-- UNCONDITIONAL IN *WHO*. The gate is not `if _is_service_role()` and not
+-- `if v_actor_agent_id is distinct from current_agent_id()`. A conditional gate is one
+-- `is distinct from` away from being skipped by a caller that presents both a service_role
+-- claim and a `sub`, and it would make this function's invariant depend on
+-- `_resolved_actor_agent_id` continuing to raise on a mismatch — borrowing a property instead
+-- of stating it. The redundancy on the authenticated path is the price of that.
+--
+-- CONDITIONAL ON *THREAD PRESENCE*, and that is not a loophole. `v_thread_id` is null for a
+-- claim bound to neither a task nor a thread — every `machine` / `repository` / `repo_file` /
+-- ownerless `file`|`tool`|`custom` claim in the fleet. Such a row stores `thread_id = null` and
+-- is therefore NOT a disjunct of anything: it mints no access, so there is nothing to gate.
+-- `_agent_can_access_thread(null, a)` is false, so gating unconditionally would refuse every
+-- fleet claim in existence. The gate covers exactly the claims that are keys.
+--
+-- GATE PLACEMENT is deliberate. An earlier draft of this header said it "preserves every
+-- existing error code". THAT WAS FALSE, and it is corrected below rather than softened -- see
+-- ONE ERROR CODE DOES CHANGE. The ladder is:
+--     22023 empty resource key -> P0002 task not found -> 42501 task not accessible (session)
+--     -> 42501 thread not accessible (session) -> [NEW] 42501 claim subject has no access
+--     -> OBSGATE-4 task-resource gates -> CLAIMGATE shadow/enforce -> ownerless TTL/quota
+--     -> sweep -> 23505 conflicting active claim -> insert
+-- After the task lookup, so a nonexistent task still answers P0002 rather than 42501.
+--
+-- ONE ERROR CODE DOES CHANGE, and it is a decision rather than a side effect. For a
+-- SERVICE_ROLE caller on a THREAD-BOUND claim, everything this gate now refuses used to run all
+-- the way to the INSERT and surface as a foreign-key violation. Measured by restoring the
+-- pre-fix definition (20260825000100) inside a rolled-back transaction and calling both:
+--
+--                                                    PRE-fix                  POST-fix
+--   nonexistent p_thread_id, valid subject   23503 claims_thread_id_fkey  ->  42501
+--   nonexistent subject, valid thread        23503 claims_agent_id_fkey   ->  42501
+--   nonexistent subject, THREAD-LESS claim   23503 claims_agent_id_fkey   ->  23503 (unchanged)
+--
+-- ONE rule, two observable instances: the gate raises 42501 whenever the named subject fails
+-- the predicate for the bound thread, and a nonexistent thread and a nonexistent agent both
+-- make that predicate false. The third row is the control that the change is confined to
+-- thread-BOUND claims. `authenticated` is unaffected: its session check already answered 42501
+-- for a nonexistent thread.
+--
+-- 23503 IS NOT RESTORED, DELIBERATELY. Restoring it would mean probing thread existence BEFORE
+-- the access gate, which tells a caller with no access whether a thread id exists. 42501 gives
+-- the same answer to "no such thread" and "not your thread", which is the right answer for a
+-- caller entitled to neither. All three rows are pinned (test assertions 61-63): 61/62 by the
+-- gate-deletion mutation, 63 by the make-the-gate-unconditional mutation.
+--
+-- AND BEFORE THE SWEEP -- but NOT for the reason an earlier draft of this header gave. That
+-- draft said "the sweep expires stale rows, so a refused caller must not reach it or the denial
+-- leaks observable state". THAT IS FALSE, and its own mutation is what caught it: moving the
+-- gate BELOW the sweep produced ran=60, notok=0 on the test file. `raise exception` unwinds the
+-- whole function call, so every write made before the raise is rolled back wherever the check
+-- sits. "A refused caller observes no state change" is therefore TRUE BY STATEMENT ATOMICITY
+-- and is not a consequence of placement -- and because it is true either way, no test can pin
+-- the placement through it. The gate is placed before the sweep because that matches the
+-- convention CLAIMGATE/ENFORCE states two blocks below in this same function, not because a
+-- test defends it. The distinction is recorded rather than quietly dropped, because a claim
+-- that cites a reason no assertion supports is exactly what CLAUDE.md rule 2 exists to catch.
+--
+-- ============================================================================
+-- HALF 2 — WHAT IS DELIBERATELY NOT CHANGED: the claim grandfather, RATIFIED
+-- ============================================================================
+-- The claims disjunct filters on `(thread_id, agent_id)` and NOTHING ELSE — no `status`, no
+-- `lease_expires_at`. `release_claim` sets `status='released'` rather than deleting the row, so
+-- A RELEASED OR LONG-EXPIRED CLAIM STILL GRANTS THREAD ACCESS, INDEFINITELY. Measured: after
+-- `release_claim`, `_agent_can_access_thread(T,B)` is still true; deleting the row is what
+-- flips it to false, and nothing deletes it.
+--
+-- THIS IS INTENDED. The owner ratified it on #291 (2026-08-14) as the #287 grandfather
+-- principle extended: the agent legitimately held the thread, so it keeps what it saw. The
+-- disjunct is deliberately NOT filtered on `status` or `lease_expires_at`, and a future
+-- migration that adds such a filter is REVERSING A RULING, not fixing a bug.
+--
+-- Two alternatives were considered and EXPLICITLY REJECTED; they are recorded because "why not
+-- the obvious fix" is the question a future reader will actually have:
+--
+--   (a) ACCESS ENDS WITH THE CLAIM — filter the disjunct on `status='active'` and an unexpired
+--       lease. REJECTED: it reverses the #287 ruling for this one case, and it would remove
+--       access from every principal holding a released or expired claim AT DEPLOY TIME, with
+--       no notice and no way to tell which of them still needed it.
+--   (b) KEEP THE ACCESS BUT RE-MECHANISE IT — record the access separately when the claim is
+--       taken, so a stale claim ROW is not itself the key. ACKNOWLEDGED AS THE MORE HONEST
+--       DESIGN and rejected for now on cost, and because agents holding historical released
+--       claims would need backfilling or would silently lose access.
+--
+-- PERMANENCE IS BY CONSTRUCTION, not by policy, and the test asserts it rather than describing
+-- it: no role holds DELETE or TRUNCATE on `agent_board.claims` by any route (the ACL is
+-- SELECT-only outside the owner), and NO agent_board function deletes or truncates a claims
+-- row. There is no reaper. The three non-minting writers — `release_claim`, `renew_claim`,
+-- `reclaim_fleet_machine` — update `status` / `lease_expires_at` / `resource_key` / `metadata`
+-- and never `agent_id` or `thread_id`, so none of them can re-key an existing row onto a
+-- different subject or thread. Each is asserted POSITIVELY in the test, by call, rather than by
+-- absence of a regex match.
+--
+-- THE GATE AND THE GRANDFATHER ARE COMPLEMENTARY, NOT IN TENSION. The gate decides WHO MAY BE
+-- NAMED in a claim; the grandfather decides WHAT A CLAIM MEANS afterwards. Gating the subject
+-- is what makes the grandfather safe to keep: a key can no longer be conjured for an agent that
+-- never had access, so "permanent" now only ever describes access that was really held.
+--
+-- ============================================================================
+-- WHY THIS DISJUNCTION IS THE WHOLE ACCESS STORY — `access_mode='restricted'` is unreachable
+-- ============================================================================
+-- Carried forward from #291 and RE-VERIFIED on a live replay of this bundle rather than
+-- repeated. `agent_board.threads.access_mode` defaults to `'inherit'` and:
+--   * NO agent_board function so much as mentions `access_mode` except `_agent_can_access_thread`
+--     itself, which READS it (catalog scan over stripped function source against a full replay
+--     of the bundle INCLUDING this migration, and re-asserted on every suite run by
+--     agent_board_claim_subject_gate.test.sql — subject to the prosqlbody blind spot filed as
+--     message-board#293);
+--   * `aclexplode(pg_class.relacl)` on `agent_board.threads` gives `authenticated` and
+--     `service_role` SELECT and nothing else; only the `postgres` owner can write it.
+-- So no shipped path can ever set a thread to `'restricted'`, the `thread_memberships` branch
+-- of the predicate is dead, and the seven-way `inherit` OR governs EVERY thread in production.
+-- That is why this gate matters more than its blast radius suggests: it is not one branch of an
+-- access model, it is the access model.
+--
+-- One nuance, stated rather than acted on: `service_role` DOES hold INSERT and UPDATE on
+-- `agent_board.thread_memberships` (unlike every other table in this story), and no function
+-- writes that table. The branch is dead anyway because `access_mode` itself is unwritable, so
+-- those grants confer nothing today. They are input to the owner's open question about whether
+-- the dormant per-thread ACL deserves a filing of its own; this migration does not touch them.
+--
+-- ============================================================================
+-- MECHANICS
+-- ============================================================================
+-- `create or replace` with UNCHANGED signatures throughout. `drop function` would discard the
+-- ACL **and** the COMMENT, and recreating a SECURITY DEFINER function grants EXECUTE to PUBLIC
+-- by default. `acquire_claim` is reproduced VERBATIM from 20260825000100 (CLAIMGATE/ENFORCE)
+-- except the single gate block; the applied result was diffed against the prior definition to
+-- confirm the gate is the only delta. `acquire_claim` had NO comment before this migration —
+-- the one added below is new, not a rewrite of an earlier record.
+--
+-- Definition-only: every apply-time statement is `create or replace function`, `revoke`,
+-- `grant` or `comment on`. The DML in this file is `acquire_claim`'s own body, inside
+-- `$function$ … $function$`, executed on call and never at apply time. `schema_version` stays 8.
+
+-- 1. acquire_claim: gate the NAMED subject ---------------------------------
+--    Reproduced VERBATIM from 20260825000100 (CLAIMGATE/ENFORCE) EXCEPT the single #291 gate
+--    block, inserted after the SESSION thread check and BEFORE the sweep.
+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;
+  v_shadow_authorized boolean;
+  v_ownerless boolean;
+  v_active_ownerless int;
+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
+    -- 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).
+    perform pg_advisory_xact_lock(hashtext('agent_board.claimgate_ownerless_quota'), hashtext(v_actor_agent_id::text));
+    select count(*) into v_active_ownerless
+      from agent_board.claims c
+     where c.agent_id = v_actor_agent_id
+       and c.resource_kind in ('file', 'tool', 'custom')
+       and c.status = 'active'
+       and c.released_at is null
+       and c.lease_expires_at > now();
+    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;
+
+  -- 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(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;
+
+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).';
+
+comment on function agent_board._current_agent_can_access_thread(uuid) is
+  'Thread access for the CURRENT session: service_role short-circuits true, otherwise '
+  '_agent_can_access_thread(p_thread_id, current_agent_id()). The disjunct set lives in that '
+  'helper and is not restated here. '
+  'ACCESS ONCE HELD IS NEVER WITHDRAWN, AND THAT IS DELIBERATE (message-board#287, extended and '
+  'RATIFIED for claims on message-board#291). The read_receipts, claims and inbox_items '
+  'disjuncts are all PERMANENT: no role holds DELETE or TRUNCATE on any of those tables and no '
+  'function body removes a row from them, so LEAVING A BOARD, LOSING A TASK ASSIGNMENT, OR '
+  'RELEASING A CLAIM DOES NOT REVOKE ACCESS TO A THREAD THE AGENT ALREADY HELD. The rule is '
+  '"you keep what you saw". For claims this is sharper than it looks and was ruled on '
+  'explicitly: the claims disjunct filters on (thread_id, agent_id) and NOT on status or '
+  'lease_expires_at, so a RELEASED or LONG-EXPIRED claim still grants access indefinitely. '
+  'Two alternatives were considered and REJECTED on #291: (a) filtering the disjunct on an '
+  'active, unexpired lease -- rejected because it reverses the #287 ruling for this one case '
+  'and would strip access at deploy time from every holder of a released or expired claim; '
+  '(b) recording the access separately when the claim is taken, so a stale row is not itself '
+  'the key -- acknowledged as the more honest design, rejected for now on cost and because '
+  'agents holding historical released claims would need backfilling or would silently lose '
+  'access. A future migration that adds a status or lease filter here is REVERSING A RULING, '
+  'not fixing a bug. What IS closed is the mint: mark_read (#287) and acquire_claim (#291) both '
+  'gate the NAMED subject through _agent_can_access_thread, so a receipt or a claim can only '
+  'ever record access already held. '
+  'access_mode = ''restricted'' is UNREACHABLE through the shipped API -- no function writes '
+  'threads.access_mode (it defaults to ''inherit'') and authenticated/service_role hold SELECT '
+  'and only SELECT on agent_board.threads -- so the inherit disjunction governs every thread in '
+  'production and the per-thread ACL added in #27 is dormant.';