@bongos/core 1.19.1033 → 1.19.1034

package/tests/dev_windows.mjs

@@ -0,0 +1,324 @@
+// tests/dev_windows.mjs — `bongos dev` on Windows (task 1002707), proven on any OS.
+//
+// Two layers:
+//   1. dev-lib's WINDOWS decisions, called with platform:'win32' and injected
+//      env / fs / where, so every Windows path is exercised on a Mac or Linux CI box.
+//   2. dev.js's wiring of those decisions (npm install, preflight, migrate, createdb),
+//      driven with process.platform STUBBED to 'win32' and child_process.spawnSync +
+//      fs.existsSync/readdirSync STUBBED. Nothing real is spawned, installed or read.
+//
+// Each case fails on the pre-fix code: a plain `npm` spawn with no shell, a WSL
+// bash.exe accepted for migrations, a backslash migrate.sh path, the Windows login
+// name as the Postgres role, and Homebrew/apt-get help printed to a Windows owner.
+//
+// Run:  node tests/dev_windows.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const cp = require('node:child_process');
+const fs = require('node:fs');
+const lib = require('../scripts/gds/dev-lib.js');
+const devCli = require('../scripts/gds/dev.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}`); }
+}
+
+const PF = 'C:\\Program Files';
+const GIT_BASH = 'C:\\Program Files\\Git\\bin\\bash.exe';
+const WSL_BASH = 'C:\\Windows\\System32\\bash.exe';
+const PG16_BIN = 'C:\\Program Files\\PostgreSQL\\16\\bin';
+const lower = (s) => String(s).toLowerCase();
+// A fake existsSync over an exact (case-insensitive, Windows-style) path set.
+const existsIn = (...paths) => (p) => paths.map(lower).includes(lower(p));
+
+// ======================= 1. dev-lib, platform:'win32' =======================
+
+t('npmInvocation: Windows runs npm-cli.js through node, no shell', () => {
+  const inv = lib.npmInvocation(['ci'], {
+    platform: 'win32', execPath: 'C:\\Program Files\\nodejs\\node.exe',
+    exists: existsIn('C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js'),
+  });
+  assert.equal(inv.cmd, 'C:\\Program Files\\nodejs\\node.exe');
+  assert.deepEqual(inv.args, ['C:\\Program Files\\nodejs\\node_modules\\npm\\bin\\npm-cli.js', 'ci']);
+  assert.equal(inv.shell, false);
+});
+
+t('npmInvocation: Windows without npm-cli.js falls back to the .cmd shim through a shell, as one string', () => {
+  const inv = lib.npmInvocation(['install'], { platform: 'win32', execPath: 'C:\\n\\node.exe', exists: () => false });
+  assert.equal(inv.shell, true);
+  assert.equal(inv.cmd, 'npm install');
+  assert.deepEqual(inv.args, []); // no args array beside shell:true (DEP0190)
+});
+
+t('npmInvocation: Mac/Linux keep the plain spawn', () => {
+  for (const platform of ['darwin', 'linux']) {
+    assert.deepEqual(lib.npmInvocation(['ci'], { platform, exists: () => true }), { cmd: 'npm', args: ['ci'], shell: false });
+  }
+});
+
+t('isWslBashLauncher: System32 / Sysnative / WindowsApps bash are WSL, Git Bash is not', () => {
+  assert.equal(lib.isWslBashLauncher(WSL_BASH), true);
+  assert.equal(lib.isWslBashLauncher('C:\\WINDOWS\\Sysnative\\bash.exe'), true);
+  assert.equal(lib.isWslBashLauncher('C:\\Users\\a\\AppData\\Local\\Microsoft\\WindowsApps\\bash.exe'), true);
+  assert.equal(lib.isWslBashLauncher(GIT_BASH), false);
+  assert.equal(lib.isWslBashLauncher('C:\\Program Files\\Git\\usr\\bin\\bash.exe'), false);
+});
+
+t('resolveBash: Windows finds Git Bash in Program Files and never picks WSL’s bash', () => {
+  const r = lib.resolveBash({
+    platform: 'win32', env: { ProgramFiles: PF },
+    whereAll: (b) => (b === 'bash' ? [WSL_BASH] : []),
+    exists: existsIn(GIT_BASH, WSL_BASH),
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.bin, GIT_BASH);
+});
+
+t('resolveBash: Windows prefers the Git Bash this terminal runs in (EXEPATH)', () => {
+  const own = 'D:\\tools\\Git\\bin\\bash.exe';
+  const r = lib.resolveBash({ platform: 'win32', env: { EXEPATH: 'D:\\tools\\Git\\bin', ProgramFiles: PF }, exists: existsIn(own, GIT_BASH) });
+  assert.equal(r.bin, own);
+});
+
+t('resolveBash: Windows finds Git Bash beside the git on PATH (custom install folder)', () => {
+  const custom = 'E:\\Apps\\Git\\bin\\bash.exe';
+  const r = lib.resolveBash({
+    platform: 'win32', env: {},
+    whereAll: (b) => (b === 'git' ? ['E:\\Apps\\Git\\cmd\\git.exe'] : []),
+    exists: existsIn(custom),
+  });
+  assert.equal(r.ok, true);
+  assert.equal(r.bin, custom);
+});
+
+t('resolveBash: Windows env names are read case-insensitively (PROGRAMFILES)', () => {
+  const r = lib.resolveBash({ platform: 'win32', env: { PROGRAMFILES: PF }, exists: existsIn(GIT_BASH) });
+  assert.equal(r.bin, GIT_BASH);
+});
+
+t('resolveBash: a WSL-only machine is refused and says so', () => {
+  const r = lib.resolveBash({ platform: 'win32', env: { ProgramFiles: PF }, whereAll: (b) => (b === 'bash' ? [WSL_BASH] : []), exists: existsIn(WSL_BASH) });
+  assert.equal(r.ok, false);
+  assert.equal(r.wslOnly, true);
+});
+
+t('resolveBash: Mac/Linux still use `bash` from PATH', () => {
+  assert.deepEqual(lib.resolveBash({ platform: 'linux', has: (b) => b === 'bash' }), { ok: true, bin: 'bash', source: 'PATH' });
+  assert.equal(lib.resolveBash({ platform: 'darwin', has: () => false }).ok, false);
+});
+
+t('bashScriptPath: Windows gets forward slashes (bash dirname splits on / only)', () => {
+  assert.equal(lib.bashScriptPath('C:\\x\\core\\scripts\\migrate.sh', 'win32'), 'C:/x/core/scripts/migrate.sh');
+  assert.equal(lib.bashScriptPath('/x/core/scripts/migrate.sh', 'linux'), '/x/core/scripts/migrate.sh');
+});
+
+t('windowsPgInstalls: finds installer folders newest-first, deduped, psql.exe required', () => {
+  const dirs = { [lower(`${PF}\\PostgreSQL`)]: ['15', '16', 'data-backup', '17'] };
+  const installs = lib.windowsPgInstalls({
+    env: { ProgramFiles: PF, ProgramW6432: PF }, // the same folder twice on 64-bit Windows
+    readdir: (d) => { const v = dirs[lower(d)]; if (!v) throw new Error('ENOENT'); return v; },
+    exists: existsIn(`${PF}\\PostgreSQL\\15\\bin\\psql.exe`, `${PF}\\PostgreSQL\\16\\bin\\psql.exe`), // 17 has no psql.exe
+  });
+  assert.deepEqual(installs.map((i) => i.bin), [PG16_BIN, `${PF}\\PostgreSQL\\15\\bin`]);
+  assert.equal(installs[0].service, 'postgresql-x64-16');
+});
+
+t('pgStartPlan: Windows tries each installed version’s Windows service', () => {
+  const plan = lib.pgStartPlan({ platform: 'win32', env: {}, pgInstalls: [{ service: 'postgresql-x64-16' }, { service: 'postgresql-x64-15' }] });
+  assert.deepEqual(plan.map((s) => [s.cmd, ...s.args]), [['net', 'start', 'postgresql-x64-16'], ['net', 'start', 'postgresql-x64-15']]);
+  assert.deepEqual(lib.pgStartPlan({ platform: 'win32', env: {} }), []);
+});
+
+t('pgClientArgs: Windows adds -w (never prompt) except for pg_isready', () => {
+  const params = { pgHost: 'localhost', pgUser: 'postgres' };
+  assert.deepEqual(lib.pgClientArgs(params, { platform: 'win32' }), ['-h', 'localhost', '-U', 'postgres', '-w']);
+  assert.deepEqual(lib.pgClientArgs(params, { platform: 'win32', forReady: true }), ['-h', 'localhost', '-U', 'postgres']);
+  assert.deepEqual(lib.pgClientArgs(params, { platform: 'darwin' }), ['-h', 'localhost', '-U', 'postgres']);
+});
+
+t('resolveRunParams: Windows defaults the Postgres role to `postgres`; PGUSER still wins', () => {
+  const f = { readFileSync: () => { throw new Error('ENOENT'); } };
+  const base = { instanceRoot: 'C:\\Users\\Lars\\proj', coreRoot: 'C:\\core', f, userInfo: () => ({ username: 'Lars' }), argv: [] };
+  assert.equal(lib.resolveRunParams({ ...base, env: {}, platform: 'win32' }).pgUser, 'postgres');
+  assert.equal(lib.resolveRunParams({ ...base, env: { PGUSER: 'me' }, platform: 'win32' }).pgUser, 'me');
+  assert.equal(lib.resolveRunParams({ ...base, env: {}, platform: 'darwin' }).pgUser, 'Lars');
+});
+
+t('pgInstallHint / pgStartHint: Windows steps for Windows, unchanged elsewhere', () => {
+  const win = lib.pgInstallHint('win32').join('\n');
+  assert.match(win, /postgresql\.org\/download\/windows/);
+  assert.match(win, /PGPASSWORD/);
+  assert.match(win, /self-host\.md/);           // Docker named as the fallback
+  assert.doesNotMatch(win, /brew|apt-get/);
+  assert.match(lib.pgInstallHint('darwin').join('\n'), /brew install postgresql@16/);
+  assert.match(lib.pgInstallHint('linux').join('\n'), /apt-get/);
+  const start = lib.pgStartHint('win32', { pgInstalls: [{ service: 'postgresql-x64-17' }] }).join('\n');
+  assert.match(start, /services\.msc/);
+  assert.match(start, /Start-Service postgresql-x64-17/);
+  assert.match(lib.pgStartHint('linux').join('\n'), /sudo service postgresql start/);
+});
+
+t('pgAuthHint: only on Windows, only for an authentication refusal', () => {
+  assert.match(lib.pgAuthHint('win32', 'fe_sendauth: no password supplied').join('\n'), /PGPASSWORD/);
+  assert.match(lib.pgAuthHint('win32', 'password authentication failed for user "postgres"').join('\n'), /"postgres"/);
+  assert.deepEqual(lib.pgAuthHint('win32', 'disk full'), []);
+  assert.deepEqual(lib.pgAuthHint('linux', 'no password supplied'), []);
+});
+
+t('bashMissingHint: Git for Windows first, Docker as the fallback, WSL explained', () => {
+  const h = lib.bashMissingHint('win32', { wslOnly: true }).join('\n');
+  assert.match(h, /git-scm\.com\/download\/win/);
+  assert.match(h, /self-host\.md/);
+  assert.match(h, /WSL/);
+  assert.doesNotMatch(lib.bashMissingHint('win32').join('\n'), /WSL/);
+  assert.deepEqual(lib.bashMissingHint('darwin'), []);
+});
+
+// ============ 2. dev.js wiring, process.platform + spawnSync stubbed ============
+
+// Run fn() as if on Windows: process.platform, spawnSync, existsSync, readdirSync
+// and the env keys the lookups read are all swapped, then restored however fn ends.
+// `spawn(cmd, args, opts)` answers each spawnSync; every call is recorded.
+function onWindows({ spawn, exists = () => false, readdir = null, env = {} }, fn) {
+  const realPlatform = Object.getOwnPropertyDescriptor(process, 'platform');
+  const real = { spawnSync: cp.spawnSync, existsSync: fs.existsSync, readdirSync: fs.readdirSync, log: console.log, error: console.error };
+  const envKeys = ['PATH', 'EXEPATH', 'ProgramFiles', 'ProgramW6432', 'ProgramFiles(x86)', 'LOCALAPPDATA', ...Object.keys(env)];
+  const savedEnv = Object.fromEntries(envKeys.map((k) => [k, process.env[k]]));
+  const calls = [];
+  const out = [];
+  Object.defineProperty(process, 'platform', { value: 'win32', configurable: true });
+  for (const k of envKeys) if (k !== 'PATH') delete process.env[k];
+  Object.assign(process.env, env);
+  cp.spawnSync = (cmd, args = [], opts = {}) => {
+    calls.push({ cmd, args, opts });
+    const r = spawn(cmd, args, opts) || {};
+    return { status: 0, stdout: '', stderr: '', ...r };
+  };
+  fs.existsSync = (p) => exists(String(p));
+  if (readdir) fs.readdirSync = (d) => readdir(String(d));
+  console.log = (...a) => out.push(a.join(' '));
+  console.error = (...a) => out.push(a.join(' '));
+  try {
+    return { value: fn(), calls, out: out.join('\n') };
+  } finally {
+    Object.defineProperty(process, 'platform', realPlatform);
+    cp.spawnSync = real.spawnSync; fs.existsSync = real.existsSync; fs.readdirSync = real.readdirSync;
+    console.log = real.log; console.error = real.error;
+    for (const [k, v] of Object.entries(savedEnv)) { if (v === undefined) delete process.env[k]; else process.env[k] = v; }
+  }
+}
+
+// `where <bin>` answers from a { bin: [paths] } map; everything else exits 0.
+const whereFrom = (onPath) => (cmd, args) => {
+  if (cmd !== 'where') return {};
+  const hits = typeof onPath === 'function' ? onPath(args[0]) : onPath[args[0]];
+  return hits && hits.length ? { status: 0, stdout: hits.join('\r\n') + '\r\n' } : { status: 1 };
+};
+
+const INST = { instanceRoot: '/x/inst' };
+
+t('dev.js installDeps on Windows: npm runs through node + npm-cli.js, not a bare `npm` spawn', () => {
+  const { value, calls } = onWindows({
+    spawn: whereFrom({ npm: ['C:\\Program Files\\nodejs\\npm.cmd'] }),
+    exists: (p) => p.endsWith('package-lock.json') || p.endsWith('npm-cli.js'),
+  }, () => devCli.installDeps(INST));
+  assert.equal(value, true);
+  const npmRun = calls.find((c) => c.cmd !== 'where');
+  assert.equal(npmRun.cmd, process.execPath);
+  assert.match(npmRun.args[0], /npm-cli\.js$/);
+  assert.equal(npmRun.args[1], 'ci');
+  assert.ok(!npmRun.opts.shell, 'no shell needed when npm-cli.js is used');
+});
+
+t('dev.js installDeps on Windows without npm-cli.js: the npm.cmd shim goes through a shell', () => {
+  const { calls } = onWindows({
+    spawn: whereFrom({ npm: ['C:\\Program Files\\nodejs\\npm.cmd'] }),
+    exists: (p) => p.endsWith('package-lock.json'),
+  }, () => devCli.installDeps(INST));
+  const npmRun = calls.find((c) => c.cmd !== 'where');
+  assert.equal(npmRun.cmd, 'npm ci');
+  assert.equal(npmRun.opts.shell, true);
+});
+
+t('dev.js preflight on Windows: finds installed Postgres off PATH and Git Bash over WSL bash', () => {
+  const psqlVisible = () => lower(process.env.PATH || '').includes(lower(PG16_BIN));
+  const { value, out } = onWindows({
+    env: { ProgramFiles: PF },
+    spawn: whereFrom((bin) => {
+      if (['psql', 'createdb', 'pg_isready'].includes(bin)) return psqlVisible() ? [`${PG16_BIN}\\${bin}.exe`] : [];
+      if (bin === 'bash') return [WSL_BASH];
+      return [];
+    }),
+    readdir: (d) => { if (lower(d) === lower(`${PF}\\PostgreSQL`)) return ['16']; throw new Error('ENOENT'); },
+    exists: (p) => [lower(`${PG16_BIN}\\psql.exe`), lower(GIT_BASH), lower(WSL_BASH)].includes(lower(p)),
+  }, () => {
+    const r = devCli.preflight({});
+    return { ...r, pathHadPg: psqlVisible() };
+  });
+  assert.equal(value.ok, true, out);
+  assert.equal(value.pathHadPg, true, 'the installer’s bin folder was put on PATH');
+  assert.equal(value.bashBin, GIT_BASH);
+});
+
+t('dev.js preflight on Windows with no Postgres: Windows install steps, not Homebrew/apt-get', () => {
+  const { value, out } = onWindows({ env: { ProgramFiles: PF }, spawn: whereFrom({}), readdir: () => { throw new Error('ENOENT'); } },
+    () => devCli.preflight({}));
+  assert.equal(value.ok, false);
+  assert.match(out, /postgresql\.org\/download\/windows/);
+  assert.doesNotMatch(out, /brew install|apt-get/);
+});
+
+t('dev.js preflight on Windows with only WSL bash: refuses, names Git for Windows and Docker', () => {
+  const { value, out } = onWindows({
+    env: { ProgramFiles: PF },
+    spawn: whereFrom({ psql: ['p'], createdb: ['c'], pg_isready: ['r'], bash: [WSL_BASH] }),
+    exists: (p) => lower(p) === lower(WSL_BASH),
+  }, () => devCli.preflight({}));
+  assert.equal(value.ok, false);
+  assert.match(out, /git-scm\.com\/download\/win/);
+  assert.match(out, /self-host\.md/);
+  assert.match(out, /WSL/);
+  assert.doesNotMatch(out, /use WSL/); // WSL is no longer the recommended path
+});
+
+t('dev.js migrate on Windows: Git Bash gets a forward-slash migrate.sh path', () => {
+  const params = { coreRoot: 'C:\\core', instanceRoot: 'C:\\inst', pgHost: 'localhost', pgUser: 'postgres', dbName: 'inst', envPrefix: 'CLOUDBONGOS', gdsOnly: true };
+  const { value, calls } = onWindows({ spawn: () => ({ status: 0, stdout: 'apply core_001_x.sql\n' }) },
+    () => devCli.migrate(params, GIT_BASH));
+  assert.equal(value, true);
+  assert.equal(calls[0].cmd, GIT_BASH);
+  assert.equal(calls[0].args[0], 'C:/core/scripts/migrate.sh');
+});
+
+t('dev.js createDb on Windows: psql/createdb never prompt (-w) and a refusal explains PGPASSWORD', () => {
+  const params = { pgHost: 'localhost', pgUser: 'postgres', dbName: 'inst' };
+  const { value, calls, out } = onWindows({
+    spawn: (cmd) => (cmd === 'createdb'
+      ? { status: 1, stderr: 'createdb: error: connection to server failed: fe_sendauth: no password supplied' }
+      : { status: 2, stderr: 'fe_sendauth: no password supplied' }),
+  }, () => devCli.createDb(params));
+  assert.equal(value, false);
+  for (const c of calls.filter((x) => x.cmd === 'psql' || x.cmd === 'createdb')) assert.ok(c.args.includes('-w'), `${c.cmd} got -w`);
+  assert.match(out, /PGPASSWORD/);
+  assert.match(out, /"postgres"/);
+});
+
+t('dev.js usage: Windows is supported (Git Bash), Docker is the fallback, WSL is not the answer', () => {
+  const lines = [];
+  const realLog = console.log;
+  console.log = (...a) => lines.push(a.join(' '));
+  try { devCli.usage(); } finally { console.log = realLog; }
+  const u = lines.join('\n');
+  assert.match(u, /Windows/);
+  assert.match(u, /Git Bash/);
+  assert.match(u, /self-host\.md/);
+  assert.doesNotMatch(u, /use WSL/);
+});
+
+console.log(`\n${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/tests/env_knobs_neutral_prefix.mjs

@@ -0,0 +1,203 @@
+// tests/env_knobs_neutral_prefix.mjs — the operational env knobs answer to the
+// instance's own prefix, not only to OTB_ (task 1001441, the R61 follow-up).
+//
+// R61 (task 1200) put the config dir and the auth/API-base env vars behind
+// src/instance-config.js resolveEnv(), and task 1003703 made BONGOS the canonical
+// prefix. The operational knobs below still read `process.env.OTB_*` directly, so a
+// fresh instance setting BONGOS_DEPLOY_MODE (or any knob here) was silently ignored.
+// Each test sets ONLY the canonical `<PREFIX>_<KNOB>` spelling — the prefix is
+// read from the branding contract, never assumed — and asserts the reader obeys
+// it. Every one of them fails against the direct OTB_ reads this task replaced.
+// The legacy OTB_ spellings keep working through resolveEnv's warned fallback;
+// the existing tests that set them (pre_push_hook, preflight_checks,
+// push_path_brief, ship_broadcast_server, autobongos_loop) are that proof.
+//
+// SCOPE, knob by knob (the task named ~17):
+//   converted here — DEPLOY_MODE, PUSH_VIA_SERVER, ALLOW_MAIN_PUSH (reader AND
+//     push-main.js's writer), CLAUDE_BIN (grader, preflight/doctor, the Autobongos
+//     worker and its env allowlist), COST_CRON_ROUTINE (run-routine.js's writer AND
+//     session-cost.js's reader), COST_LEDGER, GIT_SHA, MEMORY_DIR,
+//     ONBOARDING_WINDOW_DAYS, ROUTINE_ALERT_CHANNEL, and AUDIT_RANGE. AUDIT_RANGE's
+//     two writers are a bash deploy gate and a CI workflow, which cannot compute the
+//     branded prefix — so they now hand the range to main-audit.js as --range, and
+//     only an operator's own override goes through the env knob. Left as an env
+//     handoff, every deploy and CI audit would print a deprecation warning about a
+//     name no operator sets (pinned in tests/deploy_audit_gate.mjs).
+//   already done before this task — the ACTOR, PUBLIC_ORIGIN, SECURITY_ADR_PATH,
+//     STALE_CLAIM_HOURS and STATUS_DEFAULT_VERSION knobs, whose readers went through
+//     resolveEnv in task 1003703 and its predecessors (only their operator-facing
+//     text still named the old spelling, fixed here).
+//   gone — OTB_PREVIEW_STAMP has no reader or writer left anywhere.
+//
+// Run:  node --test tests/env_knobs_neutral_prefix.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { spawnSync } from 'node:child_process';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+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 { envPrefix, LEGACY_ENV_PREFIXES } = require('../src/instance-config.js');
+
+const PREFIX = envPrefix();
+const canonical = (knob) => `${PREFIX}_${knob}`;
+
+// Every spelling of a knob, so a test can clear the ones it is not about — a
+// developer's shell exporting OTB_DEPLOY_MODE must not decide these results.
+const allSpellings = (knob) => [...new Set([PREFIX, ...LEGACY_ENV_PREFIXES])].map((p) => `${p}_${knob}`);
+function envWith(knob, value, base = process.env) {
+  const env = { ...base };
+  for (const name of allSpellings(knob)) delete env[name];
+  env[canonical(knob)] = value;
+  return env;
+}
+
+// Run a snippet in a fresh node, so module-level reads (and the per-process
+// deprecation-warning ledger) start clean.
+function runNode(code, env) {
+  const r = spawnSync(process.execPath, ['-e', code], { cwd: ROOT, env, encoding: 'utf8' });
+  assert.equal(r.status, 0, `child failed: ${r.stderr}`);
+  return r.stdout.trim();
+}
+
+// A PATH with nothing on it: any `gh` / `claude` probe fails instantly and
+// deterministically, so an answer can only have come from the env override.
+const EMPTY_BIN = fs.mkdtempSync(path.join(os.tmpdir(), 'knobs-nobin-'));
+test.after(() => fs.rmSync(EMPTY_BIN, { recursive: true, force: true }));
+
+test('DEPLOY_MODE: <PREFIX>_DEPLOY_MODE pins the mode, with no gh probe', () => {
+  // 'laptop' from the env is honoured as-is. Ignored, the same run would probe gh
+  // (absent here), find no credential and fall back to 'ci'.
+  const out = runNode(
+    "console.log(require('./scripts/gds/ship-deploy-target.js').resolveDeployMode())",
+    { ...envWith('DEPLOY_MODE', 'laptop'), PATH: EMPTY_BIN },
+  );
+  assert.equal(out.split('\n').pop(), 'laptop');
+});
+
+test('PUSH_VIA_SERVER: <PREFIX>_PUSH_VIA_SERVER=0 forces the local push path', () => {
+  const out = runNode(
+    "console.log(require('./scripts/gds/ship-deploy-target.js').pushVia())",
+    { ...envWith('PUSH_VIA_SERVER', '0'), PATH: EMPTY_BIN },
+  );
+  assert.equal(out, 'local', 'with no gh on PATH, only the override can answer local');
+});
+
+test('ALLOW_MAIN_PUSH: push-main.js writes the canonical spelling, and the hook obeys it', () => {
+  const { pushEnv } = require('../scripts/gds/push-main.js');
+  const env = pushEnv({ PATH: process.env.PATH, HOME: process.env.HOME });
+  assert.equal(env[canonical('ALLOW_MAIN_PUSH')], '1', 'the writer uses this instance\'s own prefix');
+
+  const hook = path.join(ROOT, 'scripts', 'gds', 'hooks', 'pre-push.js');
+  const sha = 'a'.repeat(40);
+  const push = (e) => spawnSync(process.execPath, [hook, 'origin', 'https://example.invalid/repo.git'], {
+    cwd: ROOT, input: `refs/heads/main ${sha} refs/heads/main ${sha}\n`, encoding: 'utf8', env: e,
+  });
+  const cleared = { ...process.env };
+  for (const name of allSpellings('ALLOW_MAIN_PUSH')) delete cleared[name];
+  assert.equal(push(cleared).status, 13, 'without the override a main push is blocked (exit 13)');
+  assert.equal(push({ ...cleared, ...pushEnv({}) }).status, 0, 'the canonical override lets the pipeline push');
+});
+
+test('CLAUDE_BIN: the preflight probe, the Autobongos worker and its env allowlist', () => {
+  const { preflightChecks } = require('../scripts/gds/preflight.js');
+  let seen = null;
+  const spy = (bin) => { seen = bin; return { status: 0, stdout: 'x\n' }; };
+  const fsOk = { existsSync: () => true };
+  const r = preflightChecks({ nodeVersion: 'v22.0.0', fs: fsOk, spawn: spy, env: { [canonical('CLAUDE_BIN')]: '/opt/claude' } });
+  assert.equal(seen, '/opt/claude');
+  const row = r.find((x) => x.title === 'claude CLI');
+  assert.match(row.detail, new RegExp(`via ${canonical('CLAUDE_BIN')}`), 'the label names the spelling that supplied it');
+
+  const runner = require('../scripts/gds/autobongos-run.js');
+  assert.equal(runner.resolveWorkerBin({ [canonical('CLAUDE_BIN')]: '/x/claude' }, 'linux').bin, '/x/claude');
+  const wenv = runner.workerEnv({ [canonical('CLAUDE_BIN')]: '/x/claude', DATABASE_URL: 'postgres://secret' });
+  assert.equal(wenv[canonical('CLAUDE_BIN')], '/x/claude', 'the worker receives the canonical spelling');
+  assert.equal(wenv.DATABASE_URL, undefined, 'the allowlist still refuses everything else');
+});
+
+test('CLAUDE_BIN: the grader spawns the binary <PREFIX>_CLAUDE_BIN names', async () => {
+  const { runSubagent } = require('../modules/grading/grader-subagent.js');
+  const probe = path.join(EMPTY_BIN, 'claude-probe-does-not-exist');
+  const saved = { ...process.env };
+  try {
+    for (const name of [...allSpellings('CLAUDE_BIN'), 'CLAUDE_BIN']) delete process.env[name];
+    process.env[canonical('CLAUDE_BIN')] = probe;
+    // An empty PATH as well: if the override were ignored, a bare `claude` must fail
+    // to resolve rather than launch a real, paid session.
+    process.env.PATH = EMPTY_BIN;
+    await assert.rejects(runSubagent({ prompt: 'x', opts: { timeoutMs: 5000 } }), (err) => {
+      assert.equal(err.code, 'SUBAGENT_SPAWN_FAILED');
+      assert.ok(err.message.includes(probe), `spawned the override, not a PATH lookup: ${err.message}`);
+      return true;
+    });
+  } finally {
+    for (const k of Object.keys(process.env)) if (!(k in saved)) delete process.env[k];
+    Object.assign(process.env, saved);
+  }
+});
+
+test('COST_CRON_ROUTINE: run-routine.js writes the canonical name and session-cost.js reads it', () => {
+  const { stepEnv } = require('../scripts/gds/run-routine.js');
+  const { cronRoutineFromEnv } = require('../scripts/gds/session-cost.js');
+  const env = stepEnv('bfg', {});
+  assert.equal(env[canonical('COST_CRON_ROUTINE')], 'bfg', 'the writer uses this instance\'s own prefix');
+  assert.equal(cronRoutineFromEnv(env), 'bfg', 'the reader finds what the writer wrote');
+  assert.equal(cronRoutineFromEnv({ [canonical('COST_CRON_ROUTINE')]: '  nightly ' }), 'nightly');
+  assert.equal(cronRoutineFromEnv({}), '');
+});
+
+test('ROUTINE_ALERT_CHANNEL: <PREFIX>_ROUTINE_ALERT_CHANNEL picks the alert channel', () => {
+  const { alertChannel } = require('../scripts/gds/run-routine.js');
+  assert.equal(alertChannel({ [canonical('ROUTINE_ALERT_CHANNEL')]: 'ops' }), 'ops');
+  assert.equal(alertChannel({}), 'ship_feed');
+});
+
+test('COST_LEDGER: <PREFIX>_COST_LEDGER is the first place a ledger is looked for', () => {
+  const { knownLedgerPaths } = require('../scripts/gds/backfill-cost.js');
+  assert.equal(knownLedgerPaths({ [canonical('COST_LEDGER')]: '/data/cost_ledger.jsonl' })[0], '/data/cost_ledger.jsonl');
+});
+
+test('GIT_SHA: <PREFIX>_GIT_SHA is the deployed commit /version reports', () => {
+  const sha = 'abcdef0123456789abcdef0123456789abcdef01';
+  const out = JSON.parse(runNode(
+    "console.log(JSON.stringify(require('./src/build-info.js').buildInfo()))",
+    envWith('GIT_SHA', sha),
+  ));
+  assert.equal(out.commit, sha);
+  assert.equal(out.resolvedVia, 'env');
+});
+
+test('MEMORY_DIR: <PREFIX>_MEMORY_DIR is where memory-map.js reads MEMORY.md', () => {
+  const dir = fs.mkdtempSync(path.join(os.tmpdir(), 'knobs-memory-'));
+  try {
+    fs.writeFileSync(path.join(dir, 'MEMORY.md'), '# Memory index\n\n- [a note](a.md) — one line\n');
+    const r = spawnSync(process.execPath, ['scripts/gds/memory-map.js'], { cwd: ROOT, env: envWith('MEMORY_DIR', dir), encoding: 'utf8' });
+    assert.equal(r.status, 0, r.stderr);
+    assert.match(r.stdout, /^map: \d+ bytes/m, 'it measured the map in that directory (ignored, it prints usage and exits 2)');
+  } finally {
+    fs.rmSync(dir, { recursive: true, force: true });
+  }
+});
+
+test('AUDIT_RANGE: <PREFIX>_AUDIT_RANGE is the range main-audit.js audits, and --range still wins', () => {
+  const { requestedRange } = require('../scripts/gds/main-audit.js');
+  assert.equal(requestedRange(undefined, { [canonical('AUDIT_RANGE')]: 'abc123..HEAD' }), 'abc123..HEAD');
+  assert.equal(requestedRange('def456..HEAD', { [canonical('AUDIT_RANGE')]: 'abc123..HEAD' }), 'def456..HEAD',
+    'the flag the deploy gate and CI pass beats any env value');
+  assert.equal(requestedRange(true, {}), null, 'a bare --range with no value falls back to the default window');
+  assert.equal(requestedRange(undefined, {}), null);
+});
+
+test('ONBOARDING_WINDOW_DAYS: <PREFIX>_ONBOARDING_WINDOW_DAYS sets the window', () => {
+  const out = runNode(
+    "console.log(require('./scripts/gds/onboarding-config.js').windowDays())",
+    envWith('ONBOARDING_WINDOW_DAYS', '3'),
+  );
+  assert.equal(out, '3');
+});