@bongos/core 1.19.1072 → 1.19.1074

package/scripts/gds/smoke-box.sh

@@ -1,150 +0,0 @@
-#!/usr/bin/env bash
-# Smoke test for the per-builder dev box lifecycle (ADR 0031 §2/§5, #598).
-#
-# Unlike the other GDS smokes, this one is HERMETIC — no live server, no DB, no
-# DigitalOcean account, no network. It verifies the decision core + the dry-run
-# contract that make the lifecycle safe to ship before a single live box exists:
-#
-#   1. tests/boxes.mjs — pure logic (rank gate, cost, idle/dormant selection,
-#      transition legality) + the DO client's dry-run/live contract.
-#   2. route-rank invariant — the three /box* routes classify to their TRUE gate
-#      (archon roster, any-builder own-read + heartbeat), no 'unknown' findings.
-#   3. modules load — boxes.js, do-api.js, routes/box.js, and routes.js (mount).
-#   4. box.js --help + a dry-run plan run without a DB (control-plane safety:
-#      `--apply` is required to touch anything; dry-run is inert).
-#
-# Run:  bash scripts/gds/smoke-box.sh
-set -euo pipefail
-
-cd "$(dirname "$0")/../.."
-
-step() { printf '\n\033[1;36m==> %s\033[0m\n' "$*"; }
-fail() { printf '\033[0;31m✖ %s\033[0m\n' "$*" >&2; exit 1; }
-
-step "1. pure-logic + DO-client unit test (tests/boxes.mjs)"
-node tests/boxes.mjs || fail "boxes.mjs unit test failed"
-
-step "1b. box-access decision core (#600 rank-gated source access)"
-# tests/box_access.mjs (23 assertions) — re-added under #674 (written+passing in
-# #600 but deferred by parallel-claim conflicts on tests/). Covers the PURE
-# source-access decisions (decideSourceAccess / reconcileSourceAccess /
-# cloneSpecForScope / boxCanHoldSource / STARTER_SPARSE_PATHS) the
-# GET /box/source-access route and `box.js reconcile` both consume.
-node tests/box_access.mjs || fail "box_access.mjs unit test failed"
-
-step "1b2. box-credential provider (#600 scoped credential issuance)"
-# Kept inline: box-credential.js has no dedicated unit file yet. These pin the
-# env-provider's configured/unconfigured, scope→token/repo, and separate-starter-
-# repo hard-boundary behaviour so credential issuance never ships unverified.
-node -e "
-const c = require('./modules/dev-box/box-credential.js');
-const assert = require('node:assert').strict;
-let n = 0; const ok = (name, fn) => { fn(); n++; };
-ok('unconfigured→configured:false', () => assert.equal(c.makeEnvCredentialProvider({}).issue('full',{nowMs:0}).configured,false));
-ok('configured full→token+url', () => { const r=c.makeEnvCredentialProvider({BOX_SOURCE_REPO_URL:'u',BOX_SOURCE_FULL_TOKEN:'t'}).issue('full',{nowMs:0}); assert.equal(r.configured,true); assert.equal(r.token,'t'); });
-ok('starter falls back to full token', () => assert.equal(c.makeEnvCredentialProvider({BOX_SOURCE_REPO_URL:'u',BOX_SOURCE_FULL_TOKEN:'t'}).issue('starter',{nowMs:0}).token,'t'));
-ok('separate starter repo→hard-boundary flag', () => { const r=c.makeEnvCredentialProvider({BOX_SOURCE_REPO_URL:'u',BOX_SOURCE_FULL_TOKEN:'t',BOX_SOURCE_STARTER_REPO_URL:'s',BOX_SOURCE_STARTER_TOKEN:'st'}).issue('starter',{nowMs:0}); assert.equal(r.repoUrl,'s'); assert.equal(r.separateStarterRepo,true); });
-console.log('  ' + n + ' box-credential provider assertions passed');
-" || fail "box-credential provider failed"
-
-step "1c. onboarding module — SSH-key validation + renderers (#685, tests/box_onboard.mjs)"
-node tests/box_onboard.mjs || fail "box_onboard.mjs unit test failed"
-
-step "1c2. named-tunnel CF client — dry-run/live contract + ensure/teardown (#771, tests/cf_tunnel.mjs)"
-node tests/cf_tunnel.mjs || fail "cf_tunnel.mjs unit test failed"
-
-step "1d. end-to-end — real box-connect.sh + box-authorized-keys-fetch.sh vs a stub server (#685)"
-# Runs the GENUINE shell scripts against the real route handlers (stubbed DB):
-# key-gen -> register -> install settings, and the box-side authkeys sync + the
-# 403 clawback. Needs bash + curl + ssh-keygen (present on macOS + CI ubuntu).
-if command -v ssh-keygen >/dev/null 2>&1; then
-  node tests/box_connect_e2e.mjs || fail "box_connect_e2e.mjs end-to-end failed"
-else
-  echo "  (skipped — ssh-keygen not available)"
-fi
-
-step "1e. PowerShell bootstrap parses (#685) — best-effort, skipped where pwsh is absent"
-# box-connect.ps1 has no behavioral e2e (the harness is bash-only; the empty-
-# passphrase + BOM-less-write fixes rest on review). This at least catches gross
-# syntax errors on a pwsh-equipped machine (CI / a Windows runner); it no-ops on
-# a stock macOS/Linux dev box without PowerShell.
-if command -v pwsh >/dev/null 2>&1; then
-  pwsh -NoProfile -Command '$ErrorActionPreference="Stop"; $null=[System.Management.Automation.Language.Parser]::ParseFile((Resolve-Path infra/box-connect.ps1), [ref]$null, [ref]$null); Write-Output "  box-connect.ps1 parses"' \
-    || fail "box-connect.ps1 failed to parse under pwsh"
-else
-  echo "  (skipped — pwsh not installed; box-connect.ps1 behavior rests on review)"
-fi
-
-step "2. route-rank invariant — /box* routes classify to their true gate"
-node -e "
-const rc = require('./src/bongos/route-rank-check.js');
-const res = rc.checkRouteRanks();
-if (res.hardFail) { console.error('route-rank HARD FAIL'); process.exit(1); }
-const mine = res.routes.filter(r => r.file.endsWith('routes/box.js'));
-const want = {
-  'GET /boxes':'archon', 'GET /box/me':'any-builder', 'GET /box/source-access':'any-builder',
-  'POST /box/heartbeat':'any-builder',
-  // #685 onboarding surface
-  'POST /box/ssh-key':'any-builder', 'GET /box/ssh-key':'any-builder', 'DELETE /box/ssh-key/:id':'any-builder',
-  'GET /box/authorized-keys':'any-builder', 'GET /box/managed-settings':'any-builder',
-  // #701 onboarding middleware (auto-provision + wake-on-connect) + #760 terminal (ADR 0038)
-  'POST /box/ensure':'any-builder', 'GET /box/terminal':'any-builder', 'POST /box/terminal':'any-builder',
-  'GET /box/connect':'public', 'GET /box/connect.sh':'public', 'GET /box/connect.ps1':'public',
-};
-let bad = 0;
-for (const [key, rank] of Object.entries(want)) {
-  const got = (mine.find(r => r.key === key) || {}).rank;
-  if (got !== rank) { console.error('  MISMATCH ' + key + ': want ' + rank + ' got ' + got); bad++; }
-  else console.log('  ok ' + key + ' -> ' + rank);
-}
-process.exit(bad === 0 ? 0 : 1);
-" || fail "route-rank classification wrong"
-
-step "3. modules load cleanly (incl. the routes.js mount edit)"
-node -e "
-require('./modules/dev-box/boxes.js');
-require('./modules/dev-box/box-access.js');
-require('./modules/dev-box/box-credential.js');
-require('./modules/dev-box/box-onboard.js');
-require('./scripts/gds/do-api.js');
-require('./scripts/gds/cf-tunnel.js');
-require('./modules/dev-box/routes/box.js');
-require('./src/bongos/db.js');
-require('./src/bongos/routes.js');
-console.log('  all modules loaded');
-" || fail "module load failed"
-
-step "4. CLI is DB-free for --help (control-plane safety); reconcile + onboard registered"
-node scripts/gds/box.js --help | grep -q 'reconcile' || fail "box.js reconcile subcommand missing from help"
-node scripts/gds/box.js --help | grep -q 'onboard'   || fail "box.js onboard subcommand missing from help (#685)"
-node scripts/gds/box.js --help | grep -q 'run-intents' || fail "box.js run-intents subcommand missing from help (#701)"
-echo "  box.js --help ok (reconcile + onboard + run-intents present)"
-
-step "5. cloud-init carries the box scripts as valid base64 (#600 source + #685 authkeys)"
-node -e "
-const fs = require('fs');
-const o = require('./modules/dev-box/box-onboard.js');
-const raw = fs.readFileSync('infra/builder-box-cloud-init.yaml','utf8');
-const inject = (name) => {
-  const script = fs.readFileSync('infra/' + name,'utf8');
-  const b64 = Buffer.from(script,'utf8').toString('base64');
-  if (Buffer.from(b64,'base64').toString('utf8') !== script) { console.error('  ' + name + ' b64 does not round-trip'); process.exit(1); }
-  return b64;
-};
-const block = o.wrapManagedBlock([{ public_key: 'ssh-ed25519 AAAA', label: 'laptop' }]);
-const rendered = raw
-  .replace(/__REPO_URL__/g,'')
-  .replace(/__BOX_SOURCE_FETCH_B64__/g, inject('box-source-fetch.sh'))
-  .replace(/__BOX_AUTHKEYS_FETCH_B64__/g, inject('box-authorized-keys-fetch.sh'))
-  .replace(/__BUILDER_AUTHORIZED_KEYS_B64__/g, Buffer.from(block,'utf8').toString('base64'))
-  .replace(/__BOX_ENV_B64__/g, Buffer.from('','utf8').toString('base64'));
-const leftover = rendered.match(/__[A-Z_]+__/g);
-if (leftover) { console.error('  placeholders not substituted: ' + leftover.join(', ')); process.exit(1); }
-if (!raw.includes('encoding: b64')) { console.error('  write_files missing encoding: b64'); process.exit(1); }
-if (!raw.includes('/root/.ssh/otb-authorized-keys.block')) { console.error('  baked authorized_keys block not wired'); process.exit(1); }
-if (!raw.includes('box-authorized-keys-fetch.sh')) { console.error('  authkeys-fetch cron not wired'); process.exit(1); }
-if (!raw.includes('/etc/otb/box.env')) { console.error('  named-tunnel box.env not wired (#771)'); process.exit(1); }
-console.log('  source-fetch + authkeys-fetch scripts inject + round-trip; baked-keys block + box.env + crons wired');
-" || fail "cloud-init injection broken"
-
-printf '\n\033[1;32m✓ box-lifecycle smoke passed\033[0m\n'

package/scripts/gds/tree-preflight.js

@@ -1,241 +0,0 @@
-'use strict';
-
-// scripts/gds/tree-preflight.js — does this checkout contain the code the command
-// is about to require? (task 1003098)
-//
-// THE FAILURE THIS REPLACES. On a TASK-SCOPED dev box — a supported, server-driven
-// configuration — `GET /box/source-access` returns a sparse path list that carries
-// `scripts`, `src/bongos`, `tests`, `clients`, `config` and NOT `modules/`, except
-// the one module the claimed task is scoped to. So the platform itself produces a
-// checkout in which its own entry-point commands cannot run, and they said so like
-// this:
-//
-//   $ node scripts/gds/ship.js
-//   Error: Cannot find module '../../modules/lifecycle/ship-preflight'
-//   Require stack: scripts/gds/ship-state.js
-//
-// A raw stack trace, naming ONE missing thing. Fix that one and the next run names
-// the next — the filer lost a whole session to guess-read-fix-repeat, and their
-// workaround (`git sparse-checkout disable` plus commenting out the re-scope cron)
-// is not something a builder should have to discover.
-//
-// ENUMERATION IS THE WHOLE POINT. Node's loader is lazy by construction: it fails
-// at the first unresolvable specifier and cannot tell you about the second, because
-// it never got there. That is correct behaviour for a module loader and useless as
-// a diagnosis. This runs BEFORE the first such require and reports every missing
-// requirement it can see in ONE message.
-//
-// THE REQUIRED LIST IS COMPUTED, NEVER DECLARED. A hand-kept list of "what ship.js
-// needs" is a second copy of the require graph, and it would be wrong within a
-// month — ship.js alone fans out across sixteen ship-*.js phase files. So the
-// preflight WALKS the graph the same way the loader would: read the entry file,
-// find its `require('./x')` siblings, follow them, and collect every
-// `require('../../modules/...')` it passes. Pure string work over the file system;
-// nothing is executed, so a missing module cannot throw during the check that
-// exists to report it.
-//
-// WHY IT DOES NOT SIMPLY TRY/CATCH EACH REQUIRE. Individual guards are what the
-// codebase already does where a module is genuinely OPTIONAL (context-pack.js's
-// classifier, cli-lib.js's reward policy) and they are right for that: the command
-// still works, slightly diminished. These requires are not optional — ship.js
-// cannot ship without `modules/lifecycle/ship-preflight`. Wrapping them would turn
-// a loud failure into a confusing one.
-//
-// PURE + INJECTED (`readFile`, `exists`) so the whole thing is testable with a fake
-// file system and no box — which is the layer task 1003098 asks for the test at.
-
-const fsMod = require('node:fs');
-const pathMod = require('node:path');
-
-const REPO_ROOT = pathMod.resolve(__dirname, '..', '..');
-
-// A require of this repo's OWN module code, which is what a scoped checkout drops.
-// Matches the two spellings the CLI uses; the quote style is captured so a require
-// written with double quotes is not silently invisible to the walk.
-const MODULE_REQUIRE_RE = /require\(\s*['"](\.\.\/\.\.\/modules\/[^'"]+)['"]\s*\)/g;
-// A sibling require inside scripts/gds/ — the edges the walk follows.
-const LOCAL_REQUIRE_RE = /require\(\s*['"](\.\/[^'"]+)['"]\s*\)/g;
-
-// Comments are stripped before scanning. A header that QUOTES a require to explain
-// why it was removed would otherwise be walked as a live edge — the defect filed as
-// task 1003832 against a test that scanned raw source, and one this file would hit
-// immediately, because its own header above quotes the exact failing require.
-function stripComments(src) {
-  return String(src)
-    .replace(/\/\*[\s\S]*?\*\//g, ' ')
-    .replace(/^\s*\/\/.*$/gm, ' ');
-}
-
-// Is the character at `index` inside a try{} block?
-//
-// THE DISTINCTION THIS DRAWS IS THE WHOLE CORRECTNESS OF THE PREFLIGHT. Several of
-// the CLI's module requires are deliberately guarded — context-pack.js's classifier
-// and cli-lib.js's reward policy both sit in a try and fall back honestly, so those
-// commands RUN on a scoped box. Reporting them as missing requirements would refuse
-// a command that works, which is a worse failure than the one being fixed: a builder
-// who could have shipped is told they cannot.
-//
-// A brace walk, not a parser — this repo ships none (the route-rank-check /
-// exec-path-guard precedent). It tracks a stack of block kinds and answers whether
-// any enclosing block was opened by `try`. Comments are already stripped by the
-// caller; string and regex literals containing braces are the known blind spot, and
-// the failure direction is benign: a miscount can only mis-scope a block, and the
-// classification is proved against the real files by tests/tree_preflight.mjs, which
-// pins that start.js's requires read optional and ship.js's read required.
-function insideTry(src, index) {
-  const stack = [];
-  for (let i = 0; i < index && i < src.length; i++) {
-    const c = src[i];
-    if (c === '{') {
-      // Look back past whitespace for the keyword that opened this block.
-      const before = src.slice(Math.max(0, i - 200), i);
-      stack.push(/\btry\s*$/.test(before) ? 'try' : 'block');
-    } else if (c === '}') {
-      stack.pop();
-    }
-  }
-  return stack.includes('try');
-}
-
-function matchAll(src, re) {
-  const out = [];
-  let m;
-  re.lastIndex = 0;
-  while ((m = re.exec(src)) !== null) out.push({ spec: m[1], index: m.index });
-  return out;
-}
-
-// Resolve a relative specifier the way require would, to a repo-relative posix path.
-function resolveRel(fromFile, spec, { root = REPO_ROOT } = {}) {
-  const abs = pathMod.resolve(pathMod.dirname(fromFile), spec);
-  const rel = pathMod.relative(root, abs).split(pathMod.sep).join('/');
-  return rel;
-}
-
-// Add the `.js` a bare specifier omits. Only ever appended — a spec that already
-// names an extension is left exactly as written, so a `.json` require still points
-// at the file it names.
-function withJsExt(rel) {
-  return /\.[a-z]+$/i.test(rel) ? rel : `${rel}.js`;
-}
-
-/**
- * Every module-code path the entry point's require graph reaches. PURE.
- *
- * Follows `./sibling` edges inside scripts/gds/ transitively and collects the
- * `../../modules/...` leaves. A file it cannot read is skipped rather than thrown
- * on: this runs on a checkout that is by definition incomplete, and a preflight
- * that crashes while diagnosing a partial tree is worse than the trace it replaces.
- *
- * @returns {string[]} repo-relative posix paths, deduped, stable order
- */
-function requiredModulePaths(entryFile, { readFile, root = REPO_ROOT } = {}) {
-  const read = readFile || ((f) => fsMod.readFileSync(f, 'utf8'));
-  const seen = new Set();
-  const found = new Set();
-  const queue = [pathMod.resolve(entryFile)];
-
-  while (queue.length) {
-    const file = queue.shift();
-    if (seen.has(file)) continue;
-    seen.add(file);
-    let src;
-    try { src = stripComments(read(file)); } catch (_) { continue; }
-
-    for (const { spec, index } of matchAll(src, MODULE_REQUIRE_RE)) {
-      // A guarded require is not a requirement — see insideTry.
-      if (insideTry(src, index)) continue;
-      found.add(withJsExt(resolveRel(file, spec, { root })));
-    }
-    for (const { spec } of matchAll(src, LOCAL_REQUIRE_RE)) {
-      const abs = pathMod.resolve(pathMod.dirname(file), spec);
-      queue.push(/\.[a-z]+$/i.test(abs) ? abs : `${abs}.js`);
-    }
-  }
-  return [...found].sort();
-}
-
-/**
- * Which of those paths are not on disk. PURE. Returns repo-relative paths.
- */
-function missingPaths(paths, { exists, root = REPO_ROOT } = {}) {
-  const has = exists || ((rel) => fsMod.existsSync(pathMod.join(root, rel)));
-  return paths.filter((rel) => !has(rel));
-}
-
-// The distinct top-level module directories a set of missing paths falls under —
-// what the builder actually has to get back, and what box-sync speaks in.
-function missingModuleDirs(paths) {
-  const dirs = new Set();
-  for (const p of paths) {
-    const m = String(p).match(/^modules\/([^/]+)\//);
-    if (m) dirs.add(`modules/${m[1]}`);
-  }
-  return [...dirs].sort();
-}
-
-/**
- * ONE actionable message, or null when the tree is complete. PURE.
- *
- * Names the CONDITION (a scoped checkout, not a broken install), EVERY missing
- * requirement, and BOTH remedies — re-scope, or take the whole tree. Two are given
- * because they solve different problems: box-sync re-reads the server's path list
- * and is right when the claim moved, while sparse-checkout disable is the escape
- * hatch when the scope itself is what is wrong.
- *
- * It does not promise which one applies, because that is exactly what this layer
- * cannot know — it can see that the code is absent, not why.
- */
-function preflightMessage(missing, { command = 'this command' } = {}) {
-  if (!missing || !missing.length) return null;
-  const dirs = missingModuleDirs(missing);
-  const lines = [
-    `${command} needs code this checkout does not contain.`,
-    '',
-    `Missing (${missing.length}):`,
-    ...missing.map((p) => `  - ${p}`),
-    '',
-    'This is normal on a TASK-SCOPED dev box: the box carries scripts/, src/bongos/,',
-    'tests/ and the module your claimed task is scoped to — not every module. It is',
-    'not a broken install, and re-running will not fix it.',
-    '',
-    'Fix it with ONE of:',
-    '  node scripts/gds/box-sync.js      re-scope this box to what you hold now',
-    '  git sparse-checkout disable       take the whole tree instead',
-  ];
-  if (dirs.length) {
-    lines.splice(lines.indexOf('') + 1, 0, `Whole directories absent: ${dirs.join(', ')}`);
-  }
-  return lines.join('\n');
-}
-
-/**
- * The one call an entry point makes. Returns null when the tree is complete, or the
- * message to print before exiting non-zero.
- *
- * Every dependency is injectable so the test drives it with a fake file system —
- * and so a failure inside the preflight can never be the reason a command dies.
- */
-function checkTree(entryFile, { readFile, exists, root = REPO_ROOT, command } = {}) {
-  try {
-    const required = requiredModulePaths(entryFile, { readFile, root });
-    const missing = missingPaths(required, { exists, root });
-    return preflightMessage(missing, { command: command || pathMod.basename(entryFile) });
-  } catch (_) {
-    // A preflight that throws is a preflight that replaced a clear stack trace with
-    // a worse one. Silence here means the command proceeds and fails the old way,
-    // which is the outcome this file improves on — never the one it causes.
-    return null;
-  }
-}
-
-module.exports = {
-  REPO_ROOT,
-  requiredModulePaths,
-  missingPaths,
-  missingModuleDirs,
-  preflightMessage,
-  checkTree,
-  stripComments,
-  insideTry,
-};

package/src/bongos/app-pair.js

@@ -1,172 +0,0 @@
-// src/bongos/app-pair.js — in-memory pairing store for the Dev Box desktop app
-// (#904, ADR 0045).
-//
-// The desktop app needs a browser-clicks-only sign-in (Lars's UI-first rule:
-// no terminal, no paste, no typing codes). GitHub's device flow makes the
-// builder hand-type an 8-char code; the web OAuth flow can't hand a token to a
-// local process (safeReturnTo deliberately rejects loopback targets). So the
-// app pairs against the GDS itself:
-//
-//   1. app   → POST /auth/app-pair/start            → { pair_code, poll_token }
-//   2. app   → opens the browser at /builders/pair?code=<pair_code>
-//   3. human → already signed into the hall (or signs in via the normal web
-//              flow) and clicks ONE Approve button
-//   4. server (at approve, cookie-gated like /auth/cli-token/issue) mints a
-//      source='cli' session and parks it on the pairing entry
-//   5. app   → POST /auth/app-pair/poll { poll_token } → { token } (ONCE)
-//
-// Two credentials with distinct trust:
-//   - pair_code  — short, human-visible, shown in the browser URL. It can only
-//     APPROVE (and only from an authenticated browser cookie session); it can
-//     never read the minted token.
-//   - poll_token — long, secret, never leaves the app↔server channel. It is
-//     the ONLY credential that can collect the minted session token, and the
-//     token is handed over exactly once, then the entry is destroyed.
-//
-// Storage is an in-memory Map, same posture as the GitHub device-flow's
-// pending map in src/bongos/auth.js — single Node process (ADR 0006), short TTL,
-// a restart simply voids in-flight pairings and the app retries. No migration,
-// no new table, nothing durable to leak.
-
-const crypto = require('node:crypto');
-
-// Unambiguous code alphabet (Crockford-ish: no 0/O, 1/I/L, U/V confusion).
-const CODE_ALPHABET = 'ABCDEFGHJKMNPQRSTWXYZ23456789';
-const CODE_GROUPS = 2;          // XXXX-XXXX
-const CODE_GROUP_LEN = 4;
-
-const DEFAULT_TTL_MS = 10 * 60 * 1000;   // mirrors the OAuth state cookies
-const DEFAULT_MAX_PENDING = 500;         // memory cap; start() refuses beyond
-const POLL_INTERVAL_S = 5;               // suggested client poll cadence
-
-function randomPairCode() {
-  const groups = [];
-  for (let g = 0; g < CODE_GROUPS; g++) {
-    let s = '';
-    for (let i = 0; i < CODE_GROUP_LEN; i++) {
-      s += CODE_ALPHABET[crypto.randomInt(CODE_ALPHABET.length)];
-    }
-    groups.push(s);
-  }
-  return groups.join('-');
-}
-
-// Normalize what a human/browser hands back: trim, uppercase, drop spaces,
-// tolerate a missing dash.
-function normalizeCode(raw) {
-  if (typeof raw !== 'string') return null;
-  const s = raw.trim().toUpperCase().replace(/[\s-]+/g, '');
-  if (s.length !== CODE_GROUPS * CODE_GROUP_LEN) return null;
-  if (![...s].every((c) => CODE_ALPHABET.includes(c))) return null;
-  return `${s.slice(0, CODE_GROUP_LEN)}-${s.slice(CODE_GROUP_LEN)}`;
-}
-
-// createPairStore({ nowMs, ttlMs, maxPending }) — nowMs injectable for tests.
-function createPairStore(opts = {}) {
-  const nowMs = opts.nowMs || (() => Date.now());
-  const ttlMs = opts.ttlMs ?? DEFAULT_TTL_MS;
-  const maxPending = opts.maxPending ?? DEFAULT_MAX_PENDING;
-
-  const byCode = new Map();   // pair_code  → entry
-  const byPoll = new Map();   // poll_token → entry
-
-  function destroy(entry) {
-    byCode.delete(entry.pairCode);
-    byPoll.delete(entry.pollToken);
-  }
-
-  function expired(entry) {
-    return nowMs() >= entry.expiresAt;
-  }
-
-  // Lazy purge — called on every public op so the maps never accumulate.
-  function purge() {
-    for (const entry of byCode.values()) {
-      if (expired(entry)) destroy(entry);
-    }
-  }
-
-  return {
-    // → { pairCode, pollToken, expiresIn, interval } | { error: 'busy' }
-    start({ deviceName, platform } = {}) {
-      purge();
-      if (byCode.size >= maxPending) return { error: 'busy' };
-      let pairCode = randomPairCode();
-      while (byCode.has(pairCode)) pairCode = randomPairCode(); // vanishing odds
-      const entry = {
-        pairCode,
-        pollToken: crypto.randomBytes(32).toString('hex'),
-        deviceName: String(deviceName || 'Dev Box app').slice(0, 80),
-        platform: String(platform || 'unknown').slice(0, 20),
-        createdAt: nowMs(),
-        expiresAt: nowMs() + ttlMs,
-        status: 'pending',          // pending → approved (→ delivered = gone)
-        grant: null,                // set at approve: { token, builder, expires_at }
-      };
-      byCode.set(entry.pairCode, entry);
-      byPoll.set(entry.pollToken, entry);
-      return {
-        pairCode: entry.pairCode,
-        pollToken: entry.pollToken,
-        expiresIn: Math.floor(ttlMs / 1000),
-        interval: POLL_INTERVAL_S,
-      };
-    },
-
-    // What the approve page shows BEFORE the human clicks. null = unknown/expired
-    // (indistinguishable on purpose — no oracle for code guessing).
-    info(rawCode) {
-      purge();
-      const code = normalizeCode(rawCode);
-      const entry = code ? byCode.get(code) : null;
-      if (!entry || expired(entry)) return null;
-      return {
-        pairCode: entry.pairCode,
-        deviceName: entry.deviceName,
-        platform: entry.platform,
-        createdAt: entry.createdAt,
-        status: entry.status,
-      };
-    },
-
-    // Park the minted grant on a pending entry. The route mints the session
-    // (it holds req.builder); the store only records the handover.
-    // → { ok: true } | { error: 'not_found' | 'already_approved' }
-    approve(rawCode, grant) {
-      purge();
-      const code = normalizeCode(rawCode);
-      const entry = code ? byCode.get(code) : null;
-      if (!entry || expired(entry)) return { error: 'not_found' };
-      if (entry.status !== 'pending') return { error: 'already_approved' };
-      entry.status = 'approved';
-      entry.grant = grant;
-      return { ok: true };
-    },
-
-    // → { status: 'pending', interval }
-    // | { status: 'approved', grant }   (exactly once; entry destroyed)
-    // | { status: 'expired' }           (also for unknown poll tokens — no oracle)
-    poll(pollToken) {
-      purge();
-      const entry = typeof pollToken === 'string' ? byPoll.get(pollToken) : null;
-      if (!entry || expired(entry)) {
-        if (entry) destroy(entry);
-        return { status: 'expired' };
-      }
-      if (entry.status === 'approved') {
-        const grant = entry.grant;
-        destroy(entry); // one-shot delivery
-        return { status: 'approved', grant };
-      }
-      return { status: 'pending', interval: POLL_INTERVAL_S };
-    },
-
-    // test/ops introspection only
-    _size() { return byCode.size; },
-  };
-}
-
-// Singleton the routes use. Tests build their own stores with injected clocks.
-const pairStore = createPairStore();
-
-module.exports = { createPairStore, normalizeCode, pairStore };