mandrel-platform 1.0.0 → 1.1.0

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 });
+  }
+});

package/templates/runbooks/runner-provisioning.md

@@ -150,9 +150,18 @@ with the runner root's absolute path. The resulting file wires:
 
 - `ACTIONS_RUNNER_HOOK_JOB_STARTED=<RUNNER_DIR>/job-cleanup.sh` — the
   job-start hook. It reaps orphaned pnpm/node processes parented to **this**
-  runner's work tree, clears stale runner-scoped pnpm installs, and
-  age-gate-sweeps shared-`$TMPDIR` gitleaks leftovers. It never fails a job
-  (always exits 0) and never touches another runner's state.
+  runner's work tree, clears stale runner-scoped pnpm installs, and removes
+  leftover tool-download dirs from `<RUNNER_DIR>/_work/_temp`. It never fails
+  a job (always exits 0) and never touches another runner's state.
+
+  **Every path it reads is runner-scoped, and that is load-bearing** (issue
+  #343). The hook runs inside the *job's* clock, so its cost is charged to
+  `Set up runner` and counts against the job's own `timeout-minutes`. An
+  earlier version swept the host-shared OS temp root; on a host where that
+  directory had grown to ~840k entries, `Set up runner` reached 5m29s and
+  jobs were killed before their first real step — surfacing as `cancelled`
+  on unrelated diffs. If you add a sweep to this hook, root it at
+  `_work/_temp`, never at `$TMPDIR`.
 - `RUNNER_TOOL_CACHE=<RUNNER_DIR>/_work/_tool` and
   `AGENT_TOOLSDIRECTORY=<RUNNER_DIR>/_work/_tool` — runner-scoped tool cache
   (two env names, one dir; some actions read the legacy name).

package/templates/runner/.env.example

@@ -19,8 +19,14 @@ LANG=en_US.UTF-8
 
 # Job-start hygiene hook. Runs templates/runner/job-cleanup.sh (installed
 # into the runner root) before every job: reaps orphaned pnpm/node processes
-# from THIS runner's work tree and clears stale install/temp artifacts.
-# The hook is runner-scoped and never fails the job (always exits 0).
+# from THIS runner's work tree and clears stale install/temp artifacts from
+# `_work/_temp`. The hook is runner-scoped and never fails the job (always
+# exits 0).
+#
+# Runner-scoped means CHEAP as well as safe: the hook runs inside the job's
+# clock, so anything it reads is billed to `Set up runner` and counts against
+# the job's `timeout-minutes`. It touches only this runner's own paths, so its
+# cost never becomes a function of host-wide temp churn (issue #343).
 ACTIONS_RUNNER_HOOK_JOB_STARTED=<RUNNER_DIR>/job-cleanup.sh
 
 # Runner-scoped tool cache. Without this, actions/setup-node & friends

package/templates/runner/job-cleanup.sh

@@ -10,8 +10,8 @@
 #
 #   - an orphaned `pnpm`/`node` process (e.g. a hung install or lint) still
 #     mutating the pnpm shim install, corrupting the pnpm CLI for the next job;
-#   - leftover `gitleaks.tmp` / `gitleaks-*` artifacts in the shared $TMPDIR
-#     blocking the next gitleaks download.
+#   - leftover tool-download temp dirs (gitleaks, OSV-scanner, the semgrep
+#     venv) accumulating in the runner's own job temp.
 #
 # Running this before every job gives each job a clean slate ("fresh per job"
 # without the cost of re-registering an ephemeral runner).
@@ -35,9 +35,36 @@
 #      own work tree (`<RUNNER_DIR>/_work/...`). Every path below derives
 #      from RUNNER_DIR, which is unique per runner, so a co-resident
 #      runner's processes and files are never matched.
-#   3. Age-gates cleanup of the genuinely shared $TMPDIR gitleaks artifacts,
-#      so a fresh (in-flight) download owned by a concurrent job is never
-#      deleted — only stale leftovers are.
+#   3. NEVER READS the shared OS temp root, either. Reading is not free: the
+#      hook runs inside the JOB's clock, so any cost here is charged to
+#      `Set up runner` and counts against the job's own `timeout-minutes`.
+#      $TMPDIR is unbounded and shared with every other process on the host,
+#      so a sweep rooted there costs a function of how much UNRELATED junk
+#      the host has accumulated — see the incident note below.
+#
+# ── WHY THE SHARED-$TMPDIR SWEEP IS GONE (issue #343) ───────────────────────
+#
+# This hook used to age-gate two `find "$TMPDIR" -maxdepth 1 -name …` sweeps
+# for `gitleaks.tmp` / `gitleaks-*`. `-maxdepth 1 -name <literal>` is a FULL
+# directory enumeration for what is really an existence check, so its cost
+# scaled with host churn. On the swarm-os runner host $TMPDIR reached 841,690
+# entries; one scan measured 42s, the hook ran two of them, and up to 16
+# co-resident runners ran it concurrently. `Set up runner` reached 5m29s, and
+# every job whose `timeout-minutes` sat at or below that was killed before its
+# first real step — surfacing as `cancelled` on an innocent diff.
+#
+# It was also a no-op: the platform's actions extract via `mktemp -d`, so
+# nothing ever created `gitleaks.tmp` or `gitleaks-*`. The sweep paid an
+# unbounded cost hunting names that never existed, while the dirs the actions
+# DID leave went unswept.
+#
+# The fix is ownership, not tuning: every platform action now extracts into
+# `${RUNNER_TEMP}` (== RUNNER_TMP below), which is unique per runner. A
+# co-resident runner's in-flight download is therefore unreachable from here
+# by construction — which is what retired the age gate outright (along with
+# the stale-minutes env knob that tuned it), rather than merely shrinking its
+# blast radius. Keep it that way: a sweep added here MUST be rooted at
+# RUNNER_TMP.
 #
 # ── PARAMETERIZATION ────────────────────────────────────────────────────────
 #
@@ -48,11 +75,8 @@
 #                  runner root, next to config.sh / run.sh). Override via env
 #                  only if you install the hook elsewhere.
 #   RUNNER_TMP   — the runner's per-runner job temp (`runner.temp`), always
-#                  `${RUNNER_DIR}/_work/_temp`.
-#   JOB_CLEANUP_STALE_MINUTES
-#                — age threshold (minutes) for the shared-$TMPDIR gitleaks
-#                  sweep. Default 60. Artifacts younger than this are assumed
-#                  in-flight and left alone.
+#                  `${RUNNER_DIR}/_work/_temp`. Every path this hook touches
+#                  lives under it.
 #
 # Configured via `ACTIONS_RUNNER_HOOK_JOB_STARTED=<RUNNER_DIR>/job-cleanup.sh`
 # in the runner's `.env` (see .env.example in this directory).
@@ -64,8 +88,6 @@ set +e
 RUNNER_DIR="${RUNNER_DIR:-$(cd "$(dirname "$0")" && pwd)}"
 RUNNER_WORK="${RUNNER_DIR}/_work"
 RUNNER_TMP="${RUNNER_WORK}/_temp"
-TMP="${TMPDIR:-/tmp}"
-STALE_MINUTES="${JOB_CLEANUP_STALE_MINUTES:-60}"
 
 # 1) Reap orphaned pnpm/node processes from prior jobs — scoped to THIS
 #    runner's work tree only. The patterns target executable paths INSIDE the
@@ -85,13 +107,20 @@ pkill -9 -f "${RUNNER_WORK}/_tool/[^ ]*node_modules" 2>/dev/null
 rm -rf "${RUNNER_TMP}/pnpm"       2>/dev/null
 rm -rf "${RUNNER_TMP}/setup-pnpm" 2>/dev/null
 
-# 3) Sweep stale gitleaks artifacts from the SHARED $TMPDIR. Because this
-#    location is shared by every runner on the host, deletion is age-gated:
-#    only artifacts older than STALE_MINUTES are removed, so a concurrent
-#    runner's in-flight download is never deleted mid-job.
-find "${TMP}" -maxdepth 1 -name 'gitleaks.tmp' -mmin "+${STALE_MINUTES}" \
-  -exec rm -f  {} + 2>/dev/null
-find "${TMP}" -maxdepth 1 -name 'gitleaks-*'   -mmin "+${STALE_MINUTES}" \
-  -exec rm -rf {} + 2>/dev/null
+# 3) Remove this runner's own leftover tool-download temp dirs. The platform's
+#    composite actions and workflows create these via
+#    `mktemp -d "${RUNNER_TEMP}/<tool>.XXXXXX"`, so every one of them is
+#    runner-scoped and a co-resident runner's in-flight download is
+#    unreachable here — no age gate is needed (see the issue #343 note above).
+#
+#    Globbing is what keeps this bounded: the shell expands these against
+#    RUNNER_TMP alone, so the cost is a function of THIS runner's leftovers,
+#    never of host-wide churn. Do not replace it with a `find` over a parent.
+#    A glob that matches nothing stays literal, and `rm -rf` on a nonexistent
+#    path is silent — hence the nullglob-free form plus 2>/dev/null.
+rm -rf "${RUNNER_TMP}"/gitleaks.*    2>/dev/null
+rm -rf "${RUNNER_TMP}"/osv-scanner.* 2>/dev/null
+rm -rf "${RUNNER_TMP}"/semgrep.*     2>/dev/null
+rm -f  "${RUNNER_TMP}"/gh-api-err.*  2>/dev/null
 
 exit 0