mandrel-platform 1.13.0 → 1.13.2

package/scripts/check-action-download-retries.mjs

@@ -25,14 +25,38 @@
  *
  * WHAT COUNTS AS A DOWNLOAD
  * -------------------------
- * A `curl` invocation that writes a fetched artifact to a file — `-o <path>` or
- * `--output <path>`. Deliberately NOT a download, and so not flagged:
- *   • a `curl` with no output flag (a status probe, a POST);
+ * Any fetch that lands in a file, in every spelling a shell author reaches for
+ * — narrowing the scope to one spelling is how a real download escapes the
+ * guard. In scope:
+ *   • `curl -o <path>` / `curl --output <path>` / `curl --output=<path>`;
+ *   • a combined curl short group whose value-taking tail is the output flag,
+ *     e.g. `curl -sSLo <path>` — the same command, written shorter;
+ *   • `curl -O` / `curl --remote-name`, which name the file from the URL
+ *     instead of taking a path (and so may sit anywhere in a short group,
+ *     `-fsSLO` included, because they take no value);
+ *   • `wget -O <path>` / `wget --output-document <path>` — reported against
+ *     curl's flag spelling below, deliberately: the first-party fetches are
+ *     all curl, and a new wget one should join them rather than invent a
+ *     second resilience contract.
+ * Deliberately NOT a download, and so not flagged:
+ *   • a `curl` with no output flag at all (a status probe, a POST, a fetch
+ *     piped straight into another command);
+ *   • a write to stdout — `-o -`, `--output -`, and wget's `-O -`. `-O` is the
+ *     two commands' false friend: curl's takes no argument (so `curl -O -`
+ *     fetches the URL `-`), while wget's is the output path;
  *   • `-o /dev/null`, which is a reachability/status check, not an asset fetch
  *     (`pr-quality.yml`'s fail-fast cancellation POST is exactly this shape).
  * Retrying a POST is a different decision with different safety, and this lint
  * deliberately does not make it.
  *
+ * HOW FLAGS ARE MATCHED
+ * ---------------------
+ * As whole shell words, never as substrings: `--retry-connrefused` does not
+ * satisfy `--retry`, and a flag sitting inside a trailing `#` comment does not
+ * count. A `#` opens a comment only at start of line or after whitespace and
+ * outside quotes, so `$#`, `${#arr[@]}` and a fragment `#` inside a quoted URL
+ * are left alone. Every pattern here is a literal regex.
+ *
  * SCOPE: `.github/actions/**` action manifests. Exit 0 when clean, 1 when any
  * download is missing a required flag (prints file:line and the missing set).
  */
@@ -64,6 +88,21 @@ export const REQUIRED_FLAGS = Object.freeze([
   }),
 ]);
 
+/** `curl` invoked as a command — after whitespace or a shell operator. */
+const CURL_COMMAND = /(^|[\s;&|(])curl(\s|$)/;
+/** `wget` invoked as a command — same boundary rule. */
+const WGET_COMMAND = /(^|[\s;&|(])wget(\s|$)/;
+/** A combined short-option group: one `-` followed by letters only. */
+const SHORT_GROUP = /^-[A-Za-z]+$/;
+/** Quote characters wrapping a word, stripped so a path compares as itself. */
+const LEADING_QUOTES = /^['"]+/;
+const TRAILING_QUOTES = /['"]+$/;
+/** Output targets that are not a fetched asset on disk. */
+const STDOUT_TARGETS = new Set(['-', '/dev/null']);
+/** Long output flags in their `--flag=value` spelling. */
+const CURL_OUTPUT_EQ = '--output=';
+const WGET_OUTPUT_EQ = '--output-document=';
+
 /**
  * Pure: fold shell line-continuations so a `curl` split across several lines is
  * linted as the single command it is. The logical line keeps the 1-based number
@@ -95,18 +134,122 @@ export function collapseContinuations(source) {
 }
 
 /**
- * Pure: does this logical line invoke `curl` to write a fetched artifact to a
- * real file? See the header for what is deliberately excluded.
+ * Pure: drop a shell comment and everything after it.
+ *
+ * `#` only opens a comment at the start of the line or after whitespace, and
+ * only outside quotes — which is what keeps `$#`, `${#arr[@]}` and the fragment
+ * in `"https://host/p#frag"` from truncating the command that carries them.
+ *
+ * @param {string} text
+ * @returns {string}
+ */
+export function stripShellComment(text) {
+  let quote = null;
+  for (let i = 0; i < text.length; i += 1) {
+    const char = text[i];
+    if (char === '\\' && quote !== "'") {
+      i += 1;
+      continue;
+    }
+    if (quote !== null) {
+      if (char === quote) quote = null;
+      continue;
+    }
+    if (char === '"' || char === "'") {
+      quote = char;
+      continue;
+    }
+    const opensComment =
+      char === '#' && (i === 0 || text[i - 1] === ' ' || text[i - 1] === '\t');
+    if (opensComment) return text.slice(0, i);
+  }
+  return text;
+}
+
+/**
+ * Pure: the shell words of a logical line — comment dropped, split on
+ * whitespace, wrapping quotes removed so `"-"` compares equal to `-`.
+ *
+ * @param {string} text
+ * @returns {string[]}
+ */
+export function shellWords(text) {
+  return stripShellComment(text)
+    .split(/\s+/)
+    .filter((word) => word.length > 0)
+    .map((word) => word.replace(LEADING_QUOTES, '').replace(TRAILING_QUOTES, ''));
+}
+
+/**
+ * Pure: does this curl invocation write its body to a real file? See the
+ * header for the spellings in scope and the ones deliberately excluded.
+ *
+ * @param {string[]} words
+ * @returns {boolean}
+ */
+function curlWritesFile(words) {
+  for (let i = 0; i < words.length; i += 1) {
+    const word = words[i];
+    const shortGroup = SHORT_GROUP.test(word);
+    // `-O` takes no value, so it may sit anywhere in a group (`-fsSLO`).
+    if (word === '--remote-name' || (shortGroup && word.includes('O'))) return true;
+    if (word.startsWith(CURL_OUTPUT_EQ)) {
+      return !STDOUT_TARGETS.has(word.slice(CURL_OUTPUT_EQ.length));
+    }
+    // `-o` takes a value, so in a group it must be the tail: `-sSLo <path>`.
+    if (word === '--output' || (shortGroup && word.endsWith('o'))) {
+      return !STDOUT_TARGETS.has(words[i + 1] ?? '-');
+    }
+  }
+  return false;
+}
+
+/**
+ * Pure: does this wget invocation write its body to a real file? Unlike curl,
+ * wget's `-O` IS the output path — `wget -O - "$url"` is a stdout pipe.
+ *
+ * @param {string[]} words
+ * @returns {boolean}
+ */
+function wgetWritesFile(words) {
+  for (let i = 0; i < words.length; i += 1) {
+    const word = words[i];
+    if (word.startsWith(WGET_OUTPUT_EQ)) {
+      return !STDOUT_TARGETS.has(word.slice(WGET_OUTPUT_EQ.length));
+    }
+    if (word === '-O' || word === '--output-document') {
+      return !STDOUT_TARGETS.has(words[i + 1] ?? '-');
+    }
+  }
+  return false;
+}
+
+/**
+ * Pure: does this logical line fetch an artifact into a file? See the header
+ * for every spelling in scope and for what is deliberately excluded.
  *
  * @param {string} text
  * @returns {boolean}
  */
 export function isAssetDownload(text) {
-  if (!/(^|[\s;&|(])curl(\s|$)/.test(text)) return false;
-  const output = text.match(/(?:^|\s)(?:-o|--output)\s+(\S+)/);
-  if (!output) return false;
-  // `-o /dev/null` is a status probe, not an asset fetch.
-  return !/^["']?\/dev\/null["']?$/.test(output[1]);
+  const command = stripShellComment(text);
+  const words = shellWords(command);
+  if (CURL_COMMAND.test(command)) return curlWritesFile(words);
+  if (WGET_COMMAND.test(command)) return wgetWritesFile(words);
+  return false;
+}
+
+/**
+ * Pure: is `flag` present as its own argument — on its own or as `flag=value`?
+ * Substring matching is what let `--retry-connrefused` satisfy `--retry`.
+ *
+ * @param {string[]} words
+ * @param {string} flag
+ * @returns {boolean}
+ */
+function hasFlag(words, flag) {
+  const assigned = `${flag}=`;
+  return words.some((word) => word === flag || word.startsWith(assigned));
 }
 
 /**
@@ -116,7 +259,8 @@ export function isAssetDownload(text) {
  * @returns {string[]}
  */
 export function missingFlags(text) {
-  return REQUIRED_FLAGS.filter(({ flag }) => !text.includes(flag)).map(
+  const words = shellWords(text);
+  return REQUIRED_FLAGS.filter(({ flag }) => !hasFlag(words, flag)).map(
     ({ flag }) => flag,
   );
 }

package/scripts/check-action-download-retries.test.mjs

@@ -1,4 +1,4 @@
-// Unit coverage for the asset-download retry lint (Story #446).
+// Unit coverage for the asset-download retry lint (Story #446, tightened in #490).
 //
 // The claim worth pinning is that this guard FAILS on the defect it exists to
 // catch. A lint only ever asserted against a passing tree is indistinguishable
@@ -6,6 +6,11 @@
 // this repo has been bitten by before, so every rejection case below feeds the
 // checker a fixture it must refuse.
 //
+// Story #490 added the second half of that claim: a guard that can be SATISFIED
+// without the invariant does not guard it either. `--retry-connrefused` used to
+// satisfy `--retry` by substring, a flag inside a `#` comment counted, and four
+// of the five ways to spell a download were outside the checker's scope.
+//
 // Run: node --test scripts/check-action-download-retries.test.mjs
 
 import { test } from "node:test";
@@ -19,6 +24,8 @@ import {
   isAssetDownload,
   lintSource,
   missingFlags,
+  shellWords,
+  stripShellComment,
 } from "./check-action-download-retries.mjs";
 
 /** The exact shape that failed run 34133838332. */
@@ -38,6 +45,9 @@ const HARDENED_DOWNLOAD = BARE_DOWNLOAD.replace(
   "curl -fsSL --retry 3 --retry-connrefused --max-time 300 ",
 );
 
+/** Every required flag, in table order — the full-miss expectation. */
+const ALL_REQUIRED = REQUIRED_FLAGS.map(({ flag }) => flag);
+
 // ---------------------------------------------------------------------------
 // The guard must REJECT — the case that makes it worth having
 // ---------------------------------------------------------------------------
@@ -66,6 +76,141 @@ test("a download carrying only SOME required flags is still rejected", () => {
   assert.deepEqual(finding.missing, ["--retry-connrefused", "--max-time"]);
 });
 
+// ---------------------------------------------------------------------------
+// Flags are whole words, not substrings (Story #490 / AC-1)
+// ---------------------------------------------------------------------------
+
+test("a sibling flag does not satisfy the flag it contains", () => {
+  // `--retry-connrefused` contains `--retry`, which is exactly how a download
+  // with no retry budget at all used to pass this lint.
+  assert.deepEqual(
+    missingFlags('curl -fsSL --retry-connrefused --max-time 300 "$u" -o x'),
+    ["--retry"],
+  );
+  const [finding] = lintSource(
+    "action.yml",
+    BARE_DOWNLOAD.replace(
+      "curl -fsSL ",
+      "curl -fsSL --retry-connrefused --max-time 300 ",
+    ),
+  );
+  assert.deepEqual(finding.missing, ["--retry"], "the lint reports it too");
+});
+
+test("a flag is present as its own word or as `flag=value`", () => {
+  assert.deepEqual(
+    missingFlags('curl --retry=3 --retry-connrefused --max-time=300 -o x "$u"'),
+    [],
+    "curl's `--flag=value` spelling counts",
+  );
+  assert.deepEqual(
+    missingFlags('curl --retry-max-time 60 -o x "$u"'),
+    ALL_REQUIRED,
+    "a longer flag that merely starts with a required one satisfies nothing",
+  );
+});
+
+// ---------------------------------------------------------------------------
+// A `#` comment hides nothing, and shell `#` is not a comment (AC-2, AC-4)
+// ---------------------------------------------------------------------------
+
+test("a flag inside a trailing comment does not count", () => {
+  assert.deepEqual(
+    missingFlags('curl -fsSL -o x "$u"  # --retry 3 --retry-connrefused --max-time 300'),
+    ALL_REQUIRED,
+  );
+  assert.deepEqual(
+    missingFlags("# curl --retry 3 --retry-connrefused --max-time 300 -o x"),
+    ALL_REQUIRED,
+    "a whole-line comment carries no flags either",
+  );
+});
+
+test("a `#` inside a quoted URL does not truncate the command", () => {
+  assert.deepEqual(
+    missingFlags(
+      'curl -o x "https://host/p#frag" --retry 3 --retry-connrefused --max-time 300',
+    ),
+    [],
+    "flags after the fragment are still matched",
+  );
+  assert.equal(
+    isAssetDownload('curl -fsSL "https://host/p#frag" -o "$f"'),
+    true,
+    "the fragment does not hide the output flag either",
+  );
+});
+
+test("shell `#` expansions are not comments", () => {
+  assert.deepEqual(
+    missingFlags(
+      'curl "${#arr[@]}" --retry 3 --retry-connrefused --max-time 300 -o x "$u"',
+    ),
+    [],
+    "`${#arr[@]}` before the flags leaves them visible",
+  );
+  assert.equal(stripShellComment('echo "$#" --retry'), 'echo "$#" --retry');
+  assert.equal(stripShellComment("len=${#arr[@]} --retry"), "len=${#arr[@]} --retry");
+  assert.equal(stripShellComment("curl -o x \\# --retry"), "curl -o x \\# --retry");
+});
+
+test("stripShellComment cuts at the first real comment", () => {
+  assert.equal(stripShellComment("curl -o x # note"), "curl -o x ");
+  assert.equal(stripShellComment("#note"), "");
+  assert.equal(stripShellComment("curl -o x\t# note"), "curl -o x\t");
+  assert.equal(stripShellComment("curl -o x"), "curl -o x");
+  assert.equal(stripShellComment("echo 'a # b' # note"), "echo 'a # b' ");
+});
+
+test("shellWords splits on whitespace and unwraps quoting", () => {
+  assert.deepEqual(shellWords('  curl -o "$f" "$u" # x'), ["curl", "-o", "$f", "$u"]);
+  assert.deepEqual(shellWords('curl -o "-"'), ["curl", "-o", "-"]);
+  assert.deepEqual(shellWords(""), []);
+});
+
+// ---------------------------------------------------------------------------
+// Every download spelling is in scope (AC-3)
+// ---------------------------------------------------------------------------
+
+test("every spelling that writes a fetched artifact to a file is a download", () => {
+  const downloads = [
+    'curl -fsSL "$u" -o "${tmp}/${asset}"',
+    'curl -sSLo "$f" "$u"',
+    'curl --output "$f" "$u"',
+    'curl --output="$f" "$u"',
+    'curl -fsSL -O "$u"',
+    'curl -fsSLO "$u"',
+    'curl --remote-name "$u"',
+    'wget -O x "$u"',
+    'wget --output-document x "$u"',
+    'wget --output-document=x "$u"',
+  ];
+  for (const line of downloads) {
+    assert.equal(isAssetDownload(line), true, `${line} is a download`);
+  }
+});
+
+test("a fetch that never lands in a file is not a download", () => {
+  const notDownloads = [
+    'curl -o - "$u"',
+    'curl --output - "$u"',
+    'curl -sSLo - "$u"',
+    'wget -O - "$u"',
+    'curl -fsSL "$u" | tar -xz',
+    'curl -fsSL "https://example.test/health"',
+    'curl -sS -o /dev/null -w "%{http_code}" -X POST "$api"',
+  ];
+  for (const line of notDownloads) {
+    assert.equal(isAssetDownload(line), false, `${line} is not a download`);
+  }
+});
+
+test("a wget download is held to the same contract", () => {
+  const [finding] = lintSource("action.yml", '        wget -O "$f" "$u"');
+  assert.ok(finding, "an unhardened wget fetch is caught, not silently skipped");
+  assert.deepEqual(finding.missing, ALL_REQUIRED);
+});
+
 // ---------------------------------------------------------------------------
 // The guard must ACCEPT — no false positives on the shapes that are fine
 // ---------------------------------------------------------------------------
@@ -83,13 +228,18 @@ test("a curl that is not an asset download is not a violation", () => {
     '        curl -fsSL "https://example.test/health"',
   ].join("\n");
   assert.deepEqual(lintSource("workflow.yml", probes), []);
-  assert.equal(isAssetDownload(probes.split("\n")[0]), false, "-o /dev/null is a probe");
   assert.equal(isAssetDownload(probes.split("\n")[1]), false, "no -o is not a download");
+  assert.equal(
+    isAssetDownload('        curl -sS -o /dev/null -w "%{http_code}" -X POST "$api"'),
+    false,
+    "-o /dev/null is a probe",
+  );
 });
 
 test("a line that merely mentions curl in prose is not a download", () => {
-  assert.equal(isAssetDownload("        # predecessor used `curl --retry 3`"), false);
+  assert.equal(isAssetDownload("        # predecessor used `curl --retry 3` -o x"), false);
   assert.equal(isAssetDownload("        echo curling the asset"), false);
+  assert.equal(isAssetDownload("        echo wgetting the asset -O x"), false);
 });
 
 // ---------------------------------------------------------------------------
@@ -139,6 +289,21 @@ test("missingFlags reports in table order and REQUIRED_FLAGS each carry a why",
 test("every first-party action manifest in this repo passes", () => {
   const manifests = findActionManifests();
   assert.ok(manifests.length > 0, "the action surface is discoverable");
+  assert.ok(
+    manifests.some((p) => p.includes("gitleaks-scan")),
+    "the action whose 504 motivated this lint is in scope",
+  );
   const findings = manifests.flatMap((p) => lintSource(p, readFileSync(p, "utf8")));
   assert.deepEqual(findings, [], "no action ships an unhardened asset download");
 });
+
+test("the shipped downloads are still recognised as downloads", () => {
+  // The tightening must not narrow the lint into vacuous success: the live
+  // manifests must still present downloads for it to have judged.
+  const seen = findActionManifests().flatMap((p) =>
+    collapseContinuations(readFileSync(p, "utf8"))
+      .map(({ text }) => text)
+      .filter((text) => isAssetDownload(text)),
+  );
+  assert.ok(seen.length >= 4, `expected the tree's asset downloads, saw ${seen.length}`);
+});

package/scripts/check-advisory-scan-setup.test.mjs

@@ -18,6 +18,14 @@
  * because the defect class here is an expression that reads correctly and
  * evaluates wrong.
  *
+ * The install-free assertion is JOB-wide (Story #494). It used to slice the
+ * "Setup Node.js (install-free)" step alone, which proves nothing: the step
+ * that provisions Node was never the one likely to grow an install. What the
+ * path promises is that NOTHING in the job installs when `setup: node` is
+ * selected, so the check enumerates every step of the job, keeps the ones
+ * whose `if:` guard actually selects them under that input, and asserts the
+ * absence across the set.
+ *
  * Run: node --test scripts/check-advisory-scan-setup.test.mjs
  */
 
@@ -59,11 +67,114 @@ function stepByName(text, name) {
   return out.join("\n");
 }
 
+/** Strip a `${{ … }}` wrapper, leaving the bare Actions expression. */
+function bareExpression(raw) {
+  return raw.trim().replace(/^\$\{\{/, "").replace(/\}\}$/, "").trim();
+}
+
 /** The `${{ … }}`-free body of a step's `if:` condition. */
 function ifExpression(step, name) {
   const m = step.match(/^\s*if:\s*(.+)$/m);
   assert.ok(m, `step "${name}" has no \`if:\` guard`);
-  return m[1].trim().replace(/^\$\{\{/, "").replace(/\}\}$/, "").trim();
+  return bareExpression(m[1]);
+}
+
+/**
+ * The line span of one top-level job — from its `  <id>:` header to the next
+ * key at that indent, trailing blank lines excluded. A plain line comparison
+ * rather than a regex built around `job`: a dynamically-constructed RegExp is
+ * a SAST finding, and a job header is an exact line anyway.
+ */
+function jobRange(text, job) {
+  const lines = text.split("\n");
+  const start = lines.findIndex((l) => l.trimEnd() === `  ${job}:`);
+  assert.notEqual(start, -1, `${ADVISORY}: job '${job}' not found`);
+  let end = lines.length;
+  for (let i = start + 1; i < lines.length; i++) {
+    if (/^ {2}\S/.test(lines[i])) {
+      end = i;
+      break;
+    }
+  }
+  while (end > start + 1 && lines[end - 1].trim() === "") end--;
+  return { lines, start, end };
+}
+
+/**
+ * Every step of a job, in order, as its own block of text. Steps are split on
+ * the `- ` bullets under `steps:` at the bullet's own indent, so a nested
+ * `with:` / `env:` mapping stays with the step that owns it.
+ */
+function jobSteps(text, job) {
+  const { lines, start, end } = jobRange(text, job);
+  const body = lines.slice(start + 1, end);
+  const stepsIdx = body.findIndex((l) => l.trim() === "steps:");
+  assert.notEqual(stepsIdx, -1, `${ADVISORY}: job '${job}' declares no \`steps:\``);
+  const rest = body.slice(stepsIdx + 1);
+  const first = rest.findIndex((l) => /^\s*-\s/.test(l));
+  assert.notEqual(first, -1, `${ADVISORY}: job '${job}' declares no steps`);
+  const indent = rest[first].match(/^(\s*)/)[1].length;
+  const steps = [];
+  for (const line of rest.slice(first)) {
+    const bullet = /^\s*-\s/.test(line) && line.match(/^(\s*)/)[1].length === indent;
+    if (bullet) steps.push([]);
+    steps[steps.length - 1].push(line);
+  }
+  return steps.map((step) => step.join("\n"));
+}
+
+/** A step's `name:`, else its opening line — for a readable failure message. */
+function stepLabel(step) {
+  const m = step.match(/^\s*(?:-\s*)?name:\s*(.+)$/m);
+  return m ? m[1].trim() : step.split("\n")[0].trim();
+}
+
+/** Whether a step is selected for the run under the given `inputs` context. */
+function runsWhen(step, inputs) {
+  const m = step.match(/^\s*if:\s*(.+)$/m);
+  if (!m) return true;
+  try {
+    return evaluate(bareExpression(m[1]), inputs) === true;
+  } catch {
+    // A guard this evaluator cannot run counts as SELECTED. Fail closed: an
+    // expression nobody can evaluate must never be the reason an install slips
+    // past the check below — at worst it costs a loud failure a human reads.
+    return true;
+  }
+}
+
+// Install commands, matched against the step's YAML with comment-only lines
+// removed: the job's comments discuss `pnpm install` at length, and prose is
+// not a command. Literal patterns, never a built RegExp.
+const INSTALL_COMMANDS = [
+  { label: "pnpm install", pattern: /\bpnpm install\b/ },
+  { label: "npm ci", pattern: /\bnpm ci\b/ },
+  { label: "npm install", pattern: /\bnpm install\b/ },
+  { label: "yarn install", pattern: /\byarn install\b/ },
+];
+
+/** Every step selected by `setup` that runs an install, with what it runs. */
+function installingSteps(text, setup) {
+  return jobSteps(text, JOB)
+    .filter((step) => runsWhen(step, { setup }))
+    .map((step) => ({
+      step: stepLabel(step),
+      commands: INSTALL_COMMANDS.filter(({ pattern }) =>
+        pattern.test(
+          step
+            .split("\n")
+            .filter((l) => !l.trim().startsWith("#"))
+            .join("\n"),
+        ),
+      ).map(({ label }) => label),
+    }))
+    .filter(({ commands }) => commands.length > 0);
+}
+
+/** `text` with one extra step spliced in after the job's last existing step. */
+function withStepAppended(text, job, step) {
+  const { lines, end } = jobRange(text, job);
+  return [...lines.slice(0, end), ...step.split("\n"), ...lines.slice(end)].join("\n");
 }
 
 /** The literal `default:` of the named workflow_call input. */
@@ -80,6 +191,7 @@ function inputDefault(text, name) {
   return assert.fail(`${ADVISORY}: input \`${name}\` has no default`);
 }
 
+const JOB = "advisory-scan";
 const TOOLCHAIN_STEP = "Setup toolchain";
 const NODE_STEP = "Setup Node.js (install-free)";
 const GUARD_STEP = "Validate setup input";
@@ -135,12 +247,54 @@ test("the install-free step pins Node from .nvmrc via a SHA-pinned setup-node",
   );
 });
 
-test("no dependency install runs on the install-free path", () => {
+// ---------------------------------------------------------------------------
+// Story #494 — "install-free" is a property of the JOB, not of one step.
+// ---------------------------------------------------------------------------
+
+test("no dependency install runs ANYWHERE in the job on the install-free path", () => {
   // The whole point of the path: osv-scanner reads lockfiles off disk, and both
   // composites' gate scripts import only node builtins and relative siblings.
-  const step = stepByName(advisory, NODE_STEP);
-  assert.doesNotMatch(step, /pnpm install/, "the install-free path must not install");
-  assert.doesNotMatch(step, /npm ci|npm install/, "the install-free path must not install");
+  // So nothing in the job needs a dependency tree — and the step that
+  // provisions Node was never the step likely to grow an install anyway.
+  assert.deepEqual(
+    installingSteps(advisory, "node"),
+    [],
+    "a step selected by `setup: node` installs dependencies",
+  );
+});
+
+test("the check is job-wide: an install appended after the last step is caught", () => {
+  // The mutation the step-scoped version missed — it sliced the install-free
+  // step alone, so this fixture passed while the path's one promise was broken.
+  const mutated = withStepAppended(
+    advisory,
+    JOB,
+    ["      - name: Restore dependencies", "        run: npm ci"].join("\n"),
+  );
+  assert.deepEqual(installingSteps(mutated, "node"), [
+    { step: "Restore dependencies", commands: ["npm ci"] },
+  ]);
+});
+
+test("an install guarded onto the toolchain path is not charged to the node path", () => {
+  // The other half of the mutation, and the proof that the `if:` guards are
+  // still EVALUATED here rather than grepped: the same appended step is
+  // invisible under `setup: node` and visible under `setup: toolchain`. Drop
+  // the evaluation and this check either flags every guarded install or, if it
+  // ignored guards entirely, would have to ignore unguarded ones too.
+  const mutated = withStepAppended(
+    advisory,
+    JOB,
+    [
+      "      - name: Restore pnpm dependencies",
+      "        if: inputs.setup == 'toolchain'",
+      "        run: pnpm install --frozen-lockfile",
+    ].join("\n"),
+  );
+  assert.deepEqual(installingSteps(mutated, "node"), []);
+  assert.deepEqual(installingSteps(mutated, "toolchain"), [
+    { step: "Restore pnpm dependencies", commands: ["pnpm install"] },
+  ]);
 });
 
 // ---------------------------------------------------------------------------
@@ -222,6 +376,33 @@ test("this repo really is the npm case the caller claims", () => {
   );
 });
 
+// ---------------------------------------------------------------------------
+// Story #494 — the copy-paste path documents the input that decides the job.
+// ---------------------------------------------------------------------------
+
+test("the header's consumer snippet shows `setup:` and names both accepted values", () => {
+  // The snippet is what a consumer copies; an input missing from it is one they
+  // never learn they had. `setup` is the input whose wrong value kills the job
+  // at setup-node before the scan runs — the seven silent weeks above — so the
+  // copy path has to carry it, and has to name the other value it accepts.
+  const header = advisory.split("\nname:")[0];
+  const snippet = header.split("\n").filter((l) => l.startsWith("#"));
+  const withIdx = snippet.findIndex((l) => /^#\s+with:\s*$/.test(l));
+  assert.notEqual(withIdx, -1, `${ADVISORY}: the consumer snippet has no \`with:\` block`);
+  const withBlock = snippet.slice(withIdx).join("\n");
+  assert.match(
+    withBlock,
+    /^#\s+setup:\s*(toolchain|node)\s*$/m,
+    "the consumer snippet must pass `setup:`",
+  );
+  for (const value of ["toolchain", "node"]) {
+    assert.ok(
+      withBlock.includes(value),
+      `the consumer snippet must name the accepted value '${value}'`,
+    );
+  }
+});
+
 // ---------------------------------------------------------------------------
 // AC-8 / AC-9 — the documented contract.
 // ---------------------------------------------------------------------------