mandrel-platform 1.4.1 → 1.5.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.4.1",
+  "version": "1.5.0",
   "description": "Shared CI/deploy workflows, composite toolchain action, npm config package, Renovate preset, and operator runbook templates.",
   "license": "MIT",
   "repository": {
@@ -44,7 +44,7 @@
     "provenance": true
   },
   "dependencies": {
-    "mandrel": "^2.31.0"
+    "mandrel": "^2.35.0"
   },
   "scripts": {
     "typecheck": "node --input-type=module --eval 'process.exit(0)'",

package/scripts/apply-uptime-monitors.mjs

@@ -43,9 +43,12 @@
  *   • --token        Better Stack API token. Defaults to
  *                     $BETTERSTACK_API_TOKEN. Missing token → skip-with-
  *                     notice, exit 0.
- *   • --alert-email  Default alert-contact email applied to any monitor
- *                     entry that does not set its own `alertEmail`. Defaults
- *                     to $UPTIME_ALERT_EMAIL.
+ *   • --alert-email  DEPRECATED and ignored (defaults to $UPTIME_ALERT_EMAIL).
+ *                     Better Stack's monitor `email` field is a boolean
+ *                     ("Send e-mail alerts."), not a recipient — recipients
+ *                     resolve from the team roster and the escalation policy.
+ *                     Accepted only so an existing caller does not break; use
+ *                     a monitor entry's `policyId` to control who is alerted.
  *
  * Exit codes:
  *   0 — plan computed / applied successfully, OR skip-with-notice (no token).
@@ -58,6 +61,8 @@
 import { readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
+import { isDirectInvocation } from './lib/entry-guard.mjs';
+
 // ---------------------------------------------------------------------------
 // Monitor config schema (pure validation — no I/O)
 // ---------------------------------------------------------------------------
@@ -71,12 +76,24 @@ import { resolve } from "node:path";
  *   {
  *     "url": "https://api.example.com/health",   // required, http(s) URL
  *     "name": "api",                              // optional, defaults to url's host
- *     "alertEmail": "oncall@example.com",         // optional, falls back to --alert-email
+ *     "emailAlerts": true,                        // optional, boolean, default true
+ *     "policyId": "12345",                        // optional, Better Stack escalation policy
  *     "checkFrequency": 30                        // optional, seconds, default 30
  *   }
  *
+ * `emailAlerts` maps to Better Stack's `email` field, which the Monitors API
+ * types as a **boolean** ("Send e-mail alerts.") — it is a switch, not a
+ * recipient. Recipients resolve from the Better Stack team roster and the
+ * escalation policy named by `policyId` (`policy_id`), never from a
+ * per-monitor address. The retired `alertEmail` field is still accepted and
+ * type-checked so an existing config keeps parsing, but it is inert: it is
+ * reported in `deprecations[]` and never reaches the API payload.
+ *
  * @param {unknown} raw  Parsed JSON.
- * @returns {{ monitors: Array<{url:string, name:string, alertEmail:string|null, checkFrequency:number}> }}
+ * @returns {{
+ *   monitors: Array<{url:string, name:string, emailAlerts:boolean, policyId:string|null, checkFrequency:number}>,
+ *   deprecations: string[]
+ * }}
  * @throws {Error} with a message naming the offending index/field on invalid input.
  */
 export function parseMonitorConfig(raw) {
@@ -86,9 +103,18 @@ export function parseMonitorConfig(raw) {
       "monitor config must be a JSON array of monitor entries, or an object with a `monitors` array."
     );
   }
-  return {
-    monitors: list.map((entry, i) => validateMonitorEntry(entry, i)),
-  };
+  const deprecations = [];
+  const monitors = list.map((entry, i) => {
+    if (entry && typeof entry === "object" && entry.alertEmail !== undefined) {
+      deprecations.push(
+        `monitor config entry [${i}] sets "alertEmail" — that field is ignored. ` +
+          `Better Stack types the monitor's \`email\` field as a boolean (an on/off switch), not a recipient. ` +
+          `Use "emailAlerts" to toggle e-mail alerts and "policyId" to choose the escalation policy that decides who is alerted.`
+      );
+    }
+    return validateMonitorEntry(entry, i);
+  });
+  return { monitors, deprecations };
 }
 
 function validateMonitorEntry(entry, index) {
@@ -110,13 +136,20 @@ function validateMonitorEntry(entry, index) {
   if (entry.alertEmail !== undefined && typeof entry.alertEmail !== "string") {
     throw new Error(`monitor config entry [${index}] "alertEmail" must be a string when present.`);
   }
+  if (entry.emailAlerts !== undefined && typeof entry.emailAlerts !== "boolean") {
+    throw new Error(`monitor config entry [${index}] "emailAlerts" must be a boolean when present.`);
+  }
+  if (entry.policyId !== undefined && typeof entry.policyId !== "string") {
+    throw new Error(`monitor config entry [${index}] "policyId" must be a string when present.`);
+  }
   if (entry.checkFrequency !== undefined && !(Number.isInteger(entry.checkFrequency) && entry.checkFrequency > 0)) {
     throw new Error(`monitor config entry [${index}] "checkFrequency" must be a positive integer (seconds) when present.`);
   }
   return {
     url: entry.url,
     name: entry.name ?? host,
-    alertEmail: entry.alertEmail ?? null,
+    emailAlerts: entry.emailAlerts ?? true,
+    policyId: entry.policyId ?? null,
     checkFrequency: entry.checkFrequency ?? DEFAULT_CHECK_FREQUENCY_SECONDS,
   };
 }
@@ -163,7 +196,13 @@ function normalizeUrl(url) {
 function monitorNeedsUpdate(live, desired) {
   if (live.name !== undefined && live.name !== desired.name) return true;
   if (live.checkFrequency !== undefined && live.checkFrequency !== desired.checkFrequency) return true;
-  if (live.alertEmail !== undefined && desired.alertEmail !== null && live.alertEmail !== desired.alertEmail) return true;
+  // Both sides are booleans: the live read-back maps Better Stack's boolean
+  // `email` attribute, and `emailAlerts` normalizes to a boolean at parse.
+  // Comparing a boolean against a configured address (the pre-#403 shape)
+  // read as drift on every beat and issued a redundant PATCH per monitor
+  // per apply.
+  if (live.emailAlerts !== undefined && live.emailAlerts !== desired.emailAlerts) return true;
+  if (live.policyId !== undefined && desired.policyId !== null && live.policyId !== desired.policyId) return true;
   return false;
 }
 
@@ -209,7 +248,8 @@ export function createBetterStackClient({ token, fetchImpl = fetch, apiBase = BE
         url: m.attributes?.url ?? "",
         name: m.attributes?.pronounceable_name,
         checkFrequency: m.attributes?.check_frequency,
-        alertEmail: m.attributes?.email,
+        emailAlerts: m.attributes?.email,
+        policyId: m.attributes?.policy_id,
       }));
     },
     async createMonitor(entry) {
@@ -231,7 +271,11 @@ function toBetterStackPayload(entry) {
     url: entry.url,
     pronounceable_name: entry.name,
     check_frequency: entry.checkFrequency,
-    ...(entry.alertEmail ? { email: entry.alertEmail } : {}),
+    // `email` is a boolean in Better Stack's Monitors API ("Send e-mail
+    // alerts.") — always send the switch, never an address. `policy_id` is
+    // the field that actually determines who is alerted.
+    email: entry.emailAlerts,
+    ...(entry.policyId ? { policy_id: entry.policyId } : {}),
   };
 }
 
@@ -245,14 +289,10 @@ function toBetterStackPayload(entry) {
  * @param {{monitors: Array}} opts.config
  * @param {ReturnType<typeof createBetterStackClient>} opts.client
  * @param {boolean} opts.dryRun
- * @param {string|null} [opts.defaultAlertEmail]
  * @returns {Promise<{created: string[], updated: string[], unchanged: string[], dryRun: boolean}>}
  */
-export async function applyMonitorConfig({ config, client, dryRun, defaultAlertEmail = null }) {
-  const desired = config.monitors.map((m) => ({
-    ...m,
-    alertEmail: m.alertEmail ?? defaultAlertEmail,
-  }));
+export async function applyMonitorConfig({ config, client, dryRun }) {
+  const desired = config.monitors;
   const live = await client.listMonitors();
   const { toCreate, toUpdate, unchanged } = diffMonitors(desired, live);
 
@@ -322,10 +362,33 @@ async function main() {
     process.exit(1);
   }
 
+  // Announced before the token check on purpose: "secret provisioned, token
+  // absent" is exactly the state that produced a permanently-green apply a
+  // consumer believed was routing alerts, so that run is the one that most
+  // needs to hear the address is inert (refs #403).
+  if (opts.alertEmail) {
+    process.stdout.write(
+      "::warning title=UPTIME_ALERT_EMAIL is ignored::Better Stack resolves alert recipients from the team roster " +
+        "and escalation policy, not from a per-monitor address. Set a monitor's `policyId` instead, and drop this secret from your caller.\n"
+    );
+    process.stderr.write(
+      "[apply-uptime-monitors] DEPRECATED: --alert-email / $UPTIME_ALERT_EMAIL is ignored — Better Stack's monitor " +
+        "`email` field is a boolean switch, not a recipient. Use a monitor entry's `policyId` (escalation policy) to " +
+        "control who is alerted, and `emailAlerts` to toggle e-mail alerts.\n"
+    );
+  }
+
   // Graceful degradation: no token → skip-with-notice, exit 0. Preserves the
   // pre-existing per-consumer behaviour when Better Stack secrets are not
   // yet provisioned (acceptance criterion — see docs/reusable-workflows.md).
   if (!opts.token) {
+    // Annotation-level, not stdout-only: a consumer can otherwise sit on a
+    // permanently-green `uptime-apply` for weeks with zero live monitors and
+    // never notice the apply is inert (refs #403).
+    process.stdout.write(
+      "::warning title=Uptime monitors not applied::BETTERSTACK_API_TOKEN is not provisioned — " +
+        "this uptime-apply run created and updated nothing. Provision the secret to activate uptime monitoring.\n"
+    );
     process.stdout.write(
       "⏭️  apply-uptime-monitors: BETTERSTACK_API_TOKEN not provided — skipping uptime-monitor apply (Better Stack not provisioned for this consumer yet).\n"
     );
@@ -341,6 +404,10 @@ async function main() {
     process.exit(1);
   }
 
+  for (const notice of config.deprecations) {
+    process.stderr.write(`[apply-uptime-monitors] DEPRECATED: ${notice}\n`);
+  }
+
   // Test-only escape hatch: point the CLI at a local/offline server instead
   // of the live Better Stack API. Never set in a production caller — see
   // createBetterStackClient's apiBase docblock.
@@ -355,7 +422,6 @@ async function main() {
       config,
       client,
       dryRun: opts.dryRun,
-      defaultAlertEmail: opts.alertEmail,
     });
     const verb = result.dryRun ? "would create" : "created";
     const verbUpdate = result.dryRun ? "would update" : "updated";
@@ -372,7 +438,9 @@ async function main() {
   }
 }
 
-// Only run the CLI when invoked directly, not when imported by the self-test.
-if (import.meta.url === `file://${process.argv[1]}`) {
+// Direct-invocation guard — symlink-safe via the shared seam (Story #407):
+// comparing an unresolved argv[1] against a realpath-resolved
+// import.meta.url silently never matches under pnpm's symlinked node_modules.
+if (isDirectInvocation(import.meta.url)) {
   main();
 }

package/scripts/apply-uptime-monitors.test.mjs

@@ -42,16 +42,19 @@ test("parseMonitorConfig accepts a bare array of monitor entries", () => {
   assert.equal(monitors.length, 1);
   assert.equal(monitors[0].url, "https://api.example.com/health");
   assert.equal(monitors[0].name, "api.example.com");
-  assert.equal(monitors[0].alertEmail, null);
+  assert.equal(monitors[0].emailAlerts, true, "e-mail alerts default to on");
+  assert.equal(monitors[0].policyId, null);
   assert.equal(monitors[0].checkFrequency, DEFAULT_CHECK_FREQUENCY_SECONDS);
 });
 
 test("parseMonitorConfig accepts a wrapped { monitors: [...] } object", () => {
   const { monitors } = parseMonitorConfig({
-    monitors: [{ url: "https://x.example.com", name: "x", alertEmail: "a@b.com", checkFrequency: 60 }],
+    monitors: [
+      { url: "https://x.example.com", name: "x", emailAlerts: false, policyId: "pol-1", checkFrequency: 60 },
+    ],
   });
   assert.deepEqual(monitors, [
-    { url: "https://x.example.com", name: "x", alertEmail: "a@b.com", checkFrequency: 60 },
+    { url: "https://x.example.com", name: "x", emailAlerts: false, policyId: "pol-1", checkFrequency: 60 },
   ]);
 });
 
@@ -83,12 +86,42 @@ test("parseMonitorConfig rejects non-string name/alertEmail", () => {
   );
 });
 
+test("parseMonitorConfig rejects a non-boolean emailAlerts, naming the index", () => {
+  assert.throws(
+    () => parseMonitorConfig([{ url: "https://a.example.com" }, { url: "https://x.example.com", emailAlerts: "yes" }]),
+    /entry \[1\] "emailAlerts" must be a boolean/
+  );
+});
+
+test("parseMonitorConfig rejects a non-string policyId, naming the index", () => {
+  assert.throws(
+    () => parseMonitorConfig([{ url: "https://a.example.com" }, { url: "https://x.example.com", policyId: 12345 }]),
+    /entry \[1\] "policyId" must be a string/
+  );
+});
+
+test("parseMonitorConfig reports a retired alertEmail as a deprecation and drops it", () => {
+  const { monitors, deprecations } = parseMonitorConfig([
+    { url: "https://x.example.com", alertEmail: "oncall@example.com" },
+  ]);
+  assert.equal(deprecations.length, 1);
+  assert.match(deprecations[0], /entry \[0\] sets "alertEmail" — that field is ignored/);
+  assert.match(deprecations[0], /policyId/);
+  assert.equal(monitors[0].alertEmail, undefined, "the retired field never reaches the normalized entry");
+  assert.equal(monitors[0].emailAlerts, true);
+});
+
+test("parseMonitorConfig reports no deprecations for a clean config", () => {
+  const { deprecations } = parseMonitorConfig([{ url: "https://x.example.com", emailAlerts: false }]);
+  assert.deepEqual(deprecations, []);
+});
+
 // ---------------------------------------------------------------------------
 // diffMonitors
 // ---------------------------------------------------------------------------
 
 test("diffMonitors classifies a brand-new url as toCreate", () => {
-  const desired = [{ url: "https://new.example.com", name: "new", alertEmail: null, checkFrequency: 30 }];
+  const desired = [{ url: "https://new.example.com", name: "new", emailAlerts: true, policyId: null, checkFrequency: 30 }];
   const { toCreate, toUpdate, unchanged } = diffMonitors(desired, []);
   assert.equal(toCreate.length, 1);
   assert.equal(toUpdate.length, 0);
@@ -96,7 +129,7 @@ test("diffMonitors classifies a brand-new url as toCreate", () => {
 });
 
 test("diffMonitors classifies a matching, identical url as unchanged", () => {
-  const desired = [{ url: "https://x.example.com", name: "x", alertEmail: null, checkFrequency: 30 }];
+  const desired = [{ url: "https://x.example.com", name: "x", emailAlerts: true, policyId: null, checkFrequency: 30 }];
   const live = [{ id: "1", url: "https://x.example.com", name: "x", checkFrequency: 30 }];
   const { toCreate, toUpdate, unchanged } = diffMonitors(desired, live);
   assert.equal(toCreate.length, 0);
@@ -105,7 +138,7 @@ test("diffMonitors classifies a matching, identical url as unchanged", () => {
 });
 
 test("diffMonitors classifies a url with a drifted name/frequency as toUpdate", () => {
-  const desired = [{ url: "https://x.example.com", name: "renamed", alertEmail: null, checkFrequency: 60 }];
+  const desired = [{ url: "https://x.example.com", name: "renamed", emailAlerts: true, policyId: null, checkFrequency: 60 }];
   const live = [{ id: "1", url: "https://x.example.com", name: "x", checkFrequency: 30 }];
   const { toUpdate } = diffMonitors(desired, live);
   assert.equal(toUpdate.length, 1);
@@ -113,7 +146,7 @@ test("diffMonitors classifies a url with a drifted name/frequency as toUpdate",
 });
 
 test("diffMonitors url matching is trailing-slash and case insensitive", () => {
-  const desired = [{ url: "https://X.example.com/", name: "x", alertEmail: null, checkFrequency: 30 }];
+  const desired = [{ url: "https://X.example.com/", name: "x", emailAlerts: true, policyId: null, checkFrequency: 30 }];
   const live = [{ id: "1", url: "https://x.example.com", name: "x", checkFrequency: 30 }];
   const { toCreate, unchanged } = diffMonitors(desired, live);
   assert.equal(toCreate.length, 0);
@@ -121,7 +154,7 @@ test("diffMonitors url matching is trailing-slash and case insensitive", () => {
 });
 
 test("diffMonitors never proposes deleting a live monitor absent from desired (additive apply only)", () => {
-  const desired = [{ url: "https://kept.example.com", name: "kept", alertEmail: null, checkFrequency: 30 }];
+  const desired = [{ url: "https://kept.example.com", name: "kept", emailAlerts: true, policyId: null, checkFrequency: 30 }];
   const live = [
     { id: "1", url: "https://kept.example.com", name: "kept", checkFrequency: 30 },
     { id: "2", url: "https://hand-added.example.com", name: "manual" },
@@ -162,7 +195,16 @@ test("createBetterStackClient.listMonitors normalizes the Better Stack payload s
         data: [
           {
             id: "42",
-            attributes: { url: "https://a.example.com", pronounceable_name: "a", check_frequency: 30, email: "a@b.com" },
+            // `email` is a boolean in Better Stack's API — a switch, not a
+            // recipient. Fixturing it as an address is what let the
+            // string-typed payload bug survive a green suite (refs #403).
+            attributes: {
+              url: "https://a.example.com",
+              pronounceable_name: "a",
+              check_frequency: 30,
+              email: true,
+              policy_id: "pol-1",
+            },
           },
         ],
       },
@@ -171,7 +213,7 @@ test("createBetterStackClient.listMonitors normalizes the Better Stack payload s
   const client = createBetterStackClient({ token: "tok", fetchImpl });
   const monitors = await client.listMonitors();
   assert.deepEqual(monitors, [
-    { id: "42", url: "https://a.example.com", name: "a", checkFrequency: 30, alertEmail: "a@b.com" },
+    { id: "42", url: "https://a.example.com", name: "a", checkFrequency: 30, emailAlerts: true, policyId: "pol-1" },
   ]);
   assert.equal(calls[0].url, "https://uptime.betterstack.com/api/v2/monitors");
 });
@@ -209,7 +251,7 @@ function fakeClient({ live = [] } = {}) {
 test("applyMonitorConfig dry-run computes the plan without calling create/update", async () => {
   const client = fakeClient({ live: [] });
   const result = await applyMonitorConfig({
-    config: { monitors: [{ url: "https://x.example.com", name: "x", alertEmail: null, checkFrequency: 30 }] },
+    config: { monitors: [{ url: "https://x.example.com", name: "x", emailAlerts: true, policyId: null, checkFrequency: 30 }] },
     client,
     dryRun: true,
   });
@@ -221,7 +263,7 @@ test("applyMonitorConfig dry-run computes the plan without calling create/update
 test("applyMonitorConfig --apply issues create for new monitors", async () => {
   const client = fakeClient({ live: [] });
   const result = await applyMonitorConfig({
-    config: { monitors: [{ url: "https://x.example.com", name: "x", alertEmail: null, checkFrequency: 30 }] },
+    config: { monitors: [{ url: "https://x.example.com", name: "x", emailAlerts: true, policyId: null, checkFrequency: 30 }] },
     client,
     dryRun: false,
   });
@@ -229,21 +271,112 @@ test("applyMonitorConfig --apply issues create for new monitors", async () => {
   assert.equal(client.created.length, 1);
 });
 
-test("applyMonitorConfig falls back to defaultAlertEmail when an entry sets none", async () => {
-  const client = fakeClient({ live: [] });
-  await applyMonitorConfig({
-    config: { monitors: [{ url: "https://x.example.com", name: "x", alertEmail: null, checkFrequency: 30 }] },
+test("a created monitor sends Better Stack's `email` as a boolean, never an address", async () => {
+  const { fetchImpl, calls } = fakeFetch({
+    "POST https://uptime.betterstack.com/api/v2/monitors": { status: 201, body: { data: { id: "9" } } },
+  });
+  const client = createBetterStackClient({ token: "tok", fetchImpl });
+  await client.createMonitor({
+    url: "https://x.example.com",
+    name: "x",
+    emailAlerts: true,
+    policyId: null,
+    checkFrequency: 30,
+  });
+  const body = JSON.parse(calls[0].body);
+  assert.equal(typeof body.email, "boolean", "`email` is a boolean switch in Better Stack's API");
+  assert.equal(body.email, true);
+  assert.ok(!("policy_id" in body), "no escalation policy is sent when the entry names none");
+});
+
+test("emailAlerts:false switches e-mail alerts off rather than omitting the field", async () => {
+  const { fetchImpl, calls } = fakeFetch({
+    "POST https://uptime.betterstack.com/api/v2/monitors": { status: 201, body: { data: { id: "9" } } },
+  });
+  const client = createBetterStackClient({ token: "tok", fetchImpl });
+  await client.createMonitor({
+    url: "https://x.example.com",
+    name: "x",
+    emailAlerts: false,
+    policyId: null,
+    checkFrequency: 30,
+  });
+  assert.equal(JSON.parse(calls[0].body).email, false);
+});
+
+test("policyId maps to Better Stack's policy_id — the field that decides who is alerted", async () => {
+  const { fetchImpl, calls } = fakeFetch({
+    "POST https://uptime.betterstack.com/api/v2/monitors": { status: 201, body: { data: { id: "9" } } },
+  });
+  const client = createBetterStackClient({ token: "tok", fetchImpl });
+  await client.createMonitor({
+    url: "https://x.example.com",
+    name: "x",
+    emailAlerts: true,
+    policyId: "pol-7",
+    checkFrequency: 30,
+  });
+  const body = JSON.parse(calls[0].body);
+  assert.equal(body.policy_id, "pol-7");
+  assert.equal(typeof body.email, "boolean");
+});
+
+test("no payload ever carries an address in `email`, even from a legacy alertEmail config", async () => {
+  const { fetchImpl, calls } = fakeFetch({
+    "POST https://uptime.betterstack.com/api/v2/monitors": { status: 201, body: { data: { id: "9" } } },
+  });
+  const config = parseMonitorConfig([{ url: "https://x.example.com", alertEmail: "oncall@example.com" }]);
+  const client = createBetterStackClient({ token: "tok", fetchImpl });
+  await applyMonitorConfig({ config, client: { ...client, listMonitors: async () => [] }, dryRun: false });
+  const body = JSON.parse(calls[0].body);
+  assert.equal(typeof body.email, "boolean");
+  assert.ok(
+    !JSON.stringify(body).includes("oncall@example.com"),
+    "the retired address never reaches the Better Stack payload"
+  );
+});
+
+test("a converged monitor reports unchanged and issues no update (no per-run PATCH churn)", async () => {
+  // Live read-back carries the boolean `email`; desired carries the boolean
+  // `emailAlerts`. Pre-#403 these were a boolean vs an address, so every
+  // monitor read as drifted on every apply.
+  const client = fakeClient({
+    live: [
+      { id: "1", url: "https://x.example.com", name: "x", checkFrequency: 30, emailAlerts: true, policyId: "pol-1" },
+    ],
+  });
+  const result = await applyMonitorConfig({
+    config: {
+      monitors: [
+        { url: "https://x.example.com", name: "x", emailAlerts: true, policyId: "pol-1", checkFrequency: 30 },
+      ],
+    },
+    client,
+    dryRun: false,
+  });
+  assert.deepEqual(result.unchanged, ["https://x.example.com"]);
+  assert.equal(result.updated.length, 0);
+  assert.equal(client.updated.length, 0, "a converged config issues zero update calls");
+});
+
+test("a drifted emailAlerts switch is still detected as an update", async () => {
+  const client = fakeClient({
+    live: [{ id: "1", url: "https://x.example.com", name: "x", checkFrequency: 30, emailAlerts: false }],
+  });
+  const result = await applyMonitorConfig({
+    config: {
+      monitors: [{ url: "https://x.example.com", name: "x", emailAlerts: true, policyId: null, checkFrequency: 30 }],
+    },
     client,
     dryRun: false,
-    defaultAlertEmail: "oncall@example.com",
   });
-  assert.equal(client.created[0].alertEmail, "oncall@example.com");
+  assert.deepEqual(result.updated, ["https://x.example.com"]);
 });
 
 test("applyMonitorConfig issues update for a drifted existing monitor", async () => {
   const client = fakeClient({ live: [{ id: "1", url: "https://x.example.com", name: "old", checkFrequency: 30 }] });
   const result = await applyMonitorConfig({
-    config: { monitors: [{ url: "https://x.example.com", name: "new", alertEmail: null, checkFrequency: 30 }] },
+    config: { monitors: [{ url: "https://x.example.com", name: "new", emailAlerts: true, policyId: null, checkFrequency: 30 }] },
     client,
     dryRun: false,
   });
@@ -269,6 +402,50 @@ test("CLI skip-with-notice: no BETTERSTACK_API_TOKEN exits 0 with a notice, no c
   rmSync(tmpDir, { recursive: true, force: true });
 });
 
+test("CLI skip-with-notice raises a ::warning:: annotation so an inert apply is visible in the checks UI", () => {
+  tmpDir = mkdtempSync(join(tmpdir(), "uptime-monitors-"));
+  const configPath = join(tmpDir, "monitors.json");
+  writeFileSync(configPath, JSON.stringify([{ url: "https://x.example.com" }]));
+  const out = execFileSync("node", [CLI, "--config", configPath], {
+    encoding: "utf8",
+    env: { ...process.env, BETTERSTACK_API_TOKEN: "" },
+  });
+  assert.match(out, /^::warning title=Uptime monitors not applied::/m);
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
+test("CLI announces UPTIME_ALERT_EMAIL as ignored instead of silently no-oping, and still exits 0", async () => {
+  tmpDir = mkdtempSync(join(tmpdir(), "uptime-monitors-"));
+  const configPath = join(tmpDir, "monitors.json");
+  writeFileSync(configPath, JSON.stringify([{ url: "https://x.example.com" }]));
+  // "Secret provisioned, token absent" is the exact state that produced a
+  // permanently-green apply a consumer believed was routing alerts — so this
+  // run must still say the address is inert, and must still exit 0.
+  const { stdout, stderr } = await execFileAsync(
+    "node",
+    [CLI, "--config", configPath, "--alert-email", "oncall@example.com"],
+    { env: { ...process.env, BETTERSTACK_API_TOKEN: "" } }
+  );
+  assert.match(stderr, /DEPRECATED: --alert-email \/ \$UPTIME_ALERT_EMAIL is ignored/);
+  assert.match(stderr, /policyId/, "the notice names the replacement, not just the removal");
+  assert.match(stdout, /^::warning title=UPTIME_ALERT_EMAIL is ignored::/m);
+  assert.match(stdout, /skipping uptime-monitor apply/);
+});
+
+test("CLI reports a config's retired alertEmail on stderr and never sends it", async () => {
+  const configPath = join(tmpDir, "legacy.json");
+  writeFileSync(configPath, JSON.stringify([{ url: "https://x.example.com", alertEmail: "oncall@example.com" }]));
+  const { stdout, stderr } = await execFileAsync(
+    "node",
+    [CLI, "--config", configPath, "--dry-run", "--alert-email", "oncall@example.com"],
+    { env: { ...process.env, BETTERSTACK_API_TOKEN: "tok", BETTERSTACK_API_BASE_OVERRIDE: "http://127.0.0.1:9" } }
+  ).catch((err) => err);
+  assert.match(stderr, /DEPRECATED: monitor config entry \[0\] sets "alertEmail"/);
+  assert.match(stderr, /DEPRECATED: --alert-email \/ \$UPTIME_ALERT_EMAIL is ignored/);
+  assert.match(stdout, /::warning title=UPTIME_ALERT_EMAIL is ignored::/);
+  rmSync(tmpDir, { recursive: true, force: true });
+});
+
 test("CLI exits non-zero on an invalid config file even with a token set", () => {
   tmpDir = mkdtempSync(join(tmpdir(), "uptime-monitors-"));
   const configPath = join(tmpDir, "monitors.json");

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

@@ -7,7 +7,7 @@
  * `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
+ * This suite pins the four 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):
  *
@@ -24,6 +24,12 @@
  *      `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.
+ *   4. DOCUMENTED PRECONDITION (Story #413) — neither `.github/workflows/
+ *      pr-quality.yml` nor `docs/reusable-workflows.md` claims affected mode
+ *      can never miss a task (true only of an UNRESOLVABLE base), and both
+ *      give the conditional consumer shape `turbo run <tier>
+ *      ${TURBO_SCM_BASE:+--affected}` — the gate that stops a baked-in
+ *      `--affected` from scheduling zero tasks on a push-to-`main` run.
  *
  * The `run:` script is executed against real bash with a stubbed
  * `resolve-diff-range.sh` (the sourced derivation), so no git repo is needed;
@@ -180,3 +186,50 @@ test("single-line affected-base override exports exactly TURBO_SCM_BASE and TURB
   const nonEmpty = r.envLines.split("\n").filter((l) => l.trim() !== "");
   assert.equal(nonEmpty.length, 2, `expected exactly two env lines, got: ${JSON.stringify(nonEmpty)}`);
 });
+
+// ---------------------------------------------------------------------------
+// 4. DOCUMENTED PRECONDITION (Story #413) — the `affected` input's safety claim
+//
+// The old prose promised affected mode "can never miss a task", which is true
+// only of the UNRESOLVABLE-base case. A `--affected` baked unconditionally into
+// a consumer's package script hits the resolvable-but-EMPTY case instead: with
+// `affected: false` the TURBO_SCM_* vars are never exported, turbo falls back
+// to its own default base of `main`, and on a push to `main` that range is
+// empty — zero tasks scheduled, exit 0, a silent no-op that reads as a pass.
+// These assertions pin the correction in both consumer-facing surfaces so the
+// absolute claim cannot return and the conditional shape cannot be dropped.
+// ---------------------------------------------------------------------------
+
+const DOCS = "docs/reusable-workflows.md";
+
+/** The safe consumer shape: `--affected` only when a base was exported. */
+const CONDITIONAL_FORM = "${TURBO_SCM_BASE:+--affected}";
+
+/** Absolute claims that over-promise the fallback. Retired — must not return. */
+const ABSOLUTE_CLAIMS = ["so this can never miss a task", "never a missed task"];
+
+for (const [label, relPath] of [
+  ["the reusable workflow", WORKFLOW],
+  ["the consumer documentation", DOCS],
+]) {
+  test(`${label} states the affected-mode precondition conditionally, not absolutely`, () => {
+    const text = readFileSync(join(repoRoot, relPath), "utf8");
+    // Case-insensitive: the claim is retired as a claim, not as a casing.
+    const haystack = text.toLowerCase();
+
+    for (const claim of ABSOLUTE_CLAIMS) {
+      assert.ok(
+        !haystack.includes(claim),
+        `${relPath} still claims "${claim}" — the full-run fallback covers an ` +
+          "unresolvable base only, not a base that resolves to an empty range"
+      );
+    }
+
+    assert.ok(
+      text.includes(CONDITIONAL_FORM),
+      `${relPath} must recommend \`turbo run <tier> ${CONDITIONAL_FORM}\` — gating ` +
+        "the flag on the exported base is what keeps a push-to-`main` run from " +
+        "silently scheduling zero tasks"
+    );
+  });
+}

package/scripts/check-coverage-threshold.test.mjs

@@ -485,7 +485,7 @@ test("formatVerdict renders a skip line for the disabled gate", () => {
 //
 // The workflow's "Coverage threshold gate" step no longer embeds a copy of
 // this script (Story #230): it sparse-side-checkouts mandrel-platform at
-// `github.job_workflow_sha` into `_mandrel-platform-scripts/` and runs
+// `job.workflow_sha` into `_mandrel-platform-scripts/` and runs
 // `scripts/check-coverage-threshold.mjs` directly. These tests exercise that
 // exact invocation shape — the real script, run from the side-checkout path,
 // with the workflow's `--threshold` / `--metric` args and the consumer

package/scripts/check-destructive-migration.mjs

@@ -84,6 +84,8 @@
 import { appendFileSync, readFileSync } from "node:fs";
 import { resolve } from "node:path";
 
+import { isDirectInvocation } from './lib/entry-guard.mjs';
+
 // The override acknowledgement label. Documented in docs/reusable-workflows.md.
 export const DEFAULT_OVERRIDE_LABEL = "migration:destructive-ok";
 
@@ -635,7 +637,9 @@ function main() {
   process.exit(1);
 }
 
-// Only run the CLI when invoked directly, not when imported by the self-test.
-if (import.meta.url === `file://${process.argv[1]}`) {
+// Direct-invocation guard — symlink-safe via the shared seam (Story #407):
+// comparing an unresolved argv[1] against a realpath-resolved
+// import.meta.url silently never matches under pnpm's symlinked node_modules.
+if (isDirectInvocation(import.meta.url)) {
   main();
 }