@bongos/core 1.19.768 → 1.19.769

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.768",
-  "core_contract": "1.19.768",
-  "source_commit": "ec2107bdda1e0c2ee8404d14e539b83a836f767d",
+  "core_version": "1.19.769",
+  "core_contract": "1.19.769",
+  "source_commit": "5552e7252b67cc3192446a9c48ca2cd4faf10368",
   "source_ref": "HEAD",
-  "built_at": "2026-09-16T14:46:45.582Z",
+  "built_at": "2026-09-16T14:54:06.807Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 483,
     "agent_docs_stubbed": 25,
-    "functional_verbatim": 2123,
+    "functional_verbatim": 2125,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2631,
-  "tree_sha256": "9d2871bffc966902b2a18d7c59fc92a2e5ea137e0bee5675716ca3fbee9e01ef",
+  "file_count": 2633,
+  "tree_sha256": "8c9135931a565436af92fb7fc38953f0bf6b9ca8c6b608b91e9751c88dd62fe0",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2512,7 +2512,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "5c95283ebfac1200dcabcba2fa712b6b041be345412b92cd1f896e3648d9ecd0"
+      "sha256": "ffaeae011cd55895b3c16a2ee903e0593aa42a22cfceb3307c5228452c737948"
     },
     {
       "path": "docs/modules-contract.md",
@@ -7577,12 +7577,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "4f7ef5cc202176fb1c83a20baea17017b6adb0892051832a4bd6a440d57f1fcc"
+      "sha256": "17b6a246e7e14d3949244aff29ed7e63dc5bc5d65a7aeff2a463f8283fa5b4cc"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "ee2355bc92153c9c139cf79e19f22b80dda73a5a2abdd102b67830cb3bee0d14"
+      "sha256": "df0b9ff8dceb4cafd08db0a28bcbe92b1cbee04fefe4f811574257af0929901c"
     },
     {
       "path": "public-docs/index.html",
@@ -7812,7 +7812,7 @@
     {
       "path": "scripts/gds/build-cli-package.js",
       "mode": "0000644",
-      "sha256": "314004ef2af628fca5f572daca5e2404d1c2129b3ad650d715294cc26cc2fe13"
+      "sha256": "f3c15da424b2652ecb511d9a794cda1c037d500b8d810fb71bab2e31f41a0ca6"
     },
     {
       "path": "scripts/gds/bump-version.js",
@@ -7847,7 +7847,7 @@
     {
       "path": "scripts/gds/claim.js",
       "mode": "0000644",
-      "sha256": "22ac9d57c1ccc9fd76bd390d069c06896e3da4cd076a6c554a4335f8392b0783"
+      "sha256": "2d225377a6ab3bdc8e8cb195d5e6588517275179fe49100c42362c88a3465324"
     },
     {
       "path": "scripts/gds/classify-discipline.js",
@@ -8847,7 +8847,7 @@
     {
       "path": "scripts/gds/ship.js",
       "mode": "0000644",
-      "sha256": "a64455fdf9771e4ccb04b49d42b9bb0cb0fe45bc6cb36d4e5f3abe0c31fe99ff"
+      "sha256": "9c279a8852e46758e498334fbeb25e94be2895930a6c65b400c2c1baaac1c270"
     },
     {
       "path": "scripts/gds/skill-lint.js",
@@ -8912,7 +8912,7 @@
     {
       "path": "scripts/gds/start.js",
       "mode": "0000644",
-      "sha256": "7e4b7cd97e9a414cf55e1118c902b4ab17239d3810fe26e5b90aa18d6a948432"
+      "sha256": "8cf839a0db44d7b647cdd0ea394bdd31db924e54d4840a5f407f515c098c9de7"
     },
     {
       "path": "scripts/gds/status.js",
@@ -8939,6 +8939,11 @@
       "mode": "0000644",
       "sha256": "d3e542cf977f9aadad8f856defa6d809f3604e184cd261fbee7738aa1da736ea"
     },
+    {
+      "path": "scripts/gds/tree-preflight.js",
+      "mode": "0000644",
+      "sha256": "0655b96b842ba4073fbc72ca76204591b3339cc649f2f76986816ddfbe88ff6d"
+    },
     {
       "path": "scripts/gds/triage.js",
       "mode": "0000644",
@@ -9402,7 +9407,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "163989f8fd93a919241ac12e7627303618fc6d2d47b75f79e1b6fb875874a534"
+      "sha256": "3237d6ea069eae19ed9baf41a528984e21010defcfc5a0d96d34fd8eeca2fb4a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -12979,6 +12984,11 @@
       "mode": "0000644",
       "sha256": "61b50103967187dbff82f957d2faf6cc9ca5079b83531a5925fdeae61eb3c921"
     },
+    {
+      "path": "tests/tree_preflight.mjs",
+      "mode": "0000644",
+      "sha256": "d8382f7a608fc7511cd6e00e3a9efcb0283b8128b39cbe229fb07ae590b20c4b"
+    },
     {
       "path": "tests/triage_development.mjs",
       "mode": "0000644",

package/docs/module-api-changelog.md

@@ -2010,5 +2010,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.766 with no explicit bump. run 35109111074. (task 1002620)
   1.19.768 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.767 with no explicit bump. run 35110800163. (task 1002620)
+  1.19.769 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.768 with no explicit bump. run 35111616379. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.768",
+  "version": "1.19.769",
   "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/build-cli-package.js

@@ -56,6 +56,11 @@ const FILES = [
   'scripts/gds/install-git-hooks.js', // lazy dep of setup.js
   'scripts/gds/preflight.js',
   'scripts/gds/surface.js',   // who the output is for: agent vs terminal (task 1003680)
+  // The partial-checkout preflight (task 1003098). start/claim/ship require it
+  // ABOVE their first module require, so an absent file here breaks every verb in
+  // the published package -- which is exactly how tests/cli_package.mjs caught it.
+  // Pure: node builtins only, no repo, no network.
+  'scripts/gds/tree-preflight.js',
 
   // Read the board and move your own work along.
   'scripts/gds/start.js',

package/scripts/gds/claim.js

@@ -7,6 +7,21 @@
 // On success: prints the claim id, the task title, and the touches[] so the
 // builder knows the parallel-safety boundary they're working within.
 
+// TREE PREFLIGHT (task 1003098). A task-scoped dev box carries scripts/ and
+// src/bongos/ but not every modules/ directory, so the requires below can fail —
+// and Node's loader names only the FIRST missing one, which turned recovery into
+// guess-read-fix-repeat. This enumerates every missing requirement in one message
+// and exits before the first such require runs. It must stay ABOVE them.
+//
+// A PRE-REQUEST hard exit, like the usage banner and worktree guard: nothing has
+// been sent yet, so there is no in-flight request for cliExit to drain.
+const { action: _surfaceAction } = require('./surface.js');
+const { checkTree: _checkTree } = require('./tree-preflight.js');
+{
+  const _fault = _checkTree(__filename, { command: _surfaceAction("claim") });
+  if (_fault) { console.error(_fault); process.exit(1); }
+}
+
 const { execSync } = require('node:child_process');
 const fs = require('node:fs');
 const path = require('node:path');

package/scripts/gds/ship.js

@@ -77,6 +77,21 @@
 
 'use strict';
 
+// TREE PREFLIGHT (task 1003098). A task-scoped dev box carries scripts/ and
+// src/bongos/ but not every modules/ directory, so the requires below can fail —
+// and Node's loader names only the FIRST missing one, which turned recovery into
+// guess-read-fix-repeat. This enumerates every missing requirement in one message
+// and exits before the first such require runs. It must stay ABOVE them.
+//
+// A PRE-REQUEST hard exit, like the usage banner and worktree guard: nothing has
+// been sent yet, so there is no in-flight request for cliExit to drain.
+const { action: _surfaceAction } = require('./surface.js');
+const { checkTree: _checkTree } = require('./tree-preflight.js');
+{
+  const _fault = _checkTree(__filename, { command: _surfaceAction("ship") });
+  if (_fault) { console.error(_fault); process.exit(1); }
+}
+
 const { buildMergeArgv, gitArgvOk, sanitizeGitHubRefs } = require('./ship-git.js');
 const { apiErrorLine, normalizeApiError, postLandShipOutcome } = require('./ship-io.js');
 const { deriveTagsFromPaths } = require('./ship-surprise.js');

package/scripts/gds/start.js

@@ -52,6 +52,21 @@
 //
 // Returns JSON if --json is passed (for the slash command to parse cleanly).
 
+// TREE PREFLIGHT (task 1003098). A task-scoped dev box carries scripts/ and
+// src/bongos/ but not every modules/ directory, so the requires below can fail —
+// and Node's loader names only the FIRST missing one, which turned recovery into
+// guess-read-fix-repeat. This enumerates every missing requirement in one message
+// and exits before the first such require runs. It must stay ABOVE them.
+//
+// A PRE-REQUEST hard exit, like the usage banner and worktree guard: nothing has
+// been sent yet, so there is no in-flight request for cliExit to drain.
+const { action: _surfaceAction } = require('./surface.js');
+const { checkTree: _checkTree } = require('./tree-preflight.js');
+{
+  const _fault = _checkTree(__filename, { command: _surfaceAction("start") });
+  if (_fault) { console.error(_fault); process.exit(1); }
+}
+
 const { cliClient, requireSession, fmtUsd, printOnboardingNudge, printCostWarning, printNeedsNudge, hallBase, API_BASE, rewardPolicy, costPlusOnlyNote, isDispatcherIncompatError } = require('./cli-lib');
 const { contextPack, formatContextPackCompact } = require('./context-pack');
 const { depsFinding } = require('./preflight');

package/scripts/gds/tree-preflight.js

@@ -0,0 +1,241 @@
+'use strict';
+
+// scripts/gds/tree-preflight.js — does this checkout contain the code the command
+// is about to require? (task 1003098)
+//
+// THE FAILURE THIS REPLACES. On a TASK-SCOPED dev box — a supported, server-driven
+// configuration — `GET /box/source-access` returns a sparse path list that carries
+// `scripts`, `src/bongos`, `tests`, `clients`, `config` and NOT `modules/`, except
+// the one module the claimed task is scoped to. So the platform itself produces a
+// checkout in which its own entry-point commands cannot run, and they said so like
+// this:
+//
+//   $ node scripts/gds/ship.js
+//   Error: Cannot find module '../../modules/lifecycle/ship-preflight'
+//   Require stack: scripts/gds/ship-state.js
+//
+// A raw stack trace, naming ONE missing thing. Fix that one and the next run names
+// the next — the filer lost a whole session to guess-read-fix-repeat, and their
+// workaround (`git sparse-checkout disable` plus commenting out the re-scope cron)
+// is not something a builder should have to discover.
+//
+// ENUMERATION IS THE WHOLE POINT. Node's loader is lazy by construction: it fails
+// at the first unresolvable specifier and cannot tell you about the second, because
+// it never got there. That is correct behaviour for a module loader and useless as
+// a diagnosis. This runs BEFORE the first such require and reports every missing
+// requirement it can see in ONE message.
+//
+// THE REQUIRED LIST IS COMPUTED, NEVER DECLARED. A hand-kept list of "what ship.js
+// needs" is a second copy of the require graph, and it would be wrong within a
+// month — ship.js alone fans out across sixteen ship-*.js phase files. So the
+// preflight WALKS the graph the same way the loader would: read the entry file,
+// find its `require('./x')` siblings, follow them, and collect every
+// `require('../../modules/...')` it passes. Pure string work over the file system;
+// nothing is executed, so a missing module cannot throw during the check that
+// exists to report it.
+//
+// WHY IT DOES NOT SIMPLY TRY/CATCH EACH REQUIRE. Individual guards are what the
+// codebase already does where a module is genuinely OPTIONAL (context-pack.js's
+// classifier, cli-lib.js's reward policy) and they are right for that: the command
+// still works, slightly diminished. These requires are not optional — ship.js
+// cannot ship without `modules/lifecycle/ship-preflight`. Wrapping them would turn
+// a loud failure into a confusing one.
+//
+// PURE + INJECTED (`readFile`, `exists`) so the whole thing is testable with a fake
+// file system and no box — which is the layer task 1003098 asks for the test at.
+
+const fsMod = require('node:fs');
+const pathMod = require('node:path');
+
+const REPO_ROOT = pathMod.resolve(__dirname, '..', '..');
+
+// A require of this repo's OWN module code, which is what a scoped checkout drops.
+// Matches the two spellings the CLI uses; the quote style is captured so a require
+// written with double quotes is not silently invisible to the walk.
+const MODULE_REQUIRE_RE = /require\(\s*['"](\.\.\/\.\.\/modules\/[^'"]+)['"]\s*\)/g;
+// A sibling require inside scripts/gds/ — the edges the walk follows.
+const LOCAL_REQUIRE_RE = /require\(\s*['"](\.\/[^'"]+)['"]\s*\)/g;
+
+// Comments are stripped before scanning. A header that QUOTES a require to explain
+// why it was removed would otherwise be walked as a live edge — the defect filed as
+// task 1003832 against a test that scanned raw source, and one this file would hit
+// immediately, because its own header above quotes the exact failing require.
+function stripComments(src) {
+  return String(src)
+    .replace(/\/\*[\s\S]*?\*\//g, ' ')
+    .replace(/^\s*\/\/.*$/gm, ' ');
+}
+
+// Is the character at `index` inside a try{} block?
+//
+// THE DISTINCTION THIS DRAWS IS THE WHOLE CORRECTNESS OF THE PREFLIGHT. Several of
+// the CLI's module requires are deliberately guarded — context-pack.js's classifier
+// and cli-lib.js's reward policy both sit in a try and fall back honestly, so those
+// commands RUN on a scoped box. Reporting them as missing requirements would refuse
+// a command that works, which is a worse failure than the one being fixed: a builder
+// who could have shipped is told they cannot.
+//
+// A brace walk, not a parser — this repo ships none (the route-rank-check /
+// exec-path-guard precedent). It tracks a stack of block kinds and answers whether
+// any enclosing block was opened by `try`. Comments are already stripped by the
+// caller; string and regex literals containing braces are the known blind spot, and
+// the failure direction is benign: a miscount can only mis-scope a block, and the
+// classification is proved against the real files by tests/tree_preflight.mjs, which
+// pins that start.js's requires read optional and ship.js's read required.
+function insideTry(src, index) {
+  const stack = [];
+  for (let i = 0; i < index && i < src.length; i++) {
+    const c = src[i];
+    if (c === '{') {
+      // Look back past whitespace for the keyword that opened this block.
+      const before = src.slice(Math.max(0, i - 200), i);
+      stack.push(/\btry\s*$/.test(before) ? 'try' : 'block');
+    } else if (c === '}') {
+      stack.pop();
+    }
+  }
+  return stack.includes('try');
+}
+
+function matchAll(src, re) {
+  const out = [];
+  let m;
+  re.lastIndex = 0;
+  while ((m = re.exec(src)) !== null) out.push({ spec: m[1], index: m.index });
+  return out;
+}
+
+// Resolve a relative specifier the way require would, to a repo-relative posix path.
+function resolveRel(fromFile, spec, { root = REPO_ROOT } = {}) {
+  const abs = pathMod.resolve(pathMod.dirname(fromFile), spec);
+  const rel = pathMod.relative(root, abs).split(pathMod.sep).join('/');
+  return rel;
+}
+
+// Add the `.js` a bare specifier omits. Only ever appended — a spec that already
+// names an extension is left exactly as written, so a `.json` require still points
+// at the file it names.
+function withJsExt(rel) {
+  return /\.[a-z]+$/i.test(rel) ? rel : `${rel}.js`;
+}
+
+/**
+ * Every module-code path the entry point's require graph reaches. PURE.
+ *
+ * Follows `./sibling` edges inside scripts/gds/ transitively and collects the
+ * `../../modules/...` leaves. A file it cannot read is skipped rather than thrown
+ * on: this runs on a checkout that is by definition incomplete, and a preflight
+ * that crashes while diagnosing a partial tree is worse than the trace it replaces.
+ *
+ * @returns {string[]} repo-relative posix paths, deduped, stable order
+ */
+function requiredModulePaths(entryFile, { readFile, root = REPO_ROOT } = {}) {
+  const read = readFile || ((f) => fsMod.readFileSync(f, 'utf8'));
+  const seen = new Set();
+  const found = new Set();
+  const queue = [pathMod.resolve(entryFile)];
+
+  while (queue.length) {
+    const file = queue.shift();
+    if (seen.has(file)) continue;
+    seen.add(file);
+    let src;
+    try { src = stripComments(read(file)); } catch (_) { continue; }
+
+    for (const { spec, index } of matchAll(src, MODULE_REQUIRE_RE)) {
+      // A guarded require is not a requirement — see insideTry.
+      if (insideTry(src, index)) continue;
+      found.add(withJsExt(resolveRel(file, spec, { root })));
+    }
+    for (const { spec } of matchAll(src, LOCAL_REQUIRE_RE)) {
+      const abs = pathMod.resolve(pathMod.dirname(file), spec);
+      queue.push(/\.[a-z]+$/i.test(abs) ? abs : `${abs}.js`);
+    }
+  }
+  return [...found].sort();
+}
+
+/**
+ * Which of those paths are not on disk. PURE. Returns repo-relative paths.
+ */
+function missingPaths(paths, { exists, root = REPO_ROOT } = {}) {
+  const has = exists || ((rel) => fsMod.existsSync(pathMod.join(root, rel)));
+  return paths.filter((rel) => !has(rel));
+}
+
+// The distinct top-level module directories a set of missing paths falls under —
+// what the builder actually has to get back, and what box-sync speaks in.
+function missingModuleDirs(paths) {
+  const dirs = new Set();
+  for (const p of paths) {
+    const m = String(p).match(/^modules\/([^/]+)\//);
+    if (m) dirs.add(`modules/${m[1]}`);
+  }
+  return [...dirs].sort();
+}
+
+/**
+ * ONE actionable message, or null when the tree is complete. PURE.
+ *
+ * Names the CONDITION (a scoped checkout, not a broken install), EVERY missing
+ * requirement, and BOTH remedies — re-scope, or take the whole tree. Two are given
+ * because they solve different problems: box-sync re-reads the server's path list
+ * and is right when the claim moved, while sparse-checkout disable is the escape
+ * hatch when the scope itself is what is wrong.
+ *
+ * It does not promise which one applies, because that is exactly what this layer
+ * cannot know — it can see that the code is absent, not why.
+ */
+function preflightMessage(missing, { command = 'this command' } = {}) {
+  if (!missing || !missing.length) return null;
+  const dirs = missingModuleDirs(missing);
+  const lines = [
+    `${command} needs code this checkout does not contain.`,
+    '',
+    `Missing (${missing.length}):`,
+    ...missing.map((p) => `  - ${p}`),
+    '',
+    'This is normal on a TASK-SCOPED dev box: the box carries scripts/, src/bongos/,',
+    'tests/ and the module your claimed task is scoped to — not every module. It is',
+    'not a broken install, and re-running will not fix it.',
+    '',
+    'Fix it with ONE of:',
+    '  node scripts/gds/box-sync.js      re-scope this box to what you hold now',
+    '  git sparse-checkout disable       take the whole tree instead',
+  ];
+  if (dirs.length) {
+    lines.splice(lines.indexOf('') + 1, 0, `Whole directories absent: ${dirs.join(', ')}`);
+  }
+  return lines.join('\n');
+}
+
+/**
+ * The one call an entry point makes. Returns null when the tree is complete, or the
+ * message to print before exiting non-zero.
+ *
+ * Every dependency is injectable so the test drives it with a fake file system —
+ * and so a failure inside the preflight can never be the reason a command dies.
+ */
+function checkTree(entryFile, { readFile, exists, root = REPO_ROOT, command } = {}) {
+  try {
+    const required = requiredModulePaths(entryFile, { readFile, root });
+    const missing = missingPaths(required, { exists, root });
+    return preflightMessage(missing, { command: command || pathMod.basename(entryFile) });
+  } catch (_) {
+    // A preflight that throws is a preflight that replaced a clear stack trace with
+    // a worse one. Silence here means the command proceeds and fails the old way,
+    // which is the outcome this file improves on — never the one it causes.
+    return null;
+  }
+}
+
+module.exports = {
+  REPO_ROOT,
+  requiredModulePaths,
+  missingPaths,
+  missingModuleDirs,
+  preflightMessage,
+  checkTree,
+  stripComments,
+  insideTry,
+};

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

@@ -0,0 +1,243 @@
+// tests/tree_preflight.mjs — the partial-checkout preflight (task 1003098).
+//
+// THE BUG. On a task-scoped dev box — a supported, server-driven configuration —
+// `scripts/gds/ship.js` died with a raw stack trace naming ONE missing module. Fix
+// that one, run again, learn the next. The filer lost a session to it, and their
+// workaround (`git sparse-checkout disable` plus disabling the re-scope cron) is
+// not something a builder should have to discover. Node's loader cannot do better:
+// it stops at the first unresolvable specifier and never reaches the second.
+//
+// THE TWO FAILURE DIRECTIONS, and both are tested, because only one is obvious:
+//
+//   under-reporting — the original bug: name one missing thing, hide the other six.
+//   OVER-reporting  — the regression a naive fix causes: several of the CLI's
+//                     module requires are deliberately try-guarded, so those
+//                     commands RUN on a scoped box. Refusing them would tell a
+//                     builder who could have shipped that they cannot, which is
+//                     worse than the trace it replaces.
+//
+// Pure: a fake file system throughout, per the task's own DONE-WHEN. The cases at
+// the end are the empirical anchor — they run the classifier against the REAL
+// scripts/gds files and pin it to behaviour observed on a simulated scoped tree:
+// start.js survives, claim.js dies on one module, ship.js on seven.
+//
+// Run:  node tests/tree_preflight.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const tp = require('../scripts/gds/tree-preflight.js');
+
+const __dirname = dirname(fileURLToPath(import.meta.url));
+const repoRoot = join(__dirname, '..');
+
+let passed = 0;
+let failed = 0;
+const t = (name, fn) => {
+  try { fn(); passed += 1; console.log(`  PASS  ${name}`); }
+  catch (e) { failed += 1; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+};
+
+// A fake scripts/gds tree. Keys are absolute-ish paths as the walker resolves them.
+function fakeFs(files) {
+  return {
+    readFile: (f) => {
+      const key = String(f).replace(/\\/g, '/');
+      const hit = Object.keys(files).find((k) => key.endsWith(k));
+      if (hit === undefined) { const e = new Error('ENOENT'); e.code = 'ENOENT'; throw e; }
+      return files[hit];
+    },
+  };
+}
+
+console.log('\nthe walk — what the command actually needs:');
+
+t('collects a direct module require', () => {
+  const fs = fakeFs({ 'scripts/gds/a.js': "const x = require('../../modules/lifecycle/dead-deps.js');" });
+  assert.deepEqual(
+    tp.requiredModulePaths('/repo/scripts/gds/a.js', { ...fs, root: '/repo' }),
+    ['modules/lifecycle/dead-deps.js'],
+  );
+});
+
+t('FOLLOWS sibling requires — the whole reason a declared list would be wrong', () => {
+  // ship.js reaches its modules through sixteen ship-*.js phase files; a hand-kept
+  // list of "what ship.js needs" is a second copy of the require graph.
+  const fs = fakeFs({
+    'scripts/gds/entry.js': "const p = require('./phase.js');",
+    'scripts/gds/phase.js': "const g = require('../../modules/grading/grader.js');",
+  });
+  assert.deepEqual(
+    tp.requiredModulePaths('/repo/scripts/gds/entry.js', { ...fs, root: '/repo' }),
+    ['modules/grading/grader.js'],
+  );
+});
+
+t('a require cycle terminates', () => {
+  const fs = fakeFs({
+    'scripts/gds/a.js': "require('./b.js'); require('../../modules/lifecycle/one.js');",
+    'scripts/gds/b.js': "require('./a.js'); require('../../modules/lifecycle/two.js');",
+  });
+  assert.deepEqual(
+    tp.requiredModulePaths('/repo/scripts/gds/a.js', { ...fs, root: '/repo' }),
+    ['modules/lifecycle/one.js', 'modules/lifecycle/two.js'],
+  );
+});
+
+t('an unreadable file is skipped, never thrown on', () => {
+  // This runs on a checkout that is BY DEFINITION incomplete. A preflight that
+  // crashes while diagnosing a partial tree is worse than the trace it replaces.
+  const fs = fakeFs({ 'scripts/gds/a.js': "require('./gone.js'); require('../../modules/lifecycle/one.js');" });
+  assert.deepEqual(
+    tp.requiredModulePaths('/repo/scripts/gds/a.js', { ...fs, root: '/repo' }),
+    ['modules/lifecycle/one.js'],
+  );
+});
+
+t('a bare specifier gains .js; one that names an extension is left alone', () => {
+  const fs = fakeFs({
+    'scripts/gds/a.js': "require('../../modules/lifecycle/ship-preflight');require('../../modules/lifecycle/d.json');",
+  });
+  assert.deepEqual(
+    tp.requiredModulePaths('/repo/scripts/gds/a.js', { ...fs, root: '/repo' }),
+    ['modules/lifecycle/d.json', 'modules/lifecycle/ship-preflight.js'],
+  );
+});
+
+console.log('\nOVER-reporting — the regression a naive fix causes:');
+
+t('a try-guarded require is NOT a requirement', () => {
+  // context-pack.js and cli-lib.js both guard theirs and fall back honestly, which
+  // is why /builder-start works on a scoped box today. Reporting them would refuse
+  // a command that runs.
+  const fs = fakeFs({
+    'scripts/gds/a.js': "let c=null; try { c = require('../../modules/lifecycle/task-classifier'); } catch (_) {}",
+  });
+  assert.deepEqual(tp.requiredModulePaths('/repo/scripts/gds/a.js', { ...fs, root: '/repo' }), []);
+});
+
+t('a require AFTER a closed try is still a requirement', () => {
+  // The brace walk must pop. If it did not, one guarded require near the top would
+  // silently excuse every require below it in the file.
+  const fs = fakeFs({
+    'scripts/gds/a.js': "try { require('../../modules/lifecycle/opt.js'); } catch (_) {}\nrequire('../../modules/lifecycle/need.js');",
+  });
+  assert.deepEqual(
+    tp.requiredModulePaths('/repo/scripts/gds/a.js', { ...fs, root: '/repo' }),
+    ['modules/lifecycle/need.js'],
+  );
+});
+
+t('a require quoted inside a COMMENT is not walked', () => {
+  // tree-preflight.js's own header quotes the failing require verbatim to explain
+  // the bug. A raw-text scan would read that prose as a live edge — the defect
+  // filed as task 1003832 against a test that scanned raw source.
+  const fs = fakeFs({
+    'scripts/gds/a.js': "// require('../../modules/grading/nope.js')\n/* require('../../modules/grading/also.js') */\nrequire('../../modules/lifecycle/real.js');",
+  });
+  assert.deepEqual(
+    tp.requiredModulePaths('/repo/scripts/gds/a.js', { ...fs, root: '/repo' }),
+    ['modules/lifecycle/real.js'],
+  );
+});
+
+console.log('\nthe message — one run, every missing thing:');
+
+t('nothing missing → null, so a complete checkout is a silent no-op', () => {
+  assert.equal(tp.preflightMessage([], { command: '/builder-ship' }), null);
+  assert.equal(tp.preflightMessage(null, { command: '/builder-ship' }), null);
+});
+
+t('EVERY missing requirement is listed, not the first', () => {
+  // The whole ask. Seven for ship.js is seven guess-read-fix cycles avoided.
+  const missing = ['modules/a/one.js', 'modules/b/two.js', 'modules/b/three.js'];
+  const msg = tp.preflightMessage(missing, { command: '/builder-ship' });
+  for (const m of missing) assert.ok(msg.includes(m), `names ${m}`);
+  assert.match(msg, /Missing \(3\)/, 'and says how many');
+});
+
+t('it names the CONDITION and BOTH remedies', () => {
+  const msg = tp.preflightMessage(['modules/a/one.js'], { command: '/builder-ship' });
+  assert.match(msg, /task-scoped/i, 'names why the code is absent');
+  assert.match(msg, /not a broken install/i, 'and rules out the wrong diagnosis');
+  assert.match(msg, /box-sync\.js/, 're-scope');
+  assert.match(msg, /sparse-checkout disable/, 'or take the whole tree');
+  assert.match(msg, /\/builder-ship/, 'and says which command was refused');
+});
+
+t('it rolls the missing files up to whole directories', () => {
+  const msg = tp.preflightMessage(['modules/lifecycle/a.js', 'modules/lifecycle/b.js', 'modules/grading/c.js']);
+  assert.match(msg, /modules\/grading, modules\/lifecycle/, 'deduped and sorted');
+});
+
+console.log('\ncheckTree — what the entry points call:');
+
+t('a complete tree returns null', () => {
+  const fs = fakeFs({ 'scripts/gds/a.js': "require('../../modules/lifecycle/one.js');" });
+  assert.equal(tp.checkTree('/repo/scripts/gds/a.js', { ...fs, root: '/repo', exists: () => true }), null);
+});
+
+t('a partial tree returns the message', () => {
+  const fs = fakeFs({ 'scripts/gds/a.js': "require('../../modules/lifecycle/one.js');" });
+  const msg = tp.checkTree('/repo/scripts/gds/a.js', { ...fs, root: '/repo', exists: () => false, command: '/builder-x' });
+  assert.match(msg, /modules\/lifecycle\/one\.js/);
+});
+
+t('a preflight that THROWS returns null rather than replacing one bad trace with another', () => {
+  const boom = { readFile: () => { throw new Error('boom'); }, exists: () => { throw new Error('boom'); } };
+  assert.equal(tp.checkTree('/repo/scripts/gds/a.js', { ...boom, root: '/repo' }), null);
+});
+
+console.log('\nthe empirical anchor — the REAL CLI files:');
+
+t('start.js needs NO unguarded module code, matching that it runs on a scoped box', () => {
+  // Observed: with modules/ hidden, start.js prints its card normally. If this
+  // list is ever non-empty, /builder-start starts refusing on a box where it works.
+  const req = tp.requiredModulePaths(join(repoRoot, 'scripts/gds/start.js'), { root: repoRoot });
+  assert.deepEqual(req, [], `start.js must survive a scoped box; got ${req.join(', ')}`);
+});
+
+t('claim.js and ship.js DO need module code, matching the traces they died with', () => {
+  const claim = tp.requiredModulePaths(join(repoRoot, 'scripts/gds/claim.js'), { root: repoRoot });
+  assert.ok(claim.includes('modules/lifecycle/dead-deps.js'),
+    'the exact module claim.js died on');
+  const ship = tp.requiredModulePaths(join(repoRoot, 'scripts/gds/ship.js'), { root: repoRoot });
+  assert.ok(ship.includes('modules/lifecycle/ship-preflight.js'),
+    'the exact module ship.js died on');
+  assert.ok(ship.length >= 5,
+    `ship.js fans out across phase files; the walk found ${ship.length}, so the one-per-run cost was real`);
+});
+
+t('the three entry points actually CALL the preflight, above their first require', () => {
+  // The check is worthless if it runs after the require that dies. Asserted by
+  // position, because that is the property — not merely that the call exists.
+  for (const f of ['start.js', 'claim.js', 'ship.js']) {
+    const src = require('node:fs').readFileSync(join(repoRoot, 'scripts/gds', f), 'utf8');
+    const call = src.indexOf('_checkTree(__filename');
+    assert.ok(call > 0, `${f} calls the preflight`);
+    const firstModuleRequire = src.search(/require\(\s*['"]\.\.\/\.\.\/modules\//);
+    if (firstModuleRequire > 0) {
+      assert.ok(call < firstModuleRequire, `${f}: the preflight must run BEFORE the first modules/ require`);
+    }
+  }
+});
+
+t('the preflight names the command for the READER, never a hard-coded slash command', () => {
+  // The message this preflight prints is reader-facing, and `/builder-ship` does not exist
+  // outside Claude Code — a person running the public `bongos` CLI would be handed a command
+  // they cannot type. tests/cli_surface.mjs scans start.js for exactly this, but nothing
+  // scanned claim.js or ship.js, and the first draft of this task hard-coded all three.
+  for (const f of ['start.js', 'claim.js', 'ship.js']) {
+    const src = require('node:fs').readFileSync(join(repoRoot, 'scripts/gds', f), 'utf8');
+    const line = src.split('\n').find((l) => l.includes('_checkTree(__filename'));
+    assert.ok(line, `${f} calls the preflight`);
+    assert.ok(!/\/builder-/.test(line), `${f}: hard-coded slash command in the preflight message`);
+    assert.match(line, /_surfaceAction\(/, `${f}: the command name must come from the surface switch`);
+  }
+});
+
+console.log(`\ntree_preflight: ${passed} passed, ${failed} failed`);
+if (failed) process.exit(1);