@bongos/core 1.19.954 → 1.19.956

package/docs/module-api-changelog.md

@@ -2382,5 +2382,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.952 with no explicit bump. run 35687192774. (task 1002620)
   1.19.954 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         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/env-manifest.js

@@ -0,0 +1,215 @@
+// modules/provisioning/env-manifest.js — the project ENV VAR MANIFEST: the NAMES a
+// project's environment variables have and what each one is for (task 1004062,
+// [ADR 0323](../../docs/adr/0323-hosting-is-three-shapes-and-we-are-not-the-landlord.md)
+// decision 6).
+//
+// **THE ONE RULE: THIS FILE NEVER HANDLES A VALUE.** Not stored, not accepted, not
+// logged, not returned, not encrypted-at-rest — there is nothing to encrypt, because a
+// variable NAME is not a secret (it appears in the source that reads it). The values live
+// on the deployment platform the running application reads them from, which already
+// encrypts, audits and rotates them; Bongos keeping a second copy would make this
+// platform the custodian of other companies' credentials in exchange for nothing the
+// manifest does not already deliver.
+//
+// The rule is enforced rather than stated. `rejectsValueField` is the boundary's answer
+// to a caller that sends one — a LOUD 400, never a silent drop — and
+// `../../tests/provisioning_env_manifest.mjs` asserts both that no row shape carries a
+// value field and that sending one is refused. A silent drop would be worse than storing
+// it: the caller would believe the platform had taken custody.
+//
+// What a manifest buys, and why the owner asked for it: "no project or code base works
+// without this". A builder — human or agent — writing code has to know which variables
+// exist and what each is for, or it invents a name the platform has never heard of and
+// the setup document is incomplete in a way nothing detects until deploy.
+//
+// PURE except the four db functions at the bottom, which take the pool as an argument
+// (the module's own convention — see provisioning.js). Reaches core only through
+// src/module-api.js, and requires this module's own siblings, never another module's.
+
+'use strict';
+
+// Where a variable can apply. Fixed and small on purpose: these are the three the
+// deployment platforms in ADR 0323 decision 3 actually name, and an open-ended list
+// would make "which environments does this project have" a second question nobody asked.
+// Mirrors the CHECK in provisioning_023_env_manifest.sql.
+const ENVIRONMENTS = Object.freeze(['production', 'preview', 'development']);
+
+// The conventional POSIX-ish environment variable name: a letter or underscore, then
+// letters, digits and underscores. UPPERCASE is not enforced — `npm_config_*` and
+// `PORT` coexist in real projects, and refusing a lowercase name a project genuinely
+// reads would make the manifest wrong rather than tidy. PURE.
+const ENV_NAME_RE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+const ENV_NAME_MAX = 128;
+
+function isValidEnvName(name) {
+  const s = typeof name === 'string' ? name.trim() : '';
+  if (!s || s.length > ENV_NAME_MAX) return false;
+  return ENV_NAME_RE.test(s);
+}
+
+// Why a name is being refused, in the words a caller can act on. Returns null when the
+// name is fine. Separate from isValidEnvName so the route's message and the predicate
+// cannot drift. PURE.
+function envNameRefusal(name) {
+  if (typeof name !== 'string' || !name.trim()) return 'A variable needs a name.';
+  const s = name.trim();
+  if (s.length > ENV_NAME_MAX) return `That name is ${s.length} characters; the limit is ${ENV_NAME_MAX}.`;
+  if (/\s/.test(s)) return `"${s}" contains a space — an environment variable name cannot.`;
+  if (/^[0-9]/.test(s)) return `"${s}" starts with a digit — an environment variable name cannot.`;
+  if (!ENV_NAME_RE.test(s)) return `"${s}" is not a valid environment variable name: letters, digits and underscores only, not starting with a digit.`;
+  return null;
+}
+
+// Coerce the caller's environment list to the known set. An ABSENT or empty list means
+// "everywhere", which is stored as all three rather than as an empty array: a variable
+// the code reads is read in every environment unless somebody says otherwise, and
+// storing the explicit set means a later reader never has to know that an empty array
+// was a special case. An unknown entry is dropped here and refused by the route — the
+// drop is the backstop, not the answer. PURE.
+function normalizeEnvironments(list) {
+  if (list === undefined || list === null) return [...ENVIRONMENTS];
+  const arr = Array.isArray(list) ? list : [list];
+  const kept = [];
+  for (const raw of arr) {
+    const s = typeof raw === 'string' ? raw.trim().toLowerCase() : '';
+    if (ENVIRONMENTS.includes(s) && !kept.includes(s)) kept.push(s);
+  }
+  if (kept.length === 0) return [...ENVIRONMENTS];
+  // Stored in the canonical order, so two callers naming the same set produce equal rows
+  // and a diff of two manifests is about content rather than about ordering.
+  return ENVIRONMENTS.filter((e) => kept.includes(e));
+}
+
+// The environments a caller named that are not environments. The route refuses on this
+// rather than silently keeping the remainder: dropping 'staging' would tell the owner
+// their variable applies somewhere it does not. PURE.
+function unknownEnvironments(list) {
+  if (list === undefined || list === null) return [];
+  const arr = Array.isArray(list) ? list : [list];
+  const bad = [];
+  for (const raw of arr) {
+    const s = typeof raw === 'string' ? raw.trim().toLowerCase() : String(raw);
+    if (!ENVIRONMENTS.includes(s) && !bad.includes(s)) bad.push(s);
+  }
+  return bad;
+}
+
+// The field names that would be a VALUE, in every spelling a caller might reach for.
+// Checked as a group so the refusal can name what was sent.
+const VALUE_FIELDS = Object.freeze(['value', 'values', 'secret', 'secret_value', 'val', 'default_value', 'example_value']);
+
+// Refuse a body that carries a value, LOUDLY. Returns null when clean, else a
+// { code, message } the route fails with.
+//
+// Loud and not a silent strip, and the distinction is the whole point: a caller who
+// POSTs a secret and gets a 201 back has every reason to believe the platform now holds
+// it — they may then delete it from the place that actually stores it. A 400 that says
+// "this platform does not take values" leaves them in no doubt, and nothing is written.
+// PURE.
+function rejectsValueField(body) {
+  if (!body || typeof body !== 'object') return null;
+  const sent = VALUE_FIELDS.filter((f) => Object.prototype.hasOwnProperty.call(body, f));
+  if (sent.length === 0) return null;
+  return {
+    code: 'value_not_accepted',
+    message: `This platform stores variable NAMES, never values — ${sent.join(', ')} ${sent.length === 1 ? 'was' : 'were'} not saved and nothing was recorded. Keep the value where the running application reads it (your deployment platform), and declare the name here so builders know it exists.`,
+  };
+}
+
+// The row shape every reader gets. Built by NAMING each column rather than spreading the
+// row, so a value column that somehow appeared in the table could still never leave
+// through this function. The test asserts the absence on this projection.
+function envVarRow(row) {
+  return {
+    id: String(row.id),
+    instance_id: String(row.instance_id),
+    name: row.name,
+    description: row.description ?? null,
+    environments: Array.isArray(row.environments) ? row.environments : [],
+    required: row.required !== false,
+    created_at: row.created_at,
+    updated_at: row.updated_at,
+  };
+}
+
+// ---------------------------------------------------------------------------
+// Storage (the pool is an argument — this module's convention)
+// ---------------------------------------------------------------------------
+
+// The declared surface for one project, name-ordered so two reads of an unchanged
+// manifest are byte-identical (a builder session diffs this).
+async function listEnvVars(db, instanceId) {
+  const { rows } = await db.query(
+    `SELECT * FROM provisioning_env_vars WHERE instance_id = $1 ORDER BY name ASC`,
+    [instanceId]
+  );
+  return rows.map(envVarRow);
+}
+
+// Declare a variable, or EDIT the declaration that name already has. The UNIQUE index on
+// (instance_id, name) makes a second POST an update rather than a duplicate: two rows
+// disagreeing about DATABASE_URL is a manifest that cannot be read, and the reader would
+// have no rule for choosing. Returns { row, created }.
+async function declareEnvVar(db, { instanceId, name, description = null, environments, required = true }) {
+  const { rows } = await db.query(
+    `INSERT INTO provisioning_env_vars (instance_id, name, description, environments, required)
+          VALUES ($1, $2, $3, $4, $5)
+     ON CONFLICT (instance_id, name) DO UPDATE
+            SET description = EXCLUDED.description,
+                environments = EXCLUDED.environments,
+                required = EXCLUDED.required,
+                updated_at = now()
+       RETURNING *, (xmax = 0) AS inserted`,
+    [instanceId, String(name).trim(), description, normalizeEnvironments(environments), required !== false]
+  );
+  return { row: envVarRow(rows[0]), created: rows[0].inserted === true };
+}
+
+// Edit one declaration by id, scoped to its project so a guessed id cannot reach another
+// owner's manifest. MERGE-patch: an omitted field is left alone, which is what lets the
+// hall edit a description without restating the environments. Returns the row, or null
+// when the id does not belong to that project.
+async function updateEnvVar(db, instanceId, id, patch = {}) {
+  const sets = ['updated_at = now()'];
+  const params = [instanceId, id];
+  if (Object.prototype.hasOwnProperty.call(patch, 'description')) {
+    params.push(patch.description === null ? null : String(patch.description));
+    sets.push(`description = $${params.length}`);
+  }
+  if (Object.prototype.hasOwnProperty.call(patch, 'environments')) {
+    params.push(normalizeEnvironments(patch.environments));
+    sets.push(`environments = $${params.length}`);
+  }
+  if (Object.prototype.hasOwnProperty.call(patch, 'required')) {
+    params.push(patch.required !== false);
+    sets.push(`required = $${params.length}`);
+  }
+  if (Object.prototype.hasOwnProperty.call(patch, 'name')) {
+    params.push(String(patch.name).trim());
+    sets.push(`name = $${params.length}`);
+  }
+  const { rows } = await db.query(
+    `UPDATE provisioning_env_vars SET ${sets.join(', ')}
+      WHERE instance_id = $1 AND id = $2 RETURNING *`,
+    params
+  );
+  return rows[0] ? envVarRow(rows[0]) : null;
+}
+
+// Remove one declaration, scoped to its project for the same reason. Returns true when a
+// row went, false when the id was not that project's — the route turns both into the
+// same 404, so a guessed id never confirms another project's contents.
+async function removeEnvVar(db, instanceId, id) {
+  const { rowCount } = await db.query(
+    `DELETE FROM provisioning_env_vars WHERE instance_id = $1 AND id = $2`,
+    [instanceId, id]
+  );
+  return rowCount > 0;
+}
+
+module.exports = {
+  ENVIRONMENTS, ENV_NAME_MAX, VALUE_FIELDS,
+  isValidEnvName, envNameRefusal, normalizeEnvironments, unknownEnvironments,
+  rejectsValueField, envVarRow,
+  listEnvVars, declareEnvVar, updateEnvVar, removeEnvVar,
+};

package/modules/provisioning/migrations/provisioning_023_env_manifest.sql

@@ -0,0 +1,67 @@
+-- provisioning_023 — the project ENV VAR MANIFEST (task 1004062, ADR 0323 decision 6).
+--
+-- **THERE IS NO VALUE COLUMN, AND ADDING ONE IS THE THING THIS TABLE EXISTS TO PREVENT.**
+--
+-- A project's environment variables have two halves. The VALUES live on the deployment
+-- platform the running application reads them from — Vercel, Netlify, Render or the
+-- owner's own machine — which already encrypts, audits and rotates them. Bongos storing
+-- them too would make this platform the custodian of other companies' credentials for no
+-- gain, which is the responsibility ADR 0323 spends its entire budget avoiding.
+--
+-- The half Bongos genuinely needs is the SURFACE: which variables exist and what each one
+-- is for, so a builder — human or agent — writing code references the right names and a
+-- setup document is complete. That is a manifest, not a vault, and a manifest is exactly
+-- this: a name, a sentence, where it applies, and whether it is required.
+--
+-- Not encrypted-at-rest either, because there is nothing here to encrypt. A variable NAME
+-- is not a secret: it appears in the source that reads it. Anyone who can read this table
+-- can already read the repository.
+--
+-- For a `byo-host` project there is no platform to ask, so the manifest is simply
+-- unverifiable — which keeps "Bongos holds no values" true everywhere, with no exception
+-- to reason about later (ADR 0323 decision 6's own wording).
+--
+-- Additive + `provisioning_`-namespaced per ADR 0083 §5: CREATE TABLE IF NOT EXISTS only,
+-- no core table touched, so an instance with this module disabled is unaffected.
+
+CREATE TABLE IF NOT EXISTS provisioning_env_vars (
+  id           bigserial PRIMARY KEY,
+
+  -- The project this declaration belongs to. CASCADE because a manifest is meaningless
+  -- without its project, and ADR 0290's disconnect already relies on the row going with
+  -- it (provisioning_instances cascades its intents, events and manifests the same way).
+  instance_id  bigint NOT NULL REFERENCES provisioning_instances(id) ON DELETE CASCADE,
+
+  -- The variable's NAME, as the application reads it (e.g. 'DATABASE_URL'). Shape is
+  -- enforced in code (env-manifest.js's isValidEnvName) so the refusal can name the rule;
+  -- the length cap here is the backstop a bypassed caller still meets.
+  name         text NOT NULL CHECK (length(name) BETWEEN 1 AND 128),
+
+  -- What the variable is FOR, in a sentence. The whole point of the manifest: a name with
+  -- no purpose tells a builder the surface exists but not what to put behind it.
+  description  text,
+
+  -- Where it applies. An array because one variable is usually read in several
+  -- environments, and a row per environment would make "rename this variable" a
+  -- multi-row edit. The CHECK is a containment test (<@), so it admits any subset —
+  -- including the empty array, which env-manifest.js reads as "everywhere" and never
+  -- writes.
+  environments text[] NOT NULL DEFAULT ARRAY['production','preview','development']::text[]
+    CHECK (environments <@ ARRAY['production','preview','development']::text[]),
+
+  -- Required vs optional. Defaults to required: a variable somebody bothered to declare
+  -- is more often one the application cannot start without, and the safe default for a
+  -- setup checklist is the one that makes an omission visible.
+  required     boolean NOT NULL DEFAULT true,
+
+  created_at   timestamptz NOT NULL DEFAULT now(),
+  updated_at   timestamptz NOT NULL DEFAULT now()
+);
+
+-- One declaration per name per project. A second POST for the same name is an EDIT of
+-- the same declaration, not a duplicate row: two rows saying different things about
+-- DATABASE_URL is a manifest that cannot be read, and the reader would have no rule for
+-- picking. Case-sensitive on purpose — environment variables are, and folding the case
+-- here would silently merge `Path` and `PATH`.
+CREATE UNIQUE INDEX IF NOT EXISTS ux_provisioning_env_vars_instance_name
+  ON provisioning_env_vars (instance_id, name);

package/modules/provisioning/module.json

@@ -1,19 +1,34 @@
 {
   "key": "provisioning",
   "title": "Instance provisioning",
-  "description": "Stand up + operate a Cloud Bongos instance's own infrastructure (server, database, domain, DNS, TLS) via the API, so an owner does not manage infra by hand (ADR 0111). Owns the web-tier REQUEST + STATE surface only: it enqueues provisioning intents + reads instance state — it holds NO cloud-provider tokens and calls NO cloud API. A separate control-plane runner (scripts/gds/provision.js, task P3) is the sole token-holder that drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute WORKLOADS.",
+  "description": "Stand up + operate a Cloud Bongos instance's own infrastructure (server, database, domain, DNS, TLS) via the API, so an owner does not manage infra by hand (ADR 0111). Owns the web-tier REQUEST + STATE surface only: it enqueues provisioning intents + reads instance state \u2014 it holds NO cloud-provider tokens and calls NO cloud API. A separate control-plane runner (scripts/gds/provision.js, task P3) is the sole token-holder that drains the intents. Distinct from the `hosting` module (ADR 0092), which brokers compute WORKLOADS.",
   "coreVersion": "^1.14.0",
   "default": false,
   "author": "Cloud Bongos",
   "origin": "Cloud Bongos core",
   "license": "AGPL-3.0",
   "maintainer": "Cloud Bongos maintainers",
-  "maintenance": { "status": "core-maintained" },
+  "maintenance": {
+    "status": "core-maintained"
+  },
   "contributes": {
-    "routes": ["provisioning", "disconnect", "core-upgrade"],
+    "routes": [
+      "provisioning",
+      "disconnect",
+      "core-upgrade",
+      "env-manifest"
+    ],
     "migrations": true,
-    "pollers": ["liveness-sweep", "catalog-backfill"]
+    "pollers": [
+      "liveness-sweep",
+      "catalog-backfill"
+    ]
   },
-  "provides": ["provisioning.instanceState", "provisioning.projectPlanets", "provisioning.projectOwnedBy", "provisioning.projectPublishIdentity"],
+  "provides": [
+    "provisioning.instanceState",
+    "provisioning.projectPlanets",
+    "provisioning.projectOwnedBy",
+    "provisioning.projectPublishIdentity"
+  ],
   "consumes": []
 }

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 };