mandrel-platform 0.29.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "0.29.0",
+  "version": "1.0.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {

package/scripts/check-affected-mode.test.mjs

@@ -0,0 +1,228 @@
+#!/usr/bin/env node
+/**
+ * check-affected-mode.test.mjs — YAML-level regression guard for the
+ * affected-mode wiring in `.github/workflows/pr-quality.yml` (Story #319,
+ * follow-up to #314/#315).
+ *
+ * `scripts/resolve-diff-range.sh` has solid unit coverage
+ * (`resolve-diff-range.test.mjs`), but the affected-mode *wiring* inside the
+ * reusable workflow was only covered indirectly by anchor-expansion checks.
+ * This suite pins the three invariants that keep the affected-mode design
+ * correct, modelled on the sibling `check-ci-required-aggregator.test.mjs`
+ * (read the real workflow, extract blocks by indentation, assert):
+ *
+ *   1. GATING — the coverage-gate steps (`Checkout gate scripts`, `Coverage
+ *      threshold gate`) carry `inputs.coverage-threshold != 0 && !inputs.affected`,
+ *      and the bypass `::notice::` step carries the *complementary*
+ *      `inputs.coverage-threshold != 0 && inputs.affected`. A drift that drops
+ *      `!inputs.affected` (which would false-fail the whole-repo floor on an
+ *      affected subset) fails this suite.
+ *   2. NO EXPORT ON mode=none — executing the resolve-affected `run:` script
+ *      with an unresolved (`mode=none`) range leaves `TURBO_SCM_*` unset, so
+ *      turbo falls back to its own default rather than a bogus range.
+ *   3. INJECTION-SAFE EXPORT (Story #319 hardening) — a newline-bearing
+ *      `affected-base` override is rejected before the `$GITHUB_ENV` write, so
+ *      it can never inject a second env line; a single-line override exports
+ *      exactly `TURBO_SCM_BASE` / `TURBO_SCM_HEAD` and nothing else.
+ *
+ * The `run:` script is executed against real bash with a stubbed
+ * `resolve-diff-range.sh` (the sourced derivation), so no git repo is needed;
+ * skipped when bash is unavailable locally (CI's ubuntu runner always has it).
+ *
+ * Run: node --test scripts/check-affected-mode.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readFileSync, mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const WORKFLOW = ".github/workflows/pr-quality.yml";
+const content = readFileSync(join(repoRoot, WORKFLOW), "utf8");
+
+// ---------------------------------------------------------------------------
+// Minimal indentation-based extraction (dependency-free, mirrors
+// check-ci-required-aggregator.test.mjs). A step spans from its `- ` bullet to
+// the next sibling bullet at the same indent (or a dedent below it).
+// ---------------------------------------------------------------------------
+
+function stepByName(text, name) {
+  const lines = text.split("\n");
+  const nameIdx = lines.findIndex((l) => /^\s+(- )?name:\s/.test(l) && l.includes(name));
+  assert.notEqual(nameIdx, -1, `step "${name}" not found`);
+  let start = -1;
+  for (let i = nameIdx; i >= 0; i--) {
+    if (/^\s*-\s/.test(lines[i])) {
+      start = i;
+      break;
+    }
+  }
+  assert.notEqual(start, -1, `opening bullet for step "${name}" not found`);
+  const bulletIndent = lines[start].match(/^(\s*)/)[1].length;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) continue;
+    const indent = lines[i].match(/^(\s*)/)[1].length;
+    if (indent < bulletIndent) {
+      end = i;
+      break;
+    }
+    if (indent === bulletIndent && /^\s*-\s/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+/** The (first) `if:` expression on a step block, trimmed. */
+function ifCondition(stepBlock) {
+  const m = stepBlock.match(/^\s+if:\s*(.+?)\s*$/m);
+  assert.ok(m, "step has no `if:` condition");
+  return m[1].trim();
+}
+
+/** The dedented body of the step's `run: |` block scalar. */
+function runScript(stepBlock) {
+  const lines = stepBlock.split("\n");
+  const start = lines.findIndex((l) => /^\s+run:\s*\|\s*$/.test(l));
+  assert.notEqual(start, -1, "`run: |` block not found");
+  const runIndent = lines[start].match(/^(\s*)/)[1].length;
+  const body = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) {
+      body.push("");
+      continue;
+    }
+    const indent = lines[i].match(/^(\s*)/)[1].length;
+    if (indent <= runIndent) break;
+    body.push(lines[i].slice(runIndent + 2));
+  }
+  return body.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// 1. GATING — coverage-gate steps gated OUT of affected mode; bypass step gated IN
+// ---------------------------------------------------------------------------
+
+test("resolve-affected step runs only in affected mode", () => {
+  const cond = ifCondition(stepByName(content, "Resolve affected SCM base/head (turbo)"));
+  assert.match(cond, /inputs\.affected/, "the resolve step must be gated on `inputs.affected`");
+  assert.doesNotMatch(cond, /!\s*inputs\.affected/, "the resolve step must not be negated");
+});
+
+for (const step of ["Checkout gate scripts (mandrel-platform@resolved-sha)", "Coverage threshold gate"]) {
+  test(`coverage-gate step "${step}" is gated OUT of affected mode`, () => {
+    const cond = ifCondition(stepByName(content, step));
+    assert.match(
+      cond,
+      /inputs\.coverage-threshold != 0/,
+      "must still require a non-zero coverage-threshold"
+    );
+    assert.match(
+      cond,
+      /!\s*inputs\.affected/,
+      "must carry `!inputs.affected` — dropping it false-fails the whole-repo floor on an affected subset"
+    );
+  });
+}
+
+test("bypass `::notice::` step carries the complementary affected-mode gating", () => {
+  const step = stepByName(content, "Coverage floor bypassed (affected mode)");
+  const cond = ifCondition(step);
+  assert.match(cond, /inputs\.coverage-threshold != 0/, "must require a non-zero coverage-threshold");
+  assert.match(cond, /&&\s*inputs\.affected/, "must fire only in affected mode");
+  assert.doesNotMatch(
+    cond,
+    /!\s*inputs\.affected/,
+    "the bypass notice must be the complement of the gate — never negated"
+  );
+  assert.match(step, /::notice title=/, "the bypass must emit a visible ::notice::, never a silent skip");
+});
+
+// ---------------------------------------------------------------------------
+// 2 & 3. Execute the resolve-affected run script against real bash.
+// ---------------------------------------------------------------------------
+
+function bashAvailable() {
+  try {
+    execFileSync("bash", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+const RESOLVE_SCRIPT = runScript(stepByName(content, "Resolve affected SCM base/head (turbo)"));
+
+/**
+ * Run the extracted resolve-affected `run:` body with a stubbed
+ * resolve-diff-range.sh that sets RESOLVED_* from STUB_* env, capturing the
+ * lines the step wrote to $GITHUB_ENV.
+ */
+function runResolve({ mode = "", base = "", head = "", override } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "affected-mode-"));
+  try {
+    const workspace = join(dir, "ws");
+    mkdirSync(join(workspace, "_mandrel-platform-range", "scripts"), { recursive: true });
+    // Stub the sourced derivation: RESOLVED_* come from STUB_* env.
+    writeFileSync(
+      join(workspace, "_mandrel-platform-range", "scripts", "resolve-diff-range.sh"),
+      ['RESOLVED_EVENT_MODE="${STUB_MODE-}"', 'RESOLVED_BASE_SHA="${STUB_BASE-}"', 'RESOLVED_HEAD_SHA="${STUB_HEAD-}"', ""].join("\n")
+    );
+    const scriptFile = join(dir, "resolve.sh");
+    writeFileSync(scriptFile, RESOLVE_SCRIPT);
+    const envFile = join(dir, "github_env");
+    writeFileSync(envFile, "");
+
+    const env = {
+      ...process.env,
+      GITHUB_WORKSPACE: workspace,
+      GITHUB_ENV: envFile,
+      STUB_MODE: mode,
+      STUB_BASE: base,
+      STUB_HEAD: head,
+    };
+    if (override !== undefined) env.AFFECTED_BASE_OVERRIDE = override;
+
+    const r = spawnSync("bash", [scriptFile], { encoding: "utf8", env });
+    return { status: r.status, stderr: r.stderr, envLines: readFileSync(envFile, "utf8") };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const exec = { skip: bashAvailable() ? false : "bash not available on this host" };
+
+test("mode=none: no ranged base resolvable → TURBO_SCM_* left unset", exec, () => {
+  const r = runResolve({ mode: "", base: "", head: "" });
+  assert.equal(r.status, 0, r.stderr);
+  assert.doesNotMatch(r.envLines, /TURBO_SCM_BASE/, "mode=none must not export a base");
+  assert.doesNotMatch(r.envLines, /TURBO_SCM_HEAD/, "mode=none must not export a head");
+});
+
+test("newline-bearing affected-base override is rejected before the export (injection guard)", exec, () => {
+  const r = runResolve({ override: "deadbeef\nMALICIOUS=pwned", head: "cafebabe" });
+  assert.notEqual(r.status, 0, "a multiline override must fail the step, not export");
+  assert.doesNotMatch(r.envLines, /MALICIOUS/, "the injected env line must never reach $GITHUB_ENV");
+  assert.doesNotMatch(r.envLines, /TURBO_SCM_BASE/, "no partial export on a rejected override");
+});
+
+test("carriage-return-bearing affected-base override is rejected too", exec, () => {
+  const r = runResolve({ override: "deadbeef\rMALICIOUS=pwned", head: "cafebabe" });
+  assert.notEqual(r.status, 0);
+  assert.doesNotMatch(r.envLines, /MALICIOUS/);
+});
+
+test("single-line affected-base override exports exactly TURBO_SCM_BASE and TURBO_SCM_HEAD", exec, () => {
+  const r = runResolve({ override: "origin/main", head: "cafebabe" });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.envLines, /^TURBO_SCM_BASE=origin\/main$/m);
+  assert.match(r.envLines, /^TURBO_SCM_HEAD=cafebabe$/m);
+  const nonEmpty = r.envLines.split("\n").filter((l) => l.trim() !== "");
+  assert.equal(nonEmpty.length, 2, `expected exactly two env lines, got: ${JSON.stringify(nonEmpty)}`);
+});

package/scripts/check-osv-scan-mode.test.mjs

@@ -0,0 +1,489 @@
+#!/usr/bin/env node
+/**
+ * check-osv-scan-mode.test.mjs — YAML-level regression guard for the
+ * diff-aware OSV wiring (Story #325).
+ *
+ * The gate LOGIC has unit coverage in `osv-report-gate.test.mjs`, but the
+ * logic is inert unless the workflow actually feeds it a baseline. The wiring
+ * is where this design silently degrades, and every degradation looks like a
+ * green build:
+ *
+ *   • a shallow checkout → `git merge-base` and the baseline worktree cannot
+ *     reach the fork point → every run silently gates whole-tree, and the
+ *     incident this Story fixes comes straight back;
+ *   • a dropped `baseline-ref` input → the composite resolves 'auto' to full
+ *     with no error, for the same silent outcome;
+ *   • `advisory-scan.yml` inheriting the diff-aware default → NOTHING owns
+ *     base-branch advisories, because the PR tier deliberately stopped
+ *     blocking on them. That is the one true regression here: a real
+ *     main-level advisory would go completely unreported.
+ *
+ * This suite pins all three, modelled on the sibling
+ * `check-affected-mode.test.mjs` (read the real workflow, extract blocks by
+ * indentation, assert — then execute the extracted `run:` bodies against real
+ * bash so the fail-closed branches are proven, not just read).
+ *
+ * Run: node --test scripts/check-osv-scan-mode.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { readFileSync, mkdtempSync, writeFileSync, mkdirSync, rmSync } from "node:fs";
+import { execFileSync, spawnSync } from "node:child_process";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const prQuality = readFileSync(join(repoRoot, ".github/workflows/pr-quality.yml"), "utf8");
+const advisoryScan = readFileSync(join(repoRoot, ".github/workflows/advisory-scan.yml"), "utf8");
+const composite = readFileSync(join(repoRoot, ".github/actions/osv-scan/action.yml"), "utf8");
+
+// ---------------------------------------------------------------------------
+// Minimal indentation-based extraction (dependency-free, mirrors
+// check-affected-mode.test.mjs / check-ci-required-aggregator.test.mjs).
+// ---------------------------------------------------------------------------
+
+function stepByName(text, name) {
+  const lines = text.split("\n");
+  const nameIdx = lines.findIndex((l) => /^\s+(- )?name:\s/.test(l) && l.includes(name));
+  assert.notEqual(nameIdx, -1, `step "${name}" not found`);
+  let start = -1;
+  for (let i = nameIdx; i >= 0; i--) {
+    if (/^\s*-\s/.test(lines[i])) {
+      start = i;
+      break;
+    }
+  }
+  assert.notEqual(start, -1, `opening bullet for step "${name}" not found`);
+  const bulletIndent = lines[start].match(/^(\s*)/)[1].length;
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) continue;
+    const indent = lines[i].match(/^(\s*)/)[1].length;
+    if (indent < bulletIndent) {
+      end = i;
+      break;
+    }
+    if (indent === bulletIndent && /^\s*-\s/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+/** The dedented body of a step's `run: |` block scalar. */
+function runScript(stepBlock) {
+  const lines = stepBlock.split("\n");
+  const start = lines.findIndex((l) => /^\s+run:\s*\|\s*$/.test(l));
+  assert.notEqual(start, -1, "`run: |` block not found");
+  const runIndent = lines[start].match(/^(\s*)/)[1].length;
+  const body = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) {
+      body.push("");
+      continue;
+    }
+    const indent = lines[i].match(/^(\s*)/)[1].length;
+    if (indent <= runIndent) break;
+    body.push(lines[i].slice(runIndent + 2));
+  }
+  return body.join("\n");
+}
+
+/**
+ * The body of a mapping key at a given indent, up to the next sibling key or
+ * end of input. Terminating on end-of-input matters: the LAST declared input
+ * has no following sibling, and a regex that requires one silently matches
+ * nothing.
+ */
+function blockUnder(text, key, indent) {
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => l === `${" ".repeat(indent)}${key}:`);
+  assert.notEqual(start, -1, `key "${key}" not found at indent ${indent}`);
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) continue;
+    // The block ends at the next sibling key (same indent) or any dedent —
+    // both are just "leading whitespace no deeper than the key's own".
+    if (lines[i].match(/^(\s*)/)[1].length <= indent) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start + 1, end).join("\n");
+}
+
+/** The `osv-scan` job block, so step lookups cannot match a same-named step elsewhere. */
+function osvScanJob() {
+  const lines = prQuality.split("\n");
+  const start = lines.findIndex((l) => /^ {2}osv-scan:\s*$/.test(l));
+  assert.notEqual(start, -1, "osv-scan job not found");
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^ {2}\S/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+const job = osvScanJob();
+
+function bashAvailable() {
+  try {
+    execFileSync("bash", ["--version"], { stdio: "ignore" });
+    return true;
+  } catch {
+    return false;
+  }
+}
+const exec = { skip: bashAvailable() ? false : "bash not available on this host" };
+
+// ---------------------------------------------------------------------------
+// 1. INPUT SURFACE — the reusable workflow exposes the knobs, defaulted so the
+//    diff-aware behaviour is on and the grace window is off.
+// ---------------------------------------------------------------------------
+
+test("pr-quality declares osv-scan-mode defaulting to 'auto'", () => {
+  const block = blockUnder(prQuality, "osv-scan-mode", 6);
+  assert.match(block, /type:\s*string/, "osv-scan-mode must be a string input");
+  assert.match(
+    block,
+    /default:\s*'auto'/,
+    "osv-scan-mode must default to 'auto' (the diff-aware default)",
+  );
+});
+
+test("pr-quality declares osv-grace-days defaulting to 0 (window off)", () => {
+  const block = blockUnder(prQuality, "osv-grace-days", 6);
+  assert.match(block, /type:\s*number/, "osv-grace-days must be a number input");
+  assert.match(
+    block,
+    /default:\s*0\b/,
+    "osv-grace-days must default to 0 — no consumer's gate may soften without opting in",
+  );
+});
+
+test("the composite declares the diff-aware surface with matching defaults", () => {
+  assert.match(
+    blockUnder(composite, "scan-mode", 2),
+    /default:\s*'auto'/,
+    "composite scan-mode must default to 'auto'",
+  );
+  assert.match(
+    blockUnder(composite, "grace-days", 2),
+    /default:\s*'0'/,
+    "composite grace-days must default to '0' — the window is opt-in",
+  );
+  assert.match(
+    blockUnder(composite, "baseline-ref", 2),
+    /default:\s*''/,
+    "composite baseline-ref must default to empty (no baseline → whole-tree)",
+  );
+
+  const compositeLines = composite.split("\n");
+  for (const out of ["preexisting-count", "grace-count", "resolved-scan-mode", "baseline-scanned"]) {
+    assert.ok(
+      compositeLines.includes(`  ${out}:`),
+      `composite must expose the ${out} output`,
+    );
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 2. WIRING — the osv-scan job can actually reach the merge base, and forwards
+//    every input. A shallow checkout here degrades to whole-tree silently.
+// ---------------------------------------------------------------------------
+
+test("the osv-scan job checks out full history unless scan-mode is 'full'", () => {
+  const checkout = stepByName(job, "Checkout");
+  const m = checkout.match(/fetch-depth:\s*(.+)/);
+  assert.ok(m, "the osv-scan checkout must pin fetch-depth explicitly");
+  const expr = m[1].trim();
+  assert.match(
+    expr,
+    /inputs\.osv-scan-mode == 'full'/,
+    "fetch-depth must key off osv-scan-mode — a shallow clone cannot reach the merge base",
+  );
+  // The strings are load-bearing: a bare numeric 0 is FALSY in a GitHub
+  // expression, so `... && 0 || 1` collapses to 1 and silently re-shallows.
+  assert.match(expr, /'1'/, "the full-mode arm must be the STRING '1'");
+  assert.match(expr, /'0'/, "the diff-mode arm must be the STRING '0'");
+  assert.match(checkout, /persist-credentials:\s*false/, "must not persist the token");
+});
+
+for (const step of [
+  "Checkout diff-range resolver (mandrel-platform@resolved-sha)",
+  "Resolve OSV diff baseline (merge base)",
+]) {
+  test(`"${step}" is skipped only under scan-mode: full`, () => {
+    const block = stepByName(job, step);
+    const m = block.match(/^\s+if:\s*(.+?)\s*$/m);
+    assert.ok(m, `step "${step}" has no if: condition`);
+    assert.match(
+      m[1],
+      /inputs\.osv-scan-mode != 'full'/,
+      "the baseline steps must run for every mode except full",
+    );
+  });
+}
+
+test("the diff-range resolver is side-checked-out from the pinned platform SHA", () => {
+  const block = stepByName(job, "Checkout diff-range resolver (mandrel-platform@resolved-sha)");
+  assert.match(block, /repository:\s*dsj1984\/mandrel-platform/);
+  assert.match(
+    block,
+    /job_workflow_sha/,
+    "must resolve THIS repo at the SHA the caller pinned, not a floating ref",
+  );
+  assert.match(
+    block,
+    /scripts\/resolve-diff-range\.sh/,
+    "must reuse the canonical derivation rather than re-deriving base/head",
+  );
+});
+
+test("the composite step forwards scan-mode, baseline-ref and grace-days", () => {
+  const step = stepByName(job, "OSV advisory scan (pinned binary)");
+  assert.match(step, /scan-mode:\s*\$\{\{\s*inputs\.osv-scan-mode\s*\}\}/);
+  assert.match(
+    step,
+    /baseline-ref:\s*\$\{\{\s*steps\.osv-baseline\.outputs\.baseline-ref\s*\}\}/,
+    "the resolved merge base must reach the composite, or 'auto' silently degrades to full",
+  );
+  assert.match(step, /grace-days:\s*\$\{\{\s*inputs\.osv-grace-days\s*\}\}/);
+  // The existing contract must survive.
+  assert.match(step, /fail-on-severity:\s*\$\{\{\s*inputs\.osv-fail-on-severity\s*\}\}/);
+  assert.match(step, /allowlist-path:\s*\$\{\{\s*inputs\.osv-allowlist-path\s*\}\}/);
+});
+
+// ---------------------------------------------------------------------------
+// 3. THE SCHEDULED OWNER — advisory-scan.yml must stay whole-tree. This is the
+//    regression that would make the whole design unsafe.
+// ---------------------------------------------------------------------------
+
+test("advisory-scan pins scan-mode: full and cannot inherit the diff-aware default", () => {
+  const step = stepByName(advisoryScan, "OSV advisory scan (scheduled, non-blocking)");
+  assert.match(
+    step,
+    /scan-mode:\s*'full'/,
+    "the scheduled scan owns base-branch advisories — diff-aware there would leave them unowned",
+  );
+});
+
+test("advisory-scan still reports findings and still upserts its tracking issue", () => {
+  const step = stepByName(advisoryScan, "OSV advisory scan (scheduled, non-blocking)");
+  assert.match(step, /non-blocking:\s*'true'/, "the tracking issue is the signal, not a red job");
+  assert.match(step, /findings-out:/, "the upsert needs the machine-readable findings");
+  assert.match(
+    advisoryScan,
+    /actions\/osv-track-issue@/,
+    "the tracking-issue upsert step must still run",
+  );
+  assert.match(advisoryScan, /issues:\s*write/, "the upsert needs issues: write");
+});
+
+// ---------------------------------------------------------------------------
+// 4. EXECUTE the composite's mode-resolution prologue. 'auto' with no baseline
+//    and 'diff' with no baseline must BOTH land on full (blocking) — the
+//    fail-closed direction.
+// ---------------------------------------------------------------------------
+
+const compositeRun = runScript(stepByName(composite, "OSV advisory scan (pinned binary)"));
+// The prologue is everything before the binary download begins.
+const MODE_PROLOGUE = compositeRun.split('\nos="$(uname -s)"')[0];
+
+function resolveMode({ mode, baselineRef = "" }) {
+  const dir = mkdtempSync(join(tmpdir(), "osv-mode-"));
+  try {
+    const scriptFile = join(dir, "prologue.sh");
+    writeFileSync(scriptFile, MODE_PROLOGUE);
+    const outFile = join(dir, "github_output");
+    writeFileSync(outFile, "");
+    const r = spawnSync("bash", [scriptFile], {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        GITHUB_OUTPUT: outFile,
+        OSV_SCAN_MODE: mode,
+        OSV_BASELINE_REF: baselineRef,
+      },
+    });
+    return {
+      status: r.status,
+      stdout: r.stdout,
+      outputs: readFileSync(outFile, "utf8"),
+    };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("scan-mode 'full' never resolves to diff, even with a baseline available", exec, () => {
+  const r = resolveMode({ mode: "full", baselineRef: "deadbeef" });
+  assert.equal(r.status, 0, r.stdout);
+  assert.match(r.outputs, /^resolved-scan-mode=full$/m);
+});
+
+test("scan-mode 'auto' resolves to diff when a baseline was supplied", exec, () => {
+  const r = resolveMode({ mode: "auto", baselineRef: "deadbeef" });
+  assert.equal(r.status, 0, r.stdout);
+  assert.match(r.outputs, /^resolved-scan-mode=diff$/m);
+});
+
+test("scan-mode 'auto' falls back to full when no baseline is resolvable", exec, () => {
+  // push / schedule / a merge-queue-less event resolve no base — today's
+  // whole-tree behaviour must survive untouched there.
+  const r = resolveMode({ mode: "auto", baselineRef: "" });
+  assert.equal(r.status, 0, r.stdout);
+  assert.match(r.outputs, /^resolved-scan-mode=full$/m);
+});
+
+test("scan-mode 'diff' with no baseline degrades to full and says so", exec, () => {
+  const r = resolveMode({ mode: "diff", baselineRef: "" });
+  assert.equal(r.status, 0, r.stdout);
+  assert.match(
+    r.outputs,
+    /^resolved-scan-mode=full$/m,
+    "an unbaselined diff run must BLOCK whole-tree, never pass everything as pre-existing",
+  );
+  assert.match(r.stdout, /::warning::/, "the degradation must be visible, not silent");
+});
+
+test("an invalid scan-mode fails the step closed", exec, () => {
+  const r = resolveMode({ mode: "sideways", baselineRef: "deadbeef" });
+  assert.notEqual(r.status, 0, "an unrecognized mode must not fall through to a default");
+  assert.doesNotMatch(r.outputs, /resolved-scan-mode=/, "no partial output on a rejected mode");
+});
+
+// ---------------------------------------------------------------------------
+// 5. EXECUTE the baseline-resolution run script against real bash + real git,
+//    so the merge-base shaping and the injection guard are proven.
+// ---------------------------------------------------------------------------
+
+const BASELINE_SCRIPT = runScript(stepByName(job, "Resolve OSV diff baseline (merge base)"));
+
+/**
+ * Run the extracted baseline step with a stubbed resolve-diff-range.sh (the
+ * sourced derivation), inside a real throwaway git repo so `git merge-base`
+ * resolves for the pull_request shaping.
+ */
+function runBaseline({ mode = "", base = "", head = "", realRepo = false } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "osv-baseline-"));
+  try {
+    const workspace = join(dir, "ws");
+    mkdirSync(join(workspace, "_mandrel-platform-osv-range", "scripts"), { recursive: true });
+    writeFileSync(
+      join(workspace, "_mandrel-platform-osv-range", "scripts", "resolve-diff-range.sh"),
+      [
+        'RESOLVED_EVENT_MODE="${STUB_MODE-}"',
+        'RESOLVED_BASE_SHA="${STUB_BASE-}"',
+        'RESOLVED_HEAD_SHA="${STUB_HEAD-}"',
+        "",
+      ].join("\n"),
+    );
+
+    let baseSha = base;
+    let headSha = head;
+    if (realRepo) {
+      const git = (...args) =>
+        execFileSync(
+          "git",
+          ["-c", "user.name=t", "-c", "user.email=t@t", "-c", "commit.gpgsign=false", ...args],
+          { cwd: workspace, encoding: "utf8" },
+        ).trim();
+      git("init", "-q", "-b", "main");
+      writeFileSync(join(workspace, "a.txt"), "a\n");
+      git("add", "a.txt");
+      git("commit", "-qm", "root");
+      const fork = git("rev-parse", "HEAD");
+      // Advance main past the fork point — this drift is exactly why the PR
+      // shaping takes the merge base rather than base.sha.
+      writeFileSync(join(workspace, "b.txt"), "b\n");
+      git("add", "b.txt");
+      git("commit", "-qm", "main advances");
+      baseSha = git("rev-parse", "HEAD");
+      git("checkout", "-q", "-b", "feature", fork);
+      writeFileSync(join(workspace, "c.txt"), "c\n");
+      git("add", "c.txt");
+      git("commit", "-qm", "feature work");
+      headSha = git("rev-parse", "HEAD");
+      // The merge base of base..head is the fork point, NOT the advanced tip.
+      return { ...spawnBaseline(), forkSha: fork };
+    }
+    return spawnBaseline();
+
+    function spawnBaseline() {
+      const scriptFile = join(dir, "baseline.sh");
+      writeFileSync(scriptFile, BASELINE_SCRIPT);
+      const outFile = join(dir, "github_output");
+      writeFileSync(outFile, "");
+      const r = spawnSync("bash", [scriptFile], {
+        cwd: workspace,
+        encoding: "utf8",
+        env: {
+          ...process.env,
+          GITHUB_WORKSPACE: workspace,
+          GITHUB_OUTPUT: outFile,
+          STUB_MODE: mode,
+          STUB_BASE: baseSha,
+          STUB_HEAD: headSha,
+        },
+      });
+      return {
+        status: r.status,
+        stdout: r.stdout,
+        stderr: r.stderr,
+        outputs: readFileSync(outFile, "utf8"),
+      };
+    }
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+test("mode=none exports an EMPTY baseline-ref rather than skipping the output", exec, () => {
+  const r = runBaseline({ mode: "" });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(
+    r.outputs,
+    /^baseline-ref=$/m,
+    "an unresolvable base must still emit the (empty) output — the composite reads that as 'gate whole-tree'",
+  );
+});
+
+test("pull_request baselines on the MERGE BASE, not the drifted base tip", exec, () => {
+  const r = runBaseline({ mode: "pull_request", realRepo: true });
+  assert.equal(r.status, 0, r.stderr);
+  const m = r.outputs.match(/^baseline-ref=(.+)$/m);
+  assert.ok(m, "no baseline-ref emitted");
+  assert.equal(
+    m[1],
+    r.forkSha,
+    "must be the fork point — base.sha drifts forward once main advances, which would baseline against commits the PR never saw",
+  );
+});
+
+for (const mode of ["merge_group", "push"]) {
+  test(`${mode} baselines on the derived base directly (already the fork point)`, exec, () => {
+    const r = runBaseline({ mode, base: "cafebabe", head: "deadbeef" });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.outputs, /^baseline-ref=cafebabe$/m);
+  });
+}
+
+test("a newline-bearing base is rejected before it reaches $GITHUB_OUTPUT", exec, () => {
+  const r = runBaseline({ mode: "push", base: "cafebabe\nMALICIOUS=pwned", head: "deadbeef" });
+  assert.notEqual(r.status, 0, "a multiline base must fail the step, not export");
+  assert.doesNotMatch(r.outputs, /MALICIOUS/, "the injected line must never reach $GITHUB_OUTPUT");
+  assert.doesNotMatch(r.outputs, /baseline-ref=/, "no partial export on a rejected base");
+});
+
+test("a carriage-return-bearing base is rejected too", exec, () => {
+  const r = runBaseline({ mode: "push", base: "cafebabe\rMALICIOUS=pwned", head: "deadbeef" });
+  assert.notEqual(r.status, 0);
+  assert.doesNotMatch(r.outputs, /MALICIOUS/);
+});

package/scripts/osv-report-gate.test.mjs

@@ -16,17 +16,25 @@ import {
   classify,
   findingsDigest,
   renderSummary,
+  normalizeSource,
+  rowKey,
+  buildBaselineSet,
   OsvGateError,
 } from "../.github/actions/osv-scan/osv-report-gate.mjs";
 
-// Build an OSV-scanner-shaped report for one grouped advisory.
-const reportWith = (groups) => ({
+// Build an OSV-scanner-shaped report for one grouped advisory. `published`
+// rides on the per-vulnerability entries, mirroring the real OSV schema —
+// group rows carry the severity, never the date.
+const reportWith = (groups, { sourcePath = "pnpm-lock.yaml" } = {}) => ({
   results: [
     {
-      source: { path: "pnpm-lock.yaml" },
+      source: { path: sourcePath },
       packages: groups.map((g) => ({
         package: { name: g.name, version: g.version || "1.0.0", ecosystem: g.ecosystem || "npm" },
         groups: [{ ids: g.ids, max_severity: g.score }],
+        ...(g.published
+          ? { vulnerabilities: g.ids.map((id) => ({ id, published: g.published })) }
+          : {}),
       })),
     },
   ],
@@ -225,3 +233,307 @@ test("renderSummary reports a clean scan and a blocked scan distinctly", () => {
   assert.match(blocked.join("\n"), /❌ BLOCKED/);
   assert.match(blocked.join("\n"), /GHSA-x/);
 });
+
+// ---------------------------------------------------------------------------
+// Diff-aware baseline + publish grace window (Story #325)
+//
+// The failure these close: a newly-published advisory against a dependency
+// that has been on `main` for weeks reds EVERY open PR simultaneously — the
+// postcss GHSA-r28c-9q8g-f849 / brace-expansion GHSA-mh99-v99m-4gvg incidents
+// on the swarm-os consumer. The gate must tell "this PR introduced it" from
+// "this was already here", without ever letting a real PR-introduced advisory
+// through and without neutering the operator-authored `revisitBy` re-gate.
+// ---------------------------------------------------------------------------
+
+// A baseline built from the SAME tree, as the merge-base worktree scan yields.
+const baselineOf = (groups, opts) => buildBaselineSet(collectRows(reportWith(groups, opts), opts));
+
+test("a finding already present at the baseline is demoted, not blocked", () => {
+  const groups = [{ name: "postcss", ids: ["GHSA-r28c-9q8g-f849"], score: "7.5" }];
+  const v = classify(collectRows(reportWith(groups)), {
+    failOn: "high",
+    baseline: baselineOf(groups),
+  });
+  assert.equal(v.blocking.length, 0);
+  assert.equal(v.preexisting.length, 1);
+  assert.equal(v.preexisting[0].ids[0], "GHSA-r28c-9q8g-f849");
+});
+
+test("a head-only finding is PR-introduced and still blocks", () => {
+  const v = classify(
+    collectRows(
+      reportWith([
+        { name: "postcss", ids: ["GHSA-r28c-9q8g-f849"], score: "7.5" },
+        { name: "brand-new-dep", ids: ["GHSA-new"], score: "8.2" },
+      ]),
+    ),
+    {
+      failOn: "high",
+      baseline: baselineOf([{ name: "postcss", ids: ["GHSA-r28c-9q8g-f849"], score: "7.5" }]),
+    },
+  );
+  assert.equal(v.blocking.length, 1);
+  assert.equal(v.blocking[0].name, "brand-new-dep");
+  assert.equal(v.preexisting.length, 1);
+  assert.equal(v.preexisting[0].name, "postcss");
+});
+
+test("bumping an advisory-bearing dep to another vulnerable version still blocks", () => {
+  // Same package, same advisory id — only the version moved. The baseline key
+  // carries @version precisely so this cannot inherit the demotion.
+  const v = classify(
+    collectRows(reportWith([{ name: "postcss", ids: ["GHSA-r28c"], score: "7.5", version: "8.4.0" }])),
+    {
+      failOn: "high",
+      baseline: baselineOf([
+        { name: "postcss", ids: ["GHSA-r28c"], score: "7.5", version: "8.3.0" },
+      ]),
+    },
+  );
+  assert.equal(v.blocking.length, 1);
+  assert.equal(v.blocking[0].version, "8.4.0");
+  assert.equal(v.preexisting.length, 0);
+});
+
+test("normalizeSource reduces worktree-rooted and workspace-rooted paths alike", () => {
+  assert.equal(normalizeSource("/tmp/osv-baseline/pnpm-lock.yaml", "/tmp/osv-baseline"), "pnpm-lock.yaml");
+  assert.equal(normalizeSource("/home/runner/work/repo/pnpm-lock.yaml", "/home/runner/work/repo"), "pnpm-lock.yaml");
+  assert.equal(normalizeSource("./pnpm-lock.yaml", "/tmp/osv-baseline"), "pnpm-lock.yaml");
+  assert.equal(normalizeSource("pnpm-lock.yaml", ""), "pnpm-lock.yaml");
+  // A trailing slash on the root must not leave a leading slash behind.
+  assert.equal(normalizeSource("/tmp/base/apps/web/pnpm-lock.yaml", "/tmp/base/"), "apps/web/pnpm-lock.yaml");
+});
+
+test("the baseline matches across differing scan roots", () => {
+  // The head scan runs in the workspace; the baseline scan runs in a git
+  // worktree at a different absolute path. Un-normalized, every head finding
+  // would look head-only and the diff-aware gate would block everything.
+  const groups = [{ name: "postcss", ids: ["GHSA-r28c"], score: "7.5" }];
+  const headRows = collectRows(
+    reportWith(groups, { sourcePath: "/home/runner/work/repo/pnpm-lock.yaml" }),
+    { scanRoot: "/home/runner/work/repo" },
+  );
+  const baseRows = collectRows(reportWith(groups, { sourcePath: "/tmp/osv-baseline/pnpm-lock.yaml" }), {
+    scanRoot: "/tmp/osv-baseline",
+  });
+  assert.equal(rowKey(headRows[0]), rowKey(baseRows[0]));
+
+  const v = classify(headRows, { failOn: "high", baseline: buildBaselineSet(baseRows) });
+  assert.equal(v.blocking.length, 0);
+  assert.equal(v.preexisting.length, 1);
+});
+
+test("an EXPIRED suppression outranks BOTH demotions and still re-gates", () => {
+  // The load-bearing precedence rule. An expired suppression is by
+  // construction on a pre-existing dependency, so letting either demotion
+  // apply would neuter `revisitBy` on PRs entirely.
+  //
+  // The fixture must be genuinely eligible for both demotions or this test
+  // passes vacuously: `published` is what puts the row inside the window, and
+  // without it `grace` is empty no matter how the precedence chain is wired.
+  const groups = [
+    {
+      name: "brace-expansion",
+      ids: ["GHSA-mh99-v99m-4gvg"],
+      score: "7.5",
+      published: "2026-07-22T00:00:00Z",
+    },
+  ];
+  const rows = collectRows(reportWith(groups));
+  const baseline = baselineOf(groups);
+  const opts = { failOn: "high", today: "2026-07-24", baseline, graceDays: 30 };
+
+  // Guard the fixture: with NO allow-list entry this row is demoted. If this
+  // ever stops holding, the assertion below has nothing left to prove.
+  const unsuppressed = classify(rows, opts);
+  assert.equal(unsuppressed.blocking.length, 0, "fixture must be demotable without an allow-list");
+  assert.equal(unsuppressed.preexisting.length, 1, "fixture must be baseline-eligible");
+  assert.notEqual(rows[0].published, null, "fixture must carry a publish date to be grace-eligible");
+
+  const v = classify(rows, {
+    ...opts,
+    allowlist: [{ id: "GHSA-mh99-v99m-4gvg", reason: "stale triage", revisitBy: "2026-01-01" }],
+  });
+  assert.equal(v.blocking.length, 1);
+  assert.equal(v.expired.length, 1);
+  assert.equal(v.preexisting.length, 0);
+  assert.equal(v.grace.length, 0);
+});
+
+test("an UNEXPIRED suppression stays suppressed and is not double-counted", () => {
+  const groups = [{ name: "brace-expansion", ids: ["GHSA-mh99-v99m-4gvg"], score: "7.5" }];
+  const v = classify(collectRows(reportWith(groups)), {
+    failOn: "high",
+    allowlist: [{ id: "GHSA-mh99-v99m-4gvg", reason: "not reachable", revisitBy: "2099-12-31" }],
+    today: "2026-07-24",
+    baseline: baselineOf(groups),
+  });
+  assert.equal(v.suppressed.length, 1);
+  assert.equal(v.blocking.length, 0);
+  assert.equal(v.preexisting.length, 0);
+});
+
+test("the grace window demotes a recent advisory and not an old one", () => {
+  const rows = collectRows(
+    reportWith([
+      { name: "fresh", ids: ["GHSA-fresh"], score: "8.0", published: "2026-07-21T00:00:00Z" },
+      { name: "stale", ids: ["GHSA-stale"], score: "8.0", published: "2026-06-24T00:00:00Z" },
+    ]),
+  );
+  const v = classify(rows, { failOn: "high", graceDays: 7, today: "2026-07-24" });
+  assert.deepEqual(
+    v.grace.map((r) => r.name),
+    ["fresh"],
+  );
+  assert.deepEqual(
+    v.blocking.map((r) => r.name),
+    ["stale"],
+  );
+});
+
+test("the grace window fails closed when the publish date is unresolvable", () => {
+  // No `published` on the vulnerability entries at all…
+  const undated = classify(collectRows(reportWith([{ name: "p", ids: ["GHSA-x"], score: "8.0" }])), {
+    failOn: "high",
+    graceDays: 7,
+    today: "2026-07-24",
+  });
+  assert.equal(undated.blocking.length, 1);
+  assert.equal(undated.grace.length, 0);
+
+  // …and a present-but-garbage date is equally not a free pass.
+  const garbage = classify(
+    collectRows(reportWith([{ name: "p", ids: ["GHSA-x"], score: "8.0", published: "not-a-date" }])),
+    { failOn: "high", graceDays: 7, today: "2026-07-24" },
+  );
+  assert.equal(garbage.blocking.length, 1);
+  assert.equal(garbage.grace.length, 0);
+});
+
+test("the grace window is off at the default of 0", () => {
+  const rows = collectRows(
+    reportWith([
+      { name: "fresh", ids: ["GHSA-fresh"], score: "8.0", published: "2026-07-23T00:00:00Z" },
+    ]),
+  );
+  const v = classify(rows, { failOn: "high", today: "2026-07-24" });
+  assert.equal(v.graceDays, 0);
+  assert.equal(v.grace.length, 0);
+  assert.equal(v.blocking.length, 1);
+});
+
+test("collectRows takes the EARLIEST published date across a group's aliased ids", () => {
+  const report = {
+    results: [
+      {
+        source: { path: "pnpm-lock.yaml" },
+        packages: [
+          {
+            package: { name: "p", version: "1.0.0", ecosystem: "npm" },
+            groups: [{ ids: ["GHSA-a", "CVE-b"], max_severity: "8.0" }],
+            vulnerabilities: [
+              { id: "GHSA-a", published: "2026-07-20T00:00:00Z" },
+              { id: "CVE-b", published: "2026-05-01T00:00:00Z" },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+  assert.equal(collectRows(report)[0].published, "2026-05-01T00:00:00Z");
+
+  // …and the earliest date is what the window is judged against, so an alias
+  // published long ago cannot be laundered into the window by a fresh alias.
+  const v = classify(collectRows(report), { failOn: "high", graceDays: 7, today: "2026-07-24" });
+  assert.equal(v.blocking.length, 1);
+  assert.equal(v.grace.length, 0);
+});
+
+test("with no baseline and no grace window the partition is unchanged", () => {
+  // The backward-compatibility contract: default inputs must classify exactly
+  // as they did before diff-awareness existed.
+  const rows = collectRows(
+    reportWith([
+      { name: "crit", ids: ["C"], score: "9.9" },
+      { name: "hi", ids: ["H"], score: "7.1" },
+      { name: "med", ids: ["M"], score: "4.5" },
+      { name: "sup", ids: ["S"], score: "8.0" },
+    ]),
+  );
+  const allowlist = [{ id: "S", reason: "triaged", revisitBy: "2099-12-31" }];
+  const v = classify(rows, { failOn: "high", allowlist, today: "2026-07-24" });
+
+  assert.deepEqual(
+    v.blocking.map((r) => r.name),
+    ["crit", "hi"],
+  );
+  assert.deepEqual(
+    v.warning.map((r) => r.name),
+    ["med"],
+  );
+  assert.equal(v.suppressed.length, 1);
+  assert.equal(v.expired.length, 0);
+  // The new buckets exist but are inert.
+  assert.deepEqual(v.preexisting, []);
+  assert.deepEqual(v.grace, []);
+  assert.equal(v.baselineApplied, false);
+});
+
+test("findingsDigest ignores preexisting and grace rows entirely", () => {
+  // The scheduled tracking issue keys off this digest; a PR-side demotion must
+  // not rewrite the issue body or make an unchanged advisory set look new.
+  const groups = [
+    { name: "p1", ids: ["GHSA-a"], score: "7.5" },
+    { name: "p2", ids: ["GHSA-b"], score: "9.1", published: "2026-07-23T00:00:00Z" },
+  ];
+  const plain = classify(collectRows(reportWith(groups)), { failOn: "high", today: "2026-07-24" });
+  const demoted = classify(collectRows(reportWith(groups)), {
+    failOn: "high",
+    today: "2026-07-24",
+    baseline: baselineOf([groups[0]]),
+    graceDays: 7,
+  });
+
+  assert.equal(demoted.blocking.length, 0);
+  assert.equal(demoted.preexisting.length, 1);
+  assert.equal(demoted.grace.length, 1);
+  assert.equal(findingsDigest(demoted.blocking), findingsDigest([]));
+  assert.notEqual(findingsDigest(plain.blocking), findingsDigest(demoted.blocking));
+});
+
+test("renderSummary names both demotion buckets with one table row each", () => {
+  const groups = [
+    { name: "postcss", ids: ["GHSA-r28c-9q8g-f849"], score: "7.5" },
+    { name: "fresh", ids: ["GHSA-fresh"], score: "8.0", published: "2026-07-23T00:00:00Z" },
+  ];
+  const v = classify(collectRows(reportWith(groups)), {
+    failOn: "high",
+    today: "2026-07-24",
+    baseline: baselineOf([groups[0]]),
+    graceDays: 7,
+  });
+  const out = renderSummary(v).join("\n");
+
+  assert.match(out, /Pre-existing on the base branch — not introduced by this PR \(1\)/);
+  assert.match(out, /Within the publish grace window \(1\)/);
+  assert.match(out, /GHSA-r28c-9q8g-f849/);
+  assert.match(out, /GHSA-fresh/);
+  // Demotions are not a pass-with-nothing-to-say: the verdict line must not
+  // claim BLOCKED when everything was demoted.
+  assert.doesNotMatch(out, /❌ BLOCKED/);
+  // The grace table carries the publish date that justified the demotion.
+  assert.match(out, /\| 2026-07-23T00:00:00Z \|/);
+});
+
+test("a fully-demoted verdict set is not rendered as a clean scan", () => {
+  // Demoted findings still have to be visible — silently reporting "no known
+  // advisories" would hide exactly what the diff-aware mode chose not to gate.
+  const groups = [{ name: "postcss", ids: ["GHSA-r28c"], score: "7.5" }];
+  const v = classify(collectRows(reportWith(groups)), {
+    failOn: "high",
+    baseline: baselineOf(groups),
+  });
+  const out = renderSummary(v).join("\n");
+  assert.doesNotMatch(out, /no known advisories/);
+  assert.match(out, /GHSA-r28c/);
+});

package/scripts/runner-fleet-consumers.json

@@ -1,5 +1,6 @@
 {
-  "$comment": "Data-driven expected roster for scripts/check-runner-health.mjs (Story #258). Each entry is one repo whose self-hosted runner fleet the scheduled runner-fleet-health.yml workflow monitors. Adding/removing a runner needs only an edit here — the checker reads GET /repos/{owner}/{repo}/actions/runners and compares live status against `expectedCount` + `labels`. All nine runners (including Beestera/swarm-os's three) are co-resident on one operator Mac (2026-07-03 runner audit, repo-ops matrix §1a); if that host sleeps, reboots, fills its disk, or a launchd service dies, every listed repo's CI silently queues with no alert until this monitor catches it.",
+  "$comment": "Data-driven expected roster for scripts/check-runner-health.mjs (Story #258). Each entry is one repo whose self-hosted runner fleet the scheduled runner-fleet-health.yml workflow monitors. Adding/removing a runner needs only an edit here — the checker reads GET /repos/{owner}/{repo}/actions/runners and compares live status against `expectedCount` + `labels`. The co-resident operator Mac now carries 7 domio + 5 athportal monitored runners (plus 17 beestera/swarm-os installs that are deliberately NOT listed — see `$comment_swarm_os`); if that host sleeps, reboots, fills its disk, or a launchd service dies, every listed repo's CI silently queues with no alert until this monitor catches it. Keep these counts in lockstep with the live fleets: the maintenance contract lives in templates/runbooks/runner-provisioning.md.",
+  "$comment_expectedCount": "Semantics: warn-below (over-provisioning is fine). The checker computes shortfall = max(0, expectedCount - matchingOnline) and only alarms when fewer online runners match the labels than expected — adding runners above expectedCount never trips the alarm, so a deliberate scale-up needs no immediate roster edit (though you should still bump the count to keep the shortfall floor meaningful). Removing runners on purpose (scale-down) DOES require lowering expectedCount here, otherwise the monitor will correctly flag the missing runners as a shortfall.",
   "$comment_swarm_os": "Beestera/swarm-os is deliberately NOT listed: no dsj1984-owned PAT can read another org's runner API (fine-grained PATs are bound to one resource owner; the Beestera org rejects classic PATs), so its row would permanently false-positive as 0/3 degraded. Host-level coverage is retained regardless — its runners share the Mac with the rows below, so a wedged host still trips domio/athportal. What is NOT covered: swarm-os's individual launchd services dying while the host stays healthy, and its stale-queue check. Re-add the entry if a Beestera-owned credential (fine-grained PAT or GitHub App) plus per-repo token support ever lands.",
   "$comment_staleQueuedMinutes": "A queued/waiting workflow run older than this many minutes with no online runner matching its labels is flagged as a queue-staleness signal (optional per-repo override via `staleQueuedMinutes`).",
   "defaultStaleQueuedMinutes": 20,
@@ -7,13 +8,13 @@
     {
       "name": "domio",
       "repo": "dsj1984/domio",
-      "expectedCount": 3,
+      "expectedCount": 7,
       "labels": ["self-hosted", "macOS", "ARM64", "domio-runner"]
     },
     {
       "name": "athportal",
       "repo": "dsj1984/athportal",
-      "expectedCount": 3,
+      "expectedCount": 5,
       "labels": ["self-hosted", "macOS", "ARM64", "athportal-runner"]
     }
   ]

package/templates/runbooks/runner-provisioning.md

@@ -66,6 +66,28 @@ shasum -a 256 actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz
 tar xzf actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz
 ```
 
+## ⚠️ Read second: keep the health-monitor roster in lockstep
+
+Any change to a fleet's size — **adding or removing a runner** — **MUST** be
+accompanied by an update to that repo's `expectedCount` in
+[`scripts/runner-fleet-consumers.json`](../../scripts/runner-fleet-consumers.json).
+That file is the roster the scheduled `runner-fleet-health.yml` monitor
+(`scripts/check-runner-health.mjs`) compares the live fleet against.
+
+- **Scale up (add a runner):** bump `expectedCount` so the shortfall floor
+  keeps pace. Over-provisioning does not trip the alarm on its own (the
+  monitor is **warn-below**: `shortfall = max(0, expectedCount - matchingOnline)`),
+  but leaving the count stale hides a later drop back down to the old value.
+- **Scale down (remove a runner):** lower `expectedCount` in the same change,
+  otherwise the monitor will correctly flag the now-missing runner(s) as a
+  shortfall and page the operator for a deliberate downsizing.
+
+If the roster and the live fleet drift apart, the monitor either false-alarms
+(count too high) or goes silent on real outages above the stale threshold
+(count too low) — the exact mis-calibration this contract exists to prevent.
+See also [`runner-fleet-health.md`](runner-fleet-health.md) for the operator
+response when the monitor does fire.
+
 ## 2. Register with `config.sh` (repo-level)
 
 Registration is **repo-level** (the fleet's standing model), not org-level.
@@ -179,7 +201,10 @@ The runner loads `.env` at service start — after any `.env` change, restart:
   (§5). Mint the removal token via
   `gh api -X POST repos/<OWNER>/<REPO>/actions/runners/remove-token --jq .token`.
 - **Decommission.** Same removal sequence, then delete `<RUNNER_DIR>`.
-  Confirm the runner disappeared from *Settings → Actions → Runners*.
+  Confirm the runner disappeared from *Settings → Actions → Runners*, **and**
+  lower the repo's `expectedCount` in `scripts/runner-fleet-consumers.json`
+  (see the roster-lockstep callout above) so the health monitor does not flag
+  the intentional removal as a shortfall.
 
 ## Project-Specific Notes