mandrel-platform 1.0.0 → 1.0.1

package/scripts/check-ci-required-aggregator.test.mjs

@@ -17,20 +17,34 @@
  *   1. STRUCTURE — each aggregator's `steps:` derive results from
  *      `toJSON(needs)` and contain NO hardcoded reference to any job named in
  *      its own `needs:` array (the "no hardcoded tier-name list" AC).
- *   2. PARITY — the two aggregators' `steps:` blocks are textually identical,
- *      so a fix to one cannot drift from the other.
+ *   2. PARITY — the two aggregators' `run:` scripts are byte-identical and both
+ *      declare the same `env:` keys, so a fix to one cannot drift from the
+ *      other. (Story #333 loosened this from "the whole `steps:` blocks are
+ *      identical": ci.yml has no `workflow_call` inputs, so it must source
+ *      `CANCELLED_POLICY` as a literal where pr-quality.yml sources it from
+ *      `inputs.cancelled-policy`. The shared script reads it from the
+ *      environment, which is what keeps the logic itself byte-identical.)
  *   3. SEMANTICS — the shared run script passes on `success`/`skipped` and
  *      fails on anything else, INCLUDING `cancelled` (load-bearing for #223's
  *      fail-fast design), while naming the failing jobs and their results.
  *      Executed against real bash+jq; skipped when jq is unavailable locally
- *      (CI's ubuntu runner always has it).
+ *      (CI's ubuntu runner always has it). `gh` is stubbed to fail so these
+ *      tests stay hermetic — provenance classification (Story #333) has its
+ *      own suite in scripts/check-cancelled-provenance.test.mjs.
  *
  * Run: node --test scripts/check-ci-required-aggregator.test.mjs
  */
 
 import assert from "node:assert/strict";
 import { test } from "node:test";
-import { readFileSync, mkdtempSync, writeFileSync, rmSync } from "node:fs";
+import {
+  readFileSync,
+  mkdtempSync,
+  mkdirSync,
+  writeFileSync,
+  chmodSync,
+  rmSync,
+} from "node:fs";
 import { execFileSync, spawnSync } from "node:child_process";
 import { join, resolve, dirname } from "node:path";
 import { fileURLToPath } from "node:url";
@@ -155,14 +169,61 @@ for (const { rel, needs, steps } of blocks) {
 // 2. PARITY — the two implementations are textually identical
 // ---------------------------------------------------------------------------
 
-test("pr-quality.yml and ci.yml aggregator steps are textually identical", () => {
+// Story #333 re-shaped this from "the whole `steps:` blocks are byte-identical"
+// to "the `run:` scripts are byte-identical AND both declare the same `env:`
+// keys". ci.yml has no `workflow_call` inputs, so it cannot source
+// `CANCELLED_POLICY` from `inputs.cancelled-policy` the way pr-quality.yml
+// does — but the LOGIC is what must not drift, and the script reads the policy
+// from the environment precisely so the two can share it verbatim.
+
+/** The `KEY:` names declared under a steps block's `env:` mapping. */
+function extractEnvKeys(steps) {
+  const stepLines = steps.split("\n");
+  const start = stepLines.findIndex((l) => /^\s+env:\s*$/.test(l));
+  assert.notEqual(start, -1, "`env:` block not found");
+  const envIndent = stepLines[start].match(/^(\s*)/)[1].length;
+  const keys = [];
+  for (let i = start + 1; i < stepLines.length; i++) {
+    if (/^\s*$/.test(stepLines[i])) continue;
+    if (/^\s*#/.test(stepLines[i])) continue;
+    const indent = stepLines[i].match(/^(\s*)/)[1].length;
+    if (indent <= envIndent) break;
+    const key = stepLines[i].match(/^\s+([A-Za-z_][A-Za-z0-9_]*):/);
+    if (key) keys.push(key[1]);
+  }
+  assert.ok(keys.length > 0, "`env:` block declared no keys");
+  return keys.sort();
+}
+
+test("pr-quality.yml and ci.yml aggregator run scripts are byte-identical", () => {
   assert.equal(
-    blocks[0].steps,
-    blocks[1].steps,
-    "the two `ci-required` steps blocks must not drift — apply every change to both"
+    extractRunScript(blocks[0].steps),
+    extractRunScript(blocks[1].steps),
+    "the two `ci-required` run scripts must not drift — apply every logic change to both"
+  );
+});
+
+test("pr-quality.yml and ci.yml aggregators declare the same env keys", () => {
+  assert.deepEqual(
+    extractEnvKeys(blocks[0].steps),
+    extractEnvKeys(blocks[1].steps),
+    "the shared run script reads its inputs from the environment — a key present " +
+      "in only one workflow would leave the other running the same script unconfigured"
   );
 });
 
+test("the shared aggregator script never references workflow_call inputs", () => {
+  // ci.yml has none, so an `inputs.*` reference could not be mirrored and
+  // would break the byte-identical run-script guarantee above.
+  for (const { rel, steps } of blocks) {
+    assert.doesNotMatch(
+      extractRunScript(steps),
+      /inputs\./,
+      `${rel}: the run script must read configuration from \`env:\`, not \`inputs.*\``
+    );
+  }
+});
+
 // ---------------------------------------------------------------------------
 // 3. SEMANTICS — pass on success/skipped, fail (naming jobs) on anything else
 // ---------------------------------------------------------------------------
@@ -176,7 +237,7 @@ function jqAvailable() {
   }
 }
 
-function runAggregator(needsResults) {
+function runAggregator(needsResults, { captureSummary = false } = {}) {
   const script = extractRunScript(blocks[0].steps);
   const dir = mkdtempSync(join(tmpdir(), "ci-required-"));
   try {
@@ -185,10 +246,36 @@ function runAggregator(needsResults) {
     const needsJson = Object.fromEntries(
       Object.entries(needsResults).map(([k, result]) => [k, { result, outputs: {} }])
     );
-    return spawnSync("bash", [file], {
-      encoding: "utf8",
-      env: { ...process.env, NEEDS_JSON: JSON.stringify(needsJson) },
-    });
+    // Neutralize the provenance lookup (Story #333): shadow `gh` with a stub
+    // that always fails, so these tests stay hermetic and exercise the
+    // `unknown`-provenance path. Provenance classification itself is covered
+    // by scripts/check-cancelled-provenance.test.mjs.
+    const bin = join(dir, "bin");
+    mkdirSync(bin);
+    const ghStub = join(bin, "gh");
+    writeFileSync(ghStub, "#!/usr/bin/env bash\nexit 1\n");
+    chmodSync(ghStub, 0o755);
+
+    const env = {
+      ...process.env,
+      PATH: `${bin}:${process.env.PATH}`,
+      NEEDS_JSON: JSON.stringify(needsJson),
+    };
+    // The step-summary write must degrade when GITHUB_STEP_SUMMARY is unset
+    // (this harness, and any `act`-style local runner), so only define it when
+    // a test is actually asserting on the summary body.
+    const summaryPath = join(dir, "summary.md");
+    if (captureSummary) {
+      writeFileSync(summaryPath, "");
+      env.GITHUB_STEP_SUMMARY = summaryPath;
+    } else {
+      delete env.GITHUB_STEP_SUMMARY;
+    }
+    const r = spawnSync("bash", [file], { encoding: "utf8", env });
+    return {
+      ...r,
+      summary: captureSummary ? readFileSync(summaryPath, "utf8") : "",
+    };
   } finally {
     rmSync(dir, { recursive: true, force: true });
   }
@@ -225,3 +312,72 @@ test("run script: every non-passing job is named", semantics, () => {
   assert.match(r.stderr, /unit\(cancelled\)/);
   assert.doesNotMatch(r.stderr, /e2e/);
 });
+
+// ---------------------------------------------------------------------------
+// 4. TRIAGE PARTITION (Story #331) — a fail-fast run reds N jobs but only one
+//    of them actually failed. The aggregate must say WHICH, so triage does not
+//    land on a collateral cancel.
+// ---------------------------------------------------------------------------
+
+test("run script: partitions own-failures from collateral cancels", semantics, () => {
+  const r = runAggregator({
+    lint: "success",
+    security: "failure",
+    unit: "cancelled",
+    e2e: "cancelled",
+  });
+  assert.equal(r.status, 1);
+
+  const own = r.stderr
+    .split("\n")
+    .find((l) => l.includes("Failed on their own"));
+  const collateral = r.stderr
+    .split("\n")
+    .find((l) => l.includes("do not triage"));
+
+  assert.ok(own, `no own-failure line in stderr:\n${r.stderr}`);
+  assert.ok(collateral, `no collateral line in stderr:\n${r.stderr}`);
+
+  // The tier that actually failed is named ONLY on the triage line, and the
+  // cancelled siblings ONLY on the collateral line — a partition, not two
+  // copies of the same flat list.
+  assert.match(own, /security\(failure\)/);
+  assert.doesNotMatch(own, /unit|e2e/);
+  assert.match(collateral, /unit\(cancelled\)/);
+  assert.match(collateral, /e2e\(cancelled\)/);
+  assert.doesNotMatch(collateral, /security/);
+});
+
+test("run script: an all-cancelled aggregate says no job failed on its own", semantics, () => {
+  const r = runAggregator({ lint: "success", unit: "cancelled" }, { captureSummary: true });
+  assert.equal(r.status, 1);
+  assert.doesNotMatch(r.stderr, /Failed on their own/);
+  assert.match(r.summary, /No job reported its own failure/);
+});
+
+test("run script: writes the triage partition to the job summary", semantics, () => {
+  const r = runAggregator(
+    { security: "failure", unit: "cancelled" },
+    { captureSummary: true }
+  );
+  assert.equal(r.status, 1);
+  assert.match(r.summary, /ci-required failed/);
+  assert.match(r.summary, /Failed on their own[^\n]*security\(failure\)/);
+  assert.match(r.summary, /Cancelled[^\n]*do not triage:[^\n]*unit\(cancelled\)/);
+});
+
+test("run script: a green aggregate writes no summary", semantics, () => {
+  const r = runAggregator({ lint: "success", unit: "success" }, { captureSummary: true });
+  assert.equal(r.status, 0, r.stderr);
+  assert.equal(r.summary, "");
+});
+
+test("run script: survives an unset GITHUB_STEP_SUMMARY", semantics, () => {
+  // The failure path writes a summary; with the variable unset (local runners,
+  // `act`, this harness) the redirect must degrade rather than error out and
+  // swallow the exit-1 verdict.
+  const r = runAggregator({ unit: "failure" });
+  assert.equal(r.status, 1);
+  assert.match(r.stderr, /unit\(failure\)/);
+  assert.doesNotMatch(r.stderr, /ambiguous redirect|No such file or directory/);
+});

package/scripts/check-destructive-migration.test.mjs

@@ -56,6 +56,43 @@ test("globToRegExp: `**` crosses path separators, `*` does not", () => {
   assert.ok(globToRegExp("*.sql").test("x.sql"));
 });
 
+// The glob set reaches this function from a CLI argument, so CodeQL reports
+// `js/regex-injection` (high) on the `new RegExp` it builds. That alert is a
+// false positive ONLY for as long as the translator escapes every regex
+// metacharacter — the input must be able to control `*` / `**` semantics and
+// nothing else. These two tests are the evidence that claim rests on; if a
+// future edit drops a character from the escape set, they fail rather than
+// letting a stale dismissal stand.
+test("globToRegExp: escapes every regex metacharacter to a literal", () => {
+  // `*` is excluded deliberately — it is the one character the glob syntax
+  // gives meaning to. `/` is not a metacharacter in the RegExp *constructor*
+  // (only in literal notation), but is asserted anyway.
+  const METACHARS = [".", "+", "?", "^", "$", "{", "}", "(", ")", "|", "[", "]", "\\", "/"];
+  for (const meta of METACHARS) {
+    const glob = `a${meta}b`;
+    const re = globToRegExp(glob);
+    assert.ok(re.test(glob), `\`${meta}\` must match itself literally (got ${re})`);
+    assert.ok(
+      !re.test("aXb"),
+      `\`${meta}\` leaked regex meaning — it matched an arbitrary character (got ${re})`
+    );
+  }
+});
+
+test("globToRegExp: a regex-injection payload translates to a literal pattern", () => {
+  // The classic catastrophic-backtracking payload. If any of it survived
+  // unescaped, this pattern would carry regex semantics into the matcher.
+  const re = globToRegExp("(a+)+$");
+  // Compared as a STRING, not against a regex literal: writing the expected
+  // pattern as `/^\(a\+\)\+\$$/` puts a (wholly escaped, quantifier-free)
+  // regex literal in the file that CodeQL's js/redos analysis reads as a live
+  // backtracking hazard. The assertion is identical in strength — this test
+  // has always been about the produced source text.
+  assert.equal(String(re), "/^\\(a\\+\\)\\+\\$$/");
+  assert.ok(re.test("(a+)+$"), "the payload matches only its literal self");
+  assert.ok(!re.test("aaaaaaaa"), "the payload carries no quantifier semantics");
+});
+
 test("isMigrationFile: matches migration globs and any .sql tail", () => {
   assert.ok(isMigrationFile("apps/api/migrations/0007_drop.ts"));
   assert.ok(isMigrationFile("drizzle/0001_init.sql"));

package/scripts/check-fail-fast-attribution.test.mjs

@@ -0,0 +1,390 @@
+#!/usr/bin/env node
+/**
+ * check-fail-fast-attribution.test.mjs — regression guard for fail-fast
+ * cancellation attribution in `.github/workflows/pr-quality.yml` (Story #331).
+ *
+ * WHY THIS EXISTS
+ * ---------------
+ * Opt-in `fail-fast` (Story #223) cancels the whole run on the first tier
+ * failure. GitHub records a bare `cancelled` conclusion on every sibling tier
+ * — with no pointer to the tier that actually failed. A job-status scan then
+ * reads N red jobs and blames the wrong one: in swarm-os run 30168441137 the
+ * Accessibility tier failed on a transient build flake, fail-fast cancelled
+ * Typecheck and Lint & format (both of which had already passed their own work
+ * step), and triage landed on Typecheck.
+ *
+ * The fix writes the attribution at two workflow surfaces, and this suite pins
+ * both against regression:
+ *
+ *   1. TRIGGER SIDE (`&cancel-on-failure`) — the authoritative record. It runs
+ *      in a job whose conclusion is `failure`, never `cancelled`, so it is not
+ *      subject to the runner's cancellation grace budget. It emits a run-level
+ *      `::error title=fail-fast::` annotation and a job-summary block naming
+ *      the tier, BEFORE requesting the cancel — so the record survives even
+ *      when the cancel call itself fails.
+ *
+ *   2. COLLATERAL SIDE (`&explain-cancellation`) — best effort. Fires only on
+ *      `cancelled()`, states that this tier did not itself fail, and resolves
+ *      the real culprit from the Actions API. Loud-but-non-fatal on the cancel
+ *      step's terms: every lookup failure degrades to a generic message and
+ *      exits 0, and `timeout-minutes: 1` keeps the lookup from eating the
+ *      grace budget the tier's own artifact uploads need.
+ *
+ * It also pins the negative space that makes this change safe to ship to
+ * consumers: no new permission surface. GitHub validates a called workflow's
+ * declared JOB permissions against the caller's grant at compile time,
+ * ignoring the job's `if:` gate — so a job-level `permissions:` block here
+ * would `startup_failure` every consumer that has not widened its caller
+ * token, whether or not they enable fail-fast.
+ *
+ * Run: node --test scripts/check-fail-fast-attribution.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import {
+  readFileSync,
+  writeFileSync,
+  mkdtempSync,
+  mkdirSync,
+  rmSync,
+  chmodSync,
+} from "node:fs";
+import { spawnSync } from "node:child_process";
+import { join, resolve, dirname } from "node:path";
+import { fileURLToPath } from "node:url";
+import { tmpdir } from "node:os";
+
+const repoRoot = resolve(dirname(fileURLToPath(import.meta.url)), "..");
+const WORKFLOW = ".github/workflows/pr-quality.yml";
+const source = readFileSync(join(repoRoot, WORKFLOW), "utf8");
+const lines = source.split("\n");
+
+const EXPLAIN = "explain-cancellation";
+const CANCEL = "cancel-on-failure";
+
+// ---------------------------------------------------------------------------
+// Indentation-based extraction (dependency-free, mirroring the approach in
+// check-ci-required-aggregator.test.mjs). Steps are `      - ` entries at
+// 6-space indent; jobs are `  <id>:` at 2-space indent.
+// ---------------------------------------------------------------------------
+
+/** The step block introduced by `      - &<anchor>`, through its last line. */
+function extractAnchoredStep(anchor) {
+  const start = lines.findIndex((l) => l === `      - &${anchor}`);
+  assert.notEqual(start, -1, `anchor \`&${anchor}\` not found in ${WORKFLOW}`);
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^\s*$/.test(lines[i])) continue;
+    if (lines[i].match(/^(\s*)/)[1].length <= 6) {
+      end = i;
+      break;
+    }
+  }
+  return lines.slice(start, end).join("\n");
+}
+
+/** The dedented body of a step's `run: |` block scalar. */
+function extractRunScript(step) {
+  const stepLines = step.split("\n");
+  const start = stepLines.findIndex((l) => /^\s+run:\s*\|\s*$/.test(l));
+  assert.notEqual(start, -1, "`run: |` block not found");
+  const runIndent = stepLines[start].match(/^(\s*)/)[1].length;
+  const body = [];
+  for (let i = start + 1; i < stepLines.length; i++) {
+    if (/^\s*$/.test(stepLines[i])) {
+      body.push("");
+      continue;
+    }
+    if (stepLines[i].match(/^(\s*)/)[1].length <= runIndent) break;
+    body.push(stepLines[i].slice(runIndent + 2));
+  }
+  return body.join("\n");
+}
+
+/**
+ * Every job in the workflow, as `{ id, stepRefs }` where `stepRefs` is the
+ * ordered list of anchor/alias names used as step entries (`- &x` / `- *x`).
+ * A plain `- name: …` step contributes nothing — only the aliased ones matter
+ * for the ordering invariant this suite pins.
+ */
+function extractJobs() {
+  const jobsStart = lines.findIndex((l) => l === "jobs:");
+  assert.notEqual(jobsStart, -1, "`jobs:` not found");
+  const jobs = [];
+  let current = null;
+  for (let i = jobsStart + 1; i < lines.length; i++) {
+    const jobHeader = lines[i].match(/^ {2}([A-Za-z0-9_-]+):\s*$/);
+    if (jobHeader) {
+      current = { id: jobHeader[1], stepRefs: [] };
+      jobs.push(current);
+      continue;
+    }
+    const stepRef = lines[i].match(/^ {6}- [&*]([A-Za-z0-9_-]+)\s*$/);
+    if (stepRef && current) current.stepRefs.push(stepRef[1]);
+  }
+  assert.ok(jobs.length > 0, "no jobs parsed");
+  return jobs;
+}
+
+const explainStep = extractAnchoredStep(EXPLAIN);
+const cancelStep = extractAnchoredStep(CANCEL);
+const jobs = extractJobs();
+
+// ---------------------------------------------------------------------------
+// 1. STRUCTURE — the two attribution surfaces exist, are correctly gated, and
+//    are wired into every tier job that participates in fail-fast.
+// ---------------------------------------------------------------------------
+
+test("the collateral explainer fires only on cancellation under fail-fast", () => {
+  assert.match(
+    explainStep,
+    /^\s+if:\s+\$\{\{\s*cancelled\(\)\s*&&\s*inputs\.fail-fast\s*\}\}\s*$/m,
+    "`&explain-cancellation` must be gated `cancelled() && inputs.fail-fast` — " +
+      "an `always()` gate would fire it on the green path"
+  );
+});
+
+test("the trigger-side record fires only on this tier's own failure", () => {
+  assert.match(
+    cancelStep,
+    /^\s+if:\s+\$\{\{\s*failure\(\)\s*&&\s*inputs\.fail-fast\s*\}\}\s*$/m,
+    "`&cancel-on-failure` must stay gated `failure() && inputs.fail-fast` — " +
+      "the two attribution gates must remain mutually exclusive"
+  );
+});
+
+test("the collateral explainer is time-bounded", () => {
+  // A cancelled job runs its remaining cancelled()/always() steps inside a
+  // bounded runner grace period. An unbounded API lookup here would compete
+  // with the tier's own artifact uploads for that budget.
+  assert.match(
+    explainStep,
+    /^\s+timeout-minutes:\s+1\s*$/m,
+    "`&explain-cancellation` must declare `timeout-minutes: 1`"
+  );
+});
+
+test("every fail-fast tier job carries both attribution steps", () => {
+  const participating = jobs.filter((j) => j.stepRefs.includes(CANCEL));
+  assert.ok(
+    participating.length >= 8,
+    `expected every tier job to alias \`${CANCEL}\`; found ${participating.length}`
+  );
+  for (const job of participating) {
+    assert.ok(
+      job.stepRefs.includes(EXPLAIN),
+      `job \`${job.id}\` aliases \`${CANCEL}\` but not \`${EXPLAIN}\` — a ` +
+        `cancelled ${job.id} would report a bare 'cancelled' with no upstream pointer`
+    );
+  }
+});
+
+test("the explainer immediately precedes the cancel step, which stays last", () => {
+  for (const job of jobs.filter((j) => j.stepRefs.includes(CANCEL))) {
+    const cancelIdx = job.stepRefs.indexOf(CANCEL);
+    const explainIdx = job.stepRefs.indexOf(EXPLAIN);
+    assert.equal(
+      explainIdx,
+      cancelIdx - 1,
+      `job \`${job.id}\`: \`${EXPLAIN}\` must sit immediately before \`${CANCEL}\``
+    );
+    assert.equal(
+      cancelIdx,
+      job.stepRefs.length - 1,
+      `job \`${job.id}\`: \`${CANCEL}\` must remain the LAST step, so ` +
+        `\`if: always()\` uploads finish before the run-wide cancel signal lands`
+    );
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 2. PERMISSION SURFACE — unchanged. `gh run view` needs only `actions: read`,
+//    already covered by the workflow-level `actions: write`.
+// ---------------------------------------------------------------------------
+
+/**
+ * Job-level permission blocks, as `{ job: [scope, …] }`. Three jobs already
+ * declare one on `main` (a job-level block REPLACES the workflow-level one, so
+ * each has to re-declare the fail-fast cancel grant). This suite pins that
+ * inventory rather than forbidding it outright: the invariant that matters is
+ * that fail-fast attribution introduced no NEW grant.
+ */
+function extractJobPermissions() {
+  const found = {};
+  let job = null;
+  for (let i = 0; i < lines.length; i++) {
+    const header = lines[i].match(/^ {2}([A-Za-z0-9_-]+):\s*$/);
+    if (header) job = header[1];
+    if (!/^ {4}permissions:/.test(lines[i])) continue;
+    const scopes = [];
+    for (let j = i + 1; j < lines.length; j++) {
+      if (/^\s*#/.test(lines[j])) continue;
+      const scope = lines[j].match(/^ {6}([a-z-]+):\s*(\S+)\s*$/);
+      if (!scope) break;
+      scopes.push(`${scope[1]}: ${scope[2]}`);
+    }
+    found[job] = scopes;
+  }
+  return found;
+}
+
+test("no job declares a permission beyond the pre-existing inventory", () => {
+  // A job-level `permissions:` block is validated against the CALLER's grant
+  // at compile time, ignoring the job's `if:` gate — a new or widened one here
+  // startup_failures EVERY consumer that has not widened its caller token,
+  // including consumers that never enable the tier. `gh run view` (the
+  // collateral explainer's culprit lookup) needs only `actions: read`, which
+  // the existing `actions: write` already covers, so nothing had to change.
+  assert.deepEqual(extractJobPermissions(), {
+    "migration-guard": ["contents: read", "actions: write", "pull-requests: read"],
+    security: ["contents: read", "actions: write"],
+    "osv-scan": ["contents: read", "actions: write"],
+  });
+});
+
+test("the workflow-level permission grant is unchanged", () => {
+  assert.match(
+    source,
+    /^permissions:\n {2}contents: read\n {2}actions: write\n/m,
+    "the attribution steps must not widen the declared permission surface"
+  );
+});
+
+// ---------------------------------------------------------------------------
+// 3. SEMANTICS — the two run scripts, executed under real bash against a
+//    stubbed `gh` on PATH.
+// ---------------------------------------------------------------------------
+
+/**
+ * Execute a step's run script with a stubbed `gh` (and `curl`) shadowing any
+ * real binaries, so the scripts' branches are exercised without network I/O.
+ */
+function runStep(script, { ghExit = 0, ghStdout = "", env = {} } = {}) {
+  const dir = mkdtempSync(join(tmpdir(), "fail-fast-attr-"));
+  try {
+    const bin = join(dir, "bin");
+    mkdirSync(bin);
+    for (const cmd of ["gh", "curl"]) {
+      const stub = join(bin, cmd);
+      writeFileSync(
+        stub,
+        `#!/usr/bin/env bash\nprintf '%s' ${JSON.stringify(ghStdout)}\nexit ${ghExit}\n`
+      );
+      chmodSync(stub, 0o755);
+    }
+    const summary = join(dir, "summary.md");
+    writeFileSync(summary, "");
+    const file = join(dir, "step.sh");
+    writeFileSync(file, script);
+    const r = spawnSync("bash", [file], {
+      encoding: "utf8",
+      env: {
+        ...process.env,
+        PATH: `${bin}:${process.env.PATH}`,
+        GITHUB_STEP_SUMMARY: summary,
+        GITHUB_API_URL: "https://api.github.invalid",
+        GH_TOKEN: "stub-token",
+        RUN_ID: "30168441137",
+        REPO: "Beestera/swarm-os",
+        TIER_ID: "typecheck",
+        ...env,
+      },
+    });
+    return { ...r, summary: readFileSync(summary, "utf8") };
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+const cancelScript = extractRunScript(cancelStep);
+const explainScript = extractRunScript(explainStep);
+
+test("trigger side: names the failing tier in a run-level annotation", () => {
+  const r = runStep(cancelScript, { env: { TIER_ID: "e2e" } });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(
+    r.stdout,
+    /::error title=fail-fast::/,
+    "the trigger must emit a run-level annotation, not just a log line"
+  );
+  assert.match(r.stdout, /e2e/, "the annotation must name the tier that failed");
+  assert.match(r.stdout, /collateral/);
+});
+
+test("trigger side: writes the attribution to the job summary", () => {
+  const r = runStep(cancelScript, { env: { TIER_ID: "e2e" } });
+  assert.match(r.summary, /fail-fast triggered by/);
+  assert.match(r.summary, /e2e/);
+});
+
+test("trigger side: records the attribution even when the cancel call fails", () => {
+  // A caller whose token lacks `actions: write` cannot cancel — the record of
+  // WHICH tier failed must still land, which is why it is written first.
+  const r = runStep(cancelScript, { ghExit: 1, ghStdout: "000" });
+  assert.equal(r.status, 0, "the cancel step stays non-fatal");
+  assert.match(r.stdout, /::error title=fail-fast::/);
+  assert.match(r.summary, /fail-fast triggered by/);
+});
+
+test("collateral side: names the real culprit when the lookup succeeds", () => {
+  const r = runStep(explainScript, { ghStdout: "Accessibility (2/3)" });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /::notice title=fail-fast collateral::/);
+  assert.match(r.stdout, /Accessibility \(2\/3\)/);
+  assert.match(r.summary, /Accessibility \(2\/3\)/);
+  assert.match(r.summary, /did \*\*not\*\* fail/);
+});
+
+test("collateral side: degrades to a generic message when the lookup fails", () => {
+  const r = runStep(explainScript, { ghExit: 1 });
+  assert.equal(
+    r.status,
+    0,
+    "a failed culprit lookup must never fail the step — it is best-effort"
+  );
+  assert.match(r.stdout, /::notice title=fail-fast collateral::/);
+  assert.match(r.stdout, /could not be resolved/);
+  assert.match(r.summary, /could not be resolved/);
+});
+
+test("collateral side: still explains itself when gh is absent entirely", () => {
+  // Self-hosted runners are not guaranteed to ship the gh CLI.
+  const dir = mkdtempSync(join(tmpdir(), "fail-fast-nogh-"));
+  try {
+    const empty = join(dir, "bin");
+    mkdirSync(empty);
+    const summary = join(dir, "summary.md");
+    writeFileSync(summary, "");
+    const file = join(dir, "step.sh");
+    writeFileSync(file, explainScript);
+    // Resolve bash absolutely — PATH is deliberately emptied for the child so
+    // `command -v gh` finds nothing.
+    const r = spawnSync("/bin/bash", [file], {
+      encoding: "utf8",
+      env: {
+        PATH: empty,
+        GITHUB_STEP_SUMMARY: summary,
+        RUN_ID: "1",
+        REPO: "o/r",
+        TIER_ID: "lint",
+        GH_TOKEN: "stub-token",
+      },
+    });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stdout, /lint/);
+    assert.match(readFileSync(summary, "utf8"), /could not be resolved/);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test("collateral side: never claims this tier failed", () => {
+  const r = runStep(explainScript, { ghStdout: "Accessibility (2/3)" });
+  assert.doesNotMatch(
+    r.stdout,
+    /::error/,
+    "a collateral cancel must not emit a failure annotation — that is what " +
+      "made cancelled siblings indistinguishable from the real failure"
+  );
+});