@bongos/core 1.19.80 → 1.19.81

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.80",
-  "core_contract": "1.19.80",
-  "source_commit": "e9830526a46cd238c6ea856406a1bcde6fcb6e4f",
+  "core_version": "1.19.81",
+  "core_contract": "1.19.81",
+  "source_commit": "c19697303b3961520ebb175928cde6beddf00896",
   "source_ref": "HEAD",
-  "built_at": "2026-08-12T23:02:51.567Z",
+  "built_at": "2026-08-12T23:08:05.391Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 295,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1226,
+    "functional_verbatim": 1227,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1542,
-  "tree_sha256": "8efe860e490a9f9bca1f3739c652e205e29d50643e86361a1eb631f7474a1ba9",
+  "file_count": 1543,
+  "tree_sha256": "799b7337a46edabc3eb3adca6a29fb43c274e1ab27a9b130d09a986d4177cd9b",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -37,7 +37,7 @@
     {
       "path": ".claude/skills/builder-box/SKILL.md",
       "mode": "0000644",
-      "sha256": "d8bfc9298bbb136742147e83d2500b9cb0961fec35ca15dc3cb773c9ecdf8b4b"
+      "sha256": "e131788fccfd87e882ef4e03798513cf7ff41047a2908fca8cf6314ff12e0524"
     },
     {
       "path": ".claude/skills/builder-claim/SKILL.md",
@@ -4057,12 +4057,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "b7e3e581321a968a2978affc8766e5bc9ec8f412f0c3e7a94c47916138724de9"
+      "sha256": "845771b9d06a05dcb4eb8b90a0002b26d1fc105c2d27d24f870f89640fb09769"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "283e5a12a702be6937db0eb28a69775e3cb6b760ae217b3824d65ba7feb6743b"
+      "sha256": "04febc37475484098b13f52462cda84d2a120c5ef64b7c2edf733e14ac6b3e1f"
     },
     {
       "path": "public-docs/index.html",
@@ -4552,7 +4552,7 @@
     {
       "path": "scripts/gds/box-sync.js",
       "mode": "0000644",
-      "sha256": "8169a34dcef766360d10c7d27c7404a776aeb0b8a43f8b91fc9bc12af35a8b1b"
+      "sha256": "981544bfd56d486c2017edd744c86089659771a74399b4780455821c45e3b3a9"
     },
     {
       "path": "scripts/gds/box.js",
@@ -5687,7 +5687,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "e85465ed2f13494396cf2d74bad0c8a2b6e52d42d48c493a3d0dcf4694f6072e"
+      "sha256": "3e4f5f5d1cb49b46416308dc7a4fa145b8260ca8dd0c63ed1a16ba499b622bc2"
     },
     {
       "path": "src/module-loader/loader.js",
@@ -6029,6 +6029,11 @@
       "mode": "0000644",
       "sha256": "93bc891850e77350161214749954ddb257169ae323b7242f35becc4e6a9cabcf"
     },
+    {
+      "path": "tests/box_sync_scope_report.mjs",
+      "mode": "0000644",
+      "sha256": "010525c500aa1d5133f85a1a2ea7c23e9a680b08493a6f3b78c69a5108501468"
+    },
     {
       "path": "tests/box_task_scope.mjs",
       "mode": "0000644",

package/.claude/skills/builder-box/SKILL.md

@@ -16,12 +16,18 @@ The per-builder box lifecycle (ADR 0031 §2) auto-suspends when idle (snapshot-a
 
 ## How to use
 
-1. **Fetch the box + keys** (own-scoped; uses the builder's session token):
+1. **Fetch the box + keys + the resolved scope** (own-scoped; uses the builder's session token):
    ```bash
-   node -e 'const{apiCall}=require("./scripts/gds/cli-lib");(async()=>{for(const p of ["/api/gds/box/me","/api/gds/box/ssh-key"]){const r=await apiCall("GET",p);console.log(p,r.status,JSON.stringify(r.data));}})()'
+   node -e 'const{apiCall}=require("./scripts/gds/cli-lib");(async()=>{for(const p of ["/api/gds/box/me","/api/gds/box/ssh-key","/api/gds/box/scope"]){const r=await apiCall("GET",p);console.log(p,r.status,JSON.stringify(r.data));}})()'
    ```
    (If the script returns "no GDS session", run `/builder-setup` first.)
 
+   **Always report the scope, not just the state** (task 1002731). `/box/scope` returns `{scope, modules, sparse_paths, task_scope}`, and a too-narrow box is otherwise a *silent* failure — the builder sees a working box that is quietly missing the code they need. Read it out:
+   - `scope: 'task'` → name the modules: *"your box holds dev-box, hall-ui — and nothing else."*
+   - `scope: 'base'` → **say plainly that the box has no `modules/` code at all.** With no active claim that is expected; claiming a task and running `/builder-sync` fixes it.
+   - `scope: 'full'` with `modules: []` → the task-1002729 fallback fired: they hold claims, but those claims' goals declare no `scope_modules`, so the box fell back to their rank. Usable, but task-scoping is not actually doing anything — setting the goal's wall would give a tighter box.
+   - `scope: 'starter'` → the fixed newcomer slice, not scoped to their claim.
+
 2. **Relay it in plain language:**
    - **state = `none`** → they have no box yet. On a Mac/Windows: run `/builder-connect` (registers their SSH key + installs the Desktop file). To actually create the box hands-off, `POST /api/gds/box/ensure` queues the auto-provision (no operator CLI needed). *(The old path — ask an operator to `box.js onboard <login>` — still works but is no longer required.)*
    - **state = `active`** → box is up at `hostname` (`ip`). They can connect from Claude Desktop → Code → Environment → "Example Dev Box". For a browser/Chromebook (ADR 0038), the terminal comes from the web: `GET /api/gds/box/terminal` returns a `url` + a basic-auth `credential` (username `otb`, password = <redacted>; open the url, enter them, then type `claude` in the terminal. No SSH needed.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.80",
+  "version": "1.19.81",
   "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/box-sync.js

@@ -57,10 +57,77 @@ function main(argv = process.argv.slice(2)) {
     console.error(`sync: could not run the fetch (${r.error.message})`);
     process.exit(1);
   }
-  if (r.status === 0) console.log('sync: done — your box now holds the code for your active claim.');
-  process.exit(r.status == null ? 1 : r.status);
+  if (r.status !== 0) process.exit(r.status == null ? 1 : r.status);
+  console.log('sync: done — your box now holds the code for your active claim.');
+  // Then say WHAT it holds, so a base-only box is visible instead of silent.
+  reportScope().then(() => process.exit(0), () => process.exit(0));
+}
+
+// ---------------------------------------------------------------------------
+// task 1002731 — say what scope the box ACTUALLY got
+// ---------------------------------------------------------------------------
+
+// The failure this exists for is a SILENT one: a box comes up holding only the
+// base slice (no modules/ at all) and nothing anywhere says so. Live, that was
+// 247 of 248 source grants — including an Archon with 7 active claims — and the
+// only way to see it was reading box_events on the control plane. GET /box/scope
+// already returns the resolved decision; nothing ever showed it to a human.
+//
+// PURE so it is unit-testable without a box or a network: takes the /box/scope
+// body, returns the lines to print. null/garbage in → one honest line rather
+// than a crash, because this is diagnostic output on an already-degraded path
+// and must never be the thing that fails.
+function formatScopeReport(scope) {
+  if (!scope || typeof scope !== 'object' || Array.isArray(scope)) {
+    return ['scope: could not read your box scope (GET /box/scope did not answer).'];
+  }
+  const modules = Array.isArray(scope.modules) ? scope.modules : null;
+  const paths = Array.isArray(scope.sparse_paths) ? scope.sparse_paths : [];
+  const out = [];
+
+  if (scope.scope === 'task' && modules && modules.length) {
+    out.push(`scope: task — your box holds ${modules.length} module(s): ${modules.join(', ')}`);
+  } else if (scope.scope === 'base') {
+    out.push('scope: BASE ONLY — your box holds no modules/ code at all.');
+    out.push(scope.task_scope
+      ? '  Why: you hold no active claim, so there is no work to scope the box to.'
+      : '  Why: this instance resolved no claim scope.');
+    out.push('  Fix: claim a task (/builder-claim N), then re-run this sync.');
+  } else if (scope.scope === 'full') {
+    out.push('scope: full — your box holds the whole repo (your rank allows it).');
+    if (modules && modules.length === 0) {
+      // The task-1002729 fallback fired: claims held, but their goals declare no
+      // wall. Worth naming — the box is usable, but task-scoping is doing nothing.
+      out.push('  Note: your claimed work declares no module scope, so this fell back to');
+      out.push("  your rank rather than scoping to the task. Setting the goal's");
+      out.push('  scope_modules would give you a tighter box.');
+    }
+  } else if (scope.scope === 'starter') {
+    out.push('scope: starter — a fixed slice for newcomers, not scoped to your claim.');
+  } else {
+    out.push(`scope: ${String(scope.scope || 'unknown')}`);
+  }
+  if (paths.length) out.push(`  paths: ${paths.length} sparse entr${paths.length === 1 ? 'y' : 'ies'}`);
+  return out;
+}
+
+// Read the resolved scope and print it. Never throws and never changes the exit
+// status — a diagnostic that could fail the sync it reports on would be worse
+// than no diagnostic.
+async function reportScope() {
+  try {
+    const { apiCall } = require('./cli-lib');
+    const r = await apiCall('GET', '/api/gds/box/scope');
+    if (!r || r.status !== 200) {
+      console.log('scope: could not read your box scope right now (that does not affect the sync above).');
+      return;
+    }
+    for (const line of formatScopeReport(r.data)) console.log(line);
+  } catch (_) {
+    console.log('scope: could not read your box scope right now (that does not affect the sync above).');
+  }
 }
 
 if (require.main === module) main();
 
-module.exports = { resolveFetchScript, FETCH_SCRIPT };
+module.exports = { resolveFetchScript, FETCH_SCRIPT, formatScopeReport };

package/src/module-api.js

@@ -587,8 +587,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.78 with no explicit bump. run 31648954641. (task 1002620)
 //   1.19.80 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.79 with no explicit bump. run 31649366675. (task 1002620)
+//   1.19.81 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.80 with no explicit bump. run 31649705242. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.80'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.81'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/box_sync_scope_report.mjs

@@ -0,0 +1,81 @@
+// tests/box_sync_scope_report.mjs
+//
+// Task 1002731 — the scope read-out that makes a too-narrow box VISIBLE.
+//
+// The failure being guarded is a silent one: a box comes up holding only the
+// base slice (no modules/ at all) and nothing tells the builder. Live, that was
+// 247 of 248 source grants on the cloudbongos fleet — including an Archon
+// holding 7 active claims — and the only way to see it was reading box_events
+// on the control plane.
+//
+// formatScopeReport is PURE (takes the GET /box/scope body, returns lines), so
+// this needs no box, no network and no DB.
+//
+// Run:  node tests/box_sync_scope_report.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { formatScopeReport } = require('../scripts/gds/box-sync.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+const joined = (scope) => formatScopeReport(scope).join('\n');
+
+t('base-only is stated in plain words, with a why and a fix', () => {
+  const out = joined({ scope: 'base', mode: 'sparse', modules: [], sparse_paths: ['docs', 'scripts'], task_scope: true });
+  assert.match(out, /BASE ONLY/, 'the degraded state is named, not buried');
+  assert.match(out, /no modules\/ code at all/, 'says what is actually missing');
+  assert.match(out, /Why:/, 'explains the cause');
+  assert.match(out, /builder-claim/, 'gives the builder the actual next step');
+});
+
+t('task scope names the modules the box holds', () => {
+  const out = joined({ scope: 'task', mode: 'sparse', modules: ['dev-box', 'hall-ui'], sparse_paths: ['a', 'b', 'c'], task_scope: true });
+  assert.match(out, /scope: task/);
+  assert.match(out, /dev-box, hall-ui/, 'names them rather than just counting');
+  assert.match(out, /3 sparse entries/);
+});
+
+t('full + EMPTY modules surfaces the 1002729 fallback rather than looking healthy', () => {
+  // The exact live shape: claims held, but their goals declare no scope_modules.
+  // The box works, so nothing complains — but task-scoping is not doing anything,
+  // and that is worth telling someone.
+  const out = joined({ scope: 'full', mode: 'full', modules: [], sparse_paths: null, task_scope: true });
+  assert.match(out, /scope: full/);
+  assert.match(out, /declares no module scope/, 'names why it fell back');
+  assert.match(out, /scope_modules/, 'points at the thing to fix');
+});
+
+t('full with real modules does NOT nag about the fallback', () => {
+  const out = joined({ scope: 'full', mode: 'full', modules: ['kernel'], sparse_paths: null, task_scope: false });
+  assert.match(out, /scope: full/);
+  assert.ok(!/declares no module scope/.test(out), 'no false alarm when nothing is wrong');
+});
+
+t('starter is distinguished from a claim-scoped box', () => {
+  const out = joined({ scope: 'starter', mode: 'sparse', modules: null, sparse_paths: ['x'], task_scope: false });
+  assert.match(out, /starter/);
+  assert.match(out, /not scoped to your claim/);
+});
+
+t('a missing or malformed body degrades to one honest line, never a throw', () => {
+  // This runs on an already-degraded path; it must not be the thing that fails.
+  for (const bad of [null, undefined, 'nope', 42, []]) {
+    const lines = formatScopeReport(bad);
+    assert.ok(Array.isArray(lines) && lines.length >= 1, `handled ${JSON.stringify(bad)}`);
+  }
+  assert.match(joined(null), /could not read/);
+});
+
+t('an unknown scope value is reported verbatim rather than swallowed', () => {
+  assert.match(joined({ scope: 'something-new', sparse_paths: [] }), /something-new/);
+});
+
+console.log(`\nbox_sync_scope_report.mjs: ${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);