mandrel-platform 0.20.1 → 0.24.0

package/scripts/deploy-worker-secrets.test.mjs

@@ -0,0 +1,136 @@
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  parseCsv,
+  parseSecretNames,
+  resolveSecretValue,
+  provisionWorkerSecrets,
+} from "./deploy-worker-secrets.mjs";
+
+// ---------------------------------------------------------------------------
+// Pure helpers
+// ---------------------------------------------------------------------------
+
+test("parseCsv trims entries and drops empties", () => {
+  assert.deepEqual(parseCsv(" api , worker-cron ,, "), ["api", "worker-cron"]);
+  assert.deepEqual(parseCsv(undefined), []);
+});
+
+test("parseSecretNames trims, skips blanks, and skips '#' comment lines", () => {
+  const raw = ["# deploy-critical only", "TURSO_AUTH_TOKEN", "", "  UPSTREAM_API_KEY  ", "   # trailing note"].join("\n");
+  assert.deepEqual(parseSecretNames(raw), ["TURSO_AUTH_TOKEN", "UPSTREAM_API_KEY"]);
+  assert.deepEqual(parseSecretNames(""), []);
+});
+
+test("resolveSecretValue returns the value only for present, non-empty string entries", () => {
+  const ctx = { A: "value", B: "", C: 42 };
+  assert.equal(resolveSecretValue(ctx, "A"), "value");
+  assert.equal(resolveSecretValue(ctx, "B"), null);
+  assert.equal(resolveSecretValue(ctx, "C"), null);
+  assert.equal(resolveSecretValue(ctx, "MISSING"), null);
+  assert.equal(resolveSecretValue(null, "A"), null);
+});
+
+// ---------------------------------------------------------------------------
+// provisionWorkerSecrets — orchestration with an injected wrangler runner
+// ---------------------------------------------------------------------------
+
+function collect() {
+  const lines = [];
+  const calls = [];
+  return {
+    lines,
+    calls,
+    log: (line) => lines.push(line),
+    runWrangler: (args, stdinValue) => {
+      calls.push({ args, stdinValue });
+      return 0;
+    },
+  };
+}
+
+const BASE_ENV = {
+  DEPLOY_ENV: "production",
+  DEPLOYED_WORKERS: "api,worker-cron",
+  WORKER_SECRETS: "TURSO_AUTH_TOKEN",
+  SECRETS_CONTEXT: JSON.stringify({ TURSO_AUTH_TOKEN: "s3cret" }),
+};
+
+test("provisions each name onto each worker via versions secret put, then promotes with versions deploy -y", () => {
+  const { log, runWrangler, calls } = collect();
+  const code = provisionWorkerSecrets(BASE_ENV, { log, runWrangler });
+  assert.equal(code, 0);
+
+  assert.deepEqual(
+    calls.map((c) => c.args.slice(0, 3).join(" ")),
+    [
+      "versions secret put", // api
+      "versions deploy --name", // api promote
+      "versions secret put", // worker-cron
+      "versions deploy --name", // worker-cron promote
+    ]
+  );
+
+  // put: value travels over stdin, never in argv.
+  const put = calls[0];
+  assert.deepEqual(put.args, ["versions", "secret", "put", "TURSO_AUTH_TOKEN", "--name", "api", "--env", "production"]);
+  assert.equal(put.stdinValue, "s3cret");
+
+  // promote: non-interactive -y, message names the Story.
+  const promote = calls[1];
+  assert.ok(promote.args.includes("-y"));
+  assert.ok(promote.args.includes("--message"));
+  assert.equal(promote.stdinValue, undefined);
+});
+
+test("secret values never appear in log output", () => {
+  const { log, runWrangler, lines } = collect();
+  provisionWorkerSecrets(BASE_ENV, { log, runWrangler });
+  assert.ok(lines.every((l) => !l.includes("s3cret")));
+});
+
+test("zero resolved names is a notice + exit 0 (nothing to provision)", () => {
+  const { log, runWrangler, calls, lines } = collect();
+  const code = provisionWorkerSecrets(
+    { ...BASE_ENV, WORKER_SECRETS: "\n# only comments\n\n" },
+    { log, runWrangler }
+  );
+  assert.equal(code, 0);
+  assert.equal(calls.length, 0);
+  assert.ok(lines.some((l) => l.includes("resolved to zero names")));
+});
+
+test("a listed name absent (or empty) in the inherited context is a hard error", () => {
+  const { log, runWrangler, lines } = collect();
+  const code = provisionWorkerSecrets(
+    { ...BASE_ENV, WORKER_SECRETS: "MISSING_SECRET" },
+    { log, runWrangler }
+  );
+  assert.equal(code, 1);
+  assert.ok(lines.some((l) => l.includes("'MISSING_SECRET' is not present (or empty)")));
+});
+
+test("malformed SECRETS_CONTEXT JSON is a hard error", () => {
+  const { log, runWrangler } = collect();
+  const code = provisionWorkerSecrets({ ...BASE_ENV, SECRETS_CONTEXT: "{not json" }, { log, runWrangler });
+  assert.equal(code, 1);
+});
+
+test("a failing wrangler versions secret put aborts with exit 1", () => {
+  const { log } = collect();
+  const code = provisionWorkerSecrets(BASE_ENV, {
+    log,
+    runWrangler: (args) => (args[1] === "secret" ? 1 : 0),
+  });
+  assert.equal(code, 1);
+});
+
+test("a failing wrangler versions deploy aborts with exit 1", () => {
+  const { log } = collect();
+  const code = provisionWorkerSecrets(BASE_ENV, {
+    log,
+    runWrangler: (args) => (args[0] === "versions" && args[1] === "deploy" ? 1 : 0),
+  });
+  assert.equal(code, 1);
+});

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/README.md

@@ -54,3 +54,16 @@ node node_modules/mandrel-platform/scripts/platform-sync.mjs --ref mandrel-platf
 
 > Placeholder convention: `<UPPER_SNAKE>` between angle brackets. Search for
 > `<` after copying to find everything that still needs a value.
+
+## Self-contained runbooks (not stubs)
+
+One template in this directory is a **full runbook**, not a thin stub — it
+has no canonical `docs/runbooks/` counterpart to link and carries the entire
+process inline (placeholders included):
+
+| Runbook | Scope |
+|---------|-------|
+| `runner-provisioning.md` | provision a persistent self-hosted runner with the [`templates/runner/`](../runner/) hygiene kit (job-start cleanup hook + runner-scoped `.env`) |
+
+Adopt it the same way as a stub (copy into `docs/runbooks/`, fill the
+placeholders); `platform-sync.mjs` materializes it alongside the stubs.

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/runbooks/runner-provisioning.md

@@ -0,0 +1,187 @@
+# Self-Hosted Runner Provisioning — <PROJECT_NAME>
+
+> **Self-contained runbook** (not a thin stub). Unlike the other templates in
+> this directory, there is no canonical `docs/runbooks/` counterpart to link —
+> this file IS the process. It provisions a **persistent** (non-ephemeral)
+> GitHub Actions runner on a macOS host using the mandrel-platform runner kit
+> (`templates/runner/`), which ships the job-start hygiene hook
+> (`job-cleanup.sh`) and the per-runner `.env` (`.env.example`).
+>
+> Placeholder convention: `<UPPER_SNAKE>` between angle brackets — search for
+> `<` after copying to find everything that still needs a value.
+
+---
+
+## ⚠️ Read first: the shared-`$HOME` concurrency hazard
+
+Every runner on a host typically runs as the **same OS user**, so anything
+resolved against `$HOME` is **shared across all co-resident runners** — it is
+*not* scoped to "this runner", no matter what a comment claims. The two
+hazards this kit exists to close:
+
+1. **`~/setup-pnpm` is shared.** `pnpm/action-setup`'s `dest` input defaults
+   to `~/setup-pnpm`. With N runners on one host, N concurrent jobs race on
+   one pnpm shim install. Worse, a cleanup hook that `pkill`s processes
+   matching `~/setup-pnpm` or `rm -rf`s it at job start will **destroy a pnpm
+   install a concurrent runner is mid-flight on**. The fix is ordering:
+   **first** make the pnpm shim location per-runner (workflow-side, see
+   [pnpm scoping](#3-pnpm-scoping-workflow-side-prerequisite) below), and only
+   **then** is a reap/delete hook safe — and even then it must target only the
+   runner-scoped path. The kit's `job-cleanup.sh` never touches
+   `~/setup-pnpm`.
+2. **The default tool cache is shared.** Without a runner-scoped
+   `RUNNER_TOOL_CACHE`, toolchain actions extract into a host-shared cache
+   and co-resident runners race on it. The kit's `.env` scopes it to the
+   runner's own `_work/_tool`.
+
+Do not roll the hook out to a host until every workflow that job's runner
+serves installs pnpm to a runner-scoped `dest`. Rolling out the hook without
+the pnpm-scoping prerequisite reintroduces the exact corruption it guards
+against.
+
+## Host Values
+
+| Value | Setting |
+|-------|---------|
+| Runner host | `<RUNNER_HOST>` |
+| Runner OS user | `<RUNNER_USER>` |
+| Runner root dir | `<RUNNER_DIR>` (e.g. `~/Development/github-runners/<REPO>`) |
+| Repository | `<OWNER>/<REPO>` |
+| Runner name | `<REPO>-runner` (or `<REPO>-runner-<N>` for a pool) |
+| Labels | `self-hosted, macOS, ARM64, <REPO>-runner` |
+| Runner version | `<RUNNER_VERSION>` (latest from [actions/runner releases](https://github.com/actions/runner/releases)) |
+
+## 1. Download and unpack the runner
+
+One directory per runner — never share a runner root between registrations.
+
+```bash
+mkdir -p <RUNNER_DIR> && cd <RUNNER_DIR>
+curl -o actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz -L \
+  https://github.com/actions/runner/releases/download/v<RUNNER_VERSION>/actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz
+# Verify the SHA-256 against the checksum published on the release page
+# before unpacking — same download-and-verify posture as the platform's
+# pinned gitleaks/actionlint installs.
+shasum -a 256 actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz
+tar xzf actions-runner-osx-arm64-<RUNNER_VERSION>.tar.gz
+```
+
+## 2. Register with `config.sh` (repo-level)
+
+Registration is **repo-level** (the fleet's standing model), not org-level.
+Mint a short-lived registration token via the repo UI
+(*Settings → Actions → Runners → New self-hosted runner*) or:
+
+```bash
+gh api -X POST repos/<OWNER>/<REPO>/actions/runners/registration-token --jq .token
+```
+
+Then configure:
+
+```bash
+cd <RUNNER_DIR>
+./config.sh \
+  --url https://github.com/<OWNER>/<REPO> \
+  --token <REGISTRATION_TOKEN> \
+  --name <REPO>-runner \
+  --labels self-hosted,macOS,ARM64,<REPO>-runner \
+  --work _work \
+  --unattended
+```
+
+- `--labels` — the four-label contract the fleet's workflows target
+  (`self-hosted, macOS, ARM64, <REPO>-runner`). The `<REPO>-runner` label is
+  the routing key; keep it unique per repo.
+- `--work _work` — keeps the work tree inside `<RUNNER_DIR>`, which is what
+  makes every path in the hygiene kit runner-scoped.
+- Registration tokens expire after ~1 hour; mint a fresh one per runner.
+
+## 3. pnpm scoping (workflow-side prerequisite)
+
+Before installing the hook, confirm every workflow this runner serves
+installs the pnpm shim to a **runner-scoped** destination:
+
+- Workflows using the platform's `setup-toolchain` composite action (all
+  `pr-quality.yml` tiers) are already safe: it defaults `pnpm/action-setup`'s
+  `dest` to `${{ runner.temp }}/pnpm`, i.e. `<RUNNER_DIR>/_work/_temp/pnpm`,
+  unique per runner. `pr-quality.yml` also exposes a `pnpm-dest` input for
+  explicit overrides.
+- Workflows calling `pnpm/action-setup` directly MUST pass
+  `dest: ${{ runner.temp }}/pnpm`. The action's default (`~/setup-pnpm`) is
+  host-shared and unsafe under runner concurrency (see the hazard header).
+
+There is **no runner-side override** for the pnpm `dest` — it is a workflow
+input — which is why this step is a rollout gate, not an `.env` line.
+
+## 4. Install the hygiene kit (hook + `.env`)
+
+Copy the kit from the platform payload into the runner root:
+
+```bash
+cp node_modules/mandrel-platform/templates/runner/job-cleanup.sh <RUNNER_DIR>/job-cleanup.sh
+chmod +x <RUNNER_DIR>/job-cleanup.sh
+cp node_modules/mandrel-platform/templates/runner/.env.example <RUNNER_DIR>/.env
+```
+
+Then edit `<RUNNER_DIR>/.env` and replace every `<RUNNER_DIR>` placeholder
+with the runner root's absolute path. The resulting file wires:
+
+- `ACTIONS_RUNNER_HOOK_JOB_STARTED=<RUNNER_DIR>/job-cleanup.sh` — the
+  job-start hook. It reaps orphaned pnpm/node processes parented to **this**
+  runner's work tree, clears stale runner-scoped pnpm installs, and
+  age-gate-sweeps shared-`$TMPDIR` gitleaks leftovers. It never fails a job
+  (always exits 0) and never touches another runner's state.
+- `RUNNER_TOOL_CACHE=<RUNNER_DIR>/_work/_tool` and
+  `AGENT_TOOLSDIRECTORY=<RUNNER_DIR>/_work/_tool` — runner-scoped tool cache
+  (two env names, one dir; some actions read the legacy name).
+- `LANG=en_US.UTF-8`.
+
+The hook needs no per-runner editing: it derives `RUNNER_DIR` from its own
+location, so the same file works verbatim on every runner.
+
+## 5. Install as a launchd service (`svc.sh`)
+
+```bash
+cd <RUNNER_DIR>
+./svc.sh install   # generates the launchd plist for the current user
+./svc.sh start
+./svc.sh status    # expect: Started · running
+```
+
+Verify end-to-end: push a trivial workflow run targeting
+`runs-on: [self-hosted, macOS, ARM64, <REPO>-runner]` and confirm (a) the job
+is picked up and (b) the job log shows the `Set up runner` hook phase running
+`job-cleanup.sh` before the first step.
+
+The runner loads `.env` at service start — after any `.env` change, restart:
+
+```bash
+./svc.sh stop && ./svc.sh start
+```
+
+## 6. Update / rotation guidance
+
+- **Runner version updates.** Persistent runners self-update by default when
+  GitHub releases a new runner version; no action needed. If a runner is
+  pinned or the self-update wedges, stop the service, download/unpack the new
+  tarball over `<RUNNER_DIR>` (config and `.env` survive), and restart via
+  `svc.sh`.
+- **Kit updates.** The hook and `.env.example` are versioned in
+  mandrel-platform. On a platform release that touches `templates/runner/`,
+  re-copy `job-cleanup.sh` (verbatim — it is parameterized) and diff
+  `.env.example` against the live `.env`, then `./svc.sh stop && ./svc.sh
+  start`. There is no `mandrel sync` equivalent for a runner host's
+  filesystem — this is an operator-applied step.
+- **Token/registration rotation.** Registration tokens are one-shot at
+  config time; nothing persists to rotate. To move a runner between repos or
+  rename it: `./svc.sh stop && ./svc.sh uninstall && ./config.sh remove
+  --token <REMOVAL_TOKEN>`, then re-register (§2) and reinstall the service
+  (§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*.
+
+## Project-Specific Notes
+
+<!-- Record host quirks: co-resident runner inventory for this host, Xcode /
+     toolchain versions the workloads assume, monitoring hooks, etc. -->

package/templates/runner/.env.example

@@ -0,0 +1,45 @@
+# .env — per-runner environment for a PERSISTENT self-hosted runner
+# (mandrel-platform runner kit).
+#
+# Copy this file to `<RUNNER_DIR>/.env` (the runner root, next to config.sh)
+# and replace every `<RUNNER_DIR>` placeholder with the runner's ABSOLUTE
+# root path (e.g. /Users/ci/Development/github-runners/myrepo). The runner
+# loads this file at service start and injects the variables into every job.
+#
+# Placeholder convention: `<UPPER_SNAKE>` between angle brackets — search for
+# `<` after copying to find everything that still needs a value.
+#
+# See templates/runbooks/runner-provisioning.md for the full provisioning
+# procedure, including WHY every value here must be runner-scoped (multiple
+# runners on one host share an OS user, so anything resolved against $HOME is
+# a cross-runner concurrency hazard).
+
+# Locale — pnpm/git/node emit UTF-8; a C locale garbles their output.
+LANG=en_US.UTF-8
+
+# Job-start hygiene hook. Runs templates/runner/job-cleanup.sh (installed
+# into the runner root) before every job: reaps orphaned pnpm/node processes
+# from THIS runner's work tree and clears stale install/temp artifacts.
+# The hook is runner-scoped and never fails the job (always exits 0).
+ACTIONS_RUNNER_HOOK_JOB_STARTED=<RUNNER_DIR>/job-cleanup.sh
+
+# Runner-scoped tool cache. Without this, actions/setup-node & friends
+# default the tool cache to a host-shared location and co-resident runners
+# race on extraction. `_work/_tool` is inside this runner's own work tree,
+# so each runner gets an isolated cache.
+RUNNER_TOOL_CACHE=<RUNNER_DIR>/_work/_tool
+
+# Same value, second consumer: some toolchain actions read
+# AGENT_TOOLSDIRECTORY (the Azure Pipelines-era name) instead of
+# RUNNER_TOOL_CACHE. Keep both pointing at the same runner-scoped dir.
+AGENT_TOOLSDIRECTORY=<RUNNER_DIR>/_work/_tool
+
+# ── pnpm scoping (read this before enabling the hook) ──────────────────────
+# The pnpm shim install location is a WORKFLOW-side setting, not a runner-side
+# one: pnpm/action-setup's `dest` input defaults to `~/setup-pnpm`, which is
+# SHARED across every runner on the host. The platform's setup-toolchain
+# composite action already re-defaults `dest` to `${{ runner.temp }}/pnpm`
+# (runner-scoped); workflows that call pnpm/action-setup directly MUST pass
+# `dest: ${{ runner.temp }}/pnpm` (or the pr-quality.yml `pnpm-dest` input).
+# The job-cleanup.sh hook only reaps the runner-scoped locations — it
+# deliberately never touches `~/setup-pnpm`.