@bongos/core 1.19.819 → 1.19.820

package/scripts/gds/ship-regen.js

@@ -235,6 +235,34 @@ function regenerateFileMap() {
   return 'committed-nofatal';
 }
 
+// docs/copy-registry.json + docs/copy-inventory.md — the reader-facing copy the UI
+// actually renders (task 1003556).
+//
+// WHY IT HAS TO RUN HERE. Every row in the registry carries a `line`, so editing ANY
+// scanned UI file shifts line numbers and makes tests/copy_inventory.mjs red — on the
+// PR's MERGE ref, not on the branch, which is the worst place to find out. Nothing in
+// the ship path regenerated it (grep for copy-inventory across ship.js, ship-regen.js
+// and ship-preflight-steps.js used to return zero hits) and fitness did not cover the
+// pair either, so the builder got no local signal at all and learned from CI.
+//
+// Task 1003546 fixed the SERVER-side merge heals for the same artifact. Those repair a
+// strand after it happens; this is the prevention, so the PR is not born stale.
+function regenerateCopyInventory() {
+  console.log('  regenerating the copy registry + inventory from the shipped tree...');
+  shellOk(`"${process.execPath}" ${JSON.stringify(path.join(__dirname, 'copy-inventory.js'))}`);
+  const dirty = gitOk('git status --porcelain docs/copy-registry.json docs/copy-inventory.md');
+  if (!dirty) {
+    console.log('  copy registry already current — nothing to commit');
+    return 'current';
+  }
+  shellOk('git add docs/copy-registry.json docs/copy-inventory.md');
+  if (shellOk('git commit -m "chore(copy): auto-regenerate the copy registry + inventory (task 1003556)"')) {
+    console.log('  committed auto-regenerated copy registry');
+    return 'committed';
+  }
+  return 'committed-nofatal';
+}
+
 // ---------- merge serialization lock (#462 C4; extended in #269 C6) ----------
 //
 // autoMerge() mutates the SHARED main worktree (REPO_ROOT). Two concurrent
@@ -313,6 +341,7 @@ module.exports = {
   regenerateApiClient,
   regenerateApiDocs,
   regenerateDiagrams,
+  regenerateCopyInventory,
   regenerateFileMap,
   regenerateRepoMap,
   regenerateSessionIndex,

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

@@ -21,6 +21,22 @@ import { spawnSync } from 'node:child_process';
 import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+// HOME ALONE IS NOT ISOLATION ON WINDOWS (task 1003763).
+//
+// os.homedir() reads USERPROFILE on win32 and never consults HOME, so
+// `env: { ...process.env, HOME: home }` isolated nothing there: the installed CLI
+// saw the DEVELOPER'S REAL session file. That is precisely the false green the
+// comment below guards against — an unauthenticated-path assertion passing because
+// the machine happens to be signed in.
+//
+// HOMEDRIVE/HOMEPATH are os.homedir()'s second win32 source, so all four go. Named
+// rather than inlined twice: this is the third site in the repo to need it (after
+// tests/cli_sessions.mjs in task 1003760 and tests/cli_surface.mjs in task 1003941),
+// and every one of them got it half-right first.
+function homelessEnv(home, extra = {}) {
+  return { ...process.env, HOME: home, USERPROFILE: home, HOMEDRIVE: '', HOMEPATH: home, ...extra };
+}
 const BUILDER = path.join(REPO_ROOT, 'scripts', 'gds', 'build-cli-package.js');
 // Running npm from a test (task 1003529). On Windows `npm` is a .cmd shim: bare
 // 'npm' is ENOENT and 'npm.cmd' is EINVAL under Node 24's CVE-2024-27980 mitigation,
@@ -152,7 +168,7 @@ test('the packed tarball installs and every verb runs with no repo present', (t)
   // file on this machine cannot make a verb look healthier than it is.
   fs.writeFileSync(path.join(site, 'package.json'), JSON.stringify({ name: 'probe', private: true }));
   const installed = npm(['install', '--no-audit', '--no-fund', '--silent', path.join(site, tarball)], {
-    cwd: site, encoding: 'utf8', env: { ...process.env, HOME: home },
+    cwd: site, encoding: 'utf8', env: homelessEnv(home),
   });
   assert.equal(installed.status, 0, `npm install failed:\n${installed.stderr}`);
 
@@ -166,7 +182,7 @@ test('the packed tarball installs and every verb runs with no repo present', (t)
 
   const runVerb = (args) => spawnSync(process.execPath, [bongos, ...args], {
     cwd: site, encoding: 'utf8', input: '',
-    env: { ...process.env, HOME: home, CLOUDBONGOS_API_BASE: 'http://127.0.0.1:45999', NO_COLOR: '1' },
+    env: homelessEnv(home, { CLOUDBONGOS_API_BASE: 'http://127.0.0.1:45999', NO_COLOR: '1' }),
   });
 
   // help and version must work with nothing configured at all.

package/tests/hall_roster_world.mjs

@@ -271,11 +271,16 @@ test('sessions: every id on a row is a door, the earned figure is shown, the tot
   assert.match(html, /<div class="stat-row" id="stats-body"><\/div>/);
   const ths = (html.match(/<th[ >]/g) || []).length;
   // task 1002516: a tenth column, "Plain speech" — the transcript accessibility
-  // dimension the criterion asks to surface on the dashboard (ADR 0291). The
-  // per-cell contract (a not-scored session is a dash, never a zero) lives in
-  // tests/hall_sessions_ledger.mjs; this pin is only the column count.
-  assert.equal(ths, 10, 'ten columns: session, builder, tasks, earned, turns, tokens, tool errors, duration, plain speech, recorded');
-  assert.match(src, /colspan="10"/, 'the empty row spans them all');
+  // dimension the criterion asks to surface on the dashboard (ADR 0291).
+  // task 1003975: an eleventh, "Kind" — the session's derived shape, so the 54%
+  // of rows with no task chip are readable at all. The per-cell contracts (a
+  // not-scored session is a dash, never a zero; an unclassified one is a dash,
+  // never 'Unclear') live in tests/hall_sessions_ledger.mjs and
+  // tests/session_type.mjs; this pin is the column count AND that the empty row
+  // still spans them — a header added without widening the colspan leaves the
+  // empty state short by a column, which no screenshot pass would catch.
+  assert.equal(ths, 11, 'eleven columns: session, builder, kind, tasks, earned, turns, tokens, tool errors, duration, plain speech, recorded');
+  assert.match(src, new RegExp(`colspan="${ths}"`), 'the empty row spans them all');
   const fam = html.indexOf('/builders/oversight.css');
   assert.ok(fam > 0 && html.indexOf('/builders/sessions.css') > fam, 'sessions.html links the family sheet before its own');
 });

package/tests/home_isolation_guard.mjs

@@ -0,0 +1,95 @@
+// tests/home_isolation_guard.mjs — setting HOME for a child isolates nothing on
+// Windows (task 1003763).
+//
+// os.homedir() reads USERPROFILE on win32 and never consults HOME, so
+// `env: { ...process.env, HOME: tmp }` leaves the child looking at the developer's
+// real home — and their real CLI session. Three tasks fixed this one site at a time:
+// 1003760 (cli_sessions, which DESTROYED a live session), 1003941 (cli_surface) and
+// this one (cli_package). The last two are the dangerous shape — a test that isolates
+// nothing does not announce itself, it quietly stops testing what its comment claims.
+//
+// Run:  node tests/home_isolation_guard.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { checkHomeIsolation, offendingLines, stripComments, ALLOW } =
+  require('../scripts/gds/home-isolation-guard.js');
+
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+
+test('the live tree is clean, and the scan is not empty', () => {
+  const r = checkHomeIsolation();
+  assert.deepEqual(r.violations, [], r.violations.join('\n'));
+  // A guard that scans nothing passes for free. The note carries the counts so a
+  // silently-broken scan is visible rather than reassuring.
+  const scanned = Number(/^(\d+) test file/.exec(r.note)?.[1] ?? 0);
+  const sites = Number(/(\d+) of them build a child env/.exec(r.note)?.[1] ?? 0);
+  assert.ok(scanned > 100, `expected the whole tests/ tree, scanned ${scanned}`);
+  assert.ok(sites > 0, 'no file builds a child env with HOME — the pattern has drifted and this guard is inert');
+});
+
+test('the original broken shape IS caught', () => {
+  const src = 'const r = spawnSync(node, [x], { env: { ...process.env, HOME: home } });';
+  assert.equal(offendingLines(src).length, 1);
+});
+
+test('the fixed shape is not', () => {
+  const src = 'const r = spawnSync(node, [x], { env: { ...process.env, HOME: home, USERPROFILE: home } });';
+  assert.deepEqual(offendingLines(src), []);
+});
+
+test('a HELPER CALL SITE is not a child env', () => {
+  // tests/setup_smoke.mjs passes { HOME: fakeHome } to its own runSetup(), which adds
+  // USERPROFILE itself. Flagging the callers would point at the wrong line and, worse,
+  // train someone to "fix" three call sites instead of the one helper.
+  assert.deepEqual(offendingLines("runSetup(['--dry-run'], { HOME: fakeHome });"), []);
+});
+
+test('a COMMENT quoting the bug is not the bug', () => {
+  // Every file that fixed this now explains it by quoting the broken line. A raw text
+  // scan therefore reports exactly the files that already fixed it — which is how the
+  // first run of this guard produced three false positives.
+  assert.deepEqual(offendingLines('// env: { ...process.env, HOME: home } isolated nothing'), []);
+  assert.deepEqual(offendingLines('/* env: { ...process.env, HOME: home } */'), []);
+  assert.ok(!stripComments('// { ...process.env, HOME: x }').includes('HOME'));
+});
+
+test('a multi-line literal is still read', () => {
+  const src = [
+    'const r = spawnSync(node, [x], {',
+    '  env: {',
+    '    ...process.env,',
+    '    HOME: home,',
+    '  },',
+    '});',
+  ].join('\n');
+  assert.equal(offendingLines(src).length, 1, 'the literal wraps — a single-line matcher misses the real shape');
+});
+
+test('every allowlisted file exists and still means HOME differently', () => {
+  // An allowlist entry is a claim. If the file is gone, the claim is stale and the
+  // entry is a hole nobody is watching.
+  for (const [name, why] of ALLOW) {
+    const p = path.join(REPO_ROOT, 'tests', name);
+    let src;
+    try { src = readFileSync(p, 'utf8'); } catch {
+      assert.fail(`allowlisted tests/${name} no longer exists — remove the entry rather than leaving an unwatched hole`);
+    }
+    assert.ok(why && why.length > 20, `tests/${name} needs a reason, not just an exemption`);
+    assert.match(src, /HOME/, `tests/${name} no longer mentions HOME, so its exemption is dead`);
+  }
+});
+
+test('the two sites this task fixed are actually fixed', () => {
+  const src = readFileSync(path.join(REPO_ROOT, 'tests', 'cli_package.mjs'), 'utf8');
+  assert.deepEqual(offendingLines(src), []);
+  assert.match(src, /USERPROFILE/, 'cli_package must set USERPROFILE alongside HOME');
+  const surface = readFileSync(path.join(REPO_ROOT, 'tests', 'cli_surface.mjs'), 'utf8');
+  assert.deepEqual(offendingLines(surface), []);
+});

package/tests/session_type.mjs

@@ -0,0 +1,215 @@
+// tests/session_type.mjs — the session-type classifier and its filter
+// (task 1003975, from idea 1001033, goal 1000093).
+//
+// WHAT THIS FILE PINS, in order of what would actually go wrong:
+//   (1) the measured shapes. Each fixture is a real session's counters, taken
+//       from the 247-row sample the classifier's header records, so a retuning
+//       that looks harmless in the abstract has to face the corpus it was
+//       derived from.
+//   (2) that the ONE-SHOT boundary is the bimodal gap it was measured to be, and
+//       that it is computed as prompts (user turns MINUS tool results) — reading
+//       user_turns raw would call every subagent an interactive session, which
+//       is exactly the confusion the column exists to end.
+//   (3) that task_ids is never consulted. 82 of the sample's 179 automated rows
+//       carry a task id (a grader worker inherits the task it ran inside), so a
+//       classifier that reached for it would label them build sessions.
+//   (4) that a write tool wins over everything, and that Bash is NOT one — Bash
+//       is 75% of all tool calls in the corpus, so counting it as a write would
+//       collapse the vocabulary to a single value.
+//   (5) that the route's filter is validated against the classifier's own list,
+//       and that the filter reaches the tally as well as the page — a filter on
+//       only one of the two is how a table of 57 rows ends up under a headline
+//       claiming 4,595.
+//
+// Run:  node tests/session_type.mjs
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+
+process.env.NODE_ENV = 'test';
+const require = createRequire(import.meta.url);
+const st = require('../modules/sessions/session-type.js');
+
+// ---------------------------------------------------------------------------
+// Fixtures. Every one is a real sampled session reduced to what the classifier
+// reads; the ids in the comments are session_records ids from the 2026-09-17
+// sample so a later reader can go and look at the row itself.
+// ---------------------------------------------------------------------------
+
+// id 1007108 — a builder-sequence run: 70 turns, 42 tool calls, files written.
+const BUILD = {
+  metrics: { assistant_turns: 70, user_turns: 43, tool_result_count: 42, tool_use_count: 42 },
+  detail: [{ role: 'assistant', tools: ['Skill'] }, { role: 'assistant', tools: ['Bash', 'Write'] }],
+};
+
+// id 1007121 — a grader worker: one prompt in, one JSON verdict out, no tools.
+const GRADER = {
+  metrics: { assistant_turns: 2, user_turns: 1, tool_result_count: 0, tool_use_count: 0 },
+  detail: [{ role: 'user' }, { role: 'assistant', snippet: '{"security_score": 6}' }],
+};
+
+// id 1007117 — a panel subagent reading the codebase: 12 reads, but every user
+// turn is one of those reads coming back. One prompt started it.
+const PANEL = {
+  metrics: { assistant_turns: 23, user_turns: 13, tool_result_count: 12, tool_use_count: 12 },
+  detail: Array.from({ length: 12 }, () => ({ role: 'assistant', tools: ['Read'] })),
+};
+
+// id 1007109 — a person steering: 11 user turns of which 8 are tool results, so
+// three real prompts, and nothing was written.
+const EXPLORING = {
+  metrics: { assistant_turns: 13, user_turns: 11, tool_result_count: 8, tool_use_count: 8 },
+  detail: [{ role: 'assistant', tools: ['Bash'] }],
+};
+
+// No sampled row had this shape (0 of 247) — a person asking, with no tools at
+// all. It is here because the bucket must work the day it first happens.
+const TALKING = {
+  metrics: { assistant_turns: 9, user_turns: 5, tool_result_count: 0, tool_use_count: 0 },
+  detail: [{ role: 'user' }, { role: 'assistant' }, { role: 'user' }],
+};
+
+// ---------------------------------------------------------------------------
+// (1) The measured shapes.
+// ---------------------------------------------------------------------------
+
+test('each measured session shape classifies as itself', () => {
+  assert.equal(st.classifySession(BUILD), 'build');
+  assert.equal(st.classifySession(GRADER), 'automated');
+  assert.equal(st.classifySession(PANEL), 'automated');
+  assert.equal(st.classifySession(EXPLORING), 'exploration');
+  assert.equal(st.classifySession(TALKING), 'conversation');
+});
+
+test('every verdict is in the closed set', () => {
+  for (const fixture of [BUILD, GRADER, PANEL, EXPLORING, TALKING, {}, { metrics: {} }]) {
+    assert.ok(
+      st.SESSION_TYPES.includes(st.classifySession(fixture)),
+      `classify returned a type outside SESSION_TYPES for ${JSON.stringify(fixture).slice(0, 60)}`
+    );
+  }
+});
+
+// ---------------------------------------------------------------------------
+// (2) The one-shot boundary, and that it is PROMPTS and not user turns.
+// ---------------------------------------------------------------------------
+
+test('prompts are user turns minus tool results, floored at zero', () => {
+  assert.equal(st.humanPrompts({ user_turns: 13, tool_result_count: 12 }), 1);
+  assert.equal(st.humanPrompts({ user_turns: 11, tool_result_count: 8 }), 3);
+  // A disagreeing digest (an old row, a truncated transcript) must not produce a
+  // negative, which would sail under the one-shot boundary as if measured.
+  assert.equal(st.humanPrompts({ user_turns: 2, tool_result_count: 40 }), 0);
+  assert.equal(st.humanPrompts({}), 0);
+});
+
+test('the boundary sits between one prompt and two — the measured bimodal gap', () => {
+  assert.equal(st.ONE_SHOT_PROMPT_MAX, 1);
+  const at = { metrics: { assistant_turns: 20, user_turns: 11, tool_result_count: 10, tool_use_count: 10 }, detail: [{ role: 'assistant', tools: ['Read'] }] };
+  const over = { metrics: { assistant_turns: 20, user_turns: 12, tool_result_count: 10, tool_use_count: 10 }, detail: [{ role: 'assistant', tools: ['Read'] }] };
+  assert.equal(st.classifySession(at), 'automated', 'one prompt is an invocation');
+  assert.equal(st.classifySession(over), 'exploration', 'two prompts is someone steering');
+});
+
+test('reading user_turns raw would misread the panel subagent — the whole point', () => {
+  // 13 user turns looks like a long conversation; 12 of them are tool results.
+  assert.ok(PANEL.metrics.user_turns > 2, 'fixture still has the misleading raw count');
+  assert.equal(st.classifySession(PANEL), 'automated');
+});
+
+// ---------------------------------------------------------------------------
+// (3) task_ids is never consulted.
+// ---------------------------------------------------------------------------
+
+test('a task id cannot change the verdict', () => {
+  // The grader worker ran inside a ship and inherited its task. 82 of the
+  // sample's 179 automated rows look exactly like this.
+  const withTask = { ...GRADER, task_ids: [1003975, 1003841] };
+  assert.equal(st.classifySession(withTask), 'automated');
+  const buildWithout = { ...BUILD, task_ids: [] };
+  assert.equal(st.classifySession(buildWithout), 'build');
+});
+
+// ---------------------------------------------------------------------------
+// (4) Write tools win; Bash is not one.
+// ---------------------------------------------------------------------------
+
+test('a write tool outranks every other signal', () => {
+  // One prompt, one edit: an invocation that nonetheless changed the repo.
+  const oneShotEdit = {
+    metrics: { assistant_turns: 4, user_turns: 2, tool_result_count: 2, tool_use_count: 2 },
+    detail: [{ role: 'assistant', tools: ['Read'] }, { role: 'assistant', tools: ['Edit'] }],
+  };
+  assert.equal(st.classifySession(oneShotEdit), 'build');
+});
+
+test('Bash alone is not a build — it reads at least as often as it writes', () => {
+  assert.ok(!st.WRITE_TOOLS.has('Bash'));
+  const bashOnly = {
+    metrics: { assistant_turns: 21, user_turns: 13, tool_result_count: 11, tool_use_count: 11 },
+    detail: [{ role: 'assistant', tools: ['Bash'] }],
+  };
+  assert.equal(st.classifySession(bashOnly), 'exploration');
+});
+
+test('every editor the harness offers counts as a write', () => {
+  for (const tool of ['Edit', 'Write', 'MultiEdit', 'NotebookEdit']) {
+    const row = { metrics: { assistant_turns: 2, user_turns: 1, tool_result_count: 1, tool_use_count: 1 }, detail: [{ role: 'assistant', tools: [tool] }] };
+    assert.equal(st.classifySession(row), 'build', `${tool} should count as a write`);
+  }
+});
+
+test('a malformed detail never throws', () => {
+  assert.equal(st.usedWriteTool(null), false);
+  assert.equal(st.usedWriteTool('Edit'), false);
+  assert.equal(st.usedWriteTool([null, { tools: null }, { tools: [null, 7] }]), false);
+  assert.equal(st.usedWriteTool([{ tools: ['Edit'] }]), true);
+});
+
+// ---------------------------------------------------------------------------
+// (5) The vocabulary guard + the shared filter clause.
+// ---------------------------------------------------------------------------
+
+test('isSessionType accepts exactly the closed set', () => {
+  for (const t of st.SESSION_TYPES) assert.ok(st.isSessionType(t), `${t} should be valid`);
+  for (const bad of ['Build', 'build ', 'ops', '', null, undefined, 7, {}]) {
+    assert.ok(!st.isSessionType(bad), `${JSON.stringify(bad)} should be rejected`);
+  }
+});
+
+test('an empty digest is unknown, not a quiet conversation', () => {
+  assert.equal(st.classifySession({}), 'unknown');
+  assert.equal(st.classifySession({ detail: [], metrics: {} }), 'unknown');
+  assert.equal(st.classifySession(), 'unknown');
+});
+
+test('the type filter reaches the page query AND the tally, through one clause', async () => {
+  // The clause is shared by searchSessions and summarizeSessions precisely so the
+  // two cannot drift; this captures the SQL both emit and proves the predicate and
+  // its bound value are in each.
+  const emitted = [];
+  const pool = { query: async (sql, params) => { emitted.push({ sql, params }); return { rows: [{}] }; } };
+  const moduleApi = require('../src/module-api.js');
+  const realPool = moduleApi.pool;
+  Object.defineProperty(moduleApi, 'pool', { value: pool, configurable: true, writable: true });
+  delete require.cache[require.resolve('../modules/sessions/db.js')];
+  const db = require('../modules/sessions/db.js');
+  try {
+    await db.searchSessions({ sessionType: 'build' });
+    await db.summarizeSessions({ sessionType: 'build' });
+    assert.equal(emitted.length, 2);
+    for (const { sql, params } of emitted) {
+      assert.ok(/sr\.session_type = \$8/.test(sql), 'the type predicate is missing from one of the two queries');
+      assert.equal(params[7], 'build', 'the type is not bound as $8');
+    }
+    // Absent filter binds NULL, which the clause reads as "every kind" — not as a
+    // literal that would match no row.
+    emitted.length = 0;
+    await db.searchSessions({});
+    assert.equal(emitted[0].params[7], null);
+  } finally {
+    Object.defineProperty(moduleApi, 'pool', { value: realPool, configurable: true, writable: true });
+    delete require.cache[require.resolve('../modules/sessions/db.js')];
+  }
+});

package/tests/ship_regen_copy_inventory.mjs

@@ -0,0 +1,69 @@
+// tests/ship_regen_copy_inventory.mjs — the ship path keeps the copy registry fresh
+// (task 1003556).
+//
+// WHY THIS EXISTS. docs/copy-registry.json carries a LINE NUMBER per row, so editing
+// any scanned UI file (modules/hall-ui/public, modules/status-ui/public,
+// modules/public-landing/public) shifts them and stales the artifact. Nothing in the
+// ship path regenerated it — grep for copy-inventory across ship.js, ship-regen.js
+// and ship-preflight-steps.js used to return zero hits — and fitness did not gate it,
+// so the first signal a builder got was CI failing on the PR's MERGE ref. That is the
+// hardest place to attribute a failure: the branch is green, and what broke is the
+// combination.
+//
+// Task 1003546 fixed the SERVER-side merge heals for the same artifact; those repair a
+// strand after it happens. This is the prevention, and these tests pin the wiring
+// rather than the behaviour, because the failure mode is "nobody calls it".
+//
+// Run:  node tests/ship_regen_copy_inventory.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { readFileSync } from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const read = (rel) => readFileSync(path.join(REPO_ROOT, rel), 'utf8');
+
+test('ship-regen exports regenerateCopyInventory beside its siblings', () => {
+  const regen = require('../scripts/gds/ship-regen.js');
+  assert.equal(typeof regen.regenerateCopyInventory, 'function');
+  // The siblings it must sit beside — if one of these disappears the convention moved
+  // and this file should move with it, rather than silently guarding nothing.
+  for (const sib of ['regenerateFileMap', 'regenerateRepoMap', 'regenerateSessionIndex']) {
+    assert.equal(typeof regen[sib], 'function', `${sib} is the convention this follows`);
+  }
+});
+
+test('the merge path CALLS it — the whole bug was that nobody did', () => {
+  const src = read('scripts/gds/ship-merge.js');
+  assert.match(src, /regenerateCopyInventory\(\)/,
+    'ship-merge must invoke it, not merely import it');
+  // Called on the same beat as the other generated artifacts, not somewhere that runs
+  // only on a branch of the flow.
+  const idx = src.indexOf('regenerateCopyInventory()');
+  const fileMapIdx = src.indexOf('regenerateFileMap()');
+  assert.ok(fileMapIdx > 0 && Math.abs(idx - fileMapIdx) < 600,
+    'it should run beside the other regenerators, not in a separate branch of the flow');
+});
+
+test('fitness gates the pair, so a local run says so before CI does', () => {
+  const src = read('scripts/gds/fitness.js');
+  assert.match(src, /copy-inventory\.js.*--check|'--check'\]/s);
+  assert.ok(src.includes("'copy-inventory.js'"),
+    'the freshness check must run copy-inventory --check');
+  assert.match(src, /copy-registry\.json \+ docs\/copy-inventory\.md are STALE/,
+    'and name both artifacts plus the fix command in the violation');
+});
+
+test('the registry really is line-sensitive — the premise of all of the above', () => {
+  // If rows stopped carrying line numbers, none of this wiring would be needed and
+  // this file would be guarding a problem that no longer exists.
+  const reg = JSON.parse(read('docs/copy-registry.json'));
+  const rows = Array.isArray(reg) ? reg : (reg.entries || reg.rows || Object.values(reg).find(Array.isArray));
+  assert.ok(Array.isArray(rows) && rows.length > 0, 'the registry must have rows to be stale-able');
+  assert.ok(rows.some((r) => r && typeof r === 'object' && 'line' in r),
+    'rows carry a `line`, which is why any UI edit stales this artifact');
+});