@consiliency/agent-board-schema 1.44.0 → 1.48.0

package/fixtures/already-applied.json

@@ -568,6 +568,22 @@
     {
       "id": "20260924000100_agent_board_agent_liveness_denominator",
       "sha256": "deb58ead6c4d7bbda686b85191d5eb2f2771ae2a405933ffbfbaabd7ad0117d9"
+    },
+    {
+      "id": "20260925000100_agent_board_ownerless_renew_ttl_cap",
+      "sha256": "da312f43cabf07c6dfd10dbe2a119fb46f49f24155e21adce4f38e291a38103c"
+    },
+    {
+      "id": "20260926000100_agent_board_ownerless_quota_census",
+      "sha256": "bbfabcb2d45cbcebd1e6e121032a1045e8406ea8763a784762a92d210e1e1043"
+    },
+    {
+      "id": "20260928000100_agent_board_ownerless_quota_renew_convergence",
+      "sha256": "9982efff25378703a744187b15081b5cd53ab38fa6ac7d2950092a471780169e"
+    },
+    {
+      "id": "20260927000100_agent_board_fleet_domain_no_downgrade",
+      "sha256": "ec5c4d89aff2d6d77d44cb3d00c1096b39010c6064c23d72eb3c5c354f8a5e74"
     }
   ]
 }

package/migrations/20260925000100_agent_board_ownerless_renew_ttl_cap.sql

@@ -0,0 +1,166 @@
+-- #373 — the ownerless TTL cap was ACQUIRE-ONLY, so the bound it advertises did not exist.
+--
+-- THE GAP, re-derived from the catalog rather than taken from the issue:
+--
+--   acquire_claim   guard=true   ttl_cap=true   quota=true
+--   renew_claim     guard=false  ttl_cap=false  quota=false
+--   release_claim   guard=false  ttl_cap=false  quota=false
+--
+-- `_claimgate_ownerless_ttl_cap()` (30 days) bounded an ownerless `file`/`tool`/`custom` lease at
+-- ACQUIRE and nowhere else. An agent could take a 30-day lease and renew it indefinitely, past the
+-- cap, forever. The duration bound was advertised and unenforced.
+--
+-- A COMMENT THAT DESCRIBED BEHAVIOUR THE CODE DID NOT HAVE. `_claimgate_ownerless_ttl_cap()` says
+-- ENFORCE "extends the horizon to renew for all non-task kinds". For the ownerless kinds it
+-- demonstrably did not — the ENFORCE rewrite (20260825000100) re-authorises and clamps only
+-- machine/repository/repo_file and says so in its own text. That is the shape AGENTS.md rule 5
+-- names: an intention written as a fact, which reads as true and is never re-checked.
+--
+-- CLAMP, NOT REJECT — and this differs from acquire deliberately. `acquire_claim` RAISES on an
+-- over-cap lease (22023): nothing is lost, the caller simply asks for less. A renew that raised
+-- would instead KILL A LIVE LEASE the agent is currently relying on, converting a length problem
+-- into an availability incident. Renew already resolves this the same way for the fleet-gated
+-- kinds — clamp to the horizon, and let an over-long legacy lease reconcile at its next renew --
+-- so the ownerless clamp mirrors renew's own idiom rather than acquire's.
+--
+-- SAME FOUR CONDITIONS AS ACQUIRE, so one flag governs both paths and a board that opted out of
+-- our locking is not clamped by it either:
+--   the kind is ownerless · not service_role · _claimgate_ownerless_guards_enabled()
+--   · the claim's board is not claim_policy='advisory'
+--
+-- WHAT THIS DOES NOT DO. The per-agent quota (50 concurrent ownerless claims) is untouched. It was
+-- never defeated by this gap — renewing does not increase an agent's claim count — and all three
+-- board seats on #369 converged on that independently. This closes the TTL half only.
+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_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, c.thread_id
+    into v_kind, v_key, v_thread_id
+    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;
+
+  -- 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;
+$$;
+
+-- The comment #373 called out as describing behaviour the code did not have. It now does.
+comment on function agent_board._claimgate_ownerless_ttl_cap() is
+  'Max lease horizon for an ownerless (file/tool/custom) claim: 30 days. Enforced at BOTH acquire '
+  '(which RAISES 22023 on an over-cap request) and renew (which CLAMPS, because raising would kill '
+  'a live lease the agent is relying on). #373 closed the renew half; before that this comment '
+  'claimed a horizon renew did not apply and a lease could be renewed past the cap forever. '
+  'Governed by _claimgate_ownerless_guards_enabled() on both paths, and skipped for a board whose '
+  'claim_policy is advisory.';
+
+-- Second stale comment, raised by a review seat: the flags table said this scope_key gates the
+-- ownerless guards "in acquire_claim", which was true when written and is not now. Same rule-5
+-- shape as the helper comment above -- a recorded fact that keeps asserting itself after the code
+-- moved. Corrected here rather than left for the next reader to disbelieve.
+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 the ownerless (file/tool/custom) guards on BOTH write '
+  'paths: the TTL cap + per-agent quota in acquire_claim, and the TTL clamp in renew_claim (#373 '
+  '-- before that the cap was acquire-only and a lease could be renewed past it forever). '
+  'Operator-managed (service_role); enabled only after the prod lease-length census.';

package/migrations/20260926000100_agent_board_ownerless_quota_census.sql

@@ -0,0 +1,268 @@
+-- #388 — the ownerless quota bounds NEW ACQUISITIONS but never CONVERGES an agent already over it.
+--
+-- THE PROPERTY, stated as the issue states it. `acquire_claim` enforces a per-agent ceiling of
+-- `_claimgate_ownerless_quota()` (50) concurrent active file/tool/custom claims. `renew_claim`
+-- does not, and #387 deliberately did not add it — that PR closed the TTL half only. So the quota
+-- is effective against GROWTH and not against PERSISTENCE: an agent already over it renews every
+-- one of its claims indefinitely and stays over, forever.
+--
+-- THREE WAYS AN AGENT IS ALREADY OVER, all real and none hypothetical:
+--   1. claims acquired while `ownerless_guards` was OFF — the flag defaults disabled and was
+--      flipped in production only recently (#369), so everything accumulated before the flip is
+--      grandfathered;
+--   2. claims acquired under a board that was `claim_policy = 'advisory'` and later set back to
+--      `inherit` — the acquire-time guard is skipped for an advisory board (20260922000100), but
+--      the resulting rows are counted by every LATER check;
+--   3. a quota value lowered after the fact.
+--
+-- ---------------------------------------------------------------------------
+-- WHAT THIS MIGRATION IS, AND THE THREE THINGS IT DELIBERATELY IS NOT
+-- ---------------------------------------------------------------------------
+--
+-- IT IS A READ-ONLY CENSUS. #388 step 3: "which agents are currently over quota on the live
+-- board". Nothing here writes, blocks, clamps or refuses.
+--
+-- IT IS NOT ENFORCEMENT, and that is a decision rather than an omission. Acquire refusing costs
+-- the caller nothing — it asked for a new claim and did not get it. Renew refusing would KILL A
+-- LIVE LEASE the agent is currently relying on, and if an agent is 10 over, the reasonable
+-- behaviour is not "fail 10 renews at random", it is a decision about WHICH claims lose (oldest
+-- first? least recently touched? notify the agent?). That is a product question nobody has
+-- answered. This is the instrument that informs it. Enforcement, if it is chosen, additionally
+-- needs the agent-scoped `pg_advisory_xact_lock` acquire already takes plus a two-session
+-- isolationtester case (#137's harness), because two concurrent renews must not both observe room.
+--
+-- IT IS NOT A SCRIPT, and the alternative was considered rather than skipped. A `scripts/*.mjs`
+-- check with the house 0/1/2 exit contract answers a question about whatever database it is
+-- pointed at; the population that matters is PRODUCTION, and the operator path to production is
+-- `service_role` SQL through the Management API, where a view and a function are directly
+-- readable and a Node script is not runnable at all. A CI invocation would examine an empty
+-- freshly-built database and report "0 of 0" — true, and worthless. And an exit code is a GATE:
+-- 1 means "fail the build", which presumes a policy about what an over-quota agent should cause
+-- to happen. #388 explicitly defers that policy, so there is nothing yet for a non-zero exit to
+-- mean. When the convergence policy exists, a script that gates on this view is the natural next
+-- artifact; it is not this one.
+--
+-- ---------------------------------------------------------------------------
+-- THE NUMERATOR IS ACQUIRE'S OWN COUNT PREDICATE, VERBATIM
+-- ---------------------------------------------------------------------------
+-- A census whose arithmetic differs from the enforcer's is a census about a different question,
+-- and it would be silently wrong rather than visibly wrong. The count below is copied from the
+-- quota block of the CURRENT `acquire_claim` (20260922000100 — note that migration re-creates it
+-- from a `pg_get_functiondef` dump in UPPERCASE, so a lowercase grep for the definer finds
+-- 20260914000100 and reads the wrong body):
+--
+--     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()
+--
+-- NO BOARD-POLICY FILTER, and this is the subtle one. The advisory board opt-out gates WHETHER
+-- the guard runs for the acquisition being attempted; it does not exclude the resulting rows from
+-- the count. So an agent's 60 claims count as 60 even if 20 of them were taken on advisory
+-- boards. Filtering them out here would produce a smaller, friendlier, WRONG number that does not
+-- predict what acquire does. Stated operationally, a row in this view with `acquire_blocked` true
+-- means: this agent's next ownerless acquire, on an `inherit` board, with the guards on, raises
+-- 54000.
+--
+-- `claims_on_advisory_boards` is reported as a SEPARATE column precisely because it is the thing
+-- the convergence decision needs and the thing the headline count must not absorb — refusing a
+-- claim that another board's own lock already granted is us breaking a promise, so an operator
+-- weighing "which claims lose" needs to see that share without it distorting the ceiling test.
+--
+-- OVERAGE AND ACQUIRE_BLOCKED ARE DIFFERENT NUMBERS AND BOTH ARE REPORTED. Acquire refuses at
+-- `count >= quota`, so an agent holding exactly 50 is already frozen while being over by nothing.
+--   * `overage`         = greatest(count - quota, 0) — how many claims exceed the ceiling. This is
+--                         the convergence question: what would have to be given up.
+--   * `acquire_blocked` = count >= quota — acquire's refusal predicate, verbatim. This is the
+--                         "why can my agent not take a lock" question.
+-- Collapsing them into one boolean would answer one of those two questions wrongly.
+--
+-- ---------------------------------------------------------------------------
+-- THE DENOMINATOR IS NOT OPTIONAL
+-- ---------------------------------------------------------------------------
+-- The live answer today is expected to be ZERO agents over quota. A reader that emits "0
+-- offenders" and nothing else is byte-identical whether it examined 400 agents or examined
+-- nothing at all — which is exactly the defect #367 shipped a migration to close, where
+-- `v_ops_presence_heartbeats` returned zero rows about an entirely unmonitored fleet and read as
+-- perfect health. So `ownerless_quota_census()` always emits its population alongside its finding:
+--
+--     0 over quota, of 12 agents holding ownerless claims, across 47 active agents
+--
+-- and it additionally emits `guards_enabled` and `quota`, so the output states the REGIME it
+-- measured under. "0 over quota" with `guards_enabled = false` is a materially different fact
+-- from the same number with the flag on, and a reader that reports the count without the flag
+-- invites exactly the rule-5 misreading — a true statement about a moment, still asserting itself
+-- after the moment moved.
+--
+-- ---------------------------------------------------------------------------
+-- The view. `security_invoker` matching every other view in agent_board; the grant below is what
+-- actually confines it, and the two are not redundant (see the grant comment).
+-- ---------------------------------------------------------------------------
+create or replace view agent_board.v_ownerless_claim_quota
+with (security_invoker = true)
+as
+with holders as (
+  select
+    c.agent_id                                                       as agent_id,
+    count(*)::integer                                                as active_ownerless_claims,
+    -- The advisory share, resolved per claim through its OWN thread. A claim with no thread, or a
+    -- thread with no board, resolves to 'inherit' by the helper's own contract — so absence never
+    -- reads as an opt-out here either.
+    count(*) filter (
+      where agent_board._claimgate_board_claim_policy(c.thread_id) = 'advisory'
+    )::integer                                                       as claims_on_advisory_boards,
+    count(*) filter (where c.resource_kind = 'file')::integer        as file_claims,
+    count(*) filter (where c.resource_kind = 'tool')::integer        as tool_claims,
+    count(*) filter (where c.resource_kind = 'custom')::integer      as custom_claims,
+    min(c.created_at)                                                as oldest_claim_at,
+    max(c.created_at)                                                as newest_claim_at,
+    max(c.lease_expires_at)                                          as latest_lease_expires_at
+  from agent_board.claims c
+  -- ACQUIRE'S PREDICATE, VERBATIM. Every conjunct is load-bearing and each has a near-miss row in
+  -- the pgTAP fixture: a released claim, an expired-status claim, a lapsed-lease claim, and an
+  -- owned-kind claim all sit next to the counted ones so that dropping any conjunct here fails a
+  -- named assertion rather than passing quietly.
+  where c.resource_kind in ('file', 'tool', 'custom')
+    and c.status = 'active'
+    and c.released_at is null
+    and c.lease_expires_at > now()
+  group by c.agent_id
+)
+select
+  h.agent_id,
+  -- Identity sufficient to ACT on the row without a second query: who to contact, and whether the
+  -- agent is even still in service. `status` is REPORTED, never filtered on — a suspended agent
+  -- holding 60 live leases is precisely the row an operator most needs to see, and a
+  -- `status = 'active'` filter here would hide it.
+  a.handle                                                           as agent_handle,
+  a.display_name                                                     as agent_display_name,
+  a.status                                                           as agent_status,
+  h.active_ownerless_claims,
+  agent_board._claimgate_ownerless_quota()                           as quota,
+  greatest(h.active_ownerless_claims - agent_board._claimgate_ownerless_quota(), 0)::integer
+                                                                     as overage,
+  (h.active_ownerless_claims >= agent_board._claimgate_ownerless_quota())
+                                                                     as acquire_blocked,
+  h.claims_on_advisory_boards,
+  h.file_claims,
+  h.tool_claims,
+  h.custom_claims,
+  h.oldest_claim_at,
+  h.newest_claim_at,
+  h.latest_lease_expires_at
+from holders h
+join agent_board.agents a on a.id = h.agent_id;
+
+comment on view agent_board.v_ownerless_claim_quota is
+  '#388 read-only census: one row per agent HOLDING at least one active ownerless (file/tool/'
+  'custom) claim, with its count, the quota, and the overage. The count is acquire_claim''s own '
+  'quota predicate verbatim (kind in file/tool/custom, status active, released_at null, lease '
+  'unexpired) with NO board-policy filter, because the advisory opt-out gates whether the guard '
+  'RUNS for an acquisition, not whether the resulting rows COUNT — so acquire_blocked (count >= '
+  'quota) predicts acquire''s 54000 exactly. overage (count - quota, floored at 0) is the '
+  'different question of how many claims exceed the ceiling; an agent at exactly the quota is '
+  'blocked while over by nothing. claims_on_advisory_boards is reported separately because it '
+  'informs the convergence decision without distorting the ceiling test. agent_status is reported '
+  'and never filtered: a suspended agent holding live leases is the row that matters most. '
+  'REPORT-ONLY — nothing here refuses, clamps or converges anything; see #388 for why refusing a '
+  'renew is a product decision and not a clamp. Read agent_board.ownerless_quota_census() FIRST '
+  'for the denominator. security_invoker, service_role only.';
+
+-- ---------------------------------------------------------------------------
+-- The summary. Its only job is to make an empty result impossible to misread.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board.ownerless_quota_census()
+returns table(
+  guards_enabled                  boolean,
+  quota                           integer,
+  agents_active                   integer,
+  agents_holding_ownerless_claims integer,
+  agents_over_quota               integer,
+  agents_acquire_blocked          integer,
+  total_active_ownerless_claims   integer,
+  total_overage                   integer
+)
+language sql
+stable
+security invoker
+set search_path = agent_board, public
+as $$
+  select
+    -- The REGIME first: a count without the flag that governs it is a rule-5 fact with no
+    -- expiry. "0 over quota" means something different when the guards are off.
+    agent_board._claimgate_ownerless_guards_enabled()                       as guards_enabled,
+    agent_board._claimgate_ownerless_quota()                                as quota,
+    -- The widest denominator: the fleet. Non-zero even when NOBODY holds an ownerless claim, so
+    -- "0 of 0" can still be distinguished from "0 of 0, of 0" — a database this reader cannot
+    -- see into at all.
+    (select count(*)::integer from agent_board.agents where status = 'active')
+                                                                            as agents_active,
+    -- The population actually examined. THIS is the number that makes a zero finding meaningful.
+    -- It is counted from the view directly and NOT derived from the offender set — deriving it
+    -- would make it 0 exactly when the finding is 0, which is the vacuous shape this exists to
+    -- prevent.
+    (select count(*)::integer from agent_board.v_ownerless_claim_quota)
+                                                                            as agents_holding_ownerless_claims,
+    (select count(*) filter (where overage > 0)::integer
+       from agent_board.v_ownerless_claim_quota)                            as agents_over_quota,
+    (select count(*) filter (where acquire_blocked)::integer
+       from agent_board.v_ownerless_claim_quota)                            as agents_acquire_blocked,
+    (select coalesce(sum(active_ownerless_claims), 0)::integer
+       from agent_board.v_ownerless_claim_quota)                            as total_active_ownerless_claims,
+    (select coalesce(sum(overage), 0)::integer
+       from agent_board.v_ownerless_claim_quota)                            as total_overage;
+$$;
+
+comment on function agent_board.ownerless_quota_census() is
+  '#388 denominator. Returns agents_holding_ownerless_claims and agents_active ALONGSIDE '
+  'agents_over_quota, so "0 over quota" can never be rendered as "all clear" — 0 over, of 0 '
+  'holders, across 47 active agents, is a reader that examined nothing, and it reads as one '
+  '(the #367 defect shape). Also emits guards_enabled and quota so the output states the regime '
+  'it measured under. agents_holding_ownerless_claims is counted from the view, NOT derived from '
+  'the offender set: a denominator that collapses to 0 exactly when the finding is 0 proves '
+  'nothing. agents_over_quota counts overage > 0; agents_acquire_blocked counts count >= quota, '
+  'which is acquire_claim''s refusal predicate and is the strictly larger set. '
+  'security invoker + stable: a projection of v_ownerless_claim_quota, inheriting the caller''s '
+  'RLS.';
+
+-- ---------------------------------------------------------------------------
+-- SERVICE_ROLE ONLY, and this is the most important statement in the file.
+--
+-- `security_invoker` does not make an `authenticated` grant safe here; it makes it dangerous, and
+-- for the mirror-image reason #367 found. The RLS SELECT policy on `agent_board.claims` is:
+--
+--     agent_id = current_agent_id()
+--     or exists (select 1 from tasks t where t.id = task_id
+--                 and (t.created_by_agent_id = current_agent_id()
+--                      or t.assigned_agent_id = current_agent_id()))
+--
+-- so an authenticated caller can see essentially ITS OWN claims. Read by that caller this view
+-- returns one row — itself — and the census reports `agents_holding_ownerless_claims = 1`,
+-- `agents_over_quota = 0`. Not an error, not an empty result: a confident, plausible, fleet-shaped
+-- answer that is wrong, and wrong in the reassuring direction. Two agents would get two different
+-- censuses with no way to tell which was right, and the one that mattered — the agent sitting at
+-- 60 claims — would be invisible to everyone except itself.
+--
+-- #367 hit this as OVER-reporting (a LEFT JOIN turned "hidden from you" into an alarm). Here the
+-- join is an inner aggregate, so it is UNDER-reporting, which is worse for a census whose whole
+-- purpose is to find the outliers: over-reporting is noisy and gets investigated, under-reporting
+-- is silence with a denominator attached to make it look diligent.
+--
+-- An authenticated agent cannot answer "who in the fleet is over quota" at all, because it cannot
+-- see anyone else's claims. That is the RLS model working, not a gap here, and the honest response
+-- is to withhold the surface rather than serve a per-caller answer that reads fleet-wide. Quota
+-- convergence is an operations question and this is an operations surface.
+--
+-- `security_invoker` is kept anyway as defence in depth: if a future migration widens the grant,
+-- rows are still RLS-filtered rather than leaked wholesale. OQ-8/OQ-9 pin both the view option and
+-- the grant so widening either fails a test that says why.
+-- ---------------------------------------------------------------------------
+grant select on agent_board.v_ownerless_claim_quota to service_role;
+
+-- NOT REDUNDANT — this is the AL-9b trap from #367, which arrives on a plain
+-- `create or replace function` and not only on a DROP. A newly created function is granted
+-- EXECUTE to PUBLIC by default, so `authenticated` inherits it through PUBLIC and granting only
+-- service_role above would change nothing on its own.
+revoke all on function agent_board.ownerless_quota_census() from public;
+grant execute on function agent_board.ownerless_quota_census() to service_role;