mandrel-platform 1.3.0 → 1.4.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "mandrel-platform",
-  "version": "1.3.0",
+  "version": "1.4.1",
   "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.7.0"
+    "mandrel": "^2.31.0"
   },
   "scripts": {
     "typecheck": "node --input-type=module --eval 'process.exit(0)'",

package/scripts/check-first-party-pin-freshness.mjs

@@ -38,6 +38,22 @@
  * <subpath>` names, plus every tracked working-tree file under it, so an added
  * or removed sibling is drift too.
  *
+ * ## Why a subpath can have COMPANIONS (Story #389)
+ *
+ * The subpaths this checker knows are exactly the ones named on `uses:` lines,
+ * which reopens the same blind spot one level up the moment an action's
+ * behaviour moves into a SIBLING DIRECTORY. Story #389 reduced
+ * `.github/actions/osv-track-issue` to a thin preset that executes
+ * `.github/actions/track-issue/track-issue.mjs` — nothing `uses:` the generic
+ * action, so a rewrite of that shared core would leave every `osv-track-issue`
+ * pin reading fresh while the pinned SHA runs the old state machine.
+ *
+ * `COMPANION_SUBPATHS` closes it: a subpath's companions are folded into the
+ * tree comparison and into the drift cache key, so an edit confined to the
+ * shared core marks every call site of every dependent preset stale. The map
+ * is deliberately explicit rather than inferred — a heuristic over `run:`
+ * bodies would both miss indirection and invent false drift.
+ *
  * This checker closes it by classifying every first-party SHA pin into one of
  * two failure classes — deliberately kept distinct, because their remedies
  * differ:
@@ -325,6 +341,33 @@ export function createGit(repoRoot) {
 // Subpath tree comparison
 // ---------------------------------------------------------------------------
 
+/**
+ * Subpaths whose runtime behaviour lives partly in ANOTHER directory that no
+ * `uses:` line names. Each key's companions are compared alongside it, so an
+ * edit confined to a shared core still marks the dependent pins stale.
+ *
+ * Keep this map in step with any preset/core split under `.github/actions/`:
+ * an entry omitted here is a pin that reads fresh while running old code.
+ *
+ * @type {Record<string, string[]>}
+ */
+export const COMPANION_SUBPATHS = {
+  // Story #389 — the preset executes ../track-issue/track-issue.mjs.
+  ".github/actions/osv-track-issue": [".github/actions/track-issue"],
+};
+
+/**
+ * Companion subpaths for a `uses:` subpath (empty when it stands alone).
+ * Trailing slashes are tolerated so `foo/` and `foo` resolve identically.
+ *
+ * @param {string} subpath
+ * @param {Record<string, string[]>} [map]
+ * @returns {string[]}
+ */
+export function companionsFor(subpath, map = COMPANION_SUBPATHS) {
+  return map[String(subpath).replace(/\/+$/, "")] || [];
+}
+
 /** How each drift kind reads in the report. */
 const DRIFT_PHRASE = {
   differs: "differs from the working-tree copy",
@@ -341,15 +384,21 @@ const DRIFT_PHRASE = {
  * since the pinned revision is drift just as much as one whose bytes changed —
  * all three change what the pinned revision actually executes.
  *
+ * `companions` extends the comparison to directories the subpath EXECUTES but
+ * no `uses:` line names (Story #389). They are compared identically: a shared
+ * core that differs at the pinned SHA is exactly as inert as a sibling script.
+ *
  * @param {{lsTree: Function, lsFiles: Function, show: Function}} git
  * @param {string} repoRoot
  * @param {string} sha
  * @param {string} subpath
+ * @param {string[]} [companions]
  * @returns {Array<{path: string, kind: "differs" | "added" | "removed" | "unreadable"}>}
  */
-export function diffSubpathAtSha(git, repoRoot, sha, subpath) {
-  const pinned = new Set(git.lsTree(sha, subpath));
-  const working = new Set(git.lsFiles(subpath));
+export function diffSubpathAtSha(git, repoRoot, sha, subpath, companions = []) {
+  const roots = [subpath, ...companions];
+  const pinned = new Set(roots.flatMap((root) => git.lsTree(sha, root)));
+  const working = new Set(roots.flatMap((root) => git.lsFiles(root)));
   const drift = [];
 
   for (const path of [...new Set([...pinned, ...working])].sort()) {
@@ -384,12 +433,17 @@ export function diffSubpathAtSha(git, repoRoot, sha, subpath) {
  *
  * @param {string} subpath
  * @param {ReturnType<typeof diffSubpathAtSha>} drift
+ * @param {string[]} [companions]
  * @returns {string}
  */
-export function describeDrift(subpath, drift) {
+export function describeDrift(subpath, drift, companions = []) {
   const detail = drift.map((d) => `${d.path} ${DRIFT_PHRASE[d.kind]}`).join("; ");
+  const scope =
+    companions.length > 0
+      ? `${subpath} (and the shared code it executes: ${companions.join(", ")})`
+      : subpath;
   return (
-    `${drift.length} file(s) under ${subpath} lag the pinned SHA — the pinned ` +
+    `${drift.length} file(s) under ${scope} lag the pinned SHA — the pinned ` +
     `revision is what actually runs: ${detail}`
   );
 }
@@ -406,7 +460,11 @@ export function describeDrift(subpath, drift) {
  * `git` is injectable so a caller can drive the classification against a
  * substitute history; it defaults to the real git bound to `opts.cwd`.
  *
- * @param {{cwd?: string, workflowsDir?: string, actionsDir?: string, firstPartyOwner?: string, ref?: string}} opts
+ * `opts.companions` overrides {@link COMPANION_SUBPATHS} — injectable so a
+ * fixture can exercise the shared-core relationship without depending on this
+ * repo's own action layout.
+ *
+ * @param {{cwd?: string, workflowsDir?: string, actionsDir?: string, firstPartyOwner?: string, ref?: string, companions?: Record<string, string[]>}} opts
  * @param {ReturnType<typeof createGit>} [git]
  * @returns {{ok: boolean, fatal: string|null, stale: object[], unreachable: object[], unpinnedRefs: object[], scanned: number, files: string[], headSha: string|null}}
  */
@@ -457,12 +515,15 @@ export function runCheck(opts = {}, git = createGit(resolve(opts.cwd || process.
 
   // Every call site for a subpath must move together, so the same
   // (sha, subpath) pair is compared repeatedly — `setup-toolchain` alone has
-  // five. Resolve each tree once.
+  // five. Resolve each tree once. The companions are part of the key: two
+  // subpaths sharing a core must not collide, and a companion map override
+  // must not read a cache entry computed without it.
+  const companionMap = opts.companions || COMPANION_SUBPATHS;
   const driftCache = new Map();
-  const driftFor = (sha, subpath) => {
-    const key = `${sha}:${subpath}`;
+  const driftFor = (sha, subpath, companions) => {
+    const key = `${sha}:${[subpath, ...companions].join(",")}`;
     if (!driftCache.has(key)) {
-      driftCache.set(key, diffSubpathAtSha(git, repoRoot, sha, subpath));
+      driftCache.set(key, diffSubpathAtSha(git, repoRoot, sha, subpath, companions));
     }
     return driftCache.get(key);
   };
@@ -511,12 +572,13 @@ export function runCheck(opts = {}, git = createGit(resolve(opts.cwd || process.
         continue;
       }
 
-      const drift = driftFor(pin.sha, pin.subpath);
+      const companions = companionsFor(pin.subpath, companionMap);
+      const drift = driftFor(pin.sha, pin.subpath, companions);
       if (drift.length > 0) {
         stale.push({
           ...pin,
           manifest: manifest.path,
-          reason: describeDrift(pin.subpath, drift),
+          reason: describeDrift(pin.subpath, drift, companions),
         });
       }
     }

package/scripts/check-first-party-pin-freshness.test.mjs

@@ -37,8 +37,10 @@ import {
   resolveManifest,
   manifestsMatch,
   diffSubpathAtSha,
+  companionsFor,
   runCheck,
   runCli,
+  COMPANION_SUBPATHS,
 } from "./check-first-party-pin-freshness.mjs";
 
 const OWNER = "test-owner/test-repo";
@@ -390,6 +392,165 @@ test("diffSubpathAtSha: a blob git cannot resolve at the pinned SHA is drift, no
   assert.deepEqual(drift, [{ path, kind: "differs" }]);
 });
 
+// ---------------------------------------------------------------------------
+// Story #389 — a subpath's COMPANIONS are compared alongside it
+//
+// The subpaths this checker knows are exactly the ones named on `uses:` lines,
+// so the moment an action's behaviour moves into a sibling DIRECTORY the
+// Story #379 blind spot reopens one level up. `osv-track-issue` is now a thin
+// preset that executes `../track-issue/track-issue.mjs`, and nothing `uses:`
+// the generic action — so without a companion map, a rewrite of that shared
+// core leaves every preset call site reading fresh while the pinned SHA runs
+// the old state machine.
+// ---------------------------------------------------------------------------
+
+const PRESET_SUBPATH = ".github/actions/osv-track-issue";
+const CORE_SUBPATH = ".github/actions/track-issue";
+const PRESET_COMPANIONS = { [PRESET_SUBPATH]: [CORE_SUBPATH] };
+
+/** A workflow pinning `subpath@sha`, one step per call site. */
+function workflowFor(subpath, sha) {
+  return [
+    "name: fixture",
+    "on:",
+    "  push:",
+    "    branches: [main]",
+    "jobs:",
+    "  demo:",
+    "    runs-on: ubuntu-latest",
+    "    steps:",
+    `      - uses: ${OWNER}/${subpath}@${sha}`,
+    "",
+  ].join("\n");
+}
+
+/**
+ * A repo shaped like the post-#389 split: a preset directory whose manifest
+ * runs a script in a sibling core directory that no `uses:` line names. Both
+ * are committed; the caller then edits the CORE in the working tree only.
+ */
+function makePresetRepo(label) {
+  const root = mkdtempSync(join(tmpdir(), `pinfresh-${label}-`));
+  git(root, "init", "-b", "main");
+  git(root, "config", "user.email", "fixture@example.invalid");
+  git(root, "config", "user.name", "Pin Freshness Fixture");
+  git(root, "config", "commit.gpgsign", "false");
+  git(root, "config", "core.hooksPath", join(root, ".no-hooks"));
+
+  put(root, `${CORE_SUBPATH}/action.yml`, SIBLING_MANIFEST);
+  put(root, `${CORE_SUBPATH}/track-issue.mjs`, "export const verdict = () => 'noop';\n");
+  put(root, `${PRESET_SUBPATH}/action.yml`, SIBLING_MANIFEST);
+  put(root, `${PRESET_SUBPATH}/osv-track-issue.mjs`, "import '../track-issue/track-issue.mjs';\n");
+  git(root, "add", "-A");
+  git(root, "commit", "-m", "split the tracker into a core and a preset");
+  const after = git(root, "rev-parse", "HEAD");
+
+  return { root, after };
+}
+
+test("stale: an edit confined to the shared core marks every preset call site stale", () => {
+  const { root, after } = makePresetRepo("companion-stale");
+  track(root);
+  // Two call sites, both pinning the preset — neither names the core.
+  put(root, ".github/workflows/one.yml", workflowFor(PRESET_SUBPATH, after));
+  put(root, ".github/workflows/two.yml", workflowFor(PRESET_SUBPATH, after));
+
+  // The edit is confined to the core, and nothing under the preset changes.
+  put(root, `${CORE_SUBPATH}/track-issue.mjs`, "export const verdict = () => 'create';\n");
+
+  // The premise, asserted rather than assumed: without the companion map this
+  // fixture reads perfectly fresh — which is the blind spot, not a pass.
+  const blind = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: {} });
+  assert.equal(blind.ok, true, "premise: a preset-only comparison sees no drift");
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: PRESET_COMPANIONS });
+
+  assert.equal(result.ok, false);
+  assert.equal(result.scanned, 2);
+  assert.equal(result.stale.length, 2, "every call site of the preset is stale, not just one");
+  assert.equal(result.unreachable.length, 0);
+  for (const f of result.stale) {
+    assert.equal(f.subpath, PRESET_SUBPATH);
+    assert.match(f.reason, /track-issue\.mjs/, "the report names the drifting shared file");
+    assert.match(f.reason, /shared code it executes/, "and explains why a sibling tree is in scope");
+  }
+});
+
+test("stale: a file added to the shared core since the pinned SHA is drift", () => {
+  const { root, after } = makePresetRepo("companion-added");
+  track(root);
+  put(root, ".github/workflows/one.yml", workflowFor(PRESET_SUBPATH, after));
+  put(root, `${CORE_SUBPATH}/helper.mjs`, "export const help = () => 1;\n");
+  git(root, "add", "-A");
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: PRESET_COMPANIONS });
+
+  assert.equal(result.ok, false);
+  assert.match(result.stale[0].reason, /helper\.mjs/);
+});
+
+test("clean: a pin carrying the current core AND preset exits 0", () => {
+  const { root, after } = makePresetRepo("companion-clean");
+  track(root);
+  put(root, ".github/workflows/one.yml", workflowFor(PRESET_SUBPATH, after));
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: PRESET_COMPANIONS });
+  assert.equal(result.ok, true);
+});
+
+test("a subpath with no companions is compared exactly as before", () => {
+  const { root, after } = makePresetRepo("companion-unmapped");
+  track(root);
+  // Pin the CORE directly — it has no companions of its own, so a preset edit
+  // must not leak into its comparison.
+  put(root, ".github/workflows/one.yml", workflowFor(CORE_SUBPATH, after));
+  put(root, `${PRESET_SUBPATH}/osv-track-issue.mjs`, "// rewritten preset\n");
+
+  const result = runCheck({ cwd: root, firstPartyOwner: OWNER, companions: PRESET_COMPANIONS });
+  assert.equal(result.ok, true, "companions are directional, not symmetric");
+});
+
+test("diffSubpathAtSha: companions are unioned into both sides of the comparison", () => {
+  const presetPath = `${PRESET_SUBPATH}/action.yml`;
+  const corePath = `${CORE_SUBPATH}/action.yml`;
+  const presetBody = readFileSync(join(REPO_ROOT, presetPath), "utf8");
+  // The pinned side knows only the preset; the working side also has the core.
+  const fake = {
+    lsTree: (_sha, root) => (root === PRESET_SUBPATH ? [presetPath] : []),
+    lsFiles: (root) => (root === PRESET_SUBPATH ? [presetPath] : [corePath]),
+    show: () => presetBody,
+  };
+
+  const without = diffSubpathAtSha(fake, REPO_ROOT, "0".repeat(40), PRESET_SUBPATH);
+  assert.deepEqual(without, [], "the preset tree alone is identical at both ends");
+
+  const withCore = diffSubpathAtSha(fake, REPO_ROOT, "0".repeat(40), PRESET_SUBPATH, [CORE_SUBPATH]);
+  assert.deepEqual(withCore, [{ path: corePath, kind: "added" }]);
+});
+
+test("companionsFor: unmapped subpaths stand alone, and trailing slashes resolve", () => {
+  assert.deepEqual(companionsFor(".github/actions/setup-toolchain"), []);
+  assert.deepEqual(companionsFor(PRESET_SUBPATH, PRESET_COMPANIONS), [CORE_SUBPATH]);
+  assert.deepEqual(companionsFor(`${PRESET_SUBPATH}/`, PRESET_COMPANIONS), [CORE_SUBPATH]);
+});
+
+test("COMPANION_SUBPATHS: every mapped subpath and companion exists in this repo", () => {
+  // A map entry pointing at a path that no longer exists is a silently-dead
+  // guard — the pin would read fresh again with nothing flagging it.
+  for (const [subpath, companions] of Object.entries(COMPANION_SUBPATHS)) {
+    assert.ok(
+      resolveManifest(REPO_ROOT, subpath),
+      `${subpath} is mapped but resolves to no manifest`
+    );
+    for (const companion of companions) {
+      assert.ok(
+        resolveManifest(REPO_ROOT, companion),
+        `${subpath} names companion ${companion}, which resolves to no manifest`
+      );
+    }
+  }
+});
+
 // ---------------------------------------------------------------------------
 // AC-7 — third-party / local / docker references are never classified
 // ---------------------------------------------------------------------------

package/scripts/check-playwright-browser-install.test.mjs

@@ -0,0 +1,451 @@
+#!/usr/bin/env node
+/**
+ * check-playwright-browser-install.test.mjs — regression guard for the e2e
+ * tier's Playwright browser install (Story #396).
+ *
+ * The bug this pins: the install step was gated on
+ * `steps.playwright-cache.outputs.cache-hit != 'true'`. `actions/cache` sets
+ * `cache-hit: true` on an EXACT key match and says nothing about what the
+ * restored tree actually contains, so the gate treats "an entry exists under
+ * this key" as proof the binaries are present. A cache saved partially — or
+ * saved before a Playwright patch added a browser variant under the same
+ * version key — therefore skips the only step that would repair it, and every
+ * scenario dies in milliseconds at `browserType.launch`.
+ *
+ * It could not self-heal in either direction: the hit kept skipping the
+ * repair, and Actions cache entries are IMMUTABLE under a key (`actions/cache`
+ * skips its post-job save on an exact hit), so the bad entry was never
+ * overwritten. Hence the two halves of the fix this file guards:
+ *
+ *   1. The install runs unconditionally, so a bad restore costs a re-download
+ *      rather than the run. This is not a new cost — the pre-fix hit path
+ *      already ran `playwright install-deps`, so the same OS-dependency step
+ *      ran on BOTH branches; collapsing them adds only a browser-manifest
+ *      verify.
+ *   2. A caller-settable salt is folded into the cache key, so an operator can
+ *      stop paying that repair on every run by moving to a fresh key — without
+ *      hand-deleting caches through the GitHub API.
+ *
+ * Asserting the key by string-matching its spelling would pin the text rather
+ * than the contract. The property that actually matters is RELATIONAL: the
+ * default salt must leave the key byte-for-byte identical to the pre-fix one
+ * (or every consumer's warm cache is silently invalidated by the upgrade), and
+ * distinct salts must produce distinct keys (or the escape hatch does not
+ * escape). So this extracts the real key template and resolves it under
+ * several salt values, the same read-then-execute approach as
+ * check-toolchain-cache-default.test.mjs.
+ *
+ * Run: node --test scripts/check-playwright-browser-install.test.mjs
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+import { spawnSync } from "node:child_process";
+import { mkdtempSync, mkdirSync, readFileSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+
+const QUALITY = ".github/workflows/pr-quality.yml";
+const SALT_INPUT = "playwright-cache-salt";
+
+/**
+ * The fixed literal the resolve step falls back to (Story #400).
+ *
+ * It must stay a CONSTANT. A host- or run-derived fallback (`$GITHUB_SHA`, a
+ * date) satisfies "the step no longer fails" while minting a new cache key on
+ * every run — permanently defeating the ~460 MiB cache the step exists to
+ * label, which is a worse outcome than the abort it replaced.
+ */
+const SENTINEL = "unresolved";
+
+/** The exact key template the tier carried before Story #396. */
+const PRE_FIX_KEY = "playwright-${{ runner.os }}-${{ steps.pw-version.outputs.version }}";
+const PRE_FIX_RESTORE_KEY = "playwright-${{ runner.os }}-";
+
+const text = readFileSync(QUALITY, "utf8");
+
+/**
+ * The workflow with whole-line `#` comments removed.
+ *
+ * The guard is about what the workflow DOES, not what it says: the tier
+ * carries a comment naming the very expression this file forbids, so that a
+ * future reader is told not to reintroduce it. Scanning raw text would let
+ * that warning fail the check it exists to support. Only leading-`#` lines are
+ * dropped — never a mid-line `#`, which could sit inside a quoted value.
+ */
+const code = text
+  .split("\n")
+  .filter((l) => !l.trimStart().startsWith("#"))
+  .join("\n");
+
+// ---------------------------------------------------------------------------
+// Extraction
+// ---------------------------------------------------------------------------
+
+/**
+ * The `steps:` block of the named job, sliced by indentation.
+ *
+ * Scans lines rather than building a `new RegExp` around the job name: a
+ * dynamically-constructed regex is a SAST finding (ReDoS surface) and buys
+ * nothing here, since the block boundary is just indentation.
+ */
+function jobBlock(name, source = code) {
+  const lines = source.split("\n");
+  const start = lines.indexOf(`  ${name}:`);
+  assert.notEqual(start, -1, `${QUALITY}: job \`${name}\` not found`);
+  const out = [];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].trim() === "") {
+      out.push(lines[i]);
+      continue;
+    }
+    // Dedent to the job-name level or beyond → the block ended.
+    if (lines[i].match(/^(\s*)/)[1].length <= 2) break;
+    out.push(lines[i]);
+  }
+  return out.join("\n");
+}
+
+/**
+ * The `- name: <step>` … block for one step of a job, sliced by indentation.
+ *
+ * `source` defaults to the comment-stripped text — right for asserting what the
+ * workflow DOES. Pass the raw `text` when the block is going to be EXECUTED, so
+ * the guard runs the same script the runner does rather than a stripped
+ * paraphrase of it.
+ */
+function stepBlock(job, stepName, source = code) {
+  const lines = jobBlock(job, source).split("\n");
+  const start = lines.findIndex((l) => l.trim() === `- name: ${stepName}`);
+  assert.notEqual(start, -1, `${QUALITY}: step \`${stepName}\` not found in job \`${job}\``);
+  const indent = lines[start].match(/^(\s*)/)[1].length;
+  const out = [lines[start]];
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].trim() === "") continue;
+    const width = lines[i].match(/^(\s*)/)[1].length;
+    // A sibling list item (or a dedent) at the same indent ends this step.
+    if (width <= indent) break;
+    out.push(lines[i]);
+  }
+  return out.join("\n");
+}
+
+/** The literal `default:` of the named workflow_call input. */
+function inputDefault(name) {
+  const lines = code.split("\n");
+  const start = lines.indexOf(`      ${name}:`);
+  assert.notEqual(start, -1, `${QUALITY}: workflow_call input \`${name}\` not found`);
+  for (let i = start + 1; i < lines.length; i++) {
+    if (lines[i].trim() === "") continue;
+    if (lines[i].match(/^(\s*)/)[1].length <= 6) break;
+    const d = lines[i].match(/^\s*default:\s*(.+)$/);
+    if (d) return d[1].trim();
+  }
+  return assert.fail(`${QUALITY}: input \`${name}\` has no default`);
+}
+
+/** The `key:` / `restore-keys:` templates of the cache step. */
+function cacheKeys() {
+  const block = stepBlock("e2e", "Cache Playwright browsers");
+  const key = block.match(/^\s*key:\s*(.+)$/m);
+  assert.ok(key, `${QUALITY}: the cache step has no \`key:\``);
+  const restore = block.match(/^\s*restore-keys:\s*\|\s*\n\s*(.+)$/m);
+  assert.ok(restore, `${QUALITY}: the cache step has no \`restore-keys:\``);
+  return { key: key[1].trim(), restoreKey: restore[1].trim() };
+}
+
+/**
+ * Resolve a key template for one salt value, leaving every other `${{ … }}`
+ * placeholder untouched so the result is directly comparable to the pre-fix
+ * literal. Split/join rather than a constructed regex, for the SAST reason
+ * above.
+ */
+function resolveSalt(template, salt) {
+  return template
+    .split(`\${{ inputs.${SALT_INPUT} }}`)
+    .join(salt)
+    .split(`\${{ inputs['${SALT_INPUT}'] }}`)
+    .join(salt);
+}
+
+/**
+ * The dedented body of a step's `run: |` block, taken from the RAW workflow
+ * text so the guard executes what the runner executes.
+ *
+ * This is only sound while the block holds no `${{ }}` expression — the runner
+ * substitutes those before bash ever sees them, and there is no substituting
+ * them here. A dedicated test below pins that precondition rather than leaving
+ * it as a silent assumption.
+ */
+function runScript(job, stepName) {
+  const lines = stepBlock(job, stepName, text).split("\n");
+  const start = lines.findIndex((l) => l.trim() === "run: |");
+  assert.notEqual(start, -1, `${QUALITY}: step \`${stepName}\` has no \`run: |\` block`);
+  const body = lines.slice(start + 1);
+  assert.ok(body.length > 0, `${QUALITY}: step \`${stepName}\` has an empty \`run:\` block`);
+  const indent = body[0].match(/^(\s*)/)[1].length;
+  return body.map((l) => l.slice(indent)).join("\n");
+}
+
+/**
+ * Run a script under the runner's own shell invocation, in a throwaway cwd.
+ *
+ * GitHub executes `shell: bash` as `bash --noprofile --norc -eo pipefail
+ * {0}` — the `-e` is the whole reason the pre-fix step could kill the tier, so
+ * the guard reproduces the flags exactly. `cwd` is passed to `spawnSync` and
+ * `process.chdir` is never called: this file's later tests read
+ * `docs/reusable-workflows.md` by a RELATIVE path, and a leaked cwd would fail
+ * them for a reason that has nothing to do with the change under test.
+ */
+function runInDir(script, cwd) {
+  const outPath = join(cwd, "github-output");
+  writeFileSync(outPath, "");
+  const scriptPath = join(cwd, "step.sh");
+  writeFileSync(scriptPath, script);
+  const res = spawnSync("bash", ["--noprofile", "--norc", "-eo", "pipefail", scriptPath], {
+    cwd,
+    env: { ...process.env, GITHUB_OUTPUT: outPath },
+    encoding: "utf8",
+  });
+  const outputs = new Map();
+  for (const line of readFileSync(outPath, "utf8").split("\n")) {
+    const eq = line.indexOf("=");
+    if (eq > 0) outputs.set(line.slice(0, eq), line.slice(eq + 1));
+  }
+  return { status: res.status, stderr: res.stderr, outputs };
+}
+
+/** A temp directory, removed however the callback exits. */
+function withTempDir(fn) {
+  const dir = mkdtempSync(join(tmpdir(), "pw-version-"));
+  try {
+    return fn(dir);
+  } finally {
+    rmSync(dir, { recursive: true, force: true });
+  }
+}
+
+/**
+ * Plant a resolvable `@playwright/test` under `dir`.
+ *
+ * The `exports` map matters: the real package restricts subpath access and
+ * lists `"./package.json"` explicitly. Without it here, a resolution strategy
+ * that is ILLEGAL against the real package would still pass this guard.
+ */
+function plantPlaywright(dir, version) {
+  const pkgDir = join(dir, "node_modules", "@playwright", "test");
+  mkdirSync(pkgDir, { recursive: true });
+  writeFileSync(
+    join(pkgDir, "package.json"),
+    JSON.stringify({
+      name: "@playwright/test",
+      version,
+      exports: { "./package.json": "./package.json" },
+    }),
+  );
+}
+
+// ---------------------------------------------------------------------------
+// The contract
+// ---------------------------------------------------------------------------
+
+test("no step gates on the Playwright cache-hit output", () => {
+  // AC-1, the defect itself. `cache-hit` is true whenever an entry EXISTS
+  // under the key — it is not a statement about the entry's contents, so no
+  // step may treat it as one.
+  assert.doesNotMatch(
+    code,
+    /steps\.playwright-cache\.outputs\.cache-hit/,
+    "a cache-hit gate is back: a partial cache would again be fatal rather than repaired",
+  );
+});
+
+test("the browser install runs unconditionally with --with-deps", () => {
+  // AC-1. Unconditional is the whole fix — an `if:` of ANY shape here
+  // reintroduces a path where a bad restore is never repaired.
+  const block = stepBlock("e2e", "Install Playwright browsers");
+  assert.match(block, /run:\s*pnpm exec playwright install --with-deps/);
+  assert.doesNotMatch(
+    block,
+    /^\s*if:/m,
+    "the install step must carry no condition — see this file's header",
+  );
+});
+
+test("the cache-hit-only OS-dependency step is gone", () => {
+  // AC-1. Its only reason to exist was the hit branch; leaving it behind
+  // would run `install-deps` twice on every run.
+  assert.doesNotMatch(
+    jobBlock("e2e"),
+    /- name: Install browser OS dependencies/,
+    "the split OS-dependency step is redundant once the install is unconditional",
+  );
+});
+
+test(`the ${SALT_INPUT} input exists with a literal default`, () => {
+  // AC-2. A `workflow_call` default may not hold an expression: GitHub
+  // resolves defaults during interface validation, before any context exists,
+  // and check-workflow-portability.mjs Rule 2 rejects it outright.
+  const value = inputDefault(SALT_INPUT);
+  assert.doesNotMatch(value, /\$\{\{/, "a workflow_call default may not hold an expression");
+  assert.equal(value, "''");
+});
+
+test("the cache key interpolates the salt input", () => {
+  // AC-2. Declared-but-unread is the failure mode that makes the escape hatch
+  // silently inert.
+  const { key } = cacheKeys();
+  assert.match(key, /inputs\./, "the key does not read any input");
+  assert.notEqual(
+    resolveSalt(key, "probe"),
+    key,
+    `the key does not interpolate \`inputs.${SALT_INPUT}\``,
+  );
+});
+
+test("the default salt leaves the cache key byte-for-byte unchanged", () => {
+  // AC-3 — the compatibility contract. If this drifts, every consumer's warm
+  // ~460 MiB cache is silently orphaned the moment they adopt the release,
+  // which is a worse outage than the bug being fixed.
+  const { key, restoreKey } = cacheKeys();
+  assert.equal(resolveSalt(key, ""), PRE_FIX_KEY);
+  assert.equal(resolveSalt(restoreKey, ""), PRE_FIX_RESTORE_KEY);
+});
+
+test("distinct salts produce distinct cache keys", () => {
+  // AC-4 — the escape hatch actually escapes. A salt that collapses into the
+  // same key (interpolated into a comment, or into a segment the key does not
+  // use) would leave the operator back at deleting caches by hand.
+  const { key } = cacheKeys();
+  const base = resolveSalt(key, "");
+  const bumped = resolveSalt(key, "-v2");
+  const bumpedAgain = resolveSalt(key, "-v3");
+  assert.notEqual(bumped, base, "a non-empty salt must not resolve to the default key");
+  assert.notEqual(bumpedAgain, bumped, "two different salts must not collide");
+});
+
+test("the salt does not disturb the restore-keys prefix", () => {
+  // A deliberate asymmetry, not an oversight: the prefix fallback must keep
+  // matching older entries so a salt bump still gets a WARM start. The
+  // unconditional install then fills whatever the old entry was missing, and
+  // because a prefix (non-exact) restore leaves `cache-hit` false, the
+  // post-job save writes a complete tree under the NEW key. That is what
+  // completes the escape — one run, no manual cache deletion.
+  const { restoreKey } = cacheKeys();
+  assert.equal(
+    resolveSalt(restoreKey, "-v2"),
+    PRE_FIX_RESTORE_KEY,
+    "restore-keys must stay salt-free so a bumped key still warm-starts",
+  );
+});
+
+test("the documented input row states the default and the escape semantics", () => {
+  // AC-6. The row is the consumer-facing contract for a knob whose entire
+  // purpose is manual operator use — undocumented, it may as well not exist.
+  const docs = readFileSync("docs/reusable-workflows.md", "utf8");
+  const rows = docs
+    .split("\n")
+    .filter((l) => l.startsWith(`| \`${SALT_INPUT}\``) && /\|\s*string\s*\|/.test(l));
+  assert.equal(rows.length, 1, "expected exactly one documented input row");
+  assert.match(rows[0], /`''`/, "row does not state the empty-string default");
+  assert.match(rows[0], /cache/i, "row does not explain what the salt affects");
+});
+
+// ---------------------------------------------------------------------------
+// Version resolution (Story #400)
+//
+// The pre-fix step ran `node -e "…require('./node_modules/@playwright/test/…')"`
+// as a bare `VAR=$(…)` assignment. Under `bash -eo pipefail` that propagates
+// the substitution's exit status, so on a consumer whose ROOT node_modules
+// lacks the package — pnpm's isolated layout only symlinks a root DIRECT
+// dependency, so a workspace-owned Playwright has no such path — `set -e`
+// killed the step and took the whole e2e tier with it. A step that exists only
+// to LABEL a cache key must never be able to do that.
+// ---------------------------------------------------------------------------
+
+test("version resolution uses a bare specifier, not a hardcoded root path", () => {
+  const block = stepBlock("e2e", "Resolve Playwright version");
+  assert.doesNotMatch(
+    block,
+    /\.\/node_modules\/@playwright\/test/,
+    "a hardcoded root path is back: a workspace-owned Playwright would not resolve",
+  );
+  assert.match(
+    block,
+    /require\((['"])@playwright\/test\/package\.json\1\)/,
+    "resolution must go through the bare specifier, which walks node_modules",
+  );
+});
+
+test("the resolve step's run block holds no workflow expression", () => {
+  // The precondition for executing this step in the tests below: the runner
+  // substitutes `${{ }}` before bash sees it, and nothing substitutes it here.
+  // Threading an input into the block would leave the guard asserting against
+  // a string that never runs.
+  assert.doesNotMatch(
+    runScript("e2e", "Resolve Playwright version"),
+    /\$\{\{/,
+    "keep the run block expression-free so the guard executes the runner's text",
+  );
+});
+
+test("the sentinel is assigned as a fixed literal", () => {
+  // Invariant 2 (see SENTINEL above). Assert the SHAPE of the assignment, not
+  // merely that the step stopped failing — `PW_VERSION=$(date +%F)` would pass
+  // a stability check across two runs in the same second and still rekey the
+  // cache on every push.
+  const script = runScript("e2e", "Resolve Playwright version");
+  const assignments = script
+    .split("\n")
+    .map((l) => l.trim())
+    .filter((l) => !l.startsWith("#") && l.includes(`=${SENTINEL}`));
+  assert.equal(assignments.length, 1, `expected exactly one \`=${SENTINEL}\` assignment`);
+  const [assignment] = assignments;
+  assert.match(assignment, /^[A-Za-z_][A-Za-z0-9_]*=unresolved$/, "the sentinel must be a literal");
+  assert.ok(!assignment.includes("$("), "the sentinel must not be command-substituted");
+  assert.ok(!assignment.includes("${"), "the sentinel must not be parameter-expanded");
+});
+
+test("an unresolvable @playwright/test yields the sentinel instead of failing the tier", () => {
+  // The defect itself. A temp dir has no `node_modules` anywhere up its tree,
+  // which is exactly the consumer shape that lost the tier.
+  const script = runScript("e2e", "Resolve Playwright version");
+  withTempDir((dir) => {
+    const { status, outputs, stderr } = runInDir(script, dir);
+    assert.equal(status, 0, `the step must not fail the tier; stderr:\n${stderr}`);
+    assert.equal(outputs.get("version"), SENTINEL);
+  });
+});
+
+test("the sentinel is stable across runs, so the cache key does not churn", () => {
+  // Invariant 2 again, from the outside: a value that varies run to run mints a
+  // fresh key every time and permanently defeats the cache.
+  const script = runScript("e2e", "Resolve Playwright version");
+  const read = () => withTempDir((dir) => runInDir(script, dir).outputs.get("version"));
+  const first = read();
+  // Pin the value, not just its stability: two runs that both emit NOTHING are
+  // trivially equal, which would let a step that never writes the output pass.
+  assert.equal(first, SENTINEL);
+  assert.equal(read(), first);
+});
+
+test("a resolvable @playwright/test produces the pre-fix cache key exactly", () => {
+  // The compatibility contract, end to end: what the step actually emits, fed
+  // through the real key template at the default salt, must equal the key
+  // consumers' warm caches already sit under.
+  const script = runScript("e2e", "Resolve Playwright version");
+  const version = "1.61.1";
+  const resolved = withTempDir((dir) => {
+    plantPlaywright(dir, version);
+    const { status, outputs, stderr } = runInDir(script, dir);
+    assert.equal(status, 0, `stderr:\n${stderr}`);
+    return outputs.get("version");
+  });
+  assert.equal(resolved, version, "the step must report the resolved package's version");
+
+  const { key } = cacheKeys();
+  const withVersion = resolveSalt(key, "")
+    .split("${{ steps.pw-version.outputs.version }}")
+    .join(resolved);
+  assert.equal(withVersion, `playwright-\${{ runner.os }}-${version}`);
+});

package/scripts/osv-track-issue.test.mjs

@@ -6,6 +6,14 @@
 // clears. That contract is the pure `decideVerdict` function — these tests
 // pin every branch of it, plus the marker round-trip and the gh-driven
 // lookup, without any network access.
+//
+// Story #389 moved that state machine into the generic
+// `.github/actions/track-issue` core and reduced this module to a preset over
+// it. Every test below predates that move and is retained verbatim: passing
+// unmodified is the evidence that the extraction preserved the OSV verdict
+// contract rather than rewriting it. The sections appended at the end cover
+// what the move newly put at risk — marker continuity against a LIVE advisory
+// issue, and the findings-envelope adapter.
 
 import { test } from "node:test";
 import assert from "node:assert/strict";
@@ -15,8 +23,11 @@ import {
   extractDigest,
   digestMarker,
   buildIssueBody,
+  buildEnvUpdates,
   findTrackingIssue,
+  DIGEST_PREFIX,
   TRACKER_MARKER,
+  TRACKER_MARKER_KEY,
 } from "../.github/actions/osv-track-issue/osv-track-issue.mjs";
 
 const issueWithDigest = (number, digest) => ({
@@ -89,3 +100,147 @@ test("findTrackingIssue returns null when nothing carries the marker", () => {
   const runner = () => JSON.stringify([{ number: 1, body: "no marker" }]);
   assert.equal(findTrackingIssue({ repo: "acme/app", labels: [] }, runner), null);
 });
+
+// ---------------------------------------------------------------------------
+// Story #389 — marker continuity across the extraction
+//
+// These two strings are what a LIVE advisory issue in a consumer repo is keyed
+// on. A changed byte in either would leave that issue undiscoverable, so the
+// next scheduled run would open a SECOND one — the exact duplicate-spam
+// failure this action exists to prevent. They are therefore asserted as
+// literals, not derived from the module under test.
+// ---------------------------------------------------------------------------
+
+test("the tracker marker is byte-identical to the live one", () => {
+  assert.equal(TRACKER_MARKER, "<!-- mandrel:osv-advisory-tracker -->");
+  assert.equal(TRACKER_MARKER_KEY, "mandrel:osv-advisory-tracker");
+  assert.equal(DIGEST_PREFIX, "mandrel:osv-advisory-digest:");
+});
+
+test("a rendered OSV body round-trips its digest through the live digest prefix", () => {
+  const body = buildIssueBody({
+    digest: "cafe1234-3",
+    summary: "| advisory | package |",
+    repo: "acme/app",
+    branch: "main",
+  });
+
+  assert.ok(body.includes("<!-- mandrel:osv-advisory-tracker -->"));
+  assert.ok(body.includes("<!-- mandrel:osv-advisory-digest: cafe1234-3 -->"));
+  assert.equal(extractDigest(body), "cafe1234-3");
+});
+
+test("the OSV body is unchanged by the extraction — markers, prose, then summary", () => {
+  // Pinned against the shape the pre-#389 module produced. A silent body
+  // rewrite would churn every consumer's tracking issue on the next run.
+  const body = buildIssueBody({
+    digest: "d-1",
+    summary: "SUMMARY-BLOCK",
+    repo: "acme/app",
+    branch: "trunk",
+  });
+
+  assert.equal(
+    body,
+    [
+      "<!-- mandrel:osv-advisory-tracker -->",
+      "<!-- mandrel:osv-advisory-digest: d-1 -->",
+      "",
+      "Scheduled OSV advisory scan of `acme/app` (default branch `trunk`) found advisories at or",
+      "above the configured gate. This issue is maintained automatically by the",
+      "`advisory-scan.yml` reusable workflow — it is updated when the finding set changes",
+      "and closed automatically when the set clears. Do not edit the markers above.",
+      "",
+      "SUMMARY-BLOCK",
+    ].join("\n"),
+  );
+});
+
+test("an empty summary still renders the historical placeholder", () => {
+  const body = buildIssueBody({ digest: "d-1", summary: "", repo: "a/b", branch: "main" });
+  assert.match(body, /_\(no summary provided\)_/);
+});
+
+// ---------------------------------------------------------------------------
+// Story #389 — the findings-envelope adapter
+//
+// This module no longer performs the upsert; it translates the osv-scan
+// envelope into the generic TRACK_* contract and hands it to the shared core.
+// ---------------------------------------------------------------------------
+
+/** Collapse the adapter's entry list into a lookup for assertion. */
+const asMap = (entries) => Object.fromEntries(entries);
+
+test("the adapter forwards the live marker and digest prefix verbatim", () => {
+  const env = asMap(
+    buildEnvUpdates({ digest: "abc123", counts: { blocking: 2 }, failOn: "high", summary: "s" }, {
+      OSV_TRACK_REPO: "acme/app",
+    }),
+  );
+
+  assert.equal(env.TRACK_MARKER, "mandrel:osv-advisory-tracker");
+  assert.equal(env.TRACK_DIGEST_PREFIX, "mandrel:osv-advisory-digest:");
+});
+
+test("the adapter passes the scanner's own digest rather than deriving one", () => {
+  // The scanner digest depends on finding identity (id + package + version +
+  // source); a derived one over a count-shaped label would churn on nothing.
+  const env = asMap(
+    buildEnvUpdates({ digest: "scanner-digest", counts: { blocking: 3 }, failOn: "high" }, {
+      OSV_TRACK_REPO: "acme/app",
+    }),
+  );
+  assert.equal(env.TRACK_DIGEST, "scanner-digest");
+});
+
+test("a blocking count of zero yields an empty failing set", () => {
+  const env = asMap(
+    buildEnvUpdates({ digest: "empty-0", counts: { blocking: 0 }, failOn: "high" }, {
+      OSV_TRACK_REPO: "acme/app",
+    }),
+  );
+  assert.deepEqual(JSON.parse(env.TRACK_FAILED_ITEMS), []);
+});
+
+test("a non-zero blocking count yields a non-empty failing set", () => {
+  const env = asMap(
+    buildEnvUpdates({ digest: "d", counts: { blocking: 4 }, failOn: "critical" }, {
+      OSV_TRACK_REPO: "acme/app",
+    }),
+  );
+  const items = JSON.parse(env.TRACK_FAILED_ITEMS);
+  assert.equal(items.length, 1);
+  assert.match(items[0], /4 advisory finding\(s\) at or above the 'critical' gate/);
+});
+
+test("the adapter neither refreshes on an unchanged set nor comments on change", () => {
+  // Both knobs default to today's OSV posture, so the preset must set neither.
+  const env = asMap(buildEnvUpdates({ digest: "d", counts: { blocking: 1 } }, { OSV_TRACK_REPO: "a/b" }));
+  assert.equal(env.TRACK_UNCHANGED_BEHAVIOR, undefined);
+  assert.equal(env.TRACK_COMMENT_ON_CHANGE, undefined);
+  assert.equal(env.TRACK_RUN_URL, undefined, "no run link — the body stays byte-stable across runs");
+});
+
+test("the adapter carries the caller's title, labels and branch through", () => {
+  const env = asMap(
+    buildEnvUpdates({ digest: "d", counts: { blocking: 1 } }, {
+      OSV_TRACK_REPO: "acme/app",
+      OSV_TRACK_BRANCH: "trunk",
+      OSV_TRACK_TITLE: "Custom title",
+      OSV_TRACK_LABELS: "security,ops",
+    }),
+  );
+
+  assert.equal(env.TRACK_REPO, "acme/app");
+  assert.equal(env.TRACK_BRANCH, "trunk");
+  assert.equal(env.TRACK_TITLE, "Custom title");
+  assert.equal(env.TRACK_LABELS, "security,ops");
+  assert.match(env.TRACK_BODY_INTRO, /Scheduled OSV advisory scan of `acme\/app` \(default branch `trunk`\)/);
+  assert.match(env.TRACK_CLOSE_COMMENT, /no longer reports any finding at or above the gate/);
+});
+
+test("the adapter defaults the title to the documented one when the caller omits it", () => {
+  const env = asMap(buildEnvUpdates({ digest: "d", counts: { blocking: 1 } }, { OSV_TRACK_REPO: "a/b" }));
+  assert.equal(env.TRACK_TITLE, "OSV advisory scan — default branch findings");
+  assert.equal(env.TRACK_BRANCH, "main");
+});

package/scripts/track-issue.test.mjs

@@ -0,0 +1,375 @@
+// Unit coverage for the generic single-issue failure tracker (Story #389).
+//
+// The whole point of this action is a SINGLE tracked issue that does not spam:
+// it must open once, stay quiet while the failing set is unchanged, update only
+// on a real change, and close when the set clears. That contract is the pure
+// `decideVerdict` function — these tests pin every branch of it, plus the
+// failing-set derivation, the digest, the marker round-trip and the gh-driven
+// lookup, without any network access.
+//
+// Run: node --test scripts/track-issue.test.mjs
+
+import { test } from "node:test";
+import assert from "node:assert/strict";
+
+import {
+  DEFAULT_CLOSE_COMMENT,
+  DEFAULT_INTRO,
+  buildIssueBody,
+  computeDigest,
+  decideVerdict,
+  defaultDigestPrefix,
+  digestMarker,
+  extractDigest,
+  failingJobs,
+  findTrackingIssue,
+  markerKey,
+  markerLine,
+  renderEnvEntry,
+  resolveConfig,
+} from "../.github/actions/track-issue/track-issue.mjs";
+
+const MARKER = "acme:nightly-tracker";
+const PREFIX = defaultDigestPrefix(MARKER);
+const OPTS = { digestPrefix: PREFIX };
+
+/** An open tracked issue whose body carries `digest`. */
+const issueWithDigest = (number, digest) => ({
+  number,
+  body: buildIssueBody({ marker: MARKER, digestPrefix: PREFIX, digest, detail: "…" }),
+});
+
+// ---------------------------------------------------------------------------
+// AC-3 — the four-way state machine survives the extraction unchanged
+// ---------------------------------------------------------------------------
+
+test("CREATE when items are failing and no tracking issue is open", () => {
+  const v = decideVerdict(null, { failedCount: 2, digest: "abcd1234" }, OPTS);
+  assert.equal(v.action, "create");
+});
+
+test("UPDATE when the failing-set digest changed since the issue was written", () => {
+  const existing = issueWithDigest(42, "abcd1234");
+  const v = decideVerdict(existing, { failedCount: 3, digest: "zzzz9999" }, OPTS);
+  assert.equal(v.action, "update");
+});
+
+test("CLOSE when the failing set is now empty but an issue is still open", () => {
+  const existing = issueWithDigest(42, "abcd1234");
+  const v = decideVerdict(existing, { failedCount: 0, digest: "green-0" }, OPTS);
+  assert.equal(v.action, "close");
+});
+
+test("NOOP when nothing is failing and there is no issue to close", () => {
+  const v = decideVerdict(null, { failedCount: 0, digest: "green-0" }, OPTS);
+  assert.equal(v.action, "noop");
+});
+
+// ---------------------------------------------------------------------------
+// AC-4 — the never-a-second-issue invariant, asserted on the core
+// ---------------------------------------------------------------------------
+
+test("two consecutive failing runs against an open marked issue never yield CREATE", () => {
+  // Run 1 opens the issue; the tracker then finds it on every subsequent run.
+  assert.equal(decideVerdict(null, { failedCount: 1, digest: "d1" }, OPTS).action, "create");
+  const open = issueWithDigest(7, "d1");
+
+  // Run 2 — same failing set. Run 3 — a DIFFERENT failing set. Neither may
+  // create: a second issue is the duplicate-spam failure this action prevents.
+  const second = decideVerdict(open, { failedCount: 1, digest: "d1" }, OPTS);
+  const third = decideVerdict(open, { failedCount: 4, digest: "d2" }, OPTS);
+
+  assert.equal(second.action, "noop");
+  assert.equal(third.action, "update");
+  for (const v of [second, third]) assert.notEqual(v.action, "create");
+});
+
+test("an unparseable body never yields CREATE while an issue is open", () => {
+  // A human editing the body away is not a licence to open a second issue: the
+  // marker still found the issue, so the worst case is a redundant UPDATE.
+  const mangled = { number: 9, body: "someone deleted the digest marker" };
+  assert.equal(decideVerdict(mangled, { failedCount: 2, digest: "d9" }, OPTS).action, "update");
+});
+
+// ---------------------------------------------------------------------------
+// AC-5 — only `failure` counts; cancelled/skipped are not failures
+// ---------------------------------------------------------------------------
+
+test("failingJobs counts only entries whose result is exactly `failure`", () => {
+  const needs = {
+    build: { result: "success" },
+    test: { result: "failure" },
+    deploy: { result: "cancelled" },
+    docs: { result: "skipped" },
+    lint: { result: "failure" },
+  };
+  assert.deepEqual(failingJobs(needs), ["lint", "test"]);
+});
+
+test("a job-results payload of only cancelled/skipped never yields CREATE", () => {
+  // A self-hosted fleet going down produces a wall of `cancelled` — raising an
+  // issue for that is precisely the noise this tracker exists to avoid.
+  const noise = { a: { result: "cancelled" }, b: { result: "skipped" }, c: { result: "success" } };
+  const failed = failingJobs(noise);
+  assert.deepEqual(failed, []);
+
+  const digest = computeDigest(failed);
+  assert.equal(
+    decideVerdict(null, { failedCount: failed.length, digest }, OPTS).action,
+    "noop",
+    "no open issue → nothing to do",
+  );
+  assert.equal(
+    decideVerdict(issueWithDigest(3, "d1"), { failedCount: failed.length, digest }, OPTS).action,
+    "close",
+    "an open issue is closed, because nothing is actually failing",
+  );
+});
+
+test("resolveConfig derives an empty failing set from an all-cancelled job payload", () => {
+  const cfg = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_JOB_RESULTS: JSON.stringify({ a: { result: "cancelled" }, b: { result: "skipped" } }),
+  });
+  assert.deepEqual(cfg.failedItems, []);
+  assert.equal(cfg.digest, "green-0");
+});
+
+// ---------------------------------------------------------------------------
+// AC-6 — unchanged-set behaviour is selectable, defaulting to today's posture
+// ---------------------------------------------------------------------------
+
+test("an unchanged digest is NOOP by default", () => {
+  const existing = issueWithDigest(42, "same-digest");
+  const v = decideVerdict(existing, { failedCount: 2, digest: "same-digest" }, OPTS);
+  assert.equal(v.action, "noop");
+  assert.equal(v.changed, false);
+});
+
+test("the same unchanged digest is UPDATE under `unchanged-behavior: refresh`", () => {
+  const existing = issueWithDigest(42, "same-digest");
+  const v = decideVerdict(
+    existing,
+    { failedCount: 2, digest: "same-digest" },
+    { ...OPTS, unchangedBehavior: "refresh" },
+  );
+  assert.equal(v.action, "update");
+  assert.equal(v.changed, false, "a refresh is not a change — it must not fire a change comment");
+});
+
+test("resolveConfig defaults unchanged-behavior to noop and rejects an unknown value", () => {
+  const base = { TRACK_MARKER: MARKER, TRACK_REPO: "acme/app" };
+  assert.equal(resolveConfig(base).unchangedBehavior, "noop");
+  assert.equal(resolveConfig({ ...base, TRACK_UNCHANGED_BEHAVIOR: "refresh" }).unchangedBehavior, "refresh");
+  assert.equal(
+    resolveConfig({ ...base, TRACK_UNCHANGED_BEHAVIOR: "shout" }).unchangedBehavior,
+    "noop",
+    "an unrecognised value falls back to the quiet posture rather than spamming",
+  );
+});
+
+// ---------------------------------------------------------------------------
+// Marker + digest contract
+// ---------------------------------------------------------------------------
+
+test("the action owns both marker lines and they round-trip through a body", () => {
+  const body = buildIssueBody({
+    marker: MARKER,
+    digestPrefix: PREFIX,
+    digest: "deadbeef",
+    intro: "watching the nightly",
+    detail: "one job is red",
+  });
+
+  assert.ok(body.includes(markerLine(MARKER)));
+  assert.equal(extractDigest(body, PREFIX), "deadbeef");
+  assert.equal(extractDigest("no markers here", PREFIX), null);
+  assert.match(body, /watching the nightly/);
+  assert.match(body, /one job is red/);
+});
+
+test("a marker supplied as a rendered comment is not double-wrapped", () => {
+  // A caller that hands over `<!-- k -->` must still produce `<!-- k -->` —
+  // a double-wrapped marker would never match the live issue again.
+  assert.equal(markerKey("<!-- acme:x -->"), "acme:x");
+  assert.equal(markerLine("<!-- acme:x -->"), "<!-- acme:x -->");
+});
+
+test("the legacy `--!>` comment terminator is stripped, not left in the key", () => {
+  // `--!>` closes an HTML comment just as `-->` does. A stripper blind to it
+  // leaves a stray `!` in the key, so the rendered marker stops matching the
+  // live issue and the next run opens a second one.
+  assert.equal(markerKey("<!-- acme:x --!>"), "acme:x");
+  assert.equal(markerLine("<!-- acme:x --!>"), "<!-- acme:x -->");
+});
+
+test("a digest marker closed with `--!>` is still recovered", () => {
+  assert.equal(extractDigest("<!-- acme:d: abc123 --!>", "acme:d:"), "abc123");
+});
+
+test("extractDigest skips non-matching comments and needs a single token", () => {
+  const body = [
+    "<!-- acme:nightly-tracker -->",
+    "<!-- unrelated: note -->",
+    "<!-- acme:d: two tokens -->",
+    "<!-- acme:d: realdigest -->",
+  ].join("\n");
+  assert.equal(extractDigest(body, "acme:d:"), "realdigest");
+  assert.equal(extractDigest("<!-- acme:d: -->", "acme:d:"), null);
+  assert.equal(extractDigest("<!-- acme:d: unterminated", "acme:d:"), null);
+});
+
+test("the digest prefix defaults from the marker but is overridable", () => {
+  assert.equal(defaultDigestPrefix(MARKER), "acme:nightly-tracker-digest:");
+  assert.match(digestMarker("abc", "custom:pfx:"), /<!-- custom:pfx: abc -->/);
+  assert.equal(extractDigest(digestMarker("abc", "custom:pfx:"), "custom:pfx:"), "abc");
+});
+
+test("a regex-special digest prefix is matched literally, not as a pattern", () => {
+  const prefix = "acme(v1).digest:";
+  assert.equal(extractDigest(digestMarker("xyz", prefix), prefix), "xyz");
+  assert.equal(extractDigest("<!-- acmeXv1Yxdigest: xyz -->", prefix), null);
+});
+
+test("body defaults fill in when the caller supplies no prose", () => {
+  const body = buildIssueBody({ marker: MARKER, digestPrefix: PREFIX, digest: "d" });
+  assert.ok(body.includes(DEFAULT_INTRO));
+  assert.match(body, /_\(no detail provided\)_/);
+  assert.ok(!body.includes("Latest run:"), "an absent run-url omits the line entirely");
+});
+
+test("a run-url is rendered only when supplied", () => {
+  const body = buildIssueBody({
+    marker: MARKER,
+    digestPrefix: PREFIX,
+    digest: "d",
+    runUrl: "https://example.invalid/run/1",
+  });
+  assert.match(body, /Latest run: https:\/\/example\.invalid\/run\/1/);
+});
+
+// ---------------------------------------------------------------------------
+// Digest derivation
+// ---------------------------------------------------------------------------
+
+test("computeDigest is order-independent and de-duplicating", () => {
+  assert.equal(computeDigest(["b", "a"]), computeDigest(["a", "b"]));
+  assert.equal(computeDigest(["a", "a", "b"]), computeDigest(["a", "b"]));
+  assert.notEqual(computeDigest(["a"]), computeDigest(["a", "b"]));
+  assert.match(computeDigest(["a"]), /^[0-9a-f]{12}$/);
+});
+
+test("computeDigest marks an empty set legibly rather than hashing nothing", () => {
+  assert.equal(computeDigest([]), "green-0");
+  assert.equal(computeDigest(undefined), "green-0");
+});
+
+// ---------------------------------------------------------------------------
+// Environment contract
+// ---------------------------------------------------------------------------
+
+test("failed-items takes precedence over job-results when both are supplied", () => {
+  const cfg = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_FAILED_ITEMS: JSON.stringify(["explicit"]),
+    TRACK_JOB_RESULTS: JSON.stringify({ ignored: { result: "failure" } }),
+  });
+  assert.deepEqual(cfg.failedItems, ["explicit"]);
+});
+
+test("an explicit digest wins over the derived one", () => {
+  const cfg = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_FAILED_ITEMS: JSON.stringify(["a"]),
+    TRACK_DIGEST: "caller-supplied",
+  });
+  assert.equal(cfg.digest, "caller-supplied");
+});
+
+test("malformed failed-items is an error, not a silently-empty failing set", () => {
+  // Swallowing a parse error here would CLOSE a live tracked issue while the
+  // failures it names are still happening.
+  const cfg = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_FAILED_ITEMS: "{not json",
+  });
+  assert.match(cfg.error, /TRACK_FAILED_ITEMS/);
+
+  const notAnArray = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_FAILED_ITEMS: '{"a":1}',
+  });
+  assert.match(notAnArray.error, /JSON string array/);
+});
+
+test("malformed job-results is an error rather than an empty failing set", () => {
+  const cfg = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_JOB_RESULTS: "{not json",
+  });
+  assert.match(cfg.error, /TRACK_JOB_RESULTS/);
+});
+
+test("resolveConfig splits labels and defaults the quiet knobs", () => {
+  const cfg = resolveConfig({
+    TRACK_MARKER: MARKER,
+    TRACK_REPO: "acme/app",
+    TRACK_LABELS: " ci , ,tracking ",
+  });
+  assert.deepEqual(cfg.labels, ["ci", "tracking"]);
+  assert.equal(cfg.commentOnChange, false);
+  assert.equal(cfg.dryRun, false);
+  assert.equal(cfg.branch, "main");
+  assert.equal(cfg.closeComment, DEFAULT_CLOSE_COMMENT);
+});
+
+test("renderEnvEntry escalates a multi-line value to the heredoc form", () => {
+  assert.equal(renderEnvEntry("K", "one"), "K=one\n");
+  const multi = renderEnvEntry("K", "one\ntwo");
+  assert.match(multi, /^K<<K_EOF_7f3a\none\ntwo\nK_EOF_7f3a\n$/);
+  assert.throws(() => renderEnvEntry("K", "a\nK_EOF_7f3a"), /delimiter/);
+});
+
+// ---------------------------------------------------------------------------
+// gh lookup
+// ---------------------------------------------------------------------------
+
+test("findTrackingIssue confirms the marker rather than trusting the search hint", () => {
+  const calls = [];
+  const runner = (args, opts) => {
+    calls.push({ args, opts });
+    // gh's `in:body` search is fuzzy — return one true match and one false positive.
+    return JSON.stringify([
+      { number: 99, body: "unrelated issue mentioning nightly-tracker in prose" },
+      { number: 100, body: `${markerLine(MARKER)}\n${digestMarker("x-1", PREFIX)}\nbody` },
+    ]);
+  };
+
+  const found = findTrackingIssue({ repo: "acme/app", labels: ["ci"], marker: MARKER }, runner);
+
+  assert.equal(found.number, 100);
+  assert.ok(calls[0].args.includes("--label"));
+  assert.ok(calls[0].args.includes("ci"));
+});
+
+test("findTrackingIssue returns null when nothing carries the marker", () => {
+  const runner = () => JSON.stringify([{ number: 1, body: "no marker" }]);
+  assert.equal(findTrackingIssue({ repo: "acme/app", labels: [], marker: MARKER }, runner), null);
+});
+
+test("findTrackingIssue surfaces a gh failure rather than reporting no issue", () => {
+  // Reporting "no issue" on a failed lookup would open a duplicate.
+  const runner = () => {
+    throw new Error("gh: not authenticated");
+  };
+  assert.throws(
+    () => findTrackingIssue({ repo: "acme/app", labels: [], marker: MARKER }, runner),
+    /gh issue list failed/,
+  );
+});