mandrel-platform 1.12.0 → 1.13.1

package/scripts/check-semgrep-lockfile.test.mjs

@@ -38,7 +38,61 @@ const LOCKFILE = "scripts/semgrep-requirements.txt";
 const WORKFLOW = ".github/workflows/pr-quality.yml";
 const UPDATER = "scripts/update-semgrep-rules.mjs";
 
+const DOCS = "docs/reusable-workflows.md";
+
 const lockfile = readFileSync(LOCKFILE, "utf8");
+const workflow = readFileSync(WORKFLOW, "utf8");
+
+const SAST_STEP_HEADER = "- name: SAST (Semgrep, blocking, no SARIF upload)";
+
+/**
+ * Return the SAST step's `run:` body — from its `- name:` line to the next
+ * step at the same indentation — with comment-only lines stripped.
+ *
+ * Both halves earn their place. Scoping to the step is what stops a whole-file
+ * `indexOf` from resolving an anchor against an unrelated tier a thousand
+ * lines away; dropping comments is what stops it from resolving against PROSE
+ * ABOUT the code instead of the code. The selector-before-venv guard below did
+ * both: its `select-semgrep-python.sh` hit landed in the side-checkout step's
+ * comment block and its `-m venv` hit in a paragraph explaining venvs, so the
+ * ordering it asserted was the ordering of two comments.
+ */
+function sastStepCode(text = workflow) {
+  const start = text.indexOf(SAST_STEP_HEADER);
+  if (start === -1) return "";
+  const rest = text.slice(start + SAST_STEP_HEADER.length);
+  const end = rest.indexOf("\n      - ");
+  const step = end === -1 ? rest : rest.slice(0, end);
+  return step
+    .split("\n")
+    .filter((line) => !line.trimStart().startsWith("#"))
+    .join("\n");
+}
+
+/**
+ * True when the SAST step chooses its interpreter before it builds the venv.
+ * A predicate rather than a bare assertion so the guard can be exercised
+ * against a MUTATED workflow — a test that only ever sees the passing input
+ * cannot show it would notice the failure.
+ */
+function selectorPrecedesVenv(text) {
+  const code = sastStepCode(text);
+  const select = code.indexOf('source "${SELECT_PYTHON}"');
+  const venv = code.indexOf('"${SEMGREP_PYTHON}" -m venv');
+  if (select === -1 || venv === -1) return false;
+  return select < venv;
+}
+
+// semgrep's own `requires_python`, recorded per release. Verified on PyPI
+// 2026-09-10: 1.97.0 was `>=3.8`, 1.136.0 `>=3.9`, and 1.137.0 raised it to
+// `>=3.10` — which is why a runner on macOS system Python (3.9.6) could not
+// install the 1.176.1 pin at all (issue #480).
+//
+// This table is what makes the floor in pr-quality.yml checkable without a
+// network call: a bump to a release with no entry here fails loudly, so
+// "look up the new requires_python" becomes a step of the bump rather than
+// something discovered by a consumer's red CI.
+const SEMGREP_PYTHON_FLOORS = new Map([["1.176.1", "3.10"]]);
 
 /**
  * Parse `name==version` requirement lines, ignoring comments and hash
@@ -118,7 +172,6 @@ test("the lockfile, the workflow, and the rules updater pin the same semgrep", (
   const lockVersion = REQS.get("semgrep");
   assert.ok(lockVersion, `${LOCKFILE}: semgrep must be pinned`);
 
-  const workflow = readFileSync(WORKFLOW, "utf8");
   const wf = workflow.match(/SEMGREP_PIN='semgrep==([^']+)'/);
   assert.ok(wf, `${WORKFLOW}: SEMGREP_PIN not found`);
   assert.equal(wf[1], lockVersion, "workflow SEMGREP_PIN disagrees with the lockfile");
@@ -203,3 +256,319 @@ test("the header warns about the manylinux_2_34 wheel tag", () => {
     "the header must carry a regeneration command",
   );
 });
+
+// ---------------------------------------------------------------------------
+// 5. The interpreter floor on the non-lockfile install path (Story #482)
+// ---------------------------------------------------------------------------
+
+test("pr-quality.yml declares an interpreter floor matching the pinned semgrep", () => {
+  const version = REQS.get("semgrep");
+  const declared = workflow.match(/SEMGREP_PYTHON_FLOOR='([^']+)'/);
+  assert.ok(
+    declared,
+    `${WORKFLOW}: SEMGREP_PYTHON_FLOOR must be declared beside SEMGREP_PIN — without it the SAST step cannot tell a too-old interpreter from a working one`,
+  );
+
+  const recorded = SEMGREP_PYTHON_FLOORS.get(version);
+  assert.ok(
+    recorded,
+    `no requires_python floor recorded for semgrep ${version} — read it off PyPI and add it to SEMGREP_PYTHON_FLOORS before bumping SEMGREP_PIN`,
+  );
+  assert.equal(
+    declared[1],
+    recorded,
+    `SEMGREP_PYTHON_FLOOR is ${declared[1]} but semgrep ${version} requires Python >= ${recorded}`,
+  );
+});
+
+test("the selector rides the same side-checkout as the lockfile", () => {
+  // The sparse-checkout is NON-CONE and lists exact paths, so a script the
+  // SAST step sources is absent at run time unless it is named here — and a
+  // missing `source` target kills the security tier for every consumer at
+  // once. Both files must sit in the one list.
+  const start = workflow.indexOf("- name: Checkout Semgrep lockfile");
+  assert.notEqual(start, -1, `${WORKFLOW}: the Semgrep side-checkout step was renamed or removed`);
+  const step = workflow.slice(start, workflow.indexOf("path: _mandrel-platform-semgrep", start));
+
+  assert.ok(
+    step.includes("scripts/semgrep-requirements.txt"),
+    "the side-checkout must still carry the lockfile",
+  );
+  assert.ok(
+    step.includes("scripts/select-semgrep-python.sh"),
+    "the side-checkout must carry the interpreter selector the SAST step sources",
+  );
+  assert.ok(
+    step.includes("sparse-checkout-cone-mode: false"),
+    "non-cone mode is what makes the exact-path list meaningful",
+  );
+});
+
+test("the SAST step selects an interpreter before it creates the venv", () => {
+  // A venv inherits the interpreter that built it, so a floor enforced after
+  // `-m venv` cannot fix anything. Order is the whole guarantee.
+  const code = sastStepCode();
+  assert.notEqual(code, "", `${WORKFLOW}: the SAST step was renamed or removed`);
+  assert.ok(
+    code.includes('source "${SELECT_PYTHON}"'),
+    `${WORKFLOW}: the SAST step must source the interpreter selector`,
+  );
+  assert.ok(
+    code.includes('"${SEMGREP_PYTHON}" -m venv'),
+    "the venv must be built from the selected interpreter, not from bare python3",
+  );
+  assert.ok(selectorPrecedesVenv(workflow), "the selector must be sourced BEFORE the venv");
+});
+
+test("the selector-before-venv guard fails when the two are swapped", () => {
+  // The mutation the guard exists to catch, performed on a copy: move the venv
+  // line above the `source` line and the check must go red. Without this, the
+  // guard could be resolving anchors that no reordering of the real step would
+  // ever move — which is precisely how it passed while comparing two comments.
+  const VENV_LINE = '          "${SEMGREP_PYTHON}" -m venv "${venv_dir}"\n';
+  const SOURCE_LINE = '          source "${SELECT_PYTHON}"\n';
+  assert.ok(workflow.includes(VENV_LINE), `${WORKFLOW}: the venv line changed shape`);
+  assert.ok(workflow.includes(SOURCE_LINE), `${WORKFLOW}: the source line changed shape`);
+
+  const mutated = workflow
+    .replace(VENV_LINE, "")
+    .replace(SOURCE_LINE, `${VENV_LINE}${SOURCE_LINE}`);
+  assert.notEqual(mutated, workflow, "the mutation must actually change the workflow");
+  assert.equal(
+    selectorPrecedesVenv(mutated),
+    false,
+    "a venv built before the interpreter is chosen must fail the guard",
+  );
+});
+
+test("the non-lockfile path installs exactly SEMGREP_PIN, never a resolved older release", () => {
+  // Downgrading to fit an old interpreter re-admits CVE-2026-0994: the newest
+  // py3.9-compatible semgrep (1.136.0) pins opentelemetry ~=1.25.0, which caps
+  // protobuf below 5.0, and every protobuf 4.x is affected. This path is not
+  // hash-pinned and its closure is not OSV-scanned, so it would be silent.
+  assert.ok(
+    workflow.includes('--retries 3 "${SEMGREP_PIN}"'),
+    "the fallback must install the exact pin",
+  );
+
+  // Matched as literal substrings rather than a regex alternating the
+  // comparison operators: CodeQL reads such a pattern as an attempted HTML-tag
+  // filter and raises js/bad-tag-filter at HIGH, which blocks the merge.
+  const LOOSE = ["semgrep<", "semgrep>", "semgrep~=", "semgrep!=", 'semgrep=="${'];
+  for (const loose of LOOSE) {
+    assert.ok(
+      !workflow.includes(loose),
+      `${WORKFLOW}: '${loose}' would let pip resolve a semgrep other than the pin`,
+    );
+  }
+});
+
+test("the Linux hash-pinned branch keeps its exact cp312 equality", () => {
+  // Widening this to a `>=` (proposed in issue #480) would route a cp313
+  // interpreter onto the lockfile's cp312-only wheels under
+  // `--only-binary :all:`, with no sdist fallback — the fleet-red the fallback
+  // exists to avoid. The equality is the guard, not the oversight.
+  assert.ok(
+    workflow.includes('[ "${pyver}" = "312" ]'),
+    `${WORKFLOW}: the cp312 test must stay an equality`,
+  );
+  assert.ok(
+    workflow.includes('The `= "312"` below is an EQUALITY on purpose'),
+    "the equality must carry a comment saying why a >= test would be wrong",
+  );
+  assert.ok(
+    workflow.includes("sdist fallback"),
+    "that comment must name the missing sdist fallback as the mechanism",
+  );
+});
+
+test("the floor added no workflow_call input and no new job permission", () => {
+  // A consumer-set semgrep pin would re-open the same un-scanned downgrade
+  // hole operator-side; `enable-sast: false` is the escape hatch. And a new
+  // job-level permission is a COMPILE-TIME break for every caller of this
+  // reusable workflow, not a runtime one.
+  assert.ok(!workflow.includes("semgrep-pin:"), "no semgrep-pin input — see the Story's non-goals");
+  assert.ok(!workflow.includes("python-version:"), "no python-version input — see the Story's non-goals");
+
+  const start = workflow.indexOf("name: Security (secret scan + SAST)");
+  assert.notEqual(start, -1, `${WORKFLOW}: the security job was renamed`);
+  const header = workflow.slice(start, workflow.indexOf("steps:", start));
+  const granted = header
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => l === "contents: read" || l === "actions: write");
+  assert.equal(
+    granted.length,
+    2,
+    "the security job's permissions must remain exactly contents: read + actions: write",
+  );
+  assert.ok(!header.includes("id-token:"), "no new permission was needed for an interpreter floor");
+  assert.ok(!header.includes("packages:"), "no new permission was needed for an interpreter floor");
+});
+
+// ---------------------------------------------------------------------------
+// 6. The hash-pinned path's real preconditions, and an audible fallback (#495)
+// ---------------------------------------------------------------------------
+
+test("the hash-pinned branch tests architecture as well as OS and ABI", () => {
+  // The lockfile was resolved with `--platform manylinux*_x86_64` only, and
+  // PyPI ships a separate `manylinux_2_34_aarch64` semgrep wheel that no entry
+  // covers. On an arm64 Linux runner the OS+ABI test passed and
+  // `--require-hashes --only-binary` hard-failed on a hash mismatch — a red
+  // that reads like a tampered artifact rather than an unsupported arch.
+  const code = sastStepCode();
+  assert.ok(
+    code.includes('[ "${pyver}" = "312" ]'),
+    `${WORKFLOW}: the cp312 test must stay an equality`,
+  );
+  assert.ok(
+    code.includes('[ "${runner_arch}" = "x86_64" ]'),
+    `${WORKFLOW}: the hash-pinned branch must also require x86_64`,
+  );
+  assert.ok(
+    code.includes('runner_arch="$(uname -m)"'),
+    "the architecture must be read from the runner, not assumed",
+  );
+});
+
+test("the lockfile's declared ABI matches the branch's cp equality", () => {
+  // Two spellings of one fact: `3.12` steers the interpreter probe and `312`
+  // gates the install. A bump that moved one and not the other would probe for
+  // an interpreter the install then rejects.
+  const abi = workflow.match(/export SEMGREP_LOCKFILE_ABI='([^']+)'/);
+  assert.ok(abi, `${WORKFLOW}: SEMGREP_LOCKFILE_ABI must be exported for the selector`);
+  assert.equal(
+    abi[1].replace(".", ""),
+    "312",
+    `SEMGREP_LOCKFILE_ABI is ${abi[1]} but the hash-pinned branch installs only on cp312`,
+  );
+});
+
+test("every reason for leaving the hash-pinned path is warned about by name", () => {
+  // The single line this replaced said "Non-Linux runner (or no lockfile)" on
+  // all four, so the two that actually cost the fleet its supply-chain pin — a
+  // rolled interpreter and an unsupported arch — were reported as neither of
+  // them, at log level, on a green job.
+  const code = sastStepCode();
+  const reasons = code.split("\n").filter((l) => l.includes("fallback_reason="));
+  assert.equal(reasons.length, 4, "expected one named reason per precondition");
+
+  for (const [precondition, phrase] of [
+    ["OS", "not Linux"],
+    ["architecture", "not x86_64"],
+    ["interpreter ABI", "not the lockfile's cp312"],
+    ["missing lockfile", "lockfile is missing"],
+  ]) {
+    assert.ok(
+      reasons.some((line) => line.includes(phrase)),
+      `no fallback reason names the ${precondition} precondition (looked for "${phrase}")`,
+    );
+  }
+
+  const warning = code
+    .split("\n")
+    .find((l) => l.includes("::warning::") && l.includes("${fallback_reason}"));
+  assert.ok(
+    warning,
+    "the fallback must emit a ::warning:: carrying the resolved reason, not a log line",
+  );
+  assert.ok(
+    warning.includes("WITHOUT hash-pinning"),
+    "the warning must say what was actually lost",
+  );
+});
+
+test("the SAST exclude list covers every platform side-checkout", () => {
+  // Two directories are materialized from mandrel-platform's own tree —
+  // `_mandrel-platform-sast` (the ruleset) and `_mandrel-platform-semgrep`
+  // (the lockfile + selector). Only the first was ever excluded, so platform
+  // source could enter a caller's finding set. The glob covers the next one
+  // too.
+  const code = sastStepCode();
+  assert.ok(
+    code.includes("--exclude '_mandrel-platform-*'"),
+    `${WORKFLOW}: the exclude list must cover _mandrel-platform-* , not one checkout by name`,
+  );
+
+  // Both checkout paths must fall under the glob, or the exclude is cosmetic.
+  for (const path of ["_mandrel-platform-sast", "_mandrel-platform-semgrep"]) {
+    assert.ok(
+      workflow.includes(`path: ${path}`),
+      `${WORKFLOW}: expected a side-checkout at ${path}`,
+    );
+    assert.ok(path.startsWith("_mandrel-platform-"), `${path} is not covered by the glob`);
+  }
+});
+
+// ---------------------------------------------------------------------------
+// 7. The rules updater shares the selector, and counts its own hashes (#495)
+// ---------------------------------------------------------------------------
+
+test("the rules updater builds its venv from the shared interpreter selector", () => {
+  const updater = readFileSync(UPDATER, "utf8");
+  assert.ok(
+    updater.includes("select-semgrep-python.sh"),
+    `${UPDATER}: the venv interpreter must come from the same selector the SAST step uses`,
+  );
+  assert.ok(
+    !/spawnSync\("python3"/.test(updater),
+    `${UPDATER}: a hard-coded python3 installs nothing on a macOS system interpreter`,
+  );
+});
+
+test("the rules updater no longer installs setuptools", () => {
+  // It was there only because semgrep 1.97.0's transitive
+  // opentelemetry-instrumentation 0.46b0 imported pkg_resources at load.
+  // 0.58b0 does not, and 80.9.0 — the last release shipping pkg_resources —
+  // carries its own advisories.
+  const updater = readFileSync(UPDATER, "utf8");
+  assert.ok(
+    !/["']setuptools["']/.test(updater),
+    `${UPDATER}: setuptools must not be reinstalled into the vendoring venv`,
+  );
+});
+
+test("the SEMGREP_HASHES comment states the artifact count it actually carries", () => {
+  // The comment read "the four platform wheels + the sdist" while the array
+  // held eight. A reader checking whether the hash set is complete is reading
+  // the comment, so a stale count is a supply-chain claim that is not true.
+  const updater = readFileSync(UPDATER, "utf8");
+  const version = REQS.get("semgrep");
+
+  const mapStart = updater.indexOf("const SEMGREP_HASHES = {");
+  assert.notEqual(mapStart, -1, `${UPDATER}: SEMGREP_HASHES not found`);
+  const entryStart = updater.indexOf(`"${version}": [`, mapStart);
+  assert.notEqual(entryStart, -1, `${UPDATER}: SEMGREP_HASHES has no entry for ${version}`);
+  const entry = updater.slice(entryStart, updater.indexOf("],", entryStart));
+  const recorded = entry.split("sha256:").length - 1;
+  assert.ok(recorded > 0, `${UPDATER}: the ${version} entry carries no hashes`);
+
+  const comment = updater.slice(0, mapStart);
+  const claimed = comment.match(/(\d+) artifacts/);
+  assert.ok(
+    claimed,
+    `${UPDATER}: the SEMGREP_HASHES comment must state how many artifacts it pins`,
+  );
+  assert.equal(
+    Number.parseInt(claimed[1], 10),
+    recorded,
+    `the comment claims ${claimed[1]} artifacts but the ${version} entry pins ${recorded}`,
+  );
+});
+
+// ---------------------------------------------------------------------------
+// 8. The documented behaviour is the shipped behaviour (#495)
+// ---------------------------------------------------------------------------
+
+test("the SAST docs describe the ABI-first probe order and the fallback warning", () => {
+  // A consumer debugging a lost hash pin reads this section, not the workflow.
+  const docs = readFileSync(DOCS, "utf8");
+  const start = docs.indexOf("> **Python interpreter floor.**");
+  assert.notEqual(start, -1, `${DOCS}: the SAST interpreter section was renamed or removed`);
+  const section = docs.slice(start, docs.indexOf("#### SAST ruleset provenance", start));
+
+  assert.match(section, /SEMGREP_LOCKFILE_ABI|lockfile.{0,40}ABI/i, "the ABI input must be named");
+  assert.match(section, /probed first|first on Linux/i, "the probe order must be stated");
+  assert.match(section, /::warning::/, "the fallback warning must be documented");
+  assert.match(section, /x86_64/, "the architecture precondition must be documented");
+});

package/scripts/check-workflow-lint-tier.test.mjs

@@ -65,6 +65,44 @@ export function jobKeys(block) {
     .map((l) => l.trim().split(":")[0]);
 }
 
+/**
+ * The composite's single `run:` block — everything after its `run: |` line.
+ * The infra-failure assertions below are about SHELL CONTROL FLOW, so they
+ * must not be able to match the action's header comments, which describe that
+ * flow in prose using the same words.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function runBlock(text) {
+  const marker = "\n      run: |\n";
+  const start = text.indexOf(marker);
+  assert.notEqual(start, -1, "the composite's run: block was not found");
+  const block = text.slice(start + marker.length);
+  assert.ok(block.includes("set -euo pipefail"), "run: block did not resolve to the script");
+  return block;
+}
+
+/**
+ * The body of one shell function defined at the run-block's own indent.
+ * Scoped like `jobBlock`: the point is to assert what `infra_fail` does, not
+ * that the two words appear somewhere in a 300-line file.
+ *
+ * @param {string} run @param {string} name
+ * @returns {string}
+ */
+export function shellFunction(run, name) {
+  const lines = run.split(/\r?\n/);
+  const start = lines.findIndex((l) => l.trim() === `${name}() {`);
+  assert.notEqual(start, -1, `shell function '${name}' not defined`);
+  const body = [];
+  for (let i = start + 1; i < lines.length; i += 1) {
+    if (lines[i].trim() === "}") return body.join("\n");
+    body.push(lines[i]);
+  }
+  assert.fail(`shell function '${name}' is unterminated`);
+}
+
 /**
  * The block declaring one composite-action input. Anchored to a line start
  * because the action's header carries USAGE COMMENTS that contain the same
@@ -322,3 +360,141 @@ test("the docs explain the advisory posture, the dial, shellcheck and provenance
   assert.match(section, /checksum/i);
   assert.match(section, /no checksums file/i, "the zizmor provenance caveat must be recorded");
 });
+
+// ---------------------------------------------------------------------------
+// Infrastructure failure routes to the gate, not to `exit 1` (Story #496, AC-2)
+// ---------------------------------------------------------------------------
+//
+// Before #496 a release-CDN blip on either binary `exit 1`-ed inside this
+// inline bash BEFORE the gate script was ever invoked, so the enforcement dial
+// the gate owns could not see it: an advisory tier reddened every consumer's
+// required check on someone else's outage. These assertions pin the routing —
+// the behaviour on the other side of it is unit-tested end-to-end in
+// `workflow-lint-gate.test.mjs`, which runs the real gate.
+
+test("the gate is the ONE exit from this step — every path funnels through it", () => {
+  const run = runBlock(ACTION);
+  assert.equal(
+    run.split("workflow-lint-gate.mjs").length - 1,
+    1,
+    "the gate must be invoked from exactly one place (`run_gate`), or the infra " +
+      "path and the normal path can drift into disagreeing about the dial",
+  );
+  const gate = shellFunction(run, "run_gate");
+  assert.match(
+    gate,
+    /WORKFLOW_LINT_INFRA_FAILURE="\$\{1:-\}"/,
+    "the reason travels to the gate as an env var, empty on the normal path",
+  );
+  assert.match(gate, /WORKFLOW_LINT_ENFORCE="\$\{WORKFLOW_LINT_ENFORCE\}"/);
+  assert.match(gate, /node "\$\{ACTION_PATH\}\/workflow-lint-gate\.mjs"/);
+  assert.match(run, /^\s*run_gate ""$/m, "the normal path still invokes the gate");
+});
+
+test("infra_fail writes empty reports and hands the reason to the gate", () => {
+  const body = shellFunction(runBlock(ACTION), "infra_fail");
+  assert.match(body, /echo "\[\]" > "\$\{al_report\}"/);
+  assert.match(body, /echo "\[\]" > "\$\{zz_report\}"/);
+  assert.match(body, /run_gate "\$1"/, "the failure reason is forwarded, not swallowed");
+  assert.match(
+    body,
+    /exit "\$infra_code"/,
+    "the step's exit code is the GATE's verdict, not a hard-coded 1",
+  );
+});
+
+test("the download branches route to infra_fail rather than exiting 1", () => {
+  const run = runBlock(ACTION);
+  // curl's failure must be CAPTURED — an unguarded curl under `set -e` aborts
+  // the step before any of this routing can run.
+  for (const varName of ["al_curl", "zz_curl"]) {
+    assert.ok(run.includes(`${varName}=$?`), `${varName} does not capture curl's exit code`);
+    assert.ok(
+      run.includes(`if [ "$${varName}" -ne 0 ]; then`),
+      `${varName} is captured but never branched on`,
+    );
+  }
+  assert.equal(
+    run.split('infra_fail "download-failed:').length - 1,
+    2,
+    "both downloads (actionlint and zizmor) must route to infra_fail",
+  );
+});
+
+test("the checksum-mismatch branches route to infra_fail rather than exiting 1", () => {
+  const run = runBlock(ACTION);
+  assert.equal(
+    run.split('infra_fail "checksum-mismatch:').length - 1,
+    2,
+    "both checksum comparisons must route to infra_fail",
+  );
+  // Trust is unchanged: a mismatch still never reaches extract/execute.
+  const mismatch = run.slice(run.indexOf('infra_fail "checksum-mismatch: actionlint'));
+  assert.ok(
+    mismatch.indexOf("tar -xzf") > 0,
+    "the mismatch branch must precede extraction — an unverified archive is never opened",
+  );
+});
+
+test("an unmapped platform routes to infra_fail from all four sites", () => {
+  const run = runBlock(ACTION);
+  assert.equal(
+    run.split('infra_fail "unmapped-platform:').length - 1,
+    4,
+    "unsupported OS, unsupported arch, and the two unmapped checksum slugs",
+  );
+});
+
+test("no infrastructure path exits 1 directly any more", () => {
+  const run = runBlock(ACTION);
+  const hardExits = run
+    .split(/\r?\n/)
+    .filter((l) => l.trim() === "exit 1" || l.trim().endsWith("; exit 1 ;;"));
+  assert.deepEqual(
+    hardExits,
+    [],
+    "a bare `exit 1` here bypasses the gate's dial entirely, which is the defect " +
+      "Story #496 removed. Route the failure through infra_fail instead.",
+  );
+});
+
+test("a genuine TOOL failure still exits non-zero regardless of the dial", () => {
+  // The split matters: a linter that RAN and crashed is about the caller's
+  // tree, not about a third-party CDN, so it is red either way.
+  const run = runBlock(ACTION);
+  assert.match(run, /exit "\$al_code"/);
+  assert.match(run, /exit "\$zz_code"/);
+});
+
+// ---------------------------------------------------------------------------
+// The posture is documented on both surfaces (Story #496, AC-3)
+// ---------------------------------------------------------------------------
+
+test("the enforce input describes the advisory infra-failure posture", () => {
+  const desc = actionInput(ACTION, "enforce").replace(/\s+/g, " ");
+  assert.match(desc, /INFRASTRUCTURE FAILURES follow this same dial/);
+  assert.match(desc, /exits 0 while the tier is advisory/);
+  assert.match(
+    desc,
+    /TOOL failure/,
+    "the description must still name the class that is red regardless",
+  );
+});
+
+test("the docs no longer claim infrastructure failures always fail the tier", () => {
+  assert.ok(
+    !/always fails? the tier/i.test(DOCS),
+    "the retired sentence (download/checksum/tool failures always fail the tier) " +
+      "is now wrong for two of those three classes",
+  );
+  const start = DOCS.indexOf("### Workflow lint tier (`enable-workflow-lint`)");
+  assert.notEqual(start, -1);
+  const section = DOCS.slice(start, start + 9000);
+  assert.match(section, /infrastructure failure/i);
+  assert.match(
+    section,
+    /exits 0 while the tier\s+is advisory/,
+    "the section must state the advisory-until-enforced behaviour explicitly",
+  );
+  assert.match(section, /never extracted or executed/, "the trust caveat must survive");
+});

package/scripts/check-workflow-portability.mjs

@@ -48,8 +48,11 @@
  *      are no logs, and `gh pr checks` reports `pending 0`, indistinguishable
  *      from a busy fleet. Normalize to
  *      `fromJSON(startsWith(inputs.runner, '[') && inputs.runner ||
- *      format('"{0}"', inputs.runner))`, which accepts both documented
- *      shapes. (Caused #419 / v1.5.0; behaviour is covered by
+ *      format('"{0}"', inputs.runner || 'ubuntu-latest'))`, which accepts both
+ *      documented shapes and lands an EMPTY value on the default label rather
+ *      than on `""` — a `default:` fires only when the key is absent, so an
+ *      empty-but-present value reaches the site and would queue forever too
+ *      (#493). (Caused #419 / v1.5.0; behaviour is covered by
  *      check-runner-runs-on.test.mjs, which evaluates the real expression
  *      rather than matching its spelling.)
  *
@@ -301,7 +304,7 @@ export function checkWorkflowContent(content) {
         `JSON-encoded label-array string resolves to ONE unmatchable label ` +
         `name and the job queues until the 24-hour timeout, silently. ` +
         `Normalize it: \`fromJSON(startsWith(inputs.runner, '[') && ` +
-        `inputs.runner || format('"{0}"', inputs.runner))\`.`,
+        `inputs.runner || format('"{0}"', inputs.runner || 'ubuntu-latest'))\`.`,
     });
   });
 

package/scripts/check-workflow-portability.test.mjs

@@ -223,7 +223,7 @@ function runnerWorkflow(value) {
 
 const NORMALIZED =
   "${{ fromJSON(startsWith(inputs.runner, '[') && inputs.runner " +
-  "|| format('\"{0}\"', inputs.runner)) }}";
+  "|| format('\"{0}\"', inputs.runner || 'ubuntu-latest')) }}";
 
 test("Rule 4: a raw `runs-on: ${{ inputs.runner }}` is a violation", () => {
   const violations = checkWorkflowContent(runnerWorkflow("${{ inputs.runner }}"));