@bongos/core 1.17.0

package/tests/devbox_downloads.mjs

@@ -0,0 +1,122 @@
+// tests/devbox_downloads.mjs
+//
+// Hermetic unit tests for the Dev Box app's branded download redirects (#904,
+// ADR 0045) — src/devbox-downloads.js — plus a shape check that the COMMITTED
+// config/devbox-app.json actually parses and resolves (so a bad release bump
+// fails this gate, not prod). Pure: no server, no network.
+//
+// Run:  node tests/devbox_downloads.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { buildDevboxDownloads } = require('../src/devbox-downloads.js');
+const committedConfig = require('../config/devbox-app.json');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const CFG = {
+  releases_repo: 'lars589/amazonprimea-devbox',
+  version: '1.2.3',
+  assets: {
+    'mac-arm64': 'OTB-Dev-Box-1.2.3-arm64.dmg',
+    'win-x64': 'OTB-Dev-Box-Setup-1.2.3.exe',
+  },
+  aliases: { mac: 'mac-arm64', win: 'win-x64' },
+};
+
+console.log('redirectFor:');
+
+t('maps a known target to the versioned release-asset URL', () => {
+  const d = buildDevboxDownloads(CFG);
+  assert.equal(
+    d.redirectFor('mac-arm64'),
+    'https://github.com/lars589/amazonprimea-devbox/releases/download/v1.2.3/OTB-Dev-Box-1.2.3-arm64.dmg'
+  );
+});
+
+t('aliases resolve; case and a stray extension are tolerated', () => {
+  const d = buildDevboxDownloads(CFG);
+  assert.equal(d.redirectFor('mac'), d.redirectFor('mac-arm64'));
+  assert.equal(d.redirectFor('WIN'), d.redirectFor('win-x64'));
+  assert.equal(d.redirectFor('mac-arm64.dmg'), d.redirectFor('mac-arm64'));
+});
+
+t('unknown targets, junk, and prototype-pollution probes → null', () => {
+  const d = buildDevboxDownloads(CFG);
+  assert.equal(d.redirectFor('linux-x64'), null);
+  assert.equal(d.redirectFor('../../etc/passwd'), null);
+  assert.equal(d.redirectFor('constructor'), null);
+  assert.equal(d.redirectFor('__proto__'), null);
+  assert.equal(d.redirectFor(''), null);
+  assert.equal(d.redirectFor('x'.repeat(40)), null);
+  assert.equal(d.redirectFor(null), null);
+});
+
+t('asset filenames are URL-encoded into the redirect (no path breakout)', () => {
+  const d = buildDevboxDownloads({
+    ...CFG,
+    assets: { 'mac-arm64': 'evil/../name.dmg' },
+  });
+  assert.ok(d.redirectFor('mac-arm64').endsWith('/v1.2.3/evil%2F..%2Fname.dmg'));
+});
+
+console.log('latestJson:');
+
+t('latestJson lists every target with file + url', () => {
+  const d = buildDevboxDownloads(CFG);
+  const j = d.latestJson();
+  assert.equal(j.version, '1.2.3');
+  assert.deepEqual(Object.keys(j.assets).sort(), ['mac-arm64', 'win-x64']);
+  assert.equal(j.assets['win-x64'].file, 'OTB-Dev-Box-Setup-1.2.3.exe');
+  assert.ok(j.assets['win-x64'].url.includes('/releases/download/v1.2.3/'));
+});
+
+console.log('versionJson (#924 — the app/hall update-check payload):');
+
+t('versionJson is the flat {version, assets: {target: url}} form', () => {
+  const d = buildDevboxDownloads(CFG);
+  const v = d.versionJson();
+  assert.equal(v.version, '1.2.3');
+  assert.deepEqual(Object.keys(v.assets).sort(), ['mac-arm64', 'win-x64']);
+  // assets values are bare download URLs (not the {file,url} wrapper latestJson uses).
+  assert.equal(typeof v.assets['mac-arm64'], 'string');
+  assert.ok(v.assets['mac-arm64'].endsWith('/v1.2.3/OTB-Dev-Box-1.2.3-arm64.dmg'));
+  assert.equal(v.assets['win-x64'], d.redirectFor('win-x64'));
+});
+
+console.log('config validation:');
+
+t('bad repo or version is rejected at boot, not served', () => {
+  assert.throws(() => buildDevboxDownloads({ ...CFG, releases_repo: 'no-slash' }));
+  assert.throws(() => buildDevboxDownloads({ ...CFG, releases_repo: 'a/b/c' }));
+  assert.throws(() => buildDevboxDownloads({ ...CFG, version: 'v1.2.3' }));
+  assert.throws(() => buildDevboxDownloads(null));
+});
+
+console.log('committed config:');
+
+t('config/devbox-app.json parses, resolves every target, and aliases point at real targets', () => {
+  const d = buildDevboxDownloads(committedConfig);
+  const j = d.latestJson();
+  for (const target of Object.keys(committedConfig.assets)) {
+    assert.ok(d.redirectFor(target), `target ${target} must resolve`);
+    assert.ok(j.assets[target].url.startsWith('https://github.com/'), `url for ${target}`);
+  }
+  for (const [alias, target] of Object.entries(committedConfig.aliases || {})) {
+    assert.equal(d.redirectFor(alias), d.redirectFor(target), `alias ${alias} → ${target}`);
+  }
+  // Every asset filename embeds the config version — catches a half-bumped release.
+  for (const file of Object.values(committedConfig.assets)) {
+    assert.ok(file.includes(committedConfig.version), `${file} should carry version ${committedConfig.version}`);
+  }
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/diff_derived_signals.mjs

@@ -0,0 +1,115 @@
+// tests/diff_derived_signals.mjs
+//
+// Coverage for touches[] cleanup [3/8] (task 878): session-log tags + shipper
+// badges + the claim-time learnings lookup must derive from the REAL committed
+// diff / the task's own metadata, not the predicted touches[].
+//
+// Three pure helpers carry the new behaviour; this pins them DB-free:
+//   1. ship.deriveTagsFromPaths       — folder tags over the changed-files list
+//   2. achievements.filesForBadges    — prefer the real diff, fall back to touches[]
+//   3. learnings._tagsFromTask        — discipline + title keywords (no touches[])
+//
+// Run:  node tests/diff_derived_signals.mjs
+
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ship = require('../scripts/gds/ship.js');
+// achievements carved into modules/economy/ (BV1.R77 / ADR 0093 §1-2).
+const achievements = require('../modules/economy/achievements.js');
+const learnings = require('../modules/memory/learnings.js');
+
+const tests = [];
+const test = (name, fn) => tests.push({ name, fn });
+
+// ---- ship.deriveTagsFromPaths ----
+
+test('deriveTagsFromPaths: leading folder segment becomes the tag', () => {
+  assert.deepEqual(
+    ship.deriveTagsFromPaths(['src/bongos/db.js', 'src/bongos/routes/tasks.js', 'migrations/081_x.sql']).sort(),
+    ['migrations', 'src'],
+  );
+});
+
+test('deriveTagsFromPaths: empty / globby input falls back to "pms"', () => {
+  assert.deepEqual(ship.deriveTagsFromPaths([]), ['pms']);
+  assert.deepEqual(ship.deriveTagsFromPaths(['*', '**']), ['pms']);
+  assert.deepEqual(ship.deriveTagsFromPaths(null), ['pms']);
+});
+
+test('deriveTagsFromPaths: art + scripts paths', () => {
+  assert.deepEqual(
+    ship.deriveTagsFromPaths(['art/generated/tiles/x.png', 'scripts/gds/ship.js']).sort(),
+    ['art', 'scripts'],
+  );
+});
+
+// ---- achievements.filesForBadges ----
+
+test('filesForBadges: a non-empty committed diff wins over touches[]', () => {
+  assert.deepEqual(
+    achievements.filesForBadges(['art/x.png'], ['src/bongos/db.js']),
+    ['art/x.png'],
+  );
+});
+
+test('filesForBadges: empty/absent diff falls back to touches[]', () => {
+  assert.deepEqual(achievements.filesForBadges([], ['src/bongos/db.js']), ['src/bongos/db.js']);
+  assert.deepEqual(achievements.filesForBadges(null, ['src/bongos/db.js']), ['src/bongos/db.js']);
+});
+
+test('filesForBadges: both empty → []', () => {
+  assert.deepEqual(achievements.filesForBadges(null, null), []);
+  assert.deepEqual(achievements.filesForBadges([], []), []);
+});
+
+test('filesForBadges: the badge cutover — diff says art/, prediction said gds', () => {
+  // A task whose touches[] mispredicted src/bongos/ but actually shipped only art/
+  // should now earn art-pipeline-shipper (real), not gds-shipper (predicted).
+  const files = achievements.filesForBadges(['art/pipeline/x.py'], ['src/bongos/db.js']);
+  assert.ok(files.some((f) => f.startsWith('art/')), 'real art/ diff drives the badge');
+  assert.ok(!files.some((f) => f.startsWith('src/bongos/')), 'mispredicted gds touches[] is ignored');
+});
+
+// ---- learnings._tagsFromTask ----
+
+test('_tagsFromTask: discipline + meaningful title words become candidates', () => {
+  const tags = learnings._tagsFromTask({
+    discipline: 'engineering',
+    title: 'Re-home migration allocation to a needs_migration boolean',
+  });
+  assert.ok(tags.includes('engineering'), 'discipline is a candidate');
+  assert.ok(tags.includes('migration'), 'meaningful title word is a candidate');
+  assert.ok(tags.includes('allocation'), 'meaningful title word is a candidate');
+  assert.ok(!tags.includes('to'), 'short word (<4 chars) dropped');
+  assert.ok(!tags.includes('a'), 'single-char token dropped');
+});
+
+test('_tagsFromTask: unclassified discipline is not a tag', () => {
+  const tags = learnings._tagsFromTask({ discipline: 'unclassified', title: 'drift scanner deletion' });
+  assert.ok(!tags.includes('unclassified'));
+  assert.ok(tags.includes('drift') && tags.includes('scanner') && tags.includes('deletion'));
+});
+
+test('_tagsFromTask: empty task → no candidates (lookup returns nothing, never throws)', () => {
+  assert.deepEqual(learnings._tagsFromTask({}), []);
+  assert.deepEqual(learnings._tagsFromTask({ discipline: '', title: '' }), []);
+});
+
+// ---- runner ----
+
+let pass = 0, fail = 0;
+for (const { name, fn } of tests) {
+  try {
+    await fn();
+    console.log(`PASS  ${name}`);
+    pass++;
+  } catch (e) {
+    console.log(`FAIL  ${name}`);
+    console.log(`      ${e.message}`);
+    fail++;
+  }
+}
+console.log(`\n${pass} passed, ${fail} failed`);
+process.exit(fail === 0 ? 0 : 1);

package/tests/discord_approvals.mjs

@@ -0,0 +1,174 @@
+// tests/discord_approvals.mjs
+//
+// Unit tests for Discord reaction → Archon approval (task 1100). The load-bearing
+// logic is PURE and tested here with no DB and no bot. This surface is MEMBER-ONLY
+// now: the dev-box first-box approval gate was removed (task 1141), so a reaction
+// only ever resolves a member-join (invite) request — there is no box branch.
+//   - emojiToDecision: 👍 → approve, 👎 → decline, anything else → null.
+//   - parseApprovalMarker: maps a request line back to { kind, id }, anchored to
+//     the LEADING `member-request #<id>` so a body mentioning another #id can't
+//     hijack it. Only the member marker is recognized.
+//   - recordApprovalReaction: the trust-boundary orchestration (ADR 0016) — acts
+//     ONLY for a linked Archon; re-derives live rank; resolves the member request;
+//     idempotent on already-resolved records; audits surface='discord_bot'; never
+//     throws (the caller is a gateway event handler). Any non-member kind is rejected.
+//   - memberApprovalLine: the producer line round-trips through parseApprovalMarker
+//     (the marker contract the two halves share).
+//
+// Run:  node tests/discord_approvals.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const ap = require('../modules/discord/discord-approvals.js');
+const bcast = require('../modules/onboarding/approval-broadcast.js');
+
+let passed = 0, 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}`); });
+}
+
+console.log('Discord reaction → Archon approval (task 1100):');
+
+// ---- emojiToDecision -------------------------------------------------------
+await t('emojiToDecision maps 👍/👎 and ignores the rest', () => {
+  assert.equal(ap.emojiToDecision('👍'), 'approve');
+  assert.equal(ap.emojiToDecision('👎'), 'decline');
+  assert.equal(ap.emojiToDecision('🎉'), null);
+  assert.equal(ap.emojiToDecision(''), null);
+  assert.equal(ap.emojiToDecision(undefined), null);
+});
+
+// ---- parseApprovalMarker ---------------------------------------------------
+await t('parseApprovalMarker reads the LEADING member-request + #<id>', () => {
+  assert.deepEqual(ap.parseApprovalMarker('member-request #42 — alice is asking to join'), { kind: 'member', id: 42 });
+});
+
+await t('parseApprovalMarker recognizes ONLY the member marker (box-intent is gone)', () => {
+  // The box-intent marker was removed with the first-box approval gate (task 1141).
+  assert.equal(ap.parseApprovalMarker('box-intent #7 — bob wants their first box'), null);
+  assert.equal(ap.parseApprovalMarker('  box-intent #5 leading but no longer a kind'), null);
+});
+
+await t('parseApprovalMarker ignores non-leading markers (no hijack)', () => {
+  assert.equal(ap.parseApprovalMarker('please approve member-request #42'), null);
+  assert.equal(ap.parseApprovalMarker('✅ alice invited to the hall.'), null);   // confirmation line
+});
+
+await t('parseApprovalMarker rejects junk', () => {
+  assert.equal(ap.parseApprovalMarker('member-request #0 nope'), null);   // id > 0
+  assert.equal(ap.parseApprovalMarker('member-request #'), null);
+  assert.equal(ap.parseApprovalMarker('random text'), null);
+  assert.equal(ap.parseApprovalMarker(''), null);
+  assert.equal(ap.parseApprovalMarker(null), null);
+  assert.equal(ap.parseApprovalMarker(42), null);                         // non-string
+});
+
+// ---- producer ↔ parser round-trip (the shared marker contract) -------------
+await t('memberApprovalLine round-trips through parseApprovalMarker', () => {
+  const line = bcast.memberApprovalLine({ id: 99, github_login: 'carol', display_name: 'Carol', note: 'hi @everyone' });
+  assert.deepEqual(ap.parseApprovalMarker(line), { kind: 'member', id: 99 });
+});
+
+// ---- recordApprovalReaction (orchestration via fakes) ----------------------
+const GOOD_ID = '123456789012345678';
+const archon = { id: 1, rank: 'archon', github_login: 'lars589' };
+
+function makeDeps(over = {}) {
+  const calls = { member: [], audit: [] };
+  const deps = {
+    getBuilderByDiscordUserId: async () => ('builder' in over ? over.builder : archon),
+    resolveAccessRequest: async (a) => {
+      calls.member.push(a);
+      return over.memberResolved === undefined
+        ? { id: a.id, github_login: 'carol', status: a.status }
+        : over.memberResolved;
+    },
+    insertAuditLog: async (a) => { calls.audit.push(a); if (over.auditThrows) throw new Error('audit boom'); return { id: 1 }; },
+  };
+  return { deps, calls };
+}
+
+await t('member 👍 by Archon → invited, audits surface=discord_bot', async () => {
+  const { deps, calls } = makeDeps();
+  const r = await ap.recordApprovalReaction({ discordUserId: GOOD_ID, kind: 'member', decision: 'approve', recordId: 42 }, deps);
+  assert.equal(r.outcome, 'approved');
+  assert.deepEqual(calls.member[0], { id: 42, status: 'invited', builderId: 1 });
+  assert.equal(calls.audit[0].surface, 'discord_bot');
+  assert.equal(calls.audit[0].route, 'discord:approval:member');
+});
+
+await t('member 👎 by Archon → dismissed', async () => {
+  const { deps, calls } = makeDeps();
+  const r = await ap.recordApprovalReaction({ discordUserId: GOOD_ID, kind: 'member', decision: 'decline', recordId: 42 }, deps);
+  assert.equal(r.outcome, 'declined');
+  assert.equal(calls.member[0].status, 'dismissed');
+});
+
+await t('a non-member kind (box / task) → bad_kind, no write', async () => {
+  // The first-box approval gate was removed (task 1141); recordApprovalReaction now
+  // accepts ONLY kind='member'. ANY other kind is rejected before any work.
+  for (const kind of ['box', 'task']) {
+    const { deps, calls } = makeDeps();
+    const r = await ap.recordApprovalReaction({ discordUserId: GOOD_ID, kind, decision: 'approve', recordId: 7 }, deps);
+    assert.equal(r.outcome, 'ignored');
+    assert.equal(r.reason, 'bad_kind');
+    assert.equal(calls.member.length + calls.audit.length, 0);
+  }
+});
+
+await t('NON-Archon reactor → ignored, no write (the trust boundary)', async () => {
+  for (const rank of ['metic', 'thetes', 'xenos']) {
+    const { deps, calls } = makeDeps({ builder: { id: 2, rank, github_login: 'm' } });
+    const r = await ap.recordApprovalReaction({ discordUserId: GOOD_ID, kind: 'member', decision: 'approve', recordId: 42 }, deps);
+    assert.equal(r.outcome, 'ignored');
+    assert.equal(r.reason, 'not_archon');
+    assert.equal(calls.member.length + calls.audit.length, 0);
+  }
+});
+
+await t('unlinked reactor → ignored, no write', async () => {
+  const { deps, calls } = makeDeps({ builder: null });
+  const r = await ap.recordApprovalReaction({ discordUserId: GOOD_ID, kind: 'member', decision: 'approve', recordId: 42 }, deps);
+  assert.equal(r.outcome, 'ignored');
+  assert.equal(r.reason, 'unlinked_reactor');
+  assert.equal(calls.member.length + calls.audit.length, 0);
+});
+
+await t('already-resolved record → already_resolved, no audit', async () => {
+  const { deps, calls } = makeDeps({ memberResolved: null });
+  const r = await ap.recordApprovalReaction({ discordUserId: GOOD_ID, kind: 'member', decision: 'approve', recordId: 42 }, deps);
+  assert.equal(r.outcome, 'already_resolved');
+  assert.equal(calls.audit.length, 0);  // nothing happened → nothing to audit
+});
+
+await t('bad discord id / kind / decision / record id → ignored before any work', async () => {
+  const { deps, calls } = makeDeps();
+  assert.equal((await ap.recordApprovalReaction({ discordUserId: 'nope', kind: 'member', decision: 'approve', recordId: 1 }, deps)).reason, 'bad_discord_user_id');
+  assert.equal((await ap.recordApprovalReaction({ discordUserId: GOOD_ID, kind: 'task', decision: 'approve', recordId: 1 }, deps)).reason, 'bad_kind');
+  assert.equal((await ap.recordApprovalReaction({ discordUserId: GOOD_ID, kind: 'member', decision: 'maybe', recordId: 1 }, deps)).reason, 'bad_decision');
+  assert.equal((await ap.recordApprovalReaction({ discordUserId: GOOD_ID, kind: 'member', decision: 'approve', recordId: 0 }, deps)).reason, 'bad_record_id');
+  assert.equal(calls.member.length + calls.audit.length, 0);
+});
+
+await t('audit failure does NOT undo the approval', async () => {
+  const { deps, calls } = makeDeps({ auditThrows: true });
+  const r = await ap.recordApprovalReaction({ discordUserId: GOOD_ID, kind: 'member', decision: 'approve', recordId: 42 }, deps);
+  assert.equal(r.outcome, 'approved');
+  assert.equal(calls.member.length, 1);
+});
+
+await t('a DB error returns {error}, never throws', async () => {
+  const deps = {
+    getBuilderByDiscordUserId: async () => { throw new Error('db down'); },
+    resolveAccessRequest: async () => ({}),
+    insertAuditLog: async () => ({}),
+  };
+  const r = await ap.recordApprovalReaction({ discordUserId: GOOD_ID, kind: 'member', decision: 'approve', recordId: 42 }, deps);
+  assert.equal(r.outcome, 'error');
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/discord_autojoin.mjs

@@ -0,0 +1,158 @@
+// tests/discord_autojoin.mjs
+//
+// Unit tests for the Discord link-first auto-join helper (Phase 3 F7, ADR 0033).
+// auth.addDiscordGuildMember() PUTs to Discord's add-guild-member endpoint with
+// the user's OAuth token + the bot token, setting the rank role at add-time.
+//
+// Network is stubbed via global.fetch; the bot token is injected via env
+// (DISCORD_BOT_TOKEN) so no creds file is touched. Pure-ish: we assert the
+// request shape (url, method, Bot auth header, body) and the status mapping
+// (201 → added:true, 204 → added:false, anything else → throws).
+//
+// Run:  node tests/discord_autojoin.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+
+// Inject a bot token BEFORE requiring auth so loadDiscordBotToken() resolves it
+// from env (the file fallback is never reached).
+process.env.DISCORD_BOT_TOKEN = 'test-bot-token';
+const auth = require('../src/bongos/auth.js');
+
+let passed = 0, 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 realFetch = global.fetch;
+function stubFetch(status, bodyText = '') {
+  const calls = [];
+  global.fetch = async (url, opts) => {
+    calls.push({ url, opts });
+    return {
+      status,
+      ok: status >= 200 && status < 300,
+      text: async () => bodyText,
+    };
+  };
+  return calls;
+}
+function restoreFetch() { global.fetch = realFetch; }
+
+console.log('Discord auto-join helper (Phase 3 F7):');
+
+await t('PUTs to the add-member endpoint with Bot auth + access_token + roles in body', async () => {
+  const calls = stubFetch(201);
+  try {
+    const res = await auth.addDiscordGuildMember({
+      guildId: '111111111111111111',
+      discordUserId: '222222222222222222',
+      accessToken: 'user-oauth-token',
+      roleIds: ['333333333333333333'],
+    });
+    assert.equal(res.added, true, '201 → added:true');
+    assert.equal(calls.length, 1);
+    const { url, opts } = calls[0];
+    assert.equal(url, 'https://discord.com/api/guilds/111111111111111111/members/222222222222222222');
+    assert.equal(opts.method, 'PUT');
+    assert.equal(opts.headers.Authorization, 'Bot test-bot-token');
+    assert.equal(opts.headers['Content-Type'], 'application/json');
+    const body = JSON.parse(opts.body);
+    assert.equal(body.access_token, 'user-oauth-token');
+    assert.deepEqual(body.roles, ['333333333333333333']);
+  } finally { restoreFetch(); }
+});
+
+await t('204 (already a member) → added:false', async () => {
+  stubFetch(204);
+  try {
+    const res = await auth.addDiscordGuildMember({
+      guildId: '1', discordUserId: '2', accessToken: 'tok', roleIds: [],
+    });
+    assert.equal(res.added, false);
+  } finally { restoreFetch(); }
+});
+
+await t('non-2xx (e.g. 403 missing Create Instant Invite) throws with status + body', async () => {
+  stubFetch(403, 'Missing Permissions');
+  try {
+    await assert.rejects(
+      () => auth.addDiscordGuildMember({ guildId: '1', discordUserId: '2', accessToken: 'tok', roleIds: [] }),
+      /403.*Missing Permissions/,
+    );
+  } finally { restoreFetch(); }
+});
+
+await t('roles defaults to [] when roleIds is missing/not an array', async () => {
+  const calls = stubFetch(201);
+  try {
+    await auth.addDiscordGuildMember({ guildId: '1', discordUserId: '2', accessToken: 'tok' });
+    assert.deepEqual(JSON.parse(calls[0].opts.body).roles, []);
+  } finally { restoreFetch(); }
+});
+
+await t('throws a clear error when guildId is missing', async () => {
+  await assert.rejects(
+    () => auth.addDiscordGuildMember({ discordUserId: '2', accessToken: 'tok', roleIds: [] }),
+    /guild id not configured/,
+  );
+});
+
+console.log('\nDiscord guild-remove helper (F7 unlink follow-up):');
+
+await t('DELETEs the member endpoint with Bot auth header', async () => {
+  const calls = stubFetch(204);
+  try {
+    const res = await auth.removeDiscordGuildMember({
+      guildId: '111111111111111111',
+      discordUserId: '222222222222222222',
+    });
+    assert.equal(res.removed, true);
+    assert.equal(calls.length, 1);
+    const { url, opts } = calls[0];
+    assert.equal(url, 'https://discord.com/api/guilds/111111111111111111/members/222222222222222222');
+    assert.equal(opts.method, 'DELETE');
+    assert.equal(opts.headers.Authorization, 'Bot test-bot-token');
+  } finally { restoreFetch(); }
+});
+
+await t('404 (not in guild) → removed:false, not_in_guild', async () => {
+  stubFetch(404);
+  try {
+    const res = await auth.removeDiscordGuildMember({ guildId: '1', discordUserId: '2' });
+    assert.equal(res.removed, false);
+    assert.equal(res.reason, 'not_in_guild');
+  } finally { restoreFetch(); }
+});
+
+await t('403 (missing Kick Members) → removed:false, missing_permission', async () => {
+  stubFetch(403);
+  try {
+    const res = await auth.removeDiscordGuildMember({ guildId: '1', discordUserId: '2' });
+    assert.equal(res.removed, false);
+    assert.equal(res.reason, 'missing_permission');
+  } finally { restoreFetch(); }
+});
+
+await t('unexpected status throws', async () => {
+  stubFetch(500, 'Internal Server Error');
+  try {
+    await assert.rejects(
+      () => auth.removeDiscordGuildMember({ guildId: '1', discordUserId: '2' }),
+      /500/,
+    );
+  } finally { restoreFetch(); }
+});
+
+await t('throws when guildId is missing', async () => {
+  await assert.rejects(
+    () => auth.removeDiscordGuildMember({ discordUserId: '2' }),
+    /guild id not configured/,
+  );
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/discord_bot.mjs

@@ -0,0 +1,94 @@
+// tests/discord_bot.mjs
+//
+// Unit tests for the Discord bot process (Phase 3 F3, ADR 0033 §F3). These
+// cover the parts that must hold WITHOUT a live gateway, a token, or the
+// discord.js dependency being exercised:
+//   - botEnabled() is the fail-closed kill-switch: ON only for the exact
+//     string 'true' (mirrors BFG_WRITE_ENABLED). Anything else is OFF.
+//   - start() is a no-op when the switch is off: it returns null, never throws,
+//     and never touches discord.js — so a default deploy carries no bot.
+//   - start() enabled-but-tokenless returns null and does not throw — a
+//     misconfiguration must not crash the boot path.
+//   - loadDiscordBotToken() prefers env, returns null when nothing is set.
+//   - stop() on a never-started bot is a safe no-op.
+//
+// The live connection (login → 'ready') is verified out-of-band with a real
+// token (see the F3 ship notes); it can't be unit-tested without network.
+//
+// Run:  node tests/discord_bot.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+const require = createRequire(import.meta.url);
+const bot = require('../modules/discord/discord-bot.js');
+const auth = require('../src/bongos/auth.js');
+
+let passed = 0, 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}`); });
+}
+
+// Save + restore the env keys these tests poke, so the suite is order-safe.
+const SAVED = {
+  DISCORD_BOT_ENABLED: process.env.DISCORD_BOT_ENABLED,
+  DISCORD_BOT_TOKEN: process.env.DISCORD_BOT_TOKEN,
+};
+function restoreEnv() {
+  for (const [k, v] of Object.entries(SAVED)) {
+    if (v === undefined) delete process.env[k];
+    else process.env[k] = v;
+  }
+}
+
+console.log('Discord bot process (Phase 3 F3):');
+
+await t('botEnabled is ON only for the exact string "true"', () => {
+  assert.equal(bot.botEnabled({ DISCORD_BOT_ENABLED: 'true' }), true);
+  for (const v of ['1', 'false', 'TRUE', 'yes', '', undefined]) {
+    assert.equal(bot.botEnabled({ DISCORD_BOT_ENABLED: v }), false, `should be OFF for ${String(v)}`);
+  }
+  assert.equal(bot.botEnabled({}), false, 'unset → OFF (fail-closed default)');
+});
+
+await t('start() is a no-op returning null when the switch is off', async () => {
+  delete process.env.DISCORD_BOT_ENABLED;
+  const r = await bot.start();
+  assert.equal(r, null);
+  // Off path must not have loaded discord.js into the require cache.
+  const loaded = Object.keys(require.cache).some((p) => p.includes('/node_modules/discord.js/'));
+  assert.equal(loaded, false, 'discord.js must not be required when the bot is disabled');
+  restoreEnv();
+});
+
+await t('start() enabled-but-tokenless returns null and does not throw', async () => {
+  process.env.DISCORD_BOT_ENABLED = 'true';
+  delete process.env.DISCORD_BOT_TOKEN;
+  // Force the file fallback to miss too by pointing HOME at an empty dir would
+  // be ideal, but loadDiscordBotToken reads a fixed path; in CI there is no
+  // ~/.config/otb/discord-bot.json, so env-absent → null. If a dev machine has
+  // the file, this test is skipped rather than connecting a real bot.
+  if (auth.loadDiscordBotToken()) {
+    console.log('        (skipped — a real bot token is present on this machine)');
+  } else {
+    const r = await bot.start();
+    assert.equal(r, null, 'no token → no connection');
+  }
+  restoreEnv();
+});
+
+await t('loadDiscordBotToken prefers DISCORD_BOT_TOKEN env', () => {
+  process.env.DISCORD_BOT_TOKEN = 'env-token-xyz';
+  assert.equal(auth.loadDiscordBotToken(), 'env-token-xyz');
+  assert.equal(auth.discordBotConfigured(), true);
+  restoreEnv();
+});
+
+await t('stop() on a never-started bot is a safe no-op', async () => {
+  await bot.stop(); // must not throw
+});
+
+restoreEnv();
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);