@consiliency/agent-board-schema 1.48.0 → 1.51.0

package/migrations/20261001000100_agent_board_claimpolicy_lock_grant_revoke.sql

@@ -0,0 +1,158 @@
+-- Consiliency/message-board#405 — the board policy lock helper is granted to NOBODY.
+--
+-- WHAT THIS CLOSES, measured rather than argued. 20260930000100 revoked
+-- `_claimgate_lock_board_policy` from public/anon/authenticated and GRANTED it to `service_role`,
+-- on the reasoning (stated in its own comment) that the serialisation "cannot be reached from a
+-- session". `service_role` IS a session role. With that grant in place a single service_role
+-- transaction assembles the exact inversion claimpolicy_claimrow_lock_order.spec constructs by
+-- hand:
+--
+--   BEGIN;  select agent_board.renew_claim(<token>, …);      -- claims ROW LOCK, no board lock
+--           select agent_board._claimgate_lock_board_policy(<board>);   -- board lock, AFTER it
+--
+-- and a concurrent `set_board_claim_policy` on that board (board lock, then #400's cap-reset
+-- UPDATE onto the row session 1 holds) closes the cycle. Reproduced against this bundle as
+-- `ERROR: deadlock detected` before this migration existed.
+--
+-- WHY renew_claim STILL TAKES THE ROW LOCK FOR service_role, which is the part that makes the
+-- composition work: its `update agent_board.claims` sits OUTSIDE the ownerless block, so
+-- `_is_service_role()` short-circuits the BOARD lock while the ROW lock is taken regardless. The
+-- caller therefore holds a claims row lock and no board lock — precisely the state the inversion
+-- needs — and only needs one more granted call to want the board lock.
+--
+-- WHY REVOKING IS SAFE, derived from the catalog rather than assumed. The helper is NOT
+-- `SECURITY DEFINER`; its three callers (`acquire_claim`, `renew_claim`, `set_board_claim_policy`)
+-- ARE, and are owned by the same role that owns the helper. A SECURITY DEFINER function executes
+-- as its owner, and an owner needs no grant on its own function, so the definer path is unaffected
+-- by any grant at all. CPR-22 asserts the empty ACL; CPR-22a asserts the definer path still
+-- reaches the lock AND that the advisory lock is genuinely held afterwards, so the negative cannot
+-- pass by the enforcement having been taken offline.
+--
+-- NOTHING CALLS IT DIRECTLY. Derived from the tree on this branch, not from a live database: the
+-- only references to `_claimgate_lock_board_policy` outside its defining migration are in this
+-- package's pgTAP file, the isolation-spec COMMENTS, and the p_metadata catalog snapshot. No
+-- TypeScript package (client/cli/mcp/runtime) and no Edge Function names it, in any casing.
+--
+-- WHY A NEW MIGRATION RATHER THAN EDITING 20260930000100's GRANT LINE. That migration is this
+-- PR's own and still unmerged, so amending it would be tidier history — but this repository cannot
+-- prove that no database has already applied it (the canary project tracks this branch), and a
+-- bundle is replayed by digest rather than re-derived. A forward revoke is correct whether or not
+-- the grant was ever applied, and `revoke` on an absent grant is a no-op. Replay-safe either way.
+--
+-- NOT `DROP FUNCTION`: that would discard the ACL *and* the COMMENT and re-grant EXECUTE to PUBLIC
+-- by default (AGENTS.md, "Schema-change mechanics that bite"). The function body is unchanged here;
+-- only its ACL and its comment move.
+
+-- THE REVOKE IS DERIVED, ACROSS EVERY OVERLOAD, AND CASCADES. Three separate holes closed here,
+-- each of which would leave this migration's own comment asserting something false:
+--
+-- 1. NAMED ROLES ARE A HAND LIST. `revoke ... from public, anon, authenticated, service_role`
+--    leaves a grant to any fifth role standing. That is not hypothetical bookkeeping — this bundle
+--    is REPLAYED ONTO ADOPTER DATABASES we do not control, where an operator may have granted this
+--    helper to a role we have never heard of.
+--
+-- 2. ONE SIGNATURE IS A HAND LIST TOO. Keying the sweep to `(uuid)` lets a `(text)` overload carry
+--    a grant straight through it. The property wanted is about the NAME: nothing in agent_board
+--    called _claimgate_lock_board_policy should be executable by a non-owner, whatever its
+--    argument types. Every overload is swept.
+--
+-- 3. `REVOKE` DEFAULTS TO `RESTRICT`, AND RESTRICT FAILS ON A DEPENDENT GRANT. If a grantee holds
+--    EXECUTE **WITH GRANT OPTION** and has granted it onward, a plain REVOKE ERRORS ("dependent
+--    privileges exist") — and on an adopter database that is a FAILED MIGRATION, not a tidier ACL,
+--    with the empty ACL not achieved either. `CASCADE` is chosen deliberately over enumerating
+--    dependencies: the whole claim of this migration is that NOTHING non-owner holds EXECUTE, so a
+--    downstream grant is exactly as unwanted as the grant it hangs from, and handling dependencies
+--    individually would only reach the same end state by a longer route. Stated rather than
+--    slipped in, because CASCADE silently removes grants a third party made: an operator who
+--    deliberately delegated this helper onward will find that delegation gone after upgrading.
+--    That is the intended outcome — the helper is not meant to be reachable from any session — but
+--    it is a real effect on someone else's database and belongs in the record.
+--
+-- 4. `ON FUNCTION` IS THE WRONG VERB FOR A ROUTINE, AND RAISES. The scan above selects by NAME,
+--    which admits any pg_proc row — a legal same-name PROCEDURE or AGGREGATE included. `REVOKE …
+--    ON FUNCTION` against a procedure fails with `is not a function`, and it would fail at the
+--    MATERIALISATION statement, before the sweep runs at all: a second adopter-upgrade abort from
+--    the same source as the RESTRICT one, a query written for functions applied to routines.
+--    Measured on this bundle: `on function` against a procedure errors, `on routine` succeeds
+--    against a procedure AND an aggregate. So both statements say ROUTINE and there is no prokind
+--    filter — operating on routines consistently is the choice, rather than narrowing the scan to
+--    prokind='f' and leaving a same-name procedure's grant standing. Window functions ('w') cannot
+--    be created without C-level support and are untested here; ROUTINE is the widest verb available
+--    and no narrower verb would cover more.
+--
+-- The OWNER is excluded throughout: EXECUTE is implicit in ownership, cannot be revoked, and is
+-- exactly the path the three SECURITY DEFINER callers use.
+--
+-- A missing function RAISES rather than silently sweeping nothing: this migration exists to
+-- establish an ACL, and doing that to a function that is not there is a failure, not a success.
+-- Likewise an unresolvable grantee OID. Both differ from CPR-22, which RENDERS those cases instead
+-- — a raise inside a pgTAP assertion aborts the file and emits no `not ok`, whereas here failing
+-- closed is right, because skipping silently would leave a live grant standing.
+do $$
+declare
+  v_overloads int := 0;
+  v_who       text;
+  f           record;
+  r           record;
+begin
+  for f in
+    select p.oid, p.oid::regprocedure::text as sig
+      from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+     where n.nspname = 'agent_board'
+       and p.proname = '_claimgate_lock_board_policy'
+  loop
+    v_overloads := v_overloads + 1;
+
+    -- MATERIALISE THE ACL FIRST. While `proacl` is NULL the function carries DEFAULT privileges,
+    -- and the default for a function is EXECUTE to PUBLIC — but aclexplode(NULL) yields no rows,
+    -- so the sweep below would find nothing to revoke on a database where no grant was ever
+    -- written explicitly. This statement both removes that implicit PUBLIC grant and populates
+    -- proacl so the sweep can see the rest.
+    execute format('revoke all on routine %s from public cascade', f.sig);
+
+    for r in
+      select distinct a.grantee
+        from pg_proc p, aclexplode(p.proacl) a
+       where p.oid = f.oid
+         and a.privilege_type = 'EXECUTE'
+         and a.grantee <> p.proowner
+    loop
+      if r.grantee = 0 then
+        v_who := 'public';
+      else
+        select quote_ident(rolname) into v_who from pg_roles where oid = r.grantee;
+      end if;
+      if v_who is null then
+        raise exception
+          'EXECUTE grantee % on % has no pg_roles row — cannot revoke it, and reporting an empty ACL would be false',
+          r.grantee, f.sig
+          using errcode = '42704';
+      end if;
+      execute format('revoke all on routine %s from %s cascade', f.sig, v_who);
+    end loop;
+  end loop;
+
+  if v_overloads = 0 then
+    raise exception
+      'no function named agent_board._claimgate_lock_board_policy — refusing to report an empty ACL for a function that does not exist'
+      using errcode = '42883';
+  end if;
+end $$;
+
+-- The comment 20260930000100 attached asserts the service_role grant this migration removes, and
+-- cites CPR-14 for the ACL — CPR-14 is the claims row-lock class assertion; CPR-22 is the ACL one.
+-- Both corrected here, in the same migration that makes the first sentence true.
+comment on function agent_board._claimgate_lock_board_policy(uuid) is
+  '#405: the board-scoped serialisation point for claim policy. Takes a pg_advisory_xact_lock on '
+  'hashtextextended(''agent_board.board_claim_policy:''||board_id) so set_board_claim_policy''s '
+  'flip and every ownerless enforcement decision on that board are totally ordered, and RAISES '
+  '0A000 unless transaction_isolation is ''read committed'' — under repeatable read or '
+  'serializable the wait does not advance the caller''s snapshot, so the lock would be silently '
+  'ineffective; under read uncommitted the lock still works (PostgreSQL runs it as read '
+  'committed) and the refusal is a deliberate one-accepted-spelling contract rather than a '
+  'correctness requirement. A null board is isolation-checked and takes no lock. '
+  'EXECUTE is granted to NO role (#405 follow-up): the helper is not SECURITY DEFINER, its three '
+  'callers are and share its owner, so they reach it by ownership. The grant that existed briefly '
+  'let a service_role session compose renew_claim''s claims row lock with a direct call to this '
+  'helper and deadlock against the policy writer. CPR-22 pins the empty ACL; CPR-22a pins that '
+  'the definer path still works.';

package/migrations/20261002000100_agent_board_session_challenge_supersede.sql

@@ -0,0 +1,383 @@
+-- F1 (code-review-2026-09-01): the per-key pending-challenge cap was a lockout lever.
+--
+-- THE DEFECT. `/session` step "challenge" is verify_jwt=false: it needs only an agent
+-- handle and a key id, both directory-visible, and each request inserts a challenge row
+-- through service_role. `issue_signing_key_challenge` capped pending challenges at 16
+-- per KEY and RAISED `challenge_pending_cap` at the cap. So any caller who could reach
+-- the endpoint could hold a victim's sixteen slots with one request every five minutes;
+-- every legitimate challenge for that key then failed. The client turned the 403 into a
+-- non-retryable SessionError and STOPPED its background refresh loop, so the outage
+-- outlived the flood and needed a restart to clear. The same shape occurred by accident
+-- after sixteen crashed mints inside one five-minute challenge lifetime.
+--
+-- THE CHANGE. Forward-only `create or replace` of two functions, both reproducing their
+-- current body verbatim with one edit each:
+--
+--   1. issue_signing_key_challenge — at the cap, SUPERSEDE the oldest pending challenge
+--      and issue, instead of refusing. The resource bound is unchanged (at most 16
+--      pending rows per key, still); what changes is that arrival is never refused.
+--   2. mint_fleet_agent_session — report a superseded challenge as `challenge_superseded`
+--      rather than `nonce_replay`, so an eviction is retryable without teaching a client
+--      to retry through a genuine replay.
+--
+-- WHY SUPERSEDE RATHER THAN NARROW THE CAP. The cap's purpose is to bound rows per key;
+-- refusing was how it was spelled, not what it was for. Making the cap per-source instead
+-- does NOT close this: sixteen requests over five minutes fit under any per-source limit
+-- a real fleet can use, and a caller with several sources is not bounded per key at all.
+-- The per-source rate cap added to the handler in this same change bounds the COST of
+-- driving the queue; superseding is what removes the denial.
+--
+-- WHAT IS CLOSED, AND THE RESIDUAL THAT IS NOT. What this closes is the HOLDABLE lockout:
+-- fill-and-walk-away no longer denies anything, and an outage can no longer outlive the
+-- attack. What it does NOT close is eviction under a SUSTAINED flood. A challenge is the
+-- NEWEST of its key when issued, so sixteen later issues rotate it out and its mint then
+-- raises challenge_superseded. Per source that is bounded by the `session:` rate cap;
+-- IN AGGREGATE IT IS UNBOUNDED, because a per-key aggregate bound is precisely the
+-- holdable lever this migration removes -- the two cannot both exist. N sources rotate the
+-- queue in 1/N of the per-source time, so a minter loses its challenge once its
+-- issue->mint gap exceeds ~32/N seconds at the default 30/min.
+--
+-- That residual is DoS-class, not stored state: it costs the attacker continuous traffic and
+-- stops when the traffic stops. NOTE WHAT IS NOT CLAIMED: "the victim's recovery is one
+-- retry" is true of a ONE-SHOT evictor (driven end-to-end by F1-F in
+-- session.integration.test.ts) and NOT of a sustained flood, where the retry re-enters on
+-- the same odds and the retry count is geometric in the ratio of the client's issue->mint
+-- window W to the flood's rotation period. W is asserted NOWHERE here and is dominated by
+-- the signer -- an OS-keychain prompt makes it seconds, at which point a handful of sources
+-- suffices. An earlier version of this header stated the one-retry recovery flatly.
+-- It is pinned by assertions 19-20 of
+-- agent_board_signing_challenge_pending_cap.test.sql rather than left as prose, because a
+-- sentence is not re-checked (rule 5). ACCEPTED FOR THIS RELEASE AND TRACKED BY
+-- message-board#423, which owns whether an eventual-progress mechanism is wanted; this
+-- migration deliberately does not attempt one. An earlier version of this header called the race
+-- "rate-bounded in attempts": true per source, FALSE in aggregate. Deleted rather than
+-- softened -- it was the sentence that was wrong.
+--
+-- `create or replace` preserves both functions' ACLs; both are restated below anyway,
+-- with their COMMENTs, because a SECURITY DEFINER function grants EXECUTE to PUBLIC by
+-- default and this file must be self-contained if either is ever dropped and re-run.
+
+create or replace function agent_board.issue_signing_key_challenge(
+  p_agent_id uuid,
+  p_key_id text,
+  p_expires_in interval default interval '5 minutes'
+)
+returns table (
+  challenge_id uuid,
+  agent_id uuid,
+  key_id text,
+  key_version integer,
+  fingerprint text,
+  challenge text,
+  expires_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid;
+  v_key agent_board.agent_signing_keys%rowtype;
+  v_challenge_id uuid := gen_random_uuid();
+  v_nonce text := encode(extensions.gen_random_bytes(24), 'base64');
+  v_expires_at timestamptz;
+  v_pending integer;
+  v_evicted uuid;
+  -- Frozen pending-challenge cap per signing key (IF-0-MBHARDEN-1a). N=16.
+  c_pending_cap constant integer := 16;
+begin
+  if p_expires_in is null or p_expires_in <= interval '0 seconds' or p_expires_in > interval '15 minutes' then
+    raise exception 'challenge expiry must be between 0 and 15 minutes' using errcode = '22023';
+  end if;
+
+  v_actor := agent_board._resolved_actor_agent_id(p_agent_id, 'p_agent_id');
+
+  select *
+    into v_key
+    from agent_board.agent_signing_keys ask
+   where ask.agent_id = v_actor
+     and ask.key_id = p_key_id
+   for update;
+
+  if not found then
+    raise exception 'signing key not found' using errcode = 'P0002';
+  end if;
+  if v_key.status in ('revoked', 'compromised') then
+    raise exception 'key_revoked: signing key is revoked' using errcode = '22023';
+  end if;
+  if v_key.expires_at is not null and v_key.expires_at <= now() then
+    update agent_board.agent_signing_keys
+       set status = 'expired',
+           proof_state = 'expired',
+           updated_at = now()
+     where id = v_key.id;
+    raise exception 'key_expired: signing key is expired' using errcode = '22023';
+  end if;
+
+  -- Pending-challenge cap: at most N=16 unexpired, unconsumed, still-pending
+  -- challenges per key. Serialized by the `for update` above, so the count is
+  -- race-free and the eviction below cannot double-fire.
+  --
+  -- AT THE CAP THIS SUPERSEDES, IT DOES NOT REFUSE (review finding F1). The
+  -- previous behaviour raised challenge_pending_cap, which made a per-key RESOURCE
+  -- BOUND into a per-key LOCKOUT LEVER: /session step "challenge" is
+  -- verify_jwt=false and needs only a directory-visible handle and key id, so any
+  -- caller could hold all sixteen slots with one request every five minutes and the
+  -- key's legitimate owner could never obtain a challenge again. The client turned
+  -- the resulting 403 into a non-retryable error and stopped its refresh loop, so
+  -- the outage outlived the flood.
+  --
+  -- WHAT SUPERSEDING COSTS. It creates an eviction the refusal did not have: sixteen
+  -- later issues rotate any pending challenge out, so a sustained flood evicts a slow
+  -- minter for as long as it runs. Bounded per source by the `session:` rate cap,
+  -- UNBOUNDED in aggregate -- an aggregate per-key bound is the holdable lever this
+  -- removes. DoS-class rather than stored state: it stops when the traffic stops, and
+  -- the consequence is one retry rather than a stopped client. Pinned by assertions
+  -- 19-20 of agent_board_signing_challenge_pending_cap.test.sql.
+  --
+  -- The eviction is deliberately made LOUD instead of
+  -- cheap: the row is marked (below) and mint_fleet_agent_session reports
+  -- challenge_superseded, distinct from the nonce_replay a genuine replay raises, so
+  -- the client can retry the one without learning to ignore the other.
+  --
+  -- WHY OLDEST. The oldest pending challenge is the one most likely to be abandoned,
+  -- and taking it puts a freshly-issued challenge LAST in the eviction order — a
+  -- challenge is minted within milliseconds of issue, so the legitimate flow is the
+  -- one this ordering protects. `order by created_at` with `id` as the tiebreak keeps
+  -- the choice deterministic when two rows share a timestamp.
+  --
+  -- WHY `SKIP LOCKED`, WHICH IS NOT OPTIONAL. This function holds a FOR UPDATE on the
+  -- agent_signing_keys row and then writes an agent_signing_key_challenges row;
+  -- mint_fleet_agent_session takes those two in the OPPOSITE order (challenge row FOR
+  -- UPDATE at 20260718000600:73-76, then key row FOR UPDATE at :95-100). A plain
+  -- eviction would therefore deadlock against a concurrent mint of the very row being
+  -- evicted — an ABBA this change would have INTRODUCED, and exactly the traffic it
+  -- makes common: floods driving evictions while legitimate agents mint. SKIP LOCKED
+  -- removes the cycle by never waiting: a challenge row a mint already holds is passed
+  -- over for the next-oldest. It also happens to be the kinder choice, since the row a
+  -- mint is holding is the one row we most want not to evict. The pair is pinned as a
+  -- class by agent_board_fk_lock_edges.test.sql FKL-10, which named this inversion when
+  -- the first version of this migration omitted the clause.
+  select count(*)
+    into v_pending
+    from agent_board.agent_signing_key_challenges c
+   where c.signing_key_id = v_key.id
+     and c.proof_state = 'pending'
+     and c.consumed_at is null
+     and c.expires_at > now();
+
+  if v_pending >= c_pending_cap then
+    update agent_board.agent_signing_key_challenges
+       set proof_state = 'expired',
+           consumed_at = now(),
+           updated_at = now(),
+           metadata = metadata || jsonb_build_object(
+             'superseded_at', now(),
+             'superseded_by', v_challenge_id
+           )
+     where id = (
+       select c.id
+         from agent_board.agent_signing_key_challenges c
+        where c.signing_key_id = v_key.id
+          and c.proof_state = 'pending'
+          and c.consumed_at is null
+          and c.expires_at > now()
+        order by c.created_at, c.id
+        for update skip locked
+        limit 1
+     )
+    returning id into v_evicted;
+
+    -- No evictable row. Under SKIP LOCKED this is reachable without the bound being
+    -- wrong: every one of the sixteen pending rows can be row-locked by a concurrent
+    -- mint of that same key. Issuing anyway would grow the pending set past the cap,
+    -- so refuse — the pre-change behaviour, now confined to a window in which sixteen
+    -- mints for one key are in flight at once, and retryable at the client rather than
+    -- terminal. ('expired'/consumed_at is the same closed-out shape the consumed-shape
+    -- CHECK requires, and reuses the existing proof_state vocabulary rather than adding
+    -- a value; the metadata marker is what distinguishes an eviction from a lapse.)
+    if v_evicted is null then
+      raise exception 'challenge_pending_cap: too many pending signing-key challenges for this key (max %)', c_pending_cap
+        using errcode = '22023';
+    end if;
+  end if;
+
+  v_expires_at := now() + p_expires_in;
+
+  insert into agent_board.agent_signing_key_challenges(
+    id,
+    signing_key_id,
+    agent_id,
+    challenge_nonce,
+    challenge_bytes,
+    expires_at,
+    metadata
+  )
+  values (
+    v_challenge_id,
+    v_key.id,
+    v_actor,
+    v_nonce,
+    'agent-signing-key-proof.v1:' || v_challenge_id::text || ':' || v_nonce,
+    v_expires_at,
+    jsonb_build_object('keyId', v_key.key_id, 'keyVersion', v_key.key_version)
+  );
+
+  update agent_board.agent_signing_keys
+     set proof_state = 'challenge_issued',
+         updated_at = now()
+   where id = v_key.id
+     and proof_state <> 'proven';
+
+  return query
+  select
+    v_challenge_id,
+    v_actor,
+    v_key.key_id,
+    v_key.key_version,
+    v_key.fingerprint,
+    'agent-signing-key-proof.v1:' || v_challenge_id::text || ':' || v_nonce,
+    v_expires_at;
+end;
+$$;
+comment on function agent_board.issue_signing_key_challenge(uuid, text, interval) is
+  'Issues a one-time PoP challenge for an agent signing key. Bounds the key to at most 16 concurrently-pending challenges; AT the bound it supersedes the OLDEST pending challenge (proof_state=''expired'', consumed_at set, metadata.superseded_by naming the new challenge) and issues, rather than refusing — refusing made the bound a lockout lever on the unauthenticated /session surface (F1). Serialized by the FOR UPDATE on the key row. authenticated + service_role.';
+
+revoke all on function agent_board.issue_signing_key_challenge(uuid, text, interval) from public, anon;
+grant execute on function agent_board.issue_signing_key_challenge(uuid, text, interval) to authenticated, service_role;
+
+create or replace function agent_board.mint_fleet_agent_session(
+  p_challenge_id uuid,
+  p_nonce text,
+  p_signing_key_id uuid,
+  p_agent_id uuid,
+  p_max_ttl_seconds integer default 900
+)
+returns table(session_id text, expires_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_challenge agent_board.agent_signing_key_challenges%rowtype;
+  v_key agent_board.agent_signing_keys%rowtype;
+  v_auth_user_id uuid;
+  v_parent_agent_id uuid;
+  v_ttl integer := least(coalesce(p_max_ttl_seconds, 900), 900);
+  v_session_id text := 'fas_' || replace(gen_random_uuid()::text, '-', '');
+  v_expires_at timestamptz;
+begin
+  if v_ttl <= 0 then
+    raise exception 'max_ttl_seconds must be positive' using errcode = '22023';
+  end if;
+
+  -- (i) challenge: exists, bound to this agent + signing key, unconsumed, unexpired.
+  select * into v_challenge
+    from agent_board.agent_signing_key_challenges c
+   where c.id = p_challenge_id
+   for update;
+  if not found then
+    raise exception 'signing key challenge not found' using errcode = 'P0002';
+  end if;
+  if v_challenge.agent_id <> p_agent_id or v_challenge.signing_key_id <> p_signing_key_id then
+    raise exception 'actor_mismatch: challenge is not bound to this agent and signing key' using errcode = '42501';
+  end if;
+  -- An EVICTED challenge is not a replayed one. issue_signing_key_challenge closes
+  -- the oldest pending row out ('expired' + consumed_at) when a new challenge arrives
+  -- at the per-key cap; without this branch that row would arrive here and be reported
+  -- as nonce_replay, which is a security signal the client must never learn to retry
+  -- through. Named separately so the client can retry exactly this one. Checked BEFORE
+  -- the generic branch because the evicted row satisfies it.
+  if v_challenge.metadata ? 'superseded_by' then
+    raise exception 'challenge_superseded: this challenge was superseded by a newer one for the same key; request a fresh challenge'
+      using errcode = '22023';
+  end if;
+  if v_challenge.proof_state <> 'pending' or v_challenge.consumed_at is not null then
+    raise exception 'nonce_replay: signing key challenge already consumed' using errcode = '23505';
+  end if;
+  if v_challenge.expires_at <= now() then
+    raise exception 'timestamp_out_of_window: signing key challenge expired' using errcode = '22023';
+  end if;
+  -- #10 nonce binding (belt-and-suspenders on top of the challenge_id binding): the
+  -- caller must present the exact stored challenge_nonce for this challenge row.
+  if p_nonce is null or p_nonce <> v_challenge.challenge_nonce then
+    raise exception 'nonce_mismatch: presented nonce does not match the bound challenge' using errcode = '42501';
+  end if;
+
+  -- (ii) signing key: bound to this agent, active, unrevoked.
+  select * into v_key
+    from agent_board.agent_signing_keys ask
+   where ask.id = p_signing_key_id
+     and ask.agent_id = p_agent_id
+   for update;
+  if not found then
+    raise exception 'signing key not found for agent' using errcode = 'P0002';
+  end if;
+  if v_key.status <> 'active' or v_key.revoked_at is not null then
+    raise exception 'key_revoked: signing key is not active' using errcode = '42501';
+  end if;
+  -- #12 key expiry: today only the challenge RPC checks agent_signing_keys.expires_at;
+  -- the mint must reject an expired key as well.
+  if v_key.expires_at is not null and v_key.expires_at <= now() then
+    raise exception 'key_expired: signing key is past its expires_at' using errcode = '42501';
+  end if;
+
+  -- (iii) whole principal active (self + every ancestor up to lineage root).
+  if not agent_board._agent_principal_active(p_agent_id) then
+    raise exception 'principal_inactive: agent principal is not fully active' using errcode = '42501';
+  end if;
+
+  -- (iv) #4 governing delegation-grant liveness for root_minted children. A child
+  -- that holds a delegation_grants row may mint ONLY while that grant is unrevoked
+  -- and unexpired (grant_expires_at > now()). independent_auth principals hold no
+  -- grant row and skip this gate. This binds the hours-scale grant clock to the mint
+  -- so an expired/revoked grant cannot keep re-minting <=900s tokens indefinitely.
+  if exists (select 1 from agent_board.delegation_grants g where g.child_agent_id = p_agent_id) then
+    if not exists (
+      select 1
+        from agent_board.delegation_grants g
+       where g.child_agent_id = p_agent_id
+         and g.revoked_at is null
+         and g.grant_expires_at > now()
+    ) then
+      raise exception 'grant_expired: the governing delegation grant is revoked or expired' using errcode = '42501';
+    end if;
+  end if;
+
+  -- Scope to the agent's authenticated principal. A fleet_agent_session must bind to
+  -- an auth-bound agent (no auth_user_id column on nonfleet_sessions; this is a mint
+  -- invariant flowed to the EF token sub, not a stored value).
+  select a.auth_user_id, a.parent_agent_id
+    into v_auth_user_id, v_parent_agent_id
+    from agent_board.agents a
+   where a.id = p_agent_id;
+  if v_auth_user_id is null then
+    raise exception 'agent has no auth_user_id principal to scope the session' using errcode = '42501';
+  end if;
+
+  -- Consume the challenge (one-time).
+  update agent_board.agent_signing_key_challenges
+     set proof_state = 'consumed',
+         consumed_at = now(),
+         updated_at = now()
+   where id = p_challenge_id;
+
+  v_expires_at := now() + make_interval(secs => v_ttl);
+
+  insert into agent_board.nonfleet_sessions(
+    id, session_id, identity_class, agent_id, parent_agent_id,
+    max_ttl_seconds, issued_at, expires_at
+  )
+  values (
+    v_session_id, v_session_id, 'fleet_agent_session', p_agent_id, v_parent_agent_id,
+    v_ttl, now(), v_expires_at
+  );
+
+  return query select v_session_id, v_expires_at;
+end;
+$$;
+comment on function agent_board.mint_fleet_agent_session(uuid, text, uuid, uuid, integer) is
+  'Whole-principal PoP session mint: re-validates challenge (incl. bound nonce) + active/unrevoked/unexpired signing key + full-lineage liveness + governing delegation-grant liveness, consumes the challenge, and inserts a <=900s fleet_agent_session. A challenge superseded by issue_signing_key_challenge raises challenge_superseded (retryable: request a fresh challenge), distinct from the nonce_replay a genuine replay raises. service_role-only.';
+
+revoke all on function agent_board.mint_fleet_agent_session(uuid, text, uuid, uuid, integer) from public, anon, authenticated;
+grant execute on function agent_board.mint_fleet_agent_session(uuid, text, uuid, uuid, integer) to service_role;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.48.0",
+  "version": "1.51.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.48.0",
+  "packageVersion": "1.51.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 146,
-  "aggregateSha256": "cbb24bed446f3334f4c0593716b51ee00e5b6faf57bfd7b48a8767f019551551",
+  "migrationCount": 150,
+  "aggregateSha256": "94b8945ab506a02a31ffd0ed6daad37d5655f209214558ca868dbb22693fb57d",
   "migrations": [
     {
       "order": 0,
@@ -1362,6 +1362,42 @@
       "sourceRef": "message-board",
       "bytes": 36921,
       "sha256": "9982efff25378703a744187b15081b5cd53ab38fa6ac7d2950092a471780169e"
+    },
+    {
+      "order": 146,
+      "id": "20260929000100_agent_board_advisory_revert_cap_reset",
+      "filename": "20260929000100_agent_board_advisory_revert_cap_reset.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 24052,
+      "sha256": "f2bd4e9e06f5c348aba379a004a010d8dba29a84f66b1b4569313fad4a0046ba"
+    },
+    {
+      "order": 147,
+      "id": "20260930000100_agent_board_claim_policy_race",
+      "filename": "20260930000100_agent_board_claim_policy_race.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 58999,
+      "sha256": "1893b57ccb643a8293c0dc801d2d66d20fe1d71a2b7dc95cd93f64ced39b472d"
+    },
+    {
+      "order": 148,
+      "id": "20261001000100_agent_board_claimpolicy_lock_grant_revoke",
+      "filename": "20261001000100_agent_board_claimpolicy_lock_grant_revoke.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 10193,
+      "sha256": "db73a9941d4601dd6db0c767fdc718534fe2856598a305f4747496cadc722afd"
+    },
+    {
+      "order": 149,
+      "id": "20261002000100_agent_board_session_challenge_supersede",
+      "filename": "20261002000100_agent_board_session_challenge_supersede.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 19273,
+      "sha256": "f10d8f539538fcf63d5b3538650160e7a4f9e345ccb7476b21756675f2b6ab80"
     }
   ],
   "excludedBridge": {