@bongos/core 1.19.955 → 1.19.956

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.955",
-  "core_contract": "1.19.955",
-  "source_commit": "3595ab322a25adbfb15980ecfbf3277c095e0d4b",
+  "core_version": "1.19.956",
+  "core_contract": "1.19.956",
+  "source_commit": "b5f9ec6f9c84cf59195511dea0bef9cd2f607e00",
   "source_ref": "HEAD",
-  "built_at": "2026-09-22T05:17:25.737Z",
+  "built_at": "2026-09-22T05:46:01.341Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 514,
     "agent_docs_stubbed": 26,
-    "functional_verbatim": 2355,
+    "functional_verbatim": 2357,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2895,
-  "tree_sha256": "cb656bb0b99f15d870988930f28520127a84bbc30f2c897df885ef8139504e4a",
+  "file_count": 2897,
+  "tree_sha256": "37422b79ea02e637ca3a28a909c2d299c5f309190fbda25845bcb1ad6d2765c1",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2692,7 +2692,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "e153e8b45c3cda248dfa42e233d2650353711b41650e7066287d94a43a347fc8"
+      "sha256": "e5152e6018b9378631ce08e502ef244efca8db514fdb5acca5f6da21a6fca155"
     },
     {
       "path": "docs/modules-contract.md",
@@ -6702,7 +6702,12 @@
     {
       "path": "modules/provisioning/pollers/liveness-sweep.js",
       "mode": "0000644",
-      "sha256": "90db999a2e1d3dec2e3910281e2e5dccd55cf294d7c5c38233456c29d71bacd3"
+      "sha256": "b7db2ecae7e3df06646e04f5203a6ac8bbb61b301ccde833d2024d9d2ba64394"
+    },
+    {
+      "path": "modules/provisioning/pollers/runner-drift-notify.js",
+      "mode": "0000644",
+      "sha256": "8d861e41d66c9c14995db3921ab0b225d3abdafceda5edc0029a4020d47fe3b4"
     },
     {
       "path": "modules/provisioning/provisioning.js",
@@ -8072,12 +8077,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "4e5b09dee33c9b46fdc4e4e0a1025df50e79bdcad9ed6be9aee8d81a52d14953"
+      "sha256": "984830848a268de5d21b596133f328532da98025312eb19c55bab1f59bcefd3d"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "e8b75ca994f900a282dedd9e5c0589c151f3e8b0eab513e4c51b4ed254ab34f2"
+      "sha256": "3b5369b5abd11bc15832bd5f20582f76fb70e492e9cf2c79060e01ffd5f288df"
     },
     {
       "path": "public-docs/index.html",
@@ -10082,7 +10087,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a3909e0963c8f56e17bca596d30f27ee3e10100cefb055bf8a2f3506139a18ed"
+      "sha256": "77129f6f2f9471813d98976e7fcac4b9f219507c10960a7b3c6aaa219e862421"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -13249,6 +13254,11 @@
       "mode": "0000644",
       "sha256": "f31a8fc12866f7d639b7472578422e29129db85bbd9ddecb663e753393d74e2a"
     },
+    {
+      "path": "tests/provisioning_runner_drift_notice.mjs",
+      "mode": "0000644",
+      "sha256": "18662f6f446b33a677ffc71dd7115f8e59997d6f86adbadcd91e5e4bdac2fd76"
+    },
     {
       "path": "tests/provisioning_settings.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2384,5 +2384,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.953 with no explicit bump. run 35687914716. (task 1002620)
   1.19.955 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.954 with no explicit bump. run 35690089430. (task 1002620)
+  1.19.956 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.955 with no explicit bump. run 35691908420. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/modules/provisioning/pollers/liveness-sweep.js

@@ -28,12 +28,24 @@ const { Agent: UndiciAgent } = require('undici');
 const api = require('../../../src/module-api');
 const provisioning = require('../provisioning');
 const { planNotices, postNotice } = require('./liveness-notify');
+// task 1004000: the runner-drift check rides this tick rather than installing a timer of
+// its own — the sweep already runs every ~5 min on the one host that can see the systemd
+// units. It reads the checker as a SUBPROCESS, not a require: `scripts/gds/runner-drift.js`
+// is core-package territory (ADR 0083) and its systemctl reads are blocking, so requiring
+// it would have put N×15s of event-loop work in the process serving live traffic. See
+// ./runner-drift-notify.js's header.
+const { planDriftNotices, formatDriftLine, readRunnerDrift } = require('./runner-drift-notify');
 
 // Notice state between sweeps (task 1002894): id → { streak, notified }. In memory
 // on purpose — it is seeded only by a fall this process observed, which is exactly
 // what stops a restarted control plane re-announcing an outage it arrived to find.
 const noticeState = new Map();
-function resetNoticeState() { noticeState.clear(); }
+// Unit names already announced as drifting (task 1004000). In memory like its neighbour,
+// but for the opposite reason: this one exists only to stop a stale runner posting every
+// five minutes forever, NOT to suppress a first sighting — a drift that predates this
+// process is exactly the thing nobody noticed, so a restart re-announcing it is correct.
+const driftState = new Set();
+function resetNoticeState() { noticeState.clear(); driftState.clear(); }
 
 // Name a project in an owner-facing message only when it is public on the platform's
 // map; a private or stealth one is described, never identified.
@@ -241,6 +253,34 @@ async function sweepOnce(deps = {}) {
   for (const notice of plan.notices) {
     try { notify(notice); } catch (e) { log(`[liveness] notice failed (non-blocking): ${e && e.message ? e.message : e}`); }
   }
+
+  // ── runner drift (task 1004000) ───────────────────────────────────────────
+  // Placed at the TAIL, after the account is built and the liveness notices are out, so
+  // that a systemctl hiccup can never cost this tick its liveness verdict — the reason
+  // the whole block is wrapped. `collect` is injected so the composition stays hermetic
+  // in tests; production uses readRunnerDrift, which spawns the checker and answers null
+  // when there is no systemd to ask. AWAITED, and that is the point: the read is a
+  // subprocess rather than a blocking in-process require, so a hung systemctl costs this
+  // tick its drift check and never the event loop serving live requests. Not gated on
+  // `rows.length`: the runners are worth checking on a control plane with no tenant
+  // projects at all.
+  try {
+    const collect = deps.collectRunnerDrift || readRunnerDrift;
+    const instanceRoot = deps.instanceRoot || process.env.BONGOS_INSTANCE_ROOT || process.cwd();
+    const drift = planDriftNotices(await collect({ instanceRoot }), driftState);
+    const line = formatDriftLine(drift);
+    if (line) log(line);
+    for (const notice of drift.notices) {
+      try { notify(notice); } catch (e) { log(`[liveness] drift notice failed (non-blocking): ${e && e.message ? e.message : e}`); }
+    }
+    out.runnerDrift = drift.drifting;
+    out.runnerUnresolved = drift.unresolved;
+  } catch (e) {
+    // A drift check that throws must not take the sweep with it. Logged rather than
+    // swallowed: silence here would be indistinguishable from a healthy host, which is
+    // the exact failure this task was filed about.
+    log(`[drift] check failed (non-blocking): ${e && e.message ? e.message : e}`);
+  }
   return out;
 }
 

package/modules/provisioning/pollers/runner-drift-notify.js

@@ -0,0 +1,203 @@
+'use strict';
+
+// modules/provisioning/pollers/runner-drift-notify.js — say it out loud when an
+// intent-runner unit is pointed at a different core than the instance installed
+// (task 1004000, the follow-up the task 1002722 grade asked for).
+//
+// WHY. Three drift signals already existed and every one of them needed a human to go
+// and look: `scripts/gds/runner-drift.js` exits 1, `bongos doctor` has an "Intent
+// runners" section, and each run-intents tick writes a `⚠ DRIFT:` banner into the
+// journal. A stale runner is exactly the condition nobody is looking for — it drains
+// intents perfectly happily using last month's code — so a signal that waits to be read
+// is a signal that is not doing its job.
+//
+// WHERE IT RUNS. Inside the liveness sweep, not on a timer of its own. The sweep already
+// ticks every ~5 minutes on the control plane, which is the one host that can see the
+// systemd units (CI cannot), and `collectRunnerDrift` is two `systemctl` reads. A second
+// timer would be a second thing to install, a second thing to forget to install, and a
+// second thing whose silence means nothing.
+//
+// HOW IT DIFFERS FROM ITS SIBLING, AND WHY. `./liveness-notify.js` is the pattern here,
+// but two of its three rules are deliberately NOT copied:
+//
+//   * IT ANNOUNCES ON FIRST SIGHT. Liveness stays silent about a project that was already
+//     down before this process started, so that a restarted control plane does not
+//     re-announce an outage it merely arrived to find. Drift is the opposite case: a
+//     runner that has been stale for a fortnight is precisely the thing nobody noticed,
+//     and this task exists because those three signals went unread. Waiting for an edge
+//     would mean the only drift ever announced is drift that begins while the process
+//     happens to be watching.
+//   * THERE IS NO CONFIRM STREAK. Liveness waits out a second sweep because one refused
+//     connection is a blip. Drift is a deterministic read of two files on local disk —
+//     there is no blip to wait out, and a delay would buy nothing but a later notice.
+//
+// The third rule IS copied, and matters more here than there:
+//
+//   * COLLAPSE A FAN-OUT. Every unit drifting at once is one cause — an upgrade moved the
+//     installed core and the units still run the old checkout — so it is ONE message. A
+//     host with several runners would otherwise emit a burst that reads like several
+//     independent faults. Unconditional here rather than threshold-gated; see the note
+//     where liveness's FLEET_GUARD would have been.
+//
+// And one rule of its own:
+//
+//   * `unresolved` IS NOT DRIFT. It means the checker could not tell (an ExecStart that
+//     runs no .js directly, no core version above the script, no installed core). That is
+//     the absence of a verdict, not a bad one, so announcing it would be a siren over
+//     nothing. It is counted into the sweep's log line instead, where it is visible
+//     without being urgent — and a host that is ALL unresolved says so in that line
+//     rather than reading as healthy.
+//
+// HOW IT READS SYSTEMD, AND WHY NOT BY require(). The checker itself is
+// `scripts/gds/runner-drift.js`, which is CORE-package territory: a module may require
+// only the published doorway `src/module-api.js` (ADR 0083, `docs/modules-contract.md`,
+// and this module's own CLAUDE.md header). So this reads it the way its sibling reads
+// `scripts/discord/post.js` — as a SUBPROCESS, `node scripts/gds/runner-drift.js --json`
+// — which crosses no require boundary and needs no new doorway for a fact only the
+// control plane's own host can answer.
+//
+// The subprocess is ALSO the reason this is safe inside the web process. `collectRunnerDrift`
+// uses `spawnSync` with a 15-second timeout per `systemctl` call; requiring it would have
+// put N×15s of blocking work on the event loop that serves live HTTP traffic, once every
+// five minutes. `execFile` is async, so a hung systemctl costs this tick its drift check
+// and nothing else.
+//
+// **A NON-ZERO EXIT IS NOT AN ERROR HERE.** `runner-drift.js` exits 1 precisely WHEN it
+// finds drift — that is its contract as a CI-style gate — so treating a failed exit as a
+// failed read would discard the only result worth reporting. The JSON on stdout is the
+// answer; the exit code is ignored when it parses, and only an unparseable stdout counts
+// as "could not look".
+//
+// PURE except `readRunnerDrift`, which spawns that subprocess, and `postNotice`, which
+// ./liveness-sweep.js imports straight from ./liveness-notify.js — one Discord path, one
+// dry-run switch, one place a webhook change lands.
+
+const { execFile } = require('node:child_process');
+const path = require('node:path');
+
+// scripts/gds/runner-drift.js is invoked from the repo root regardless of cwd, the same
+// way ./liveness-notify.js invokes scripts/discord/post.js.
+const REPO_ROOT = path.resolve(__dirname, '..', '..', '..');
+// Generous next to the checker's own per-call 15s, and it exists so a hung systemctl
+// costs this tick its drift check rather than the tick.
+const READ_TIMEOUT_MS = Number(process.env.PROVISIONING_DRIFT_TIMEOUT_MS) || 30_000;
+
+// Ask the checker what the host's runner units look like. Resolves to the units array, or
+// NULL for "could not look" — no systemd, an unparseable answer, a timeout, a missing
+// script. Null is deliberately not an empty array: "no runner units" and "could not ask"
+// must not read the same, and planDriftNotices treats them differently.
+function readRunnerDrift({ instanceRoot, execFileImpl = execFile, timeoutMs = READ_TIMEOUT_MS } = {}) {
+  return new Promise((resolve) => {
+    let settled = false;
+    const done = (v) => { if (!settled) { settled = true; resolve(v); } };
+    try {
+      execFileImpl('node',
+        ['scripts/gds/runner-drift.js', '--instance-root', String(instanceRoot || ''), '--json'],
+        { cwd: REPO_ROOT, timeout: timeoutMs, maxBuffer: 4 * 1024 * 1024 },
+        (_err, stdout) => {
+          // _err is IGNORED on purpose: exit 1 IS the drift signal (see the header).
+          let parsed = null;
+          try { parsed = JSON.parse(String(stdout || '')); } catch (_) { parsed = null; }
+          if (!parsed || parsed.systemd !== true) return done(null);
+          done(Array.isArray(parsed.units) ? parsed.units : null);
+        });
+    } catch (_) {
+      done(null);
+    }
+  });
+}
+
+// NO FLEET-GUARD KNOB, and the absence is deliberate. ./liveness-notify.js needs one
+// because it posts per PROJECT and a fleet can be large, so "how many at once means look
+// at the platform" is a real threshold. Here the collapse is unconditional: a host runs
+// two or three runner units, every drifting one has the same cause (an upgrade moved the
+// installed core), and the notice is one message whose wording already branches on the
+// count. A tunable that can only ever be 1 or 2 on a population of 2 is a knob that does
+// nothing, and a knob that does nothing still has to be read and reasoned about.
+
+// What the owner reads. Owner-audience and plain: the reader is being told their
+// automation is quietly running old code, and what that means for them. A unit name is
+// operator vocabulary, so it appears once, at the end, for whoever goes to fix it. PURE.
+function driftNoticeText({ kind, units = [], installed = null } = {}) {
+  const n = units.length;
+  if (kind === 'clear') {
+    return n > 1
+      ? `✅ All ${n} background runners are back on the current version.`
+      : `✅ The background runner is back on the current version.`;
+  }
+  const version = installed ? ` The project installed **${installed}**.` : '';
+  const which = units.length ? ` (${units.join(', ')})` : '';
+  if (n > 1) {
+    return `⚠️ ${n} background runners are running an older version of the platform than this project has installed.${version} When that many disagree at once it is almost always one upgrade that moved the code without restarting them, so they are still doing their work with last month's rules — worth pointing them at the new version${which}.`;
+  }
+  return `⚠️ A background runner is running an older version of the platform than this project has installed.${version} It will keep doing its work, but with the older rules, which is the kind of thing that goes unnoticed for weeks — worth pointing it at the new version${which}.`;
+}
+
+// The decision, given this tick's assessment (the rows `collectRunnerDrift` returns) and
+// the notice state carried between ticks. MUTATES `state` (a Set of unit names already
+// announced) and returns what to post; everything else is pure, so the rules above are
+// unit-tested with no systemd, no sweep and no network.
+//
+// `units === null` means there is no systemd to ask — not a healthy host, and not a
+// drifted one. It returns nothing and touches no state, so a checker that cannot run
+// never clears an announcement it also cannot re-make.
+function planDriftNotices(units, state) {
+  if (units === null || units === undefined) {
+    return { notices: [], drifting: 0, unresolved: 0, checked: 0, systemd: false };
+  }
+  const drifting = units.filter((u) => u && u.status === 'drift');
+  const unresolved = units.filter((u) => u && u.status === 'unresolved');
+  const names = drifting.map((u) => u.name);
+
+  // NEW drift only: a unit already announced stays silent until it recovers, so a stale
+  // runner does not post every five minutes for a fortnight.
+  const fresh = names.filter((name) => !state.has(name));
+  // Recovery: a unit we announced that is no longer drifting. Read from the units this
+  // tick actually assessed — a unit that has been REMOVED from the host is not a
+  // recovery and is dropped from the state without a notice, because "the unit is gone"
+  // and "the unit is fixed" are different facts and only one of them is good news.
+  const assessed = new Set(units.map((u) => u && u.name).filter(Boolean));
+  const stillDrifting = new Set(names);
+  const recovered = [...state].filter((name) => assessed.has(name) && !stillDrifting.has(name));
+  const vanished = [...state].filter((name) => !assessed.has(name));
+
+  const notices = [];
+  if (fresh.length) {
+    // The installed version is the same for every unit on the host, so the first one
+    // carries it for the message.
+    const installed = (drifting.find((u) => u.instanceVersion) || {}).instanceVersion || null;
+    notices.push({ kind: 'drift', units: fresh, text: driftNoticeText({ kind: 'drift', units: fresh, installed }) });
+  }
+  if (recovered.length) {
+    notices.push({ kind: 'clear', units: recovered, text: driftNoticeText({ kind: 'clear', units: recovered }) });
+  }
+
+  for (const name of fresh) state.add(name);
+  for (const name of recovered) state.delete(name);
+  for (const name of vanished) state.delete(name);
+
+  return {
+    notices,
+    drifting: drifting.length,
+    unresolved: unresolved.length,
+    checked: units.length,
+    systemd: true,
+  };
+}
+
+// The sweep's one-line account of what the drift check saw. Returns null when there is
+// nothing worth a line — no systemd, or no runner units at all — so a vanilla control
+// plane does not narrate an empty check every five minutes. A host whose every unit is
+// `unresolved` DOES get a line: that is not health, and it must not read as health. PURE.
+function formatDriftLine({ systemd, checked, drifting, unresolved }) {
+  if (!systemd || !checked) return null;
+  if (!drifting && !unresolved) return null;
+  const parts = [`runners=${checked}`];
+  if (drifting) parts.push(`drift=${drifting}`);
+  if (unresolved) parts.push(`unresolved=${unresolved} (cannot tell — not a verdict)`);
+  return `[drift] ${parts.join(' · ')}`;
+}
+
+// postNotice is NOT re-exported: ./liveness-sweep.js imports it straight from
+// ./liveness-notify.js, so a re-export here would be API surface with no caller.
+module.exports = { planDriftNotices, driftNoticeText, formatDriftLine, readRunnerDrift };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.955",
+  "version": "1.19.956",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.955",
+      "version": "1.19.956",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.955",
+  "version": "1.19.956",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.955'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.956'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/provisioning_runner_drift_notice.mjs

@@ -0,0 +1,292 @@
+// tests/provisioning_runner_drift_notice.mjs
+//
+// An intent-runner unit pointed at a different core than the instance installed now says
+// so, once, without anybody looking (task 1004000 — the follow-up the task 1002722 grade
+// asked for).
+//
+// THE DONE-WHEN IS TWO SENTENCES AND BOTH ARE HERE: "a unit repointed at a different core
+// than the installed one produces one notice within one tick, and a healthy host produces
+// none." The first is asserted through the real sweep tick, with a fake `systemctl`
+// reader, so what is proved is the wiring and not only the planner. The second is
+// asserted the same way — silence is a result, and the only way to know it is not the
+// silence of a check that never ran is to prove the tick DID run and chose to say
+// nothing.
+//
+// Also pinned, because each is a way this kind of alert goes wrong:
+//   • ONE notice, not one every five minutes — the state suppresses a repeat
+//   • a FIRST SIGHT is announced, unlike liveness's deliberate silence about an outage
+//     that predates the process (the reason is in runner-drift-notify.js's header, and a
+//     test that got this backwards would look just as green)
+//   • `unresolved` is NOT drift — it is the absence of a verdict, and announcing it would
+//     be a siren over nothing; it reaches the log line instead
+//   • no systemd → nothing said and no state touched, so a checker that cannot run never
+//     clears an announcement it also cannot re-make
+//   • a unit that VANISHES is not a recovery — "it is gone" and "it is fixed" are
+//     different facts and only one is good news
+//   • a drift check that throws does not take the liveness sweep with it
+//
+// DB-free and network-free: the systemctl reader and the notifier are injected.
+//
+// Run:  node tests/provisioning_runner_drift_notice.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { readFileSync } from 'node:fs';
+
+const require = createRequire(import.meta.url);
+const notify = require('../modules/provisioning/pollers/runner-drift-notify.js');
+const sweep = require('../modules/provisioning/pollers/liveness-sweep.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const DRIFTED = { name: 'bongos-intent-runner.service', status: 'drift', runnerVersion: '1.19.900', instanceVersion: '1.19.953', reason: 'runs core 1.19.900 but the instance installed 1.19.953' };
+const HEALTHY = { name: 'bongos-intent-runner.service', status: 'ok', runnerVersion: '1.19.953', instanceVersion: '1.19.953', reason: 'runs core 1.19.953' };
+const UNRESOLVED = { name: 'bongos-intent-runner.service', status: 'unresolved', runnerVersion: null, instanceVersion: '1.19.953', reason: 'ExecStart does not run a .js script directly' };
+
+console.log('the planner:');
+
+t('a drifted unit is announced on FIRST SIGHT, and the message names the installed version', () => {
+  const state = new Set();
+  const r = notify.planDriftNotices([DRIFTED], state);
+  assert.equal(r.notices.length, 1);
+  assert.equal(r.notices[0].kind, 'drift');
+  assert.match(r.notices[0].text, /older version/);
+  assert.match(r.notices[0].text, /1\.19\.953/, 'the installed version is in the message — it is what the runner should be on');
+  assert.match(r.notices[0].text, /bongos-intent-runner\.service/, 'and the unit name, once, for whoever fixes it');
+  assert.equal(r.drifting, 1);
+  // The opposite of liveness's rule, deliberately: drift that predates this process is
+  // exactly what nobody noticed, so a restart re-announcing it is correct.
+  assert.deepEqual([...state], ['bongos-intent-runner.service']);
+});
+
+t('the SECOND tick says nothing — one notice, not one every five minutes', () => {
+  const state = new Set();
+  notify.planDriftNotices([DRIFTED], state);
+  const again = notify.planDriftNotices([DRIFTED], state);
+  assert.deepEqual(again.notices, []);
+  assert.equal(again.drifting, 1, 'still counted in the account, just not re-announced');
+});
+
+t('a recovery is announced once, and then the unit is forgotten', () => {
+  const state = new Set();
+  notify.planDriftNotices([DRIFTED], state);
+  const fixed = notify.planDriftNotices([HEALTHY], state);
+  assert.equal(fixed.notices.length, 1);
+  assert.equal(fixed.notices[0].kind, 'clear');
+  assert.match(fixed.notices[0].text, /back on the current version/);
+  assert.deepEqual([...state], [], 'forgotten, so a later drift is a fresh first sight');
+  assert.deepEqual(notify.planDriftNotices([HEALTHY], state).notices, [], 'and the all-clear is not repeated either');
+});
+
+t('a unit that VANISHES is not a recovery', () => {
+  // "The unit is gone" and "the unit is fixed" are different facts and only one of them
+  // is good news. The state is still cleared, so a reinstated unit is a fresh first sight.
+  const state = new Set();
+  notify.planDriftNotices([DRIFTED], state);
+  const gone = notify.planDriftNotices([], state);
+  assert.deepEqual(gone.notices, [], 'no all-clear for a unit nobody fixed');
+  assert.deepEqual([...state], []);
+});
+
+t('several units drifting at once are ONE message, because they have one cause', () => {
+  const state = new Set();
+  const units = [DRIFTED, { ...DRIFTED, name: 'bongos-box-intent-runner.service' }];
+  const r = notify.planDriftNotices(units, state);
+  assert.equal(r.notices.length, 1, 'one message, not one per unit');
+  assert.match(r.notices[0].text, /2 background runners/);
+  assert.match(r.notices[0].text, /one upgrade that moved the code/, 'and it names the usual cause');
+  assert.equal(r.notices[0].units.length, 2);
+});
+
+t("'unresolved' is NOT drift — no notice, but it does reach the log line", () => {
+  const state = new Set();
+  const r = notify.planDriftNotices([UNRESOLVED], state);
+  assert.deepEqual(r.notices, [], 'the absence of a verdict is not a bad verdict');
+  assert.equal(r.unresolved, 1);
+  assert.equal(r.drifting, 0);
+  assert.deepEqual([...state], []);
+  // Visible without being urgent — and a host that is ALL unresolved must not read as
+  // healthy, which is why the line exists at all.
+  assert.match(notify.formatDriftLine(r), /unresolved=1 \(cannot tell — not a verdict\)/);
+});
+
+t('no systemd says nothing, touches no state, and reports systemd:false', () => {
+  const state = new Set(['bongos-intent-runner.service']);
+  for (const nothing of [null, undefined]) {
+    const r = notify.planDriftNotices(nothing, state);
+    assert.deepEqual(r.notices, []);
+    assert.equal(r.systemd, false);
+    assert.deepEqual([...state], ['bongos-intent-runner.service'],
+      'a checker that cannot run must not clear an announcement it also cannot re-make');
+  }
+});
+
+t('a healthy host produces no log line either — no narration every five minutes', () => {
+  const r = notify.planDriftNotices([HEALTHY], new Set());
+  assert.deepEqual(r.notices, []);
+  assert.equal(notify.formatDriftLine(r), null, 'a vanilla control plane stays quiet');
+  assert.equal(notify.formatDriftLine({ systemd: true, checked: 0, drifting: 0, unresolved: 0 }), null, 'and so does a host with no runner units');
+  assert.match(notify.formatDriftLine({ systemd: true, checked: 2, drifting: 1, unresolved: 0 }), /runners=2 · drift=1/);
+});
+
+console.log('\nthrough the real sweep tick:');
+
+// The sweep's own dependency seam, with no projects to probe: this tick is about the
+// runners. `collectRunnerDrift` is what the production path reads systemd through.
+function tickDeps({ units, notifySpy, logs }) {
+  return {
+    // `pool`, not `db` — sweepOnce's own seam name. Passing the wrong one silently falls
+    // back to the real api.pool and the tick tries to reach Postgres, which is how these
+    // five cases first failed.
+    pool: { query: async () => ({ rows: [] }) },
+    log: (m) => logs.push(String(m)),
+    notify: (n) => notifySpy.push(n),
+    collectRunnerDrift: async () => units,
+    instanceRoot: '/srv/instance',
+  };
+}
+
+// No active instances to probe: this tick is about the runners, and the roster read is
+// the only other thing sweepOnce does before reaching them.
+const provisioning = require('../modules/provisioning/provisioning.js');
+provisioning.listActiveInstancesForLiveness = async () => [];
+
+await ta('DONE-WHEN 1: a repointed unit produces ONE notice within ONE tick', async () => {
+  sweep.resetNoticeState();
+  const notifySpy = [], logs = [];
+  const out = await sweep.sweepOnce(tickDeps({ units: [DRIFTED], notifySpy, logs }));
+  assert.equal(notifySpy.length, 1, `one notice from one tick, got ${notifySpy.length}`);
+  assert.equal(notifySpy[0].kind, 'drift');
+  assert.equal(out.runnerDrift, 1, 'and the tick reports it in its account');
+  assert.ok(logs.some((l) => /\[drift\].*drift=1/.test(l)), 'the journal carries the line too');
+});
+
+await ta('DONE-WHEN 2: a healthy host produces NONE — and the tick demonstrably ran', async () => {
+  sweep.resetNoticeState();
+  const notifySpy = [], logs = [];
+  let asked = 0;
+  const deps = tickDeps({ units: [HEALTHY], notifySpy, logs });
+  const out = await sweep.sweepOnce({ ...deps, collectRunnerDrift: async () => { asked++; return [HEALTHY]; } });
+  assert.equal(notifySpy.length, 0, 'nothing is said');
+  assert.equal(asked, 1, 'and this is NOT the silence of a check that never ran');
+  assert.equal(out.runnerDrift, 0);
+  assert.ok(!logs.some((l) => /\[drift\]/.test(l)), 'no line either — silence all the way down');
+});
+
+await ta('the same drift over two ticks is announced once', async () => {
+  sweep.resetNoticeState();
+  const notifySpy = [], logs = [];
+  const deps = tickDeps({ units: [DRIFTED], notifySpy, logs });
+  await sweep.sweepOnce(deps);
+  await sweep.sweepOnce(deps);
+  assert.equal(notifySpy.length, 1, `the second tick must not re-announce, got ${notifySpy.length}`);
+});
+
+await ta('a drift check that THROWS does not take the sweep with it', async () => {
+  sweep.resetNoticeState();
+  const notifySpy = [], logs = [];
+  const deps = tickDeps({ units: [], notifySpy, logs });
+  const out = await sweep.sweepOnce({ ...deps, collectRunnerDrift: async () => { throw new Error('systemctl exploded'); } });
+  assert.ok(out, 'the tick still returns its liveness account');
+  assert.equal(out.swept, 0);
+  // Logged, not swallowed: silence here is indistinguishable from a healthy host, which
+  // is the exact failure this task was filed about.
+  assert.ok(logs.some((l) => /\[drift\] check failed/.test(l) && /systemctl exploded/.test(l)),
+    `the failure is said out loud: ${logs.join(' | ')}`);
+});
+
+await ta('the check is not gated on there being tenant projects', async () => {
+  // A control plane with no tenants still has runners worth checking — and that is the
+  // host this runs on.
+  sweep.resetNoticeState();
+  const notifySpy = [], logs = [];
+  const out = await sweep.sweepOnce(tickDeps({ units: [DRIFTED], notifySpy, logs }));
+  assert.equal(out.swept, 0, 'no projects at all');
+  assert.equal(notifySpy.length, 1, 'and the drift was still found');
+});
+
+console.log('\nwiring:');
+
+t('the module crosses NO require boundary into core — the checker is a subprocess', () => {
+  // A module may require only src/module-api.js (ADR 0083, docs/modules-contract.md, and
+  // this module's own CLAUDE.md header). scripts/ is core-package territory, so the
+  // checker is read the way the sibling reads scripts/discord/post.js: as a subprocess.
+  // fitness's checkModulesImportOnlyApi does not currently catch a scripts/ target, so
+  // this assertion is the only thing standing between the rule and a silent regression.
+  for (const f of ['runner-drift-notify.js', 'liveness-sweep.js']) {
+    const src = readFileSync(new URL(`../modules/provisioning/pollers/${f}`, import.meta.url), 'utf8');
+    const requires = [...src.matchAll(/require\((['"])([^'"]+)\1\)/g)].map((m) => m[2]);
+    for (const spec of requires) {
+      // src/module-api(.js) is THE doorway and is allowed; everything else under src/ or
+      // scripts/ is not.
+      if (/^(\.\.\/)+src\/module-api(\.js)?$/.test(spec)) continue;
+      assert.ok(!/(^|\/)scripts\//.test(spec) && !/(^|\/)src\//.test(spec),
+        `${f} requires "${spec}" — a module may require only src/module-api.js; spawn a script instead (ADR 0083)`);
+    }
+  }
+  const notifySrc = readFileSync(new URL('../modules/provisioning/pollers/runner-drift-notify.js', import.meta.url), 'utf8');
+  assert.match(notifySrc, /execFile/, 'the checker is spawned');
+  assert.match(notifySrc, /runner-drift\.js', '--instance-root'|scripts\/gds\/runner-drift\.js/, 'and it is the checker that is spawned');
+});
+
+t('postNotice is NOT re-exported — the sweep takes it straight from its owner', () => {
+  // A re-export with no production caller is API surface to keep true for nothing.
+  assert.equal(notify.postNotice, undefined);
+  const sweepSrc = readFileSync(new URL('../modules/provisioning/pollers/liveness-sweep.js', import.meta.url), 'utf8');
+  assert.match(sweepSrc, /const \{ planNotices, postNotice \} = require\('\.\/liveness-notify'\);/,
+    'one Discord path, imported from the file that owns it');
+});
+
+await ta('readRunnerDrift: a NON-ZERO exit is the drift signal, not a failed read', async () => {
+  // runner-drift.js exits 1 exactly WHEN it finds drift — that is its contract as a
+  // CI-style gate. Treating a failed exit as a failed read would discard the only result
+  // worth reporting, so the exit code is ignored whenever stdout parses.
+  const payload = JSON.stringify({ instanceRoot: '/srv/instance', systemd: true, units: [DRIFTED] });
+  const execFileImpl = (_cmd, _args, _opts, cb) => cb(Object.assign(new Error('Command failed'), { code: 1 }), payload, '');
+  const units = await notify.readRunnerDrift({ instanceRoot: '/srv/instance', execFileImpl });
+  assert.equal(units.length, 1);
+  assert.equal(units[0].status, 'drift');
+});
+
+await ta('readRunnerDrift: it spawns the checker with the instance root, from the repo root', async () => {
+  let seen = null;
+  const execFileImpl = (cmd, args, opts, cb) => { seen = { cmd, args, opts }; cb(null, JSON.stringify({ systemd: true, units: [] }), ''); };
+  const units = await notify.readRunnerDrift({ instanceRoot: '/srv/instance', execFileImpl });
+  assert.deepEqual(units, []);
+  assert.equal(seen.cmd, 'node');
+  assert.deepEqual(seen.args, ['scripts/gds/runner-drift.js', '--instance-root', '/srv/instance', '--json']);
+  assert.match(seen.opts.cwd, /cloud-bongos/, 'invoked from the repo root regardless of cwd');
+  assert.ok(seen.opts.timeout > 0, 'a hung systemctl costs the check, not the tick');
+});
+
+await ta('readRunnerDrift: "could not look" is NULL, never an empty array', async () => {
+  // "No runner units" and "could not ask" must not read the same — planDriftNotices
+  // treats them differently, and an empty array would silently clear announcements.
+  const cases = [
+    ['unparseable stdout', (_c, _a, _o, cb) => cb(null, 'systemctl: command not found', '')],
+    ['no systemd', (_c, _a, _o, cb) => cb(null, JSON.stringify({ systemd: false, units: [] }), '')],
+    ['empty stdout', (_c, _a, _o, cb) => cb(new Error('timeout'), '', '')],
+    ['a throwing spawn', () => { throw new Error('ENOENT'); }],
+  ];
+  for (const [why, execFileImpl] of cases) {
+    assert.equal(await notify.readRunnerDrift({ instanceRoot: '/x', execFileImpl }), null, why);
+  }
+  // And the empty-array case really is distinct: a host with systemd and no units.
+  assert.deepEqual(await notify.readRunnerDrift({ instanceRoot: '/x', execFileImpl: (_c, _a, _o, cb) => cb(null, JSON.stringify({ systemd: true, units: [] }), '') }), []);
+});
+
+t('the sweep clears BOTH notice states on reset, or a test leaks into the next one', () => {
+  const src = readFileSync(new URL('../modules/provisioning/pollers/liveness-sweep.js', import.meta.url), 'utf8');
+  assert.match(src, /function resetNoticeState\(\) \{ noticeState\.clear\(\); driftState\.clear\(\); \}/);
+});
+
+console.log(`\nprovisioning_runner_drift_notice: ${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);