@consiliency/agent-board-schema 1.42.0 → 1.44.0

package/fixtures/already-applied.json

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

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/migrations/20260924000100_agent_board_agent_liveness_denominator.sql

@@ -0,0 +1,169 @@
+-- #367 — a liveness reader that cannot report "all clear" about a fleet it is not watching.
+--
+-- THE DEFECT THIS CLOSES. `v_ops_presence_heartbeats` selects FROM `agent_board.presence`:
+--
+--   from agent_board.presence p
+--   join agent_board.agents a on a.id = p.agent_id
+--   where p.expires_at < now();
+--
+-- `presence` is an upsert keyed by `agent_id`, written only by `heartbeat`. An agent that has
+-- NEVER heartbeated has no row, and a row that does not exist cannot be expired. So that view
+-- detects exactly one thing: "was reporting, then stopped". It is structurally blind to
+-- "never reported."
+--
+-- MEASURED, not theorised. On the canonical project on 2026-08-29, immediately after #366 shipped
+-- the writer half: `presence` held 0 rows while 8 agents were `status = 'active'`. Every one of
+-- them was unmonitored, and `select * from v_ops_presence_heartbeats` returned zero rows — output
+-- byte-identical to a fleet in perfect health. That is an absence of signal carrying an alarm's
+-- authority, which is worse than no reader at all, because a reader is something people trust.
+--
+-- THE FIX IS THE JOIN DIRECTION. This view selects FROM `agents` and LEFT JOINs `presence`, so a
+-- never-reporting agent is NAMED rather than missing. That is the whole idea; everything else here
+-- follows from it.
+--
+-- WHAT THIS DELIBERATELY DOES NOT CLAIM. #367 offers two shapes: (1) scope the claim to what the
+-- data supports, and (2) establish an expectation so that never-reporting is itself an anomaly.
+-- This is (1). `never_reported` is a REPORTED STATE, not a judgement — the view says "this agent
+-- has no presence row", never "this agent is stalled". Shape (2) would require deciding what
+-- "expected to be alive" means for an agent that is idle by design, and #366 is deliberate that an
+-- agent waiting on a human is indistinguishable from a stalled one from outside the process.
+-- Naming the state without asserting it is abnormal is how this stays honest while still being
+-- strictly more informative than the view it complements.
+--
+-- WHY THE SUMMARY FUNCTION EXISTS AT ALL. A caller that reads only rows still cannot tell
+-- "0 stale agents" from "nobody reports". The summary always emits `active_agents` alongside
+-- `reporting_agents`, so an empty stale set is reported as `0 stale of 3 reporting, of 8 active`
+-- and can never be rendered as "all clear". #367's first acceptance criterion is that the
+-- denominator appears in the output; putting it in a function rather than in a comment is what
+-- makes that mechanical.
+
+-- ---------------------------------------------------------------------------
+-- The view. `security_invoker` so RLS on `agents`/`presence` applies to the READER, matching
+-- every other view in agent_board — a definer view here would hand every caller a fleet-wide
+-- roster regardless of what they may see.
+-- ---------------------------------------------------------------------------
+create or replace view agent_board.v_agent_liveness
+with (security_invoker = true)
+as
+select
+  a.id                                        as agent_id,
+  a.handle                                    as agent_handle,
+  -- The vocabulary is closed and total: every active agent lands in exactly one of these.
+  -- `never_reported` is FIRST because it is the case the view exists to make visible.
+  case
+    when p.agent_id is null      then 'never_reported'
+    when p.expires_at < now()    then 'stale'
+    else                              'fresh'
+  end                                         as liveness_state,
+  p.availability,
+  p.thread_id,
+  p.activity_summary,
+  p.last_heartbeat_at,
+  p.expires_at,
+  -- NULL rather than a number for a never-reporting agent. A zero here would read as
+  -- "reported just now", which is the opposite of the truth.
+  case
+    when p.last_heartbeat_at is null then null
+    else round(extract(epoch from (now() - p.last_heartbeat_at)) / 60.0, 2)
+  end                                         as heartbeat_lag_minutes
+from agent_board.agents a
+left join agent_board.presence p on p.agent_id = a.id
+where a.status = 'active';
+
+comment on view agent_board.v_agent_liveness is
+  '#367 liveness reader. Selects FROM agents and LEFT JOINs presence, so an agent that has NEVER '
+  'heartbeated is NAMED with liveness_state = never_reported rather than being absent — the blind '
+  'spot in v_ops_presence_heartbeats, which selects from presence and therefore cannot see an '
+  'agent with no row. liveness_state is one of never_reported / stale / fresh and is a REPORTED '
+  'STATE, not a judgement: never_reported means "no presence row", NOT "stalled". Deciding that '
+  'idleness is abnormal is #367 shape (2) and is deliberately not done here. security_invoker, so '
+  'RLS applies to the reader.';
+
+-- ---------------------------------------------------------------------------
+-- The summary. Its ONLY job is to make an empty result impossible to misread.
+-- ---------------------------------------------------------------------------
+create or replace function agent_board.agent_liveness_summary()
+returns table(
+  active_agents    integer,
+  reporting_agents integer,
+  fresh            integer,
+  stale            integer,
+  never_reported   integer
+)
+language sql
+stable
+security invoker
+set search_path = agent_board, public
+as $$
+  select
+    count(*)::integer                                                as active_agents,
+    count(*) filter (where liveness_state <> 'never_reported')::integer as reporting_agents,
+    count(*) filter (where liveness_state = 'fresh')::integer        as fresh,
+    count(*) filter (where liveness_state = 'stale')::integer        as stale,
+    count(*) filter (where liveness_state = 'never_reported')::integer as never_reported
+  from agent_board.v_agent_liveness;
+$$;
+
+comment on function agent_board.agent_liveness_summary() is
+  '#367 denominator. Returns active_agents and reporting_agents ALONGSIDE the stale count, so a '
+  'caller can never render "0 stale" as "all clear" — 0 stale of 0 reporting, of 8 active, is an '
+  'unmonitored fleet, and it reads as one. The four state counts sum to active_agents by '
+  'construction because v_agent_liveness assigns every active agent exactly one state. '
+  'security invoker + stable: it is a projection of the view and inherits the caller''s RLS.';
+
+-- ---------------------------------------------------------------------------
+-- The OLD view is left in service deliberately — it answers a narrower question correctly and
+-- operators' saved queries reference it — but it now carries its own blind spot in the catalog.
+-- Two review seats independently made the same point: shipping a fix while the DOCUMENTED alarm
+-- path still has the defect closes an issue without closing the exposure. `specs/operations.md`
+-- was repointed in the same change; this comment is for whoever reads the catalog instead.
+-- ---------------------------------------------------------------------------
+comment on view agent_board.v_ops_presence_heartbeats is
+  'Expired presence leases. BLIND SPOT, by construction: it selects FROM presence, and presence '
+  'has no row for an agent that has NEVER heartbeated — so this detects only "was reporting, then '
+  'stopped" and an empty result is byte-identical to a healthy fleet. Measured 2026-08-29 on the '
+  'canonical project: 0 presence rows, 8 active agents, this view returned nothing. For "who in '
+  'the fleet is alive" use agent_board.v_agent_liveness and agent_board.agent_liveness_summary() '
+  '(#367), which select FROM agents and state their denominator. This view remains correct for '
+  'the narrower question it actually answers.';
+
+-- ---------------------------------------------------------------------------
+-- SERVICE_ROLE ONLY, and this is the most important line in the file.
+--
+-- The first version of this migration granted both to `authenticated` as well, reasoning that
+-- `security_invoker` made that safe because RLS would apply to the reader. That reasoning was
+-- exactly backwards, and a red-team review seat found it. RLS does not merely LIMIT what an
+-- authenticated caller sees here — it CHANGES WHAT THE ANSWER MEANS:
+--
+--   * `agents`   is `using (current_agent_id() is not null)`  → an agent sees EVERY agent row.
+--   * `presence` is `using (agent_id = current_agent_id())`   → an agent sees ONLY ITS OWN row.
+--
+-- So for an authenticated caller the LEFT JOIN converts "this row is invisible to you" into
+-- `p.agent_id is null`, which this view then labels `never_reported`. Measured on a local cluster
+-- with TWO genuinely healthy agents, both with fresh presence rows:
+--
+--   as service_role            → fresh=2  never_reported=0     (true)
+--   as authenticated agent one → fresh=1  never_reported=1     (FABRICATED)
+--
+-- The reader would invent the exact alarm it exists to report, and it would do so confidently and
+-- per-caller, so two readers would disagree with no way to tell which was right. That is strictly
+-- worse than the blind spot this migration closes: `v_ops_presence_heartbeats` UNDER-reports
+-- (silence), and this would OVER-report (a false positive with an agent's name on it).
+--
+-- An authenticated agent cannot answer "who in the fleet is alive" at all, because it cannot see
+-- anyone else's presence. That is a property of the RLS model, not a gap in this view, and the
+-- honest response is to withhold the surface rather than to serve a per-caller answer that reads
+-- like a fleet-wide one. Liveness is an operations question and this is an operations surface.
+--
+-- `security_invoker` is KEPT even though only service_role is granted: it is defence in depth, so
+-- that if a future migration widens the grant the rows are still RLS-filtered rather than leaked
+-- wholesale. AL-9 pins the grant so widening it fails a test that says why.
+-- ---------------------------------------------------------------------------
+grant select on agent_board.v_agent_liveness to service_role;
+
+-- The REVOKE is not redundant, and AL-9b caught it missing. A newly created function is granted
+-- EXECUTE to PUBLIC by default, so `authenticated` inherits it through PUBLIC and granting only
+-- service_role above changes nothing on its own. This is the schema-mechanics trap AGENTS.md
+-- names, arriving on a plain `create or replace function` rather than on a DROP.
+revoke all on function agent_board.agent_liveness_summary() from public;
+grant execute on function agent_board.agent_liveness_summary() to service_role;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@consiliency/agent-board-schema",
-  "version": "1.42.0",
+  "version": "1.44.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.44.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": 142,
+  "aggregateSha256": "e608fdc22d910cb43f3d31cf32cb5a3316da2d46404150547c9b2b54a74f585a",
   "migrations": [
     {
       "order": 0,
@@ -1308,6 +1308,24 @@
       "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"
+    },
+    {
+      "order": 141,
+      "id": "20260924000100_agent_board_agent_liveness_denominator",
+      "filename": "20260924000100_agent_board_agent_liveness_denominator.sql",
+      "origin": "message-board-forward",
+      "sourceRef": "message-board",
+      "bytes": 10530,
+      "sha256": "deb58ead6c4d7bbda686b85191d5eb2f2771ae2a405933ffbfbaabd7ad0117d9"
     }
   ],
   "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 + one LIVENESSDENOM 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 + 1 = 142)', () => {
     expect(manifest.migrationCount).toBe(manifest.migrations.length);
-    expect(manifest.migrationCount).toBe(140);
+    expect(manifest.migrationCount).toBe(142);
     // 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,24 @@ 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',
+      // #367 LIVENESSDENOM. v_ops_presence_heartbeats selects FROM presence, and presence has no
+      // row for an agent that never heartbeated -- so it detects only "was reporting, then
+      // stopped" and is structurally blind to "never reported". Measured on the canonical project
+      // the day #366 shipped the writer half: 0 presence rows, 8 active agents, and the view
+      // returned zero rows, which is byte-identical to a healthy fleet. v_agent_liveness selects
+      // FROM agents and LEFT JOINs presence so a never-reporting agent is NAMED, and
+      // agent_liveness_summary() always emits reporting_agents beside the stale count so a caller
+      // cannot render "0 stale" as "all clear".
+      '20260924000100_agent_board_agent_liveness_denominator.sql',
     ]) {
       expect(names.has(f)).toBe(true);
     }

package/tests/agent_board_agent_liveness.test.sql

@@ -0,0 +1,271 @@
+-- #367 — the reader must not be able to say "all clear" about a fleet it is not watching.
+--
+-- AL-3 IS THE ASSERTION THIS FILE EXISTS FOR, and it is written as a DIFFERENTIAL against the
+-- view it complements. Asserting only "v_agent_liveness names the never-reporting agent" would
+-- pass against a view that names everything and prove nothing about the defect; asserting only
+-- "v_ops_presence_heartbeats misses it" would be a test of code this migration does not change.
+-- Scoring BOTH surfaces on the SAME agent in the SAME transaction is what makes the assertion
+-- about the difference rather than about either one.
+--
+-- AL-6 IS THE OTHER HALF, and it is the one that would have caught the real incident. It builds
+-- the exact production shape — active agents, ZERO presence rows — and asserts the summary reports
+-- `0 stale of 0 reporting, of N active`. A reader that returned "0 stale" alone is byte-identical
+-- to a healthy fleet, which is what made the blind spot dangerous rather than merely incomplete.
+--
+-- SCOPING. Every assertion is scoped to THIS test's agents by handle prefix. An unscoped count
+-- over agent_board.agents is polluted by every fixture any other test left behind and fails
+-- looking like a real defect.
+create extension if not exists pgtap with schema extensions;
+set search_path = extensions, public, agent_board;
+
+begin;
+
+select plan(17);
+
+-- ---------------------------------------------------------------------------
+-- Fixture: three ACTIVE agents in three distinct liveness states, plus one INACTIVE agent that
+-- must not appear at all.
+--   fresh   — heartbeated, lease in the future
+--   stale   — heartbeated, lease in the past
+--   never   — no presence row, which is the case the view exists to surface
+--   retired — status <> 'active'; a liveness reader must not name a decommissioned agent
+-- ---------------------------------------------------------------------------
+create temp table _al (sfx text, fresh uuid, stale uuid, never uuid, retired uuid) on commit drop;
+
+do $$
+declare
+  v_sfx text := replace(substr(gen_random_uuid()::text, 1, 8), '-', '');
+  v_fresh uuid := gen_random_uuid();
+  v_stale uuid := gen_random_uuid();
+  v_never uuid := gen_random_uuid();
+  v_retired uuid := gen_random_uuid();
+  v_u uuid;
+begin
+  foreach v_u in array array[v_fresh, v_stale, v_never, v_retired] loop
+    null;
+  end loop;
+
+  insert into agent_board.agents(id, agent_type, handle, display_name, status)
+  values (v_fresh,   'agent', 'al-fresh-'   || v_sfx, 'AL Fresh',   'active'),
+         (v_stale,   'agent', 'al-stale-'   || v_sfx, 'AL Stale',   'active'),
+         (v_never,   'agent', 'al-never-'   || v_sfx, 'AL Never',   'active'),
+         (v_retired, 'agent', 'al-retired-' || v_sfx, 'AL Retired', 'inactive');
+
+  -- Presence rows written DIRECTLY rather than through heartbeat(): this file is about the
+  -- reader, and going through the RPC would couple it to the actor-resolution path #366 owns.
+  insert into agent_board.presence(agent_id, availability, last_heartbeat_at, expires_at, metadata, updated_at)
+  values (v_fresh, 'busy', now() - interval '1 minute',  now() + interval '20 minutes', '{}'::jsonb, now()),
+         (v_stale, 'away', now() - interval '2 hours',   now() - interval '90 minutes', '{}'::jsonb, now());
+
+  insert into _al values (v_sfx, v_fresh, v_stale, v_never, v_retired);
+end $$;
+
+-- ---------------------------------------------------------------------------
+-- AL-1..3: the three states, and the differential that names the defect.
+-- ---------------------------------------------------------------------------
+select is(
+  (select liveness_state from agent_board.v_agent_liveness where agent_id = (select fresh from _al)),
+  'fresh',
+  'AL-1: an agent with an unexpired lease reads fresh');
+
+select is(
+  (select liveness_state from agent_board.v_agent_liveness where agent_id = (select stale from _al)),
+  'stale',
+  'AL-2: an agent whose lease has passed reads stale');
+
+select is(
+  (select liveness_state from agent_board.v_agent_liveness where agent_id = (select never from _al)),
+  'never_reported',
+  'AL-3 THE POINT: an agent with NO presence row is NAMED never_reported rather than being absent');
+
+-- The differential. Same agent, same transaction, the pre-existing surface — which selects FROM
+-- presence and therefore cannot see it. If this ever returns a row, the blind spot closed
+-- somewhere else and AL-3 has stopped being about anything.
+select is(
+  (select count(*)::int from agent_board.v_ops_presence_heartbeats where agent_id = (select never from _al)),
+  0,
+  'AL-3b DIFFERENTIAL: v_ops_presence_heartbeats CANNOT see that same agent — which is why AL-3 is a fix and not a restatement');
+
+-- ---------------------------------------------------------------------------
+-- AL-4: a decommissioned agent is not a liveness subject. Without the status filter every agent
+-- ever created accumulates in the never_reported bucket and the signal drowns.
+-- ---------------------------------------------------------------------------
+select is(
+  (select count(*)::int from agent_board.v_agent_liveness where agent_id = (select retired from _al)),
+  0,
+  'AL-4: an inactive agent does not appear at all — a liveness reader must not name a decommissioned agent');
+
+-- ---------------------------------------------------------------------------
+-- AL-5: the lag column. NULL for a never-reporting agent, because 0 would read as
+-- "reported just now" — the exact inversion of the truth.
+-- ---------------------------------------------------------------------------
+select is(
+  (select heartbeat_lag_minutes from agent_board.v_agent_liveness where agent_id = (select never from _al)),
+  null,
+  'AL-5: heartbeat_lag_minutes is NULL for a never-reporting agent, never 0 — a zero would read as "reported just now"');
+
+select ok(
+  (select heartbeat_lag_minutes > 100 from agent_board.v_agent_liveness where agent_id = (select stale from _al)),
+  'AL-5b: and it is a real elapsed figure for one that did report (2h ago reads as >100 minutes)');
+
+-- ---------------------------------------------------------------------------
+-- AL-6: THE DENOMINATOR, built as the production shape that motivated the issue.
+--
+-- Scored on a scoped recomputation rather than on the global summary, because the summary counts
+-- every active agent in the database and other fixtures pollute it. The PROPERTY under test is
+-- "the reader states reporting alongside stale", and it holds per-subset exactly as it holds
+-- globally.
+-- ---------------------------------------------------------------------------
+select is(
+  (select
+     count(*) filter (where liveness_state <> 'never_reported')::text || ' reporting of ' ||
+     count(*)::text || ' active, ' ||
+     count(*) filter (where liveness_state = 'stale')::text || ' stale'
+   from agent_board.v_agent_liveness
+   where agent_handle like 'al-%' || (select sfx from _al)),
+  '2 reporting of 3 active, 1 stale',
+  'AL-6: the reader states REPORTING alongside STALE, so a count can never be read without its denominator');
+
+-- The real incident shape: active agents, nothing reporting. Deleting this fixture's presence
+-- rows reproduces `presence_rows = 0, active_agents = 8` from the canonical project.
+delete from agent_board.presence
+ where agent_id in (select fresh from _al union all select stale from _al);
+
+select is(
+  (select
+     count(*) filter (where liveness_state = 'stale')::text || ' stale of ' ||
+     count(*) filter (where liveness_state <> 'never_reported')::text || ' reporting, of ' ||
+     count(*)::text || ' active'
+   from agent_board.v_agent_liveness
+   where agent_handle like 'al-%' || (select sfx from _al)),
+  '0 stale of 0 reporting, of 3 active',
+  'AL-6b THE INCIDENT SHAPE: with nothing reporting, the output says so — "0 stale" alone would be byte-identical to a healthy fleet');
+
+-- ---------------------------------------------------------------------------
+-- THE ASYMMETRY BELOW IS LOAD-BEARING FOR AL-7b AND AL-10, and neither had it at first.
+-- AL-6b has just deleted this fixture's presence rows, and the persistent seeds carry active
+-- agents with NO presence rows, so at this point the whole database is fresh=0 and stale=0. Every
+-- comparison downstream then scores 0-against-0 and reads as agreement: AL-7b reduced to
+-- `reporting_agents = 0` (so a `reporting_agents` hardcoded to 0 passed it), and AL-10 compared
+-- '0/0' to '0/0' (so swapping the fresh/stale predicates passed it). Two review seats found the
+-- first; the mutation battery found the second. Restoring exactly ONE fresh row is the minimum
+-- state in which either mutation is observable at all.
+insert into agent_board.presence(agent_id, availability, last_heartbeat_at, expires_at, metadata, updated_at)
+values ((select never from _al), 'ready', now(), now() + interval '20 minutes', '{}'::jsonb, now());
+
+-- AL-7: the summary function is TOTAL — the four state counts sum to active_agents. If a fourth
+-- state is ever added to the view's CASE without being added to the function, this fails.
+-- ---------------------------------------------------------------------------
+select is(
+  (select fresh + stale + never_reported from agent_board.agent_liveness_summary()),
+  (select active_agents from agent_board.agent_liveness_summary()),
+  'AL-7: the state counts sum to active_agents — a new state that the summary does not count fails here');
+
+-- ---------------------------------------------------------------------------
+-- AL-7b: THE SUMMARY'S OWN reporting_agents, and this assertion exists because the mutation
+-- battery found it missing. Corrupting `reporting_agents` to `count(*)` — so an entirely
+-- unmonitored fleet reports full participation — produced NO failure anywhere in this file.
+-- AL-6/AL-6b recompute the denominator FROM THE VIEW and never call the summary at all, and AL-7's
+-- sum is unaffected by that field. So the one column that makes the denominator mechanical was
+-- unasserted, while the migration's comment claimed it was the point of the function.
+--
+-- Scored as a RELATIONSHIP rather than a literal, because the summary is global and every other
+-- test's fixtures are in it: `reporting_agents` must equal `fresh + stale`. That holds under any
+-- amount of pollution, and it is discriminating here precisely because this file's fixture
+-- guarantees at least one never-reporting agent exists — so active_agents is strictly greater,
+-- and a reporting_agents that counted everyone fails.
+-- ---------------------------------------------------------------------------
+select is(
+  (select reporting_agents from agent_board.agent_liveness_summary()),
+  (select fresh + stale from agent_board.agent_liveness_summary()),
+  'AL-7b: the summary''s OWN reporting_agents equals fresh + stale — a denominator that counted never-reporting agents as reporting would say an unmonitored fleet was fully participating');
+
+-- ---------------------------------------------------------------------------
+-- AL-8: security_invoker, asserted from the catalog. A definer view here would hand every caller
+-- a fleet-wide roster regardless of what RLS says they may see.
+-- ---------------------------------------------------------------------------
+select ok(
+  (select 'security_invoker=true' = any(c.reloptions)
+     from pg_class c join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = 'agent_board' and c.relname = 'v_agent_liveness'),
+  'AL-8: the view is security_invoker — RLS applies to the reader, not to the view owner');
+
+select ok(
+  (select not p.prosecdef
+     from pg_proc p join pg_namespace n on n.oid = p.pronamespace
+    where n.nspname = 'agent_board' and p.proname = 'agent_liveness_summary'),
+  'AL-8b: the SUMMARY is not SECURITY DEFINER either — AL-8 inspects only the view, so a definer function over an invoker view would silently restore the fleet-wide read this design refuses');
+
+-- ---------------------------------------------------------------------------
+-- AL-9: SERVICE_ROLE ONLY. The blocking finding of this PR's review.
+--
+-- The first version granted both surfaces to `authenticated` too, on the reasoning that
+-- security_invoker made it safe. RLS does not just limit what an authenticated caller sees here —
+-- it changes what the answer MEANS. `agents` is readable by any agent; `presence` is own-row only.
+-- So the LEFT JOIN turns "invisible to you" into `never_reported`, and the view FABRICATES the
+-- alarm it exists to report. Measured with two genuinely healthy agents: service_role saw
+-- fresh=2/never=0, an authenticated caller saw fresh=1/never=1.
+--
+-- Asserted via has_*_privilege rather than by reading pg_class.relacl, because that resolves
+-- inherited and PUBLIC-default grants which a direct ACL read cannot see.
+-- ---------------------------------------------------------------------------
+select is(
+  (select coalesce(string_agg(r, ', ' order by r), '')
+     from unnest(array['anon','authenticated','service_role']) r
+    where has_table_privilege(r, 'agent_board.v_agent_liveness', 'select')),
+  'service_role',
+  'AL-9 SECURITY: only service_role may read the view — granted to authenticated it would report never_reported for every agent whose presence row RLS hides, fabricating alarms about healthy agents');
+
+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.agent_liveness_summary()', 'execute')),
+  'service_role',
+  'AL-9b: and the summary is service_role only for the same reason — its denominator is per-caller under RLS, so two readers would disagree with no way to say which was right');
+
+-- ---------------------------------------------------------------------------
+-- AL-10: the summary's fresh/stale are the VIEW's fresh/stale. AL-7/7b assert only SUMS, and a
+-- review seat pointed out that swapping the two predicates inside agent_liveness_summary() leaves
+-- every one of them green: both identities still hold and nothing checked the values themselves.
+-- Scored as an identity against the view so it is immune to other fixtures' pollution.
+--
+-- THE ASYMMETRY BELOW IS LOAD-BEARING, and the first version of this assertion did not have it.
+-- AL-6b has just deleted this fixture's presence rows, so at this point fresh = 0 and stale = 0 --
+-- and '0/0' equals '0/0' whichever way round the two predicates are. The assertion scored a
+-- VACUOUS MATCH and read as agreement; the swap mutation ran clean against it. Restoring exactly
+-- ONE fresh row makes the two counts differ, which is the minimum condition under which a swap is
+-- observable at all. Measured, not reasoned: the mutation fails this line now and did not before.
+-- ---------------------------------------------------------------------------
+select is(
+  (select fresh || '/' || stale from agent_board.agent_liveness_summary()),
+  (select
+     (count(*) filter (where liveness_state = 'fresh'))::text || '/' ||
+     (count(*) filter (where liveness_state = 'stale'))::text
+   from agent_board.v_agent_liveness),
+  'AL-10: the summary''s fresh and stale ARE the view''s fresh and stale — swapping the two predicates inside the function keeps every sum identity true and is invisible without this');
+
+-- ---------------------------------------------------------------------------
+-- AL-11: THE CLASS, from the catalog rather than from a list written here (rule 1).
+--
+-- The claim this migration makes is "v_ops_presence_heartbeats is the surface with the blind
+-- spot". That was checked by enumerating pg_views rather than by reading the diff, and the answer
+-- was yes — but a claim checked once is a claim about the moment it was checked. This asserts the
+-- membership so a NEW view over presence fails here and NAMES ITSELF, forcing whoever adds it to
+-- state its join direction.
+--
+-- Each member's claim is asserted POSITIVELY in the message rather than by absence from a list:
+--   v_agent_dashboard        FROM agents LEFT JOIN presence  — correct direction, no blind spot
+--   v_agent_liveness         FROM agents LEFT JOIN presence  — this migration
+--   v_ops_presence_heartbeats FROM presence JOIN agents      — the blind spot, kept deliberately
+--   v_ops_table_growth       names 'presence' as a row-count subject, not a liveness reader
+-- ---------------------------------------------------------------------------
+select is(
+  (select string_agg(c.relname, ', ' order by c.relname)
+     from pg_class c join pg_namespace n on n.oid = c.relnamespace
+    where n.nspname = 'agent_board' and c.relkind = 'v'
+      and pg_get_viewdef(c.oid) ~ 'presence'),
+  'v_agent_dashboard, v_agent_liveness, v_ops_presence_heartbeats, v_ops_table_growth',
+  'AL-11 CLASS: exactly these four agent_board views read presence — a new one fails here and names itself, so its join direction gets stated instead of assumed');
+
+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/catalog/p_metadata_parameters.json

@@ -321,6 +321,10 @@
       "signature": "add_artifact(p_created_by_agent_id uuid, p_uri text, p_artifact_type text, p_storage_kind text, p_thread_id uuid, p_task_id uuid, p_message_id uuid, p_task_event_id uuid, p_metadata jsonb)",
       "declares_p_metadata": true
     },
+    {
+      "signature": "agent_liveness_summary()",
+      "declares_p_metadata": false
+    },
     {
       "signature": "append_task_event(p_task_id uuid, p_actor_agent_id uuid, p_event_type text, p_payload jsonb, p_status text, p_assigned_agent_id uuid, p_completed_at timestamp with time zone)",
       "declares_p_metadata": false