@bongos/core 1.19.1032 → 1.19.1034

package/tests/release_notes.mjs

@@ -0,0 +1,327 @@
+// tests/release_notes.mjs — the release summaries shipped INSIDE the core package
+// (task 1004218): generated from history at pack time, redacted like a doc, pinned like
+// every other file, and read back by the upgrade runner for a from→to range.
+//
+// WHAT IS ACTUALLY AT RISK, in the order it would hurt:
+//
+//   1. THE WRONG RELEASE GETS THE CREDIT. The obvious generator — split the log wherever a
+//      `release: core X.Y.Z` subject appears — credits a merge made on a branch before one
+//      release, but landed after it, to the EARLIER release. The history below contains
+//      exactly that shape, backdated, and every release is checked against the checkout
+//      reader's own `git log --merges <prev>..<release>` answer.
+//   2. A LEAK THAT WEDGES THE LANE. These are builder-written sentences, and the real
+//      history holds ones that name a prior instance. Shipped verbatim, the fail-closed leak
+//      scan would refuse every pack from then on — the history cannot be edited.
+//   3. A RANGE READ AS "NOTHING CHANGED". A range the notes do not reach must come back as
+//      a reason, never as an empty list, and the boundaries are `from` exclusive, `to`
+//      inclusive.
+//
+// Run:  node tests/release_notes.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import { execFileSync, spawnSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {
+  RELEASE_NOTES_FILE, parseChangeRecords, parseLogRecords, buildReleaseNotes, generateReleaseNotes,
+  serializeReleaseNotes, boundReleaseNotes, notesBetween,
+} from '../scripts/gds/release-notes.js';
+import {
+  releaseNotesArtifact, scanArtifactForLeaks, PRIOR_INSTANCE_FLOOR, buildTar, TAR_ROOT,
+  sha256hex, canonicalTreeHash, buildCoreManifest, withTarballInfo, reproducePinFromTree,
+} from '../scripts/gds/package-core.js';
+import {
+  readPackagedNotes, readInstalledNotes, parseChangeRecords as runnerParser,
+} from '../scripts/gds/provision-core-upgrade.js';
+import { buildRedactionRules, collectSensitiveLiterals } from '../scripts/gds/mirror-redact.js';
+
+const TMP = fs.mkdtempSync(path.join(os.tmpdir(), 'bongos-release-notes-test-'));
+process.on('exit', () => { try { fs.rmSync(TMP, { recursive: true, force: true }); } catch { /* best-effort */ } });
+
+const CARRIER = (v) => `release: core ${v} — CI auto-patch carrier (publish-on-merge, ADR 0161)`;
+
+// ---- a real core-shaped history ---------------------------------------------------
+//
+//   main:  C0 ─ M1 ─ R(1.0.1) ─────────────── M2 ─ R(1.0.2) ─ M3
+//           │   │                              │               │
+//           │   task-1                  feat ──┘        hand-3 ┘
+//           └─ F1 ─ N(nested merge, backdated to 2020) ─ S(merges main at 1.0.1)
+//
+// N was made on the branch long before 1.0.1 and landed with M2, after it. Its date puts
+// it at the very end of a date-ordered log, so a subject-split generator hands it to 1.0.1.
+function makeHistory() {
+  const dir = fs.mkdtempSync(path.join(TMP, 'repo-'));
+  const git = (args, env = {}) => execFileSync('git', args, {
+    cwd: dir, encoding: 'utf8', env: { ...process.env, ...env },
+  });
+  let n = 0;
+  const commit = (msg, env) => {
+    fs.writeFileSync(path.join(dir, `c${n++}.txt`), `${msg}\n`);   // a file each, so no branch conflicts
+    git(['add', '-A'], env);
+    git(['-c', 'commit.gpgsign=false', 'commit', '-q', '--no-verify', '-m', msg], env);
+  };
+  const merge = (branch, subject, body, env) => git(['-c', 'commit.gpgsign=false', 'merge', '-q', '--no-ff', '--no-verify',
+    '-m', subject, ...(body ? ['-m', body] : []), branch], env);
+  const old = (d) => ({ GIT_AUTHOR_DATE: d, GIT_COMMITTER_DATE: d });
+
+  git(['init', '-q', '-b', 'main']);
+  git(['config', 'user.email', 'test@example.com']);
+  git(['config', 'user.name', 'Test']);
+  commit('initial', old('2020-01-01T00:00:00Z'));
+  git(['checkout', '-q', '-b', 'feat']);
+  commit('feature work begins', old('2020-01-02T00:00:00Z'));
+  git(['checkout', '-q', '-b', 'sub-7']);
+  commit('a sub-branch', old('2020-01-03T00:00:00Z'));
+  git(['checkout', '-q', 'feat']);
+  merge('sub-7', 'Merge sub-7: The nested summary, merged on its branch long ago.', null, old('2020-01-04T00:00:00Z'));
+  git(['checkout', '-q', 'main']);
+  git(['checkout', '-q', '-b', 'task-1']);
+  commit('work for task 1');
+  git(['checkout', '-q', 'main']);
+  merge('task-1', 'Merge pull request #1 from an-owner/task-1', 'task 1001: The first summary.');
+  commit(CARRIER('1.0.1'));
+  git(['checkout', '-q', 'feat']);
+  merge('main', 'Merge origin/main into feat (pre-stage freshness, task 1068)');
+  git(['checkout', '-q', 'main']);
+  merge('feat', 'Merge pull request #2 from an-owner/task-2', 'task 1002: The second summary.');
+  commit(CARRIER('1.0.2'));
+  git(['checkout', '-q', '-b', 'hand-3']);
+  commit('work for the next release');
+  git(['checkout', '-q', 'main']);
+  merge('hand-3', 'Merge hand-3: An unreleased summary.');
+  const shaOf = (v) => git(['log', '--format=%H', '-1', '-F', `--grep=release: core ${v} `]).trim();
+  return { dir, git: (args) => git(args), shaOf };
+}
+
+const H = makeHistory();
+const repoGit = H.git;
+const texts = (list) => list.map((e) => e.text);
+
+test('each release is credited with EXACTLY what landed since the previous one — even a backdated branch merge', () => {
+  const r = generateReleaseNotes({ git: repoGit, ref: 'HEAD', version: '1.0.3' });
+  assert.equal(r.skipped, undefined);
+  assert.deepEqual(texts(r.notes['1.0.1']), ['The first summary.']);
+  assert.equal(r.notes['1.0.1'][0].id, '1001', 'the CI shape keeps its task id');
+  assert.deepEqual(texts(r.notes['1.0.2']), ['The second summary.', 'The nested summary, merged on its branch long ago.'],
+    'the nested merge LANDED with 1.0.2 — its 2020 date must not hand it to 1.0.1');
+  assert.ok(!texts(r.notes['1.0.2']).some((t) => /pre-stage freshness/.test(t)), 'the mechanics of landing stay dropped');
+});
+
+test('the answer is the checkout reader’s own range — git log --merges <prev>..<release>', () => {
+  // The fallback path asks git for this one range at a time; the generator must agree
+  // with it for every release, or the page would say different things on different boxes.
+  const { notes } = generateReleaseNotes({ git: repoGit, ref: 'HEAD', version: '1.0.3' });
+  const log = repoGit(['log', '--merges', '--format=%s%x1f%b%x1e', `${H.shaOf('1.0.1')}..${H.shaOf('1.0.2')}`]);
+  assert.deepEqual(texts(notes['1.0.2']).sort(), texts(parseChangeRecords(log)).sort());
+  assert.equal(runnerParser, parseChangeRecords, 'one parser, not two: the runner re-exports this one');
+});
+
+test('the unreleased tail belongs to the packed version only when that version has no release yet', () => {
+  const declared = generateReleaseNotes({ git: repoGit, ref: 'HEAD', version: '1.0.3' });
+  assert.deepEqual(texts(declared.notes['1.0.3']), ['An unreleased summary.'], 'a hand-declared version carries its own tail');
+  const released = generateReleaseNotes({ git: repoGit, ref: 'HEAD', version: '1.0.2' });
+  assert.deepEqual(Object.keys(released.notes), ['1.0.1', '1.0.2'], 'on a work merge the tail is the NEXT release’s, and is not guessed at');
+  const behind = generateReleaseNotes({ git: repoGit, ref: 'HEAD', version: '0.9.0' });
+  assert.deepEqual(Object.keys(behind.notes), ['1.0.1', '1.0.2'], 'a version older than the newest release never takes the tail');
+});
+
+test('a shallow clone produces NO notes, and says why — never a partial file that looks whole', () => {
+  const shallow = path.join(TMP, 'shallow');
+  execFileSync('git', ['clone', '-q', '--depth', '1', `file://${H.dir}`, shallow]);
+  const r = generateReleaseNotes({
+    git: (args) => execFileSync('git', ['-C', shallow, ...args], { encoding: 'utf8' }), ref: 'HEAD', version: '1.0.3',
+  });
+  assert.equal(r.notes, undefined);
+  assert.match(r.skipped, /shallow clone/);
+});
+
+test('a version released twice keeps both halves, and a repeated sentence once', () => {
+  const rec = (sha, parents, subject, body = '') => `${sha}\x1f${parents}\x1f${subject}\x1f${body}\x1e\n`;
+  const log = [
+    rec('e', 'd', CARRIER('2.0.0')),
+    rec('d', 'c x', 'Merge b-2: Second half.'),
+    rec('c', 'b', CARRIER('2.0.0')),
+    rec('b', 'a y', 'Merge b-1: First half.'),
+    rec('a', '', 'initial'),
+  ].join('');
+  const { notes } = buildReleaseNotes(parseLogRecords(log));
+  assert.deepEqual(texts(notes['2.0.0']), ['First half.', 'Second half.']);
+});
+
+// ---- the range ---------------------------------------------------------------------
+
+const NOTES = {
+  '1.19.900': [{ text: 'already live' }],
+  '1.19.901': [{ id: '1', text: 'first in range' }],
+  '1.19.920': [],
+  '1.19.949': [{ id: '3', text: 'the target itself' }, { text: 'first in range' }],
+  '1.19.950': [{ text: 'after the target' }],
+};
+
+test('(from, to]: from EXCLUSIVE, to INCLUSIVE, newest release first, a sentence said once', () => {
+  assert.deepEqual(texts(notesBetween(NOTES, '1.19.900', '1.19.949').entries), ['the target itself', 'first in range']);
+  assert.deepEqual(texts(notesBetween(NOTES, '1.19.901', '1.19.949').entries), ['the target itself', 'first in range'],
+    'starting AT 1.19.901 excludes its own entry — the one left is the target’s repeat of it');
+  assert.deepEqual(texts(notesBetween(NOTES, '1.19.949', '1.19.950').entries), ['after the target']);
+});
+
+test('a release of pure housekeeping is COVERED and empty — distinct from not covered', () => {
+  assert.deepEqual(notesBetween(NOTES, '1.19.901', '1.19.920'), { entries: [] });
+});
+
+test('a range the notes do not reach is refused with a reason, never an empty list', () => {
+  assert.match(notesBetween(NOTES, '1.19.900', '1.19.999').uncovered, /do not list core 1\.19\.999/);
+  assert.match(notesBetween(NOTES, '1.19.850', '1.19.949').uncovered, /begin at core 1\.19\.900, after 1\.19\.850/);
+  assert.match(notesBetween(null, '1.19.900', '1.19.949').uncovered, /not a list of releases/);
+  assert.match(notesBetween([], '1.19.900', '1.19.949').uncovered, /not a list of releases/);
+});
+
+test('a file off the network is re-checked, not trusted', () => {
+  const messy = {
+    '1.0.1': [],
+    '1.0.2': [null, { text: '' }, { text: 42 }, { id: 'x; rm -rf', text: 'kept, bad id dropped' }, { id: 12, text: 'y'.repeat(900) }],
+    'not-a-version': [{ text: 'ignored' }],
+    '1.0.3': 'not an array',
+  };
+  const { entries } = notesBetween(messy, '1.0.1', '1.0.2');
+  assert.deepEqual(entries[0], { text: 'kept, bad id dropped' });
+  assert.equal(entries[1].id, '12');
+  assert.ok(entries[1].text.length <= 400, 'bounded — it reaches a DOM');
+  assert.equal(entries.length, 2);
+});
+
+// ---- the bound -----------------------------------------------------------------------
+
+test('past the bound the OLDEST releases go, the fewest that fit, and the newest always stays', () => {
+  const big = {};
+  for (let i = 1; i <= 60; i++) big[`1.0.${i}`] = [{ text: `release ${i} ${'x'.repeat(200)}` }];
+  const full = serializeReleaseNotes(big).length;
+  const cap = Math.floor(full / 2);
+  const b = boundReleaseNotes(big, cap);
+  assert.ok(serializeReleaseNotes(b.notes).length <= cap);
+  assert.equal(b.dropped[0], '1.0.1', 'oldest first');
+  assert.ok('1.0.60' in b.notes);
+  const oneMore = [b.dropped[b.dropped.length - 1], ...Object.keys(b.notes)];
+  assert.ok(serializeReleaseNotes(Object.fromEntries(oneMore.map((v) => [v, big[v]]))).length > cap, 'no more dropped than needed');
+  assert.deepEqual(boundReleaseNotes(big, full).dropped, [], 'under the bound nothing moves');
+  // …and the reader then refuses what the trimmed file no longer holds.
+  assert.match(notesBetween(b.notes, '1.0.1', '1.0.60').uncovered, /begin at core/);
+  assert.ok(notesBetween(b.notes, Object.keys(b.notes)[0], '1.0.60').entries);
+});
+
+// ---- the neutral floor ---------------------------------------------------------------
+
+const floorExtra = { owners: [...PRIOR_INSTANCE_FLOOR.owners], tokens: [...PRIOR_INSTANCE_FLOOR.tokens], literals: [] };
+const rules = buildRedactionRules({}, floorExtra);
+const sensitiveLiterals = collectSensitiveLiterals({}, floorExtra);
+const OWNER = PRIOR_INSTANCE_FLOOR.owners[0];   // never typed here: this file ships too
+
+test('a summary naming a prior instance’s owner is REDACTED like a doc, and the scan then passes', () => {
+  const notes = { '1.0.1': [], '1.0.2': [{ id: '7', text: `Asking ${OWNER} for help now reaches them.` }] };
+  const art = releaseNotesArtifact(notes, { rules, sensitiveLiterals, envSecrets: [], knownDocNames: new Set() });
+  assert.deepEqual(art.leaks, []);
+  assert.equal(art.redacted, 1);
+  assert.ok(!art.buf.toString('utf8').toLowerCase().includes(OWNER.toLowerCase()));
+  assert.match(art.notes['1.0.2'][0].text, /^Asking example-owner for help/);
+  assert.deepEqual(scanArtifactForLeaks([{ path: RELEASE_NOTES_FILE, content: art.buf }]).literalHits, []);
+  // The post-build scan reads the generated file like any other: unredacted, it is flagged.
+  assert.ok(scanArtifactForLeaks([{ path: RELEASE_NOTES_FILE, content: serializeReleaseNotes(notes) }]).literalHits.length > 0);
+});
+
+test('residue AFTER redaction is reported as a leak — which main() treats as fatal', () => {
+  const notes = { '1.0.2': [{ text: `Asking ${OWNER} for help.` }] };
+  const blind = buildRedactionRules({}, {});   // a redactor that does not know the literal
+  const art = releaseNotesArtifact(notes, { rules: blind, sensitiveLiterals, envSecrets: [], knownDocNames: new Set() });
+  assert.ok(art.leaks.some((l) => /^doc:literal:/.test(l.label)), JSON.stringify(art.leaks));
+});
+
+// ---- packed, verified, downloaded, read back ------------------------------------------
+
+// The artifact the way main() assembles it: the notes staged beside package.json into ONE
+// file set, from which the pin is computed — then the pin reproduced from the unpacked tgz,
+// which is what --self-verify does at publish time.
+function pack({ withNotes = true } = {}) {
+  const gen = generateReleaseNotes({ git: repoGit, ref: 'HEAD', version: '1.0.3' });
+  const art = releaseNotesArtifact(gen.notes, { rules, sensitiveLiterals, envSecrets: [], knownDocNames: new Set() });
+  const files = [{ path: 'package.json', buf: Buffer.from('{"name":"@bongos/core","version":"1.0.3"}\n') }];
+  if (withNotes) files.push({ path: RELEASE_NOTES_FILE, buf: art.buf });
+  const filesMeta = files.map((f) => ({ path: f.path, mode: '100644', sha256: sha256hex(f.buf) }));
+  const tgz = buildTar(files.map((f) => ({ name: TAR_ROOT + f.path, mode: 0o644, buf: f.buf })));
+  const out = fs.mkdtempSync(path.join(TMP, 'dist-'));
+  const tgzPath = path.join(out, 'bongos-core-1.0.3.tgz');
+  fs.writeFileSync(tgzPath, tgz);
+  const sidecar = withTarballInfo(buildCoreManifest({
+    version: '1.0.3', coreContract: '1.0.3', sourceCommit: null, sourceRef: 'HEAD', builtAtIso: new Date(0).toISOString(),
+    files: filesMeta, treeHash: canonicalTreeHash(filesMeta),
+  }), { name: 'bongos-core-1.0.3.tgz', sha256: sha256hex(tgz), bytes: tgz.length });
+  return { art, tgzPath, sidecar };
+}
+
+// `npm pack` stood in for (no registry in a unit test); `tar` is the real one.
+function registry(tgzPath, asked = []) {
+  return (cmd, args, opts) => {
+    if (cmd !== 'npm') return spawnSync(cmd, args, opts);
+    asked.push(args[1]);
+    fs.copyFileSync(tgzPath, path.join(args[args.indexOf('--pack-destination') + 1], path.basename(tgzPath)));
+    return { status: 0, stdout: `${path.basename(tgzPath)}\n`, stderr: '' };
+  };
+}
+
+test('PACKED, SELF-VERIFIED, DOWNLOADED, READ BACK — and the range comes out right', () => {
+  const { art, tgzPath, sidecar } = pack();
+  // --self-verify: the pin reproduces from the unpacked tarball, notes file included.
+  const unpacked = fs.mkdtempSync(path.join(TMP, 'unpacked-'));
+  assert.equal(spawnSync('tar', ['-xzf', tgzPath, '-C', unpacked]).status, 0);
+  const rep = reproducePinFromTree({ treeRoot: path.join(unpacked, 'package'), sidecar, tgzPath });
+  assert.ok(rep.ok, rep.problems.join('; '));
+  assert.ok(sidecar.files.some((f) => f.path === RELEASE_NOTES_FILE), 'the notes are IN the pin, not beside it');
+
+  const asked = [];
+  const got = readPackagedNotes('1.0.3', { spawn: registry(tgzPath, asked), tmpDir: TMP });
+  assert.deepEqual(asked, ['@bongos/core@1.0.3'], 'the target’s own package is the one fetched');
+  assert.deepEqual(got.notes, art.notes, 'what comes out is what went in');
+  const r = notesBetween(got.notes, '1.0.1', '1.0.3');
+  assert.deepEqual(texts(r.entries), ['An unreleased summary.', 'The second summary.', 'The nested summary, merged on its branch long ago.'],
+    '1.0.1’s own summary is excluded; the target’s is included');
+  assert.deepEqual(fs.readdirSync(TMP).filter((n) => n.startsWith('bongos-release-notes-')), [], 'the download does not outlive the call');
+});
+
+test('a package published before the notes existed says so — the real tar, a real tarball without the file', () => {
+  const { tgzPath } = pack({ withNotes: false });
+  const got = readPackagedNotes('1.0.3', { spawn: registry(tgzPath), tmpDir: TMP });
+  assert.equal(got.notes, undefined);
+  assert.match(got.missing, /the core 1\.0\.3 package carries no release notes/);
+});
+
+test('every way the download can fail is named, and cleaned up', () => {
+  const fake = (npm, tar) => (cmd, args) => {
+    if (cmd === 'npm') {
+      if (npm.writes) fs.writeFileSync(path.join(args[args.indexOf('--pack-destination') + 1], 'bongos-core-9.9.9.tgz'), 'x');
+      return npm;
+    }
+    return tar;
+  };
+  const ok = { status: 0, stdout: '', stderr: '', writes: true };
+  const cases = [
+    [fake({ status: 1, stdout: '', stderr: 'npm error code E404\nnpm error 404 Not Found - GET https://registry.npmjs.org/x' }, null),
+      /could not download the core 9\.9\.9 package to read its release notes \(npm error 404 Not Found/],
+    [fake({ status: 0, stdout: '', stderr: '' }, null), /left no tarball/],
+    [fake(ok, { status: 2, stdout: '', stderr: 'tar: Error opening archive: Unrecognized archive format' }), /could not read the release notes out of the core 9\.9\.9 package/],
+    [fake(ok, { status: 0, stdout: '{not json', stderr: '' }), /not valid JSON/],
+    [fake({ error: new Error('spawnSync npm ETIMEDOUT'), status: null }, null), /ETIMEDOUT/],
+  ];
+  for (const [spawn, want] of cases) assert.match(readPackagedNotes('9.9.9', { spawn, tmpDir: TMP }).error, want);
+  let spawned = false;
+  assert.match(readPackagedNotes("9.9.9'; rm -rf /", { spawn: () => { spawned = true; } }).error, /could not work out/);
+  assert.equal(spawned, false, 'a version that is not three numbers reaches no command');
+  assert.deepEqual(fs.readdirSync(TMP).filter((n) => n.startsWith('bongos-release-notes-')), []);
+});
+
+test('the installed core’s own file: read when present, and a missing or broken one is not an answer', () => {
+  const at = (body) => ({ fs: { readFileSync: (p) => { assert.ok(p.endsWith(RELEASE_NOTES_FILE)); if (body === null) throw new Error('ENOENT'); return body; } } });
+  assert.deepEqual(readInstalledNotes(at('{"1.0.1":[]}')).notes, { '1.0.1': [] });
+  assert.match(readInstalledNotes(at(null)).missing, /carries no release notes/);
+  assert.match(readInstalledNotes(at('{bad')).error, /not valid JSON/);
+});

package/tests/shell_stat_portability.mjs

@@ -0,0 +1,49 @@
+// tests/shell_stat_portability.mjs — no shell script leans on one platform's `stat`
+// (task 1004170).
+//
+// THE BUG. GNU stat takes `-c FORMAT`; BSD/macOS stat refuses `-c` outright, and its own
+// `-f FORMAT` means "file system status" to GNU. Five scripts called `stat -c` alone, so
+// each died, or lost its answer, on every Mac, and passed on CI's Linux, so nobody
+// reading Actions saw it. Only one of the five had a test that ran it; the suites beside
+// each script now run them under macOS-shaped tools. This is the ratchet that stops a
+// sixth arriving without one.
+//
+// THE RULE, per line of every tracked shell script: a `stat -c` carries its BSD twin after
+// an `||` on the same line, and a `stat -f` never appears without one before it. A byte
+// count needs neither: POSIX `wc -c` answers it everywhere.
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GNU = /(^|[^\w-])stat\s+(-c|--format|--printf)[\s=]/;
+const BSD = /(^|[^\w-])stat\s+-f\s/;
+
+// offending — the lines of `src` that ask stat in only one platform's dialect.
+function offending(src) {
+  return src.split('\n').map((l, i) => ({ n: i + 1, l })).filter(({ l }) => {
+    if (/^\s*#/.test(l)) return false;
+    const g = l.search(GNU);
+    const b = l.search(BSD);
+    if (g < 0 && b < 0) return false;
+    return !(g >= 0 && b > g && l.slice(g, b).includes('||'));
+  });
+}
+
+test('every tracked shell script asks stat in both dialects, or not at all', () => {
+  const files = execFileSync('git', ['ls-files', '*.sh'], { cwd: ROOT, encoding: 'utf8' }).split('\n').filter(Boolean);
+  assert.ok(files.length > 20, `the scan must see the scripts, got ${files.length}`);
+  const hits = files.flatMap((f) => offending(fs.readFileSync(path.join(ROOT, f), 'utf8')).map(({ n, l }) => `${f}:${n}: ${l.trim()}`));
+  assert.deepEqual(hits, [], "size: wc -c < f | tr -d '[:space:]'; anything else: stat -c FMT f || stat -f FMT f");
+});
+
+test('the rule catches a lone GNU or BSD stat, and passes the paired form and prose', () => {
+  assert.equal(offending("BYTES=$(stat -c '%s' \"$f\")").length, 1);
+  assert.equal(offending('U=$(stat -f %Su "$d")').length, 1);
+  assert.equal(offending('U=$(stat -c %U "$d" 2>/dev/null || stat -f %Su "$d" 2>/dev/null)').length, 0);
+  assert.equal(offending("  # was stat -c '%s', which BSD refuses").length, 0, 'a comment is not a call');
+});

package/tests/ship_land_conflict.mjs

@@ -0,0 +1,181 @@
+// tests/ship_land_conflict.mjs — a CONFLICTING PR is named while the land waits (task 1003499).
+//
+// WHY. GitHub's auto-merge waits for a clean merge as well as green checks, so a PR
+// whose branch conflicts with main sits open under a fully green rollup and never
+// merges. PR #497 did that for ~25 minutes while the ship's poll printed nothing and
+// then signed off with "auto-merge is armed ... NOT a failure" and a card saying
+// "Nothing to do" — so the completion card read "landing automatically" over a land
+// that could not happen. These tests drive the REAL poll loops (pollCiDeploy, the
+// gh path; pollServerPublish, the server path) with a scripted PR, and pin both
+// halves: the conflict is said once, when it appears, and a wait that ends
+// conflicting is a bail with the fix named, never the pending banner.
+//
+// Run:  node tests/ship_land_conflict.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+process.env.BONGOS_SURFACE = 'agent'; // the plain cards print on the agent surface only
+
+const require = createRequire(import.meta.url);
+const land = require('../scripts/gds/ship-land.js');
+const { CARDS } = require('../scripts/gds/plain-cards.js');
+
+let passed = 0;
+let failed = 0;
+async function test(name, fn) {
+  try { await fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+// Run fn with console.log captured; returns { result, out }.
+async function capture(fn) {
+  const lines = [];
+  const real = console.log;
+  console.log = (...a) => { lines.push(a.join(' ')); };
+  try { return { result: await fn(), out: lines.join('\n') }; }
+  finally { console.log = real; }
+}
+const count = (hay, needle) => hay.split(needle).length - 1;
+const CONFLICT_LINE = 'the PR CONFLICTS with main';
+const PENDING_BANNER = 'This is NOT a failure';
+
+// A scripted `gh pr view`: the Nth read answers with states[N] (the last one repeats).
+function ghScript(states, calls = []) {
+  let i = 0;
+  return (args) => {
+    calls.push(args.join(' '));
+    const s = states[Math.min(i, states.length - 1)];
+    i++;
+    return typeof s === 'function' ? s(args) : s;
+  };
+}
+const OPEN = (mergeable, mergeStateStatus) => ({ state: 'OPEN', mergeCommit: null, mergeable, mergeStateStatus });
+const noPause = () => {};
+
+// ---- the pure half ----
+
+await test('prConflicting reads both shapes it is handed, and a failed read is not a conflict', () => {
+  // gh pr view (camelCase)
+  assert.equal(land.prConflicting(OPEN('CONFLICTING', 'DIRTY')), true);
+  assert.equal(land.prConflicting(OPEN('UNKNOWN', 'DIRTY')), true);
+  assert.equal(land.prConflicting(OPEN('CONFLICTING', 'UNKNOWN')), true);
+  assert.equal(land.prConflicting(OPEN('MERGEABLE', 'CLEAN')), false);
+  assert.equal(land.prConflicting(OPEN('MERGEABLE', 'BLOCKED')), false, 'a red or pending check is not a conflict');
+  assert.equal(land.prConflicting(OPEN('UNKNOWN', 'UNKNOWN')), false, 'mergeability still computing is not a conflict');
+  // publish-status merge_driver (snake_case, as mergeIfGreen returns it)
+  assert.equal(land.prConflicting({ reason: 'merge_conflict', mergeable: 'CONFLICTING', merge_state: 'DIRTY' }), true);
+  assert.equal(land.prConflicting({ reason: null, merge_state: 'DIRTY' }), true);
+  assert.equal(land.prConflicting({ reason: 'failing_check:unit', mergeable: 'MERGEABLE', merge_state: 'BLOCKED' }), false);
+  for (const nothing of [null, undefined, {}]) assert.equal(land.prConflicting(nothing), false);
+});
+
+await test('the conflict lines name the fix — merge main in, then re-run this task\'s ship — and carry the card', () => {
+  const text = land.conflictPrLines(4242).join('\n');
+  assert.ok(text.includes(CONFLICT_LINE), text);
+  assert.ok(text.includes('git merge origin/main'), 'merge, never rebase: the branch is already published (strand-fix case C)');
+  assert.ok(!/rebase/.test(text), 'a rebase makes every later push non-fast-forward');
+  assert.ok(text.includes('node scripts/gds/ship.js 4242'), 'the resume names THIS task');
+  assert.ok(text.includes(CARDS.merge_conflict.happened), 'the plain-words card for merge_conflict follows');
+});
+
+await test('landConflicted is a bail with the fix as its next step, never pending', async () => {
+  const { result } = await capture(() => land.landConflicted(4242));
+  assert.equal(result.ok, false);
+  assert.equal(result.pending, false, 'pending is what makes the card say "landing automatically"');
+  assert.match(result.reason, /conflicts with main/);
+  assert.equal(result.nextStep, '/strand-fix 4242');
+  assert.equal(result.bailId, null, 'untagged, so ship-merge never reroutes it into the PR path it already took');
+});
+
+// ---- the gh path: pollCiDeploy ----
+
+await test('pollCiDeploy: a PR conflicting for the whole wait bails, says so ONCE, and never prints the pending banner', async () => {
+  const calls = [];
+  const { result, out } = await capture(() => land.pollCiDeploy(4242, 'task-4242', 'abc', {
+    ghJson: ghScript([OPEN('CONFLICTING', 'DIRTY')], calls), pause: noPause,
+  }));
+  assert.equal(result.pending, false, 'a conflicting PR is not "landing automatically"');
+  assert.equal(result.nextStep, '/strand-fix 4242');
+  assert.equal(count(out, CONFLICT_LINE), 1, `said once when it appeared, not on every poll:\n${out}`);
+  assert.ok(!out.includes(PENDING_BANNER), 'the "NOT a failure" banner is for a land that is on its way');
+  assert.ok(!out.includes(CARDS.land_pending.next), 'nor the "Nothing to do" card');
+  assert.ok(calls[0].includes('mergeable') && calls[0].includes('mergeStateStatus'), `the poll asks GitHub whether it can merge: ${calls[0]}`);
+});
+
+await test('pollCiDeploy: a mergeable PR that merely outlasts the wait is still pending, as before', async () => {
+  const { result, out } = await capture(() => land.pollCiDeploy(4242, 'task-4242', 'abc', {
+    ghJson: ghScript([OPEN('MERGEABLE', 'BLOCKED')]), pause: noPause,
+  }));
+  assert.equal(result.pending, true);
+  assert.ok(out.includes(PENDING_BANNER));
+  assert.equal(count(out, CONFLICT_LINE), 0);
+});
+
+await test('pollCiDeploy: a conflict the server heals inside the window is announced, then the wait ends pending', async () => {
+  const states = [OPEN('UNKNOWN', 'UNKNOWN'), OPEN('CONFLICTING', 'DIRTY'), OPEN('CONFLICTING', 'DIRTY'), OPEN('MERGEABLE', 'BLOCKED')];
+  const { result, out } = await capture(() => land.pollCiDeploy(4242, 'task-4242', 'abc', {
+    ghJson: ghScript(states), pause: noPause,
+  }));
+  assert.equal(count(out, CONFLICT_LINE), 1);
+  assert.equal(result.pending, true, 'healed: the checks re-run and auto-merge is armed again');
+});
+
+await test('pollCiDeploy: a heal undone by main moving on is announced again, and the verdict is the LAST state', async () => {
+  const states = [OPEN('CONFLICTING', 'DIRTY'), OPEN('MERGEABLE', 'BLOCKED'), OPEN('CONFLICTING', 'DIRTY')];
+  const { result, out } = await capture(() => land.pollCiDeploy(4242, 'task-4242', 'abc', {
+    ghJson: ghScript(states), pause: noPause,
+  }));
+  assert.equal(count(out, CONFLICT_LINE), 2);
+  assert.equal(result.pending, false);
+});
+
+await test('pollCiDeploy: a gh that predates the mergeable fields falls back to the old read, no worse than before', async () => {
+  const calls = [];
+  const oldGh = (args) => (args.join(' ').includes('mergeable') ? null : { state: 'OPEN', mergeCommit: null });
+  const { result, out } = await capture(() => land.pollCiDeploy(4242, 'task-4242', 'abc', {
+    ghJson: ghScript([oldGh], calls), pause: noPause,
+  }));
+  assert.equal(result.pending, true, 'with nothing to say about mergeability, the old verdict stands');
+  assert.equal(count(out, CONFLICT_LINE), 0);
+  assert.ok(calls.some((c) => c.endsWith('--json state,mergeCommit')), 'the two-field read was the fallback');
+});
+
+await test('pollCiDeploy: a failed read keeps the last answer instead of forgetting the conflict', async () => {
+  const states = [OPEN('CONFLICTING', 'DIRTY'), null];
+  const { result } = await capture(() => land.pollCiDeploy(4242, 'task-4242', 'abc', {
+    ghJson: ghScript(states), pause: noPause,
+  }));
+  assert.equal(result.pending, false, 'a gh hiccup at the end must not turn a conflict back into "landing automatically"');
+});
+
+// ---- the server path: pollServerPublish ----
+
+const status = (merge_driver) => async () => ({
+  ok: true, data: { merged: false, pr_state: 'open', deploy_status: null, reconcile_blocked: null, merge_driver },
+});
+
+await test('pollServerPublish: a merge_conflict from the server is named once, and the timeout bails', async () => {
+  const { result, out } = await capture(() => land.pollServerPublish(4242, 'task-4242', {
+    readStatus: status({ reason: 'merge_conflict', mergeable: 'CONFLICTING', merge_state: 'DIRTY', rollup_state: 'SUCCESS' }),
+    pause: noPause,
+  }));
+  assert.equal(count(out, CONFLICT_LINE), 1, out);
+  assert.ok(!out.includes('is RED'), 'green checks: a conflict is not a red PR');
+  assert.ok(!out.includes(PENDING_BANNER));
+  assert.equal(result.pending, false);
+  assert.equal(result.nextStep, '/strand-fix 4242');
+});
+
+await test('pollServerPublish: a red check still reads RED and still waits pending — this change does not touch it', async () => {
+  const { result, out } = await capture(() => land.pollServerPublish(4242, 'task-4242', {
+    readStatus: status({ reason: 'failing_check:unit', mergeable: 'MERGEABLE', merge_state: 'BLOCKED' }),
+    pause: noPause,
+  }));
+  assert.ok(out.includes('is RED'));
+  assert.equal(count(out, CONFLICT_LINE), 0);
+  assert.equal(result.pending, true);
+});
+
+console.log(`\nship-land conflict signal (task 1003499) tests: ${passed} passed, ${failed} failed`);
+process.exitCode = failed > 0 ? 1 : 0;