mandrel-platform 0.21.0 → 0.24.0

package/package.json

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

package/scripts/check-runner-health.mjs

@@ -0,0 +1,469 @@
+#!/usr/bin/env node
+/**
+ * check-runner-health.mjs
+ *
+ * Scheduled runner-fleet health monitor for mandrel-platform (Story #258).
+ *
+ * All nine self-hosted runners across the fleet (domio, athportal, swarm-os)
+ * are co-resident on ONE operator Mac (2026-07-03 runner audit, repo-ops
+ * matrix §1a). If that host sleeps, reboots for an OS update, fills its disk,
+ * or a launchd service dies, every consumer's CI and deploy-trigger jobs
+ * silently queue ("waiting for a runner") with no alert — nothing watches the
+ * fleet today. This script is the standing check that closes that gap.
+ *
+ * Modeled on `check-pin-drift.mjs` (same GitHub-hosted, config-driven,
+ * `GITHUB_STEP_SUMMARY`-rendering shape via the `scripts/lib/gh-json.mjs`
+ * seam) with two differences: it must run FREQUENTLY (not weekly) and it must
+ * ALERT (not just render a dashboard), because the whole point is catching an
+ * offline fleet fast.
+ *
+ * For each repo in `scripts/runner-fleet-consumers.json` it:
+ *   1. Calls `GET /repos/{owner}/{repo}/actions/runners` and flags any runner
+ *      whose `status !== "online"`.
+ *   2. Flags a count shortfall: fewer online runners matching the expected
+ *      `labels` set than `expectedCount`.
+ *   3. Flags queue-staleness: a `queued`/`waiting` workflow run older than
+ *      `staleQueuedMinutes` with no online runner matching its labels
+ *      (a wedged fleet accepts jobs into the queue but never claims them).
+ *   4. Renders a per-repo dashboard to `GITHUB_STEP_SUMMARY`.
+ *
+ * Alerting (no external dependency, on-ethos default): the CLI exits
+ * non-zero when any repo is unhealthy, so GitHub's native failed-workflow
+ * notification fires. That is the only alert channel — no tracking issues
+ * are filed.
+ *
+ * GitHub access is via the `gh` CLI (`gh api`), through the same injectable
+ * `runGh` seam `check-pin-drift.mjs` uses (`scripts/lib/gh-json.mjs`), so the
+ * whole pipeline is exercised offline in tests with canned responses.
+ *
+ * Usage:
+ *   node scripts/check-runner-health.mjs
+ *   node scripts/check-runner-health.mjs --config scripts/runner-fleet-consumers.json
+ *   node scripts/check-runner-health.mjs --json          # machine-readable envelope
+ *
+ * Exit codes:
+ *   0 — every repo healthy.
+ *   1 — at least one repo unhealthy (offline runner, count shortfall, stale
+ *       queued run, or a fetch error), OR a fatal error (bad config).
+ *
+ * GitHub Actions: when GITHUB_STEP_SUMMARY is set, the human-readable report
+ * is also appended there so it renders on the job summary page.
+ */
+
+import { readFileSync, appendFileSync } from "node:fs";
+import { resolve } from "node:path";
+
+import { defaultGhRunner, ghApiJson, isNotFound } from "./lib/gh-json.mjs";
+
+// ---------------------------------------------------------------------------
+// Arg parsing
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {string[]} argv
+ * @returns {{ config: string, json: boolean }}
+ */
+export function parseArgv(argv = []) {
+  let config = "scripts/runner-fleet-consumers.json";
+  let json = false;
+  for (let i = 0; i < argv.length; i += 1) {
+    const a = argv[i];
+    if (a === "--config") {
+      const next = argv[i + 1];
+      if (next && !next.startsWith("--")) {
+        config = next;
+        i += 1;
+      }
+    } else if (a === "--json") {
+      json = true;
+    }
+  }
+  return { config, json };
+}
+
+// ---------------------------------------------------------------------------
+// Pure helpers (exported for unit-style probing without GitHub access)
+// ---------------------------------------------------------------------------
+
+/**
+ * Does a runner's label set satisfy the expected label roster? A runner
+ * "matches" when every expected label is present among the runner's labels
+ * (order-independent, extra labels on the runner are fine).
+ *
+ * @param {string[]} runnerLabels
+ * @param {string[]} expectedLabels
+ * @returns {boolean}
+ */
+export function runnerMatchesLabels(runnerLabels, expectedLabels) {
+  const have = new Set((runnerLabels || []).map((l) => l.toLowerCase()));
+  return (expectedLabels || []).every((l) => have.has(l.toLowerCase()));
+}
+
+/**
+ * Classify one repo's live runner list against its expected roster.
+ *
+ * @param {Array<{ id: number, name: string, status: string, busy?: boolean, labels: Array<{ name: string }> }>} runners
+ * @param {{ expectedCount: number, labels: string[] }} expected
+ * @returns {{
+ *   total: number,
+ *   online: number,
+ *   offline: Array<{ id: number, name: string, status: string }>,
+ *   matchingOnline: number,
+ *   shortfall: number,
+ *   hasShortfall: boolean,
+ *   hasOffline: boolean,
+ * }}
+ */
+export function classifyRunners(runners, expected) {
+  const list = Array.isArray(runners) ? runners : [];
+  const offline = list
+    .filter((r) => r.status !== "online")
+    .map((r) => ({ id: r.id, name: r.name, status: r.status }));
+  const online = list.filter((r) => r.status === "online");
+  const matchingOnline = online.filter((r) =>
+    runnerMatchesLabels(
+      (r.labels || []).map((l) => (typeof l === "string" ? l : l.name)),
+      expected.labels,
+    ),
+  ).length;
+  const expectedCount =
+    typeof expected.expectedCount === "number" ? expected.expectedCount : 0;
+  const shortfall = Math.max(0, expectedCount - matchingOnline);
+  return {
+    total: list.length,
+    online: online.length,
+    offline,
+    matchingOnline,
+    shortfall,
+    hasShortfall: shortfall > 0,
+    hasOffline: offline.length > 0,
+  };
+}
+
+/**
+ * Is a workflow run "stuck in queue"? True when its status is `queued` or
+ * `waiting`, it is older than `staleMinutes`, and no online runner in
+ * `onlineLabelSets` matches every one of its `labels` (i.e. nothing could ever
+ * pick it up).
+ *
+ * @param {{ status: string, created_at: string, labels?: string[] }} run  A workflow run summary (labels resolved from its job requirements when available).
+ * @param {string[][]} onlineLabelSets  Each online runner's label list.
+ * @param {number} staleMinutes
+ * @param {number} [nowMs]  Injectable current epoch ms (for tests).
+ * @returns {boolean}
+ */
+export function isStaleQueuedRun(run, onlineLabelSets, staleMinutes, nowMs = Date.now()) {
+  if (run.status !== "queued" && run.status !== "waiting") return false;
+  const createdMs = Date.parse(run.created_at);
+  if (Number.isNaN(createdMs)) return false;
+  const ageMinutes = (nowMs - createdMs) / 60000;
+  if (ageMinutes < staleMinutes) return false;
+  const runLabels = Array.isArray(run.labels) ? run.labels : [];
+  if (runLabels.length === 0) {
+    // No label info to match against — can't assert "nothing could pick this
+    // up" without over-claiming, so don't flag it as stale from labels alone.
+    return false;
+  }
+  const anyOnlineMatches = onlineLabelSets.some((labels) =>
+    runnerMatchesLabels(labels, runLabels),
+  );
+  return !anyOnlineMatches;
+}
+
+/**
+ * Combine the three health signals into a single per-repo health verdict.
+ *
+ * @param {ReturnType<typeof classifyRunners>} runnerVerdict
+ * @param {Array<object>} staleRuns
+ * @returns {boolean} true when the repo is healthy (no offline, no shortfall, no stale queued runs).
+ */
+export function isRepoHealthy(runnerVerdict, staleRuns) {
+  return (
+    !runnerVerdict.hasOffline &&
+    !runnerVerdict.hasShortfall &&
+    (!Array.isArray(staleRuns) || staleRuns.length === 0)
+  );
+}
+
+/**
+ * Render the human-readable dashboard report.
+ *
+ * @param {{
+ *   results: Array<{
+ *     name: string,
+ *     repo: string,
+ *     error?: string,
+ *     verdict?: ReturnType<typeof classifyRunners>,
+ *     staleRuns?: Array<{ id: number, html_url?: string, created_at: string }>,
+ *     healthy?: boolean,
+ *   }>,
+ * }} report
+ * @returns {string}
+ */
+export function renderReport(report) {
+  const out = [];
+  out.push("## Runner-fleet health dashboard");
+  out.push("");
+  out.push(
+    "All self-hosted runners are co-resident on one operator Mac — a wedged " +
+      "host silently stalls every listed repo's CI with no other alert.",
+  );
+  out.push("");
+  out.push("| Repo | Online / Expected | Offline | Stale queued | Status |");
+  out.push("| ---- | ------------------ | ------- | ------------- | ------ |");
+
+  const problemLines = [];
+  for (const r of report.results) {
+    if (r.error) {
+      out.push(`| \`${r.name}\` | — | — | — | ⚠️ error |`);
+      problemLines.push(`- \`${r.name}\` (${r.repo}): error — ${r.error}`);
+      continue;
+    }
+    const v = r.verdict;
+    const stale = Array.isArray(r.staleRuns) ? r.staleRuns : [];
+    const healthy = r.healthy === true;
+    const status = healthy ? "✅ healthy" : "❌ degraded";
+    out.push(
+      `| \`${r.name}\` | ${v.matchingOnline}/${v.matchingOnline + v.shortfall} | ${v.offline.length} | ${stale.length} | ${status} |`,
+    );
+    if (!healthy) {
+      if (v.hasOffline) {
+        const names = v.offline.map((o) => `\`${o.name}\` (${o.status})`).join(", ");
+        problemLines.push(
+          `- \`${r.name}\` (${r.repo}): OFFLINE runner(s) — ${names}.`,
+        );
+      }
+      if (v.hasShortfall) {
+        problemLines.push(
+          `- \`${r.name}\` (${r.repo}): SHORTFALL — ${v.matchingOnline} online runner(s) matching labels, expected at least ${v.matchingOnline + v.shortfall}.`,
+        );
+      }
+      if (stale.length > 0) {
+        const runs = stale
+          .map((run) => (run.html_url ? `[#${run.id}](${run.html_url})` : `#${run.id}`))
+          .join(", ");
+        problemLines.push(
+          `- \`${r.name}\` (${r.repo}): STALE QUEUED RUN(S) — ${runs} queued with no matching online runner.`,
+        );
+      }
+    }
+  }
+
+  out.push("");
+  if (problemLines.length > 0) {
+    out.push("### Degraded");
+    out.push("");
+    out.push(...problemLines);
+    out.push("");
+    out.push(
+      "**Operator response:** wake/reboot the Mac, check disk space, and " +
+        "restart the launchd runner services. See " +
+        "`templates/runbooks/runner-fleet-health.md`.",
+    );
+  } else {
+    out.push("### ✅ Fleet healthy");
+    out.push("");
+    out.push("Every configured repo has its expected online runner count and no stale queued runs.");
+  }
+  out.push("");
+  return out.join("\n");
+}
+
+// ---------------------------------------------------------------------------
+// GitHub access — runners + workflow runs.
+// ---------------------------------------------------------------------------
+
+/**
+ * Fetch a repo's live self-hosted runner list.
+ *
+ * @param {string} repo    "owner/name".
+ * @param {(args: string[]) => string} runGh
+ * @returns {Array<{ id: number, name: string, status: string, busy?: boolean, labels: Array<{ name: string }> }>}
+ */
+export function fetchRunners(repo, runGh) {
+  let obj;
+  try {
+    obj = ghApiJson(`repos/${repo}/actions/runners?per_page=100`, runGh);
+  } catch (err) {
+    if (isNotFound(err)) return [];
+    throw err;
+  }
+  return Array.isArray(obj?.runners) ? obj.runners : [];
+}
+
+/**
+ * Fetch a repo's currently queued/waiting workflow runs (for stale-queue
+ * detection). Returns [] on a 404 (repo unreadable, or genuinely no runs);
+ * any other error propagates so the caller records an `error` row.
+ *
+ * @param {string} repo
+ * @param {(args: string[]) => string} runGh
+ * @returns {Array<{ id: number, status: string, created_at: string, html_url?: string, labels?: string[] }>}
+ */
+export function fetchQueuedRuns(repo, runGh) {
+  let obj;
+  try {
+    obj = ghApiJson(
+      `repos/${repo}/actions/runs?status=queued&per_page=50`,
+      runGh,
+    );
+  } catch (err) {
+    if (isNotFound(err)) return [];
+    throw err;
+  }
+  const queued = Array.isArray(obj?.workflow_runs) ? obj.workflow_runs : [];
+  let waitingObj;
+  try {
+    waitingObj = ghApiJson(
+      `repos/${repo}/actions/runs?status=waiting&per_page=50`,
+      runGh,
+    );
+  } catch (err) {
+    if (isNotFound(err)) return queued;
+    throw err;
+  }
+  const waiting = Array.isArray(waitingObj?.workflow_runs)
+    ? waitingObj.workflow_runs
+    : [];
+  return [...queued, ...waiting];
+}
+
+// ---------------------------------------------------------------------------
+// Orchestration
+// ---------------------------------------------------------------------------
+
+/**
+ * Build the full health report for the configured repos.
+ *
+ * @param {{
+ *   repos: Array<{ name: string, repo: string, expectedCount: number, labels: string[], staleQueuedMinutes?: number }>,
+ *   defaultStaleQueuedMinutes?: number,
+ * }} config
+ * @param {(args: string[]) => string} runGh
+ * @param {number} [nowMs]
+ * @returns {{ results: Array<object> }}
+ */
+export function buildReport(config, runGh, nowMs = Date.now()) {
+  const defaultStale =
+    typeof config.defaultStaleQueuedMinutes === "number"
+      ? config.defaultStaleQueuedMinutes
+      : 20;
+  const results = [];
+  for (const entry of config.repos) {
+    try {
+      const runners = fetchRunners(entry.repo, runGh);
+      const verdict = classifyRunners(runners, entry);
+      const onlineLabelSets = runners
+        .filter((r) => r.status === "online")
+        .map((r) => (r.labels || []).map((l) => (typeof l === "string" ? l : l.name)));
+      const staleMinutes =
+        typeof entry.staleQueuedMinutes === "number"
+          ? entry.staleQueuedMinutes
+          : defaultStale;
+      const queuedRuns = fetchQueuedRuns(entry.repo, runGh);
+      const staleRuns = queuedRuns.filter((run) =>
+        isStaleQueuedRun(run, onlineLabelSets, staleMinutes, nowMs),
+      );
+      results.push({
+        name: entry.name,
+        repo: entry.repo,
+        verdict,
+        staleRuns,
+        healthy: isRepoHealthy(verdict, staleRuns),
+      });
+    } catch (err) {
+      results.push({
+        name: entry.name,
+        repo: entry.repo,
+        error: err instanceof Error ? err.message : String(err),
+        healthy: false,
+      });
+    }
+  }
+  return { results };
+}
+
+/**
+ * @param {{ results: Array<{ error?: string, healthy?: boolean }> }} report
+ * @returns {boolean} true when any repo is unhealthy or errored.
+ */
+export function hasUnhealthy(report) {
+  return report.results.some((r) => r.error || r.healthy === false);
+}
+
+// ---------------------------------------------------------------------------
+// CLI entry
+// ---------------------------------------------------------------------------
+
+/**
+ * @param {{
+ *   argv?: string[],
+ *   cwd?: string,
+ *   stdout?: { write: (s: string) => void },
+ *   stderr?: { write: (s: string) => void },
+ *   runGh?: (args: string[]) => string,
+ *   summaryPath?: string | undefined,
+ *   nowMs?: number,
+ * }} [opts]
+ * @returns {number} exit code
+ */
+export function runCli({
+  argv = process.argv.slice(2),
+  cwd = process.cwd(),
+  stdout = process.stdout,
+  stderr = process.stderr,
+  runGh = defaultGhRunner,
+  summaryPath = process.env.GITHUB_STEP_SUMMARY,
+  nowMs = Date.now(),
+} = {}) {
+  const { config: configRel, json } = parseArgv(argv);
+  const configPath = resolve(cwd, configRel);
+
+  let config;
+  try {
+    config = JSON.parse(readFileSync(configPath, "utf-8"));
+  } catch (err) {
+    stderr.write(
+      `[runner-health] ❌ failed to read config ${configPath}: ${err instanceof Error ? err.message : String(err)}\n`,
+    );
+    return 1;
+  }
+  if (!Array.isArray(config.repos)) {
+    stderr.write(`[runner-health] ❌ config must define { repos: [] }\n`);
+    return 1;
+  }
+
+  const report = buildReport(config, runGh, nowMs);
+  const unhealthy = hasUnhealthy(report);
+
+  if (json) {
+    stdout.write(
+      `${JSON.stringify({ kind: "runner-fleet-health-report", unhealthy, ...report }, null, 2)}\n`,
+    );
+  } else {
+    const text = renderReport(report);
+    stdout.write(`${text}\n`);
+    if (summaryPath) {
+      try {
+        appendFileSync(summaryPath, `${text}\n`);
+      } catch (err) {
+        stderr.write(
+          `[runner-health] ⚠ could not write job summary: ${err instanceof Error ? err.message : String(err)}\n`,
+        );
+      }
+    }
+  }
+
+  if (unhealthy) {
+    stderr.write(`[runner-health] ❌ fleet degraded\n`);
+    return 1;
+  }
+  return 0;
+}
+
+// Direct-invocation guard (matches the repo's other scripts/*.mjs entry style).
+const invokedDirectly =
+  process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname);
+if (invokedDirectly) {
+  process.exit(runCli());
+}

package/scripts/check-runner-health.test.mjs

@@ -0,0 +1,389 @@
+#!/usr/bin/env node
+/**
+ * check-runner-health.test.mjs — node:test suite for the scheduled
+ * runner-fleet health monitor (Story #258).
+ *
+ * The checker exposes pure helpers plus an injectable `runGh` seam, so the
+ * whole pipeline is exercised offline with canned GitHub responses — no
+ * network, no `gh` auth.
+ *
+ * Run: node scripts/check-runner-health.test.mjs   (or `node --test scripts/`)
+ */
+
+import assert from "node:assert/strict";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { test } from "node:test";
+
+import {
+  buildReport,
+  classifyRunners,
+  fetchQueuedRuns,
+  fetchRunners,
+  hasUnhealthy,
+  isRepoHealthy,
+  isStaleQueuedRun,
+  parseArgv,
+  renderReport,
+  runCli,
+  runnerMatchesLabels,
+} from "./check-runner-health.mjs";
+
+// ---------------------------------------------------------------------------
+// parseArgv
+// ---------------------------------------------------------------------------
+
+test("parseArgv defaults to the fleet consumer config", () => {
+  const opts = parseArgv([]);
+  assert.equal(opts.config, "scripts/runner-fleet-consumers.json");
+  assert.equal(opts.json, false);
+});
+
+test("parseArgv parses --config and --json", () => {
+  const opts = parseArgv(["--config", "custom.json", "--json"]);
+  assert.equal(opts.config, "custom.json");
+  assert.equal(opts.json, true);
+});
+
+// ---------------------------------------------------------------------------
+// runnerMatchesLabels
+// ---------------------------------------------------------------------------
+
+test("runnerMatchesLabels is case-insensitive and order-independent", () => {
+  assert.equal(
+    runnerMatchesLabels(["Self-Hosted", "macOS", "ARM64", "domio-runner"], [
+      "self-hosted",
+      "arm64",
+    ]),
+    true,
+  );
+});
+
+test("runnerMatchesLabels fails when an expected label is missing", () => {
+  assert.equal(
+    runnerMatchesLabels(["self-hosted", "macOS"], ["self-hosted", "ARM64"]),
+    false,
+  );
+});
+
+// ---------------------------------------------------------------------------
+// classifyRunners
+// ---------------------------------------------------------------------------
+
+const EXPECTED = { expectedCount: 3, labels: ["self-hosted", "macOS", "ARM64", "domio-runner"] };
+
+test("classifyRunners reports a fully healthy fleet", () => {
+  const runners = [1, 2, 3].map((n) => ({
+    id: n,
+    name: `domio-runner-${n}`,
+    status: "online",
+    labels: [{ name: "self-hosted" }, { name: "macOS" }, { name: "ARM64" }, { name: "domio-runner" }],
+  }));
+  const v = classifyRunners(runners, EXPECTED);
+  assert.equal(v.total, 3);
+  assert.equal(v.online, 3);
+  assert.equal(v.matchingOnline, 3);
+  assert.equal(v.shortfall, 0);
+  assert.equal(v.hasShortfall, false);
+  assert.equal(v.hasOffline, false);
+});
+
+test("classifyRunners flags an offline runner", () => {
+  const runners = [
+    { id: 1, name: "domio-runner-1", status: "online", labels: [{ name: "self-hosted" }, { name: "macOS" }, { name: "ARM64" }, { name: "domio-runner" }] },
+    { id: 2, name: "domio-runner-2", status: "offline", labels: [{ name: "self-hosted" }, { name: "macOS" }, { name: "ARM64" }, { name: "domio-runner" }] },
+  ];
+  const v = classifyRunners(runners, EXPECTED);
+  assert.equal(v.hasOffline, true);
+  assert.equal(v.offline.length, 1);
+  assert.equal(v.offline[0].name, "domio-runner-2");
+  assert.equal(v.matchingOnline, 1);
+  assert.equal(v.hasShortfall, true);
+  assert.equal(v.shortfall, 2);
+});
+
+test("classifyRunners flags a count shortfall even with all-online but wrong labels", () => {
+  const runners = [
+    { id: 1, name: "other-runner", status: "online", labels: [{ name: "self-hosted" }, { name: "linux" }] },
+  ];
+  const v = classifyRunners(runners, EXPECTED);
+  assert.equal(v.hasOffline, false);
+  assert.equal(v.matchingOnline, 0);
+  assert.equal(v.hasShortfall, true);
+  assert.equal(v.shortfall, 3);
+});
+
+test("classifyRunners handles an empty runner list", () => {
+  const v = classifyRunners([], EXPECTED);
+  assert.equal(v.total, 0);
+  assert.equal(v.hasShortfall, true);
+  assert.equal(v.shortfall, 3);
+});
+
+// ---------------------------------------------------------------------------
+// isStaleQueuedRun
+// ---------------------------------------------------------------------------
+
+const NOW = Date.parse("2026-07-03T12:00:00Z");
+
+test("isStaleQueuedRun flags an old queued run with no matching online runner", () => {
+  const run = {
+    status: "queued",
+    created_at: "2026-07-03T11:00:00Z", // 60 min ago
+    labels: ["self-hosted", "macOS", "ARM64", "domio-runner"],
+  };
+  assert.equal(isStaleQueuedRun(run, [], 20, NOW), true);
+});
+
+test("isStaleQueuedRun does not flag a recently queued run", () => {
+  const run = {
+    status: "queued",
+    created_at: "2026-07-03T11:55:00Z", // 5 min ago
+    labels: ["self-hosted", "macOS", "ARM64", "domio-runner"],
+  };
+  assert.equal(isStaleQueuedRun(run, [], 20, NOW), false);
+});
+
+test("isStaleQueuedRun does not flag when a matching online runner exists", () => {
+  const run = {
+    status: "queued",
+    created_at: "2026-07-03T11:00:00Z",
+    labels: ["self-hosted", "macOS", "ARM64", "domio-runner"],
+  };
+  const onlineLabelSets = [["self-hosted", "macOS", "ARM64", "domio-runner"]];
+  assert.equal(isStaleQueuedRun(run, onlineLabelSets, 20, NOW), false);
+});
+
+test("isStaleQueuedRun ignores non-queued/waiting runs", () => {
+  const run = { status: "completed", created_at: "2026-07-03T09:00:00Z" };
+  assert.equal(isStaleQueuedRun(run, [], 20, NOW), false);
+});
+
+test("isStaleQueuedRun does not flag when no label info is available", () => {
+  const run = { status: "queued", created_at: "2026-07-03T09:00:00Z", labels: [] };
+  assert.equal(isStaleQueuedRun(run, [], 20, NOW), false);
+});
+
+// ---------------------------------------------------------------------------
+// isRepoHealthy
+// ---------------------------------------------------------------------------
+
+test("isRepoHealthy is true only with no offline/shortfall/stale", () => {
+  const healthyVerdict = { hasOffline: false, hasShortfall: false };
+  assert.equal(isRepoHealthy(healthyVerdict, []), true);
+  assert.equal(isRepoHealthy({ ...healthyVerdict, hasOffline: true }, []), false);
+  assert.equal(isRepoHealthy({ ...healthyVerdict, hasShortfall: true }, []), false);
+  assert.equal(isRepoHealthy(healthyVerdict, [{ id: 1 }]), false);
+});
+
+// ---------------------------------------------------------------------------
+// renderReport
+// ---------------------------------------------------------------------------
+
+test("renderReport renders a healthy fleet with no Degraded section", () => {
+  const report = {
+    results: [
+      {
+        name: "domio",
+        repo: "dsj1984/domio",
+        verdict: { matchingOnline: 3, shortfall: 0, offline: [], hasOffline: false, hasShortfall: false },
+        staleRuns: [],
+        healthy: true,
+      },
+    ],
+  };
+  const text = renderReport(report);
+  assert.match(text, /✅ healthy/);
+  assert.match(text, /✅ Fleet healthy/);
+  assert.doesNotMatch(text, /### Degraded/);
+});
+
+test("renderReport surfaces offline / shortfall / stale-run detail lines", () => {
+  const report = {
+    results: [
+      {
+        name: "domio",
+        repo: "dsj1984/domio",
+        verdict: {
+          matchingOnline: 1,
+          shortfall: 2,
+          offline: [{ id: 2, name: "domio-runner-2", status: "offline" }],
+          hasOffline: true,
+          hasShortfall: true,
+        },
+        staleRuns: [{ id: 42, html_url: "https://github.com/dsj1984/domio/actions/runs/42", created_at: "x" }],
+        healthy: false,
+      },
+    ],
+  };
+  const text = renderReport(report);
+  assert.match(text, /❌ degraded/);
+  assert.match(text, /OFFLINE runner\(s\)/);
+  assert.match(text, /SHORTFALL/);
+  assert.match(text, /STALE QUEUED RUN/);
+  assert.match(text, /### Degraded/);
+  assert.match(text, /templates\/runbooks\/runner-fleet-health\.md/);
+});
+
+test("renderReport surfaces a fetch error row", () => {
+  const report = { results: [{ name: "domio", repo: "dsj1984/domio", error: "boom" }] };
+  const text = renderReport(report);
+  assert.match(text, /⚠️ error/);
+  assert.match(text, /error — boom/);
+});
+
+// ---------------------------------------------------------------------------
+// fetchRunners / fetchQueuedRuns (injectable runGh)
+// ---------------------------------------------------------------------------
+
+test("fetchRunners returns the runners array from the API response", () => {
+  const runGh = () =>
+    JSON.stringify({ total_count: 1, runners: [{ id: 1, name: "r1", status: "online", labels: [] }] });
+  const runners = fetchRunners("dsj1984/domio", runGh);
+  assert.equal(runners.length, 1);
+  assert.equal(runners[0].name, "r1");
+});
+
+test("fetchRunners returns [] on a 404", () => {
+  const runGh = () => {
+    const err = new Error("gh: Not Found (HTTP 404)");
+    throw err;
+  };
+  assert.deepEqual(fetchRunners("dsj1984/domio", runGh), []);
+});
+
+test("fetchRunners propagates a non-404 error", () => {
+  const runGh = () => {
+    throw new Error("gh: Forbidden (HTTP 403)");
+  };
+  assert.throws(() => fetchRunners("dsj1984/domio", runGh));
+});
+
+test("fetchQueuedRuns merges queued and waiting runs", () => {
+  const runGh = (args) => {
+    const path = args[1];
+    if (path.includes("status=queued")) {
+      return JSON.stringify({ workflow_runs: [{ id: 1, status: "queued", created_at: "x" }] });
+    }
+    if (path.includes("status=waiting")) {
+      return JSON.stringify({ workflow_runs: [{ id: 2, status: "waiting", created_at: "y" }] });
+    }
+    throw new Error(`unexpected path ${path}`);
+  };
+  const runs = fetchQueuedRuns("dsj1984/domio", runGh);
+  assert.equal(runs.length, 2);
+  assert.deepEqual(runs.map((r) => r.id).sort(), [1, 2]);
+});
+
+test("fetchQueuedRuns returns [] on a 404", () => {
+  const runGh = () => {
+    throw new Error("gh: Not Found (HTTP 404)");
+  };
+  assert.deepEqual(fetchQueuedRuns("dsj1984/domio", runGh), []);
+});
+
+// ---------------------------------------------------------------------------
+// buildReport / hasUnhealthy
+// ---------------------------------------------------------------------------
+
+const CONFIG = {
+  defaultStaleQueuedMinutes: 20,
+  repos: [
+    { name: "domio", repo: "dsj1984/domio", expectedCount: 2, labels: ["self-hosted", "domio-runner"] },
+  ],
+};
+
+test("buildReport marks a repo healthy when runners are all online and matching", () => {
+  const runGh = (args) => {
+    const path = args[1];
+    if (path.includes("actions/runners")) {
+      return JSON.stringify({
+        runners: [
+          { id: 1, name: "r1", status: "online", labels: [{ name: "self-hosted" }, { name: "domio-runner" }] },
+          { id: 2, name: "r2", status: "online", labels: [{ name: "self-hosted" }, { name: "domio-runner" }] },
+        ],
+      });
+    }
+    if (path.includes("actions/runs")) {
+      return JSON.stringify({ workflow_runs: [] });
+    }
+    throw new Error(`unexpected ${path}`);
+  };
+  const report = buildReport(CONFIG, runGh, NOW);
+  assert.equal(report.results[0].healthy, true);
+  assert.equal(hasUnhealthy(report), false);
+});
+
+test("buildReport marks a repo unhealthy and records a fetch error as unhealthy", () => {
+  const runGh = (args) => {
+    const path = args[1];
+    if (path.includes("actions/runners")) throw new Error("gh: Service Unavailable (HTTP 503)");
+    return "{}";
+  };
+  const report = buildReport(CONFIG, runGh, NOW);
+  assert.equal(report.results[0].error !== undefined, true);
+  assert.equal(hasUnhealthy(report), true);
+});
+
+// ---------------------------------------------------------------------------
+// runCli (end-to-end against a temp config + injected runGh)
+// ---------------------------------------------------------------------------
+
+test("runCli exits 0 for a healthy fleet and 1 for a degraded one", () => {
+  const dir = mkdtempSync(join(tmpdir(), "runner-health-cli-"));
+  try {
+    const configPath = join(dir, "runner-fleet-consumers.json");
+    writeFileSync(
+      configPath,
+      JSON.stringify({
+        defaultStaleQueuedMinutes: 20,
+        repos: [
+          { name: "domio", repo: "dsj1984/domio", expectedCount: 2, labels: ["self-hosted", "domio-runner"] },
+        ],
+      }),
+    );
+    const stdout = { buf: "", write(s) { this.buf += s; } };
+    const stderr = { buf: "", write(s) { this.buf += s; } };
+    const healthyRunGh = (args) => {
+      const path = args[1];
+      if (path.includes("actions/runners")) {
+        return JSON.stringify({
+          runners: [
+            { id: 1, name: "r1", status: "online", labels: [{ name: "self-hosted" }, { name: "domio-runner" }] },
+            { id: 2, name: "r2", status: "online", labels: [{ name: "self-hosted" }, { name: "domio-runner" }] },
+          ],
+        });
+      }
+      if (path.includes("actions/runs")) return JSON.stringify({ workflow_runs: [] });
+      throw new Error(`unexpected ${path}`);
+    };
+    const code = runCli({
+      argv: ["--config", configPath],
+      cwd: process.cwd(),
+      stdout,
+      stderr,
+      runGh: healthyRunGh,
+      summaryPath: undefined,
+      nowMs: NOW,
+    });
+    assert.equal(code, 0);
+    assert.match(stdout.buf, /Fleet healthy|Runner-fleet health dashboard/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("runCli returns 1 on a bad config path", () => {
+  const stdout = { buf: "", write(s) { this.buf += s; } };
+  const stderr = { buf: "", write(s) { this.buf += s; } };
+  const code = runCli({
+    argv: ["--config", "scripts/does-not-exist.json"],
+    cwd: process.cwd(),
+    stdout,
+    stderr,
+    runGh: () => "{}",
+  });
+  assert.equal(code, 1);
+  assert.match(stderr.buf, /failed to read config/);
+});

package/scripts/platform-sync.test.mjs

@@ -570,22 +570,49 @@ test("--check-ruleset requires --consumer-repo", () => {
   }, /consumer-repo/);
 });
 
-test("apply materializes the canonical deploy-staging.yml workflow caller template", () => {
+test("apply materializes the canonical deploy-staging dispatcher + run templates (Story #272)", () => {
   const out = JSON.parse(run([]));
-  const stub = join(consumer, ".github", "workflows", "deploy-staging.yml");
-  assert.ok(existsSync(stub));
+  const dispatcher = join(consumer, ".github", "workflows", "deploy-staging.yml");
+  const runner = join(consumer, ".github", "workflows", "deploy-staging-run.yml");
+  assert.ok(existsSync(dispatcher), "deploy-staging.yml (dispatcher) materialized");
+  assert.ok(existsSync(runner), "deploy-staging-run.yml (deploy) materialized");
   assert.ok(
     out.workflowStubs.created.some((f) => f.endsWith("deploy-staging.yml")),
-    "deploy-staging.yml reported as created"
+    "deploy-staging.yml (dispatcher) reported as created"
+  );
+  assert.ok(
+    out.workflowStubs.created.some((f) => f.endsWith("deploy-staging-run.yml")),
+    "deploy-staging-run.yml (deploy) reported as created"
+  );
+  const dispatcherBody = readFileSync(dispatcher, "utf8");
+  const runnerBody = readFileSync(runner, "utf8");
+  // Both halves carry the never-clobber template marker.
+  assert.ok(
+    dispatcherBody.includes("Canonical staging-deploy caller template"),
+    "dispatcher carries the template marker"
+  );
+  assert.ok(
+    runnerBody.includes("Canonical staging-deploy caller template"),
+    "run template carries the template marker"
+  );
+  // The dispatcher fires on CI-green (workflow_run) and DISPATCHES the run
+  // workflow — it must NOT call the deploy directly, since a workflow_run
+  // deploy skips every environment: job (Story #272).
+  assert.ok(
+    dispatcherBody.includes("workflow_run") &&
+      dispatcherBody.includes("gh workflow run deploy-staging-run.yml"),
+    "dispatcher fires on workflow_run and dispatches deploy-staging-run.yml"
   );
-  const body = readFileSync(stub, "utf8");
   assert.ok(
-    body.includes("Canonical staging-deploy caller template"),
-    "materialized workflow carries the template marker"
+    !dispatcherBody.includes("dsj1984/mandrel-platform/.github/workflows/deploy-cloudflare.yml"),
+    "dispatcher does NOT uses: deploy-cloudflare.yml directly (that would skip environment: jobs on workflow_run)"
   );
+  // The deploy half runs on workflow_dispatch (where environment: jobs execute)
+  // and uses the shared reusable workflow.
   assert.ok(
-    body.includes("dsj1984/mandrel-platform/.github/workflows/deploy-cloudflare.yml"),
-    "template calls the shared deploy-cloudflare.yml reusable workflow"
+    runnerBody.includes("workflow_dispatch") &&
+      runnerBody.includes("dsj1984/mandrel-platform/.github/workflows/deploy-cloudflare.yml"),
+    "run template deploys on workflow_dispatch via the shared deploy-cloudflare.yml"
   );
 });
 

package/scripts/runner-fleet-consumers.json

@@ -0,0 +1,20 @@
+{
+  "$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_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,
+  "repos": [
+    {
+      "name": "domio",
+      "repo": "dsj1984/domio",
+      "expectedCount": 3,
+      "labels": ["self-hosted", "macOS", "ARM64", "domio-runner"]
+    },
+    {
+      "name": "athportal",
+      "repo": "dsj1984/athportal",
+      "expectedCount": 3,
+      "labels": ["self-hosted", "macOS", "ARM64", "athportal-runner"]
+    }
+  ]
+}

package/templates/runbooks/runner-fleet-health.md

@@ -0,0 +1,150 @@
+# Runner Fleet Health Monitor
+
+> **Self-contained runbook** (not a thin stub). Unlike most templates in this
+> directory, there is no canonical `docs/runbooks/` counterpart to link — this
+> file IS the process, mirroring `runner-provisioning.md`. It documents the
+> scheduled `.github/workflows/runner-fleet-health.yml` monitor (Story #258):
+> what it checks, the token scope it needs, the alert semantics, and the
+> operator response when it fires.
+
+---
+
+## Why this exists
+
+All self-hosted runners across the fleet (`domio`, `athportal`, `swarm-os`)
+are **co-resident on one operator Mac**. If that host sleeps, reboots for an
+OS update, fills its disk, or a launchd runner service dies, **every
+consumer's CI and deploy-trigger jobs silently queue** ("waiting for a
+runner") with no alert. Nothing else watches this:
+
+- The Better Stack uptime unit (`uptime-apply.yml`) monitors the **deployed
+  apps**, not the runners.
+- Deploy pipelines are `workflow_run`-gated, so a wedged runner can silently
+  stall staging indefinitely — no failed job, no notification, just a queue
+  that never drains.
+
+> **Roster note:** `Beestera/swarm-os` is monitored only *indirectly*. No
+> `dsj1984`-owned token can read another org's runner API (fine-grained PATs
+> are bound to one resource owner; the Beestera org rejects classic PATs), so
+> its roster entry would permanently false-positive as `0/3` degraded.
+> Because its runners share the Mac with the rostered repos, a wedged
+> **host** still trips the `domio`/`athportal` rows; what goes unwatched is a
+> swarm-os-only launchd service death and its stale queue. See
+> `$comment_swarm_os` in `scripts/runner-fleet-consumers.json`.
+
+`runner-fleet-health.yml` is the standing check that catches this fast.
+
+## What it checks
+
+Runs on a schedule (~every 15 minutes) plus `workflow_dispatch`, on
+`ubuntu-latest` (deliberately GitHub-hosted so it keeps running when the Mac
+is down). For each repo in `scripts/runner-fleet-consumers.json` it calls
+`GET /repos/{owner}/{repo}/actions/runners` and:
+
+1. **Offline runners** — flags any runner whose `status != online`.
+2. **Count shortfall** — flags fewer online runners matching the repo's
+   expected `labels` set than its configured `expectedCount`.
+3. **Stale queued runs** (optional signal) — a `queued`/`waiting` workflow run
+   older than `staleQueuedMinutes` (default 20) with no online runner matching
+   its labels. This catches the case where the runner *looks* present in the
+   roster count but is actually wedged and not claiming jobs.
+
+It renders a per-repo dashboard on `GITHUB_STEP_SUMMARY`.
+
+## Config-driven roster
+
+Adding, removing, or resizing a runner needs **only a config edit** —
+`scripts/runner-fleet-consumers.json`:
+
+```jsonc
+{
+  "defaultStaleQueuedMinutes": 20,
+  "repos": [
+    { "name": "domio", "repo": "dsj1984/domio", "expectedCount": 3, "labels": ["self-hosted", "macOS", "ARM64", "domio-runner"] },
+    // ... one object per repo
+  ],
+}
+```
+
+## Token scope: `PIN_DRIFT_TOKEN`
+
+The monitor reuses the same fine-grained PAT `pin-drift.yml` already
+provisions (`secrets.PIN_DRIFT_TOKEN`), falling back to the built-in
+`github.token` when the secret is absent (the built-in token only grants read
+access to the workflow's own repo — cross-repo rows then surface as `⚠️
+error` rather than hard-failing this repo's own row).
+
+For the runner reads, `PIN_DRIFT_TOKEN` must carry, on every rostered repo:
+
+- **Administration: read** — required by `GET .../actions/runners` (the
+  self-hosted runner list is an admin-surface endpoint; `actions:read` is
+  NOT sufficient for it).
+- **Actions: read** — required by `GET .../actions/runs` (the stale-queue
+  check).
+
+Resource-owner caveat: a fine-grained PAT is bound to a **single** resource
+owner, and the Beestera org rejects classic PATs — which is exactly why
+`Beestera/swarm-os` is off the roster (see the roster note above). Every
+rostered repo must be readable by the ONE token this workflow gets; a repo
+the token cannot see 404s and false-positives as degraded, so extend the
+roster only together with a credential that covers the new repo.
+
+When the token lacks visibility, GitHub returns **404** (not 403) and the
+script treats the empty runner list as a real shortfall — the repo's row
+reads `❌ degraded` with `0/N` online even when the runners are healthy. A
+fleet-wide `0/N` across every repo is the token-misconfiguration signature;
+check the secret before touching the runner host.
+
+## Alert semantics
+
+Alert-only by design (no host-side remediation) — the monitor never touches
+the runner host itself. One channel fires on an unhealthy repo, deliberately
+without adding a new external dependency:
+
+- **Native GitHub failed-workflow notification.** The job script exits
+  non-zero when any repo is unhealthy, so GitHub's own email/notification
+  settings fire the standard "workflow run failed" alert to whoever
+  watches this repo. No tracking issues are filed — the dashboard detail
+  lives on the failed run's job summary.
+
+A future Slack/PagerDuty push could layer on top of this later — deliberately
+deferred (see the Story's Out of Scope) to avoid a new external dependency for
+the initial alert-only default.
+
+## Operator response
+
+When the scheduled workflow run fails:
+
+1. **Read the dashboard** on the workflow run's job summary — it names which
+   signal fired (offline runner, count shortfall, or stale queued run) and
+   for which repo.
+2. **Wake or reboot the Mac** if it's asleep, powered off, or unresponsive
+   over SSH.
+3. **Check disk space** (`df -h`) — a full disk is a common launchd-runner
+   death cause; free space and restart the affected runner service(s).
+4. **Restart the launchd runner service(s)** for the affected repo:
+   ```bash
+   cd <RUNNER_DIR>          # see templates/runbooks/runner-provisioning.md
+   ./svc.sh stop && ./svc.sh start
+   ./svc.sh status          # expect: Started · running
+   ```
+5. **Re-run the monitor** (`workflow_dispatch` from the Actions tab, or wait
+   for the next 15-minute tick) to confirm recovery — a green run means the
+   fleet reports healthy again.
+
+## Out of scope (Story #258)
+
+- Host-side remediation / auto-recovery (waking the Mac, restarting services)
+  — this monitor is alert-only; the operator performs the response above by
+  hand.
+- Host disk-usage monitoring — not exposable via the runners API anyway, and
+  tracked separately.
+- External paging integrations beyond the native failed-workflow
+  notification.
+- Cross-repo runner isolation / ephemeral-runner questions — explicitly
+  deferred.
+
+## Project-Specific Notes
+
+<!-- Record host quirks, roster changes, or false-positive tuning
+     (staleQueuedMinutes overrides) specific to this fleet. -->

package/templates/workflows/deploy-staging-run.yml

@@ -0,0 +1,77 @@
+name: deploy-staging-run
+
+# Canonical staging-deploy caller template — DEPLOY half (Story #272).
+#
+# > **Why this file runs on `workflow_dispatch`.** Its sibling
+# > `deploy-staging.yml` fires on CI-green (`workflow_run`) and DISPATCHES this
+# > workflow. The deploy lives here, on `workflow_dispatch`, because the shared
+# > `deploy-cloudflare.yml`'s `environment:`-gated jobs (`check-env` /
+# > `migration` / `deploy` / `boot-smoke`) are silently SKIPPED on a
+# > `workflow_run` event but run normally on `workflow_dispatch` (Story #272).
+# > Adopt this file together with `deploy-staging.yml`; `platform-sync`
+# > materializes both.
+#
+# > **Thin local caller.** The defence-in-depth deploy core lives in the shared
+# > `dsj1984/mandrel-platform` `deploy-cloudflare.yml` reusable workflow — see
+# > https://github.com/dsj1984/mandrel-platform/blob/main/docs/reusable-workflows.md#deploy-cloudflareyml.
+# > This file only holds <PROJECT_NAME>-specific values (worker names, build
+# > step, secret mapping). When the deploy PROCESS changes, that change lands
+# > upstream in mandrel-platform — not here.
+#
+# Replace every <PLACEHOLDER> with your project's real values:
+#   <MANDREL_PLATFORM_SHA>   the pinned mandrel-platform commit SHA (resolve via
+#                            `node scripts/platform-sync.mjs --ref <release-tag>`
+#                            from the consumer repo root, or `git ls-remote`).
+#   <MANDREL_PLATFORM_TAG>   the human-readable release tag matching the SHA
+#                            above (trailing `# <tag>` comment).
+#   <WORKERS_CSV>            comma-separated Worker names for this env, e.g.
+#                            "api,web".
+#   <BUILD_COMMAND>          optional build command (omit build-command /
+#                            build-artifact entirely if the deploy job's default
+#                            checkout is build-ready).
+#
+# See the full input/secret contract:
+# https://github.com/dsj1984/mandrel-platform/blob/main/docs/reusable-workflows.md#deploy-cloudflareyml
+
+on:
+  # Dispatched by deploy-staging.yml on CI-green, and available for manual
+  # on-demand deploys (UI "Run workflow" + `gh workflow run`). The optional sha
+  # input records the CI-verified commit; the deploy itself runs against the
+  # main tip (`--ref main`).
+  workflow_dispatch:
+    inputs:
+      sha:
+        description: >
+          Commit SHA that passed CI (informational — the deploy runs against
+          the current main tip). Populated automatically when dispatched by
+          deploy-staging.yml.
+        required: false
+        type: string
+
+permissions:
+  contents: read
+
+# Serialize staging deploys: only the freshest dispatch should reach the
+# staging surfaces. The shared deploy-cloudflare.yml additionally serializes
+# per-environment.
+concurrency:
+  group: deploy-staging-run
+  cancel-in-progress: true
+
+jobs:
+  deploy:
+    name: Staging deploy (shared deploy-cloudflare.yml)
+    uses: dsj1984/mandrel-platform/.github/workflows/deploy-cloudflare.yml@<MANDREL_PLATFORM_SHA> # <MANDREL_PLATFORM_TAG>
+    with:
+      environment: staging
+      gh-environment: staging
+      workers: <WORKERS_CSV>
+      migrate: true
+      # db-engine defaults to 'd1'. Set db-engine + migrate-command +
+      # snapshot-command for a non-D1 engine (e.g. Turso) — see the contract
+      # doc's "command seams" section.
+    # Frozen secret allowlist: only {CLOUDFLARE_*, TURSO_*} cross into the
+    # shared workflow. Map your project's secret NAMES onto these slots.
+    secrets:
+      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
+      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}

package/templates/workflows/deploy-staging.yml

@@ -1,89 +1,91 @@
 name: deploy-staging
 
-# Canonical staging-deploy caller template (Story #175).
+# Canonical staging-deploy caller template — DISPATCHER half (Story #175,
+# reworked for Story #272).
+#
+# > **Why two files (Story #272).** A reusable workflow's `environment:`-gated
+# > jobs (`deploy-cloudflare.yml`'s `check-env` / `migration` / `deploy` /
+# > `boot-smoke`) are **silently skipped on a `workflow_run` event** — a
+# > documented GitHub limitation. The previous single-file template called
+# > `deploy-cloudflare.yml` DIRECTLY from `on: workflow_run`, so those jobs
+# > skipped and **0 workers deployed while the run reported green** (all-skipped,
+# > none failed). One consumer hid 40+ consecutive non-deploys this way.
+# >
+# > The fix: this file is now a thin **dispatcher** that fires on CI-green and
+# > re-launches the deploy via **`workflow_dispatch`** — the event on which the
+# > `environment:` jobs DO run — against its sibling `deploy-staging-run.yml`.
+# > `workflow_dispatch` and `repository_dispatch` are the two events that
+# > "always create workflow runs" even when triggered with the built-in
+# > `GITHUB_TOKEN`, so **no PAT is required** for this same-repo dispatch — just
+# > `permissions: actions: write` below. (Cross-repo dispatch, like
+# > `smoke-dispatch.yml`, still needs a PAT; same repo does not.)
 #
 # > **Thin local caller.** The defence-in-depth deploy core (secret-isolation
 # > audit -> CF env gate -> migration (snapshot + apply) -> deploy ->
-# > boot-smoke + auto-rollback) AND the CI-green guard both live in the shared
+# > boot-smoke + auto-rollback) lives in the shared
 # > `dsj1984/mandrel-platform` `deploy-cloudflare.yml` reusable workflow — see
 # > https://github.com/dsj1984/mandrel-platform/blob/main/docs/reusable-workflows.md#deploy-cloudflareyml.
-# > This file only holds <PROJECT_NAME>-specific values (worker names, build
-# > step, secret mapping). When the deploy PROCESS changes, that change lands
-# > upstream in mandrel-platform — not here.
-#
-# One paved road (operator decision 2026-07-01, D4): every consumer triggers
-# staging deploy via `workflow_run` on its own CI workflow, gated on
-# `conclusion == 'success'`. `workflow_run` fires on BOTH a successful AND a
-# failed upstream run, so a caller-side guard against a red run used to be
-# REQUIRED here — every consumer hand-copied the same `preflight` job (see
-# mandrel-platform Story #175 context). That guard now lives INSIDE
-# `deploy-cloudflare.yml` itself as a job-level `if:` on its entry jobs
-# (`github.event` inside a reusable workflow is the CALLER's event, so the
-# shared workflow can see and gate on the `workflow_run` conclusion even
-# though it cannot own this file's `on:` block); a red upstream run skips
-# the whole chain with zero runner spin-ups (mandrel-platform Story #237).
-# This template needs NO caller-side preflight guard as a result —
-# copy it as-is and fill in the placeholders below.
+# > The <PROJECT_NAME>-specific values (worker names, build step, secret
+# > mapping) live in the sibling `deploy-staging-run.yml`. When the deploy
+# > PROCESS changes, that change lands upstream in mandrel-platform — not here.
 #
-# Replace every <PLACEHOLDER> with your project's real values:
-#   <CI_WORKFLOW_NAME>        the `name:` of the workflow this deploy should
-#                              gate on (e.g. "quality", "CI", "PR Quality").
-#                              Must match EXACTLY — GitHub matches
-#                              `workflow_run.workflows` by workflow name, not
-#                              file path.
-#   <MANDREL_PLATFORM_SHA>     the pinned mandrel-platform commit SHA (resolve
-#                              via `node scripts/platform-sync.mjs --ref
-#                              <release-tag>` from the consumer repo root, or
-#                              hand-resolve via `git ls-remote`).
-#   <MANDREL_PLATFORM_TAG>     the human-readable release tag matching the SHA
-#                              above (trailing `# <tag>` comment).
-#   <WORKERS_CSV>              comma-separated Worker names for this env, e.g.
-#                              "api,web".
-#   <BUILD_COMMAND>            optional build command (omit build-command /
-#                              build-artifact entirely if the deploy job's
-#                              default checkout is build-ready).
+# Adopt BOTH files together: this `deploy-staging.yml` (dispatcher) and
+# `deploy-staging-run.yml` (the actual deploy). `platform-sync` materializes
+# both. Replace every <PLACEHOLDER>:
+#   <CI_WORKFLOW_NAME>   the `name:` of the workflow this deploy gates on (e.g.
+#                        "quality", "CI"). Must match EXACTLY — GitHub matches
+#                        `workflow_run.workflows` by workflow name, not path.
 #
 # See the full input/secret contract:
 # https://github.com/dsj1984/mandrel-platform/blob/main/docs/reusable-workflows.md#deploy-cloudflareyml
 
 on:
-  # CI-green gate: fires when <CI_WORKFLOW_NAME> finishes on main. The shared
-  # deploy-cloudflare.yml's job-level CI-green gate skips the entire job
-  # chain (zero runners) unless the upstream conclusion was 'success' — no
-  # caller-side guard needed.
+  # CI-green gate: fires when <CI_WORKFLOW_NAME> completes on main. Unlike the
+  # old shape, this does NOT call the deploy directly — a `workflow_run` deploy
+  # would skip every `environment:` job. It only DISPATCHES the deploy (below)
+  # on success, so the actual deploy runs on `workflow_dispatch` where those
+  # jobs execute. A red upstream run simply does not dispatch — there is no
+  # green-but-didn't-deploy run at all.
   workflow_run:
     workflows: [<CI_WORKFLOW_NAME>]
     branches: [main]
     types: [completed]
-  # Manual on-demand trigger (UI "Run workflow" + `gh workflow run`).
-  # workflow_dispatch always passes the shared workflow's CI-green guard
-  # (operator-intentional, no upstream conclusion to gate on).
-  workflow_dispatch:
 
+# actions:write lets the built-in GITHUB_TOKEN dispatch deploy-staging-run.yml
+# via the workflow_dispatch API. No PAT needed for a same-repo dispatch —
+# workflow_dispatch always creates a run even from GITHUB_TOKEN.
 permissions:
   contents: read
+  actions: write
 
-# Cancel an in-flight staging deploy when a newer commit lands on main — only
-# the freshest tip of main should reach the staging surfaces. The shared
-# deploy-cloudflare.yml additionally serializes per-environment.
+# Only the freshest tip of main should reach staging: cancel an in-flight
+# DISPATCH when a newer CI run completes. (The deploy itself is serialized
+# separately in deploy-staging-run.yml and per-environment inside the shared
+# deploy-cloudflare.yml.)
 concurrency:
-  group: deploy-staging
+  group: deploy-staging-dispatch
   cancel-in-progress: true
 
 jobs:
-  deploy:
-    name: Staging deploy (shared deploy-cloudflare.yml)
-    uses: dsj1984/mandrel-platform/.github/workflows/deploy-cloudflare.yml@<MANDREL_PLATFORM_SHA> # <MANDREL_PLATFORM_TAG>
-    with:
-      environment: staging
-      gh-environment: staging
-      workers: <WORKERS_CSV>
-      migrate: true
-      # db-engine defaults to 'd1'. Set db-engine + migrate-command +
-      # snapshot-command for a non-D1 engine (e.g. Turso) — see the contract
-      # doc's "command seams" section.
-    # Frozen secret allowlist: only {CLOUDFLARE_*, TURSO_*} cross into the
-    # shared workflow. Map your project's secret NAMES onto these slots.
-    secrets:
-      CLOUDFLARE_API_TOKEN: ${{ secrets.CLOUDFLARE_API_TOKEN }}
-      CLOUDFLARE_ACCOUNT_ID: ${{ secrets.CLOUDFLARE_ACCOUNT_ID }}
+  dispatch:
+    name: Dispatch staging deploy on CI-green
+    runs-on: ubuntu-latest
+    timeout-minutes: 5
+    # CI-green gate: dispatch the deploy ONLY when the upstream CI run
+    # concluded 'success'. `workflow_run` fires on both success and failure, so
+    # this guard is load-bearing — without it a red main would still deploy.
+    if: ${{ github.event.workflow_run.conclusion == 'success' }}
+    steps:
+      - name: Dispatch deploy-staging-run.yml (workflow_dispatch)
+        env:
+          GH_TOKEN: ${{ github.token }}
+          REPO: ${{ github.repository }}
+          SHA: ${{ github.event.workflow_run.head_sha }}
+        shell: bash
+        run: |
+          set -euo pipefail
+          gh workflow run deploy-staging-run.yml \
+            --repo "${REPO}" \
+            --ref main \
+            -f sha="${SHA}"
+          echo "Dispatched staging deploy for ${SHA} (deploy runs on workflow_dispatch so environment: jobs execute)."