@bongos/core 1.19.761 → 1.19.762

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.761",
-  "core_contract": "1.19.761",
-  "source_commit": "3412fa5f1d7bb5d383191d64806396f61b136ae5",
+  "core_version": "1.19.762",
+  "core_contract": "1.19.762",
+  "source_commit": "4235a1ef680b4e7b79d8e61dc88b68069bc48d5f",
   "source_ref": "HEAD",
-  "built_at": "2026-09-16T03:36:29.589Z",
+  "built_at": "2026-09-16T03:56:12.759Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 483,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2115,
+    "functional_verbatim": 2116,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2623,
-  "tree_sha256": "e9ee270455be1db1f07c7c206e5f9ba6a408a2f231634a18330a70ac78a0ed59",
+  "file_count": 2624,
+  "tree_sha256": "7561f06e166d4cb1fa763b4771e03e57bba45299206df6dc706609de095557a3",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2512,7 +2512,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "94b5d8c1844e775937a9acec9a78b5c2a789ed6e8e194835c02cd0d2634a4d29"
+      "sha256": "6eafab6b4df93ff7ed5abfb7c2d7ed203d4a277cb9533fa262653e6ada53a4de"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7567,12 +7567,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "172d01adc5b82fa70d7079ec41e84a7a99b89b84c40c58d8d383b45c7a18f584"
+      "sha256": "b20ee554299dfd5a29d5877d1eb9df41f460d30f1db26526485b4588228ef2e3"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "7f3d59f7939972bb1a32c493f4203e0c22286a3296ae69d9a11a06ed2c5d62a9"
+      "sha256": "222eb11d6d265b2235b1a7455707bc9bc9aa2210bcec0deb34dcbfdc12de784d"
     },
     {
       "path": "public-docs/index.html",
@@ -8062,7 +8062,7 @@
     {
       "path": "scripts/gds/fitness-ratchets.js",
       "mode": "0000644",
-      "sha256": "7a0828405f5069ef97dedfa0874c156507f3ec10651c0e45cfd62d31315275d7"
+      "sha256": "b3f4092fffd30e50cb145b524beeed5d483132f52e77e37a7ab9c18bbf300bc7"
     },
     {
       "path": "scripts/gds/fitness.js",
@@ -9382,7 +9382,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "3429cc6b1beee6916f92a274dd2e85be55cb7e10236d8d70c4a4a8cf7ac6387c"
+      "sha256": "9fca9034c480450daf57672bfecc9c7d09f8105fddd88d81ef8e46d025903cac"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -10532,7 +10532,7 @@
     {
       "path": "tests/fitness_ratchets.mjs",
       "mode": "0000644",
-      "sha256": "e33edfa4925694d824c042f1fd06a977f1ac14b5c1cb24b5326014ca9f86ece0"
+      "sha256": "949526efc49c317a7be7e33beea0643b29748f3fd4e914d3a3670ce9ce6aadeb"
     },
     {
       "path": "tests/fitness_two_root.mjs",
@@ -10589,6 +10589,11 @@
       "mode": "0000644",
       "sha256": "850113ed91babc9eb54dc22231f194d283fd3f94cee9deef1e6e0bf6f3a969c2"
     },
+    {
+      "path": "tests/github_push_stderr_truncation.mjs",
+      "mode": "0000644",
+      "sha256": "d400c1830c9255851682c1653841a616ab9088f6facb2a5893f0ec41a72626eb"
+    },
     {
       "path": "tests/github_repo_visibility.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -1996,5 +1996,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.759 with no explicit bump. run 35052040282. (task 1002620)
   1.19.761 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         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)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.761",
+  "version": "1.19.762",
   "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/fitness-ratchets.js

@@ -243,10 +243,20 @@ function knipIssueCount() {
 //
 // The file's own header says raising a baseline to pass CI is out of policy;
 // deleting the file must not be the loophole that raising it is not.
-function readBaselines() {
+//
+// `baselinePath` is injectable for TESTS ONLY (task 1003351) and defaults to the
+// real file, so every production caller is unchanged. The three task-1003227
+// cases used to prove the three unreadable shapes by renaming and overwriting the
+// repo's OWN config/fitness-baselines.json, restoring in a finally — and
+// run-unit-tests.js runs each file under a 90s execFileSync timeout, whose
+// SIGTERM skips the finally and leaves the last payload on disk. That is how a
+// real checkout ended up with {"_comment":"no metrics key"} committed-adjacent
+// and the sibling case dying on `Cannot read properties of undefined`. A test
+// must not have to survive being killed to leave the repo intact.
+function readBaselines(baselinePath = BASELINE_PATH) {
   let raw;
   try {
-    raw = fs.readFileSync(BASELINE_PATH, 'utf8');
+    raw = fs.readFileSync(baselinePath, 'utf8');
   } catch (e) {
     const missing = e && e.code === 'ENOENT';
     return {
@@ -355,9 +365,17 @@ function computeMetrics({ withDocs = true } = {}) {
 }
 
 // The fitness.js check (in-suite, hermetic — everything except knip).
-function checkQualityRatchets() {
-  const metrics = computeMetrics();
-  const { metrics: baselines, error: baselineError } = readBaselines();
+//
+// Both options are injectable for TESTS ONLY (task 1003351); fitness.js calls
+// this through `CHECKS.map((fn) => fn())`, with no arguments, so the defaults are
+// what production runs. `metrics` matters as much as `baselinePath` here: a test
+// that only wanted to prove an unreadable baseline file still paid for a full
+// computeMetrics() sweep — git ls-files plus every tracked .js plus the
+// docs-entropy scan, measured at 23.7s + 2.5s + 2.8s, i.e. ~29s of this file's
+// 29s runtime, which is what pushed it into the 90s timeout in the first place.
+function checkQualityRatchets({ baselinePath = BASELINE_PATH, metrics: injectedMetrics = null } = {}) {
+  const metrics = injectedMetrics === null ? computeMetrics() : injectedMetrics;
+  const { metrics: baselines, error: baselineError } = readBaselines(baselinePath);
   const { violations, warnings } = compareToBaselines(metrics, baselines);
   // task 1003227: an unreadable baseline file is a hard failure, not silence. Put it
   // FIRST so it is the headline rather than buried under per-metric noise.
@@ -434,6 +452,9 @@ if (require.main === module) main();
 
 module.exports = {
   checkQualityRatchets,
+  // Exported for tests/fitness_ratchets.mjs (task 1003351), which proves the
+  // injected baselinePath is honoured rather than silently falling back.
+  readBaselines,
   computeMetrics,
   compareToBaselines,
   duplicateWindowCount,

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.761'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.762'; // 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/fitness_ratchets.mjs

@@ -10,6 +10,71 @@ import { fileURLToPath } from 'node:url';
 
 const require = createRequire(import.meta.url);
 const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+// Task 1003351 — the tripwire, installed BEFORE fitness-ratchets.js is required.
+// Fixing today's three cases only fixes today's three cases; the hazard is the
+// SHAPE, and it is an easy one to reach for again ("just back it up and restore
+// in a finally"). A finally is not a guarantee — run-unit-tests.js kills this
+// file on a 90s timeout and SIGTERM skips it — so the rule is stronger than
+// "restore afterwards": a test in this file may not write under <ROOT>/config at
+// all. Failing at the write names the offending path, which is far easier to act
+// on than the delayed symptom it used to produce (a dirty tree, and a sibling
+// case dying on a mangled baseline one run later).
+//
+// WHICH ARGUMENT IS THE WRITE. This is the whole subtlety, and getting it wrong
+// makes the guard worse than none — it would read as comprehensive while missing
+// the exact call the original bug used. fs.copyFileSync(src, DEST) and
+// fs.renameSync(old, NEW) write to their SECOND argument, so a restore-direction
+// `fs.copyFileSync(backup, real)` — precisely what the old `finally` blocks ran —
+// passes a harmless temp path in position 0. Every method is therefore listed
+// with the argument indices that are WRITE positions, not assumed to be [0].
+// renameSync guards BOTH: position 1 writes into config/, and position 0 moves a
+// file OUT of it, which is how the ABSENT-baseline case used to work.
+const CONFIG_WRITE_ARGS = {
+  writeFileSync: [0],
+  appendFileSync: [0],
+  unlinkSync: [0],
+  rmSync: [0],
+  truncateSync: [0],
+  mkdirSync: [0],
+  renameSync: [0, 1],
+  copyFileSync: [1],
+  cpSync: [1],
+  linkSync: [1],
+  symlinkSync: [1],
+};
+
+{
+  const fs = require('node:fs');
+  const CONFIG_DIR = path.join(ROOT, 'config');
+  const underConfig = (value) => {
+    // Only string paths are resolvable; an fd or a URL is not a path here and
+    // passes through to the real call untouched.
+    if (typeof value !== 'string') return null;
+    const resolved = path.resolve(value);
+    const inside = resolved === CONFIG_DIR || resolved.startsWith(CONFIG_DIR + path.sep);
+    return inside ? resolved : null;
+  };
+  for (const [name, writeArgs] of Object.entries(CONFIG_WRITE_ARGS)) {
+    const original = fs[name];
+    if (typeof original !== 'function') continue;
+    fs[name] = function guarded(...args) {
+      for (const i of writeArgs) {
+        const hit = underConfig(args[i]);
+        if (hit) {
+          throw new Error(
+            `tests/fitness_ratchets.mjs may not fs.${name} under <ROOT>/config — got ${hit} `
+            + `(argument ${i}). Task 1003351: a timeout SIGTERM skips your finally and the repo `
+            + 'keeps the payload. Pass a temp path via checkQualityRatchets({ baselinePath }) / '
+            + 'readBaselines(path) instead.',
+          );
+        }
+      }
+      return original.apply(this, args);
+    };
+  }
+}
+
 const rat = require(path.join(ROOT, 'scripts', 'gds', 'fitness-ratchets.js'));
 
 test('ratchet compare: worse fails, equal passes, better nudges, unknown warns', () => {
@@ -103,53 +168,102 @@ test('the committed baseline file parses and covers every hermetic metric', () =
 // (pure) for the metric-level rules and exercise the file-level rule by pointing at a
 // baseline that does not exist.
 
-test('1003227 an ABSENT baseline file makes the gate hard-fail, not pass', async () => {
+// Task 1003351: these three used to prove their point by renaming/overwriting the
+// repo's own config/fitness-baselines.json and restoring in a `finally`. That is
+// only safe if the process is allowed to finish, and it is not: run-unit-tests.js
+// runs each test file under execFileSync with a 90s timeout, and the SIGTERM that
+// enforces it skips `finally` entirely. Since each case also called the real
+// checkQualityRatchets() — a ~29s full-repo sweep — this file sat right at the
+// timeout, so the kill was the normal outcome rather than the rare one. It left
+// {"_comment":"no metrics key"} as the committed file's contents, which then made
+// the sibling case die on `Cannot read properties of undefined (reading
+// 'oversized_file_count')` and the working tree dirty. Observed on Windows
+// 2026-08-29; standalone `node tests/fitness_ratchets.mjs` never reproduced it,
+// because nothing imposes the timeout there.
+//
+// Now each case owns a baseline file in its own temp dir and injects synthetic
+// metrics, so there is no sweep, no shared file, and nothing to restore. A
+// killed process leaves the repo exactly as it found it.
+const tmpBaseline = (contents) => {
   const fs = require('node:fs');
-  const real = rat.BASELINE_PATH;
-  const backup = `${real}.1003227-test-backup`;
-  const had = fs.existsSync(real);
-  if (had) fs.renameSync(real, backup);
-  try {
-    const r = rat.checkQualityRatchets();
-    assert.equal(r.hardFail, true, 'a gate that cannot read its floors must not report a pass');
-    assert.ok(r.violations.length > 0, 'and it must say so as a VIOLATION, not a warning');
-    assert.match(r.violations[0], /MISSING/, 'the first violation names the real cause');
-    assert.match(r.violations[0], /fails CLOSED/i, 'and states the posture explicitly');
-  } finally {
-    if (had) fs.renameSync(backup, real);
-  }
+  const os = require('node:os');
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'ratchet-baseline-'));
+  const file = path.join(dir, 'fitness-baselines.json');
+  if (contents !== null) fs.writeFileSync(file, contents);
+  return file;
+};
+// Any non-empty metric map exercises compareToBaselines without a repo sweep. An
+// unknown metric is a WARNING, never a violation, so violations[0] is the
+// baseline error itself — which is the whole point of each assertion below.
+const SYNTHETIC_METRICS = { excess_lines_total: 1 };
+
+test('1003227 an ABSENT baseline file makes the gate hard-fail, not pass', async () => {
+  const r = rat.checkQualityRatchets({ baselinePath: tmpBaseline(null), metrics: SYNTHETIC_METRICS });
+  assert.equal(r.hardFail, true, 'a gate that cannot read its floors must not report a pass');
+  assert.ok(r.violations.length > 0, 'and it must say so as a VIOLATION, not a warning');
+  assert.match(r.violations[0], /MISSING/, 'the first violation names the real cause');
+  assert.match(r.violations[0], /fails CLOSED/i, 'and states the posture explicitly');
 });
 
 test('1003227 a MALFORMED baseline file also hard-fails', async () => {
-  const fs = require('node:fs');
-  const real = rat.BASELINE_PATH;
-  const backup = `${real}.1003227-test-backup2`;
-  const had = fs.existsSync(real);
-  if (had) fs.copyFileSync(real, backup);
-  try {
-    fs.writeFileSync(real, '{ this is not json');
-    const r = rat.checkQualityRatchets();
-    assert.equal(r.hardFail, true, 'unparseable is no more verifiable than absent');
-    assert.match(r.violations[0], /not valid JSON/);
-  } finally {
-    if (had) { fs.copyFileSync(backup, real); fs.unlinkSync(backup); }
-  }
+  const r = rat.checkQualityRatchets({
+    baselinePath: tmpBaseline('{ this is not json'), metrics: SYNTHETIC_METRICS,
+  });
+  assert.equal(r.hardFail, true, 'unparseable is no more verifiable than absent');
+  assert.match(r.violations[0], /not valid JSON/);
 });
 
 test('1003227 a baseline file with no "metrics" object hard-fails', async () => {
+  const r = rat.checkQualityRatchets({
+    baselinePath: tmpBaseline(JSON.stringify({ _comment: 'no metrics key' })),
+    metrics: SYNTHETIC_METRICS,
+  });
+  assert.equal(r.hardFail, true);
+  assert.match(r.violations[0], /no "metrics" object/);
+});
+
+test('1003351 the config/ write-guard actually fires — a tripwire nobody has tripped is not a tripwire', () => {
   const fs = require('node:fs');
-  const real = rat.BASELINE_PATH;
-  const backup = `${real}.1003227-test-backup3`;
-  const had = fs.existsSync(real);
-  if (had) fs.copyFileSync(real, backup);
-  try {
-    fs.writeFileSync(real, JSON.stringify({ _comment: 'no metrics key' }));
-    const r = rat.checkQualityRatchets();
-    assert.equal(r.hardFail, true);
-    assert.match(r.violations[0], /no "metrics" object/);
-  } finally {
-    if (had) { fs.copyFileSync(backup, real); fs.unlinkSync(backup); }
-  }
+  // Every probe is chosen so an UNGUARDED call cannot damage anything: each one
+  // names a source or a parent directory that does not exist, so without the
+  // guard it raises ENOENT instead of moving a real file into config/. That is
+  // what makes the MESSAGE match load-bearing rather than decorative — a bare
+  // assert.throws() would pass on the very failure it exists to catch.
+  const guarded = /may not fs\.\w+ under <ROOT>\/config/;
+  const real = path.join(ROOT, 'config', 'fitness-baselines.json');
+  const absent = path.join(ROOT, 'config', '.1003351-absent-dir', 'probe.json');
+  const noSuchSource = path.join(ROOT, 'config', '..', '.1003351-no-such-source');
+
+  assert.throws(() => fs.unlinkSync(real), guarded, 'unlinkSync on the real baseline');
+  assert.throws(() => fs.writeFileSync(absent, 'x'), guarded,
+    'a NESTED write under config/ — the guard is on the prefix, not one filename');
+
+  // The destination-argument cases. These are the ones that matter most: they are
+  // the restore direction the original buggy finally blocks used, and a guard that
+  // only inspected argument 0 would wave every one of them through.
+  assert.throws(() => fs.copyFileSync(noSuchSource, real), guarded,
+    'copyFileSync writes to argument 1 — the restore call the old tests ran');
+  assert.throws(() => fs.renameSync(noSuchSource, real), guarded,
+    'renameSync writes to argument 1');
+  assert.throws(() => fs.renameSync(real, noSuchSource), guarded,
+    'renameSync argument 0 moves the baseline OUT of config/ — the ABSENT case');
+
+  // And it is a guard, not a blanket ban on writing: temp paths still work, and a
+  // copy whose DESTINATION is outside config/ is legitimate even when it reads
+  // the real baseline.
+  const tmpDest = tmpBaseline('{"metrics":{}}');
+  assert.ok(fs.existsSync(tmpDest), 'writes outside config/ are untouched');
+  fs.copyFileSync(real, tmpDest);
+  assert.ok(fs.readFileSync(tmpDest, 'utf8').includes('metrics'), 'reading the real baseline is allowed');
+});
+
+test('1003351 the real baseline path still reads cleanly — the injected path is a test seam, not a bypass', () => {
+  const real = rat.readBaselines();
+  assert.equal(real.error, null, 'the committed baseline file parses');
+  assert.ok(real.metrics && typeof real.metrics === 'object', 'and yields a metrics map');
+  const injected = rat.readBaselines(tmpBaseline(JSON.stringify({ metrics: { only_me: 1 } })));
+  assert.deepEqual(injected.metrics, { only_me: 1 }, 'an injected path is actually honoured');
+  assert.notDeepEqual(injected.metrics, real.metrics, 'and does not fall back to the real file');
 });
 
 test('1003227 a missing KEY for a NEW metric stays a warning (adding a metric must not brick CI)', () => {

package/tests/github_push_stderr_truncation.mjs

@@ -0,0 +1,139 @@
+// tests/github_push_stderr_truncation.mjs — the builder-facing git stderr must
+// keep the line that names the CAUSE, even when the cap bites (task 1003199).
+//
+// THE INCIDENT. The server-mediated publish rejected three pushes with
+// `remote: fatal error in commit_refs`. The server log kept that line; the
+// builder's client did not. stderr was head-sliced at 500 chars (and again at 200
+// on the way out), so what reached the person who had to act was clipped mid-word
+// at `error: failed` — naming neither cause nor remedy. They correctly stopped and
+// filed blocker 1000117; diagnosing it took ten minutes in a separate session, the
+// round trip took a day, and two finished tasks sat outside main throughout.
+//
+// Task 1003222 fixed the truncation: the cap went 500 → 8000 and became head+tail
+// with a loud marker instead of a blind head-slice. It exported truncateLoudly
+// "so its behaviour is testable, not just its effect" — and then no test was
+// written. This is that test.
+//
+// WHY THE SHAPE OF THE FIXTURES MATTERS. git puts the useful line LAST: the
+// `remote:` lines follow the progress chatter, and a non-fast-forward failure pads
+// itself with a long `hint:` block. A head-only truncation therefore throws away
+// precisely the causal line, on precisely the errors that need it. Both fixtures
+// below are built to EXCEED the cap — the originating row's own warning was that a
+// synthetic string under 500 chars cannot fail this test, and under the 8000-char
+// cap that trap is even easier to fall into.
+//
+// Run:  node --test tests/github_push_stderr_truncation.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { truncateLoudly, STDERR_MAX, scrubCredential } = require('../modules/lifecycle/github-push.js');
+
+// Progress chatter git emits before it ever reaches the verdict. Padded past the
+// cap so the truncation genuinely bites.
+const chatter = (n) => Array.from({ length: n },
+  (_, i) => `Enumerating objects: ${i}, done.\nCounting objects: ${i}% (${i}/${n}), done.`).join('\n');
+
+// CLASS 1 — the blocker-1000117 shape: a server-side rejection whose cause is the
+// LAST line of the stream.
+const COMMIT_REFS = [
+  'Enumerating objects: 41, done.',
+  chatter(400),
+  'Writing objects: 100% (23/23), 4.21 KiB | 1.05 MiB/s, done.',
+  'Total 23 (delta 17), reused 0 (delta 0), pack-reused 0',
+  'remote: fatal error in commit_refs',
+  'To https://github.com/example/repo.git',
+  ' ! [remote rejected] task-1003199 -> task-1003199 (failure)',
+  "error: failed to push some refs to 'https://github.com/example/repo.git'",
+].join('\n');
+
+// CLASS 2 — non-fast-forward. Real shape: progress chatter, then the verdict, then
+// a long `hint:` block. The hints are the padding a head-slice would preserve at
+// the cause's expense, and they sit AFTER the verdict, which is why keeping a tail
+// is what saves it.
+const NON_FAST_FORWARD = [
+  chatter(600),
+  'To https://github.com/example/repo.git',
+  ' ! [rejected]        task-1003199 -> task-1003199 (fetch first)',
+  "error: failed to push some refs to 'https://github.com/example/repo.git'",
+  'hint: Updates were rejected because the remote contains work that you do not',
+  'hint: have locally. This is usually caused by another repository pushing to',
+  'hint: the same ref. If you want to integrate the remote changes, use',
+  "hint: 'git pull' before pushing again.",
+  'hint: See the "Note about fast-forwards" in "git push --help" for details.',
+].join('\n');
+
+test('precondition: both fixtures exceed the cap, or this whole file proves nothing', () => {
+  assert.ok(COMMIT_REFS.length > STDERR_MAX, `commit_refs fixture is ${COMMIT_REFS.length}, cap ${STDERR_MAX}`);
+  assert.ok(NON_FAST_FORWARD.length > STDERR_MAX, `nff fixture is ${NON_FAST_FORWARD.length}, cap ${STDERR_MAX}`);
+});
+
+test('a commit_refs failure keeps the line that names the cause', () => {
+  const out = truncateLoudly(COMMIT_REFS);
+  assert.ok(out.includes('remote: fatal error in commit_refs'),
+    'the causal line is the whole reason stderr is attached at all');
+  assert.ok(out.includes('! [remote rejected]'), 'and the rejection line beside it');
+});
+
+test('a non-fast-forward failure keeps ! [rejected] and the error line', () => {
+  const out = truncateLoudly(NON_FAST_FORWARD);
+  assert.ok(out.includes('! [rejected]'), 'the verdict line');
+  assert.ok(out.includes('error: failed to push some refs'), 'the error line');
+});
+
+test('the truncation SAYS it truncated — never a message that just stops', () => {
+  const out = truncateLoudly(COMMIT_REFS);
+  assert.match(out, /characters omitted/,
+    'a silently clipped message reads like the whole message; that is what cost the day');
+  assert.match(out, /full text in the server log/, 'and it names where the rest lives');
+});
+
+test('the output stays bounded — the cap is still a real payload guard', () => {
+  const out = truncateLoudly(COMMIT_REFS);
+  // cap + the marker itself; the marker is deliberately outside the budget so the
+  // kept head and tail are each a full share.
+  assert.ok(out.length < STDERR_MAX + 200, `bounded, got ${out.length}`);
+});
+
+test('text within the cap is returned untouched — no marker on a short error', () => {
+  const short = 'remote: fatal error in commit_refs\nerror: failed to push some refs';
+  assert.equal(truncateLoudly(short), short);
+});
+
+test('both ends survive: a head-only slice would drop the tail, a tail-only the head', () => {
+  const out = truncateLoudly(NON_FAST_FORWARD);
+  assert.ok(out.startsWith('Enumerating objects'), 'the head is kept — the run did start');
+  assert.ok(out.trimEnd().endsWith('"git push --help" for details.'),
+    'and the tail, which is where git puts the verdict and its remedy');
+});
+
+// The shape of the guarantee, stated rather than assumed. head+tail keeps the two
+// ENDS, so a verdict in the exact MIDDLE of a stream far larger than the cap is
+// lost. That is not a defect for the two classes this task is about — git puts the
+// verdict at the end of both — but it is the boundary of what the current
+// truncation promises, and a future reader should not have to rediscover it. If a
+// failure class ever turns up whose cause sits mid-stream, THIS is the test that
+// says the fix must become line-aware (prefer remote:/error:/fatal: over hint:)
+// rather than merely bigger.
+test('KNOWN LIMIT: a cause buried mid-stream is not preserved — head+tail keeps the ends', () => {
+  const buried = [chatter(400), 'remote: fatal error in commit_refs', chatter(400)].join('\n');
+  assert.ok(buried.length > STDERR_MAX * 2, 'the fixture must dwarf the cap for the middle to be dropped');
+  const out = truncateLoudly(buried);
+  assert.ok(!out.includes('remote: fatal error in commit_refs'),
+    'documenting the boundary: if this starts passing, the truncation became smarter and this test should be rewritten, not deleted');
+});
+
+test('empty and non-string input do not throw', () => {
+  for (const v of ['', null, undefined, 0]) assert.equal(truncateLoudly(v), '');
+});
+
+test('truncation never resurrects a scrubbed credential', () => {
+  // scrubCredential runs BEFORE truncateLoudly on both call sites. Pin the order's
+  // consequence: a token in the tail half must not reappear in the kept tail.
+  const withToken = [chatter(400), 'remote: https://x-access-token:ghp_AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH@github.com/e/r.git', 'error: failed'].join('\n');
+  const out = truncateLoudly(scrubCredential(withToken));
+  assert.ok(!out.includes('ghp_AAAABBBBCCCCDDDDEEEEFFFFGGGGHHHH'), 'the token must not survive');
+  assert.ok(out.includes('error: failed'), 'while the causal tail still does');
+});