@consiliency/agent-board-schema 1.42.0 → 1.43.0

package/fixtures/already-applied.json

@@ -560,6 +560,10 @@
     {
       "id": "20260922000100_agent_board_board_claim_policy",
       "sha256": "1363a194f50342feb613a1aa1e01321a2a81783d88dfebe2c8f2002170cdc25c"
+    },
+    {
+      "id": "20260923000100_agent_board_heartbeat_preserve",
+      "sha256": "22713b970564bc59433026f70934758982b4cf7832be9c06197faa2d4ecc0040"
     }
   ]
 }

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.42.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.42.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": 140,
-  "aggregateSha256": "d82adb3013e8a1118ecae11a3aff4d3f0e7b6f7d53f7116d9565d22b2eca1e93",
+  "migrationCount": 141,
+  "aggregateSha256": "d97c281cbc43a2c031dc769731473c6c9d1aa4facb0f72d07095cd1b9301a163",
   "migrations": [
     {
       "order": 0,
@@ -1308,6 +1308,15 @@
       "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 + one BOARDCLAIMPOLICY 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 = 140)', () => {
+  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(140);
+    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,
@@ -253,6 +253,15 @@ describe('manifest integrity', () => {
       // 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_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;