@bongos/core 1.18.19 → 1.19.3

package/modules/security/tests/scan_store.mjs

@@ -0,0 +1,250 @@
+// modules/security/tests/scan_store.mjs
+//
+// Task 1002547 (goal 1000055) — the scan-record store's PURE validation seam.
+// The security contract under test:
+//
+//   * STRUCTURE ONLY, NEVER CONTENT — a findings_summary is a list of one-line,
+//     length-capped, known-keys-only claims; anything shaped like quoted target
+//     content (multi-line, fence-marked, unknown keys, oversized) is rejected,
+//     and every string is scrubbed of dangerous codepoints before it can land;
+//   * an ABORTED scan is recordable, and the verdict/completion coupling is
+//     enforced before the DB ever sees the row (a dead scan must never read as
+//     a passing one);
+//   * target_host is DERIVED from the validated URL, never trusted from the
+//     caller.
+//
+// DB-free — only the pure normalize/validate seam is exercised, so this runs
+// in `node scripts/gds/run-unit-tests.js`.
+// Run directly:  node modules/security/tests/scan_store.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const store = require('../scan-store.js');
+const { normalizeScanPayload, SUMMARY_LIMITS } = store;
+const { FENCE_MARKER } = require('../artifact-scan/fence-local.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+function goodPayload(over = {}) {
+  return {
+    target_url: 'https://github.com/example/repo',
+    artifact_kind: 'repo',
+    resolved_sha: 'a'.repeat(40),
+    content_hash: 'b'.repeat(64),
+    file_count: 12,
+    total_bytes: 34567,
+    tier: 'default',
+    verdict: 'caution',
+    completion: 'complete',
+    findings_critical: 0,
+    findings_high: 1,
+    findings_medium: 2,
+    findings_low: 0,
+    findings_summary: [
+      { code: 'net_sink', severity: 'high', file: 'src/post.js', message: 'same-file read-then-send co-occurrence' },
+    ],
+    engine_version: 'scan-engine/0.1.0',
+    action_taken: 'none',
+  };
+}
+
+// ---------- the happy path ----------
+
+test('a complete scan payload normalizes, with target_host derived from the URL', () => {
+  const r = normalizeScanPayload(goodPayload());
+  assert.equal(r.ok, true, JSON.stringify(r));
+  assert.equal(r.value.target_host, 'github.com');
+  assert.equal(r.value.verdict, 'caution');
+});
+
+test('a caller-supplied target_host is ignored — the host comes from the validated URL only', () => {
+  const r = normalizeScanPayload({ ...goodPayload(), target_host: 'trusted-looking.example' });
+  assert.equal(r.ok, true, JSON.stringify(r));
+  assert.equal(r.value.target_host, 'github.com');
+});
+
+// ---------- an aborted scan is recordable; the coupling is enforced ----------
+
+test('an aborted scan with no verdict is recordable', () => {
+  const p = goodPayload();
+  delete p.verdict;
+  p.completion = 'aborted';
+  p.abort_code = 'clone_timeout';
+  const r = normalizeScanPayload(p);
+  assert.equal(r.ok, true, JSON.stringify(r));
+  assert.equal(r.value.verdict, null);
+  assert.equal(r.value.abort_code, 'clone_timeout');
+});
+
+test('a complete scan WITHOUT a verdict is rejected — silence must never read as passing', () => {
+  const p = goodPayload();
+  delete p.verdict;
+  const r = normalizeScanPayload(p);
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'verdict_completion_mismatch');
+});
+
+test('an aborted scan WITH a verdict is rejected — a dead scan cannot carry a conclusion', () => {
+  const p = goodPayload();
+  p.completion = 'aborted';
+  const r = normalizeScanPayload(p);
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'verdict_completion_mismatch');
+});
+
+test('an incomplete scan follows the same coupling: no verdict OK, with verdict rejected', () => {
+  const base = goodPayload();
+  delete base.verdict;
+  const ok = normalizeScanPayload({ ...base, completion: 'incomplete' });
+  assert.equal(ok.ok, true, JSON.stringify(ok));
+  assert.equal(ok.value.verdict, null);
+  const bad = normalizeScanPayload({ ...goodPayload(), completion: 'incomplete' });
+  assert.equal(bad.ok, false);
+  assert.equal(bad.code, 'verdict_completion_mismatch');
+});
+
+// ---------- identity fields ----------
+
+test('a URL carrying embedded credentials is REJECTED — a token must never land in an all-ranks row', () => {
+  const r = normalizeScanPayload({ ...goodPayload(), target_url: 'https://ghp_secret123@github.com/org/private' });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'bad_target_url');
+});
+
+test('the stored target_url is the PARSED serialization, never the raw caller string', () => {
+  const r = normalizeScanPayload({ ...goodPayload(), target_url: 'https://github.com/Example/Repo' });
+  assert.equal(r.ok, true, JSON.stringify(r));
+  assert.equal(r.value.target_url, new URL('https://github.com/Example/Repo').href);
+});
+
+test('a non-https target URL is rejected', () => {
+  const r = normalizeScanPayload({ ...goodPayload(), target_url: 'http://github.com/x/y' });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'bad_target_url');
+});
+
+test('a malformed content_hash is rejected', () => {
+  const r = normalizeScanPayload({ ...goodPayload(), content_hash: 'not-hex' });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'bad_content_hash');
+});
+
+test('a malformed resolved_sha is rejected', () => {
+  const r = normalizeScanPayload({ ...goodPayload(), resolved_sha: 'main' });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'bad_resolved_sha');
+});
+
+test('bad enum values are rejected: tier, verdict, kind, action', () => {
+  for (const [field, value] of [
+    ['tier', 'ultra'], ['verdict', 'fine'], ['artifact_kind', 'zip'], ['action_taken', 'installed'],
+  ]) {
+    const r = normalizeScanPayload({ ...goodPayload(), [field]: value });
+    assert.equal(r.ok, false, `${field}=${value} must be rejected`);
+  }
+});
+
+// ---------- findings_summary: structure only, never content ----------
+
+test('a multi-line summary message is rejected — one-LINE claims only', () => {
+  const p = goodPayload();
+  p.findings_summary = [{ code: 'x', severity: 'low', file: 'a.js', message: 'line one\nline two of quoted payload' }];
+  const r = normalizeScanPayload(p);
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'summary_not_one_line');
+});
+
+test('an unknown summary item key is rejected — no side channel for quoted content', () => {
+  const p = goodPayload();
+  p.findings_summary = [{ code: 'x', severity: 'low', file: 'a.js', message: 'ok', excerpt: 'quoted target bytes' }];
+  const r = normalizeScanPayload(p);
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'summary_unknown_key');
+});
+
+test('a summary string carrying the mirror fence marker is rejected as quoted content', () => {
+  const p = goodPayload();
+  p.findings_summary = [{ code: 'x', severity: 'low', file: 'a.js', message: `saw ${FENCE_MARKER} here` }];
+  const r = normalizeScanPayload(p);
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'summary_quoted_content');
+});
+
+test('dangerous codepoints are scrubbed out of summary strings before they can land', () => {
+  const p = goodPayload();
+  p.findings_summary = [{ code: 'x', severity: 'low', file: 'a.js', message: `igno${String.fromCodePoint(0xfeff)}re this` }];
+  const r = normalizeScanPayload(p);
+  assert.equal(r.ok, true, JSON.stringify(r));
+  assert.equal(r.value.findings_summary[0].message, 'ignore this');
+});
+
+test('too many summary items are rejected', () => {
+  const p = goodPayload();
+  p.findings_summary = Array.from({ length: SUMMARY_LIMITS.maxItems + 1 }, (_, i) => ({
+    code: 'x', severity: 'low', file: `f${i}.js`, message: 'm',
+  }));
+  const r = normalizeScanPayload(p);
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'summary_too_many_items');
+});
+
+test('an over-long summary message is rejected', () => {
+  const p = goodPayload();
+  p.findings_summary = [{ code: 'x', severity: 'low', file: 'a.js', message: 'm'.repeat(SUMMARY_LIMITS.maxMessageChars + 1) }];
+  const r = normalizeScanPayload(p);
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'summary_string_too_long');
+});
+
+test('a summary item severity outside the four levels is rejected', () => {
+  const p = goodPayload();
+  p.findings_summary = [{ code: 'x', severity: 'catastrophic', file: 'a.js', message: 'm' }];
+  const r = normalizeScanPayload(p);
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'summary_bad_severity');
+});
+
+test('negative findings counts are rejected', () => {
+  const r = normalizeScanPayload({ ...goodPayload(), findings_high: -1 });
+  assert.equal(r.ok, false);
+  assert.equal(r.code, 'bad_counts');
+});
+
+// ---------- the route file: rank gates stated where fitness can see them ----------
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const routeSrc = fs.readFileSync(path.join(here, '..', 'routes', 'scans.js'), 'utf8');
+
+test("the POST is gated api.requireRank('metic', 'archon') — a verdict-shaped write is a trust-shaped write", () => {
+  assert.match(routeSrc, /router\.post\(\s*'\/security\/scans'[\s\S]{0,400}?api\.requireRank\('metic',\s*'archon'\)/);
+});
+
+test('the GET is requireBuilder at every rank — the newest builder needs the warning most', () => {
+  assert.match(routeSrc, /router\.get\(\s*'\/security\/scans'[\s\S]{0,200}?api\.requireBuilder/);
+  const getBlock = routeSrc.slice(routeSrc.indexOf("router.get("));
+  assert.ok(!/requireRank/.test(getBlock.slice(0, 300)), 'the read side must not be rank-gated');
+});
+
+test('a Xenos POST gets a DEFINED degraded path, not a bare 403', () => {
+  assert.match(routeSrc, /degraded/i);
+  assert.match(routeSrc, /report file/i);
+});
+
+test('module.json mounts the scans route', () => {
+  const manifest = JSON.parse(fs.readFileSync(path.join(here, '..', 'module.json'), 'utf8'));
+  assert.ok(manifest.contributes.routes.includes('scans'));
+  assert.ok(manifest.contributes.routes.includes('reports'), 'reports must stay mounted');
+});
+
+console.log(`\nscan_store: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/modules/security/tests/tool_scans_migration.mjs

@@ -0,0 +1,116 @@
+// modules/security/tests/tool_scans_migration.mjs
+//
+// Structural guards on security_001_tool_scans.sql. These are not a substitute
+// for applying it — they are the invariants that must survive any later edit,
+// checked in the DB-free gate where a live Postgres is not available.
+//
+// The load-bearing one is the verdict/completion coupling: an aborted scan must
+// be unable to carry a verdict, and a complete one must be unable to omit it.
+// Without that constraint a scan that died could be read as one that passed,
+// which is the single most dangerous confusion this whole feature can produce.
+//
+// Run directly:  node modules/security/tests/tool_scans_migration.mjs
+
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const here = path.dirname(fileURLToPath(import.meta.url));
+const SQL_PATH = path.join(here, '..', 'migrations', 'security_001_tool_scans.sql');
+const sql = fs.readFileSync(SQL_PATH, 'utf8');
+// Comments carry prose that would otherwise trip the keyword scans below.
+const code = sql.replace(/--[^\n]*/g, '');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try { fn(); passed++; console.log(`  ok  ${name}`); }
+  catch (err) { failed++; console.log(`  FAIL ${name}`); console.log(`     ${err.message}`); }
+}
+
+test('every created object is security_-namespaced (ADR 0083 §Decision #5)', () => {
+  const created = [...code.matchAll(/CREATE\s+(?:TABLE|INDEX|VIEW|TYPE|SEQUENCE)\s+(?:IF\s+NOT\s+EXISTS\s+)?([a-z_][a-z0-9_]*)/gi)]
+    .map((m) => m[1]);
+  assert.ok(created.length >= 4, `expected the table + its indexes, saw ${created.length}`);
+  for (const name of created) {
+    assert.ok(name.startsWith('security_'), `${name} is outside the security_ namespace`);
+  }
+});
+
+test('additive only — no destructive DDL', () => {
+  for (const re of [/\bDROP\s+(TABLE|COLUMN|INDEX|CONSTRAINT|TYPE)\b/i, /\bTRUNCATE\b/i, /\bALTER\s+TABLE\s+\w+\s+DROP\b/i]) {
+    assert.ok(!re.test(code), `destructive DDL found: ${re}`);
+  }
+});
+
+test('idempotent — table and every index use IF NOT EXISTS', () => {
+  assert.match(code, /CREATE\s+TABLE\s+IF\s+NOT\s+EXISTS\s+security_tool_scans/i);
+  const indexes = [...code.matchAll(/CREATE\s+INDEX(\s+IF\s+NOT\s+EXISTS)?/gi)];
+  assert.ok(indexes.length >= 3, `expected at least 3 indexes, saw ${indexes.length}`);
+  for (const m of indexes) {
+    assert.ok(m[1], 'an index is missing IF NOT EXISTS — the migration would fail on re-run');
+  }
+});
+
+test('runs in a single transaction', () => {
+  assert.match(code, /^\s*BEGIN;/m);
+  assert.match(code, /^\s*COMMIT;/m);
+});
+
+test('carries every column the scan record needs', () => {
+  for (const col of [
+    'target_url', 'target_host', 'artifact_kind', 'resolved_sha', 'content_hash',
+    'file_count', 'total_bytes', 'tier', 'verdict', 'completion', 'abort_code',
+    'findings_critical', 'findings_high', 'findings_medium', 'findings_low',
+    'findings_summary', 'action_taken', 'engine_version', 'scanned_by_builder_id',
+    'created_at', 'updated_at',
+  ]) {
+    assert.ok(new RegExp(`\\b${col}\\b`).test(code), `missing column: ${col}`);
+  }
+});
+
+test('an aborted scan can never carry a verdict, and a complete one can never omit it', () => {
+  // The invariant that stops "the scan died" from ever reading as "it passed".
+  assert.match(code, /CHECK\s*\(\s*\(completion\s*=\s*'complete'\)\s*=\s*\(verdict\s+IS\s+NOT\s+NULL\)\s*\)/i);
+});
+
+test('completion records an aborted scan rather than losing it', () => {
+  assert.match(code, /completion\s+IN\s*\('complete',\s*'aborted',\s*'incomplete'\)/i);
+});
+
+test('verdict is constrained to the three honest values', () => {
+  assert.match(code, /verdict\s+IN\s*\('clean',\s*'caution',\s*'dangerous'\)/i);
+});
+
+test('the low tier is a recorded value, so a verdict is always read in tier context', () => {
+  assert.match(code, /tier\s+IN\s*\('low',\s*'default',\s*'high',\s*'xhigh',\s*'max'\)/i);
+});
+
+test('findings_summary is size-capped at the DB layer', () => {
+  // Defense in depth with the route: a hostile artifact must not push unbounded
+  // text into a field every future reader of this table renders.
+  assert.match(code, /length\(findings_summary::text\)\s*<=\s*\d+/i);
+});
+
+test('content_hash and scanner are indexed — the two lookups the table exists for', () => {
+  assert.match(code, /CREATE\s+INDEX\s+IF\s+NOT\s+EXISTS\s+security_tool_scans_content_hash_idx[\s\S]*?\(content_hash\)/i);
+  assert.match(code, /CREATE\s+INDEX\s+IF\s+NOT\s+EXISTS\s+security_tool_scans_scanner_idx[\s\S]*?\(scanned_by_builder_id/i);
+});
+
+test('a deleted builder does not delete the scan record', () => {
+  // Attribution is nullable; the security finding outlives the account.
+  assert.match(code, /scanned_by_builder_id\s+bigint\s+REFERENCES\s+builders\(id\)\s+ON\s+DELETE\s+SET\s+NULL/i);
+});
+
+test('findings_summary must be a JSON array, not a smuggled scalar or object', () => {
+  assert.match(code, /jsonb_typeof\(findings_summary\)\s*=\s*'array'/i);
+});
+
+test('updated_at is live — rows mutate post-insert (action_taken), so a touch trigger exists', () => {
+  assert.match(code, /CREATE\s+OR\s+REPLACE\s+FUNCTION\s+security_tool_scans_touch_updated_at\(\)/i);
+  assert.match(code, /CREATE\s+TRIGGER\s+security_tool_scans_updated_at\s+BEFORE\s+UPDATE\s+ON\s+security_tool_scans/i);
+});
+
+console.log(`\ntool_scans_migration: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/modules/sessions/routes/sessions.js

@@ -65,10 +65,11 @@ const MAX_DETAIL_TURNS = 5000; // a hard ceiling; ship.js bounds well under this
 // also a follow-up — see SR-17 notes.
 const MAX_DETAIL_ELEMENT_BYTES = 4 * 1024;        // 4 KB per detail[] element
 const MAX_DETAIL_TOTAL_BYTES = 2 * 1024 * 1024;   // 2 MB total detail[] payload
-// The three LIVE ranks (ADR 0018) — deliberately NOT db.RANKS, which is the full
-// 16-entry historical enum. Only these three are ever assigned to a builder, so
-// the search filter validates against them (a query for any other rank is a 400).
-const VALID_RANKS = new Set(['xenos', 'thetes', 'metic', 'archon']);
+// The LIVE ranks — deliberately NOT db.RANKS, which is the full 16-entry
+// historical enum. Only the live ladder is ever assigned to a builder, so the
+// search filter validates against it (a query for any other rank is a 400).
+// Derived from the doorway ladder (BV1.R108) rather than hand-copied.
+const VALID_RANKS = new Set(api.LIVE_RANK_LADDER);
 
 // Per-builder read limiter for the session corpus (mirrors the memory router's
 // forensic-read limiter). Reads aren't covered by the global write limiter.
@@ -270,7 +271,7 @@ module.exports = function buildSessionsRouter() {
   // Express matches the literal paths first (the numeric :id never swallows them).
 
   // rank: archon — cross-builder corpus search (BFG-principal posture until 6C.1).
-  router.get('/sessions/search', auth.requireBuilder, auth.requireRank('archon'), readRateLimit, async (req, res) => {
+  router.get('/sessions/search', auth.requireBuilder, auth.requirePermission('session.search'), readRateLimit, async (req, res) => {
     const q = req.query || {};
     const rank = q.rank ? String(q.rank) : null;
     if (rank && !VALID_RANKS.has(rank)) {

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.18.19",
+  "version": "1.19.3",
   "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/public-landing/create.html

@@ -700,9 +700,13 @@ input[type=text].bad{border-color:var(--err);}
     $('ghFresh').hidden = !(ok && !adopt);
     $('manualHome').hidden = !isManualHome();
     if (need) {
+      // Informed consent (ADR 0155): this grants `repo`, which GitHub's own screen
+      // words as full control of ALL your repositories — so say plainly why we ask
+      // and what we do with it, rather than letting GitHub's wording be the first
+      // the user hears of it. Private repos are the reason the scope is this wide.
       $('ghConnectMsg').textContent = adopt
-        ? 'You’re signed in — creating your project needs one more GitHub permission. Allow repo access to pick the repository to adopt.'
-        : 'You’re signed in — creating your project needs one more GitHub permission. Allow repo access and we’ll create the empty repo for you.';
+        ? 'You’re signed in — creating your project needs one more GitHub permission. GitHub will ask for repository access (it words this as access to all your repositories — that is the only scope it offers that can write to a private repo). We use it to read the repo you pick and push the setup commit to it. Nothing else is touched.'
+        : 'You’re signed in — creating your project needs one more GitHub permission. GitHub will ask for repository access (it words this as access to all your repositories — the narrower option cannot write to private repos). We use it to create your new empty repo and push the setup commit to it. Nothing else is touched.';
     }
     if (ok && adopt) initAdoptPicker();
     if (ok && !adopt) syncFresh();
@@ -934,7 +938,13 @@ input[type=text].bad{border-color:var(--err);}
           slug: state.slug,
           hosting_shape: 'standalone',
           domain: state.domain || undefined,
-          target_ref: state.owner + '/' + state.repo
+          target_ref: state.owner + '/' + state.repo,
+          /* LOAD-BEARING for the control-plane runner, not just for the checklist we
+             render (task 1002562): 'adopt' makes it clone + layer onto the repo's
+             existing history instead of pushing a fresh tree, which a repo that already
+             has commits rejects as unrelated history. state.mode already tracked
+             greenfield|adopt for the UI — it has to reach the server too. */
+          onboard_mode: state.mode === 'adopt' ? 'adopt' : 'greenfield'
         })
       });
     }).then(function (res) {

package/scripts/gds/abandon.js

@@ -41,7 +41,7 @@ const { cliClient, requireSession, arg } = require('./cli-lib');
     } else if (r.data?.error === 'task_not_found') {
       console.error(`Task #${taskId} not found.`);
     } else if (r.status === 403) {
-      console.error('Abandoning a task is Archon-only.');
+      console.error('Abandoning a task needs Metic+ rank (ADR 0152).');
     } else {
       console.error(`abandon failed (${r.status}):`, r.data);
     }

package/scripts/gds/audit-authorship.sh

@@ -126,6 +126,12 @@ ALLOWLIST=(
   # That's the GitHub org/user that owns the repo; not a builder identity.
   'scripts/deploy/provision-staging.sh'
 
+  # CODEOWNERS is GitHub's owner-review list (task 1002611 / ADR 0159): the
+  # format requires the literal @username on every entry. Repo-hosting
+  # identity, same nature as provision-staging.sh — not a builder identity
+  # hardcoded in code.
+  'CODEOWNERS'
+
   # Dev Box app distribution (#904, ADR 0044): the PUBLIC releases repo lives
   # under the same GitHub account that owns the main repo — repo-hosting
   # identity (same nature as provision-staging.sh above), not a builder

package/scripts/gds/box.js

@@ -1051,7 +1051,7 @@ async function cmdSweepDormant(pool, boxes, { apply }) {
     try {
       await deprovisionOne(pool, boxes, doApi, box, { actor: 'sweep:dormant' });
       reclaimed++;
-      const ping = postReclaimPing(`@${box.github_login} — your dev box was idle for ${days} days and has been reclaimed to save cost. Ask an Archon to re-provision when you're back; your memory is server-side and unaffected.`);
+      const ping = postReclaimPing(`@${box.github_login} — your dev box was idle for ${days} days and has been reclaimed to save cost. Queue a fresh one anytime with POST /api/gds/box/ensure (no operator needed); your memory is server-side and unaffected.`);
       if (!ping.ok) pingFailed++;
       console.log(`  ✓ reclaimed @${box.github_login} (parked ${days}d)${ping.ok ? '' : ' [chat ping failed]'}`);
     } catch (e) { errors++; await markErrorUnlessDestroyed(pool, boxes, box.builder_id, e.message); console.log(`  ✖ @${box.github_login}: ${e.message}`); }

package/scripts/gds/bump-version.js

@@ -0,0 +1,76 @@
+#!/usr/bin/env node
+// scripts/gds/bump-version.js — the mechanical CORE_VERSION patch bump for the
+// publish-on-merge lane (ADR 0161, task 1002620).
+//
+// WHY THIS EXISTS. ADR 0161 makes every merge to main publishable: when a merge
+// lands without a human version bump, CI bumps a PATCH itself so the release
+// has a unique version. The bump edits src/module-api.js in the two places the
+// repo's version discipline lives — the `const CORE_VERSION` literal and the
+// changelog comment block above it — because a bare literal change with no
+// changelog line is exactly the drift the discipline exists to prevent.
+//
+// POLICY (deliberately narrow): this script only ever bumps PATCH. A MINOR or
+// MAJOR is a statement about the doorway surface that only a human (or a far
+// smarter check) can make — it stays an in-task hand edit, exactly as before.
+//
+// SHAPE-PRESERVING: deploy-divergence.js finds bump commits with
+// `git log -G"^const CORE_VERSION = "` and reads the literal with a regex; the
+// rewrite here keeps that exact line shape. tests/bump_version.mjs pins this.
+//
+// Usage:
+//   node scripts/gds/bump-version.js                # dry-run: print the plan
+//   node scripts/gds/bump-version.js --apply        # rewrite src/module-api.js
+//   node scripts/gds/bump-version.js --apply --note "run 123456"  # extra provenance
+// stdout (both modes): one JSON line { from, to, applied } for CI to capture.
+
+'use strict';
+
+const fs = require('node:fs');
+const path = require('node:path');
+
+const TARGET = path.join(__dirname, '..', '..', 'src', 'module-api.js');
+const CONST_RE = /^const CORE_VERSION = '(\d+)\.(\d+)\.(\d+)';.*$/m;
+// The changelog block's closing divider sits immediately above the const line.
+const DIVIDER = '// ---------------------------------------------------------------------------';
+
+// Pure transform: (source text, optional note) -> { from, to, text }.
+// Throws with a precise message on any shape it does not recognize — a silent
+// mis-edit of the version literal is the worst possible failure mode here.
+function bumpPatch(src, { note = '' } = {}) {
+  const m = src.match(CONST_RE);
+  if (!m) throw new Error(`bump-version: could not find the CORE_VERSION literal in ${TARGET} (expected: const CORE_VERSION = 'x.y.z';)`);
+  const [major, minor, patch] = [Number(m[1]), Number(m[2]), Number(m[3])];
+  const from = `${major}.${minor}.${patch}`;
+  const to = `${major}.${minor}.${patch + 1}`;
+
+  // 1. The changelog entry — inserted just above the divider that closes the
+  //    changelog block, matching the existing two-line entry style.
+  const constLineStart = src.search(CONST_RE);
+  const dividerStart = src.lastIndexOf(DIVIDER, constLineStart);
+  if (dividerStart === -1) throw new Error('bump-version: could not find the changelog closing divider above CORE_VERSION');
+  const noteSuffix = note ? ` ${note}.` : '';
+  const entry =
+    `//   ${to} — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges\n` +
+    `//         landed since ${from} with no explicit bump.${noteSuffix} (task 1002620)\n`;
+
+  // 2. The literal — same line shape deploy-divergence greps for.
+  const newConstLine = `const CORE_VERSION = '${to}'; // CI auto-patch carrier (ADR 0161); see changelog above`;
+
+  const text = src.slice(0, dividerStart) + entry + src.slice(dividerStart).replace(CONST_RE, newConstLine);
+  return { from, to, text };
+}
+
+function main() {
+  const apply = process.argv.includes('--apply');
+  const noteIdx = process.argv.indexOf('--note');
+  const note = noteIdx !== -1 ? (process.argv[noteIdx + 1] || '') : '';
+
+  const src = fs.readFileSync(TARGET, 'utf8');
+  const { from, to, text } = bumpPatch(src, { note });
+  if (apply) fs.writeFileSync(TARGET, text);
+  else console.error(`bump-version: would bump ${from} → ${to} (dry-run; pass --apply to write)`);
+  console.log(JSON.stringify({ from, to, applied: apply }));
+}
+
+module.exports = { bumpPatch, CONST_RE };
+if (require.main === module) main();

package/scripts/gds/claim.js

@@ -210,6 +210,21 @@ function formatClaimFailure(r, taskId) {
     lines.push(`  ${d.what_to_do || 'Ship or release the current claim first.'}`);
     return { lines, exit: 1 };
   }
+  // task 1002589: the per-session DB backstop index tripped. Distinct from
+  // session_already_has_active_claim (the route guard's own refusal): since
+  // core_204 (task 1002570) the index keys per (session, worktree) —
+  // matching the guard — so this mainly surfaces the same-tree race the guard
+  // couldn't see, or fires on a DB still carrying the migration-180
+  // session-only index. Either way the target task itself is NOT taken — never
+  // render this as "claimed by another session".
+  if (code === 'session_already_has_bound_claim') {
+    const n = d.active_task_id;
+    lines.push(n
+      ? `Task #${taskId} is still free — but this session already holds a bound claim on #${n}${d.active_task_title ? `: ${d.active_task_title}` : ''}.`
+      : `Task #${taskId} is still free — but this session already holds a bound claim on another task.`);
+    lines.push(`  ${d.what_to_do || `Run /builder-ship ${n || '<task>'} (or /builder-release ${n || '<task>'}) first, claim from a separate worktree, or claim with {"bind_session":false} (an unbound claim always coexists).`}`);
+    return { lines, exit: 1 };
+  }
   if (code === 'ALREADY_CLAIMED') {
     lines.push(`Task #${taskId} was just claimed by another session. Try a different task.`);
     return { lines, exit: 1 };

package/scripts/gds/cli-lib.js

@@ -250,10 +250,22 @@ function printUnauthGuidanceAndExit() {
 
 // task 1050 (C): is this response the dev-box bootstrap-scoped 403? A box's baked
 // session (source='box', #919/ADR 0053) may only call the 4 on-box bootstrap
-// endpoints; everything else (claim/ship/me/…) returns 403 { error: 'box_scope' }.
-// Pure + exported so the detector is unit-tested.
+// endpoints; everything else (claim/ship/me/…) returns a 403 box_scope.
+//
+// task 1002162: accept BOTH body shapes. The live server emits the ADR 0116 (R01)
+// envelope — `{ error: { code, message, details? } }` from api-errors.js
+// `envelope()` — so `res.data.error` is an OBJECT and the old `=== 'box_scope'`
+// string test could never match. Both call sites below were therefore dead code
+// (box-scope was only ever caught by box-auth-check.js instead). Older/flat paths
+// still return `{ error: 'box_scope' }`, so normalize the same way
+// claim.js:formatClaimFailure does rather than swapping one shape for the other.
+//
+// Pure + exported so the detector is unit-tested against the real envelope.
 function isBoxScope(res) {
-  return !!res && res.status === 403 && !!res.data && res.data.error === 'box_scope';
+  if (!res || res.status !== 403 || !res.data) return false;
+  const errRaw = res.data.error;
+  const code = errRaw !== null && typeof errRaw === 'object' ? errRaw.code : errRaw;
+  return code === 'box_scope';
 }
 
 let _boxScopeExitInFlight = false;
@@ -652,7 +664,7 @@ function printCostWarning(meBody) {
   const cost = meBody && meBody.cost;
   if (!cost || typeof cost !== 'object') return;
   if (cost.level === 'over') {
-    console.log(`⚠ BUDGET EXCEEDED — $${cost.spend_mtd_usd} of $${cost.budget_mtd_usd} this month (${cost.pct_used}%). Cost-incurring actions (ship, art pipeline) are blocked until an Archon raises your budget.`);
+    console.log(`⚠ BUDGET EXCEEDED — $${cost.spend_mtd_usd} of $${cost.budget_mtd_usd} this month (${cost.pct_used}%). Cost-incurring actions (ship, art pipeline) are blocked until a Metic or Archon raises your budget.`);
   } else if (cost.level === 'warn') {
     console.log(`⚠ Budget at ${cost.pct_used}% — $${cost.spend_mtd_usd} of $${cost.budget_mtd_usd} this month. You'll be blocked from cost-incurring actions at 100%.`);
   }