@consiliency/agent-board-schema 1.45.0 → 1.48.0

package/migrations/20260928000100_agent_board_ownerless_quota_renew_convergence.sql

@@ -0,0 +1,562 @@
+-- #388 — the ownerless quota bounds NEW ACQUISITIONS but never CONVERGES an agent already over it.
+--
+-- THE PROPERTY. `acquire_claim` refuses at `count >= _claimgate_ownerless_quota()` (50) concurrent
+-- active ownerless (file/tool/custom) claims. `renew_claim` has never asked the question at all. So
+-- the ceiling binds GROWTH and not PERSISTENCE: an agent already over it renews every one of its
+-- claims indefinitely and stays over, forever. #393 shipped the census that REPORTS those agents
+-- (`v_ownerless_claim_quota`, `ownerless_quota_census()`); nothing CONVERGES them. This does.
+--
+-- ===========================================================================
+-- THE DESIGN: A MONOTONE, NON-EXTENDING CLAMP. "While over quota, a renew may not postpone a
+-- deadline." The lease the agent already holds is untouched to the microsecond; the renew succeeds
+-- and returns the row; the only thing withheld is MORE TIME.
+-- ===========================================================================
+--
+-- WHY NOT A RAISE, and this is the option a reader reaches for first. #387's test file states the
+-- rationale and ORT-3 asserts it by checking a resulting TIMESTAMP rather than an error: acquire
+-- RAISES because nothing is lost by asking again, but a renew that raised would KILL A LEASE THE
+-- AGENT IS ACTIVELY HOLDING, converting a quantity problem into an availability incident. That
+-- reasoning is undisturbed by #388 — being over quota is exactly the state in which the agent has
+-- the most in-flight work to lose — so no existing assertion changes contract here.
+--
+-- WHY NOT THE OBVIOUS CLAMP — a short grace horizon (renew still succeeds, but only to
+-- `now() + 1 hour`, so leases lapse quickly). IT DOES NOT CONVERGE, and the counterexample is
+-- one line: an agent at 60 simply renews all 60 every hour and stays at 60 forever. Convergence
+-- under that design is contingent on the over-quota agent CHOOSING to abandon claims, which is
+-- the one party whose cooperation the guard exists not to require. It also behaves worst for the
+-- careful agent (a 29-day lease is cut to an hour) and not at all for the diligent one. Rejected
+-- on the counterexample, recorded here so the next reader does not re-propose it as "simpler".
+--
+-- WHY THE MONOTONE CLAMP CONVERGES, AND AGAINST WHOM. Every deadline is FIXED at the moment the
+-- agent goes over. No renew can move one later, so each claim lapses at its own already-set expiry,
+-- the count falls monotonically, and the guard releases the instant the count is back at the
+-- ceiling. The agent keeps every second it already had — up to the full 30-day ownerless cap —
+-- which is a longer and fairer grace than any fixed window, and it is per claim rather than uniform.
+--
+-- THAT SENTENCE IS SCOPED, and an earlier version of this header stated it without the scope, which
+-- was WRONG. It holds against an agent whose boards do not opt out. It does NOT hold against an
+-- agent with a cooperating board owner, and #399's panel is right that this is the material
+-- limitation:
+--
+--   THE OWNER-TOGGLE ESCAPE. The advisory carve-out below is resolved at RENEW TIME against the
+--   board's CURRENT policy, and `set_board_claim_policy` is owner-settable. So an owner can flip
+--   the board to 'advisory', let the over-quota agent renew every claim to the full horizon, flip
+--   back to 'inherit', and repeat before the next expiry. Nothing here takes the granted horizon
+--   back — the clamp only refuses to EXTEND, it never shortens — so the agent stays over quota for
+--   as long as the owner keeps flipping. NO ACCOMPLICE IS REQUIRED: `create_board` seeds the
+--   creator's owner membership and that membership is exactly what the policy gate tests, so an
+--   agent that created a board holds the switch that exempts its own claims. ORQ-11 performs the
+--   flip-flop through the real RPCs and pins it.
+--
+--   AND IT IS INVISIBLE TO THE CENSUS, which is the half worth recording. #393 resolves board
+--   policy at QUERY time, so once the board is back to 'inherit' the escaped claim contributes ZERO
+--   to `claims_on_advisory_boards` while the overage it bought is still counted. An operator sees
+--   an agent over quota with no advisory share — the shape that reads as plain squatting — and the
+--   column built to explain the exemption reports none of it. ORQ-12 pins that too.
+--
+-- THE CARVE-OUT IS NOT REMOVED IN RESPONSE, and that is a decision rather than an oversight. A board
+-- coordinating through someone else's mutex asked us not to enforce; refusing to extend a lease that
+-- mutex already granted would break the promise the opt-out makes, which is the whole reason the
+-- opt-out exists. Making the exemption ACQUIRE-time was also rejected: nothing records the policy in
+-- force when a claim was taken — that absence is #393's own documented gap — and inventing a policy
+-- history here would be a second, unreviewed mechanism. What was defective was the CLAIM, not the
+-- code, so the claim is scoped and the limitation is pinned by a test rather than left in prose.
+--
+-- THE REST OF THE CONVERGENCE BOUND, STATED HONESTLY rather than as "unconditional". The horizon is
+-- THE LONGEST LEASE THE AGENT CURRENTLY HOLDS. A 400-day lease grandfathered from before the flag
+-- flip (#369) lapses at ITS OWN expiry and not sooner — a renew-side guard cannot touch a claim
+-- whose holder never renews it, and this one does not pretend to. `service_role` is outside it too,
+-- by the operator carve-out. An agent whose entire overage sits on advisory boards never converges,
+-- which is why the census reports `claims_on_advisory_boards` as its own column: it is precisely
+-- the share this guard cannot reach while the board stays advisory.
+--
+-- `> quota`, NOT `>= quota`, AND THE DIFFERENCE IS A REAL AGENT. `>=` is ACQUIRE's refusal
+-- predicate, and acquire refusing at 50 is what makes 50 the largest population reachable through
+-- it. Reusing `>=` here would freeze an agent sitting legitimately AT the ceiling and walk it down
+-- to 49 — shrinking a legal population rather than converging an illegal one. The predicate used is
+-- the census's own `overage > 0` / `agents_over_quota`, so the fixed point is exactly the ceiling
+-- and the two surfaces answer with one arithmetic.
+--
+-- WHICH ASSERTIONS PIN THAT, corrected by MEASURING rather than by reasoning about the fixtures.
+-- An earlier draft of this header said "ORQ-2 is the assertion that fails on `>=`, and it is the
+-- only one that can: it needs an agent at EXACTLY 50, which no other fixture has." Both halves
+-- were wrong, and the mutation says so:
+--
+--   `>` -> `>=`                     ran=31, not ok on ORQ-5 AND ORQ-13
+--   remove the least() clamp        ran=31, not ok on ORQ-1, ORQ-2, ORQ-3
+--
+-- So ORQ-2 pins the CLAMP, not the boundary, and the boundary is pinned TWICE. The "only one that
+-- can" reasoning was self-refuting: ORQ-13 is the fixed point, and its own text says it "puts the
+-- agent AT the ceiling" — precisely the fixture the header claimed no other case had. Being pinned
+-- by two assertions is stronger than the claim, but a header that names the wrong assertion sends
+-- the next reader to the wrong test when this breaks, so it is corrected rather than left as a
+-- harmless understatement.
+--
+-- NO `pg_advisory_xact_lock`, AND THIS DEVIATES FROM #388 STEP 2 ON PURPOSE. That step prescribes
+-- acquire's agent-scoped lock plus a two-session isolationtester case "so two concurrent renews
+-- cannot both observe room". That requirement belongs to an ADMIT design — one where a renew
+-- CONSUMES a slot and two concurrent renews could consume the same one. This design admits
+-- nothing. The row being renewed is required by the UPDATE's own WHERE (`status = 'active' and
+-- released_at is null and lease_expires_at > now()`) to be one of the counted rows, so the count is
+-- INVARIANT under renew: renew inserts nothing and can only shorten. Two concurrent renews by the
+-- same agent therefore either both freeze or both pass, and either way the population is unchanged.
+-- The only stale read available is "saw 51 while a concurrent release made it 50", whose entire
+-- consequence is one renew that did not extend and which the next renew extends. Acquire keeps its
+-- lock, because acquire COUNTS THEN INSERTS and that genuinely races.
+--
+-- THE CARVE-OUTS ARE ACQUIRE'S FOUR, VERBATIM, so one operator flag governs every ownerless guard
+-- on both write paths and a board coordinating its own locking is not converged by ours:
+--   the kind is ownerless · not service_role · _claimgate_ownerless_guards_enabled()
+--   · the claim's board is not claim_policy = 'advisory'
+-- The agent id and the thread come from the LIVE CLAIM, never from a caller argument — a
+-- caller-supplied thread would let an agent choose which board's policy is consulted.
+--
+-- ONE DEFINITION OF THE COUNT, NOT THREE. `_claimgate_active_ownerless_claims()` below is extracted
+-- from acquire's inline predicate and acquire is re-created to call it, so the two ENFORCEMENT
+-- paths cannot drift. The census view keeps its own copy DELIBERATELY: OQ-6's four near-miss rows
+-- are what make each conjunct of the reader's predicate individually mutation-visible, and routing
+-- the view's headline through the helper would make that mutation invisible. The two are pinned
+-- EQUAL behaviourally instead (ORQ-13), which is the property that actually matters.
+
+-- ---------------------------------------------------------------------------
+-- The count. Acquire's quota predicate, moved here unchanged, and now the single definition both
+-- enforcement paths ask.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board._claimgate_active_ownerless_claims(p_agent_id uuid)
+returns integer
+language sql
+stable
+set search_path = ''
+as $$
+  select count(*)::integer
+    from agent_board.claims c
+   where c.agent_id = p_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();
+$$;
+
+-- SERVICE_ROLE ONLY, and NARROWER than the sibling `_claimgate_ownerless_quota()` (which is granted
+-- to `authenticated`) on purpose. That one returns a constant and tells a caller nothing. This one
+-- reads `agent_board.claims`, and it is `security invoker` — so an `authenticated` caller would get
+-- its OWN RLS-filtered count back, wearing the name of the fleet-wide quota count. That is the
+-- census's own #367-shape trap one layer down: a confident, plausible, wrong number. The two
+-- SECURITY DEFINER callers do not need the grant (a definer executes as its owner), so withholding
+-- it costs the enforcement paths nothing.
+revoke all on function agent_board._claimgate_active_ownerless_claims(uuid) from public, anon;
+grant execute on function agent_board._claimgate_active_ownerless_claims(uuid) to service_role;
+
+comment on function agent_board._claimgate_active_ownerless_claims(uuid) is
+  '#388: THE single definition of an agent''s active ownerless (file/tool/custom) claim count — '
+  'acquire_claim''s quota predicate, extracted verbatim (kind in file/tool/custom, status active, '
+  'released_at null, lease unexpired). Called by acquire_claim (which refuses at >= '
+  '_claimgate_ownerless_quota()) and by renew_claim (which stops EXTENDING at > quota, so an '
+  'over-quota agent converges to the ceiling UNLESS its board opts out — a board owner can flip '
+  'claim_policy to advisory and back indefinitely, and an agent that created a board is its owner, '
+  'so convergence is guaranteed only against an agent whose boards do not opt out, #399). NO '
+  'board-policy filter here: the advisory opt-out gates '
+  'whether a guard RUNS, not whether the resulting rows COUNT. service_role only, and deliberately '
+  'narrower than _claimgate_ownerless_quota(): this reads claims under security invoker, so an '
+  'authenticated caller would receive its own RLS-filtered count under a fleet-wide name.';
+
+-- ---------------------------------------------------------------------------
+-- acquire_claim, re-created from the 20260922000100 pg_get_functiondef dump with exactly one hunk
+-- changed: the inline count is now the helper call. CREATE OR REPLACE with an unchanged signature,
+-- so the ACL and the COMMENT survive.
+-- ---------------------------------------------------------------------------
+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;
+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()
+     -- 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.
+     and agent_board._claimgate_board_claim_policy(v_thread_id) <> '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).
+    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 this migration'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;
+
+  -- 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. The #373 body (20260925000100) with the convergence clamp added after the TTL clamp,
+-- and the live claim's agent id and CURRENT expiry read alongside the kind it already reads.
+-- ---------------------------------------------------------------------------
+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_thread_id uuid;
+  v_claim_agent_id uuid;
+  v_current_expires timestamptz;
+  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).
+  --
+  -- #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;
+
+  -- #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 four conditions are acquire's, verbatim, 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_kind in ('file', 'tool', 'custom')
+     and not agent_board._is_service_role()
+     and agent_board._claimgate_ownerless_guards_enabled()
+     and agent_board._claimgate_board_claim_policy(v_thread_id) <> 'advisory'
+     and 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.
+  --
+  -- `>` 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.
+  --
+  -- Same four carve-outs as the cap above, evaluated against the LIVE claim's holder and thread.
+  -- No 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. See the
+  -- migration header for why that departs from #388 step 2.
+  if v_kind in ('file', 'tool', 'custom')
+     and not agent_board._is_service_role()
+     and agent_board._claimgate_ownerless_guards_enabled()
+     and agent_board._claimgate_board_claim_policy(v_thread_id) <> 'advisory'
+     and 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;
+
+  -- 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;
+$$;
+
+-- ---------------------------------------------------------------------------
+-- Rule 5: two comments that were true when written and are not now. Corrected in the same
+-- migration that falsifies them rather than left for the next reader to disbelieve.
+-- ---------------------------------------------------------------------------
+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 — GUARANTEED ONLY against an agent '
+  'whose boards do not opt out: a board owner may flip claim_policy to advisory, let the agent '
+  'renew to the full horizon, and flip back, indefinitely (#399; pinned by ORQ-11/12). 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 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 BOTH write '
+  'paths: the TTL cap + per-agent quota in acquire_claim, and in renew_claim both the TTL clamp '
+  '(#373) and the quota-convergence clamp (#388, which stops an over-quota holder from extending '
+  'any lease until it is back at the ceiling — on a board that has not opted out; the advisory '
+  'opt-out is owner-toggleable and re-toggleable, so it is also an escape from convergence, #399). '
+  'Operator-managed (service_role); enabled only after '
+  'the prod lease-length census.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.45.0",
+  "version": "1.48.0",
   "description": "Canonical, immutable, exact-pinnable agent_board schema bundle: ordered SQL migrations, digest + compatibility manifest, and deterministic materialize/plan/check tooling for adopters.",
   "repository": "https://github.com/Consiliency/message-board.git",
   "type": "module",

package/schema-manifest.json

@@ -2,7 +2,7 @@
   "schema": "agent_board_schema_manifest.v1",
   "interface": "IF-0-MBPLANE-BUNDLE-1",
   "package": "@consiliency/agent-board-schema",
-  "packageVersion": "1.45.0",
+  "packageVersion": "1.48.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 143,
-  "aggregateSha256": "e5f248a69031759fbd220b5504268c4ca3159fc7cf641404badf2f2ae855e4ae",
+  "migrationCount": 146,
+  "aggregateSha256": "cbb24bed446f3334f4c0593716b51ee00e5b6faf57bfd7b48a8767f019551551",
   "migrations": [
     {
       "order": 0,
@@ -1335,6 +1335,33 @@
       "sourceRef": "message-board",
       "bytes": 9981,
       "sha256": "da312f43cabf07c6dfd10dbe2a119fb46f49f24155e21adce4f38e291a38103c"
+    },
+    {
+      "order": 143,
+      "id": "20260926000100_agent_board_ownerless_quota_census",
+      "filename": "20260926000100_agent_board_ownerless_quota_census.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 17894,
+      "sha256": "bbfabcb2d45cbcebd1e6e121032a1045e8406ea8763a784762a92d210e1e1043"
+    },
+    {
+      "order": 144,
+      "id": "20260927000100_agent_board_fleet_domain_no_downgrade",
+      "filename": "20260927000100_agent_board_fleet_domain_no_downgrade.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 25689,
+      "sha256": "ec5c4d89aff2d6d77d44cb3d00c1096b39010c6064c23d72eb3c5c354f8a5e74"
+    },
+    {
+      "order": 145,
+      "id": "20260928000100_agent_board_ownerless_quota_renew_convergence",
+      "filename": "20260928000100_agent_board_ownerless_quota_renew_convergence.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 36921,
+      "sha256": "9982efff25378703a744187b15081b5cd53ab38fa6ac7d2950092a471780169e"
     }
   ],
   "excludedBridge": {