@bongos/core 1.17.1 → 1.17.3

package/tests/run_routine.mjs

@@ -4,8 +4,9 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import path from 'node:path';
 const require = createRequire(import.meta.url);
-const { parseRoutineFrontmatter, tokenize } = require('../scripts/gds/run-routine.js');
+const { parseRoutineFrontmatter, tokenize, resolveStepArgv } = require('../scripts/gds/run-routine.js');
 
 let passed = 0, failed = 0;
 function test(name, fn) {
@@ -65,5 +66,29 @@ test('tokenize splits argv and honors quotes', () => {
   assert.deepEqual(tokenize(''), []);
 });
 
+// resolveStepArgv — two-root step resolution (ADR 0108; task 2138). Explicit roots (pure).
+const ROOTS = { coreRoot: '/core', instanceRoot: '/inst' };
+
+test('resolveStepArgv: `bongos exec <rel>` resolves under the CORE root', () => {
+  assert.deepEqual(
+    resolveStepArgv(['bongos', 'exec', 'scripts/gds/box.js', 'sweep-idle', '--apply'], ROOTS),
+    [process.execPath, path.join('/core', 'scripts/gds/box.js'), 'sweep-idle', '--apply']);
+});
+
+test('resolveStepArgv: `node scripts/...` → CORE root; `node .claude/...` companion → INSTANCE root', () => {
+  assert.deepEqual(
+    resolveStepArgv(['node', 'scripts/gds/x.js', '--flag'], ROOTS),
+    [process.execPath, path.join('/core', 'scripts/gds/x.js'), '--flag']);
+  assert.deepEqual(
+    resolveStepArgv(['node', '.claude/scheduled-tasks/demo/run.js'], ROOTS),
+    [process.execPath, path.join('/inst', '.claude/scheduled-tasks/demo/run.js')]);
+});
+
+test('resolveStepArgv: absolute paths + non-node commands + empty pass through untouched', () => {
+  assert.deepEqual(resolveStepArgv(['node', '/abs/x.js'], ROOTS), ['node', '/abs/x.js']);
+  assert.deepEqual(resolveStepArgv(['bash', 'x.sh'], ROOTS), ['bash', 'x.sh']);
+  assert.deepEqual(resolveStepArgv([], ROOTS), []);
+});
+
 console.log(`\nrun_routine: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/run_routine_two_root.mjs

@@ -0,0 +1,77 @@
+// tests/run_routine_two_root.mjs — task 2138 (ADR 0108 configurable-root).
+//
+// Proves the deterministic cron dispatcher works in a real CONSUMER layout: it FINDS a routine
+// under resolveInstanceRoot() (the host repo — NOT the core root) and RUNS its companion step,
+// whose core require() resolves into node_modules/@bongos/core via the materialized
+// _core-resolve.js sibling. This is task 2138's "a consumer-layout dispatch finds + runs the
+// routines" done-when, exercised in a synthetic two-root tree.
+//
+// Counterfactual built in: the routine exists ONLY under the synthetic instance root, so against
+// the pre-2138 dispatcher (TASKS_DIR hardcoded to __dirname/../..) run-routine would look in THIS
+// repo, not find `demo`, and exit 2 — reddening this test. And the companion asserts its core lib
+// resolved from node_modules/@bongos/core (not the instance root), so a single-root resolve fails it.
+//
+// DB-free, no model. Run: node tests/run_routine_two_root.mjs
+
+import { strict as assert } from 'node:assert';
+import { execFileSync } from 'node:child_process';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(__dirname, '..'); // the core root (this repo), fixed by resolveCoreRoot()
+const RUN_ROUTINE = path.join(REPO, 'scripts', 'gds', 'run-routine.js');
+const CORE_RESOLVE = path.join(REPO, '.claude', 'hooks', '_core-resolve.js');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
+}
+
+// Build a synthetic CONSUMER tree: instance content (.claude/) at its OWN root; the core installed
+// under node_modules/@bongos/core carrying just the one lib the companion needs.
+const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'rr-two-root-'));
+const inst = path.join(tmp, 'instance');
+try {
+  const coreLibDir = path.join(inst, 'node_modules', '@bongos', 'core', 'scripts', 'gds');
+  fs.mkdirSync(coreLibDir, { recursive: true });
+  fs.writeFileSync(path.join(coreLibDir, 'fake-core-lib.js'), 'module.exports = { ping: () => "CORE_OK" };\n');
+
+  // the materialized _core-resolve.js sibling (the real one — its resolution is what we exercise)
+  const hooksDir = path.join(inst, '.claude', 'hooks');
+  fs.mkdirSync(hooksDir, { recursive: true });
+  fs.copyFileSync(CORE_RESOLVE, path.join(hooksDir, '_core-resolve.js'));
+
+  // a materialized deterministic routine + its instance-path companion
+  const rtDir = path.join(inst, '.claude', 'scheduled-tasks', 'demo');
+  fs.mkdirSync(rtDir, { recursive: true });
+  fs.writeFileSync(path.join(rtDir, 'SKILL.md'),
+    ['---', 'name: demo', 'mode: deterministic', 'steps:',
+      '  - command: node .claude/scheduled-tasks/demo/run.js', '    sink: none', '---', 'body', ''].join('\n'));
+  fs.writeFileSync(path.join(rtDir, 'run.js'),
+    "const { requireCore, coreModulePath } = require('../../hooks/_core-resolve.js');\n" +
+    "const { ping } = requireCore('scripts/gds/fake-core-lib.js');\n" +
+    "console.log('RESOLVED=' + coreModulePath('scripts/gds/fake-core-lib.js'));\n" +
+    "console.log(ping());\n");
+
+  test('dispatch finds the routine under resolveInstanceRoot() and runs it; companion resolves core from node_modules', () => {
+    const out = execFileSync(process.execPath, [RUN_ROUTINE, 'demo'], {
+      encoding: 'utf8',
+      // Diverge the roots: OTB_INSTANCE_ROOT points resolveInstanceRoot() at the synthetic tree
+      // (OTB_ is an accepted legacy prefix; ADR 0108 §1); resolveCoreRoot() stays this repo.
+      // CLAUDE_PROJECT_DIR pins _core-resolve's own instance root to the synthetic tree too.
+      env: { ...process.env, OTB_INSTANCE_ROOT: inst, CLAUDE_PROJECT_DIR: inst },
+    });
+    assert.match(out, /CORE_OK/, 'companion step should have run and printed its core lib output');
+    assert.match(out, /RESOLVED=.*node_modules[/\\]@bongos[/\\]core[/\\]scripts[/\\]gds[/\\]fake-core-lib\.js/,
+      'the core lib must resolve from node_modules/@bongos/core, proving two-root (not single-root) resolution');
+  });
+} finally {
+  fs.rmSync(tmp, { recursive: true, force: true });
+}
+
+console.log(`\nrun_routine_two_root: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/scrubber_corpus.mjs

@@ -242,6 +242,23 @@ test('collectEnvSecrets: gathers secret-shaped env VALUES, skips benign & short'
   assert.ok(!out.includes(env.MAC_INSTALLER_CERT_P12) && !out.includes(env.APPLE_API_ISSUER_ID), 'env literals scrubbed');
 });
 
+test('collectEnvSecrets: benign shell PWD/OLDPWD are skipped, real *_PWD password vars still collected (task 2130)', () => {
+  // Regression: PWD/OLDPWD contain "pwd" (the password alternative in ENV_SECRET_KEY_RE)
+  // and hold a directory PATH ≥ 8 chars, so pre-fix they were collected as "secrets" — then
+  // the package-core no-leak gate aborted a legit publish whenever that path appeared verbatim
+  // in a functional file (a /Users/<name> anti-pattern comment), passing or failing purely on
+  // the operator's last `cd`. Exact-match exclusion, so genuine password vars still match.
+  const env = {
+    PWD: '/Users/larskristensen/dev/Claude-OTB',
+    OLDPWD: '/Users/larskristensen',
+    MYSQL_PWD: randStr(20, 40, B64URL), // a real password var — MUST still be collected
+  };
+  const got = collectEnvSecrets(env);
+  assert.ok(!got.includes(env.PWD), 'PWD (a directory path) must not be collected');
+  assert.ok(!got.includes(env.OLDPWD), 'OLDPWD (a directory path) must not be collected');
+  assert.ok(got.includes(env.MYSQL_PWD), 'MYSQL_PWD (a real password var) must still be collected');
+});
+
 test('self-reference `key = key` (SQL SET col = col) survives — zero recall loss', () => {
   // task 1688: the core packager redacts live SQL, so a `_token` COLUMN self-increment
   // must NOT be corrupted — while a real `key = <secret>` assignment is STILL redacted.

package/tests/update_channel.mjs

@@ -0,0 +1,186 @@
+// tests/update_channel.mjs
+//
+// task 2150 / ADR 0136 — the update-subscription policy core (scripts/gds/update-channel.js).
+// Pins the channel math + manifest loading the `core-update-subscription` routine relies on:
+//   1. semver — parse (incl. prerelease), compare precedence.
+//   2. channelAllows — the pinned/patch/minor blast-radius matrix; majors + prereleases never auto.
+//   3. resolveChannelTarget — highest permitted target, or null (pinned / nothing newer / unknown).
+//   4. parseNpmViewVersions — the array / bare-string / empty shapes npm view emits.
+//   5. listAvailableVersions — ok + fail-soft with an injected runner.
+//   6. loadSubscriptions — missing/malformed → empty; channel default + validate; env kept; dropless.
+//
+// DB-free + network-free (every external is injected). Run:  node tests/update_channel.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { mkdtempSync, writeFileSync } from 'node:fs';
+import { tmpdir } from 'node:os';
+import { join } from 'node:path';
+
+const require = createRequire(import.meta.url);
+const uc = require('../scripts/gds/update-channel.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.message}`); }
+}
+
+// ---- semver ----------------------------------------------------------------
+
+t('parseSemver: plain, v-prefixed, prerelease, junk', () => {
+  assert.deepEqual(uc.parseSemver('1.17.2'), { major: 1, minor: 17, patch: 2, pre: '' });
+  assert.deepEqual(uc.parseSemver('v2.0.0'), { major: 2, minor: 0, patch: 0, pre: '' });
+  assert.deepEqual(uc.parseSemver('1.17.2-rc.1'), { major: 1, minor: 17, patch: 2, pre: 'rc.1' });
+  assert.equal(uc.parseSemver('1.17'), null);
+  assert.equal(uc.parseSemver('latest'), null);
+  assert.equal(uc.parseSemver(''), null);
+});
+
+t('compareSemver: numeric precedence + prerelease below stable', () => {
+  assert.equal(uc.compareSemver('1.17.2', '1.17.1'), 1);
+  assert.equal(uc.compareSemver('1.17.1', '1.18.0'), -1);
+  assert.equal(uc.compareSemver('1.17.1', '2.0.0'), -1);
+  assert.equal(uc.compareSemver('1.17.2', '1.17.2'), 0);
+  assert.equal(uc.compareSemver('1.17.2-rc.1', '1.17.2'), -1); // prerelease < stable
+  assert.equal(uc.compareSemver('bogus', '1.0.0'), -1);        // unparseable sorts lowest
+});
+
+t('normalizeChannel: valid pass through, unknown/blank → patch default', () => {
+  assert.equal(uc.normalizeChannel('pinned'), 'pinned');
+  assert.equal(uc.normalizeChannel('MINOR'), 'minor');
+  assert.equal(uc.normalizeChannel('major'), 'patch'); // major is not a valid auto-channel
+  assert.equal(uc.normalizeChannel(''), 'patch');
+  assert.equal(uc.normalizeChannel(undefined), 'patch');
+});
+
+// ---- channelAllows ---------------------------------------------------------
+
+t('channelAllows: patch stays within x.y', () => {
+  assert.equal(uc.channelAllows('1.17.1', '1.17.2', 'patch'), true);
+  assert.equal(uc.channelAllows('1.17.1', '1.17.10', 'patch'), true);
+  assert.equal(uc.channelAllows('1.17.1', '1.18.0', 'patch'), false); // minor bump not allowed on patch
+  assert.equal(uc.channelAllows('1.17.1', '2.0.0', 'patch'), false);
+});
+
+t('channelAllows: minor allows higher minor within the major, not a major', () => {
+  assert.equal(uc.channelAllows('1.17.1', '1.18.0', 'minor'), true);
+  assert.equal(uc.channelAllows('1.17.1', '1.17.5', 'minor'), true);
+  assert.equal(uc.channelAllows('1.17.1', '2.0.0', 'minor'), false); // major never automatic
+});
+
+t('channelAllows: pinned never; not-newer never; prerelease never; unknown installed never', () => {
+  assert.equal(uc.channelAllows('1.17.1', '1.99.99', 'pinned'), false);
+  assert.equal(uc.channelAllows('1.17.2', '1.17.1', 'patch'), false); // older
+  assert.equal(uc.channelAllows('1.17.1', '1.17.1', 'patch'), false); // same
+  assert.equal(uc.channelAllows('1.17.1', '1.17.2-rc.1', 'patch'), false); // prerelease target
+  assert.equal(uc.channelAllows(null, '1.17.2', 'patch'), false);     // unknown installed
+  assert.equal(uc.channelAllows('1.17.1', 'garbage', 'patch'), false);
+});
+
+// ---- resolveChannelTarget --------------------------------------------------
+
+const AVAIL = ['1.16.9', '1.17.0', '1.17.1', '1.17.2', '1.17.3', '1.18.0', '1.18.1', '2.0.0', '1.17.4-rc.1'];
+
+t('resolveChannelTarget: patch → highest patch on the same minor', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.1', channel: 'patch', available: AVAIL }), '1.17.3');
+});
+
+t('resolveChannelTarget: minor → highest minor within the major (not 2.0.0)', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.1', channel: 'minor', available: AVAIL }), '1.18.1');
+});
+
+t('resolveChannelTarget: pinned → null', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.1', channel: 'pinned', available: AVAIL }), null);
+});
+
+t('resolveChannelTarget: already newest → null; prerelease never chosen', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.3', channel: 'patch', available: AVAIL }), null);
+  // A prerelease ahead (1.17.4-rc.1) is NOT a target even though it's numerically newer.
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.3', channel: 'minor', available: ['1.17.4-rc.1'] }), null);
+});
+
+t('resolveChannelTarget: unknown installed / empty list → null (never guesses)', () => {
+  assert.equal(uc.resolveChannelTarget({ installed: null, channel: 'patch', available: AVAIL }), null);
+  assert.equal(uc.resolveChannelTarget({ installed: '1.17.1', channel: 'patch', available: [] }), null);
+  assert.equal(uc.resolveChannelTarget({}), null);
+});
+
+// ---- parseNpmViewVersions --------------------------------------------------
+
+t('parseNpmViewVersions: array, bare string, empty, malformed', () => {
+  assert.deepEqual(uc.parseNpmViewVersions('["1.0.0","1.1.0"]'), { ok: true, versions: ['1.0.0', '1.1.0'] });
+  assert.deepEqual(uc.parseNpmViewVersions('"1.0.0"'), { ok: true, versions: ['1.0.0'] });
+  assert.deepEqual(uc.parseNpmViewVersions('   '), { ok: true, versions: [] });
+  const bad = uc.parseNpmViewVersions('not json');
+  assert.equal(bad.ok, false);
+});
+
+// ---- listAvailableVersions (injected runner) -------------------------------
+
+t('listAvailableVersions: ok path parses stdout; non-zero exit is fail-soft', () => {
+  const ok = uc.listAvailableVersions({ run: () => ({ status: 0, stdout: '["1.17.1","1.17.2"]' }) });
+  assert.deepEqual(ok, { ok: true, versions: ['1.17.1', '1.17.2'] });
+
+  const fail = uc.listAvailableVersions({ run: () => ({ status: 1, stderr: 'E404 Not Found' }) });
+  assert.equal(fail.ok, false);
+  assert.match(fail.error, /E404/);
+
+  const threw = uc.listAvailableVersions({ run: () => { throw new Error('spawn ENOENT'); } });
+  assert.equal(threw.ok, false);
+  assert.match(threw.error, /ENOENT/);
+});
+
+// ---- loadSubscriptions -----------------------------------------------------
+
+function scratchWith(obj) {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-subs-'));
+  const cfgDir = join(dir, 'config');
+  require('node:fs').mkdirSync(cfgDir, { recursive: true });
+  writeFileSync(join(cfgDir, 'update-subscriptions.json'), typeof obj === 'string' ? obj : JSON.stringify(obj));
+  return dir;
+}
+
+t('loadSubscriptions: missing file → empty roster, present:false, no throw', () => {
+  const dir = mkdtempSync(join(tmpdir(), 'otb-subs-none-'));
+  const r = uc.loadSubscriptions({ instanceDir: dir });
+  assert.deepEqual(r.instances, []);
+  assert.equal(r.present, false);
+  assert.equal(r.defaultChannel, 'patch');
+});
+
+t('loadSubscriptions: malformed JSON → empty + error, no throw', () => {
+  const dir = scratchWith('{ not valid');
+  const r = uc.loadSubscriptions({ instanceDir: dir });
+  assert.deepEqual(r.instances, []);
+  assert.match(r.error, /malformed JSON/);
+});
+
+t('loadSubscriptions: normalizes channel, keeps env, defaults from defaultChannel', () => {
+  const dir = scratchWith({
+    defaultChannel: 'minor',
+    instances: [
+      { slug: 'demo', dir: '/srv/demo', service: 'demo.service', healthUrl: 'https://demo/healthz', env: { PGDATABASE: 'demo', BAD: 5 } },
+      { slug: 'pinnedone', dir: '/srv/p', channel: 'PINNED' },
+      { slug: 'nochan', dir: '/srv/n' },
+    ],
+  });
+  const r = uc.loadSubscriptions({ instanceDir: dir });
+  assert.equal(r.defaultChannel, 'minor');
+  assert.equal(r.instances.length, 3);
+  const demo = r.instances.find((i) => i.slug === 'demo');
+  assert.equal(demo.channel, 'minor');            // inherited from defaultChannel
+  assert.deepEqual(demo.env, { PGDATABASE: 'demo' }); // non-string env value dropped
+  assert.equal(r.instances.find((i) => i.slug === 'pinnedone').channel, 'pinned');
+  assert.equal(r.instances.find((i) => i.slug === 'nochan').channel, 'minor');
+});
+
+t('loadSubscriptions: an entry without a dir is dropped (cannot be upgraded)', () => {
+  const dir = scratchWith({ instances: [{ slug: 'ghost' }, { slug: 'real', dir: '/srv/real' }] });
+  const r = uc.loadSubscriptions({ instanceDir: dir });
+  assert.equal(r.instances.length, 1);
+  assert.equal(r.instances[0].slug, 'real');
+});
+
+console.log(`\nupdate_channel: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/upgrade.mjs

@@ -416,6 +416,137 @@ t('runUpgrade --registry (full): pins the exact version + writes the env-fed .np
   assert.ok(!calls.some((c) => /vendor/.test(c)), 'did not vendor a tarball');
 });
 
+// ---- 9. auto-rollback on failure (task 2149) --------------------------------
+
+// A pin-aware spawn shim: `npm install` installs whatever the CURRENT pin resolves to, so the
+// forward install lands the target and a post-rollback install restores the previous core.
+// Knobs simulate a failing target install or a failing migrate.
+function pinAwareRun(calls, { dir, failMigrate = false, failInstallForVersion = null } = {}) {
+  return (cmd, args) => {
+    calls.push(`${cmd} ${(args || []).join(' ')}`.trim());
+    if (cmd === 'git' && args[0] === 'status') return { status: 0, stdout: '' };
+    if (cmd === 'npm' && args[0] === 'install') {
+      const pkg = JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8'));
+      const dep = pkg.dependencies['@bongos/core'];
+      const v = u.versionFromTgzPath(dep) || u.versionFromDep(dep);
+      if (failInstallForVersion && v === failInstallForVersion) return { status: 1 };
+      writeFileSync(join(dir, 'node_modules', '@bongos', 'core', 'package.json'),
+        JSON.stringify({ name: '@bongos/core', version: v }) + '\n');
+      return { status: 0 };
+    }
+    if (cmd === 'npm' && args[0] === 'run' && args[1] === 'migrate') return { status: failMigrate ? 1 : 0 };
+    return { status: 0 }; // systemctl / restart-cmd / anything else
+  };
+}
+
+// A fake pg that records every ledger INSERT's params (params[3] = note).
+function recordingPg(queries) {
+  return { Pool: class { async query(sql, params) { queries.push({ sql, params }); } async end() {} } };
+}
+
+t('rollback on health failure: reverts pin, restarts again, re-checks health, writes ONE rolled_back ledger row', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const calls = [], queries = [];
+  let fetchN = 0;
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service', healthUrl: 'http://x/healthz' },
+    {
+      log: () => {}, err: () => {},
+      run: pinAwareRun(calls, { dir }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+      // forward health fails (1st fetch); the post-rollback re-check recovers (2nd fetch)
+      fetch: async () => { fetchN++; return fetchN === 1 ? { ok: false, status: 503 } : { ok: true, status: 200 }; },
+      sleep: async () => {}, now: () => 0, healthBudgetMs: 0,
+    }
+  );
+  assert.equal(res.ok, false, 'a failed health check is not a success');
+  assert.equal(res.rolledBack, true, 'the upgrade rolled back');
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'pin reverted to the previous core');
+  assert.equal(u.readInstalledCoreVersion(dir), '1.14.1', 'previous core reinstalled');
+  assert.equal(res.rollback.healthOk, true, 'health recovered after the rollback restart');
+  assert.equal(calls.filter((c) => c === 'systemctl restart demo.service').length, 2, 'restarted twice: forward + rollback');
+  assert.equal(queries.length, 1, 'only the rolled_back row is written (no phantom upgraded row)');
+  assert.equal(queries[0].params[1], '1.15.0', 'to_version = the attempted target');
+  assert.match(queries[0].params[3], /^rolled_back:/, 'note marks the reversal');
+});
+
+t('rollback on migrate failure: reverts pin + reinstalls previous core + rolled_back ledger', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const calls = [], queries = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service' },
+    {
+      log: () => {}, err: () => {},
+      run: pinAwareRun(calls, { dir, failMigrate: true }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.equal(res.rolledBack, true);
+  assert.match(res.rollback.reason, /migrate failed/);
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'pin reverted');
+  assert.equal(u.readInstalledCoreVersion(dir), '1.14.1', 'previous core reinstalled');
+  assert.equal(queries.length, 1);
+  assert.match(queries[0].params[3], /^rolled_back: migrate failed/);
+});
+
+t('rollback on npm-install failure: reverts pin + reinstalls previous core', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const calls = [], queries = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service' },
+    {
+      log: () => {}, err: () => {},
+      run: pinAwareRun(calls, { dir, failInstallForVersion: '1.15.0' }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.equal(res.rolledBack, true);
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1', 'pin reverted after the failed install');
+  assert.equal(u.readInstalledCoreVersion(dir), '1.14.1', 'previous core reinstalled');
+  assert.match(queries[0].params[3], /^rolled_back: npm install failed/);
+});
+
+t('--no-rollback-on-failure: a failed health check does NOT revert (records the attempt, leaves the new pin)', async () => {
+  const src = mkdtempSync(join(tmpdir(), 'src-'));
+  writeFileSync(join(src, 'bongos-core-1.15.0.tgz'), 'TGZ');
+  const dir = scratchConsumer({ pinned: '1.14.1', installed: '1.14.1' });
+  const queries = [];
+  const res = await u.runUpgrade(
+    { to: '1.15.0', from: join(src, 'bongos-core-1.15.0.tgz'), instance: dir, service: 'demo.service', healthUrl: 'http://x/healthz', rollbackOnFailure: false },
+    {
+      log: () => {}, err: () => {},
+      run: pinAwareRun([], { dir }),
+      materialize: () => ({ skills: 1 }), regenerateApiArtifacts: () => ({ ok: true, ran: [] }),
+      databaseUrl: 'postgres://x/y', pg: recordingPg(queries),
+      fetch: async () => ({ ok: false, status: 503 }), sleep: async () => {}, now: () => 0, healthBudgetMs: 0,
+    }
+  );
+  assert.equal(res.ok, false);
+  assert.ok(!res.rolledBack, 'no rollback when opted out');
+  assert.equal(u.readPinnedCoreVersion(dir), '1.15.0', 'the new pin is left in place for inspection');
+  assert.equal(queries.length, 1, 'the attempt is still recorded');
+  assert.ok(!/^rolled_back/.test(queries[0].params[3] || ''), 'not marked as a rollback');
+});
+
+t('restorePin: writes a previous dep string back verbatim (file: or registry)', () => {
+  const dir = scratchConsumer({ pinned: '1.15.0' });
+  u.restorePin(dir, 'file:vendor/bongos-core-1.14.1.tgz');
+  assert.equal(u.readPinnedCoreVersion(dir), '1.14.1');
+  u.restorePin(dir, '^1.16.0');
+  assert.equal(JSON.parse(readFileSync(join(dir, 'package.json'), 'utf8')).dependencies['@bongos/core'], '^1.16.0');
+});
+
 await Promise.all(pending);
 console.log(`\nupgrade: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/workflow_exec_paths.mjs

@@ -0,0 +1,98 @@
+// tests/workflow_exec_paths.mjs — task 2136 (ADR 0108 configurable-root).
+//
+// Proves every .github/workflows/*.yml invocation of a CORE script resolves in a consumer layout
+// after the R89 split: each is routed through the both-layouts resolver (infra/core-node.sh for
+// node targets, infra/core-path.sh for bash targets) AND names a PUBLISHABLE core file that ships
+// in @bongos/core (→ present at node_modules/@bongos/core post-install) and exists at the core root
+// today. No workflow still invokes a core script the bare repo-relative way. Also proves
+// core-path.sh resolves both layouts (the bash-target sibling of core-node.sh).
+//
+// DB-free, no network. Run: node tests/workflow_exec_paths.mjs
+
+import { strict as assert } from 'node:assert';
+import { execFileSync } 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 { lintWorkflowExec } = require('../scripts/gds/lint-workflow-exec.js');
+const __dirname = path.dirname(fileURLToPath(import.meta.url));
+const REPO = path.resolve(__dirname, '..');
+const CORE_PATH_SH = path.join(REPO, 'infra', 'core-path.sh');
+
+let passed = 0, failed = 0;
+function test(name, fn) {
+  try { fn(); console.log(`  ok  ${name}`); passed++; }
+  catch (err) { console.error(`  FAIL ${name}`); console.error('    ', err.message); failed++; }
+}
+
+// ---- A. the workflow lint is green on the real tree ---------------------------------------------
+test('lint-workflow-exec: every core invocation is routed + publishable (no bare repo-relative form)', () => {
+  const r = lintWorkflowExec({ instanceRoot: REPO, coreRoot: REPO });
+  assert.deepEqual(r.violations, [], `expected no violations, got: ${JSON.stringify(r.violations, null, 2)}`);
+  assert.ok(r.ok, 'lint should pass');
+  // The security-critical merge gates + the functional gates must all be covered.
+  const rels = r.checked.map((c) => `${c.file}:${c.rel}`);
+  assert.ok(rels.some((s) => s.startsWith('gate-review.yml:') && s.endsWith('scripts/gds/gate-review.js')), 'gate-review routed');
+  assert.ok(rels.some((s) => s.startsWith('grade-gate.yml:') && s.endsWith('scripts/gds/ci-grade.js')), 'grade-gate routed');
+  assert.ok(rels.some((s) => s.endsWith('scripts/migrate.sh')), 'selfhost migrate routed via core-path.sh');
+});
+
+test('lint-workflow-exec: a bare core invocation in a workflow is flagged (counterfactual)', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'wf-lint-'));
+  try {
+    fs.mkdirSync(path.join(tmp, '.github', 'workflows'), { recursive: true });
+    fs.mkdirSync(path.join(tmp, 'scripts', 'gds'), { recursive: true });
+    fs.writeFileSync(path.join(tmp, 'scripts', 'gds', 'gate-review.js'), '// probe\n');
+    fs.writeFileSync(path.join(tmp, '.github', 'workflows', 'legacy.yml'),
+      'jobs:\n  x:\n    steps:\n      - run: node scripts/gds/gate-review.js\n');
+    const r = lintWorkflowExec({ instanceRoot: tmp, coreRoot: tmp });
+    assert.ok(!r.ok, 'a bare core invocation must fail the lint');
+    assert.equal(r.violations.length, 1);
+    assert.match(r.violations[0].why, /bare core invocation/);
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+});
+
+// ---- B. core-path.sh resolves BOTH layouts ------------------------------------------------------
+function runCorePath(rel, instanceRoot) {
+  return execFileSync('bash', [CORE_PATH_SH, rel], {
+    encoding: 'utf8', env: { ...process.env, BONGOS_INSTANCE_ROOT: instanceRoot },
+  }).trim();
+}
+
+test('core-path.sh prints the monolith path (script at the instance root)', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cp-mono-'));
+  try {
+    fs.mkdirSync(path.join(tmp, 'scripts'), { recursive: true });
+    fs.writeFileSync(path.join(tmp, 'scripts', 'migrate.sh'), '# probe\n');
+    assert.equal(runCorePath('scripts/migrate.sh', tmp), path.join(tmp, 'scripts', 'migrate.sh'));
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+});
+
+test('core-path.sh falls back to the consumer path (script only under node_modules/@bongos/core)', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cp-cons-'));
+  try {
+    const pkg = path.join(tmp, 'node_modules', '@bongos', 'core', 'scripts');
+    fs.mkdirSync(pkg, { recursive: true });
+    fs.writeFileSync(path.join(pkg, 'migrate.sh'), '# probe\n');
+    assert.equal(runCorePath('scripts/migrate.sh', tmp), path.join(pkg, 'migrate.sh'));
+  } finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+});
+
+test('core-path.sh exits non-zero (no stdout) when the script is in NO layout', () => {
+  const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'cp-none-'));
+  let threw = false;
+  try {
+    execFileSync('bash', [CORE_PATH_SH, 'scripts/nope.sh'], {
+      encoding: 'utf8', stdio: 'pipe', env: { ...process.env, BONGOS_INSTANCE_ROOT: tmp },
+    });
+  } catch (_) { threw = true; }
+  finally { fs.rmSync(tmp, { recursive: true, force: true }); }
+  assert.ok(threw, 'expected a non-zero exit when the script resolves in no layout');
+});
+
+console.log(`\nworkflow_exec_paths: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/docs/design/container-exterior-tiles.md

@@ -1,49 +0,0 @@
-# Container building — exterior tile spec (pixel-precise, V2)
-
-- **Task:** [#643](https://example.com/builders#/task/643) (V2 · product). Promoted from idea_inbox [#162](https://example.com/builders#/idea/162) (builder 25 art/design brief, 2026-06-04).
-- **Date:** 2026-06-18
-- **Builds on:** [`container-exterior.md`](container-exterior.md) (the structure-level design, task [#641](https://example.com/builders#/task/641)) — this is the **tile-level** layer it calls out. Colour is governed by the locked decisions below.
-- **Status:** Spec ready. **Generation waits for [#640](https://example.com/builders#/task/640) / [ADR 0044](../adr/0044-mediterranean-palette-replacement.md)** (every tile here re-quantizes against the replacement palette — per `container-exterior.md` §Pipeline). Spec work proceeds now.
-
-## ⚠️ Colour: the original brief is superseded — weathered charcoal, not clean red
-
-idea [#162](https://example.com/builders#/idea/162)'s brief (this task's source) asked for **"saturated industrial red (or black) — clean, no weathering, no rust."** That was written **before** Lars resolved the question. The authoritative decision (later wins):
-
-- **Blocker [#7](https://example.com/builders#/blocker/7) (Lars, 2026-06-10, now a locked `style_guide.md` rule):** the container body is **weathered BLACK/CHARCOAL corrugated metal with rust streaks** — *not* red, *not* teal. Faded **Hermes-teal is an ACCENT only** (the door panel + a faint caduceus etch). It must read as an *ancient, heavy, discovered relic*, not factory-new cargo.
-- **`style_guide.md` (Lars, 2026-06-14):** **no white / light edge rim** on container (or other large-object) tiles — strip near-white edge pixels in post ("the white on the container actually sucks").
-- **`style_guide.md`:** non-ground objects carry a **1-px darker outline** against their interior (FireRed rock/tree convention); ground tiles do not.
-
-So every tile below is **weathered charcoal corrugated metal with rust streaks**; the brief's "clean red, no weathering, single-pixel white highlight" wording does **not** apply. The brief's *geometry* (corrugation, glass panels, deck, roof, staircase) is still the source — only the colour/finish is corrected.
-
-## Per-tile pixel specs (32×32 base)
-
-### Container wall tile
-- **Base:** weathered charcoal/gunmetal (a matte near-black with a faint blue-grey undertone), drawn from the replacement palette's charcoal/grey value steps (ADR 0044 guarantees enough steps).
-- **Corrugation:** 4–5 vertical ridges per tile. Each ridge: 1px lighter charcoal on the left (highlight), 1px darker on the right (shadow); flat panels between are the base.
-- **Weathering:** sparse vertical **rust streaks** (a desaturated orange-brown from the palette) bleeding downward from ridge tops + seams — irregular, 1–2px wide, not on every ridge. Reads as age, not damage.
-- **Edges:** 1px darker-charcoal **outline** on the object silhouette (per the style rule). Top edge 2px darker (top face in oblique light); bottom edge 1px near-black ground shadow. **No white/light rim** anywhere on the silhouette.
-- **Stacked-unit seam:** a 2px dark recessed line with a 1px shadow below, where the ground-floor container meets the second storey.
-
-### Glass storefront / window panel (32×32, or 64×32 wide)
-- **Fill:** semi-transparent blue-grey (≈40–50% over what's behind). Through dark glass, a faint **warm amber interior glow** (the "dark exterior, warm interior" mood from `container-exterior.md`).
-- **Frame:** 3px matte-charcoal border (the frames dissolve into the dark facade rather than reading as separate elements).
-- **Interior hint:** extremely faint 1–2-shade-darker silhouettes (a plant, shelving) — not detailed.
-- **Reflection highlight — FLAG for Lars:** the brief wanted a white upper-left reflection strip; the no-white-rim rule targets the *object silhouette*, not interior glass. Proposed: a restrained **pale-blue** (not white) 1px upper-left reflection inside the frame. If Lars wants zero light pixels here, drop it. *(Open pixel-detail decision.)*
-
-### Door tile (the one Hermes-teal accent)
-- Charcoal frame; the door panel is **faded Hermes-teal** (the single body-color exception), with a **faint caduceus etch** (1–2px lighter teal lines) where space allows, and a warm interior glow at the threshold. This is the only teal on the building.
-
-### Deck tile (wood apron, walkable)
-- Horizontal planks: light warm tan base, 4–5 planks/tile, 1px dark gap between; very subtle 1–2px grain lines; 2px darker far-edge shadow. Drawn as an alpha-margined object overlay over sand (the `marble_path` technique, [ADR 0013](../adr/<redacted>.md)) so it works on any ground.
-
-### Roof tile (top-down)
-- Flat charcoal surface, 1 shade darker than the wall face (less direct light); small 3×3 dark **container corner castings** at each corner; a faint 2px panel seam every 8px; 1px railing line on edge tiles (per `container-exterior.md` rooftop band).
-
-### Exterior staircase (object overlay)
-- Dark charcoal steel: two parallel rails with treads between (top-down ladder look); 1px railing line each outer edge, 1px lighter than the tread. Arrives at the rooftop stair-landing tile.
-
-## Mood target
-A **designed object, not a found one** — presence from its *shape and glass*, not from bright paint. The charcoal recedes into the coastal scene; at dusk the warm interior light through dark glass is the most dramatic visual in the game. The contradiction (an *ancient* shipping container) lives in the weathering + the teal-and-caduceus door.
-
-## Pipeline mapping (generate after [#640](https://example.com/builders#/task/640))
-Per [ADR 0008](../adr/<redacted>.md) (families, not per-tile): `container_building_facade` (wall · glass · door · light-fixture · staircase), `container_building_roof` (field · railing · landing), `deck_wood` (16-autotile alpha-tile line family). Furniture singletons (table, chairs) per-tile. **Nothing generates until the palette swap ([#640](https://example.com/builders#/task/640)/ADR 0044) lands** — else every tile re-quantizes against the old palette and is redone.