@bongos/core 1.18.19 → 1.19.2

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.2",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.18.19",
+      "version": "1.19.2",
       "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.2",
   "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/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%.`);
   }

package/scripts/gds/gating.js

@@ -2,18 +2,25 @@
 // scripts/gds/gating.js — owner kill-switch for main-branch merge gating.
 //
 // What "gating" means here — TWO independent levers, both toggled together:
-//   1. GitHub branch protection on `main`: required status checks (unit,
-//      trufflehog, gate-review) + required code-owner review (CODEOWNERS).
+//   1. GitHub branch protection on `main`: required status checks + required
+//      code-owner review (CODEOWNERS). The required contexts are ONLY checks
+//      that exist and can pass today — currently `unit` (the suite + fitness
+//      lane, task 1002610). The planned `secret-scan` and `gate-review`
+//      contexts (ADR 0058 phase 3; CORE_EXPECTED_CHECKS in adopt-preflight.js)
+//      join DEFAULT_PROTECTION when their workflows ship — requiring a context
+//      nothing reports blocks every merge indefinitely (D-12, ADR 0159).
 //   2. The application-layer trust gates that run on every PR — the gate-review
-//      and grade-gate CI workflows. These post their own status checks and the
-//      ship / auto-merge pipeline refuses to land a PR while gate-review is red
+//      and grade-gate CI workflows (ADR 0058 phases 1-3; NOT YET IN THE TREE —
+//      workflowState() reports them 'absent' and the toggles below no-op until
+//      they ship). Once live they post their own status checks and the ship /
+//      auto-merge pipeline refuses to land a PR while gate-review is red
 //      (it escalates gate-surface changes — infra/, migrations/, CODEOWNERS,
 //      scripts/gds plumbing — to owner approval). Branch protection alone does
 //      NOT neutralize these, which is why `off` also `gh workflow disable`s them.
 // With gating ON, a gate-surface PR needs owner approval / --admin to merge.
 // With gating OFF, ordinary `gh pr merge N` (and every builder / autonomous
-// session) merges with no checks and no approval. `unit` + `trufflehog` keep
-// running either way — real safety nets that force no approval.
+// session) merges with no checks and no approval. `unit` keeps running either
+// way — a real safety net that forces no approval.
 //
 // It is REVERSIBLE by construction: `off` snapshots the live protection to a
 // replay-ready file, then deletes protection; `on` PUTs the snapshot back,
@@ -47,19 +54,27 @@ const SNAPSHOT = require('../../src/instance-config').configPath('gating-snapsho
 // approval / --admin on gate-surface changes. Branch protection alone does NOT
 // neutralize these — they post their own status checks and the auto-merge /
 // ship pipeline refuses to land a PR while gate-review is red. So the kill-switch
-// also disables/enables these workflows. `unit` + `trufflehog` (secret scan) are
-// deliberately left running — they are real safety nets and force no approval.
+// also disables/enables these workflows. PLANNED, not yet in the tree (ADR 0058
+// phases 1-3): while absent, workflowState() reports 'absent' and both toggles
+// no-op — the names stay here so the switch covers them the moment they ship.
+// `unit` is deliberately left running — a real safety net that forces no approval.
 const GATE_WORKFLOWS = ['gate-review.yml', 'grade-gate.yml'];
 
-// Baked-in known-good config (the live state captured 2026-06-19). Used only as
-// a restore fallback when no snapshot exists, so `on` can never be stuck.
+// Baked-in known-good config. Used only as a restore fallback when no snapshot
+// exists, so `on` can never be stuck. Requires ONLY contexts that exist and can
+// pass today (ADR 0159 — D-12: a required context nothing reports blocks every
+// merge indefinitely, and a required context that is red on every PR does the
+// same). When the secret-scan / gate-review workflows ship (ADR 0058), add
+// their contexts back here — those names are the contract (adopt-preflight.js
+// CORE_EXPECTED_CHECKS, init.js), tool-agnostic on purpose.
 const DEFAULT_PROTECTION = {
   required_status_checks: {
     strict: false,
     checks: [
       { context: 'unit', app_id: 15368 },
-      { context: 'trufflehog', app_id: 15368 },
-      { context: 'gate-review', app_id: 15368 },
+      // Stated intent, not yet requirable — uncomment as each workflow ships:
+      // { context: 'secret-scan', app_id: 15368 },  // secret scanning (ADR 0058)
+      // { context: 'gate-review', app_id: 15368 },  // gate-surface review (ADR 0058 phase 3)
     ],
   },
   enforce_admins: false,
@@ -270,7 +285,7 @@ function cmdOff(repo) {
 
   console.log('\n🔴 gating OFF. `main` is UNPROTECTED and the gate-review/grade CI gates no longer');
   console.log('   run — ordinary `gh pr merge N` (and every builder / autonomous session) merges');
-  console.log('   with no checks and no approval. (unit + secret-scan still run.)');
+  console.log('   with no checks and no approval. (unit still runs.)');
   console.log('   ↩  restore everything: node scripts/gds/gating.js on');
 }
 

package/scripts/gds/gen-api-docs.js

@@ -81,7 +81,7 @@ const RANK_BLURB = {
   public: 'No authentication — any caller.',
   'any-builder': 'Any authenticated builder (row-level ownership enforced in-handler).',
   'metic+archon': 'Metic or Archon rank (review/triage powers).',
-  archon: 'Archon only (the single owner — ratification, infra, rank changes).',
+  archon: 'Archon only (rank and identity management + the escalation keys — the trust boundary).',
   'bfg-principal': 'The BFG cross-builder memory service principal (not a human rank).',
   unknown: 'Gate could not be classified from source — treat as privileged.',
 };