mandrel-platform 0.29.1 → 1.0.1

package/scripts/osv-report-gate.test.mjs

@@ -16,17 +16,25 @@ import {
   classify,
   findingsDigest,
   renderSummary,
+  normalizeSource,
+  rowKey,
+  buildBaselineSet,
   OsvGateError,
 } from "../.github/actions/osv-scan/osv-report-gate.mjs";
 
-// Build an OSV-scanner-shaped report for one grouped advisory.
-const reportWith = (groups) => ({
+// Build an OSV-scanner-shaped report for one grouped advisory. `published`
+// rides on the per-vulnerability entries, mirroring the real OSV schema —
+// group rows carry the severity, never the date.
+const reportWith = (groups, { sourcePath = "pnpm-lock.yaml" } = {}) => ({
   results: [
     {
-      source: { path: "pnpm-lock.yaml" },
+      source: { path: sourcePath },
       packages: groups.map((g) => ({
         package: { name: g.name, version: g.version || "1.0.0", ecosystem: g.ecosystem || "npm" },
         groups: [{ ids: g.ids, max_severity: g.score }],
+        ...(g.published
+          ? { vulnerabilities: g.ids.map((id) => ({ id, published: g.published })) }
+          : {}),
       })),
     },
   ],
@@ -225,3 +233,307 @@ test("renderSummary reports a clean scan and a blocked scan distinctly", () => {
   assert.match(blocked.join("\n"), /❌ BLOCKED/);
   assert.match(blocked.join("\n"), /GHSA-x/);
 });
+
+// ---------------------------------------------------------------------------
+// Diff-aware baseline + publish grace window (Story #325)
+//
+// The failure these close: a newly-published advisory against a dependency
+// that has been on `main` for weeks reds EVERY open PR simultaneously — the
+// postcss GHSA-r28c-9q8g-f849 / brace-expansion GHSA-mh99-v99m-4gvg incidents
+// on the swarm-os consumer. The gate must tell "this PR introduced it" from
+// "this was already here", without ever letting a real PR-introduced advisory
+// through and without neutering the operator-authored `revisitBy` re-gate.
+// ---------------------------------------------------------------------------
+
+// A baseline built from the SAME tree, as the merge-base worktree scan yields.
+const baselineOf = (groups, opts) => buildBaselineSet(collectRows(reportWith(groups, opts), opts));
+
+test("a finding already present at the baseline is demoted, not blocked", () => {
+  const groups = [{ name: "postcss", ids: ["GHSA-r28c-9q8g-f849"], score: "7.5" }];
+  const v = classify(collectRows(reportWith(groups)), {
+    failOn: "high",
+    baseline: baselineOf(groups),
+  });
+  assert.equal(v.blocking.length, 0);
+  assert.equal(v.preexisting.length, 1);
+  assert.equal(v.preexisting[0].ids[0], "GHSA-r28c-9q8g-f849");
+});
+
+test("a head-only finding is PR-introduced and still blocks", () => {
+  const v = classify(
+    collectRows(
+      reportWith([
+        { name: "postcss", ids: ["GHSA-r28c-9q8g-f849"], score: "7.5" },
+        { name: "brand-new-dep", ids: ["GHSA-new"], score: "8.2" },
+      ]),
+    ),
+    {
+      failOn: "high",
+      baseline: baselineOf([{ name: "postcss", ids: ["GHSA-r28c-9q8g-f849"], score: "7.5" }]),
+    },
+  );
+  assert.equal(v.blocking.length, 1);
+  assert.equal(v.blocking[0].name, "brand-new-dep");
+  assert.equal(v.preexisting.length, 1);
+  assert.equal(v.preexisting[0].name, "postcss");
+});
+
+test("bumping an advisory-bearing dep to another vulnerable version still blocks", () => {
+  // Same package, same advisory id — only the version moved. The baseline key
+  // carries @version precisely so this cannot inherit the demotion.
+  const v = classify(
+    collectRows(reportWith([{ name: "postcss", ids: ["GHSA-r28c"], score: "7.5", version: "8.4.0" }])),
+    {
+      failOn: "high",
+      baseline: baselineOf([
+        { name: "postcss", ids: ["GHSA-r28c"], score: "7.5", version: "8.3.0" },
+      ]),
+    },
+  );
+  assert.equal(v.blocking.length, 1);
+  assert.equal(v.blocking[0].version, "8.4.0");
+  assert.equal(v.preexisting.length, 0);
+});
+
+test("normalizeSource reduces worktree-rooted and workspace-rooted paths alike", () => {
+  assert.equal(normalizeSource("/tmp/osv-baseline/pnpm-lock.yaml", "/tmp/osv-baseline"), "pnpm-lock.yaml");
+  assert.equal(normalizeSource("/home/runner/work/repo/pnpm-lock.yaml", "/home/runner/work/repo"), "pnpm-lock.yaml");
+  assert.equal(normalizeSource("./pnpm-lock.yaml", "/tmp/osv-baseline"), "pnpm-lock.yaml");
+  assert.equal(normalizeSource("pnpm-lock.yaml", ""), "pnpm-lock.yaml");
+  // A trailing slash on the root must not leave a leading slash behind.
+  assert.equal(normalizeSource("/tmp/base/apps/web/pnpm-lock.yaml", "/tmp/base/"), "apps/web/pnpm-lock.yaml");
+});
+
+test("the baseline matches across differing scan roots", () => {
+  // The head scan runs in the workspace; the baseline scan runs in a git
+  // worktree at a different absolute path. Un-normalized, every head finding
+  // would look head-only and the diff-aware gate would block everything.
+  const groups = [{ name: "postcss", ids: ["GHSA-r28c"], score: "7.5" }];
+  const headRows = collectRows(
+    reportWith(groups, { sourcePath: "/home/runner/work/repo/pnpm-lock.yaml" }),
+    { scanRoot: "/home/runner/work/repo" },
+  );
+  const baseRows = collectRows(reportWith(groups, { sourcePath: "/tmp/osv-baseline/pnpm-lock.yaml" }), {
+    scanRoot: "/tmp/osv-baseline",
+  });
+  assert.equal(rowKey(headRows[0]), rowKey(baseRows[0]));
+
+  const v = classify(headRows, { failOn: "high", baseline: buildBaselineSet(baseRows) });
+  assert.equal(v.blocking.length, 0);
+  assert.equal(v.preexisting.length, 1);
+});
+
+test("an EXPIRED suppression outranks BOTH demotions and still re-gates", () => {
+  // The load-bearing precedence rule. An expired suppression is by
+  // construction on a pre-existing dependency, so letting either demotion
+  // apply would neuter `revisitBy` on PRs entirely.
+  //
+  // The fixture must be genuinely eligible for both demotions or this test
+  // passes vacuously: `published` is what puts the row inside the window, and
+  // without it `grace` is empty no matter how the precedence chain is wired.
+  const groups = [
+    {
+      name: "brace-expansion",
+      ids: ["GHSA-mh99-v99m-4gvg"],
+      score: "7.5",
+      published: "2026-07-22T00:00:00Z",
+    },
+  ];
+  const rows = collectRows(reportWith(groups));
+  const baseline = baselineOf(groups);
+  const opts = { failOn: "high", today: "2026-07-24", baseline, graceDays: 30 };
+
+  // Guard the fixture: with NO allow-list entry this row is demoted. If this
+  // ever stops holding, the assertion below has nothing left to prove.
+  const unsuppressed = classify(rows, opts);
+  assert.equal(unsuppressed.blocking.length, 0, "fixture must be demotable without an allow-list");
+  assert.equal(unsuppressed.preexisting.length, 1, "fixture must be baseline-eligible");
+  assert.notEqual(rows[0].published, null, "fixture must carry a publish date to be grace-eligible");
+
+  const v = classify(rows, {
+    ...opts,
+    allowlist: [{ id: "GHSA-mh99-v99m-4gvg", reason: "stale triage", revisitBy: "2026-01-01" }],
+  });
+  assert.equal(v.blocking.length, 1);
+  assert.equal(v.expired.length, 1);
+  assert.equal(v.preexisting.length, 0);
+  assert.equal(v.grace.length, 0);
+});
+
+test("an UNEXPIRED suppression stays suppressed and is not double-counted", () => {
+  const groups = [{ name: "brace-expansion", ids: ["GHSA-mh99-v99m-4gvg"], score: "7.5" }];
+  const v = classify(collectRows(reportWith(groups)), {
+    failOn: "high",
+    allowlist: [{ id: "GHSA-mh99-v99m-4gvg", reason: "not reachable", revisitBy: "2099-12-31" }],
+    today: "2026-07-24",
+    baseline: baselineOf(groups),
+  });
+  assert.equal(v.suppressed.length, 1);
+  assert.equal(v.blocking.length, 0);
+  assert.equal(v.preexisting.length, 0);
+});
+
+test("the grace window demotes a recent advisory and not an old one", () => {
+  const rows = collectRows(
+    reportWith([
+      { name: "fresh", ids: ["GHSA-fresh"], score: "8.0", published: "2026-07-21T00:00:00Z" },
+      { name: "stale", ids: ["GHSA-stale"], score: "8.0", published: "2026-06-24T00:00:00Z" },
+    ]),
+  );
+  const v = classify(rows, { failOn: "high", graceDays: 7, today: "2026-07-24" });
+  assert.deepEqual(
+    v.grace.map((r) => r.name),
+    ["fresh"],
+  );
+  assert.deepEqual(
+    v.blocking.map((r) => r.name),
+    ["stale"],
+  );
+});
+
+test("the grace window fails closed when the publish date is unresolvable", () => {
+  // No `published` on the vulnerability entries at all…
+  const undated = classify(collectRows(reportWith([{ name: "p", ids: ["GHSA-x"], score: "8.0" }])), {
+    failOn: "high",
+    graceDays: 7,
+    today: "2026-07-24",
+  });
+  assert.equal(undated.blocking.length, 1);
+  assert.equal(undated.grace.length, 0);
+
+  // …and a present-but-garbage date is equally not a free pass.
+  const garbage = classify(
+    collectRows(reportWith([{ name: "p", ids: ["GHSA-x"], score: "8.0", published: "not-a-date" }])),
+    { failOn: "high", graceDays: 7, today: "2026-07-24" },
+  );
+  assert.equal(garbage.blocking.length, 1);
+  assert.equal(garbage.grace.length, 0);
+});
+
+test("the grace window is off at the default of 0", () => {
+  const rows = collectRows(
+    reportWith([
+      { name: "fresh", ids: ["GHSA-fresh"], score: "8.0", published: "2026-07-23T00:00:00Z" },
+    ]),
+  );
+  const v = classify(rows, { failOn: "high", today: "2026-07-24" });
+  assert.equal(v.graceDays, 0);
+  assert.equal(v.grace.length, 0);
+  assert.equal(v.blocking.length, 1);
+});
+
+test("collectRows takes the EARLIEST published date across a group's aliased ids", () => {
+  const report = {
+    results: [
+      {
+        source: { path: "pnpm-lock.yaml" },
+        packages: [
+          {
+            package: { name: "p", version: "1.0.0", ecosystem: "npm" },
+            groups: [{ ids: ["GHSA-a", "CVE-b"], max_severity: "8.0" }],
+            vulnerabilities: [
+              { id: "GHSA-a", published: "2026-07-20T00:00:00Z" },
+              { id: "CVE-b", published: "2026-05-01T00:00:00Z" },
+            ],
+          },
+        ],
+      },
+    ],
+  };
+  assert.equal(collectRows(report)[0].published, "2026-05-01T00:00:00Z");
+
+  // …and the earliest date is what the window is judged against, so an alias
+  // published long ago cannot be laundered into the window by a fresh alias.
+  const v = classify(collectRows(report), { failOn: "high", graceDays: 7, today: "2026-07-24" });
+  assert.equal(v.blocking.length, 1);
+  assert.equal(v.grace.length, 0);
+});
+
+test("with no baseline and no grace window the partition is unchanged", () => {
+  // The backward-compatibility contract: default inputs must classify exactly
+  // as they did before diff-awareness existed.
+  const rows = collectRows(
+    reportWith([
+      { name: "crit", ids: ["C"], score: "9.9" },
+      { name: "hi", ids: ["H"], score: "7.1" },
+      { name: "med", ids: ["M"], score: "4.5" },
+      { name: "sup", ids: ["S"], score: "8.0" },
+    ]),
+  );
+  const allowlist = [{ id: "S", reason: "triaged", revisitBy: "2099-12-31" }];
+  const v = classify(rows, { failOn: "high", allowlist, today: "2026-07-24" });
+
+  assert.deepEqual(
+    v.blocking.map((r) => r.name),
+    ["crit", "hi"],
+  );
+  assert.deepEqual(
+    v.warning.map((r) => r.name),
+    ["med"],
+  );
+  assert.equal(v.suppressed.length, 1);
+  assert.equal(v.expired.length, 0);
+  // The new buckets exist but are inert.
+  assert.deepEqual(v.preexisting, []);
+  assert.deepEqual(v.grace, []);
+  assert.equal(v.baselineApplied, false);
+});
+
+test("findingsDigest ignores preexisting and grace rows entirely", () => {
+  // The scheduled tracking issue keys off this digest; a PR-side demotion must
+  // not rewrite the issue body or make an unchanged advisory set look new.
+  const groups = [
+    { name: "p1", ids: ["GHSA-a"], score: "7.5" },
+    { name: "p2", ids: ["GHSA-b"], score: "9.1", published: "2026-07-23T00:00:00Z" },
+  ];
+  const plain = classify(collectRows(reportWith(groups)), { failOn: "high", today: "2026-07-24" });
+  const demoted = classify(collectRows(reportWith(groups)), {
+    failOn: "high",
+    today: "2026-07-24",
+    baseline: baselineOf([groups[0]]),
+    graceDays: 7,
+  });
+
+  assert.equal(demoted.blocking.length, 0);
+  assert.equal(demoted.preexisting.length, 1);
+  assert.equal(demoted.grace.length, 1);
+  assert.equal(findingsDigest(demoted.blocking), findingsDigest([]));
+  assert.notEqual(findingsDigest(plain.blocking), findingsDigest(demoted.blocking));
+});
+
+test("renderSummary names both demotion buckets with one table row each", () => {
+  const groups = [
+    { name: "postcss", ids: ["GHSA-r28c-9q8g-f849"], score: "7.5" },
+    { name: "fresh", ids: ["GHSA-fresh"], score: "8.0", published: "2026-07-23T00:00:00Z" },
+  ];
+  const v = classify(collectRows(reportWith(groups)), {
+    failOn: "high",
+    today: "2026-07-24",
+    baseline: baselineOf([groups[0]]),
+    graceDays: 7,
+  });
+  const out = renderSummary(v).join("\n");
+
+  assert.match(out, /Pre-existing on the base branch — not introduced by this PR \(1\)/);
+  assert.match(out, /Within the publish grace window \(1\)/);
+  assert.match(out, /GHSA-r28c-9q8g-f849/);
+  assert.match(out, /GHSA-fresh/);
+  // Demotions are not a pass-with-nothing-to-say: the verdict line must not
+  // claim BLOCKED when everything was demoted.
+  assert.doesNotMatch(out, /❌ BLOCKED/);
+  // The grace table carries the publish date that justified the demotion.
+  assert.match(out, /\| 2026-07-23T00:00:00Z \|/);
+});
+
+test("a fully-demoted verdict set is not rendered as a clean scan", () => {
+  // Demoted findings still have to be visible — silently reporting "no known
+  // advisories" would hide exactly what the diff-aware mode chose not to gate.
+  const groups = [{ name: "postcss", ids: ["GHSA-r28c"], score: "7.5" }];
+  const v = classify(collectRows(reportWith(groups)), {
+    failOn: "high",
+    baseline: baselineOf(groups),
+  });
+  const out = renderSummary(v).join("\n");
+  assert.doesNotMatch(out, /no known advisories/);
+  assert.match(out, /GHSA-r28c/);
+});

package/scripts/platform-sync.mjs

@@ -197,6 +197,52 @@ function log(msg) {
   if (!opts.json) process.stdout.write(`${msg}\n`);
 }
 
+// ---------------------------------------------------------------------------
+// Filesystem access — perform, don't pre-check (Story #337)
+// ---------------------------------------------------------------------------
+//
+// Every read in this script used to be guarded by `existsSync(p)` before
+// `readFileSync(p)` / `readdirSync(p)`. That check-then-use shape is a
+// time-of-check/time-of-use race (CodeQL js/file-system-race, high) — the path
+// can change between the two calls, and the code then acts on a stale answer.
+// It is also lossy in a way that matters here: `existsSync` returns false for
+// a path that exists but cannot be stat'd, so a permission or type error was
+// silently reinterpreted as "absent" and the script took its create branch.
+//
+// These helpers invert it: attempt the operation, and treat ONLY `ENOENT` as
+// "not there". Every other error (EACCES, EISDIR, ELOOP, …) propagates, which
+// is both race-free and strictly more informative. One syscall, not two.
+
+/**
+ * Read a UTF-8 file, or `null` when it does not exist.
+ *
+ * @param {string} path
+ * @returns {string|null}
+ */
+function readFileIfPresent(path) {
+  try {
+    return readFileSync(path, "utf8");
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
+/**
+ * List a directory's entries, or `null` when it does not exist.
+ *
+ * @param {string} path
+ * @returns {string[]|null}
+ */
+function readdirIfPresent(path) {
+  try {
+    return readdirSync(path);
+  } catch (err) {
+    if (err.code === "ENOENT") return null;
+    throw err;
+  }
+}
+
 // ---------------------------------------------------------------------------
 // Defaults requiring resolution
 // ---------------------------------------------------------------------------
@@ -282,8 +328,9 @@ function resolveSha() {
 /** Recursively collect `.yml`/`.yaml` files under a directory. */
 function collectYaml(dir) {
   const found = [];
-  if (!existsSync(dir)) return found;
-  for (const entry of readdirSync(dir)) {
+  const entries = readdirIfPresent(dir);
+  if (entries === null) return found;
+  for (const entry of entries) {
     const full = join(dir, entry);
     const st = statSync(full);
     if (st.isDirectory()) found.push(...collectYaml(full));
@@ -401,17 +448,18 @@ function materializeRunbooks() {
   const created = [];
   const skipped = [];
   const localCopies = [];
-  if (!existsSync(runbookTemplatesDir)) {
+  const templates = readdirIfPresent(runbookTemplatesDir);
+  if (templates === null) {
     fail(`runbook templates not found at ${runbookTemplatesDir}.`);
   }
   const destDir = join(opts.consumer, "docs", "runbooks");
-  for (const entry of readdirSync(runbookTemplatesDir)) {
+  for (const entry of templates) {
     if (!entry.endsWith(".md")) continue;
     if (entry.toLowerCase() === "readme.md") continue; // index, not a stub
     const src = join(runbookTemplatesDir, entry);
     const dest = join(destDir, entry);
-    if (existsSync(dest)) {
-      const body = readFileSync(dest, "utf8");
+    const body = readFileIfPresent(dest);
+    if (body !== null) {
       if (body.includes(STUB_MARKER)) {
         skipped.push(rel(dest)); // already a reference stub — idempotent no-op
       } else {
@@ -451,16 +499,19 @@ function materializeWorkflowStubs() {
   const created = [];
   const skipped = [];
   const localCopies = [];
-  if (!existsSync(workflowTemplatesDir)) {
+  // Unlike the runbook templates above, an absent workflow-template directory
+  // is a soft no-op rather than a fatal — preserved exactly.
+  const templates = readdirIfPresent(workflowTemplatesDir);
+  if (templates === null) {
     return { created, skipped, localCopies };
   }
   const destDir = join(opts.consumer, ".github", "workflows");
-  for (const entry of readdirSync(workflowTemplatesDir)) {
+  for (const entry of templates) {
     if (!/\.ya?ml$/.test(entry)) continue;
     const src = join(workflowTemplatesDir, entry);
     const dest = join(destDir, entry);
-    if (existsSync(dest)) {
-      const body = readFileSync(dest, "utf8");
+    const body = readFileIfPresent(dest);
+    if (body !== null) {
       if (body.includes(WORKFLOW_TEMPLATE_MARKER)) {
         skipped.push(rel(dest)); // already materialized — idempotent no-op
       } else {
@@ -501,11 +552,26 @@ function reconcileRenovate() {
     ".github/renovate.json",
     ".renovaterc.json",
   ].map((p) => join(opts.consumer, p));
-  const path = candidates.find((p) => existsSync(p));
-  if (!path) return { action: "absent", file: null };
+  // Read-through rather than find-then-read: the first candidate that yields
+  // content IS the config, with no window in which it can vanish between the
+  // probe and the read.
+  let path = null;
+  let raw = null;
+  for (const candidate of candidates) {
+    try {
+      raw = readFileIfPresent(candidate);
+    } catch (err) {
+      fail(`could not read Renovate config at ${rel(candidate)}: ${err.message}`);
+    }
+    if (raw !== null) {
+      path = candidate;
+      break;
+    }
+  }
+  if (path === null) return { action: "absent", file: null };
   let cfg;
   try {
-    cfg = parseJsonc(readFileSync(path, "utf8"));
+    cfg = parseJsonc(raw);
   } catch (err) {
     fail(`could not parse Renovate config at ${rel(path)}: ${err.message}`);
   }
@@ -521,10 +587,18 @@ function reconcileRenovate() {
 
 function reconcileTsconfig() {
   const path = join(opts.consumer, "tsconfig.json");
-  if (!existsSync(path)) return { action: "absent", file: null };
+  // Read and parse failures are reported separately: conflating them (as the
+  // old check-then-read did) reported an unreadable file as a parse error.
+  let raw;
+  try {
+    raw = readFileIfPresent(path);
+  } catch (err) {
+    fail(`could not read tsconfig at ${rel(path)}: ${err.message}`);
+  }
+  if (raw === null) return { action: "absent", file: null };
   let cfg;
   try {
-    cfg = parseJsonc(readFileSync(path, "utf8"));
+    cfg = parseJsonc(raw);
   } catch (err) {
     fail(`could not parse tsconfig at ${rel(path)}: ${err.message}`);
   }

package/scripts/platform-sync.test.mjs

@@ -642,3 +642,128 @@ test("a hand-authored deploy-staging.yml is flagged, not overwritten", () => {
     "operator's hand-authored caller is never clobbered"
   );
 });
+
+// ---------------------------------------------------------------------------
+// Filesystem access — perform, don't pre-check (Story #337)
+//
+// Every read used to be guarded by `existsSync(p)` before `readFileSync(p)` —
+// a time-of-check/time-of-use race (CodeQL js/file-system-race, high) that
+// also collapsed "unreadable" into "absent". These pin the replacement
+// contract: ENOENT still means absent, and every other error is reported as a
+// READ failure rather than being mistaken for a missing file or a parse error.
+// ---------------------------------------------------------------------------
+
+/** Run the CLI expecting a non-zero exit; return the combined output. */
+function runExpectingFailure(extraArgs) {
+  try {
+    run(extraArgs);
+  } catch (err) {
+    return `${err.stdout ?? ""}${err.stderr ?? ""}`;
+  }
+  assert.fail("expected the CLI to exit non-zero");
+}
+
+test("an absent tsconfig is reported absent, not as an error", () => {
+  rmSync(join(consumer, "tsconfig.json"));
+  const out = JSON.parse(run([]));
+  assert.equal(out.tsconfig.action, "absent");
+  assert.equal(out.tsconfig.file, null);
+});
+
+test("an absent renovate config is reported absent, not as an error", () => {
+  rmSync(join(consumer, "renovate.json"));
+  const out = JSON.parse(run([]));
+  assert.equal(out.renovate.action, "absent");
+  assert.equal(out.renovate.file, null);
+});
+
+test("an unreadable tsconfig fails as a READ error, never as absent", () => {
+  // A directory where the file should be is the portable stand-in for an
+  // unreadable path (EISDIR). The old shape reported this as a *parse*
+  // failure, because the read happened inside the parse try/catch.
+  rmSync(join(consumer, "tsconfig.json"));
+  mkdirSync(join(consumer, "tsconfig.json"));
+  const out = runExpectingFailure([]);
+  assert.match(out, /could not read tsconfig/);
+  assert.doesNotMatch(out, /could not parse tsconfig/);
+});
+
+test("an unreadable renovate config fails as a READ error, never as absent", () => {
+  rmSync(join(consumer, "renovate.json"));
+  mkdirSync(join(consumer, "renovate.json"));
+  const out = runExpectingFailure([]);
+  assert.match(out, /could not read Renovate config/);
+  assert.doesNotMatch(out, /could not parse Renovate config/);
+});
+
+test("a malformed tsconfig still fails as a PARSE error", () => {
+  // The read/parse split must not blur the other way either.
+  writeFileSync(join(consumer, "tsconfig.json"), "{ not json at all");
+  const out = runExpectingFailure([]);
+  assert.match(out, /could not parse tsconfig/);
+  assert.doesNotMatch(out, /could not read tsconfig/);
+});
+
+test("an existing runbook stub is skipped, an unreadable one is not silently created", () => {
+  // First pass materializes; second must skip via the read, not a pre-check.
+  run([]);
+  const stub = join(consumer, "docs", "runbooks", "observability.md");
+  const body = readFileSync(stub, "utf8");
+  const out = JSON.parse(run([]));
+  assert.ok(
+    out.runbooks.skipped.some((f) => f.endsWith("observability.md")),
+    "already-materialized stub is skipped on the second pass"
+  );
+  assert.equal(readFileSync(stub, "utf8"), body, "skipped stub is byte-identical");
+  assert.equal(out.runbooks.created.length, 0);
+});
+
+test("no read in the sync path is guarded by a prior existence check", () => {
+  // The regression guard for the defect class itself: `existsSync` may survive
+  // only as the import and the one CLI-argument precondition that has no
+  // paired read. Anything else is a reintroduced check-then-use race.
+  const source = readFileSync(join(__dirname, "platform-sync.mjs"), "utf8");
+  const uses = source
+    .split("\n")
+    .map((line, i) => ({ line, n: i + 1 }))
+    .filter(({ line }) => /(?<![A-Za-z])existsSync\s*\(/.test(line))
+    .filter(({ line }) => !/^\s*(\/\/|\*)/.test(line));
+  assert.equal(
+    uses.length,
+    1,
+    `expected exactly one existsSync call site (the --consumer precondition); found: ${JSON.stringify(
+      uses
+    )}`
+  );
+  assert.match(uses[0].line, /opts\.consumer/);
+});
+
+test("a missing runbook-template dir fails with the message naming it, not a raw ENOENT", () => {
+  // The precondition is fatal by design. Converting the guard to a
+  // perform-then-classify read must not degrade it to an unhandled ENOENT.
+  const emptyTemplates = mkdtempSync(join(tmpdir(), "platform-sync-templates-"));
+  try {
+    const out = runExpectingFailure(["--templates", emptyTemplates]);
+    assert.match(out, /runbook templates not found at/);
+    assert.ok(out.includes(join(emptyTemplates, "runbooks")), "names the directory it looked in");
+    assert.doesNotMatch(out, /ENOENT/, "no raw errno leaks to the operator");
+  } finally {
+    rmSync(emptyTemplates, { recursive: true, force: true });
+  }
+});
+
+test("a missing workflow-template dir is a soft no-op, not a failure", () => {
+  // Deliberately NOT symmetrical with the runbook precondition above: an
+  // absent workflow-template directory yields an empty result set rather than
+  // a fatal. Pinned so the read conversion cannot quietly make it fatal.
+  const templates = mkdtempSync(join(tmpdir(), "platform-sync-templates-"));
+  try {
+    mkdirSync(join(templates, "runbooks"), { recursive: true });
+    const out = JSON.parse(run(["--templates", templates]));
+    assert.deepEqual(out.workflowStubs.created, []);
+    assert.deepEqual(out.workflowStubs.skipped, []);
+    assert.deepEqual(out.workflowStubs.localCopies, []);
+  } finally {
+    rmSync(templates, { recursive: true, force: true });
+  }
+});