@bongos/core 1.17.0

package/tests/security_docs.mjs

@@ -0,0 +1,186 @@
+// tests/security_docs.mjs
+//
+// Unit smoke for the Archon-only security_docs store (task 991). The DATED
+// exploit-detail engagement reports live in the DB (NOT the git clone —
+// threat-model §6.3 / ADR 0020) and are served only to Archons. This test
+// proves, with NO live Postgres:
+//
+//   DB helpers (against a stubbed pool seam):
+//     - listSecurityDocs() asks for METADATA only (slug/title/updated_at/bytes
+//       via char_length), never content_md — the list must not ship the bodies
+//     - getSecurityDoc() asks for the row WITH content_md, parameterized by slug
+//     - upsertSecurityDoc() is an INSERT ... ON CONFLICT (slug) DO UPDATE with
+//       updated_at = now(), parameterized
+//
+//   Route validation (pure validate() helper):
+//     - slug / title / content_md required; content_md cap is the LARGE doc cap,
+//       not the small LIMITS.DESCRIPTION
+//     - the slug character-class regex rejects non-kebab slugs
+//
+//   Rank wiring (source assertion — mirrors tests/cli_token_reissue.mjs):
+//     - all three /security/docs* routes are auth.requireRank('archon')
+//     - route-rank-check pins them to 'archon' in EXPECTED_RANKS
+//
+// We stub the pool by pre-seeding the require cache for src/db.js so the db
+// module under test never opens a socket — the same monkeypatch seam the repo
+// uses for DB-free helper coverage.
+//
+// Run:  node tests/security_docs.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 __dirname = path.dirname(fileURLToPath(import.meta.url));
+const ROOT = path.resolve(__dirname, '..');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  return Promise.resolve()
+    .then(fn)
+    .then(() => { passed++; console.log(`  ok  ${name}`); })
+    .catch((e) => { failed++; console.error(`  FAIL ${name}\n        ${e.message}`); });
+}
+
+// ---------------------------------------------------------------------------
+// Pool stub: record every query so we can assert SQL shape + params, and
+// return canned rows. Seed it into the require cache as src/bongos/pool.js (the
+// GDS-owned pool since the R52 carve-out, task 1191) BEFORE requiring
+// src/bongos/db.js so the helpers bind to this fake pool.
+// ---------------------------------------------------------------------------
+const calls = [];
+let nextRows = [];
+const fakePool = {
+  query: async (text, params) => {
+    calls.push({ text, params });
+    return { rows: nextRows };
+  },
+};
+const poolPath = require.resolve(path.join(ROOT, 'src', 'bongos', 'pool.js'));
+require.cache[poolPath] = { id: poolPath, filename: poolPath, loaded: true, exports: { pool: fakePool, instanceDbName: () => undefined } };
+
+const gdsDb = require(path.join(ROOT, 'src', 'bongos', 'db.js'));
+const { validate, LIMITS } = require(path.join(ROOT, 'src', 'bongos', 'routes', '_helpers.js'));
+const rrc = require(path.join(ROOT, 'src', 'bongos', 'route-rank-check.js'));
+
+function lastCall() { return calls[calls.length - 1]; }
+
+console.log('security_docs — DB helpers (stubbed pool):');
+
+await test('listSecurityDocs() returns METADATA only — no content_md in the SELECT', async () => {
+  calls.length = 0;
+  nextRows = [{ slug: 'a', title: 'A', updated_at: '2026-06-12T00:00:00Z', bytes: 1234 }];
+  const rows = await gdsDb.listSecurityDocs();
+  const sql = lastCall().text;
+  assert.ok(/SELECT/i.test(sql), 'should be a SELECT');
+  assert.ok(/char_length\(content_md\)\s+AS\s+bytes/i.test(sql), 'list must expose only the SIZE (char_length AS bytes)');
+  assert.ok(!/SELECT[^;]*\bcontent_md\b(?!\))/i.test(sql.replace(/char_length\(content_md\)/i, '')),
+    'list SELECT must NOT include the raw content_md column');
+  assert.ok(/ORDER BY\s+updated_at\s+DESC/i.test(sql), 'newest-updated first');
+  assert.deepEqual(rows, nextRows);
+});
+
+await test('getSecurityDoc(slug) selects content_md, parameterized by slug', async () => {
+  calls.length = 0;
+  nextRows = [{ id: 1, slug: 'rt', title: 'RT', content_md: '# body', created_at: 'x', updated_at: 'y' }];
+  const row = await gdsDb.getSecurityDoc('rt');
+  const { text, params } = lastCall();
+  assert.ok(/SELECT[\s\S]*content_md[\s\S]*FROM security_docs/i.test(text), 'get must return content_md');
+  assert.ok(/WHERE slug = \$1/i.test(text), 'parameterized by slug');
+  assert.deepEqual(params, ['rt']);
+  assert.equal(row.slug, 'rt');
+});
+
+await test('getSecurityDoc() returns null when no row', async () => {
+  nextRows = [];
+  const row = await gdsDb.getSecurityDoc('missing');
+  assert.equal(row, null);
+});
+
+await test('upsertSecurityDoc() is INSERT ... ON CONFLICT (slug) DO UPDATE w/ updated_at=now(), parameterized', async () => {
+  calls.length = 0;
+  nextRows = [{ id: 2, slug: 's', title: 'T', content_md: 'C', created_at: 'x', updated_at: 'y' }];
+  const row = await gdsDb.upsertSecurityDoc({ slug: 's', title: 'T', contentMd: 'C' });
+  const { text, params } = lastCall();
+  assert.ok(/INSERT INTO security_docs/i.test(text), 'should INSERT');
+  assert.ok(/ON CONFLICT \(slug\) DO UPDATE/i.test(text), 'should upsert on slug');
+  assert.ok(/updated_at\s*=\s*now\(\)/i.test(text), 'should bump updated_at on conflict');
+  assert.deepEqual(params, ['s', 'T', 'C'], 'parameterized in slug,title,content order');
+  assert.equal(row.slug, 's');
+});
+
+console.log('\nsecurity_docs — route validation (pure validate()):');
+
+// The exact schema the POST /security/docs route uses.
+const CONTENT_MAX = 2_000_000;
+const DOCS_SCHEMA = {
+  slug:       { required: true, type: 'string', maxLength: 128, minLength: 1 },
+  title:      { required: true, type: 'string', maxLength: 200, minLength: 1 },
+  content_md: { required: true, type: 'string', maxLength: CONTENT_MAX, minLength: 1 },
+};
+const SLUG_RE = /^[a-z0-9-]{1,128}$/;
+
+await test('valid body passes validation', () => {
+  assert.equal(validate({ slug: 'x', title: 'T', content_md: 'body' }, DOCS_SCHEMA), null);
+});
+
+await test('missing slug / title / content_md each fail required', () => {
+  for (const f of ['slug', 'title', 'content_md']) {
+    const body = { slug: 'x', title: 'T', content_md: 'body' };
+    delete body[f];
+    const r = validate(body, DOCS_SCHEMA);
+    assert.ok(r, `${f} missing should fail`);
+    assert.equal(r.error, 'validation_failed');
+    assert.ok(r.details.some((d) => d.field === f), `${f} should be flagged`);
+  }
+});
+
+await test('content_md cap is the LARGE doc cap, NOT LIMITS.DESCRIPTION', () => {
+  assert.ok(CONTENT_MAX > LIMITS.DESCRIPTION, 'doc store must allow more than the small DESCRIPTION cap');
+  // A 60k body (> LIMITS.DESCRIPTION = 50k) must be ACCEPTED by the doc schema.
+  const big = 'x'.repeat(LIMITS.DESCRIPTION + 10_000);
+  assert.equal(validate({ slug: 'x', title: 'T', content_md: big }, DOCS_SCHEMA), null,
+    'a report larger than LIMITS.DESCRIPTION must still be a legal doc');
+  // But the same body against the small DESCRIPTION cap would be rejected.
+  const small = validate({ content_md: big }, { content_md: { type: 'string', maxLength: LIMITS.DESCRIPTION } });
+  assert.ok(small, 'control: the small cap rejects the same oversize body');
+});
+
+await test('over the large cap is rejected', () => {
+  const tooBig = 'x'.repeat(CONTENT_MAX + 1);
+  const r = validate({ slug: 'x', title: 'T', content_md: tooBig }, DOCS_SCHEMA);
+  assert.ok(r && r.details.some((d) => d.field === 'content_md'), 'content over 2MB cap should fail');
+});
+
+await test('slug character-class regex rejects non-kebab slugs', () => {
+  assert.ok(SLUG_RE.test('2026-06-12-newbuilder-redteam'), 'dated kebab slug is valid');
+  assert.ok(!SLUG_RE.test('Bad Slug'),  'spaces + caps rejected');
+  assert.ok(!SLUG_RE.test('a/b'),       'path separators rejected');
+  assert.ok(!SLUG_RE.test('UPPER'),     'uppercase rejected');
+  assert.ok(!SLUG_RE.test('a'.repeat(129)), 'over 128 chars rejected');
+  assert.ok(!SLUG_RE.test(''),          'empty rejected');
+});
+
+console.log('\nsecurity_docs — rank wiring (source + pin):');
+
+await test('all three /security/docs* routes are requireRank(archon)', () => {
+  const src = fs.readFileSync(path.join(ROOT, 'src', 'bongos', 'routes', 'security.js'), 'utf8');
+  const routes = rrc.classifyText(src).filter((r) => r.route.startsWith('/security/docs'));
+  assert.equal(routes.length, 3, 'expected GET list, GET :slug, POST');
+  for (const r of routes) {
+    assert.equal(r.rank, 'archon', `${r.key} must classify as archon (serves exploit detail)`);
+  }
+});
+
+await test('route-rank-check pins all three /security/docs* routes to archon', () => {
+  for (const key of ['GET /security/docs', 'GET /security/docs/:slug', 'POST /security/docs']) {
+    assert.equal(rrc.EXPECTED_RANKS[key], 'archon', `${key} must be pinned archon in EXPECTED_RANKS`);
+  }
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/security_route.mjs

@@ -0,0 +1,108 @@
+// tests/security_route.mjs
+//
+// Unit smoke for the /security/adr internals (V3.R68 / #287). Verifies:
+//   - the env-not-set branch reports the right reason
+//   - the file-unreadable branch reports the right reason
+//   - the happy path reads the file and shapes the payload correctly
+//
+// We exercise the pure helpers (no Express, no DB) — the rank gate itself is
+// already covered by tests/rank_gate.mjs, and the route-wiring is verified by
+// reading routes.js. Keeping the surface this small means the test stays
+// fast and doesn't fight Express's stub-ability.
+//
+// Run:  node tests/security_route.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs/promises';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const security = require('../src/bongos/routes/security.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  return Promise.resolve()
+    .then(fn)
+    .then(() => { passed++; console.log(`  PASS  ${name}`); })
+    .catch((e) => { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); });
+}
+
+const { adrPath, readFullAdr } = security._internals;
+
+console.log('security/adr internals:');
+
+await t('adrPath() returns null when env unset', () => {
+  const prev = process.env.GDS_SECURITY_ADR_PATH;
+  delete process.env.GDS_SECURITY_ADR_PATH;
+  try {
+    assert.equal(adrPath(), null);
+  } finally {
+    if (prev !== undefined) process.env.GDS_SECURITY_ADR_PATH = prev;
+  }
+});
+
+await t('adrPath() trims whitespace and returns null for empty string', () => {
+  const prev = process.env.GDS_SECURITY_ADR_PATH;
+  process.env.GDS_SECURITY_ADR_PATH = '   ';
+  try {
+    assert.equal(adrPath(), null);
+  } finally {
+    if (prev !== undefined) process.env.GDS_SECURITY_ADR_PATH = prev;
+    else delete process.env.GDS_SECURITY_ADR_PATH;
+  }
+});
+
+await t('readFullAdr() reports env_not_set when path is unset', async () => {
+  const prev = process.env.GDS_SECURITY_ADR_PATH;
+  delete process.env.GDS_SECURITY_ADR_PATH;
+  try {
+    const r = await readFullAdr();
+    assert.equal(r.ok, false);
+    assert.equal(r.reason, 'env_not_set');
+  } finally {
+    if (prev !== undefined) process.env.GDS_SECURITY_ADR_PATH = prev;
+  }
+});
+
+await t('readFullAdr() reports file_unreadable when env points at missing file', async () => {
+  const prev = process.env.GDS_SECURITY_ADR_PATH;
+  process.env.GDS_SECURITY_ADR_PATH = path.join(os.tmpdir(), `nonexistent-${Date.now()}.md`);
+  try {
+    const r = await readFullAdr();
+    assert.equal(r.ok, false);
+    assert.equal(r.reason, 'file_unreadable');
+    // ENOENT is the expected code; we don't pin the value tightly in case
+    // Node renames it across platforms — just confirm we surface something.
+    assert.ok(r.code, 'expected an errno code to surface');
+  } finally {
+    if (prev !== undefined) process.env.GDS_SECURITY_ADR_PATH = prev;
+    else delete process.env.GDS_SECURITY_ADR_PATH;
+  }
+});
+
+await t('readFullAdr() returns the file contents when the file exists', async () => {
+  const tmpPath = path.join(os.tmpdir(), `security-adr-test-${Date.now()}.md`);
+  const expected = '# Test ADR\n\nProvisioned for the unit test.\n';
+  await fs.writeFile(tmpPath, expected, 'utf8');
+  const prev = process.env.GDS_SECURITY_ADR_PATH;
+  process.env.GDS_SECURITY_ADR_PATH = tmpPath;
+  try {
+    const r = await readFullAdr();
+    assert.equal(r.ok, true);
+    assert.equal(r.payload.adr_md, expected);
+    assert.equal(r.payload.source, tmpPath);
+    assert.ok(r.payload.fetched_at, 'fetched_at should be populated');
+    // ISO timestamp shape — quick sanity, not pinned to exact value.
+    assert.ok(/\d{4}-\d{2}-\d{2}T/.test(r.payload.fetched_at), 'fetched_at should look like ISO 8601');
+  } finally {
+    await fs.unlink(tmpPath).catch(() => {});
+    if (prev !== undefined) process.env.GDS_SECURITY_ADR_PATH = prev;
+    else delete process.env.GDS_SECURITY_ADR_PATH;
+  }
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/served_paths_shipped.mjs

@@ -0,0 +1,118 @@
+// tests/served_paths_shipped.mjs
+//
+// GUARD (task 2078): every static asset serve-internal.js reads at runtime from the
+// core tree MUST be included in the packaged core — i.e. isPublishable() per
+// scripts/gds/publish-manifest.js. A standalone instance runs the PACKAGED core
+// (@cloudbongos/core, ADR 0108), so a served path the publish boundary EXCLUDES is
+// simply absent on the box and 404s.
+//
+// This is exactly how demo.cloudbongos.com rendered a blank page: the browser client
+// bundle clients/bongos-client/bongos-client.global.js — served at /lib/bongos-client.js
+// and required by every hall page as window.BongosClient — was not on the allowlist, so
+// the packaged core omitted it and the whole UI crashed on load. The existing
+// tests/client_bundle_route.mjs proves the ROUTE works against the FULL checkout (file
+// present); THIS proves the file will actually SHIP. Together they close the gap.
+//
+// It parses the source statically (no import of serve-internal, which pulls the app),
+// so it stays cheap and DB-free.
+//
+// Run:  node tests/served_paths_shipped.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+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 ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const { isPublishable } = require('../scripts/gds/publish-manifest.js');
+
+const SERVE_INTERNAL = path.join(ROOT, 'src/bongos/serve-internal.js');
+
+// Paths serve-internal reads from ROOT that are INTENTIONALLY not in the packaged core.
+// Each needs a documented reason; the last test asserts each is genuinely excluded, so
+// allowlisting one later makes its exception here fail loudly (a stale-exception guard).
+const INTENTIONALLY_UNSHIPPED = {
+  // The /downloads/bongos/* installer feature reads scripts from infra/ (prod topology,
+  // PUBLISH_DENYLIST) and mounts only when config/bongos-cli.json exists (also excluded).
+  // An instance opts in by shipping both; the core deliberately doesn't.
+  infra: 'prod topology (installer scripts); the /downloads feature is config-gated and excluded from the core',
+};
+
+// Leading-literal ROOT prefixes that are BASE directories, not served asset paths:
+// serve-internal joins further DYNAMIC segments onto them (a per-module / per-request
+// filename). The concrete children carry their own allowlist entries (each enabled
+// module is individually allowlisted), so the base alone is not a shippable-asset claim.
+const NOT_SERVED_BASE = new Set([
+  'modules', // path.join(ROOT,'modules') → MODULES_ROOT; real serves are path.join(MODULES_ROOT, key, 'public', rel)
+]);
+
+// Extract the leading contiguous string-literal prefix of every path.join(ROOT, ...)
+// call. A trailing non-literal arg (a variable) means "some file under this dir", so the
+// literal prefix is the directory that must ship.
+function extractRootJoinPrefixes(src) {
+  const out = new Set();
+  const re = /path\.join\(\s*ROOT\s*,/g;
+  let m;
+  while ((m = re.exec(src))) {
+    // Arg span up to the matching close paren. These calls contain no nested parens
+    // before their close (true for every ROOT join today); a future nested call would
+    // mis-slice into an unpublishable-looking prefix and fail loudly, not pass silently.
+    const start = m.index + m[0].length;
+    const close = src.indexOf(')', start);
+    if (close === -1) continue;
+    const segs = [];
+    for (let part of src.slice(start, close).split(',')) {
+      part = part.trim();
+      const lit = part.match(/^(['"])(.*)\1$/);
+      if (!lit) break; // hit a variable → stop; prefix is the dir so far
+      segs.push(lit[2]);
+    }
+    if (segs.length) out.add(segs.join('/').replace(/\/+$/, ''));
+  }
+  return out;
+}
+
+// A prefix isPublishable() can classify: a file (its last segment has an extension)
+// checks itself; a directory checks a representative child.
+function probe(prefix) {
+  const last = prefix.split('/').pop() || '';
+  return last.includes('.') ? prefix : `${prefix}/__probe__`;
+}
+
+const prefixes = extractRootJoinPrefixes(fs.readFileSync(SERVE_INTERNAL, 'utf8'));
+
+test('extraction found the known served assets (guards against a silent no-match)', () => {
+  assert.ok(prefixes.size >= 5, `expected several ROOT-served paths, found ${prefixes.size}`);
+  assert.ok(prefixes.has('clients/bongos-client/bongos-client.global.js'), 'must see the client bundle read');
+  assert.ok(prefixes.has('docs/api/openapi.json'), 'must see the openapi spec read');
+});
+
+test('every ROOT-served asset ships in the core package (isPublishable)', () => {
+  const offenders = [];
+  for (const prefix of prefixes) {
+    if (NOT_SERVED_BASE.has(prefix)) continue;
+    if (INTENTIONALLY_UNSHIPPED[prefix]) continue;
+    if (!isPublishable(probe(prefix))) offenders.push(prefix);
+  }
+  assert.deepEqual(
+    offenders,
+    [],
+    `serve-internal.js reads these from ROOT but the publish boundary EXCLUDES them, so the ` +
+      `packaged core (@cloudbongos/core) omits them and a standalone 404s (task 2078): ${offenders.join(', ')}. ` +
+      `Fix: add each to PUBLISH_ALLOWLIST in scripts/gds/publish-manifest.js (or, if truly host-only, ` +
+      `document it in INTENTIONALLY_UNSHIPPED in this test).`
+  );
+});
+
+test('each documented exception is genuinely excluded (stale-exception guard)', () => {
+  for (const prefix of Object.keys(INTENTIONALLY_UNSHIPPED)) {
+    assert.equal(
+      isPublishable(probe(prefix)),
+      false,
+      `'${prefix}' is listed as intentionally-unshipped but the boundary now PUBLISHES it — remove it from INTENTIONALLY_UNSHIPPED.`
+    );
+  }
+});

package/tests/session-cards.mjs

@@ -0,0 +1,142 @@
+// tests/session-cards.mjs
+//
+// Unit tests for the card-delivery hook (.claude/hooks/session-cards.js, task
+// 1288) — the deterministic-delivery layer for READ-ONLY in-session cards
+// (builder-start, status). Covers the pure decision surface: matchCard (which
+// card an intent routes to), each card's arg extraction, and
+// buildAdditionalContext (the directive builder). The stdin / script-spawn /
+// inject plumbing is thin and degradable-by-design (silent exit 0) and is
+// exercised by the live hook smoke at ship time, not here.
+//
+// Run:  node tests/session-cards.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const hook = require('../.claude/hooks/session-cards.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}`);
+  }
+}
+
+const count = (hay, needle) => hay.split(needle).length - 1;
+const idOf = (prompt) => { const c = hook.matchCard(prompt); return c ? c.id : null; };
+const statusCard = hook.CARDS.find((c) => c.id === 'status');
+
+// ---------- matchCard: routing ----------
+
+test('routes builder-start intents to the builder-start card', () => {
+  for (const p of ['/builder-start', '/builder-start --full', 'please run /builder-start',
+    'what can I work on', 'hey what can I work on today?', 'what can i claim', "what's claimable",
+    'show me tasks', 'show me the tasks']) {
+    assert.equal(idOf(p), 'builder-start', `should route to builder-start: ${p}`);
+  }
+});
+
+test('routes status intents to the status card', () => {
+  for (const p of ['/status', '/status C8', 'please run /status',
+    "what's left for C8", "what's remaining in GDS-V4", 'status of GDS-V4',
+    'how far along is the memory criterion', "what's the status", 'what tasks remain to satisfy C3']) {
+    assert.equal(idOf(p), 'status', `should route to status: ${p}`);
+  }
+});
+
+test('does NOT route unrelated prompts (cost gate)', () => {
+  for (const p of ['fix the login bug', 'start the dev server', 'how does /builder-start work?',
+    'show me the diff', 'claim task 1288', 'what is the capital of France', '']) {
+    assert.equal(idOf(p), null, `should NOT route: ${p}`);
+  }
+});
+
+test('matchCard is type-safe on non-strings', () => {
+  assert.equal(hook.matchCard(null), null);
+  assert.equal(hook.matchCard(undefined), null);
+  assert.equal(hook.matchCard(42), null);
+});
+
+// ---------- status card: arg extraction ----------
+
+test('status args always start with --hook', () => {
+  assert.deepEqual(statusCard.args('/status'), ['--hook']);
+});
+
+test('status args extract an explicit version', () => {
+  assert.deepEqual(statusCard.args('status of GDS-V4'), ['--hook', '--version', 'GDS-V4']);
+  assert.deepEqual(statusCard.args('how far along is V1'), ['--hook', '--version', 'V1']);
+  assert.deepEqual(statusCard.args("what's left in PMS-V1"), ['--hook', '--version', 'PMS-V1']);
+});
+
+test('status args extract a criterion token', () => {
+  assert.deepEqual(statusCard.args("what's left for C8"), ['--hook', 'C8']);
+});
+
+test('status args extract version AND criterion together', () => {
+  assert.deepEqual(statusCard.args('status of GDS-V4 C2'), ['--hook', '--version', 'GDS-V4', 'C2']);
+});
+
+// ---------- buildAdditionalContext: widgets ON ----------
+
+const onEnv = {
+  widgets_enabled: true,
+  html: '<div class="st-card">WIDGET-BODY</div>',
+  markdown: '**/status**\nMARKDOWN-BODY',
+  warnings: [],
+};
+
+test('widgets ON: hands both forms + the show_widget branch, parameterized by title', () => {
+  const ctx = hook.buildAdditionalContext(onEnv, 'status_card');
+  assert.ok(ctx.includes('mcp__visualize__show_widget'), 'names the widget tool');
+  assert.ok(ctx.includes('mcp__visualize__read_me'), 'tells it to read_me first');
+  assert.ok(ctx.includes('title "status_card"'), 'passes the card-specific title');
+  assert.ok(ctx.includes('status card'), 'head names the card (title de-underscored)');
+  assert.ok(ctx.includes('<div class="st-card">WIDGET-BODY</div>'), 'embeds the HTML verbatim');
+  assert.ok(ctx.includes('MARKDOWN-BODY'), 'embeds the markdown fallback verbatim');
+  assert.ok(/do NOT run the script yourself/i.test(ctx), 'forbids re-running the script');
+});
+
+test('widgets ON: each fence token appears EXACTLY twice (no extraction ambiguity)', () => {
+  const ctx = hook.buildAdditionalContext(onEnv, 'status_card');
+  assert.equal(count(ctx, '<<<WIDGET_HTML>>>'), 2);
+  assert.equal(count(ctx, '<<<MARKDOWN_CARD>>>'), 2);
+});
+
+test('widgets ON: warnings relayed as a private note; absent when empty', () => {
+  assert.ok(!hook.buildAdditionalContext(onEnv, 'builder_start_card').includes('private note'));
+  const ctx = hook.buildAdditionalContext({ ...onEnv, warnings: ['⚠ 85% budget used'] }, 'builder_start_card');
+  assert.ok(ctx.includes('private note'));
+  assert.ok(ctx.includes('85% budget used'));
+});
+
+// ---------- buildAdditionalContext: widgets OFF + empties ----------
+
+test('widgets OFF: markdown-only, never a widget render', () => {
+  const ctx = hook.buildAdditionalContext({ widgets_enabled: false, html: null, markdown: 'MD-ONLY', warnings: [] }, 'status_card');
+  assert.ok(ctx.includes('MD-ONLY'));
+  assert.ok(/widgets turned OFF/i.test(ctx));
+  assert.equal(count(ctx, '<<<WIDGET_HTML>>>'), 0);
+  assert.equal(count(ctx, '<<<MARKDOWN_CARD>>>'), 2);
+});
+
+test('empty / malformed envelope or missing title → empty string', () => {
+  assert.equal(hook.buildAdditionalContext(null, 'status_card'), '');
+  assert.equal(hook.buildAdditionalContext({}, 'status_card'), '');
+  assert.equal(hook.buildAdditionalContext({ markdown: '' }, 'status_card'), '');
+  assert.equal(hook.buildAdditionalContext(onEnv, null), '', 'no title → nothing');
+});
+
+// ---------- Summary ----------
+
+console.log('');
+console.log(`session-cards tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/session_506_regression.mjs

@@ -0,0 +1,69 @@
+// tests/session_506_regression.mjs
+//
+// The #506 regression gate (6D.5, ADR 0027). Runs the session-inefficiency
+// engine (6D.3) over a checked-in, hand-built #506-shaped digest
+// (tests/fixtures/session-506-digest.json) and asserts it reproduces the
+// hand-labelled findings from the 2026-06-01 manual post-mortem:
+//
+//   - a WASTEFUL verdict (~90% of tokens on ceremony + footgun recovery);
+//   - guess-and-retry on API enums   → the #514 fix;
+//   - a stale-test red herring        → the #468 fix;
+//   - the heavyweight grader panel on a trivial change → the #513 fix.
+//
+// If a change to session-eval.js's classifier or detectors stops reproducing
+// these, THIS test fails — that's the gate. (The real #506 transcript isn't
+// retained locally; the fixture is a faithful reconstruction — see its _comment.)
+//
+// Run:  node tests/session_506_regression.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ev = require('../scripts/gds/session-eval.js');
+const fixture = require('./fixtures/session-506-digest.json');
+
+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}`);
+  }
+}
+
+const result = ev.evaluateSession(fixture);
+const footgunTypes = new Set(result.footguns.map((f) => f.type));
+
+test('#506: verdict is wasteful (ceremony + recovery dominate)', () => {
+  assert.equal(result.verdict, 'wasteful');
+  assert.ok(result.overhead_ratio > 0.85, `overhead should be ~0.9, got ${result.overhead_ratio}`);
+  assert.ok(result.work_ratio < 0.15, `work should be a small slice, got ${result.work_ratio}`);
+});
+
+test('#506 → #514: guess-and-retry on API enums detected (twice)', () => {
+  assert.ok(footgunTypes.has('guess_and_retry_api'));
+  const api = result.footguns.find((f) => f.type === 'guess_and_retry_api');
+  assert.equal(api.count, 2, 'bad_kind + status_not_patchable');
+});
+
+test('#506 → #468: stale-test red herring detected', () => {
+  assert.ok(footgunTypes.has('stale_test_red_herring'), 'the smoke-write.sh stale assertion');
+});
+
+test('#506 → #513: heavyweight pipeline on a trivial change detected', () => {
+  assert.ok(footgunTypes.has('heavyweight_pipeline_on_trivial_change'), 'panel ran on a 2-work-turn change');
+});
+
+test('#506: repeated tool failures flagged', () => {
+  assert.ok(footgunTypes.has('repeated_tool_failures'));
+});
+
+console.log('');
+console.log(`#506 regression gate (6D.5): ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);