@consiliency/agent-board-schema 1.48.0 → 1.51.0

package/migrations/20260930000100_agent_board_claim_policy_race.sql

@@ -0,0 +1,922 @@
+-- #405 — the stale-policy race family. `_claimgate_board_claim_policy` took NO lock on `boards`,
+-- so any operation whose snapshot predates a committed policy change acted on policy that was
+-- already gone.
+--
+-- WHAT #406 LEFT OPEN, IN ITS OWN WORDS. That migration's header records limitation 3: "an
+-- in-flight renew can still win the race, and this is unpinned ... closing it means taking a
+-- `boards` lock on the renew path, which is a LOCK-ORDER decision and belongs with the two-session
+-- isolationtester harness, not with this change." This is that change. The wording is corrected at
+-- the bottom of this file rather than left to be disbelieved (rule 5).
+--
+-- THREE ENTRY POINTS, AND THE THIRD IS THE ONE A LIST WOULD MISS:
+--
+--   1. `renew_claim` — a renew whose snapshot predates the revert resolves 'advisory', skips both
+--      the #373 cap and the #388 convergence clamp, and writes a full horizon AFTER the revert's
+--      row lock is released at commit. The attacker owns both sessions, so the interleave is
+--      deliberate, not lucky.
+--   2. `acquire_claim` — the SAME read, and worse: there is no claim row yet, so #406's cap reset
+--      has nothing to clamp. A stale 'advisory' read here banks a full-horizon lease that the
+--      revert cannot reach even in principle.
+--   3. `set_board_claim_policy` itself — two concurrent flips serialised on the boards ROW, which
+--      is what makes the outgoing-policy read correct, but a READER took no lock at all and so
+--      serialised against neither.
+--
+-- ===========================================================================
+-- THE MECHANISM: A BOARD-SCOPED ADVISORY XACT LOCK, TAKEN BEFORE THE POLICY DECISION, WITH THE
+-- POLICY READ AFTER IT AS A SEPARATE STATEMENT.
+-- ===========================================================================
+--
+-- WHERE "BEFORE THE POLICY DECISION" IS LOAD-BEARING, and where the first draft of this fix was
+-- wrong. It said "before the agent-scoped lock". In `acquire_claim` that agent lock lives INSIDE
+-- the branch a stale 'advisory' read SKIPS — so on the dangerous path it is never reached and
+-- ordering against it means nothing. The board opt-out was a CONJUNCT of the `if`; it is hoisted
+-- out, and the lock now precedes the decision on every path through the guarded region, including
+-- the one that observes 'advisory' and does nothing else.
+--
+-- WHY A SEPARATE STATEMENT. Under READ COMMITTED each statement takes a fresh snapshot, so a
+-- policy read issued AFTER the lock was granted observes the writer's committed value. Fused into
+-- one statement it would not: that statement's snapshot is taken before the lock is granted.
+--
+-- ===========================================================================
+-- ISOLATION LEVEL: DETECTED AND REFUSED, NOT ASSUMED.
+-- ===========================================================================
+--
+-- Under REPEATABLE READ and SERIALIZABLE the transaction's snapshot is fixed at first use. Waiting
+-- on the writer's lock does NOT advance it, so the re-read returns the SAME stale policy and the
+-- advisory lock does not fail closed — it fails silently, which is worse than not being there.
+-- `_claimgate_lock_board_policy` therefore RAISES (0A000) when
+-- `current_setting('transaction_isolation')` is anything but `read committed`.
+--
+-- 'read uncommitted' is refused too, even though PostgreSQL implements it AS read committed. A
+-- fail-closed guard with one accepted spelling stays honest; one carrying an equivalence argument
+-- has to be re-argued every time someone reads it, and the refusal costs a caller nothing it
+-- cannot fix with one `set transaction isolation level`.
+--
+-- NOTHING IN THIS TREE RUNS AT ANOTHER LEVEL — measured, not assumed: a repo-wide search for
+-- `repeatable read` / `serializable` / `isolation level` / `default_transaction_isolation` finds
+-- only two PROSE mentions (a plan and 20260901000110's header, both recording SERIALIZABLE as an
+-- out-of-scope posture change) and no code that sets one. So the refusal breaks no caller that
+-- exists. The refusal is pinned BEHAVIOURALLY by claimpolicy_isolation_refusal.spec, which now
+-- enumerates repeatable read, serializable AND read uncommitted, and STRUCTURALLY by CPR-25a,
+-- which asserts this guard is an inequality against the one ACCEPTED level rather than an
+-- equality against one refused level. (It used to cite CPR-13, which is the threads.board_id
+-- table-privilege assertion and has nothing to do with isolation.)
+--
+-- ===========================================================================
+-- THE SOLE-WRITER PROOF, RE-DERIVED AND DELIBERATELY WIDER THAN #406's.
+-- ===========================================================================
+--
+-- An advisory lock only excludes callers that also take it. So "this RPC is the only writer of
+-- boards.claim_policy" is not a nicety here, it is what makes the lock a lock. #406 proved it with
+-- `has_table_privilege(..., 'UPDATE') = false` plus zero user triggers, which does not exclude
+-- COLUMN-level UPDATE grants, rules, other SECURITY DEFINER routines, or dynamic SQL. Each of
+-- those was checked against the catalog and each is asserted positively (CPR-4..CPR-8):
+--
+--   * column-level UPDATE grants on `agent_board.boards` — the only grantee in
+--     `information_schema.column_privileges` is the table OWNER (postgres). No non-owner grantee
+--     holds UPDATE on any column, `claim_policy` included.
+--   * rules — `pg_rewrite` carries nothing on `boards` but the views' own `_RETURN` SELECT rules;
+--     there is no `ON UPDATE ... DO INSTEAD` path.
+--   * other definer routines — the catalog scan for `set claim_policy` over COMMENT-STRIPPED
+--     bodies returns exactly `set_board_claim_policy`. Stripped, because an unstripped scan of the
+--     same catalog on this schema returns THREE names: `set_board_claim_policy`'s own prose
+--     mentions `_claimgate_board_claim_policy`, and a scan that counts a comment as code is the
+--     failure mode this repo has already shipped once.
+--   * dynamic SQL — exactly two functions in `agent_board` contain an `execute`:
+--     `get_bundle_compatibility` (which writes nothing at all) and `mark_retention_metadata`
+--     (whose table allowlist is a literal that does not contain `boards`, and which only ever
+--     assigns `metadata`/`payload`). Both asserted, not described.
+--
+-- ===========================================================================
+-- THE OTHER PREMISE THE LOCK RESTS ON: WHICH BOARD.
+-- ===========================================================================
+--
+-- Both write paths derive the board from the claim's thread, so `threads.board_id` had better not
+-- move under them. It does not, and the reason is mechanical rather than incidental: the only
+-- writer is `_upsert_delivery_recipient`, whose UPDATE carries `where t.board_id is null`
+-- (OBSGATE's first-board-wins stamp). So the transition is null -> board and never board -> board.
+--
+-- That leaves exactly one drift: a claim whose thread had NO board when we looked can gain one
+-- while we wait. We hold no lock on that board, so we must not consult it — and we do not: the
+-- policy is resolved from the BOARD ID WE LOCKED, not by re-resolving through the thread. A stamp
+-- arriving mid-wait therefore resolves to 'inherit', the ENFORCING answer, so the only reachable
+-- drift is conservative. CPR-10/CPR-11 assert the writer set and the null-guard.
+--
+-- ===========================================================================
+-- LOCK ORDER — MEASURED, NOT ARGUED (PR #397's standard).
+-- ===========================================================================
+--
+--   (a) WRITER-SIDE CYCLE. `set_board_claim_policy` takes the advisory lock and then wants a
+--       `boards` row lock, while a transaction that inserted a thread on that board holds FOR KEY
+--       SHARE on the same row and then wants the advisory lock. That is a cycle IF the writer's
+--       row lock conflicts with KEY SHARE. It does not: the read is `for no key update`, chosen in
+--       #400 for precisely this reason. `claimpolicy_writer_keyshare.spec` measures BOTH
+--       directions — the shipped `for no key update` completes, and the same permutation with
+--       `for update` injected deadlocks with 40P01. The probe discriminates.
+--
+--   (b) CLAIM-ROW -> BOARD-LOCK INVERSION. Every path here takes the board lock BEFORE it touches
+--       a claims row (acquire's sweep, renew's UPDATE, the #400 cap reset are all after it), and
+--       renew's preliminary read is a plain SELECT that takes no row lock at all. The inverse
+--       holder — a session sitting on a claims row lock and then entering a policy path — is
+--       UNREACHABLE, and by privilege rather than by convention: `select ... for update` and
+--       `for key share` on `agent_board.claims` are refused to `authenticated` and `service_role`
+--       (neither holds UPDATE on the table, at table OR column level), and no function in the
+--       schema takes a claims row lock. CPR-12 asserts the privilege bound; the catalog scan for
+--       `from agent_board.claims ... for update` returns nothing.
+--
+--   (c) BOARD-THEN-AGENT. `acquire_claim` takes two advisory locks. The board lock is first on
+--       every path; the actor-scoped quota lock is only ever taken inside the non-advisory branch,
+--       after it. No function takes them in the other order (there is only one function that takes
+--       the agent lock at all), so there is no cycle to close.
+--
+-- ===========================================================================
+-- COMPLETENESS — FROM THE CATALOG (rule 1).
+-- ===========================================================================
+--
+-- The class is "resolvers of a board's claim policy": callers of
+-- `_claimgate_board_claim_policy` in `pg_proc` and `pg_get_viewdef`, UNION direct readers of the
+-- `claim_policy` column. On this tree that is exactly four, and the fourth is the one a
+-- hand-written list of "three entry points" missed:
+--
+--   acquire_claim            SERIALISE  (this migration)
+--   renew_claim              SERIALISE  (this migration)
+--   set_board_claim_policy   SERIALISE  (this migration; also the writer)
+--   v_ownerless_claim_quota  EXEMPT     — and asserted POSITIVELY, never as an absence: it is a
+--                            SELECT-only view (its only rewrite rule is `_RETURN`, ev_type 1), so
+--                            a stale policy read there produces a report LINE and can never
+--                            produce a lease. That the census resolves policy at query time is
+--                            #393's own documented behaviour (OQ-29), not a hole opened here.
+--
+-- CPR-1/2/3 derive that set from the catalog on every run, so a fifth resolver fails them and
+-- NAMES ITSELF instead of inheriting an exemption nobody decided.
+
+-- ---------------------------------------------------------------------------
+-- The board of a thread, once. Both write paths need the board ID (to lock it) and the policy (to
+-- decide), and `_claimgate_board_claim_policy` already resolved the same join internally — so it
+-- is decomposed rather than copied. `_claimgate_board_claim_policy(thread)` is re-created below as
+-- the composition of these two, which keeps ONE definition of the resolution and leaves its
+-- contract byte-identical (BCP-5's null/unknown/board-less cases all still answer 'inherit').
+--
+-- service_role only, and no grant to `authenticated`: this reads `agent_board.threads` under
+-- SECURITY DEFINER, so a grant would tell any authenticated caller which board any thread belongs
+-- to, past RLS. The two definer callers need no grant (a definer executes as its owner), and
+-- `_claimgate_board_claim_policy` — which KEEPS its `authenticated` grant because the census view
+-- resolves through it — reaches these as postgres for the same reason.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._claimgate_board_of_thread(p_thread_id uuid)
+returns uuid
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select t.board_id from agent_board.threads t where t.id = p_thread_id;
+$$;
+
+revoke all on function agent_board._claimgate_board_of_thread(uuid) from public, anon, authenticated;
+grant execute on function agent_board._claimgate_board_of_thread(uuid) to service_role;
+
+comment on function agent_board._claimgate_board_of_thread(uuid) is
+  '#405: THE single definition of "which board governs this claim" — the thread''s board_id, or '
+  'null for a null/unknown/board-less thread. Split out of _claimgate_board_claim_policy so the '
+  'enforcement paths can LOCK the board they are about to resolve policy from, and resolve that '
+  'policy from the id they locked rather than by re-walking the thread (a null board_id can be '
+  'stamped by _upsert_delivery_recipient mid-wait; re-walking would consult a board whose lock is '
+  'not held). service_role only, and deliberately narrower than _claimgate_board_claim_policy: it '
+  'reads threads under SECURITY DEFINER, so an authenticated grant would expose board membership '
+  'of any thread past RLS.';
+
+-- ---------------------------------------------------------------------------
+-- The policy of a board, once. Same coalesce-to-'inherit' fallback the thread-keyed resolver has
+-- always had, now stated where the board id is already known.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._claimgate_board_claim_policy_of(p_board_id uuid)
+returns text
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select coalesce(
+    (select b.claim_policy from agent_board.boards b where b.id = p_board_id),
+    'inherit');
+$$;
+
+revoke all on function agent_board._claimgate_board_claim_policy_of(uuid) from public, anon, authenticated;
+grant execute on function agent_board._claimgate_board_claim_policy_of(uuid) to service_role;
+
+comment on function agent_board._claimgate_board_claim_policy_of(uuid) is
+  '#405: a board''s claim policy, keyed by BOARD id. Returns ''inherit'' for a null or unknown '
+  'board — so an absent board cannot opt anything out by omission, the same rule '
+  '_claimgate_board_claim_policy has always had for an absent thread. Called by acquire_claim and '
+  'renew_claim AFTER _claimgate_lock_board_policy on the same id, as its own statement, so under '
+  'READ COMMITTED it observes a policy change that committed while the lock was being waited for. '
+  'service_role only; the definer callers execute as the owner and need no grant.';
+
+-- ---------------------------------------------------------------------------
+-- The lock, and the isolation-level refusal that makes it mean anything.
+--
+-- NOT SECURITY DEFINER: it reads nothing and writes nothing. It is nonetheless revoked from
+-- public/anon/authenticated and granted only to service_role, so the serialisation cannot be
+-- reached — or spoofed on a different key — from a session; the three definer callers execute as
+-- the owner. CPR-22 asserts that ACL -- not CPR-14, which is the claims row-lock class
+-- assertion. NOTE: the grant below is REMOVED by 20261001000100. It was not sufficient for the
+-- claim this paragraph makes: service_role is itself a session role, so `granted only to
+-- service_role` did not mean `unreachable from a session`, and a service_role transaction could
+-- compose renew_claim's claims row lock with a direct call here into a real deadlock.
+--
+-- A NULL BOARD TAKES NO LOCK, because there is no board row to serialise on and nothing whose
+-- policy could go stale (an absent board resolves 'inherit' constitutively). The ISOLATION CHECK
+-- still runs — it is not carved out for the null case. A carve-out there would be one more branch
+-- that has to stay correct, and the uniform rule ("every guarded ownerless decision and every
+-- policy flip refuses a non-READ-COMMITTED transaction") is the one that can be asserted whole.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._claimgate_lock_board_policy(p_board_id uuid)
+returns void
+language plpgsql
+set search_path = ''
+as $$
+declare
+  v_isolation text := current_setting('transaction_isolation');
+begin
+  -- READ COMMITTED IS A PRECONDITION, NOT A PREFERENCE. This lock exists so that the policy read
+  -- issued after it sees the writer's COMMITTED value; that only happens where each statement
+  -- takes a fresh snapshot. Under repeatable read / serializable the snapshot is fixed at first
+  -- use, the wait does not advance it, and the caller would read the stale policy anyway — a guard
+  -- that is silently wrong under a setting any caller can choose. Refuse instead.
+  if v_isolation <> 'read committed' then
+    raise exception
+      'claim policy enforcement requires transaction isolation level read committed (got %)',
+      v_isolation
+      using errcode = '0A000',
+            hint = 'The board policy lock only closes the stale-read race under READ COMMITTED, '
+                   'where each statement takes a fresh snapshot. Retry this call in a READ '
+                   'COMMITTED transaction.';
+  end if;
+
+  if p_board_id is not null then
+    perform pg_catalog.pg_advisory_xact_lock(
+      pg_catalog.hashtextextended('agent_board.board_claim_policy:' || p_board_id::text, 0));
+  end if;
+end;
+$$;
+
+revoke all on function agent_board._claimgate_lock_board_policy(uuid) from public, anon, authenticated;
+grant execute on function agent_board._claimgate_lock_board_policy(uuid) to service_role;
+
+comment on function agent_board._claimgate_lock_board_policy(uuid) is
+  '#405: the board-scoped serialisation point for claim policy. Takes a pg_advisory_xact_lock on '
+  'hashtextextended(''agent_board.board_claim_policy:''||board_id) so set_board_claim_policy''s '
+  'flip and every ownerless enforcement decision on that board are totally ordered, and RAISES '
+  '0A000 unless transaction_isolation is ''read committed'' — under repeatable read or '
+  'serializable the wait does not advance the caller''s snapshot, so the lock would be silently '
+  'inert rather than fail closed. A null board takes no lock (nothing to serialise; an absent '
+  'board resolves ''inherit''), but is still isolation-checked. Advisory rather than a second '
+  'boards row lock because #159 is open on lock ordering; that only excludes callers that also '
+  'take it, which is why this migration re-derives the sole-writer proof for boards.claim_policy '
+  '(CPR-4..CPR-8). Board-then-agent is the order in acquire_claim; nothing takes them the other '
+  'way. service_role only — the three definer callers execute as the owner.';
+
+-- ---------------------------------------------------------------------------
+-- The thread-keyed resolver, re-created as the composition of the two helpers above. Same
+-- contract, one definition of the walk. `create or replace` with an unchanged signature, so the
+-- ACL (authenticated + service_role, for the census view) and the COMMENT survive.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._claimgate_board_claim_policy(p_thread_id uuid)
+returns text
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select agent_board._claimgate_board_claim_policy_of(
+           agent_board._claimgate_board_of_thread(p_thread_id));
+$$;
+
+-- ---------------------------------------------------------------------------
+-- acquire_claim, re-created from the 20260928000100 pg_get_functiondef dump. The board opt-out is
+-- hoisted out of the `if` condition into a lock / read / decide sequence; nothing else moves, and
+-- the previously-nested statements are re-indented one level.
+-- ---------------------------------------------------------------------------
+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 (_upsert_delivery_recipient 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;
+
+  -- 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$;
+
+-- ---------------------------------------------------------------------------
+-- renew_claim, re-created from the 20260928000100 dump. The two ownerless blocks become one
+-- guarded region: lock, revalidate the CLAIM (not merely the policy), resolve the policy from the
+-- locked board, then the same cap and convergence decisions in the same order.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION agent_board.renew_claim(p_lease_token uuid, p_lease_expires_at timestamp with time zone)
+ 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_actor_agent_id uuid;
+  v_kind text;
+  v_key text;
+  v_thread_id uuid;
+  v_claim_agent_id uuid;
+  v_current_expires timestamptz;
+  v_effective_expires timestamptz;
+  v_board_id uuid;
+  v_board_policy text;
+begin
+  if not agent_board._is_service_role() then
+    v_actor_agent_id := agent_board._resolved_actor_agent_id(null, 'current_agent_id');
+    if not exists (
+      select 1
+        from agent_board.claims c
+       where c.lease_token = p_lease_token
+         and c.agent_id = v_actor_agent_id
+    ) then
+      raise exception 'claim not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+
+  -- CLAIMGATE/ENFORCE (#133): re-authorize + horizon for the predicate-gated kinds. Read the
+  -- live lease's resource identity (SECURITY DEFINER, so RLS does not hide it). A dead/expired
+  -- lease yields a null kind and the UPDATE below matches nothing (preserves prior behavior).
+  --
+  -- #388 adds the HOLDER and the CURRENT EXPIRY to this same read. Both come from the live row and
+  -- never from a caller argument: a caller-supplied agent id is an assertion about who holds the
+  -- claim, and a caller-supplied expiry would let the convergence clamp be handed its own baseline.
+  select c.resource_kind, c.resource_key, c.thread_id, c.agent_id, c.lease_expires_at
+    into v_kind, v_key, v_thread_id, v_claim_agent_id, v_current_expires
+    from agent_board.claims c
+   where c.lease_token = p_lease_token
+     and c.status = 'active'
+     and c.released_at is null
+     and c.lease_expires_at > now();
+
+  -- RE-AUTH: bound revocation latency to one lease term. Uses the SAME session wrapper acquire
+  -- consults (_can_claim_resource -> _can_claim_resource_for(current_agent_id())), so service_role
+  -- keeps its carve-out and acquire+renew share ONE per-kind flag (a mutation splitting the flags
+  -- fails a test). Task-renew is EXCLUDED (ownership-only, ratified supersession).
+  if v_kind in ('machine', 'repository', 'repo_file')
+     and agent_board._claimgate_kind_enforced(v_kind) then
+    if not agent_board._can_claim_resource(v_kind, agent_board._canonical_claim_key(v_kind, v_key)) then
+      raise exception 'not authorized to renew this % claim (fleet authority revoked)', v_kind
+        using errcode = '42501';
+    end if;
+  end if;
+
+  -- HORIZON: clamp the renewed lease to now()+horizon for an ENFORCED fleet-gated kind — this is
+  -- where an existing overlong lease reconciles (no bulk-clamp migration; the horizon clamps it
+  -- at its next renew). service_role exempt. Same per-kind flag as acquire.
+  v_effective_expires := p_lease_expires_at;
+  if v_kind in ('machine', 'repository', 'repo_file')
+     and not agent_board._is_service_role()
+     and agent_board._claimgate_kind_enforced(v_kind)
+     and p_lease_expires_at > now() + agent_board._claimgate_max_lease_horizon() then
+    v_effective_expires := now() + agent_board._claimgate_max_lease_horizon();
+  end if;
+
+  -- #405 THE BOARD LOCK AND THE REVALIDATION, BEFORE EITHER OWNERLESS DECISION.
+  --
+  -- ORDER, AND WHY IT IS THIS ONE. The board id is derived FROM the claim (token -> claim ->
+  -- thread -> board), so "lock the board before any claims access" is not achievable here. The
+  -- achievable order is: read the claim, derive the board, LOCK the board, RE-READ, decide.
+  --
+  -- RE-READING THE POLICY ALONE WOULD MOVE THE RACE, NOT CLOSE IT. The writer this waits on is
+  -- set_board_claim_policy, and since #400 that same call CLAMPS this board's ownerless leases on
+  -- an advisory -> inherit revert. So the row this function read BEFORE the wait is exactly the row
+  -- the writer changed DURING it, and v_current_expires -- the baseline the convergence clamp
+  -- least()s against -- would still hold the pre-clamp horizon and hand it straight back. The whole
+  -- claim read is re-issued, not just the policy.
+  --
+  -- A CLAIM THAT DIED DURING THE WAIT (released, expired, swept) re-reads as null and every guard
+  -- below is skipped, exactly as a dead lease behaves today; the UPDATE at the end then matches
+  -- nothing and the caller gets the empty result it already gets for a dead token.
+  --
+  -- ONE GUARDED REGION, not two copies of the same three conjuncts. The TTL cap and the
+  -- convergence clamp previously each re-evaluated `kind / not service_role / guards_enabled`
+  -- inline; hoisting them makes the lock a STRUCTURAL precondition of both decisions rather than a
+  -- line that has to be remembered twice.
+  if v_kind in ('file', 'tool', 'custom')
+     and not agent_board._is_service_role()
+     and agent_board._claimgate_ownerless_guards_enabled() then
+    v_board_id := agent_board._claimgate_board_of_thread(v_thread_id);
+    perform agent_board._claimgate_lock_board_policy(v_board_id);
+
+    -- REVALIDATION. Its own statement, so under READ COMMITTED it takes a snapshot taken AFTER the
+    -- lock was granted. Same projection and same predicate as the read above -- deliberately, so
+    -- there is one definition of "the live claim" and not a second, narrower one here.
+    select c.resource_kind, c.resource_key, c.thread_id, c.agent_id, c.lease_expires_at
+      into v_kind, v_key, v_thread_id, v_claim_agent_id, v_current_expires
+      from agent_board.claims c
+     where c.lease_token = p_lease_token
+       and c.status = 'active'
+       and c.released_at is null
+       and c.lease_expires_at > now();
+
+    -- Resolved from the board we LOCKED, not from the thread again -- see acquire_claim's note:
+    -- threads.board_id is first-board-wins, so a board never moves, but a null one can be stamped
+    -- mid-wait and re-resolving would consult a board whose lock we do not hold.
+    v_board_policy := agent_board._claimgate_board_claim_policy_of(v_board_id);
+
+    if v_kind in ('file', 'tool', 'custom')
+       and v_board_policy <> 'advisory' then
+      -- #373 OWNERLESS TTL CAP AT RENEW. The half that was missing: without this an agent renews a
+      -- file/tool/custom lease past the 30-day cap indefinitely and the bound is decorative.
+      --
+      -- Clamps rather than raises, unlike acquire. A raise here would kill a lease the agent is
+      -- actively holding; shortening it costs one more renew. Same resolution the fleet-kind
+      -- horizon clamp above already applies, and the same place an over-long legacy lease
+      -- reconciles.
+      --
+      -- The carve-outs are acquire's, so ONE operator flag governs both paths and a board that
+      -- declined our locking (claim_policy='advisory') is not clamped by it either. The thread
+      -- comes from the LIVE CLAIM, never from a caller argument -- a caller-supplied thread would
+      -- let an agent choose which board's policy is consulted.
+      if v_effective_expires > now() + agent_board._claimgate_ownerless_ttl_cap() then
+        v_effective_expires := now() + agent_board._claimgate_ownerless_ttl_cap();
+      end if;
+
+      -- #388 OWNERLESS QUOTA CONVERGENCE AT RENEW. The cap above bounds how LONG a lease may be;
+      -- this bounds how long an agent may stay OVER THE CEILING, which nothing did before. While
+      -- the holder is over quota a renew may not POSTPONE a deadline: it still succeeds, the lease
+      -- it already holds is preserved to the microsecond, and the only thing withheld is more time.
+      -- Each claim then lapses at its own already-set expiry, the count falls monotonically, and
+      -- this block stops firing the instant the count is back at the ceiling.
+      --
+      -- least(), not an assignment. An over-quota agent asking for a SHORTER lease must still get
+      -- the shorter one -- that is the agent converging voluntarily, and refusing it would be
+      -- perverse. v_current_expires is the REVALIDATED baseline (#405): before this migration it
+      -- was read before the policy was resolved and could not see a concurrent #400 clamp at all.
+      --
+      -- `>` and not `>=`. `>=` is ACQUIRE's refusal predicate; reusing it here would freeze an
+      -- agent sitting legitimately AT the ceiling and walk it down to 49. The predicate is the
+      -- census's own `overage > 0`, so the fixed point is exactly the ceiling.
+      --
+      -- Still no ACTOR-scoped advisory lock: the row being renewed is required by the UPDATE's own
+      -- WHERE to be one of the counted rows, so the count is invariant under renew and there is no
+      -- slot to race for (20260928000100's header). The BOARD lock above answers a different
+      -- question -- which policy governs -- and is not a substitute for it in acquire.
+      if agent_board._claimgate_active_ownerless_claims(v_claim_agent_id)
+           > agent_board._claimgate_ownerless_quota() then
+        v_effective_expires := least(v_effective_expires, v_current_expires);
+      end if;
+    end if;
+  end if;
+
+  -- CLAIMKEY (#133) MUST-FIX 1: re-canonicalize the STORED key as the lease is renewed, but
+  -- NEVER propagate a uniqueness collision. A check-then-act guard is NOT race-safe: two aliased
+  -- legacy rows renewed concurrently at READ COMMITTED can both observe the canonical key free
+  -- and one loses on claims_active_resource_unique (23505). So attempt the canonicalization and,
+  -- on unique_violation (deterministic alias OR concurrent race), retry ONCE keeping the CURRENT
+  -- key. That makes renew non-raising UNCONDITIONALLY (true normalize-only); the surviving legacy
+  -- key is the deferred dual-key alias the ENFORCE phase closes.
+  begin
+    return query
+    update agent_board.claims c
+       set lease_expires_at = v_effective_expires,
+           resource_key = agent_board._canonical_claim_key(c.resource_kind, c.resource_key),
+           updated_at = now()
+     where c.lease_token = p_lease_token
+       and c.status = 'active'
+       and c.released_at is null
+       and c.lease_expires_at > now()
+    returning 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;
+  exception when unique_violation then
+    -- the canonical key is already held (by a committed twin or a concurrent renew/acquire):
+    -- renew the lease keeping the current key, aliasing deferred to ENFORCE. Only the key change
+    -- can raise unique_violation (the lease/timestamp columns are unconstrained), so the retry
+    -- cannot itself collide.
+    return query
+    update agent_board.claims c
+       set lease_expires_at = v_effective_expires,
+           updated_at = now()
+     where c.lease_token = p_lease_token
+       and c.status = 'active'
+       and c.released_at is null
+       and c.lease_expires_at > now()
+    returning 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;
+  end;
+end;
+$function$;
+
+-- ---------------------------------------------------------------------------
+-- set_board_claim_policy, re-created from the 20260929000100 dump with one statement added: the
+-- advisory lock, after the owner gate and before the outgoing-policy read.
+-- ---------------------------------------------------------------------------
+CREATE OR REPLACE FUNCTION agent_board.set_board_claim_policy(p_board_id uuid, p_claim_policy text)
+ RETURNS TABLE(board_id uuid, claim_policy text, updated_at timestamp with time zone)
+ LANGUAGE plpgsql
+ SECURITY DEFINER
+ SET search_path TO 'agent_board', 'public'
+AS $function$
+declare
+  v_actor uuid := agent_board.current_agent_id();
+  v_row agent_board.boards%rowtype;
+  v_prev_policy text;
+begin
+  if p_claim_policy is null then
+    raise exception 'p_claim_policy must not be null' using errcode = '22023';
+  end if;
+  -- Validated HERE as well as by the column CHECK. The CHECK would reject an unknown value
+  -- anyway, but with a constraint-violation error naming an internal constraint; a caller asking
+  -- for 'off' deserves to be told the vocabulary, not handed 23514.
+  if p_claim_policy not in ('inherit', 'advisory') then
+    raise exception 'claim policy must be one of inherit, advisory (received %)', p_claim_policy
+      using errcode = '22023';
+  end if;
+
+  -- Owner gate: only an active owner-role member may set this. service_role
+  -- (current_agent_id() = null) is not an owner and is rejected here.
+  if v_actor is null
+     or not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.role = 'owner'
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'only a board owner may set the claim policy' using errcode = '42501';
+  end if;
+
+  -- #405 THE BOARD POLICY LOCK. Taken AFTER the owner gate (an unauthorized caller must not be
+  -- able to make anyone wait, the same reason the row lock below sits here) and BEFORE the
+  -- outgoing-policy read, so every reader that serialises on this key -- acquire_claim and
+  -- renew_claim -- is either entirely before this flip or entirely after it. It is an ADVISORY
+  -- lock rather than a second row lock because #159 is open on lock ordering and a row lock on a
+  -- comparable path is what ab38805 reverted for a 40P01; an advisory lock only excludes callers
+  -- that also take it, which is why this migration re-derives the sole-writer proof for
+  -- boards.claim_policy from the catalog instead of inheriting #406's.
+  --
+  -- IT DOES NOT REPLACE the `for no key update` below. That row lock is what makes two concurrent
+  -- FLIPS see each other's outgoing value; this one is what makes a concurrent READER see the
+  -- committed one. Deleting either is separately observable (CPR-9, BCP-17).
+  perform agent_board._claimgate_lock_board_policy(p_board_id);
+
+  -- #400: the OUTGOING policy, read under the row lock the UPDATE below will take anyway. Placed
+  -- AFTER the owner gate so an unauthorized caller never locks the row. `for no key update` rather
+  -- than `for update`: it does not conflict with the FOR KEY SHARE an FK reference to boards takes,
+  -- so a concurrent thread insert on this board is not queued behind a policy flip. Two concurrent
+  -- flips serialize here, so only the one that genuinely observed 'advisory' resets.
+  --
+  -- A missing board leaves this null and the UPDATE below matches nothing, so the P0002 answer and
+  -- its ordering are unchanged.
+  select b.claim_policy into v_prev_policy
+    from agent_board.boards b
+   where b.id = p_board_id
+     for no key update;
+
+  update agent_board.boards b
+     set claim_policy = p_claim_policy,
+         updated_at = now()
+   where b.id = p_board_id
+  returning * into v_row;
+
+  if v_row.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+
+  -- #400 THE CAP RESET ON REVERT. Reverting to 'inherit' means accepting inherit's rules, so this
+  -- board's active ownerless claims get the ownerless TTL cap re-applied. The escape it closes:
+  -- flip to advisory, renew every claim to an arbitrary horizon (the advisory carve-out skips both
+  -- the cap and #388's convergence clamp), flip back, repeat. An agent that created the board is
+  -- its owner, so no accomplice is needed. Nothing took the granted horizon back — the convergence
+  -- clamp only refuses to EXTEND — so the horizon simply survived the revert.
+  --
+  -- CLAMP ONLY, and least() is the ONLY thing doing it. There is deliberately no `lease_expires_at
+  -- > now() + cap` conjunct in the WHERE: it would be the same guard written twice and would make
+  -- least() unmutatable. So a claim already within the cap keeps its lease to the microsecond
+  -- (BCP-12) while its updated_at is bumped — the documented cost of one mechanism over two.
+  --
+  -- 'advisory' -> 'inherit' ONLY. A no-op re-set (inherit -> inherit) must clamp nothing, and
+  -- neither may inherit -> advisory or advisory -> advisory (BCP-15/16/17).
+  --
+  -- Governed by the same operator flag as every other ownerless guard: with ownerless_guards off
+  -- nothing enforces this cap at acquire or renew, so re-applying it here would enforce a bound no
+  -- other path enforces (BCP-18). There is no service_role conjunct because service_role cannot
+  -- reach this line — the owner gate above refuses it (BCP-8).
+  --
+  -- Scoped to THIS board through the claim's thread, the same path _claimgate_board_claim_policy
+  -- resolves. A claim on another board, or with no thread, is untouched (BCP-14).
+  if v_prev_policy = 'advisory'
+     and p_claim_policy = 'inherit'
+     and agent_board._claimgate_ownerless_guards_enabled() then
+    update agent_board.claims c
+       set lease_expires_at = least(c.lease_expires_at,
+                                    now() + agent_board._claimgate_ownerless_ttl_cap()),
+           updated_at = now()
+     where c.resource_kind = any(agent_board._claimgate_ownerless_kinds())
+       and c.status = 'active'
+       and c.released_at is null
+       and c.lease_expires_at > now()
+       and c.thread_id in (select t.id
+                             from agent_board.threads t
+                            where t.board_id = p_board_id);
+  end if;
+
+  -- #276, AFTER the boards UPDATE so this function's order is boards -> agents, the canonical one
+  -- (#194). Fleet revocation deliberately LEAVES agents.status = 'active' -- the ledger row is the
+  -- only authority signal -- so the owner-membership check above passes for a revoked owner and
+  -- cannot stand alone. Disabling this board's claim enforcement is an authority write in the same
+  -- class as flipping the role gate, which is why the mirror has to include this call and not just
+  -- the membership test. Same transaction: the raise rolls the UPDATE back -- and, since #400, the
+  -- cap reset with it.
+  --
+  -- This was MISSING in the first version of this function, which claimed in its own commit
+  -- message to mirror set_board_role_gate "exactly". A review seat found it by reading both
+  -- functions side by side rather than taking that claim.
+  perform agent_board._assert_actor_not_fleet_revoked(v_actor, 'set_board_claim_policy');
+
+  return query select v_row.id, v_row.claim_policy, v_row.updated_at;
+end;
+$function$;
+
+-- ---------------------------------------------------------------------------
+-- Rule 5: recorded facts that were true when written and are not now. 20260929000100's bytes are
+-- hashed in the manifest and in fixtures/already-applied.json, so its file cannot be edited — the
+-- comments it set are restated here, the pattern that migration itself used for the same reason.
+--
+-- WHAT CHANGED. #406 recorded its limitation 3 as "an in-flight renew can still win the race, and
+-- this is unpinned". It is now closed on all three paths and pinned by four isolation specs. Its
+-- limitation 1 — the flip-every-29-days loophole — is NOT closed and is not claimed to be: that is
+-- not a race, it is inherent to a self-service opt-out, and the owner has decided to leave it
+-- open and documented. "Bounded, not closed" therefore still applies to the QUOTA escape, and no
+-- longer applies to the stale-policy race.
+-- ---------------------------------------------------------------------------
+comment on table agent_board.claimgate_enforcement_flags is
+  'CLAIMGATE per-scope enforcement flags. Absent row => disabled (SHADOW default: blocks nothing). '
+  'scope_key ''ownerless_guards'' gates EVERY ownerless (file/tool/custom) guard on ALL THREE write '
+  'paths: the TTL cap + per-agent quota in acquire_claim, in renew_claim both the TTL clamp (#373) '
+  'and the quota-convergence clamp (#388), and in set_board_claim_policy the advisory -> inherit cap '
+  'reset (#400). The advisory opt-out is owner-toggleable and re-toggleable, so it remains an escape '
+  'from convergence — bounded since #400 by the TTL cap per cycle rather than unbounded. Since #405 '
+  'all three paths serialise on a board-scoped advisory lock before resolving policy, so the escape '
+  'can no longer be widened by RACING a revert: a flip-flop banks at most one capped window, and '
+  'never a full horizon taken from policy that was already gone. Operator-managed (service_role); '
+  'enabled only after the prod lease-length census.';
+
+comment on function agent_board._claimgate_ownerless_quota() is
+  'CLAIMGATE/SHADOW (#133): max concurrent ACTIVE ownerless (file/tool/custom) claims per agent. '
+  'Single source for the migration logic and its tests. GENEROUS placeholder (50) pending prod '
+  'census. Enforced on BOTH write paths: acquire_claim REFUSES at count >= quota (54000), and '
+  'renew_claim stops EXTENDING at count > quota (#388) so an agent already over the ceiling '
+  'converges back to it instead of renewing its overage forever — SCOPED to agents whose boards do '
+  'not opt out. A board owner may flip claim_policy to advisory, let the agent renew, and flip '
+  'back; since #400 the revert re-applies the ownerless TTL cap, so each such cycle banks at most '
+  '_claimgate_ownerless_ttl_cap() rather than an arbitrary horizon, and since #405 a concurrent '
+  'acquire or renew cannot bank MORE than that by winning a race with the revert — all three paths '
+  'take a board-scoped advisory lock before resolving policy and re-read it afterwards. The '
+  'per-cycle escape is bounded, not closed (ORQ-11/12); the RACE is closed (CPR-15..CPR-18). The '
+  'two predicates differ deliberately — >= is what makes the quota the largest reachable '
+  'population, > is what makes the ceiling the convergence fixed point — and both count through '
+  '_claimgate_active_ownerless_claims(). Governed by _claimgate_ownerless_guards_enabled() on both '
+  'paths, service_role exempt, and skipped for a board whose claim_policy is advisory.';
+
+comment on function agent_board._claimgate_board_claim_policy(uuid) is
+  'Resolves a claim''s governing board policy through its thread. Returns ''inherit'' when the '
+  'thread is null, unknown, or not board-linked — so a claim with no board cannot opt itself out '
+  'by omission; opting out requires a board an owner deliberately configured. Since #405 this is '
+  'the COMPOSITION of _claimgate_board_of_thread() and _claimgate_board_claim_policy_of(), so '
+  'there is one definition of the walk; the enforcement paths call the two halves separately in '
+  'order to LOCK the board before resolving its policy, and this thread-keyed form is what the '
+  'census view v_ownerless_claim_quota resolves through (read-only, deliberately unserialised — a '
+  'stale read there is a report line, never a lease). Keeps its authenticated grant for exactly '
+  'that reason; the two halves are service_role only.';