@consiliency/agent-board-schema 1.43.0 → 1.44.0

package/fixtures/already-applied.json

@@ -564,6 +564,10 @@
     {
       "id": "20260923000100_agent_board_heartbeat_preserve",
       "sha256": "22713b970564bc59433026f70934758982b4cf7832be9c06197faa2d4ecc0040"
+    },
+    {
+      "id": "20260924000100_agent_board_agent_liveness_denominator",
+      "sha256": "deb58ead6c4d7bbda686b85191d5eb2f2771ae2a405933ffbfbaabd7ad0117d9"
     }
   ]
 }

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.43.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.43.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": 141,
-  "aggregateSha256": "d97c281cbc43a2c031dc769731473c6c9d1aa4facb0f72d07095cd1b9301a163",
+  "migrationCount": 142,
+  "aggregateSha256": "e608fdc22d910cb43f3d31cf32cb5a3316da2d46404150547c9b2b54a74f585a",
   "migrations": [
     {
       "order": 0,
@@ -1317,6 +1317,15 @@
       "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 + 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)', () => {
+  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(141);
+    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,
@@ -262,6 +262,15 @@ describe('manifest integrity', () => {
       // 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/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