@bongos/core 1.19.762 → 1.19.763

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.762",
-  "core_contract": "1.19.762",
-  "source_commit": "4235a1ef680b4e7b79d8e61dc88b68069bc48d5f",
+  "core_version": "1.19.763",
+  "core_contract": "1.19.763",
+  "source_commit": "d56c0dce70d9d91b47d04673af4ed036f6456415",
   "source_ref": "HEAD",
-  "built_at": "2026-09-16T03:56:12.759Z",
+  "built_at": "2026-09-16T04:43:46.371Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 483,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2116,
+    "functional_verbatim": 2117,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2624,
-  "tree_sha256": "7561f06e166d4cb1fa763b4771e03e57bba45299206df6dc706609de095557a3",
+  "file_count": 2625,
+  "tree_sha256": "d1d3bb6923feb8c9a3191045a69e641c553b0ac0d9ca4b973e8f0f63c48b67d9",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2512,7 +2512,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "6eafab6b4df93ff7ed5abfb7c2d7ed203d4a277cb9533fa262653e6ada53a4de"
+      "sha256": "ef6513a9bb60c6532ad6b981c24e7e867aaeb75a85d874b7d6e67842de9cda5a"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7567,12 +7567,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b20ee554299dfd5a29d5877d1eb9df41f460d30f1db26526485b4588228ef2e3"
+      "sha256": "3331982a91d6104fac63e458b3f10d7fb6e1388ba91a8ebf2245019e5d056720"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "222eb11d6d265b2235b1a7455707bc9bc9aa2210bcec0deb34dcbfdc12de784d"
+      "sha256": "da63833600ca5e2e1d01eb5e6382bd53896d586f0f5b4e899b8616bd854f3009"
     },
     {
       "path": "public-docs/index.html",
@@ -7707,7 +7707,7 @@
     {
       "path": "scripts/gds/audit-ships.js",
       "mode": "0000644",
-      "sha256": "8dbba68d9b8c0635263f3dfb4a223edb14621fb715aa9ab603ea8220313f9dfa"
+      "sha256": "ffcb9068753855fcb0c1ea5c69fddbe97c4c5cb72f225ec38ca4c599d5aca24a"
     },
     {
       "path": "scripts/gds/autonomy-gate.js",
@@ -9382,7 +9382,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "9fca9034c480450daf57672bfecc9c7d09f8105fddd88d81ef8e46d025903cac"
+      "sha256": "d57ef047cc14ac346694d7a0507103b2b2b85583553786a3c21ba6aacac329c2"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9654,6 +9654,11 @@
       "mode": "0000644",
       "sha256": "4973872431cb0e5e7aedb978f4d5b28f804fe33aa8288f16d2656a28c85befbe"
     },
+    {
+      "path": "tests/audit_ships_git_argv.mjs",
+      "mode": "0000644",
+      "sha256": "bb7f06a866ccea00a88d2f373c70f7e4bc0a3aa5e658c61346046b83637baa35"
+    },
     {
       "path": "tests/auth_admission_gate.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1998,5 +1998,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.760 with no explicit bump. run 35052410219. (task 1002620)
   1.19.762 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.761 with no explicit bump. run 35053643269. (task 1002620)
+  1.19.763 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.762 with no explicit bump. run 35056690992. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.762",
+  "version": "1.19.763",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.19.762",
+      "version": "1.19.763",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.762",
+  "version": "1.19.763",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/scripts/gds/audit-ships.js

@@ -9,35 +9,92 @@
 // Audit-only — does NOT write to task_grades. Pre-grader ships keep clean
 // history.
 
-const { execSync } = require('node:child_process');
+const { execFileSync } = require('node:child_process');
 const grader = require('../../modules/grading/grader');
 const { cliClient } = require('./cli-lib');
 
+// EVERY git call here goes through argv, never a shell string (task 1003223 —
+// the class task 1002761 named and task 1002526 fixed in docs-entropy).
+//
+// WHAT WAS WRONG. Five call sites built shell strings. THREE of them interpolated
+// a quoted empty `--format=''`; a POSIX shell strips those quotes and git sees an
+// empty format, but the shell Node uses on Windows does not, so git receives
+// `--format=''` literally and dies with `fatal: invalid --pretty format: ''`.
+// Verified on win32 before fixing: the shell-string form throws, the argv form
+// returns " 1 file changed, 139 insertions(+)". The correct argv spelling is
+// `--format=` — empty value, no quotes, which no shell can mangle because no
+// shell is involved. The other two passed `--format='%H %s'`, which survives a
+// POSIX shell and arrives with literal quotes elsewhere; same class, same fix.
+//
+// WHY IT MATTERED MORE THAN A LOUD CRASH. The originating row asked whether the
+// try/catch around these calls "degrades to a silently empty audit — if so it is
+// the same dangerous shape after all". It did. Every catch returned null or [],
+// so on Windows the audit reported no diff stats and zero downstream impact for
+// EVERY ship, and looked like a clean run. `gitFails` below keeps the same return
+// values but says so on stderr, so an empty audit can never again be mistaken for
+// an uneventful one.
+//
+// One of the five also built a `grep | head | awk` pipeline and pinned
+// `shell: '/bin/bash'` to survive; that filtering is now done in JS, so the script
+// needs no shell at all.
+function gitLines(args, { cwd } = {}) {
+  return execFileSync('git', args, { cwd, encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 })
+    .split('\n').map((s) => s.trim()).filter(Boolean);
+}
+
+// One place that reports a git failure instead of swallowing it. Returns the
+// caller's fallback so behaviour is unchanged; only the silence is.
+function gitFails(what, err, fallback) {
+  const msg = String((err && (err.stderr || err.message)) || err).trim().split('\n')[0];
+  console.error(`audit-ships: ${what} failed — ${msg}`);
+  return fallback;
+}
+
 const DAYS = Number(process.env.AUDIT_DAYS || 2);
 
+// `git log --all` once per RUN, not once per task.
+//
+// The shell pipeline this replaced ended in `head -1`, which let git stop as soon
+// as one subject matched. The argv rewrite has no such early exit — and
+// findCommitForTask is called once per shipped task, up to 500 in a run — so a
+// naive port turned one bounded call into 500 full history walks. The commit list
+// cannot change mid-run, so it is read once and reused. Caught by the grader on
+// the first round of this task, which is a fair catch: replacing a shell pipeline
+// means inheriting the work its operators were doing, not just its output.
+let commitSubjectsCache = null;
+function commitSubjects() {
+  if (commitSubjectsCache) return commitSubjectsCache;
+  commitSubjectsCache = gitLines(['log', '--all', '--format=%H %s']);
+  return commitSubjectsCache;
+}
+
 function findCommitForTask(taskId) {
-  let sha;
+  // Matches both subject conventions: the legacy ' #NNN:' prefix and the de-#-ed
+  // 'task NNN:' form ship.js writes since task 916 (a bare "#NNN" in commit
+  // subjects autolinked to dead GitHub issue numbers).
+  //
+  // The grep|head|awk pipeline this replaces needed `shell: '/bin/bash'` to run at
+  // all — a hard dependency on a POSIX shell at a fixed path, for filtering JS can
+  // do. Doing it here also makes the id match EXACT: the old regex was
+  // interpolated unescaped, so a task id was pasted straight into a regex.
+  const re = new RegExp(` (?:#|task )${String(taskId).replace(/[^0-9]/g, '')}:`);
+  let lines;
   try {
-    sha = execSync(
-      // Matches both subject conventions: the legacy ' #NNN:' prefix and the
-      // de-#-ed 'task NNN:' form ship.js writes since task 916 (a bare "#NNN"
-      // in commit subjects autolinked to dead GitHub issue numbers).
-      `git log --all --format='%H %s' | grep -E ' (#|task )${taskId}:' | head -1 | awk '{print $1}'`,
-      { encoding: 'utf8', shell: '/bin/bash' }
-    ).trim();
-  } catch (_) {
-    return null;
+    lines = commitSubjects();
+  } catch (e) {
+    return gitFails(`finding the commit for task ${taskId}`, e, null);
   }
-  return sha || null;
+  const hit = lines.find((l) => re.test(l));
+  return hit ? (hit.split(' ')[0] || null) : null;
 }
 
 function gitDiffStatsForCommit(sha) {
   if (!sha) return null;
   let raw;
   try {
-    raw = execSync(`git show --shortstat --format='' ${sha}`, { encoding: 'utf8' });
-  } catch (_) {
-    return null;
+    raw = execFileSync('git', ['show', '--shortstat', '--format=', sha], { encoding: 'utf8' });
+  } catch (e) {
+    return gitFails(`reading diff stats for ${String(sha).slice(0, 8)}`, e, null);
   }
   // Example shortstat line: " 15 files changed, 1171 insertions(+), 65 deletions(-)"
   const m = raw.match(/(\d+) files? changed(?:, (\d+) insertions?\(\+\))?(?:, (\d+) deletions?\(-\))?/);
@@ -53,10 +110,9 @@ function gitDiffStatsForCommit(sha) {
 function filesTouchedByCommit(sha) {
   if (!sha) return [];
   try {
-    const out = execSync(`git show --name-only --format='' ${sha}`, { encoding: 'utf8' });
-    return out.split('\n').map((s) => s.trim()).filter(Boolean);
-  } catch (_) {
-    return [];
+    return gitLines(['show', '--name-only', '--format=', sha]);
+  } catch (e) {
+    return gitFails(`listing files touched by ${String(sha).slice(0, 8)}`, e, []);
   }
 }
 
@@ -64,35 +120,30 @@ function filesTouchedByCommit(sha) {
 // from origin/main that landed AFTER `sha` and touched any of `files`. High
 // count = subsequent work has built on top of this change, so a "redo"
 // risks conflicts. Excludes `sha` itself.
+const NO_DOWNSTREAM = Object.freeze({
+  commits_after_touching_files: 0, distinct_files_touched: 0, sample_subjects: [],
+});
+
 function downstreamImpact(sha, files) {
-  if (!sha || files.length === 0) {
-    return { commits_after_touching_files: 0, distinct_files_touched: 0, sample_subjects: [] };
-  }
-  // -- shell-quote each file path so spaces/specials don't break the cmd.
-  const fileArgs = files.map((f) => `'${f.replace(/'/g, "'\\''")}'`).join(' ');
-  let out;
+  if (!sha || files.length === 0) return { ...NO_DOWNSTREAM };
+  // The hand-rolled POSIX shell-quoting this replaces ("'" + escape + "'") was
+  // both unnecessary and wrong on Windows, where that quoting style is not the
+  // shell's. In argv form a path with spaces, quotes or a `$` is just an element.
+  const range = `${sha}..origin/main`;
+  let lines;
   try {
-    out = execSync(
-      `git log ${sha}..origin/main --format='%H %s' -- ${fileArgs}`,
-      { encoding: 'utf8' }
-    );
-  } catch (_) {
-    return { commits_after_touching_files: 0, distinct_files_touched: 0, sample_subjects: [] };
+    lines = gitLines(['log', range, '--format=%H %s', '--', ...files]);
+  } catch (e) {
+    return gitFails(`reading downstream commits after ${String(sha).slice(0, 8)}`, e, { ...NO_DOWNSTREAM });
   }
-  const lines = out.split('\n').map((s) => s.trim()).filter(Boolean);
   // Distinct downstream files touched
   let distinct = 0;
   try {
-    const namesOut = execSync(
-      `git log ${sha}..origin/main --name-only --format='' -- ${fileArgs}`,
-      { encoding: 'utf8' }
-    );
-    const set = new Set(
-      namesOut.split('\n').map((s) => s.trim()).filter(Boolean)
-    );
-    distinct = set.size;
-  } catch (_) {
-    distinct = 0;
+    distinct = new Set(gitLines(['log', range, '--name-only', '--format=', '--', ...files])).size;
+  } catch (e) {
+    // Same shape as every other call site: the fallback comes FROM gitFails, so
+    // the value and the report can never drift apart.
+    distinct = gitFails(`reading downstream files after ${String(sha).slice(0, 8)}`, e, 0);
   }
   return {
     commits_after_touching_files: lines.length,
@@ -251,7 +302,18 @@ async function main() {
   for (const [k, v] of Object.entries(buckets)) console.log(`  ${k}: ${v}`);
 }
 
-main().catch((err) => {
-  console.error(err);
-  process.exit(1);
-});
+// Run only as a CLI. Without this guard the file executes main() — and hits the
+// API — the instant anything requires it, which is why its git helpers had never
+// been tested: there was no way to reach them without starting an audit
+// (task 1003223).
+if (require.main === module) {
+  main().catch((err) => {
+    console.error(err);
+    process.exit(1);
+  });
+}
+
+// Exported for tests/audit_ships_git_argv.mjs — the argv-vs-shell-string fix is a
+// property of THESE functions, so the test drives them rather than re-typing an
+// equivalent git call and hoping it matches.
+module.exports = { findCommitForTask, gitDiffStatsForCommit, filesTouchedByCommit, downstreamImpact };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.762'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.763'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/audit_ships_git_argv.mjs

@@ -0,0 +1,173 @@
+// tests/audit_ships_git_argv.mjs — audit-ships' git calls must be argv, not a
+// shell string (task 1003223; the class task 1002761 named).
+//
+// THE BUG. Five calls interpolated `--format=''` into a shell string. A POSIX
+// shell strips the quotes and git sees an empty format; the shell Node uses on
+// Windows does not, so git receives `--format=''` literally and dies with
+// `fatal: invalid --pretty format: ''`. A sixth built a `grep | head | awk`
+// pipeline and pinned `shell: '/bin/bash'` to survive at all.
+//
+// WHY THIS NEEDS A TEST AND NOT JUST A FIX. Every one of those calls sat inside a
+// try/catch that returned null or []. So the Windows failure did not crash the
+// audit — it produced an audit with no diff stats and zero downstream impact for
+// every ship, which is indistinguishable from a clean run. The originating row
+// asked exactly this ("check whether the catch degrades to a silently empty audit
+// — if so it is the same dangerous shape after all"). It did.
+//
+// The static half of this file is the real net: it is the half that stays true on
+// Linux CI, where the shell-string form would have passed happily forever.
+//
+// Run:  node --test tests/audit_ships_git_argv.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import fs from 'node:fs';
+import path from 'node:path';
+import { execSync, execFileSync } from 'node:child_process';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const FILE = path.join(ROOT, 'scripts/gds/audit-ships.js');
+const audit = require('../scripts/gds/audit-ships.js');
+const raw = fs.readFileSync(FILE, 'utf8');
+
+// Scan CODE, not prose. The file's header explains the bug by quoting the exact
+// tokens that are banned ("--format=''", "grep -E", "shell: '/bin/bash'"), so a
+// naive scan of the whole file fails on its own documentation — which is exactly
+// what happened when this test was first written. Same comments-stripped posture
+// as scripts/gds/category-advisory-guard.js.
+const src = raw
+  .replace(/\/\*[\s\S]*?\*\//g, '')          // block comments
+  .split('\n').map((l) => l.replace(/(^|\s)\/\/.*$/, '$1')).join('\n');
+
+// ---- static: the shape that broke must not come back ----------------------
+
+test('no execSync anywhere — a shell string is what mangles the quoting', () => {
+  assert.doesNotMatch(src, /\bexecSync\b/,
+    'audit-ships must spawn git through execFileSync with an argv array');
+});
+
+test("no quoted --format='' — the argv spelling is --format= with no quotes", () => {
+  // Match the SHELL form precisely: two consecutive quotes after the '='. A naive
+  // /--format='/ also matches the correct argv literal '--format=', where that
+  // quote is JS string syntax, not a shell quote — it flagged the fix as the bug.
+  assert.doesNotMatch(src, /--format=''/,
+    "a quoted empty format is the exact token git rejects on Windows");
+  assert.match(src, /'--format='/, 'the argv spelling is present');
+});
+
+test('no shell pipeline and no pinned /bin/bash', () => {
+  assert.doesNotMatch(src, /\bshell:\s*['"]/, 'no shell is needed once calls are argv');
+  for (const tool of ['grep -E', '| head', '| awk']) {
+    assert.ok(!src.includes(tool), `${tool} is a POSIX-only dependency`);
+  }
+});
+
+test('git failures are reported, not swallowed into a clean-looking audit', () => {
+  // The silent `catch (_) { return null; }` is what made the Windows breakage
+  // invisible. Every catch around a git call must go through gitFails.
+  assert.match(raw, /function gitFails\(/, 'the reporting helper exists');
+  // Scoped to catches returning an empty RESULT SET — null or [] — which is the
+  // shape that turned a git failure into a clean-looking audit. A catch returning
+  // `{}` for an unreadable branding pack is a different, legitimate default and is
+  // deliberately not swept up here.
+  const silent = src.match(/catch \(_\)\s*\{\s*return (?:null|\[\])/g) || [];
+  assert.equal(silent.length, 0,
+    `silent catch(es) returning an empty result: ${silent.join(' | ')}`);
+});
+
+// ---- behavioural: the calls actually work on THIS platform ----------------
+//
+// These run real git against this repo, which is what makes them meaningful on
+// Windows: before the fix, two of them threw here and returned empty.
+
+const git = (args) => execFileSync('git', args, { cwd: ROOT, encoding: 'utf8' }).trim();
+// A NON-MERGE commit. `git show --name-only` prints nothing for a merge by
+// default, so anchoring on HEAD makes the file-listing assertions depend on
+// whatever happened to be checked out — they failed here for that reason, not
+// because the code was wrong. --no-merges picks a commit that really touched files.
+const HEAD = git(['rev-list', '--no-merges', '-n', '1', 'HEAD']);
+
+test('the exact argv git rejected as a shell string succeeds here', () => {
+  const out = execFileSync('git', ['show', '--shortstat', '--format=', HEAD], { cwd: ROOT, encoding: 'utf8' });
+  assert.match(out, /\d+ files? changed/, `shortstat should parse, got: ${JSON.stringify(out.slice(0, 80))}`);
+});
+
+test('the shell-string form is what actually fails on this platform', () => {
+  // Not a hypothetical: assert the OLD form's behaviour so the reason for the fix
+  // is recorded in a runnable way. On POSIX it succeeds (the quotes are stripped),
+  // on Windows it throws — either way, argv is the only spelling that is correct
+  // on both, which is the whole point.
+  let threw = false;
+  try { execSync(`git show --shortstat --format='' ${HEAD}`, { cwd: ROOT, encoding: 'utf8' }); }
+  catch { threw = true; }
+  if (process.platform === 'win32') {
+    assert.equal(threw, true, 'on win32 the quoted form must be the one that fails');
+  } else {
+    assert.equal(threw, false, 'on POSIX it happens to work — which is why this hid on CI');
+  }
+});
+
+test('--name-only --format= yields real paths', () => {
+  const out = execFileSync('git', ['show', '--name-only', '--format=', HEAD], { cwd: ROOT, encoding: 'utf8' });
+  const files = out.split('\n').map((s) => s.trim()).filter(Boolean);
+  assert.ok(files.length > 0, 'HEAD touched at least one file');
+  assert.ok(files.every((f) => !f.includes("'")), 'paths come back unquoted');
+});
+
+// ---- the real functions, not equivalents ---------------------------------
+//
+// These drive audit-ships' own helpers. Before this task the file executed main()
+// on require — it hit the API the moment anything imported it — so its git helpers
+// had never been reachable from a test at all. That is the deeper reason the
+// Windows breakage went unnoticed for months.
+
+test('gitDiffStatsForCommit returns real stats on this platform', () => {
+  const stats = audit.gitDiffStatsForCommit(HEAD);
+  assert.ok(stats, 'must not be the null the Windows failure returned');
+  assert.equal(stats.commit_sha, HEAD);
+  assert.ok(stats.files_changed > 0, `files_changed should be positive, got ${stats.files_changed}`);
+});
+
+test('filesTouchedByCommit returns real paths, not the empty array of a swallowed failure', () => {
+  const files = audit.filesTouchedByCommit(HEAD);
+  assert.ok(Array.isArray(files) && files.length > 0, `expected paths, got ${JSON.stringify(files)}`);
+  assert.ok(files.every((f) => typeof f === 'string' && f.length > 0));
+});
+
+test('the commit list is read once per run, not once per task', () => {
+  // The shell pipeline this replaced ended in `head -1`, so git stopped at the
+  // first match. The argv form has no early exit, and findCommitForTask runs once
+  // per shipped task — up to 500 a run — so a naive port turns one bounded call
+  // into 500 full history walks. Caught by the grader on this task's first round.
+  //
+  // Measured rather than asserted structurally: the second lookup must not spend
+  // anywhere near the first's time, because it must not touch git at all.
+  const t0 = process.hrtime.bigint();
+  audit.findCommitForTask(999999901);
+  const cold = process.hrtime.bigint() - t0;
+
+  const t1 = process.hrtime.bigint();
+  audit.findCommitForTask(999999902);
+  const warm = process.hrtime.bigint() - t1;
+
+  assert.ok(warm * 5n < cold || warm < 2_000_000n,
+    `second lookup should reuse the cached list (cold ${cold / 1000000n}ms, warm ${warm / 1000000n}ms)`);
+});
+
+test('the helpers still answer safely for a missing sha', () => {
+  assert.equal(audit.gitDiffStatsForCommit(null), null);
+  assert.deepEqual(audit.filesTouchedByCommit(null), []);
+  assert.deepEqual(audit.downstreamImpact(null, ['x']),
+    { commits_after_touching_files: 0, distinct_files_touched: 0, sample_subjects: [] });
+});
+
+test('a path containing a space survives argv — the hand-rolled quoting is gone', () => {
+  // git log -- <pathspec> with a space used to need shell quoting; in argv it is
+  // simply one element. An unmatched pathspec returns empty, never an error.
+  const out = execFileSync('git', ['log', '-1', '--format=%H', '--', 'no such file.md'], { cwd: ROOT, encoding: 'utf8' });
+  assert.equal(out.trim(), '', 'an unmatched pathspec is empty, not a crash');
+});
+