@bongos/core 1.17.0

package/tests/api_path_404.mjs

@@ -0,0 +1,96 @@
+// tests/api_path_404.mjs
+//
+// V4.R14 / #952 — self-describing errors (criterion: machine-room-ergonomics).
+// Two error shapes:
+//   1. API-shaped paths that miss the /api/gds mount get a JSON 404 + corrective
+//      hint, never the HTML island page (which JSON.parse-faulted on the client).
+//   2. A TASK_NOT_READY 409 names the promote route instead of leaving the caller
+//      to spelunk for it (#506).
+//
+// Both are pinned via the pure exported helpers (no server, no DB).
+//
+// Run:  node tests/api_path_404.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { isApiShapedPath, apiPathHint, apiNotFoundBody } = require('../src/bongos/api-path-404.js');
+const { taskNotReadyHint } = require('../modules/lifecycle/routes/claims.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// ---- isApiShapedPath -------------------------------------------------------
+t('API-shaped: /api/*, /gds/*, and bare GDS roots (/tasks, /me, …) match', () => {
+  for (const p of ['/api/foo', '/api/bongos/tasks', '/api/gds/tasks', '/bongos/tasks', '/gds/tasks',
+                   '/tasks', '/tasks/5', '/me', '/claims', '/versions', '/memory/files', '/leaderboard']) {
+    assert.equal(isApiShapedPath(p), true, `${p} should be API-shaped`);
+  }
+});
+
+t('NOT API-shaped: game/hall/static paths fall through to HTML/static', () => {
+  for (const p of ['/', '/index.html', '/builders', '/builders/work', '/atlas-ab12.png',
+                   '/vendor/phaser.min.js', '/downloads/devbox/mac', '/game', '/healthz', '/version']) {
+    assert.equal(isApiShapedPath(p), false, `${p} should NOT be API-shaped`);
+  }
+});
+
+t('word-boundary: /tasksomething is NOT a GDS root (needs / or end of path)', () => {
+  assert.equal(isApiShapedPath('/tasksomething'), false);
+  assert.equal(isApiShapedPath('/memorial'), false); // not /memory
+});
+
+// ---- apiPathHint -----------------------------------------------------------
+t('apiPathHint: rewrites to the CANONICAL mount (/api/bongos)', () => {
+  assert.equal(apiPathHint('/tasks'), '/api/bongos/tasks');
+  assert.equal(apiPathHint('/tasks/5'), '/api/bongos/tasks/5');
+  assert.equal(apiPathHint('/bongos/tasks'), '/api/bongos/tasks'); // dropped /api
+  assert.equal(apiPathHint('/gds/tasks'), '/api/gds/tasks');       // dropped /api on the alias segment
+  assert.equal(apiPathHint('/api/foo'), '/api/bongos/foo');
+});
+
+t('apiPathHint: already under a live mount (canonical OR alias) → null (genuine route miss)', () => {
+  assert.equal(apiPathHint('/api/bongos/bogus'), null);
+  assert.equal(apiPathHint('/api/bongos'), null);
+  assert.equal(apiPathHint('/api/gds/bogus'), null); // the permanent alias is a live mount too
+  assert.equal(apiPathHint('/api/gds'), null);
+});
+
+// ---- apiNotFoundBody -------------------------------------------------------
+t('apiNotFoundBody: includes error + message + hint when a rewrite exists', () => {
+  const body = apiNotFoundBody('/tasks');
+  assert.equal(body.error, 'not_found');
+  assert.equal(body.hint, '/api/bongos/tasks');
+  assert.match(body.message, /\/api\/bongos/);
+  assert.match(body.message, /\/api\/bongos\/tasks/);
+});
+
+t('apiNotFoundBody: no hint key for an already-prefixed miss (canonical or alias)', () => {
+  for (const p of ['/api/bongos/bogus', '/api/gds/bogus']) {
+    const body = apiNotFoundBody(p);
+    assert.equal(body.error, 'not_found');
+    assert.equal('hint' in body, false, 'no rewrite → omit the hint');
+  }
+});
+
+// ---- taskNotReadyHint (the 409) --------------------------------------------
+t('taskNotReadyHint: a backlog task names the promote route', () => {
+  const h = taskNotReadyHint(953, 'backlog');
+  assert.match(h, /POST \/api\/bongos\/tasks\/953\/promote/);
+  assert.match(h, /backlog/);
+});
+
+t('taskNotReadyHint: a non-backlog status is explained + still names promote', () => {
+  const h = taskNotReadyHint('953', 'blocked');
+  assert.match(h, /'blocked'/);
+  assert.match(h, /not 'ready'/);
+  assert.match(h, /POST \/api\/bongos\/tasks\/953\/promote/);
+});
+
+console.log(`\napi_path_404: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/app_pair.mjs

@@ -0,0 +1,168 @@
+// tests/app_pair.mjs
+//
+// Hermetic unit tests for the Dev Box desktop app's pairing store (#904,
+// ADR 0045) — src/bongos/app-pair.js. Pure in-memory, injected clock, no DB,
+// no network. Locks down the security-load-bearing behaviors: one-shot token
+// delivery, no-oracle expiry/unknown responses, TTL, the pending→approved
+// state machine, code normalization, and the memory cap.
+//
+// Run:  node tests/app_pair.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const { createPairStore, normalizeCode } = require('../src/bongos/app-pair.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const NOW = Date.parse('2026-06-10T12:00:00Z');
+function storeAt(opts = {}) {
+  let now = NOW;
+  const store = createPairStore({ nowMs: () => now, ...opts });
+  return { store, tick: (ms) => { now += ms; } };
+}
+
+console.log('normalizeCode:');
+
+t('accepts canonical XXXX-XXXX and returns it unchanged', () => {
+  assert.equal(normalizeCode('ABCD-EFGH'), 'ABCD-EFGH');
+});
+
+t('normalizes case, spaces, and a missing dash', () => {
+  assert.equal(normalizeCode('  abcd efgh '), 'ABCD-EFGH');
+  assert.equal(normalizeCode('abcdefgh'), 'ABCD-EFGH');
+});
+
+t('rejects wrong length, off-alphabet chars (0/O/1/I/L/U/V), and non-strings', () => {
+  assert.equal(normalizeCode('ABC-DEFG'), null);
+  assert.equal(normalizeCode('ABCD-EFG0'), null);  // 0 not in alphabet
+  assert.equal(normalizeCode('ABCD-EFGI'), null);  // I not in alphabet
+  assert.equal(normalizeCode('ABCD-EFGU'), null);  // U not in alphabet
+  assert.equal(normalizeCode(null), null);
+  assert.equal(normalizeCode(12345678), null);
+});
+
+console.log('start:');
+
+t('start returns a well-formed pairing', () => {
+  const { store } = storeAt();
+  const out = store.start({ deviceName: 'OTB Dev Box', platform: 'mac' });
+  assert.match(out.pairCode, /^[A-HJ-NP-TW-Z2-9]{4}-[A-HJ-NP-TW-Z2-9]{4}$/);
+  assert.match(out.pollToken, /^[0-9a-f]{64}$/);
+  assert.equal(out.expiresIn, 600);
+  assert.equal(out.interval, 5);
+});
+
+t('start truncates oversized device names and defaults missing fields', () => {
+  const { store } = storeAt();
+  const out = store.start({ deviceName: 'x'.repeat(500) });
+  const info = store.info(out.pairCode);
+  assert.equal(info.deviceName.length, 80);
+  assert.equal(info.platform, 'unknown');
+});
+
+t('start refuses beyond the memory cap with error:busy', () => {
+  const { store } = storeAt({ maxPending: 3 });
+  for (let i = 0; i < 3; i++) assert.ok(store.start({}).pairCode);
+  assert.deepEqual(store.start({}), { error: 'busy' });
+});
+
+t('expired entries free cap space (lazy purge)', () => {
+  const { store, tick } = storeAt({ maxPending: 2, ttlMs: 1000 });
+  store.start({});
+  store.start({});
+  tick(1001);
+  assert.ok(store.start({}).pairCode, 'cap should free after expiry');
+});
+
+console.log('info:');
+
+t('info shows device details for a live pending code (any input form)', () => {
+  const { store } = storeAt();
+  const { pairCode } = store.start({ deviceName: 'OTB Dev Box', platform: 'windows' });
+  const info = store.info(pairCode.toLowerCase().replace('-', ' '));
+  assert.equal(info.deviceName, 'OTB Dev Box');
+  assert.equal(info.platform, 'windows');
+  assert.equal(info.status, 'pending');
+});
+
+t('info: unknown and expired are indistinguishable (both null)', () => {
+  const { store, tick } = storeAt({ ttlMs: 1000 });
+  const { pairCode } = store.start({});
+  tick(1001);
+  assert.equal(store.info(pairCode), null);
+  assert.equal(store.info('ABCD-EFGH'), null);
+});
+
+console.log('approve:');
+
+t('approve parks the grant exactly once', () => {
+  const { store } = storeAt();
+  const { pairCode } = store.start({});
+  assert.deepEqual(store.approve(pairCode, { token: 'tok1' }), { ok: true });
+  assert.deepEqual(store.approve(pairCode, { token: 'tok2' }), { error: 'already_approved' });
+});
+
+t('approve on unknown or expired code → not_found', () => {
+  const { store, tick } = storeAt({ ttlMs: 1000 });
+  const { pairCode } = store.start({});
+  assert.deepEqual(store.approve('ABCD-EFGH', { token: 't' }), { error: 'not_found' });
+  tick(1001);
+  assert.deepEqual(store.approve(pairCode, { token: 't' }), { error: 'not_found' });
+});
+
+console.log('poll:');
+
+t('poll is pending before approval, delivers the grant once, then expired', () => {
+  const { store } = storeAt();
+  const { pairCode, pollToken } = store.start({});
+  assert.deepEqual(store.poll(pollToken), { status: 'pending', interval: 5 });
+  const grant = { token: 'sess-token', builder: { github_login: 'larstest' } };
+  store.approve(pairCode, grant);
+  const out = store.poll(pollToken);
+  assert.equal(out.status, 'approved');
+  assert.deepEqual(out.grant, grant);
+  // One-shot: the entry is gone; replay of the SAME poll token yields expired.
+  assert.deepEqual(store.poll(pollToken), { status: 'expired' });
+});
+
+t('poll: unknown token and expired pairing are indistinguishable', () => {
+  const { store, tick } = storeAt({ ttlMs: 1000 });
+  const { pollToken } = store.start({});
+  assert.deepEqual(store.poll('f'.repeat(64)), { status: 'expired' });
+  tick(1001);
+  assert.deepEqual(store.poll(pollToken), { status: 'expired' });
+});
+
+t('an approved-but-never-polled grant still dies at TTL', () => {
+  const { store, tick } = storeAt({ ttlMs: 1000 });
+  const { pairCode, pollToken } = store.start({});
+  store.approve(pairCode, { token: 'sess' });
+  tick(1001);
+  assert.deepEqual(store.poll(pollToken), { status: 'expired' });
+  assert.equal(store._size(), 0, 'expired entry purged');
+});
+
+t('a delivered grant leaves no residue in the store', () => {
+  const { store } = storeAt();
+  const { pairCode, pollToken } = store.start({});
+  store.approve(pairCode, { token: 'sess' });
+  store.poll(pollToken);
+  assert.equal(store._size(), 0);
+});
+
+t('pair code cannot poll; poll token cannot approve (credential separation)', () => {
+  const { store } = storeAt();
+  const { pairCode, pollToken } = store.start({});
+  assert.deepEqual(store.poll(pairCode), { status: 'expired' });
+  assert.deepEqual(store.approve(pollToken, { token: 't' }), { error: 'not_found' });
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/architect.mjs

@@ -0,0 +1,140 @@
+// tests/architect.mjs
+//
+// Unit tests for the MAS Phase 5 Architect (#459). Covers the pure parts —
+// slug, kind validation, seed-idea normalization, and the prompt builder.
+// The subagent spawn / doc write / inbox filing are I/O and are exercised by
+// the real first-audit run at ship time, not here.
+//
+// Run:  node tests/architect.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const architect = require('../scripts/gds/architect-audit.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}`); }
+}
+
+// ---------- slug ----------
+
+test('slug: lowercases + hyphenates + trims', () => {
+  assert.equal(architect.slug('Multi-Agent System'), 'multi-agent-system');
+  assert.equal(architect.slug('GDS API surface'), 'gds-api-surface');
+  assert.equal(architect.slug('  Trim/Me!!  '), 'trim-me');
+});
+
+test('slug: empty / junk → "audit" fallback', () => {
+  assert.equal(architect.slug(''), 'audit');
+  assert.equal(architect.slug('!!!'), 'audit');
+  assert.equal(architect.slug(null), 'audit');
+});
+
+test('slug: caps length', () => {
+  assert.ok(architect.slug('x'.repeat(200)).length <= 60);
+});
+
+// ---------- pickValidKind ----------
+
+test('pickValidKind: passes known kinds', () => {
+  for (const k of ['feature', 'refactor', 'cleanup', 'infra', 'decision', 'spike']) {
+    assert.equal(architect.pickValidKind(k), k);
+  }
+});
+
+test('pickValidKind: unknown → unclassified', () => {
+  assert.equal(architect.pickValidKind('architecture'), 'unclassified');
+  assert.equal(architect.pickValidKind(undefined), 'unclassified');
+});
+
+// ---------- validateSeedIdeas ----------
+
+test('validateSeedIdeas: keeps well-formed, coerces kind, trims title', () => {
+  const out = architect.validateSeedIdeas([
+    { title: '  Delete the dead foo helper ', kind: 'cleanup', body_md: 'remove src/foo.js' },
+    { title: 'Consolidate diff helpers', kind: 'architecture', body_md: 'one module' },
+  ]);
+  assert.equal(out.length, 2);
+  assert.equal(out[0].title, 'Delete the dead foo helper');
+  assert.equal(out[0].kind, 'cleanup');
+  assert.equal(out[1].kind, 'unclassified'); // 'architecture' coerced
+});
+
+test('validateSeedIdeas: drops entries without a usable title', () => {
+  const out = architect.validateSeedIdeas([
+    { title: '', kind: 'feature' },
+    { kind: 'feature', body_md: 'no title' },
+    { title: '   ', kind: 'feature' },
+    { title: 'Real one', kind: 'feature' },
+  ]);
+  assert.equal(out.length, 1);
+  assert.equal(out[0].title, 'Real one');
+});
+
+test('validateSeedIdeas: non-array / junk → []', () => {
+  assert.deepEqual(architect.validateSeedIdeas(null), []);
+  assert.deepEqual(architect.validateSeedIdeas('nope'), []);
+  assert.deepEqual(architect.validateSeedIdeas([null, 42, 'x']), []);
+});
+
+test('validateSeedIdeas: caps title length', () => {
+  const out = architect.validateSeedIdeas([{ title: 'T'.repeat(500), kind: 'feature' }]);
+  assert.ok(out[0].title.length <= 200);
+});
+
+// ---------- buildPrompt ----------
+
+test('buildPrompt: embeds the scope + all 5 Musk steps + the deletion emphasis', () => {
+  const p = architect.buildPrompt({
+    scope: 'Multi-Agent System',
+    fileList: [{ path: 'src/bongos/grader.js', loc: 700 }],
+    fileBlocks: '### src/bongos/grader.js\n```\n...\n```',
+    version: 'GDS-V3',
+  });
+  assert.match(p, /Multi-Agent System/);
+  // The 5 steps, in the prompt
+  assert.match(p, /Make the requirements less dumb/i);
+  assert.match(p, /DELETE/);
+  assert.match(p, /Simplify/i);
+  assert.match(p, /Accelerate/i);
+  assert.match(p, /Automate/i);
+  // Deletion emphasis + first-principles framing
+  assert.match(p, /not afraid to delete/i);
+  assert.match(p, /first principles/i);
+  // Output contract
+  assert.match(p, /audit_md/);
+  assert.match(p, /seed_ideas/);
+  assert.match(p, /10% honesty check/i);
+  // Scope file is listed with its LOC
+  assert.match(p, /src\/bongos\/grader\.js\s+\(700 lines\)/);
+});
+
+test('buildPrompt: no-version path omits the planning-version line cleanly', () => {
+  const p = architect.buildPrompt({
+    scope: 'X',
+    fileList: [{ path: 'a.js', loc: 1 }],
+    fileBlocks: '### a.js\n```\n1\n```',
+    version: undefined,
+  });
+  // The "Seed ideas will be filed for planning under:" line is version-gated.
+  assert.doesNotMatch(p, /filed for planning under/);
+  // ...but the rest of the prompt is intact.
+  assert.match(p, /Audit scope: X/);
+  assert.match(p, /seed_ideas/);
+});
+
+test('PROMPT_HEADER names the Architect + distinguishes it from Grader/Conductor', () => {
+  assert.match(architect.PROMPT_HEADER, /Architect/);
+  assert.match(architect.PROMPT_HEADER, /Grader/);
+  assert.match(architect.PROMPT_HEADER, /Conductor/);
+});
+
+// ---------- Summary ----------
+
+console.log('');
+console.log(`Architect tests: ${passed} passed, ${failed} failed`);
+if (failed > 0) process.exit(1);

package/tests/art_key.mjs

@@ -0,0 +1,121 @@
+// tests/art_key.mjs
+//
+// Unit smoke for modules/art-pipeline/art-key.js (task 1281, moved BV1.R48) — the GDS-delivered SHARED Gemini
+// key for newcomers. Covers the pure entitlement decision (xenos in; thetes+ out;
+// unknown rank fails closed), the env/file key loader, and the describeArtKey
+// payload shape. The route (routes/me.js) + the local sync (fetch-art-key.js) and
+// the pipeline tier (gen_api.py) are exercised by the endpoint smoke + manual
+// resolution check; here we cover the logic without pg or network.
+//
+// Hermetic: the "not configured" cases unset SHARED_ART_GEMINI_KEY and repoint
+// HOME at an empty temp dir so the ~/.config/otb/gemini-shared.json fallback can't
+// resolve to a real operator file on the test machine.
+//
+// Run:  node tests/art_key.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { mkdtempSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const a = require('../modules/art-pipeline/art-key.js');
+const db = require('../modules/lifecycle/db.js');
+
+let passed = 0;
+let failed = 0;
+function t(name, fn) {
+  try { fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+// Run a thunk with SHARED_ART_GEMINI_KEY + HOME forced to known values, restoring
+// both afterward so cases don't leak into each other.
+function withEnv({ key, emptyHome }, fn) {
+  const origKey = process.env.SHARED_ART_GEMINI_KEY;
+  const origHome = process.env.HOME;
+  if (key === null) delete process.env.SHARED_ART_GEMINI_KEY;
+  else if (key !== undefined) process.env.SHARED_ART_GEMINI_KEY = key;
+  if (emptyHome) process.env.HOME = mkdtempSync(join(tmpdir(), 'otb-artkey-'));
+  try { fn(); }
+  finally {
+    if (origKey === undefined) delete process.env.SHARED_ART_GEMINI_KEY;
+    else process.env.SHARED_ART_GEMINI_KEY = origKey;
+    process.env.HOME = origHome;
+  }
+}
+
+console.log('entitlement boundary:');
+
+t('SHARED_ART_KEY_MAX_TIER is the xenos tier (1)', () => {
+  assert.equal(a.SHARED_ART_KEY_MAX_TIER, db.REQUIRES_RANK_TIER.xenos);
+  assert.equal(a.SHARED_ART_KEY_MAX_TIER, 1);
+});
+
+t('xenos is entitled (reason newcomer)', () => {
+  assert.deepEqual(a.entitlementFor('xenos'), { entitled: true, reason: 'newcomer' });
+});
+
+t('thetes / metic / archon are NOT entitled (reason rank_above_newcomer)', () => {
+  for (const rank of ['thetes', 'metic', 'archon']) {
+    assert.deepEqual(a.entitlementFor(rank), { entitled: false, reason: 'rank_above_newcomer' }, rank);
+  }
+});
+
+t('unknown / absent rank fails closed (reason unknown_rank)', () => {
+  for (const rank of [undefined, null, '', 'wizard', 'helot']) {
+    assert.deepEqual(a.entitlementFor(rank), { entitled: false, reason: 'unknown_rank' }, String(rank));
+  }
+});
+
+console.log('\nkey loader (env wins; trimmed):');
+
+t('loadSharedGeminiKey returns the env key, trimmed', () => {
+  withEnv({ key: '  AIza-test-123  ' }, () => {
+    assert.equal(a.loadSharedGeminiKey(), 'AIza-test-123');
+    assert.equal(a.sharedGeminiKeyConfigured(), true);
+  });
+});
+
+t('not configured when env unset and no operator file (empty HOME)', () => {
+  withEnv({ key: null, emptyHome: true }, () => {
+    assert.equal(a.loadSharedGeminiKey(), null);
+    assert.equal(a.sharedGeminiKeyConfigured(), false);
+  });
+});
+
+console.log('\ndescribeArtKey (the GET /me/art-key payload, sans secret):');
+
+t('xenos + configured: entitled, configured, shared_key placeholder is null', () => {
+  withEnv({ key: 'AIza-shared' }, () => {
+    const d = a.describeArtKey({ rank: 'xenos' });
+    assert.equal(d.entitled, true);
+    assert.equal(d.configured, true);
+    assert.equal(d.reason, 'newcomer');
+    assert.equal(d.rank, 'xenos');
+    // The pure describe never embeds the secret — the route attaches it.
+    assert.equal(d.shared_key, null);
+  });
+});
+
+t('thetes: not entitled even when a key is configured (the withdraw signal)', () => {
+  withEnv({ key: 'AIza-shared' }, () => {
+    const d = a.describeArtKey({ rank: 'thetes' });
+    assert.equal(d.entitled, false);
+    assert.equal(d.reason, 'rank_above_newcomer');
+    assert.equal(d.configured, true);
+    assert.equal(d.shared_key, null);
+  });
+});
+
+t('xenos but unconfigured: entitled yet configured=false (sync no-ops)', () => {
+  withEnv({ key: null, emptyHome: true }, () => {
+    const d = a.describeArtKey({ rank: 'xenos' });
+    assert.equal(d.entitled, true);
+    assert.equal(d.configured, false);
+  });
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed === 0 ? 0 : 1);

package/tests/art_stage.mjs

@@ -0,0 +1,121 @@
+// tests/art_stage.mjs
+//
+// Hermetic unit coverage for scripts/gds/art-stage.js (#1067) — rebuild the atlas
+// + surface it on the builder's sandbox in one step. All deps (execFileSync, fs,
+// fetchImpl, resolvePreviewContext, log) are injected; NO real pipeline run, NO
+// network, NO systemd, NO real /workspace.
+//
+// Run:  node tests/art_stage.mjs   (also runs in the unit gate)
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const art = require('../scripts/gds/art-stage.js');
+
+let passed = 0, failed = 0;
+function t(name, fn) { try { fn(); passed++; console.log(`  PASS  ${name}`); } catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); } }
+async function ta(name, fn) { try { await fn(); passed++; console.log(`  PASS  ${name}`); } catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.stack || e.message}`); } }
+
+// ---------- affectedTiles ----------
+t('affectedTiles: explicit --tiles list is split verbatim', () => {
+  assert.deepEqual(art.affectedTiles('container_a container_b npc_vendor'), ['container_a', 'container_b', 'npc_vendor']);
+});
+t('affectedTiles: falls back to git status of public/assets/tiles', () => {
+  const execFileSync = (_cmd, _args) => ' M public/assets/tiles/atlas.json\n?? public/assets/tiles/container_a.png\n';
+  assert.deepEqual(art.affectedTiles('', { execFileSync, repoRoot: '/repo' }),
+    ['public/assets/tiles/atlas.json', 'public/assets/tiles/container_a.png']);
+});
+t('affectedTiles: git failure → empty list (never throws)', () => {
+  const execFileSync = () => { throw new Error('not a repo'); };
+  assert.deepEqual(art.affectedTiles('', { execFileSync }), []);
+});
+
+// ---------- copyAtlasToServed ----------
+t('copyAtlasToServed: no-op when the session checkout IS the served root', () => {
+  const r = art.copyAtlasToServed({ repoRoot: '/workspace', servedRoot: '/workspace' });
+  assert.equal(r.copied, false);
+});
+
+await ta('copyAtlasToServed: copies the tiles tree into a different served root', async () => {
+  const repo = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-art-repo-'));
+  const served = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-art-served-'));
+  fs.mkdirSync(path.join(repo, 'public/assets/tiles'), { recursive: true });
+  fs.writeFileSync(path.join(repo, 'public/assets/tiles', 'atlas-abc123.png'), 'PNGDATA');
+  const r = art.copyAtlasToServed({ repoRoot: repo, servedRoot: served });
+  assert.equal(r.copied, true);
+  assert.equal(fs.readFileSync(path.join(served, 'public/assets/tiles/atlas-abc123.png'), 'utf8'), 'PNGDATA');
+  fs.rmSync(repo, { recursive: true, force: true });
+  fs.rmSync(served, { recursive: true, force: true });
+});
+
+t('copyAtlasToServed: no served checkout → not copied (best-effort)', () => {
+  const r = art.copyAtlasToServed({ repoRoot: '/repo', servedRoot: '/nonexistent-served-xyz', fs: { existsSync: () => false } });
+  assert.equal(r.copied, false);
+});
+
+// ---------- main orchestration ----------
+function baseDeps(over = {}) {
+  const logs = [];
+  return {
+    logs,
+    log: (m) => logs.push(String(m)),
+    execFileSync: () => '', // build_tilesheet + git no-ops
+    fetchImpl: async () => ({ status: 200 }),
+    pollMs: 1, timeoutMs: 100,
+    repoRoot: '/workspace', servedRoot: '/workspace', // copy no-ops
+    ...over,
+  };
+}
+
+await ta('main: no sandbox here → rebuilds, reports no sandbox, not surfaced', async () => {
+  const deps = baseDeps({ resolvePreviewContext: () => null });
+  const r = await art.main([], deps);
+  assert.equal(r.surfaced, false);
+  assert.ok(deps.logs.some((l) => /No sandbox here/i.test(l)));
+});
+
+await ta('main: box context → restarts, waits healthy, prints the sandbox URL', async () => {
+  let restarted = false;
+  const deps = baseDeps({
+    resolvePreviewContext: () => ({ kind: 'box', url: 'https://sandbox-x.amazonprimea.com', healthUrl: 'http://127.0.0.1:3000/', restart: () => { restarted = true; } }),
+  });
+  const r = await art.main(['--tiles', 'container_a'], deps);
+  assert.equal(r.ok, true);
+  assert.equal(r.surfaced, true);
+  assert.equal(restarted, true);
+  assert.ok(deps.logs.some((l) => l.includes('https://sandbox-x.amazonprimea.com')));
+  assert.ok(deps.logs.some((l) => /container_a/.test(l)), 'affected tiles printed');
+});
+
+await ta('main: --no-build does NOT invoke build_tilesheet', async () => {
+  const calls = [];
+  const deps = baseDeps({
+    execFileSync: (cmd, args) => { calls.push([cmd, ...(args || [])].join(' ')); return ''; },
+    resolvePreviewContext: () => ({ kind: 'box', url: 'https://sandbox-x', healthUrl: 'http://127.0.0.1:3000/', restart: () => {} }),
+  });
+  await art.main(['--no-build'], deps);
+  assert.ok(!calls.some((c) => /build_tilesheet/.test(c)), 'build_tilesheet must be skipped under --no-build');
+});
+
+await ta('main: restart failure is fail-open (atlas rebuilt, surfaced:false, no throw)', async () => {
+  const deps = baseDeps({
+    resolvePreviewContext: () => ({ kind: 'box', url: 'https://sandbox-x', healthUrl: 'http://127.0.0.1:3000/', restart: () => { throw new Error('systemctl boom'); } }),
+  });
+  const r = await art.main(['--no-build'], deps);
+  assert.equal(r.ok, false);
+  assert.equal(r.surfaced, false);
+});
+
+await ta('main: quick-tunnel box (no URL) → rebuilt but not surfaced', async () => {
+  const deps = baseDeps({ resolvePreviewContext: () => ({ kind: 'box', url: null, healthUrl: 'http://127.0.0.1:3000/', restart: () => {} }) });
+  const r = await art.main(['--no-build'], deps);
+  assert.equal(r.surfaced, false);
+  assert.match(r.reason, /preview URL/);
+});
+
+console.log(`\nart_stage: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);