@consiliency/agent-board-schema 1.12.0 → 1.22.0

package/migrations/20260825000100_agent_board_claimgate_enforce.sql

@@ -0,0 +1,660 @@
+-- CLAIMGATE Phase 3 — ENFORCE (#133): per-kind GATED fleet-authority DENIAL + renew re-auth
+-- + max-lease horizon. Ships the full enforcement machinery, but every fleet-backed kind's
+-- DENIAL is behind a per-kind flag that DEFAULTS OFF — nothing denies at merge.
+--
+-- =====================================================================================
+-- ROLLOUT — GATED PER-KIND, DEFAULT OFF (maintainer decision 2026-07-31, locked)
+-- =====================================================================================
+-- Reuses the SHADOW claimgate_enforcement_flags table (20260824000100:118) with per-kind
+-- scope_keys 'enforce_machine' / 'enforce_repository' / 'enforce_repo_file', resolved by
+-- _claimgate_kind_enforced(kind) which COALESCES to FALSE when the row is absent (mirrors the
+-- send-authz config-flag pattern 20260718000100 — but note that pattern DEFAULTS FAIL-OPEN;
+-- here absent => not-enforced => SHADOW behavior, i.e. shadow-stamp only). When a kind's flag
+-- is OFF: acquire/renew still just SHADOW-stamp (current behavior, blocks nothing). When ON:
+-- DENY (42501) an unauthorized claim/renew of that kind. Machine first (smallest population,
+-- cleanest identity), then repository/repo_file once each shadow census is clean.
+--
+-- =====================================================================================
+-- MAX-LEASE HORIZON — 30d DEFAULT, operator-configurable; CLAMP (not reject)
+-- =====================================================================================
+-- "Bounded by one lease term" is meaningless without a maximum (a gated kind could meet the
+-- acquire TTL and then renew for years). ENFORCE imposes a frozen maximum horizon on acquire
+-- AND every renew for the fleet-gated kinds (machine/repository/repo_file), ONLY when that
+-- kind's enforcement flag is ON. Stored as _claimgate_max_lease_horizon() reading an optional
+-- claimgate_settings('max_lease_horizon') override row, defaulting 30d (#118 discipline: a
+-- single-source resolver, not a literal sprinkled through the logic).
+--
+-- CLAMP, not reject: the horizon CLAMPS an over-long lease to now()+horizon rather than raising.
+-- This is FORCED by the reconciliation strategy — existing overlong active leases are NOT
+-- bulk-migrated (they are gated OFF until promotion); they reconcile at their NEXT renew, which
+-- only works if renew CLAMPS (a reject would leave the old long expiry in place and just error).
+-- Acquire clamps too, for consistency (a fresh 60d request lands the 30d bound). service_role
+-- is exempt (operator carve-out, consistent with the SHADOW ownerless cap).
+--   NOTE (reviewer-visible divergence): the SHADOW ownerless TTL cap (20260824000100:369)
+--   REJECTS an over-long ownerless lease (22023); this fleet horizon CLAMPS. Different mechanism,
+--   different intent (ownerless quota-squat prevention vs. fleet lease-term bound) — deliberate.
+--
+-- =====================================================================================
+-- ACTOR-PARAMETERIZED PREDICATE (shadow evidence must cover EXISTING claims)
+-- =====================================================================================
+-- SHADOW's session-derived _can_claim_resource(kind,key) can only evaluate the CURRENT actor,
+-- so it cannot census a claim already held by some OTHER agent. ENFORCE splits it:
+--   * _can_claim_resource_for(p_actor, kind, key)  — pure authority for an ARBITRARY actor
+--     (NO service_role carve-out — that is a property of the CALLER, not the subject).
+--   * _can_claim_resource(kind, key)               — the frozen IF-0-SHADOW-1 wrapper, unchanged
+--     in behavior: service_role short-circuits true, else delegates to _for(current_agent_id()).
+-- Behavior of the frozen signature is IDENTICAL (the 36-assertion predicate suite regression-pins
+-- the refactor). The operator censuses existing rows with _can_claim_resource_for(claim.agent_id,…).
+--
+-- FAIL-CLOSED ON UNKNOWN: automatic. An unknown/unresolvable fleet resource (fingerprint not in
+-- the graph) makes the predicate return FALSE, so an enforced acquire of it DENIES — no special arm.
+--
+-- Renew re-auth CONSULTS THE SAME per-kind flag acquire does (a mutation splitting the flags fails
+-- a test). Task-kind renew AND all release_claim stay OWNERSHIP-ONLY — this SUPERSEDES
+-- 20260817000100:27-28 (maintainer-ratified 2026-07-31); only the 3 predicate-gated kinds re-auth.
+--
+-- Depends on the register_fleet_machine cross-owner-hijack fix (#141 / 20260629000101 hardening,
+-- merged as #145) — fingerprint-ownership must not be stealable once it equals lock authority.
+--
+-- #118 class (CLAUDE.md schema-mechanics): every NEWLY-DEFINED SECURITY DEFINER function below
+-- restates revoke/grant/comment; the new claimgate_settings table restates grant/RLS/policy/
+-- comment (mirroring claimgate_enforcement_flags). acquire_claim / renew_claim / _can_claim_resource
+-- are create-or-replace of existing functions (preserve prior ACL/comment) — they restate only
+-- revoke+grant. Additive, forward-only. schema_version stays 8.
+
+-- 0. Per-kind enforcement resolver — reuse claimgate_enforcement_flags, DEFAULT OFF. ---------
+create or replace function agent_board._claimgate_kind_enforced(p_resource_kind text)
+returns boolean
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select coalesce(
+    (select f.enabled
+       from agent_board.claimgate_enforcement_flags f
+      where f.scope_key = case p_resource_kind
+              when 'machine'    then 'enforce_machine'
+              when 'repository' then 'enforce_repository'
+              when 'repo_file'  then 'enforce_repo_file'
+              else null
+            end),
+    false)
+$$;
+revoke all on function agent_board._claimgate_kind_enforced(text) from public, anon;
+grant execute on function agent_board._claimgate_kind_enforced(text) to authenticated, service_role;
+comment on function agent_board._claimgate_kind_enforced(text) is
+  'CLAIMGATE/ENFORCE (#133): is DENIAL enforced for this fleet-backed kind? Reads '
+  'claimgate_enforcement_flags scope_key enforce_machine/enforce_repository/enforce_repo_file; '
+  'DEFAULTS FALSE (absent row) so a kind stays SHADOW (stamp-only) until an operator flips it. '
+  'Non-fleet kinds (task/file/tool/custom) always resolve FALSE (no scope_key). SECURITY DEFINER; '
+  'PUBLIC EXECUTE revoked. acquire AND renew consult THIS resolver (one flag per kind).';
+
+-- 1. Max-lease horizon setting + resolver (operator-configurable, default 30d). --------------
+create table if not exists agent_board.claimgate_settings (
+  key text primary key,
+  value text not null,
+  updated_at timestamptz not null default now(),
+  -- Validate the max_lease_horizon override at WRITE time, not in the hot path: a malformed or
+  -- non-positive value must fail the operator's INSERT/UPDATE rather than raise (22007) or clamp
+  -- into the past on EVERY enforced fleet acquire/renew where _claimgate_max_lease_horizon() casts
+  -- it (panel should-fix). CASE guards the cast so it only runs for the horizon key (a non-horizon
+  -- setting may hold arbitrary text). A malformed literal raises on the cast here; a <= 0 interval
+  -- fails the CHECK — both at write time.
+  constraint claimgate_settings_max_lease_horizon_valid check (
+    case when key = 'max_lease_horizon' then (value::interval) > interval '0' else true end
+  )
+);
+comment on table agent_board.claimgate_settings is
+  'CLAIMGATE operator-configurable settings (key/value text). key ''max_lease_horizon'' overrides '
+  'the fleet max-lease horizon (an interval literal, e.g. ''14 days''); absent => 30d default. '
+  'Operator-managed (service_role); read through _claimgate_max_lease_horizon().';
+alter table agent_board.claimgate_settings enable row level security;
+grant select, insert, update, delete on agent_board.claimgate_settings to service_role;
+drop policy if exists agent_board_service_all_claimgate_settings on agent_board.claimgate_settings;
+create policy agent_board_service_all_claimgate_settings
+  on agent_board.claimgate_settings
+  as permissive for all to service_role using (true) with check (true);
+
+create or replace function agent_board._claimgate_max_lease_horizon()
+returns interval
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select coalesce(
+    (select s.value::interval
+       from agent_board.claimgate_settings s
+      where s.key = 'max_lease_horizon'),
+    interval '30 days')
+$$;
+revoke all on function agent_board._claimgate_max_lease_horizon() from public, anon;
+grant execute on function agent_board._claimgate_max_lease_horizon() to authenticated, service_role;
+comment on function agent_board._claimgate_max_lease_horizon() is
+  'CLAIMGATE/ENFORCE (#133): max lease horizon for an ENFORCED fleet-backed (machine/repository/'
+  'repo_file) claim, applied on acquire AND every renew (CLAMPS an over-long lease, does not reject). '
+  'Reads claimgate_settings(''max_lease_horizon'') override; DEFAULTS 30d. SECURITY DEFINER (reads a '
+  'service_role-only table); PUBLIC EXECUTE revoked.';
+
+-- 2. _can_claim_resource_for — the ACTOR-PARAMETERIZED authority twin. ----------------------
+--    Body reproduced from _can_claim_resource (20260824000100) EXCEPT: (a) authority is computed
+--    for the PASSED p_actor, not current_agent_id(); (b) NO service_role short-circuit (that is a
+--    caller property, kept in the wrapper below). Lets the operator census EXISTING held claims
+--    for an arbitrary owner. SECURITY DEFINER to break fleet-table RLS recursion (#118).
+create or replace function agent_board._can_claim_resource_for(
+  p_actor uuid,
+  p_resource_kind text,
+  p_resource_key text
+)
+returns boolean
+language plpgsql
+stable
+security definer
+set search_path = 'agent_board', 'public'
+as $function$
+declare
+  v_fp    text;
+  v_sep   int;
+begin
+  -- The ownerless tail + task are not fleet-gated, so they remain authorized even for a null
+  -- actor (governed elsewhere: task gate in acquire_claim; ownerless TTL/quota in acquire_claim).
+  if p_resource_kind = 'task' then
+    return true;
+  elsif p_resource_kind in ('file', 'tool', 'custom') then
+    return true;
+  end if;
+
+  -- A null principal is honestly UNAUTHORIZED on any fleet-backed kind (fail-closed-on-unknown).
+  if p_actor is null then
+    return false;
+  end if;
+
+  if p_resource_kind = 'machine' then
+    v_fp := btrim(p_resource_key);
+    if v_fp is null or v_fp = '' then
+      return false;
+    end if;
+    -- machine_fingerprint is globally unique; the machine AND its trust domain must be active,
+    -- and the actor must own it OR hold an active binding on it.
+    return exists (
+      select 1
+        from agent_board.fleet_machines fm
+        join agent_board.fleet_trust_domains ftd
+          on ftd.id = fm.trust_domain_id
+       where fm.machine_fingerprint = v_fp
+         and fm.lifecycle_state = 'active'
+         and ftd.lifecycle_state = 'active'
+         and (
+           fm.owner_agent_id = p_actor
+           or exists (
+             select 1
+               from agent_board.fleet_machine_agents fma
+              where fma.machine_id = fm.id
+                and fma.agent_id = p_actor
+                and fma.lifecycle_state = 'active'
+           )
+         )
+    );
+
+  elsif p_resource_kind = 'repository' or p_resource_kind = 'repo_file' then
+    if p_resource_kind = 'repo_file' then
+      -- FIRST ':' splits fp | path (the exact position CLAIMKEY froze). No colon / empty fp =
+      -- not resolvable -> deny (honest verdict; fail-closed).
+      v_sep := position(':' in coalesce(p_resource_key, ''));
+      if v_sep <= 1 then
+        return false;
+      end if;
+      v_fp := btrim(substring(p_resource_key from 1 for v_sep - 1));
+    else
+      v_fp := btrim(p_resource_key);
+    end if;
+    if v_fp is null or v_fp = '' then
+      return false;
+    end if;
+    -- FULL chain, EVERY edge lifecycle-active (PANEL AMENDMENT: harness revoke does not cascade
+    -- to child scopes, so fhr.lifecycle_state='active' is load-bearing here). Anchored on the
+    -- actor's active binding + its repo_scope; UNION across trust domains (shared-lock model).
+    return exists (
+      select 1
+        from agent_board.fleet_machine_agents fma
+        join agent_board.fleet_repo_scopes frs
+          on frs.id = fma.repo_scope_id
+        join agent_board.fleet_harness_registrations fhr
+          on fhr.id = frs.harness_registration_id
+        join agent_board.fleet_machines fm
+          on fm.id = fhr.machine_id
+        join agent_board.fleet_trust_domains ftd
+          on ftd.id = fm.trust_domain_id
+       where fma.agent_id = p_actor
+         and fma.lifecycle_state = 'active'
+         and frs.repo_fingerprint = v_fp
+         and frs.scope_role <> 'observer'
+         and frs.lifecycle_state = 'active'
+         and fhr.lifecycle_state = 'active'
+         and fm.lifecycle_state = 'active'
+         and ftd.lifecycle_state = 'active'
+    );
+
+  else
+    -- Defensive: an unenumerated future kind. The completeness test enumerates the 7 catalog
+    -- kinds and asserts each is handled, so this is unreachable for today's constraint.
+    return true;
+  end if;
+end;
+$function$;
+-- LEAST-PRIVILEGE (panel must-fix): grant to service_role ONLY — NOT authenticated. This
+-- SECURITY DEFINER function is an RLS-bypassing authority ORACLE: fleet_machine_agents' SELECT
+-- policy (20260629000100:341-355) hides a binding from everyone but its subject/machine-owner,
+-- but _for would let ANY authenticated caller probe an arbitrary (actor, fingerprint) pair and
+-- learn whether that actor is fleet-authorized. The only call-site is the session-bound wrapper
+-- _can_claim_resource (which binds current_agent_id() and is itself SECURITY DEFINER, so it
+-- invokes _for as OWNER regardless of this grant) — no RPC passes caller input as p_actor. So the
+-- authenticated grant buys nothing and only exposes the oracle; revoke it. The operator census
+-- path runs as service_role.
+revoke all on function agent_board._can_claim_resource_for(uuid, text, text) from public, anon;
+grant execute on function agent_board._can_claim_resource_for(uuid, text, text) to service_role;
+comment on function agent_board._can_claim_resource_for(uuid, text, text) is
+  'CLAIMGATE/ENFORCE (#133): actor-parameterized fleet-graph authority — computes authority for an '
+  'ARBITRARY p_actor (NO service_role carve-out; that is a caller property, kept in the session '
+  'wrapper _can_claim_resource). Same fleet chains as SHADOW. Lets the operator (service_role) census '
+  'EXISTING held claims (_can_claim_resource_for(claim.agent_id, kind, key)). SECURITY DEFINER; granted '
+  'to service_role ONLY (an RLS-bypass authority oracle — NOT exposed to authenticated); PUBLIC revoked.';
+
+-- 3. _can_claim_resource — the frozen IF-0-SHADOW-1 wrapper, now delegating to the twin. ----
+--    BEHAVIOR UNCHANGED: service_role short-circuits true; otherwise authority for the SESSION
+--    actor (current_agent_id()). The 36-assertion predicate suite regression-pins this refactor.
+create or replace function agent_board._can_claim_resource(
+  p_resource_kind text,
+  p_resource_key text
+)
+returns boolean
+language plpgsql
+stable
+security definer
+set search_path = 'agent_board', 'public'
+as $function$
+begin
+  -- Operator carve-out: service_role short-circuits authorized (matches every other gate).
+  if agent_board._is_service_role() then
+    return true;
+  end if;
+  return agent_board._can_claim_resource_for(
+    agent_board.current_agent_id(), p_resource_kind, p_resource_key);
+end;
+$function$;
+revoke all on function agent_board._can_claim_resource(text, text) from public, anon;
+grant execute on function agent_board._can_claim_resource(text, text) to authenticated, service_role;
+comment on function agent_board._can_claim_resource(text, text) is
+  'CLAIMGATE (#133, IF-0-SHADOW-1): session-derived fleet-graph authority predicate ENFORCE consumes. '
+  'service_role short-circuits true; otherwise delegates to _can_claim_resource_for(current_agent_id()). '
+  'Behavior FROZEN and unchanged from SHADOW (the actor-parameterized split is behavior-preserving). '
+  'SECURITY DEFINER to break fleet RLS recursion; PUBLIC EXECUTE revoked.';
+
+-- 4. acquire_claim — per-kind gated DENIAL + horizon clamp. ---------------------------------
+--    Reproduced VERBATIM from 20260824000100 (SHADOW) EXCEPT the single ENFORCE block inserted
+--    right after the shadow verdict is computed and BEFORE the sweep (predicate-before-side-
+--    effects: a denied caller observes no state change — no swept-expired rows leak the deny).
+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;
+
+  -- 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;
+
+-- 5. renew_claim — RE-AUTHORIZE fleet-gated kinds + horizon clamp. --------------------------
+--    Reproduced VERBATIM from 20260821000100 (CLAIMKEY) EXCEPT the ENFORCE block after the
+--    ownership check: (a) re-run the SAME session predicate acquire consults for the 3 predicate-
+--    gated kinds when the kind's flag is ON, so a revoked binding cannot perpetually extend a
+--    lease; (b) clamp the renewed lease to the max horizon. Task-kind renew stays OWNERSHIP-ONLY
+--    (this SUPERSEDES 20260817000100:27-28, maintainer-ratified 2026-07-31): only machine/
+--    repository/repo_file re-auth; task/file/tool/custom renew unchanged, release_claim untouched.
+create or replace function agent_board.renew_claim(p_lease_token uuid, p_lease_expires_at timestamptz)
+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 timestamptz, released_at timestamptz, created_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor_agent_id uuid;
+  v_kind text;
+  v_key text;
+  v_effective_expires timestamptz;
+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).
+  select c.resource_kind, c.resource_key
+    into v_kind, v_key
+    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;
+
+  -- 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;
+$$;
+revoke all on function agent_board.renew_claim(uuid, timestamptz) from public, anon;
+grant execute on function agent_board.renew_claim(uuid, timestamptz) to authenticated, service_role;
+
+-- 6. _claimgate_promotion_blockers — PROMOTION-READINESS gate (panel must-fix, roadmap :346/:352).
+--    Enforcement flags stay OPERATOR-GATED and DEFAULT OFF (there is NO auto-clamp / auto-migrate).
+--    This is the VERIFICATION the roadmap's "reconcile before enforcement" (:346) and "zero
+--    non-canonical fleet claims at flip" (:352) exit criteria require, made checkable WITHOUT
+--    mutating any lease. For a fleet kind it returns every ACTIVE (status='active', unreleased,
+--    unexpired) claim that would BREAK the instant enforce_<kind> flips ON:
+--      (a) unauthorized  — the CURRENT holder is no longer fleet-authorized for it, computed with
+--          the actor-parameterized _can_claim_resource_for(agent_id, kind, key) (this is exactly
+--          why that private twin exists — it evaluates an EXISTING holder, not the session actor);
+--      (b) over_horizon  — lease_expires_at exceeds now()+_claimgate_max_lease_horizon(), i.e. a
+--          lease that would be clamped (and, for a lease that will never renew, would otherwise run
+--          past the bound forever — the years-long-lease case);
+--      (c) non_canonical — resource_key <> _canonical_claim_key(...), the dual-key aliasing window.
+--    An EMPTY result for a kind == SAFE to flip that kind's flag.
+--
+-- =====================================================================================
+-- PROMOTION RUNBOOK (operator, per fleet kind — machine, then repository, then repo_file)
+-- =====================================================================================
+--   1. select * from agent_board._claimgate_promotion_blockers('<kind>');   -- as service_role
+--   2. For EACH row: reconcile it — release_claim / let it expire (unauthorized or over-horizon),
+--      or renew_claim once to self-heal a non_canonical key (CLAIMKEY re-canonicalizes on renew).
+--   3. Re-run step 1; when it returns ZERO rows the kind is safe.
+--   4. Only then: insert into agent_board.claimgate_enforcement_flags(scope_key, enabled)
+--         values ('enforce_<kind>', true) on conflict (scope_key) do update set enabled = true;
+--   (The ownerless file/tool/custom guards remain INDEPENDENTLY flag-gated behind
+--    claimgate_enforcement_flags('ownerless_guards') — OFF until the prod lease-length census;
+--    they are NOT co-timed with fleet enforcement, per the maintainer decision, and this gate does
+--    not cover them.)
+--
+-- #118: SECURITY DEFINER (reads all claims + the RLS-recursive fleet graph via _for) — service_role
+-- ONLY (an operator census/oracle, same posture as _can_claim_resource_for); PUBLIC revoked.
+create or replace function agent_board._claimgate_promotion_blockers(p_resource_kind text)
+returns table(
+  claim_id uuid,
+  agent_id uuid,
+  resource_kind text,
+  resource_key text,
+  lease_expires_at timestamptz,
+  unauthorized boolean,
+  over_horizon boolean,
+  non_canonical boolean
+)
+language sql
+stable
+security definer
+set search_path = ''
+as $$
+  select c.id, c.agent_id, c.resource_kind, c.resource_key, c.lease_expires_at,
+         not agent_board._can_claim_resource_for(c.agent_id, c.resource_kind, c.resource_key)          as unauthorized,
+         c.lease_expires_at > now() + agent_board._claimgate_max_lease_horizon()                        as over_horizon,
+         c.resource_key is distinct from agent_board._canonical_claim_key(c.resource_kind, c.resource_key) as non_canonical
+    from agent_board.claims c
+   where c.resource_kind = p_resource_kind
+     and c.status = 'active'
+     and c.released_at is null
+     and c.lease_expires_at > now()
+     and (
+          not agent_board._can_claim_resource_for(c.agent_id, c.resource_kind, c.resource_key)
+       or c.lease_expires_at > now() + agent_board._claimgate_max_lease_horizon()
+       or c.resource_key is distinct from agent_board._canonical_claim_key(c.resource_kind, c.resource_key)
+     )
+$$;
+revoke all on function agent_board._claimgate_promotion_blockers(text) from public, anon;
+grant execute on function agent_board._claimgate_promotion_blockers(text) to service_role;
+comment on function agent_board._claimgate_promotion_blockers(text) is
+  'CLAIMGATE/ENFORCE (#133, roadmap :346/:352): promotion-readiness gate for a fleet kind. Returns the '
+  'ACTIVE claims that would BREAK at flip — unauthorized holder (via _can_claim_resource_for), '
+  'over the max-lease horizon, or a non-canonical key. EMPTY == safe to set enforce_<kind>=true. '
+  'Verification only (no lease is mutated; enforcement stays operator-gated, default OFF). '
+  'SECURITY DEFINER; service_role ONLY (operator census); PUBLIC revoked.';