@consiliency/agent-board-schema 1.41.0 → 1.43.0

package/fixtures/already-applied.json

@@ -556,6 +556,14 @@
     {
       "id": "20260921000100_agent_board_task_event_origin_posture",
       "sha256": "c515e9cd08b73c118de64125da94735979add5d1128d3ff070ff904af77fef81"
+    },
+    {
+      "id": "20260922000100_agent_board_board_claim_policy",
+      "sha256": "1363a194f50342feb613a1aa1e01321a2a81783d88dfebe2c8f2002170cdc25c"
+    },
+    {
+      "id": "20260923000100_agent_board_heartbeat_preserve",
+      "sha256": "22713b970564bc59433026f70934758982b4cf7832be9c06197faa2d4ecc0040"
     }
   ]
 }

package/migrations/20260922000100_agent_board_board_claim_policy.sql

@@ -0,0 +1,376 @@
+-- Board-settable claim policy: let a board opt OUT of our ownerless claim enforcement.
+--
+-- THE ASK. A board's work may be coordinated by somebody else's locking — a repository lock, a
+-- scheduler lease, an external mutex — and our claim guards must not interfere with it. If their
+-- lock already granted the work, our TTL cap or quota rejecting the acquire is us breaking a
+-- system that was working. So enforcement becomes opt-out, and the board creator owns the switch.
+--
+-- WHAT THIS DOES NOT TOUCH, WHICH IS THE WHOLE SECURITY POINT. `advisory` disables the OWNERLESS
+-- guards only — the TTL cap and per-agent quota on 'file'/'tool'/'custom'. It does NOT and MUST
+-- NOT weaken:
+--
+--   * the fleet-authority gate on 'machine' / 'repository' / 'repo_file' (_can_claim_resource),
+--     which answers "may this agent claim this resource AT ALL" and is an authorization boundary,
+--     not a locking convenience;
+--   * the claim SUBJECT gate (#291), the task/thread access checks, or the uniqueness index that
+--     makes a claim exclusive in the first place.
+--
+-- The distinction is: a board may decline OUR LOCK. A board may not grant itself SOMEONE ELSE'S
+-- RESOURCE. Structurally this holds because the opt-out is inside the `v_ownerless` branch, which
+-- only the three ownerless kinds enter — and the fleet kinds are gated far above it. BCP-6 asserts
+-- it anyway rather than trusting the structure, because "it is in the right branch" is exactly the
+-- kind of reasoning that stops being true when someone moves a line.
+--
+-- WHY THE THREAD IS THE RESOLUTION PATH. `claims` has no board_id — a claim is scoped to an agent
+-- plus an optional task/thread. So the board is reached as claim -> thread -> threads.board_id.
+-- Three cases, all deliberate:
+--   * thread has a board, board says 'advisory'  -> guards skipped
+--   * thread has a board, board says 'inherit'   -> fleet-wide flags govern (the default)
+--   * no thread, or thread has no board          -> NO BOARD TO ASK, fleet-wide flags govern
+-- The last is the important one: a bare ownerless claim cannot opt itself out by omitting a
+-- thread. Opting out requires a board that a human owner deliberately configured. BCP-5 pins it.
+--
+-- DEFAULT IS 'inherit', so every existing board behaves exactly as it does today. This ships no
+-- behaviour change until a board owner asks for one.
+
+-- 1. The column.
+alter table agent_board.boards
+  add column if not exists claim_policy text not null default 'inherit';
+
+alter table agent_board.boards drop constraint if exists boards_claim_policy_check;
+alter table agent_board.boards add constraint boards_claim_policy_check
+  check (claim_policy in (
+    'inherit',   -- follow the fleet-wide claimgate flags (default; today's behaviour)
+    'advisory'   -- record claims, never enforce them: this board's locking lives elsewhere
+  ));
+
+comment on column agent_board.boards.claim_policy is
+  'Board-settable claim enforcement. ''inherit'' follows the fleet-wide claimgate flags. ''advisory'' means this board coordinates through some OTHER locking mechanism, so our ownerless (file/tool/custom) TTL cap and per-agent quota are recorded but not enforced for its claims. It does NOT weaken the fleet-authority gate on machine/repository/repo_file, the subject gate, or claim uniqueness — a board may decline our lock, never grant itself another owner''s resource. Set via agent_board.set_board_claim_policy (board owner only).';
+
+-- 2. Resolve a claim's board policy from its thread. STABLE and SECURITY DEFINER so the read is
+--    not subject to the caller's RLS — the policy is a property of the board, not of who is asking,
+--    and a caller who cannot see the board must still be governed by it.
+create or replace function agent_board._claimgate_board_claim_policy(p_thread_id uuid)
+returns text
+language sql
+stable
+security definer
+set search_path = agent_board, public
+as $$
+  select coalesce(
+    (select b.claim_policy
+       from agent_board.threads t
+       join agent_board.boards b on b.id = t.board_id
+      where t.id = p_thread_id),
+    'inherit')
+$$;
+
+revoke all on function agent_board._claimgate_board_claim_policy(uuid) from public, anon;
+grant execute on function agent_board._claimgate_board_claim_policy(uuid) to authenticated, service_role;
+
+comment on function agent_board._claimgate_board_claim_policy(uuid) is
+  'Resolves a claim''s governing board policy through its thread. Returns ''inherit'' when the thread is null, unknown, or not board-linked — so a claim with no board cannot opt itself out by omission; opting out requires a board an owner deliberately configured.';
+-- 3. acquire_claim, with the board opt-out folded into the ownerless condition.
+--    CREATE OR REPLACE with an unchanged signature, so the ACL and 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));
+    select count(*) into v_active_ownerless
+      from agent_board.claims c
+     where c.agent_id = v_actor_agent_id
+       and c.resource_kind in ('file', 'tool', 'custom')
+       and c.status = 'active'
+       and c.released_at is null
+       and c.lease_expires_at > now();
+    if v_active_ownerless >= agent_board._claimgate_ownerless_quota() then
+      raise exception 'ownerless active-claim quota reached (% per agent)', agent_board._claimgate_ownerless_quota()
+        using errcode = '54000';
+    end if;
+  end if;
+
+  -- CLAIMKEY (#133) MUST-FIX 3: the sweep AND the conflict check are ALIAS-AWARE. p_resource_key
+  -- is already canonical (above); comparing against the CANONICAL form of each existing row's key
+  -- matches both a canonical row AND an un-healed LEGACY row for the same physical resource. Without
+  -- this, acquire('machine','machine:fpDH') would normalize to 'fpDH', see no exact-'fpDH' conflict
+  -- against a still-active legacy 'machine:fpDH' row, and INSERT a second live hold — breaking mutual
+  -- exclusion during the legacy window. Closing it here in code does NOT depend on the operator-owned
+  -- live census.
+  update agent_board.claims c
+     set status = 'expired',
+         updated_at = now()
+   where c.resource_kind = p_resource_kind
+     and agent_board._canonical_claim_key(c.resource_kind, c.resource_key) = p_resource_key
+     and c.status = 'active'
+     and c.released_at is null
+     and c.lease_expires_at <= now();
+
+  if exists (
+    select 1 from agent_board.claims
+     where claims.resource_kind = p_resource_kind
+       and agent_board._canonical_claim_key(claims.resource_kind, claims.resource_key) = p_resource_key
+       and claims.status = 'active'
+       and claims.released_at is null
+       and claims.lease_expires_at > now()
+  ) then
+    raise exception 'conflicting active claim' using errcode = '23505';
+  end if;
+
+  insert into agent_board.claims(task_id, thread_id, agent_id, resource_kind, resource_key, lease_expires_at, metadata)
+  values (
+    p_task_id, v_thread_id, v_actor_agent_id, p_resource_kind, p_resource_key, p_lease_expires_at,
+    -- SHADOW stamp: record the authority verdict alongside any caller metadata. Merged last so it
+    -- is authoritative over a caller-supplied claimgate_shadow key.
+    coalesce(p_metadata, '{}'::jsonb)
+      || jsonb_build_object(
+           'claimgate_shadow',
+           jsonb_build_object('kind', p_resource_kind, 'authorized', v_shadow_authorized)
+         )
+  )
+  returning id into v_claim_id;
+
+  if p_task_id is not null then
+    perform agent_board._append_task_event('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$;
+-- 4. The setter. Owner-gated, mirroring set_board_role_gate rather than inventing a second
+--    authorization shape: the same membership test, the same service_role refusal, and the same
+--    post-UPDATE fleet-revocation assertion.
+--
+--    THE REFUSAL IS A REAL BOUNDARY, not a formality. An earlier draft of this comment said an
+--    operator "can write the column directly with the grant it already holds" — inherited wording,
+--    and it overstates the operator's reach in THIS repo: service_role holds SELECT on boards and
+--    an RLS FOR ALL policy, but NO GRANT UPDATE, so that policy does not write. Changing the
+--    column outside this RPC needs the table owner. Flagged by a review seat that checked the
+--    grants instead of reading the sentence.
+--
+--    The point of the RPC is that a BOARD CREATOR can set this without an operator at all.
+create or replace function agent_board.set_board_claim_policy(
+  p_board_id uuid,
+  p_claim_policy text
+)
+returns table(
+  board_id uuid,
+  claim_policy text,
+  updated_at timestamptz
+)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor uuid := agent_board.current_agent_id();
+  v_row agent_board.boards%rowtype;
+begin
+  if p_claim_policy is null then
+    raise exception 'p_claim_policy must not be null' using errcode = '22023';
+  end if;
+  -- Validated HERE as well as by the column CHECK. The CHECK would reject an unknown value
+  -- anyway, but with a constraint-violation error naming an internal constraint; a caller asking
+  -- for 'off' deserves to be told the vocabulary, not handed 23514.
+  if p_claim_policy not in ('inherit', 'advisory') then
+    raise exception 'claim policy must be one of inherit, advisory (received %)', p_claim_policy
+      using errcode = '22023';
+  end if;
+
+  -- Owner gate: only an active owner-role member may set this. service_role
+  -- (current_agent_id() = null) is not an owner and is rejected here.
+  if v_actor is null
+     or not exists (
+       select 1
+         from agent_board.board_memberships bm
+        where bm.board_id = p_board_id
+          and bm.agent_id = v_actor
+          and bm.role = 'owner'
+          and bm.membership_state in ('joined', 'subscribed')
+     ) then
+    raise exception 'only a board owner may set the claim policy' using errcode = '42501';
+  end if;
+
+  update agent_board.boards b
+     set claim_policy = p_claim_policy,
+         updated_at = now()
+   where b.id = p_board_id
+  returning * into v_row;
+
+  if v_row.id is null then
+    raise exception 'board not found' using errcode = 'P0002';
+  end if;
+
+  -- #276, AFTER the boards UPDATE so this function's order is boards -> agents, the canonical one
+  -- (#194). Fleet revocation deliberately LEAVES agents.status = 'active' -- the ledger row is the
+  -- only authority signal -- so the owner-membership check above passes for a revoked owner and
+  -- cannot stand alone. Disabling this board's claim enforcement is an authority write in the same
+  -- class as flipping the role gate, which is why the mirror has to include this call and not just
+  -- the membership test. Same transaction: the raise rolls the UPDATE back.
+  --
+  -- This was MISSING in the first version of this function, which claimed in its own commit
+  -- message to mirror set_board_role_gate "exactly". A review seat found it by reading both
+  -- functions side by side rather than taking that claim.
+  perform agent_board._assert_actor_not_fleet_revoked(v_actor, 'set_board_claim_policy');
+
+  return query select v_row.id, v_row.claim_policy, v_row.updated_at;
+end;
+$$;
+
+revoke all on function agent_board.set_board_claim_policy(uuid, text) from public, anon;
+grant execute on function agent_board.set_board_claim_policy(uuid, text) to authenticated, service_role;
+
+comment on function agent_board.set_board_claim_policy(uuid, text) is
+  'Board-owner-only. Sets boards.claim_policy to ''inherit'' (follow the fleet-wide claimgate flags) or ''advisory'' (this board coordinates through another locking mechanism, so our ownerless file/tool/custom TTL cap and quota are recorded but not enforced). Never weakens the fleet-authority gate on machine/repository/repo_file, the subject gate, or claim uniqueness. Owner gate and service_role refusal mirror set_board_role_gate.';

package/migrations/20260923000100_agent_board_heartbeat_preserve.sql

@@ -0,0 +1,121 @@
+-- #366/F4 — heartbeat must be able to say "I am alive" WITHOUT also saying everything else.
+--
+-- THE DEFECT. The upsert overwrote every field it was not told, and the signature made that
+-- impossible to avoid from a caller:
+--
+--     p_availability text default 'ready'
+--
+-- An OMITTED argument arrives as 'ready', so the function cannot distinguish "not supplied" from
+-- "supplied as ready". A caller that only wants to refresh the lease therefore also resets
+-- availability to 'ready' and clears thread_id, activity_summary and metadata — every time.
+--
+-- That is fatal to an implicit, activity-coupled heartbeat (#329): reporting liveness on every
+-- board tool call would silently wipe an agent's own declared state on every call. Three views
+-- read this table — v_agent_dashboard, v_ops_presence_heartbeats, v_ops_table_growth — so the
+-- damage would be visible as an agent that is permanently 'ready' and never in a thread.
+--
+-- WHY THIS COULD NOT BE FIXED IN THE CLIENT, which is what #329 assumed. That issue said "the fix
+-- is client-side and there is no schema change here at all". It was right about the WRITER — the
+-- reason presence was empty is that nothing called heartbeat — and wrong about the WRITE. No
+-- argument a client can send distinguishes absent from 'ready', because the default is applied
+-- before the function sees it. The distinction has to exist in the signature.
+--
+-- THE CHANGE. Every optional field defaults to NULL, and NULL now means LEAVE UNCHANGED:
+--
+--     p_availability      'ready'  -> null
+--     p_metadata          '{}'     -> null
+--     (p_thread_id and p_activity_summary already defaulted null; their CLEARING behaviour changes)
+--
+-- On INSERT a null still lands the documented starting value ('ready', '{}'). On CONFLICT a null
+-- preserves what is already there.
+--
+-- THE TRADE-OFF, stated rather than buried: there is now NO WAY to clear thread_id or
+-- activity_summary through heartbeat, because null is how you say "don't touch it". Clearing was
+-- never a meaningful operation here — an agent moves to another thread or its row expires — and
+-- the alternative is the defect above. `presence` holds ZERO rows on the canonical project
+-- (measured 2026-08-29, unchanged in four weeks), so no caller relies on the old clearing shape.
+--
+--
+-- #366/F1 IS FIXED HERE TOO, and by a better mechanism than the one first proposed. The client
+-- could not call heartbeat at all: `p_agent_id uuid` had NO DEFAULT, so a call omitting it did not
+-- match the function and was rejected before the body ran. The obvious fix was to add heartbeat to
+-- the client's USER_SCOPED_ACTOR_DEFAULTS map so the client fills the id in.
+--
+-- That would have worked and it is the wrong layer. heartbeat ALREADY resolves its actor from the
+-- session:
+--
+--     v_actor_agent_id := agent_board._resolved_actor_agent_id(p_agent_id, 'p_agent_id');
+--
+-- and that resolver, for a non-service_role caller, IGNORES a supplied id beyond checking it
+-- matches `current_agent_id()`. Having the client send an id the server then re-derives is the
+-- shape this repo has a rule against: provenance is derived from the session, never from a caller
+-- argument. The id was required by the SIGNATURE, not by the semantics.
+--
+-- So `p_agent_id` gains `default null`. An authenticated caller omits it and the session answers;
+-- a service_role caller must still supply it, because `_resolved_actor_agent_id` raises 22023 for
+-- a null id under service_role — that behaviour is untouched and HBP-12 pins it.
+-- SIGNATURE IS UNCHANGED. Parameter DEFAULTS are not part of a function's identity in PostgreSQL,
+-- so this is a true CREATE OR REPLACE: the ACL and the COMMENT survive, and nothing is dropped.
+-- That matters here specifically — heartbeat is granted to authenticated, and a DROP would hand
+-- EXECUTE back to PUBLIC by default.
+create or replace function agent_board.heartbeat(
+  p_agent_id uuid default null,
+  p_thread_id uuid default null,
+  p_availability text default null,
+  p_activity_summary text default null,
+  p_expires_in interval default interval '5 minutes',
+  p_metadata jsonb default null
+)
+returns table(agent_id uuid, availability text, thread_id uuid, last_heartbeat_at timestamptz, expires_at timestamptz, updated_at timestamptz)
+language plpgsql
+security definer
+set search_path = agent_board, public
+as $$
+declare
+  v_actor_agent_id uuid;
+begin
+  v_actor_agent_id := agent_board._resolved_actor_agent_id(p_agent_id, 'p_agent_id');
+
+  -- Unchanged: a supplied thread must exist and be reachable by the caller. A NULL thread now
+  -- means "leave my thread as it is", so it is not a claim about any thread and needs no check.
+  if p_thread_id is not null then
+    if not exists (select 1 from agent_board.threads where id = p_thread_id) then
+      raise exception 'thread not found' using errcode = 'P0002';
+    end if;
+    if not agent_board._current_agent_can_access_thread(p_thread_id) then
+      raise exception 'thread not accessible to current agent' using errcode = '42501';
+    end if;
+  end if;
+
+  return query
+  insert into agent_board.presence(agent_id, thread_id, availability, activity_summary, last_heartbeat_at, expires_at, metadata, updated_at)
+  values (
+    v_actor_agent_id,
+    p_thread_id,
+    -- INSERT: a null still lands the documented starting value, so a first heartbeat behaves
+    -- exactly as it did before this migration.
+    coalesce(p_availability, 'ready'),
+    p_activity_summary,
+    now(),
+    now() + coalesce(p_expires_in, interval '5 minutes'),
+    coalesce(p_metadata, '{}'::jsonb),
+    now()
+  )
+  on conflict on constraint presence_pkey do update
+    -- UPDATE: null preserves. `presence.<col>` is the EXISTING row; `excluded.<col>` is what this
+    -- call proposed. Coalescing onto the existing value is the whole fix -- it is what lets a
+    -- lease refresh say nothing about availability.
+    set thread_id        = coalesce(excluded.thread_id, presence.thread_id),
+        availability     = coalesce(p_availability, presence.availability),
+        activity_summary = coalesce(excluded.activity_summary, presence.activity_summary),
+        metadata         = coalesce(p_metadata, presence.metadata),
+        -- These three are the POINT of a heartbeat and always advance.
+        last_heartbeat_at = excluded.last_heartbeat_at,
+        expires_at        = excluded.expires_at,
+        updated_at        = excluded.updated_at
+  returning presence.agent_id, presence.availability, presence.thread_id, presence.last_heartbeat_at, presence.expires_at, presence.updated_at;
+end;
+$$;
+
+comment on function agent_board.heartbeat(uuid, uuid, text, text, interval, jsonb) is
+  '#366/F1+F4: asserts liveness for the acting agent. Every optional field defaults to NULL and NULL means LEAVE UNCHANGED on an existing row -- so a caller refreshing only the lease does not reset availability to ''ready'' or clear thread_id/activity_summary/metadata. On a FIRST heartbeat a null still lands the documented starting value (''ready'', ''{}''). Consequence, deliberate: thread_id and activity_summary cannot be CLEARED through this RPC, because null is how a caller declines to change them. Before this migration p_availability defaulted to ''ready'', which made "not supplied" indistinguishable from "supplied as ready" and made an implicit activity-coupled heartbeat destructive. p_agent_id also gains a null default (#366/F1): it was required by the SIGNATURE though the body already resolves the actor from the session via _resolved_actor_agent_id, so an authenticated caller may now omit it entirely. service_role must still supply it -- that resolver raises 22023 for a null id under service_role, unchanged.';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.41.0",
+  "version": "1.43.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.41.0",
+  "packageVersion": "1.43.0",
   "schemaVersion": 8,
   "minClientVersion": "1.1.0",
   "source": {
@@ -46,8 +46,8 @@
       "usage": "upsert (retention/monitoring defaults; on conflict do nothing)"
     }
   ],
-  "migrationCount": 139,
-  "aggregateSha256": "0c0daf769baedbae5243a7345d44df09613494c5ea2495b342222a7248dde6d0",
+  "migrationCount": 141,
+  "aggregateSha256": "d97c281cbc43a2c031dc769731473c6c9d1aa4facb0f72d07095cd1b9301a163",
   "migrations": [
     {
       "order": 0,
@@ -1299,6 +1299,24 @@
       "sourceRef": "message-board",
       "bytes": 48237,
       "sha256": "c515e9cd08b73c118de64125da94735979add5d1128d3ff070ff904af77fef81"
+    },
+    {
+      "order": 139,
+      "id": "20260922000100_agent_board_board_claim_policy",
+      "filename": "20260922000100_agent_board_board_claim_policy.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 22285,
+      "sha256": "1363a194f50342feb613a1aa1e01321a2a81783d88dfebe2c8f2002170cdc25c"
+    },
+    {
+      "order": 140,
+      "id": "20260923000100_agent_board_heartbeat_preserve",
+      "filename": "20260923000100_agent_board_heartbeat_preserve.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 7731,
+      "sha256": "22713b970564bc59433026f70934758982b4cf7832be9c06197faa2d4ecc0040"
     }
   ],
   "excludedBridge": {

package/src/tooling.test.mjs

@@ -38,9 +38,9 @@ describe('manifest integrity', () => {
     expect(manifest.schemaVersion).toBe(8);
     expect(manifest.minClientVersion).toMatch(/^\d+\.\d+\.\d+$/);
   });
-  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION + one FEDSESSION-AUTOJOIN + one GATENULL + one MEMBSTATE + one AGENTSDIR + one LEAVEIDEM + one ROLERESET + one MBROWID + one MBHYGIENE + one MBCONSENT-A + one MBCONSENT-B(a) + one MBCONSENT-B(i) + one MBCONSENT-B(ii) + one MBCONSENT-B(iii) + one MBHARDEN-#97 + one MBHARDEN-#118 + one INVITEPOLICY + one OBSGATE + one OBSGATE-2 + one OBSGATE-3 + one OBSGATE-4 + one FLEETMACHINERLS + one RESOLVENOOP + one ROOMDELEG-LANEB + one CLAIMKEY + two MINTHARDEN + one FLEETMACHINEHIJACK + one CLAIMGATE-SHADOW + one CLAIMGATE-ENFORCE + one FLEETMACHINEREACTIVATION + one DELEGCAPCEILING + one FLEETMACHINERECLAIM + one DELEGSOLEWRITER + one FLEETDOMAINRECLAIM + five ATOMICFLEETONBOARDING (onboarding + ceiling-lock + revocation-evidence + fedsession-gate + fedsession-lock-order) + one OUTBOXWAKE + one ENROLLLOCKORDER + one FEDPROVIDERABSENCE + one WAKERECOVERY + one CONSENTRECONCILE + one ENROLLRESUMPTION + one SIGNEDAUTHORITY + one SIGNERLIFECYCLE + one LEDGERAUTHORITY + one CEILINGLOCKCOMMENT + one LEDGERBOARDCREATE + one RECEIPTSUBJECTGATE + one TASKTHREADLOCKORDER + one CLAIMSUBJECTGATE + one FEDSESSIONIDENTITYGATE + one FEDIDENTITYSLUG + one INVITENODOWNGRADE + one SIGNEDWRITEFLAG + one SIGNEDWRITEMODEL + one RTCREDCLAIM + one ORIGINPOSTURE forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 = 139)', () => {
+  it('registers the four MBAUTHZ + four MBSENDAUTHZ + four MBSESSION + four MBDELEG + three MBFED + three MBHARDEN + two MBPORTALGATE + two MBPORTAL-PR32 + two ROOMOWN + two ROOMLINK + one ROOMDELEG + one LOCALAUTH + one ROOMUIAPI + one FEDSESSION + one FEDSESSION-AUTOJOIN + one GATENULL + one MEMBSTATE + one AGENTSDIR + one LEAVEIDEM + one ROLERESET + one MBROWID + one MBHYGIENE + one MBCONSENT-A + one MBCONSENT-B(a) + one MBCONSENT-B(i) + one MBCONSENT-B(ii) + one MBCONSENT-B(iii) + one MBHARDEN-#97 + one MBHARDEN-#118 + one INVITEPOLICY + one OBSGATE + one OBSGATE-2 + one OBSGATE-3 + one OBSGATE-4 + one FLEETMACHINERLS + one RESOLVENOOP + one ROOMDELEG-LANEB + one CLAIMKEY + two MINTHARDEN + one FLEETMACHINEHIJACK + one CLAIMGATE-SHADOW + one CLAIMGATE-ENFORCE + one FLEETMACHINEREACTIVATION + one DELEGCAPCEILING + one FLEETMACHINERECLAIM + one DELEGSOLEWRITER + one FLEETDOMAINRECLAIM + five ATOMICFLEETONBOARDING (onboarding + ceiling-lock + revocation-evidence + fedsession-gate + fedsession-lock-order) + one OUTBOXWAKE + one ENROLLLOCKORDER + one FEDPROVIDERABSENCE + one WAKERECOVERY + one CONSENTRECONCILE + one ENROLLRESUMPTION + one SIGNEDAUTHORITY + one SIGNERLIFECYCLE + one LEDGERAUTHORITY + one CEILINGLOCKCOMMENT + one LEDGERBOARDCREATE + one RECEIPTSUBJECTGATE + one TASKTHREADLOCKORDER + one CLAIMSUBJECTGATE + one FEDSESSIONIDENTITYGATE + one FEDIDENTITYSLUG + one INVITENODOWNGRADE + one SIGNEDWRITEFLAG + one SIGNEDWRITEMODEL + one RTCREDCLAIM + one ORIGINPOSTURE + one BOARDCLAIMPOLICY + one HEARTBEATPRESERVE forward migrations (migrationCount = prior 113 + 5 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 + 1 = 141)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(139);
+    expect(manifest.migrationCount).toBe(141);
     // MBSESSION switched enforcement on (scoped-send re-grant): the client-visible
     // schema version bumped to 8. MBDELEG tightens delegation and MBFED adds only
     // enrollment-only additive surface (identity_providers registry, enrollment audit,
@@ -245,6 +245,23 @@ describe('manifest integrity', () => {
       // PostgreSQL refuses a default before non-defaulted parameters. Nothing is DROPped: both
       // public signatures stay byte-identical, so ACLs and COMMENTs survive.
       '20260921000100_agent_board_task_event_origin_posture.sql',
+      // BOARDCLAIMPOLICY. A board's work may be coordinated by SOMEONE ELSE'S locking -- a repo
+      // lock, a scheduler lease, an external mutex -- and our claim guards must not break a system
+      // that was already working. boards.claim_policy lets the board OWNER opt out: 'inherit'
+      // (default, today's behaviour) or 'advisory' (record claims, never enforce them). It
+      // disables the OWNERLESS file/tool/custom lease cap and quota ONLY, and cannot reach the
+      // fleet-authority gate on machine/repository/repo_file -- a board may decline our lock,
+      // never grant itself another owner's resource (BCP-6 asserts that from the catalog).
+      '20260922000100_agent_board_board_claim_policy.sql',
+      // #366/F4 HEARTBEATPRESERVE. heartbeat's upsert overwrote every field it was not told, and
+      // p_availability defaulted to 'ready' -- so the function could not distinguish "not supplied"
+      // from "supplied as ready", and a caller refreshing only its lease also reset availability
+      // and cleared thread_id/activity_summary/metadata. Fatal to an implicit activity-coupled
+      // heartbeat (#329), and unfixable from the client because the default is applied before the
+      // function sees it. Optional fields now default NULL and NULL means LEAVE UNCHANGED on an
+      // existing row; a first heartbeat still lands 'ready'/'{}'. Signature unchanged (parameter
+      // defaults are not part of function identity), so the ACL and COMMENT survive.
+      '20260923000100_agent_board_heartbeat_preserve.sql',
     ]) {
       expect(names.has(f)).toBe(true);
     }

package/tests/agent_board_board_claim_policy.test.sql

@@ -0,0 +1,228 @@
+-- Board-settable claim policy: a board may decline OUR lock, never grant itself ANOTHER OWNER'S
+-- resource.
+--
+-- THE ASK. A board's work may be coordinated by somebody else's locking — a repository lock, a
+-- scheduler lease, an external mutex. If their lock already granted the work, our TTL cap or quota
+-- rejecting the acquire is us breaking a system that was working. So the enforcement is opt-out
+-- and the board owner holds the switch.
+--
+-- BCP-6 IS THE ASSERTION THIS FILE EXISTS FOR. Everything else here checks that the opt-out
+-- works; BCP-6 checks that it does not work on the things it must never reach. `advisory` disables
+-- the OWNERLESS guards (file/tool/custom lease cap + per-agent quota) and must leave the
+-- fleet-authority gate on machine/repository/repo_file untouched — that gate answers "may this
+-- agent claim this resource at all", which is authorization, not a locking convenience.
+--
+-- Structurally that holds because the opt-out sits inside the `v_ownerless` branch and the fleet
+-- kinds are gated far above it. BCP-6 asserts it anyway: "it is in the right branch" is exactly
+-- the kind of reasoning that stops being true when someone moves a line, and this file would
+-- otherwise be a set of tests that only ever prove the permissive direction.
+--
+-- BCP-5 IS THE SECOND ONE THAT MATTERS. A claim reaches its board through its thread. So the
+-- obvious hole is a claim that simply omits the thread — if that inherited "no board, therefore no
+-- enforcement", any agent could opt itself out by passing null. It resolves to 'inherit' instead,
+-- and BCP-5 pins that the fleet-wide flags still govern.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(13);
+
+-- ---------------------------------------------------------------------------
+-- Fixture: one board with an owner and a non-owner member, a board-linked thread, and a
+-- thread with NO board (for BCP-5).
+-- ---------------------------------------------------------------------------
+create temp table _bcp (
+  board uuid, owner_agent uuid, owner_user uuid,
+  member_agent uuid, member_user uuid,
+  thread uuid, free_thread uuid
+) on commit drop;
+
+do $$
+declare
+  v_sfx text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_owner uuid := gen_random_uuid();
+  v_member uuid := gen_random_uuid();
+  v_owner_user uuid; v_member_user uuid;
+  v_board uuid; v_thread uuid := gen_random_uuid(); v_free uuid := gen_random_uuid();
+begin
+  v_owner_user  := public.ensure_github_user('bcp-own-' || v_sfx, 'bcp-own-' || v_sfx || '@example.test', 'bcp-own-' || v_sfx, 'BCP Owner');
+  v_member_user := public.ensure_github_user('bcp-mem-' || v_sfx, 'bcp-mem-' || v_sfx || '@example.test', 'bcp-mem-' || v_sfx, 'BCP Member');
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values (v_owner,  'agent', 'bcp-own-' || v_sfx, 'BCP Owner',  'active', v_owner_user,  v_owner_user),
+         (v_member, 'agent', 'bcp-mem-' || v_sfx, 'BCP Member', 'active', v_member_user, v_member_user);
+
+  -- create_board seeds the creator's owner membership (ROOMOWN).
+  perform set_config('request.jwt.claim.role', 'authenticated', true);
+  perform set_config('request.jwt.claim.sub', v_owner_user::text, true);
+  select board_id into v_board
+    from agent_board.create_board(v_owner, 'bcp-' || v_sfx, 'BCP Board', 'claim policy', '{}'::jsonb, 'private');
+
+  insert into agent_board.board_memberships(board_id, agent_id, membership_state, created_by_agent_id, role)
+  values (v_board, v_member, 'joined', v_owner, 'member');
+
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject, board_id)
+  values (v_thread, 'coordination', v_owner, 'BCP board thread', v_board),
+         (v_free,   'coordination', v_owner, 'BCP boardless thread', null);
+
+  insert into _bcp values (v_board, v_owner, v_owner_user, v_member, v_member_user, v_thread, v_free);
+end $$;
+
+-- The fleet-wide guards must be ON for any of the opt-out assertions to mean anything: with them
+-- off, everything succeeds and every permissive assertion below would pass vacuously.
+insert into agent_board.claimgate_enforcement_flags(scope_key, enabled)
+values ('ownerless_guards', true)
+on conflict (scope_key) do update set enabled = true;
+
+-- ---------------------------------------------------------------------------
+-- BCP-1..2: the column.
+-- ---------------------------------------------------------------------------
+select is(
+  (select claim_policy from agent_board.boards where id = (select board from _bcp)),
+  'inherit',
+  'BCP-1: a newly created board defaults to inherit, so this migration changes no existing behaviour');
+
+-- Scored by extracting the constraint's OWN literal list, not by checking that two known words
+-- appear in it. The weaker spelling passes against a vocabulary that also admits a third value --
+-- a review seat pointed out the first version of this assertion did exactly that.
+select is(
+  (select string_agg(m[1], ',' order by m[1])
+     from pg_constraint c,
+          lateral regexp_matches(pg_get_constraintdef(c.oid), '''([a-z-]+)''', 'g') m
+    where c.conrelid = 'agent_board.boards'::regclass
+      and c.conname = 'boards_claim_policy_check'),
+  'advisory,inherit',
+  'BCP-2: the vocabulary is EXACTLY inherit and advisory -- a third admitted value fails here');
+
+-- ---------------------------------------------------------------------------
+-- BCP-3..4: the opt-out, in both directions. Both use an over-cap lease, so the ONLY difference
+-- between them is the board policy.
+-- ---------------------------------------------------------------------------
+select lives_ok(
+  $$ select agent_board.set_board_claim_policy((select board from _bcp), 'advisory') $$,
+  'BCP-3a: a board owner may set advisory (lives_ok, so a raise fails HERE rather than aborting)');
+
+select lives_ok(
+  $$ select * from agent_board.acquire_claim(
+       (select owner_agent from _bcp), 'file', 'bcp-over-cap-advisory',
+       now() + interval '400 days', null, (select thread from _bcp)) $$,
+  'BCP-3b: with advisory, an OVER-CAP ownerless lease is allowed — their lock governs, not ours');
+
+do $$
+begin
+  perform agent_board.set_board_claim_policy((select board from _bcp), 'inherit');
+end $$;
+
+select throws_ok(
+  $$ select * from agent_board.acquire_claim(
+       (select owner_agent from _bcp), 'file', 'bcp-over-cap-inherit',
+       now() + interval '400 days', null, (select thread from _bcp)) $$,
+  '22023',
+  null,
+  'BCP-4: with inherit, the SAME over-cap lease is rejected — so BCP-3b is the policy working, not the guard being absent');
+
+-- ---------------------------------------------------------------------------
+-- BCP-5: no board means no opt-out. A claim that omits the thread must not inherit permissiveness.
+-- ---------------------------------------------------------------------------
+select throws_ok(
+  $$ select * from agent_board.acquire_claim(
+       (select owner_agent from _bcp), 'file', 'bcp-no-thread',
+       now() + interval '400 days', null, null) $$,
+  '22023',
+  null,
+  'BCP-5: a claim with NO thread cannot opt itself out by omission — it resolves to inherit and the fleet flags govern');
+
+select is(
+  agent_board._claimgate_board_claim_policy(null),
+  'inherit',
+  'BCP-5b: the resolver itself answers inherit for a null thread rather than NULL, so the comparison in acquire_claim can never be NULL-swallowed');
+
+select is(
+  agent_board._claimgate_board_claim_policy((select free_thread from _bcp)),
+  'inherit',
+  'BCP-5c: and inherit for a real thread that is not board-linked');
+
+-- ---------------------------------------------------------------------------
+-- BCP-6: THE SECURITY BOUNDARY. advisory must NOT reach the fleet-authority gate.
+--
+-- Scored from the catalog rather than by attempting a machine claim, because a behavioural probe
+-- here would need a full fleet-registration fixture and would prove only that ONE machine claim
+-- was refused. This asks the structural question instead: does the board policy appear anywhere
+-- the fleet kinds are decided? It must appear ONLY inside the ownerless branch.
+-- ---------------------------------------------------------------------------
+select is(
+  (select coalesce(string_agg(p.proname, ', ' order by p.proname), '')
+     from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board'
+      and p.proname in ('_can_claim_resource', '_claimgate_kind_enforced', '_claimgate_promotion_blockers')
+      and agent_board_test.stripped_body(p.oid, true) ~ '_claimgate_board_claim_policy'),
+  '',
+  'BCP-6 SECURITY: the board policy is reachable from NO fleet-authority function — a board may decline our lock, never grant itself another owner''s resource');
+
+-- ---------------------------------------------------------------------------
+-- BCP-7..8: who may set it. Mirrors set_board_role_gate's gate exactly.
+-- ---------------------------------------------------------------------------
+select throws_ok(
+  format($$ select set_config('request.jwt.claim.sub', %L, true);
+            select agent_board.set_board_claim_policy(%L, 'advisory') $$,
+         (select member_user from _bcp)::text, (select board from _bcp)::text),
+  '42501',
+  null,
+  'BCP-7: a non-owner MEMBER may not set the claim policy');
+
+select throws_ok(
+  format($$ select set_config('request.jwt.claims', '', true);
+            select set_config('request.jwt.claim.sub', '', true);
+            select set_config('request.jwt.claim.role', '', true);
+            select agent_board.set_board_claim_policy(%L, 'advisory') $$, (select board from _bcp)::text),
+  '42501',
+  null,
+  'BCP-8: an unresolved principal (service_role) is not an owner and is refused — same carve-out as set_board_role_gate');
+
+-- ---------------------------------------------------------------------------
+-- BCP-9: an unknown value is refused by the RPC with the vocabulary, not by the column CHECK with
+-- a constraint name. A caller asking for 'off' should be told what the options are.
+-- ---------------------------------------------------------------------------
+select throws_ok(
+  format($$ select set_config('request.jwt.claim.role', 'authenticated', true);
+            select set_config('request.jwt.claim.sub', %L, true);
+            select agent_board.set_board_claim_policy(%L, 'off') $$,
+         (select owner_user from _bcp)::text, (select board from _bcp)::text),
+  '22023',
+  null,
+  'BCP-9: an unknown policy is refused as a bad argument, naming the vocabulary — not as a raw CHECK violation');
+
+-- ---------------------------------------------------------------------------
+-- BCP-10: A FLEET-REVOKED OWNER IS STILL AN OWNER BY MEMBERSHIP. This function shipped its first
+-- version WITHOUT this check while its own commit message claimed to mirror set_board_role_gate
+-- "exactly" -- a review seat found it by reading both functions side by side instead of taking
+-- the claim. Fleet revocation deliberately leaves agents.status = 'active' (the ledger row is the
+-- only authority signal), so the membership test in BCP-7/8 passes for a revoked owner and cannot
+-- stand alone.
+--
+-- Disabling a board's claim enforcement is an authority write in the same class as flipping the
+-- role gate, so it owes the same post-UPDATE revocation assertion.
+-- ---------------------------------------------------------------------------
+do $$
+begin
+  -- revoke as an operator (service_role: no resolved actor)
+  perform set_config('request.jwt.claims', '', true);
+  perform set_config('request.jwt.claim.sub', '', true);
+  perform set_config('request.jwt.claim.role', '', true);
+  perform agent_board.revoke_fleet_subject(
+    'agent', (select owner_agent from _bcp), (select owner_agent from _bcp),
+    'BCP-10 revocation', '{}'::jsonb);
+end $$;
+
+select throws_ok(
+  format($$ select set_config('request.jwt.claim.role', 'authenticated', true);
+            select set_config('request.jwt.claim.sub', %L, true);
+            select agent_board.set_board_claim_policy(%L, 'advisory') $$,
+         (select owner_user from _bcp)::text, (select board from _bcp)::text),
+  '42501',
+  null,
+  'BCP-10: a FLEET-REVOKED owner may not disable claim enforcement, even though the board still lists them as owner and their agent row is still active');
+
+select * from finish();
+rollback;

package/tests/agent_board_heartbeat_preserve.test.sql

@@ -0,0 +1,240 @@
+-- #366/F4 pgTAP: a heartbeat can say "I am alive" WITHOUT also saying everything else.
+--
+-- THE DEFECT THIS PINS. heartbeat's upsert overwrote every field it was not told, and the
+-- signature made that unavoidable from a caller: `p_availability text default 'ready'` means an
+-- OMITTED argument arrives as 'ready', so the function could not distinguish "not supplied" from
+-- "supplied as ready". A caller refreshing only its lease also reset availability and cleared
+-- thread_id, activity_summary and metadata — every single call.
+--
+-- That is fatal to the implicit, activity-coupled heartbeat #329 wants: reporting liveness on
+-- every board tool call would wipe the agent's own declared state on every call.
+--
+-- HBP-2 IS THE ONE THIS FILE EXISTS FOR. Everything else checks that the change did not break the
+-- documented behaviour; HBP-2 checks the behaviour the change was made for. HBP-6 is its
+-- necessary twin: "preserve on null" must not decay into "ignore the argument", and a file that
+-- only asserted preservation would pass against a function that ignored availability entirely.
+--
+-- WHAT THIS FILE STRUCTURALLY CANNOT SEE, named here because a review seat walked through it.
+-- Every assertion below calls the RPC with `p_metadata` OMITTED. The production client did not:
+-- `heartbeat` was classified `signed-metadata`, and the client's attachSigningMetadata ALWAYS
+-- writes a non-null `p_metadata`, so for every signing-enabled agent the server saw a supplied
+-- argument and HBP-5's coalesce replaced the declared metadata with the signing envelope. HBP-2/3/4
+-- were true and HBP-5 was false in production, and no assertion here could have told the
+-- difference, because pgTAP cannot see what the client puts on the wire. The fix was to
+-- reclassify the RPC as `unsigned-deliberate`; the pin lives in client.test.ts, "leaves heartbeat
+-- unsigned, so a lease refresh cannot clobber declared presence (#366)". A server-side test file
+-- naming its own blind spot is cheaper than a reader assuming it has none.
+--
+-- HBP-9 ASSERTS THE TRADE-OFF RATHER THAN HIDING IT. Because null now means "leave unchanged",
+-- there is no way to CLEAR thread_id through this RPC. That is a real capability loss, it was
+-- chosen deliberately over the defect above, and it is asserted here so it is a documented
+-- property rather than something a future reader discovers and treats as a bug.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(14);
+
+-- ---------------------------------------------------------------------------
+-- Fixture: one agent, and two threads it can reach.
+-- ---------------------------------------------------------------------------
+create temp table _hb (agent uuid, auth_user uuid, thread_a uuid, thread_b uuid) on commit drop;
+
+do $$
+declare
+  v_sfx text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_agent uuid := gen_random_uuid();
+  v_user uuid;
+  v_a uuid := gen_random_uuid();
+  v_b uuid := gen_random_uuid();
+begin
+  v_user := public.ensure_github_user('hb-' || v_sfx, 'hb-' || v_sfx || '@example.test', 'hb-' || v_sfx, 'HB Agent');
+  insert into agent_board.agents(id, agent_type, handle, display_name, status, auth_user_id, owner_user_id)
+  values (v_agent, 'agent', 'hb-' || v_sfx, 'HB Agent', 'active', v_user, v_user);
+  insert into agent_board.threads(id, thread_type, created_by_agent_id, subject)
+  values (v_a, 'coordination', v_agent, 'HB thread A'),
+         (v_b, 'coordination', v_agent, 'HB thread B');
+  perform set_config('request.jwt.claim.role', 'authenticated', true);
+  perform set_config('request.jwt.claim.sub', v_user::text, true);
+  insert into _hb values (v_agent, v_user, v_a, v_b);
+end $$;
+
+-- ---------------------------------------------------------------------------
+-- HBP-1: the INSERT path is unchanged. A first heartbeat with nothing supplied still lands the
+-- documented starting values, so this migration is not a behaviour change for a new agent.
+-- ---------------------------------------------------------------------------
+do $$
+begin
+  perform agent_board.heartbeat((select agent from _hb));
+end $$;
+
+select is(
+  (select availability || '|' || coalesce(thread_id::text, 'NULL') || '|' || coalesce(activity_summary, 'NULL') || '|' || metadata::text
+     from agent_board.presence where agent_id = (select agent from _hb)),
+  'ready|NULL|NULL|{}',
+  'HBP-1: a FIRST heartbeat with nothing supplied still lands ready / no thread / no summary / {}');
+
+-- Now the agent declares real state, the way a caller that means it would.
+do $$
+begin
+  perform agent_board.heartbeat(
+    (select agent from _hb),
+    (select thread_a from _hb),
+    'busy',
+    'reviewing the panel findings',
+    interval '10 minutes',
+    '{"lane":"review"}'::jsonb);
+end $$;
+
+select is(
+  (select availability || '|' || thread_id::text || '|' || activity_summary || '|' || (metadata->>'lane')
+     from agent_board.presence where agent_id = (select agent from _hb)),
+  'busy|' || (select thread_a from _hb)::text || '|reviewing the panel findings|review',
+  'HBP-2a: an explicit heartbeat sets every field it supplies');
+
+-- ---------------------------------------------------------------------------
+-- HBP-2..5: THE FIX. A lease-only refresh — exactly what an implicit activity-coupled heartbeat
+-- sends — must leave all four declared fields alone.
+-- ---------------------------------------------------------------------------
+do $$
+begin
+  perform agent_board.heartbeat((select agent from _hb), p_expires_in => interval '30 minutes');
+end $$;
+
+select is(
+  (select availability from agent_board.presence where agent_id = (select agent from _hb)),
+  'busy',
+  'HBP-2: a lease-only refresh PRESERVES availability — before this fix it silently reset to ready on every call');
+
+select is(
+  (select thread_id from agent_board.presence where agent_id = (select agent from _hb)),
+  (select thread_a from _hb),
+  'HBP-3: and preserves thread_id');
+
+select is(
+  (select activity_summary from agent_board.presence where agent_id = (select agent from _hb)),
+  'reviewing the panel findings',
+  'HBP-4: and preserves activity_summary');
+
+select is(
+  (select metadata->>'lane' from agent_board.presence where agent_id = (select agent from _hb)),
+  'review',
+  'HBP-5: and preserves metadata');
+
+-- ---------------------------------------------------------------------------
+-- HBP-6: the necessary twin. "Preserve on null" must not decay into "ignore the argument" — a
+-- function that ignored availability entirely would pass HBP-2 through HBP-5 and be useless.
+-- ---------------------------------------------------------------------------
+do $$
+begin
+  perform agent_board.heartbeat((select agent from _hb), p_availability => 'away');
+end $$;
+
+select is(
+  (select availability from agent_board.presence where agent_id = (select agent from _hb)),
+  'away',
+  'HBP-6: an EXPLICIT availability still sets it — preserve-on-null is not ignore-the-argument');
+
+-- ---------------------------------------------------------------------------
+-- HBP-7: the fields a heartbeat exists to MOVE must always move, however little else is supplied.
+-- A preserve-everything bug would freeze the lease and make every agent look permanently stale --
+-- the exact opposite failure to the one HBP-2 fixes, and just as invisible.
+--
+-- WHY THE OBVIOUS SPELLING DOES NOT WORK: now() is fixed for an entire TRANSACTION in PostgreSQL,
+-- and this file runs in one. Two heartbeats here therefore produce the SAME last_heartbeat_at, and
+-- pg_sleep does not change that. The first version of this assertion compared two in-transaction
+-- heartbeats and failed for that reason -- a broken probe, not a broken function.
+--
+-- So the row is pushed into the past first. If last_heartbeat_at were preserved rather than
+-- written, it would STAY an hour old, which is a difference this transaction can actually see.
+-- ---------------------------------------------------------------------------
+update agent_board.presence
+   set last_heartbeat_at = now() - interval '1 hour',
+       expires_at = now() - interval '30 minutes'
+ where agent_id = (select agent from _hb);
+
+do $$
+begin
+  perform agent_board.heartbeat((select agent from _hb), p_expires_in => interval '90 minutes');
+end $$;
+
+select ok(
+  (select last_heartbeat_at = now() and expires_at > now() + interval '89 minutes'
+     from agent_board.presence where agent_id = (select agent from _hb)),
+  'HBP-7: last_heartbeat_at and expires_at ALWAYS advance -- pushed an hour into the past, a heartbeat brings them back');
+
+-- ---------------------------------------------------------------------------
+-- HBP-8: an explicitly supplied thread still moves the agent, so preservation does not pin it.
+-- ---------------------------------------------------------------------------
+do $$
+begin
+  perform agent_board.heartbeat((select agent from _hb), (select thread_b from _hb));
+end $$;
+
+select is(
+  (select thread_id from agent_board.presence where agent_id = (select agent from _hb)),
+  (select thread_b from _hb),
+  'HBP-8: an explicit thread still moves the agent between threads');
+
+-- ---------------------------------------------------------------------------
+-- HBP-9: THE TRADE-OFF, asserted rather than hidden. Null means "leave unchanged", so thread_id
+-- cannot be CLEARED through this RPC. Chosen deliberately over the destructive alternative, and
+-- pinned here so a future reader finds a documented property instead of what looks like a bug.
+-- ---------------------------------------------------------------------------
+do $$
+begin
+  perform agent_board.heartbeat((select agent from _hb), null);
+end $$;
+
+select is(
+  (select thread_id from agent_board.presence where agent_id = (select agent from _hb)),
+  (select thread_b from _hb),
+  'HBP-9 TRADE-OFF: a null thread does NOT clear it — null is how a caller declines to change a field, so clearing is not expressible here');
+
+-- ---------------------------------------------------------------------------
+-- HBP-10: CREATE OR REPLACE kept the ACL. Parameter defaults are not part of a function's
+-- identity, so this was a true replace — but DROP FUNCTION would have handed EXECUTE back to
+-- PUBLIC, and heartbeat is granted to authenticated.
+-- ---------------------------------------------------------------------------
+select is(
+  (select coalesce(string_agg(r, ', ' order by r), '')
+     from unnest(array['anon','authenticated','service_role']) r
+    where has_function_privilege(r, 'agent_board.heartbeat(uuid,uuid,text,text,interval,jsonb)', 'execute')),
+  'authenticated, service_role',
+  'HBP-10: the ACL survived the replace — authenticated and service_role, and NOT anon or public');
+
+-- ---------------------------------------------------------------------------
+-- HBP-11/12: #366/F1 — the call that could not be made.
+--
+-- p_agent_id had no default, so `heartbeat()` did not match the function and was rejected before
+-- the body ran. That is why the implicit heartbeat in #366 was a silent no-op: the RPC rejected,
+-- and the fire-and-forget reporter swallowed the error by design.
+--
+-- The fix is the SIGNATURE, not the client. The body already resolves the actor from the session,
+-- and _resolved_actor_agent_id ignores a supplied id for a non-service_role caller beyond checking
+-- it matches. Having the client send an id the server re-derives is the shape this repo has a rule
+-- against.
+-- ---------------------------------------------------------------------------
+select lives_ok(
+  $$ select agent_board.heartbeat() $$,
+  'HBP-11: an authenticated caller can heartbeat with NO arguments at all — the session answers for the actor');
+
+select is(
+  (select count(*)::int from agent_board.presence where agent_id = (select agent from _hb)),
+  1,
+  'HBP-11b: and it wrote the ACTING agent''s row, not some other one');
+
+-- service_role has no session identity, so the resolver must still demand an explicit id. If this
+-- ever passed, an operator call with no actor would silently write somebody's presence.
+select throws_ok(
+  $$ select set_config('request.jwt.claims', '', true);
+     select set_config('request.jwt.claim.sub', '', true);
+     select set_config('request.jwt.claim.role', '', true);
+     select agent_board.heartbeat() $$,
+  '22023',
+  null,
+  'HBP-12: service_role must STILL supply p_agent_id — the null default relaxes the signature, not the resolver');
+
+select * from finish();
+rollback;

package/tests/agent_board_ledger_authority.test.sql

@@ -539,12 +539,19 @@ select is(
         or agent_board_test.stripped_body(p.oid) ~* 'update\s+agent_board\.board_memberships\M[^;]*\mset\M[^;]*\mrole\s*='
         or agent_board_test.stripped_body(p.oid) ~* '(insert\s+into|update)\s+agent_board\.board_authority_ceilings\M'
         or agent_board_test.stripped_body(p.oid) ~* 'update\s+agent_board\.boards\M[^;]*\mset\M[^;]*\mrole_gate_enforced\s*='
+        -- BOARDCLAIMPOLICY: boards.claim_policy is the same SHAPE of authority as
+        -- role_gate_enforced above -- a board-level switch deciding what a later gate does
+        -- (there the creator-identity exemption, here whether our ownerless claim guards apply
+        -- at all). Counting it as an authority write is what makes the pairing assertion below
+        -- hold, and is why set_board_claim_policy carries the ledger check.
+        or agent_board_test.stripped_body(p.oid) ~* 'update\s+agent_board\.boards\M[^;]*\mset\M[^;]*\mclaim_policy\s*='
         or agent_board_test.stripped_body(p.oid) ~* 'insert\s+into\s+agent_board\.board_invite_tokens\M')),
   '_fedsession_autojoin_default_board,_redeem_unbounded_invite_for_agent,'
   || '_upsert_board_membership_state,bootstrap_board_owner_memberships,create_board,'
-  || 'create_invite_link,grant_board_role,set_board_authority_ceiling,set_board_role_gate',
+  || 'create_invite_link,grant_board_role,set_board_authority_ceiling,set_board_claim_policy,'
+  || 'set_board_role_gate',
   'the functions that WRITE a board-authority relation — in ANY shape, including a mintable '
-  'invite preset_role — are exactly these nine');
+  'invite preset_role — are exactly these ten');
 
 -- EITHER helper counts as consulting the ledger: the invite redeem path calls the UNLOCKED
 -- predicate (see the migration header), so a side that matched only the share-locking assert
@@ -558,8 +565,8 @@ select is(
       and p.proname not in ('_assert_actor_not_fleet_revoked', '_actor_fleet_revoked')
       and agent_board_test.stripped_body(p.oid) ~ '\m(_assert_actor_not_fleet_revoked|_actor_fleet_revoked)\s*\('),
   '_redeem_unbounded_invite_for_agent,create_board,create_invite_link,grant_board_role,'
-  || 'set_board_authority_ceiling,set_board_role_gate',
-  'the functions that consult the fleet revocation ledger are exactly these six (#280 added '
+  || 'set_board_authority_ceiling,set_board_claim_policy,set_board_role_gate',
+  'the functions that consult the fleet revocation ledger are exactly these seven (#280 added '
   'create_board)');
 
 -- The gate proper: the two sets must differ by EXACTLY the three asserted exemptions, and any
@@ -588,6 +595,7 @@ select is(
              or agent_board_test.stripped_body(p.oid) ~* 'update\s+agent_board\.board_memberships\M[^;]*\mset\M[^;]*\mrole\s*='
              or agent_board_test.stripped_body(p.oid) ~* '(insert\s+into|update)\s+agent_board\.board_authority_ceilings\M'
              or agent_board_test.stripped_body(p.oid) ~* 'update\s+agent_board\.boards\M[^;]*\mset\M[^;]*\mrole_gate_enforced\s*='
+            or agent_board_test.stripped_body(p.oid) ~* 'update\s+agent_board\.boards\M[^;]*\mset\M[^;]*\mclaim_policy\s*='
              or agent_board_test.stripped_body(p.oid) ~* 'insert\s+into\s+agent_board\.board_invite_tokens\M')
               <> (agent_board_test.stripped_body(p.oid) ~ '\m(_assert_actor_not_fleet_revoked|_actor_fleet_revoked)\s*\('))
      ) x),

package/tests/agent_board_write_enforcement_class.test.sql

@@ -528,6 +528,7 @@ select is( -- pgtap-allow-raise-checked
     'agent_board.send_multicast_message(uuid,uuid,jsonb,text,text,text,text,text,text,jsonb)',
     'agent_board.send_multicast_message(uuid,uuid,uuid[],text,text,text,text,text,jsonb)',
     'agent_board.set_board_authority_ceiling(uuid,text,uuid)',
+    'agent_board.set_board_claim_policy(uuid,text)',
     'agent_board.set_board_role_gate(uuid,boolean)',
     'agent_board.set_fleet_receive_policy(uuid,text,text,boolean,uuid,uuid,jsonb)',
     'agent_board.subscribe_callback_endpoint(uuid,uuid,text,text,uuid,jsonb)',
@@ -538,7 +539,7 @@ select is( -- pgtap-allow-raise-checked
     'agent_board.upsert_delegation_policy(uuid,text,jsonb,integer,interval,boolean)',
     'agent_board.verify_callback_endpoint(uuid,uuid,jsonb)'
     ]::text[],
-  '#325: the effect-derived class is exactly these 59 authenticated-executable writer OVERLOADS — per-OID, and TRANSITIVE, so a delegating wrapper whose own body holds no DML is a member rather than a blind spot');
+  '#325: the effect-derived class is exactly these 60 authenticated-executable writer OVERLOADS — per-OID, and TRANSITIVE, so a delegating wrapper whose own body holds no DML is a member rather than a blind spot');
 
 -- WEC-4. THE DELEGATION-CHAIN LIVENESS PIN, and the mitigation for the fail-open inversion the
 -- header describes. Everything above depends on `fn_call_closure()` actually resolving edges; a

package/tests/catalog/p_metadata_parameters.json

@@ -65,6 +65,10 @@
       "signature": "_check_and_bump_child_mint_rate(p_root_agent_id uuid, p_limit integer, p_window interval)",
       "declares_p_metadata": false
     },
+    {
+      "signature": "_claimgate_board_claim_policy(p_thread_id uuid)",
+      "declares_p_metadata": false
+    },
     {
       "signature": "_claimgate_kind_enforced(p_resource_kind text)",
       "declares_p_metadata": false
@@ -645,6 +649,10 @@
       "signature": "set_board_authority_ceiling(p_board_id uuid, p_max_grantable_role text, p_actor_agent_id uuid)",
       "declares_p_metadata": false
     },
+    {
+      "signature": "set_board_claim_policy(p_board_id uuid, p_claim_policy text)",
+      "declares_p_metadata": false
+    },
     {
       "signature": "set_board_role_gate(p_board_id uuid, p_enforced boolean)",
       "declares_p_metadata": false