@bongos/core 1.20.61 → 1.20.63

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.20.61'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.20.63'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('discord'); log.info('mounted');

package/tests/core_upgrade_runner.mjs

@@ -219,6 +219,19 @@ await t('a version that is not published yet is refused, and the message says th
   assert.match(f, /tag appears several minutes before/);
 });
 
+await t('the channel refusal names a step that EXISTS on /deploy, never "change the channel first" (task 1004405)', () => {
+  const patch = R.targetFault('1.20.1', ['1.19.1081', '1.20.1'], '1.19.1081', 'patch', () => false);
+  assert.ok(!/Change the channel first/.test(patch), 'the old wording named nothing a person could do');
+  assert.match(patch, /\/deploy/);
+  assert.match(patch, /Fixes and new releases/, 'patch → names the rule that admits a minor jump');
+  const pinned = R.targetFault('1.19.1082', ['1.19.1081', '1.19.1082'], '1.19.1081', 'pinned', () => false);
+  assert.match(pinned, /Stay put/);
+  assert.match(pinned, /Fixes only/);
+  const major = R.targetFault('2.0.0', ['1.19.1081', '2.0.0'], '1.19.1081', 'minor', () => false);
+  assert.match(major, /no update rule/i, 'minor is the widest rule, so pointing at a wider one would be a lie');
+  assert.match(major, /upgrading-the-core\.md/);
+});
+
 await t('a registry that could not be read is refused DIFFERENTLY from a version that does not exist', () => {
   const empty = R.targetFault('1.19.760', [], '1.19.758', 'patch', () => true);
   assert.match(empty, /could not read the published core versions/);

package/tests/update_channel_db.mjs

@@ -46,8 +46,8 @@ test('DB pinned: the sweep skips it even when the roster says minor', () => {
   const [inst] = uc.applyDbChannels([entry({ channel: 'minor' })], dbOf({ cloudbongos: 'pinned' }));
   assert.equal(inst.channel, 'pinned');
   assert.equal(targetFor(inst), null);
-  // subscribe.js skips on exactly this value, and decides it AFTER the DB rule is applied.
-  const src = readFileSync(path.join(ROOT, '.claude/scheduled-tasks/core-update-subscription/subscribe.js'), 'utf8');
+  // update-sweep.js skips on exactly this value, and decides it AFTER the DB rule is applied.
+  const src = readFileSync(path.join(ROOT, 'scripts/gds/update-sweep.js'), 'utf8');
   const applied = src.indexOf('channel.applyDbChannels(');
   const skip = src.indexOf("inst.channel === 'pinned'");
   assert.ok(applied > 0 && skip > applied, 'the pinned skip must read the channel after the /deploy rule is applied');
@@ -69,10 +69,17 @@ test('readDbChannels: no database named → not read, with the reason, and psql
   let spawned = false;
   const r = uc.readDbChannels({ env: {}, run: () => { spawned = true; } });
   assert.equal(r.ok, false);
-  assert.match(r.reason, /no DATABASE_URL or PGDATABASE/);
+  assert.match(r.reason, /no UPDATE_CHANNEL_DB \(or DATABASE_URL \/ PGDATABASE\)/);
   assert.equal(spawned, false);
 });
 
+test('readDbChannels: UPDATE_CHANNEL_DB wins, so a unit need not set PGDATABASE (which leaks into tenant upgrades)', () => {
+  let target;
+  uc.readDbChannels({ env: { UPDATE_CHANNEL_DB: 'cloudbongos', DATABASE_URL: 'postgres://other', PGDATABASE: 'tenant' }, run: (_c, a) => { target = a[1]; return { status: 0, stdout: '' }; } });
+  assert.equal(target, 'cloudbongos');
+  assert.equal(uc.CHANNEL_DB_ENV, 'UPDATE_CHANNEL_DB');
+});
+
 test('readDbChannels: parses psql -At tab output into slug → channel, from the sweep env only', () => {
   let args;
   const run = (cmd, a) => { args = [cmd, ...a]; return { status: 0, stdout: 'cloudbongos\tminor\ncharter\tpatch\n\n', stderr: '' }; };
@@ -112,12 +119,12 @@ test('channelLine: the sweep log names the channel and where it came from', () =
     [entry(), entry({ slug: 'charter', channel: 'patch' })], dbOf({ cloudbongos: 'minor' }));
   assert.equal(uc.channelLine(fromDeploy), '  • cloudbongos: channel minor, set on /deploy (roster says patch, ignored)');
   assert.equal(uc.channelLine(fromRoster), '  • charter: channel patch, from the roster — no project row for this slug');
-  const src = readFileSync(path.join(ROOT, '.claude/scheduled-tasks/core-update-subscription/subscribe.js'), 'utf8');
+  const src = readFileSync(path.join(ROOT, 'scripts/gds/update-sweep.js'), 'utf8');
   assert.match(src, /console\.log\(channel\.channelLine\(inst\)\)/);
 });
 
-test('subscribe.js reads the DB from its own env, never an entry env (which names that instance\'s DB)', () => {
-  const src = readFileSync(path.join(ROOT, '.claude/scheduled-tasks/core-update-subscription/subscribe.js'), 'utf8');
+test('update-sweep.js reads the DB from its own env, never an entry env (which names that instance\'s DB)', () => {
+  const src = readFileSync(path.join(ROOT, 'scripts/gds/update-sweep.js'), 'utf8');
   assert.match(src, /channel\.readDbChannels\(\{ env: process\.env \}\)/);
   // A core too old to carry the reader must keep the roster rather than crash the sweep.
   assert.match(src, /typeof channel\.readDbChannels === 'function'/);

package/tests/update_subscription_engine.mjs

@@ -334,7 +334,7 @@ test('the heal branch is reachable only when the dirty files ARE the pin', () =>
 // ---------------------------------------------------------------------------
 
 test('every commitPin call site in the lane decides about push', () => {
-  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'update-sweep.js'), 'utf8');
   // Every CALL, excluding the definition (which is `function commitPin({ ... push = true })` —
   // its default is what these sites must not silently inherit).
   const calls = [];
@@ -358,7 +358,7 @@ test('every commitPin call site in the lane decides about push', () => {
 });
 
 test('the direct-upgrade fallback asks pinFlagsFor rather than deciding inline', () => {
-  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'update-sweep.js'), 'utf8');
   // The fourth version of this assertion. It used to pin the inline `if` verbatim, which froze
   // the bug of task 1004122 in place: the line was correct about NOT pushing a co-tenant pin and
   // wrong about how, and a test that quotes an expression can only ever confirm it is still there.
@@ -610,7 +610,7 @@ test('preflightFlagsFor has the precedent it claims — go-live.js really does s
 });
 
 test('the direct-upgrade fallback asks preflightFlagsFor rather than deciding inline', () => {
-  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'update-sweep.js'), 'utf8');
   assert.match(src, /upArgs\.push\(\.\.\.preflightFlagsFor\(pinMode\)\)/,
     'the clean-tree policy is a pin-mode decision and must go through the named function');
 });
@@ -618,7 +618,7 @@ test('the direct-upgrade fallback asks preflightFlagsFor rather than deciding in
 test('every commitPin call site in the lane also decides what the upgrade generated', () => {
   // The sibling of the push assertion in section 8, and for the same reason: a site that inherits
   // the `generated = []` default silently reverts to the two-bucket guard that wedged the lane.
-  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'update-sweep.js'), 'utf8');
   const calls = [];
   const re = /commitPin\(\{/g;
   let m;
@@ -756,7 +756,7 @@ test('the post-upgrade net re-probes, rather than reusing the set from before th
   // A skill the NEW core adds is absent from the pre-upgrade answer, so reusing it would drop that
   // file into `other` and wedge the lane one release later — this defect again, wearing the next
   // version number. The heal, which runs BEFORE the bump, must keep using the pre-bump set.
-  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  const src = readFileSync(path.join(ROOT, 'scripts', 'gds', 'update-sweep.js'), 'utf8');
   const afterSpawn = src.split('const generatedAfter = laneGeneratedPaths(inst.dir);')[1];
   assert.ok(afterSpawn, 'the post-upgrade re-probe is gone');
   assert.equal((afterSpawn.match(/generated: generatedAfter,/g) || []).length, 2,

package/tests/update_sweep_home.mjs

@@ -0,0 +1,100 @@
+// tests/update_sweep_home.mjs — the update sweep lives in the core package and runs from it
+// (task 1004307).
+//
+// WHY. The sweep used to live only under .claude/scheduled-tasks/, which the core package never
+// ships, so cloudbongos.com's sweep ran a checkout frozen at 2026-08-25 and every later lane fix was
+// inert there. It now lives at scripts/gds/update-sweep.js. These pin the three things that keep it
+// runnable from node_modules/@bongos/core: it publishes, it needs nothing the package lacks (the
+// .claude/hooks resolver is topology-excluded), and it reads the roster from where it is told,
+// not from where its own file sits.
+//
+// Run:  node --test tests/update_sweep_home.mjs
+
+import { test } from 'node:test';
+import assert from 'node:assert/strict';
+import { createRequire } from 'node:module';
+import { spawnSync } from 'node:child_process';
+import { mkdtempSync, mkdirSync, writeFileSync, readFileSync } from 'node:fs';
+import { tmpdir } 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 SWEEP = path.join(ROOT, 'scripts', 'gds', 'update-sweep.js');
+const sweep = require(SWEEP);
+const { isPublishable } = require('../scripts/gds/publish-manifest.js');
+
+test('the sweep and every core file it requires are in the published package', () => {
+  for (const f of ['scripts/gds/update-sweep.js', 'scripts/gds/update-channel.js', 'scripts/gds/upgrade.js', 'src/module-api.js']) {
+    assert.equal(isPublishable(f), true, `${f} must publish, or the installed sweep cannot run`);
+  }
+  // The reason it moved: the old home never ships.
+  assert.equal(isPublishable('.claude/scheduled-tasks/core-update-subscription/subscribe.js'), false);
+});
+
+test('the sweep requires nothing the package lacks (no .claude/ path, no hook resolver)', () => {
+  const src = readFileSync(SWEEP, 'utf8');
+  const requires = [...src.matchAll(/require\(\s*['"]([^'"]+)['"]\s*\)/g)].map((m) => m[1]);
+  for (const r of requires) {
+    assert.ok(!r.includes('.claude') && !r.includes('_core-resolve'), `update-sweep.js requires ${r}, which the core package does not ship`);
+    if (r.startsWith('.')) assert.equal(isPublishable(path.posix.join('scripts/gds', r).replace(/\\/g, '/')), true, `${r} must publish`);
+  }
+});
+
+test('its target-instance resolver searches the same packages, in the same order, as _core-resolve.js', () => {
+  const hook = readFileSync(path.join(ROOT, '.claude', 'hooks', '_core-resolve.js'), 'utf8');
+  const m = hook.match(/const CORE_PKG_NAMES = (\[[^\]]*\]);/);
+  assert.ok(m, '_core-resolve.js CORE_PKG_NAMES not found');
+  assert.deepEqual(sweep.CORE_PKG_NAMES, JSON.parse(m[1].replace(/'/g, '"')));
+});
+
+test('coreModulePathFrom finds a target instance\'s INSTALLED core, root first', () => {
+  const inst = mkdtempSync(path.join(tmpdir(), 'sweep-home-'));
+  const pkg = path.join(inst, 'node_modules', '@bongos', 'core', 'scripts', 'gds');
+  mkdirSync(pkg, { recursive: true });
+  writeFileSync(path.join(pkg, 'upgrade.js'), '');
+  assert.equal(sweep.coreModulePathFrom(inst, 'scripts/gds/upgrade.js'), path.join(pkg, 'upgrade.js'));
+  mkdirSync(path.join(inst, 'scripts', 'gds'), { recursive: true });
+  writeFileSync(path.join(inst, 'scripts', 'gds', 'upgrade.js'), '');
+  assert.equal(sweep.coreModulePathFrom(inst, 'scripts/gds/upgrade.js'), path.join(inst, 'scripts', 'gds', 'upgrade.js'), 'a monolith root wins, as in _core-resolve.js');
+  assert.equal(sweep.coreModulePathFrom(inst, 'scripts/gds/absent.js'), null);
+});
+
+test('run from elsewhere, it reads the roster named by --instance and says which core is sweeping', () => {
+  const rosterRoot = mkdtempSync(path.join(tmpdir(), 'sweep-roster-'));
+  mkdirSync(path.join(rosterRoot, 'config'));
+  writeFileSync(path.join(rosterRoot, 'config', 'update-subscriptions.json'),
+    JSON.stringify({ instances: [{ slug: 'held', dir: path.join(rosterRoot, 'nowhere'), channel: 'pinned' }] }));
+  const cwd = mkdtempSync(path.join(tmpdir(), 'sweep-cwd-'));
+  const r = spawnSync(process.execPath, [SWEEP, '--instance', rosterRoot], { cwd, encoding: 'utf8', env: { ...process.env, DATABASE_URL: '', PGDATABASE: '' } });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, new RegExp(`update-sweep · running from .+ \\(core \\d+\\.\\d+\\.\\d+\\) · roster ${rosterRoot.replace(/[\\^$.*+?()[\]{}|]/g, '\\$&')}`));
+  assert.match(r.stdout, /1 subscribed instance/);
+  assert.match(r.stdout, /held: pinned — skipped/);
+});
+
+test('without --instance it reads the roster in its working directory (the unit\'s WorkingDirectory)', () => {
+  const cwd = mkdtempSync(path.join(tmpdir(), 'sweep-cwd-'));
+  const r = spawnSync(process.execPath, [SWEEP], { cwd, encoding: 'utf8', env: { ...process.env, DATABASE_URL: '', PGDATABASE: '' } });
+  assert.equal(r.status, 0, r.stderr);
+  assert.match(r.stdout, /no roster file — nothing subscribed/);
+  assert.ok(r.stdout.includes(`roster ${cwd}`) || r.stdout.includes(`roster ${path.resolve(cwd)}`), r.stdout);
+});
+
+test('the subscribe.js shim runs the same body, with its instance root as the default roster root', () => {
+  const shim = require('../.claude/scheduled-tasks/core-update-subscription/subscribe.js');
+  assert.equal(shim, sweep, 'the shim re-exports the core body, so tests and callers see one sweep');
+  const src = readFileSync(path.join(ROOT, '.claude', 'scheduled-tasks', 'core-update-subscription', 'subscribe.js'), 'utf8');
+  assert.match(src, /requireCore\('scripts\/gds\/update-sweep\.js'\)/);
+  assert.match(src, /sweep\.main\(\{ instanceRoot: INSTANCE_ROOT \}\)/);
+});
+
+test('the recipe\'s drop-in names the file that really ships, and the safe database setting', () => {
+  const recipe = readFileSync(path.join(ROOT, 'docs', 'recipes', 'upgrading-the-core.md'), 'utf8');
+  const execs = [...recipe.matchAll(/node_modules\/@bongos\/core\/(scripts\/gds\/[\w-]+\.js)/g)].map((m) => m[1]);
+  assert.ok(execs.length >= 2, 'the drop-in and its dry run both name the installed sweep');
+  for (const rel of execs) assert.equal(rel, 'scripts/gds/update-sweep.js');
+  assert.match(recipe, /Environment=UPDATE_CHANNEL_DB=/);
+  assert.doesNotMatch(recipe, /Environment=PGDATABASE=/, 'a unit-level PGDATABASE leaks into tenant upgrades');
+});

package/tests/wizard_demo.mjs

@@ -0,0 +1,264 @@
+// tests/wizard_demo.mjs — the demo route: training wheels, a soft time box, and "keep
+// your planet?" (task 1004420 / BV2.PS09, goal 1000121; spec D3 + D9).
+//
+// Done-when: a demo can be created, run and carried over. D3: the time box is SOFT — a
+// countdown, then the question; work is never frozen. D9: a demo is a normal project
+// marked "demo"; one nobody keeps goes offline after 30 days through the existing
+// take-offline path, with the owner told first.
+//
+// Three layers, all RUN: modules/provisioning/demo.js (the marker, the defaults, the
+// view, the answer, the sweep); the create route and the keep route over a mounted
+// router; and the hub's demo controller sliced out of projects.html and driven in a vm.
+
+import { strict as assert } from 'node:assert';
+import { test, after } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const LANDING = path.join(ROOT, 'modules', 'public-landing', 'public');
+const HUB = fs.readFileSync(path.join(LANDING, 'projects.html'), 'utf8').replace(/\r\n/g, '\n');
+const demo = require('../modules/provisioning/demo.js');
+const DAY = 86400000;
+
+// ── the module ───────────────────────────────────────────────────────────────
+
+test('a demo asks for people and hours each, inside their limits, and nothing else', () => {
+  assert.deepEqual(demo.parseDemo(undefined), { ok: true, demo: null }, 'no demo field: an ordinary project');
+  assert.deepEqual(demo.parseDemo({ people: 3, hours_each: 4 }), { ok: true, demo: { people: 3, hours_each: 4 } });
+  assert.equal(demo.parseDemo({ people: 0, hours_each: 4 }).ok, false);
+  assert.equal(demo.parseDemo({ people: 13, hours_each: 4 }).ok, false);
+  assert.equal(demo.parseDemo({ people: 3, hours_each: 41 }).ok, false);
+  assert.equal(demo.parseDemo({ people: 3, hours_each: 4, ends_at: 'never' }).ok, false, 'a caller cannot name its own end');
+  assert.equal(demo.parseDemo([3, 4]).ok, false);
+});
+
+test('the first read says what fits in the builder-hours', () => {
+  assert.equal(demo.fitCheck(1, 4).verdict, 'tight');
+  assert.equal(demo.fitCheck(3, 4).verdict, 'small');
+  assert.equal(demo.fitCheck(3, 4).total, 12);
+  assert.equal(demo.fitCheck(5, 4).verdict, 'plenty');
+});
+
+test('the demo picks no rewards and all managed, and an owner\'s own answer wins', () => {
+  assert.deepEqual(demo.withDemoDetail(undefined), { reward_intents: [], framing: 'managed' });
+  assert.deepEqual(demo.withDemoDetail({ framing: 'hybrid', team_shape: 'small-team' }), { reward_intents: [], framing: 'hybrid', team_shape: 'small-team' });
+  assert.deepEqual({ ...demo.DEMO_SETTINGS }, { visibility: 'private', joinability: 'invite_only' }, 'private to the team');
+});
+
+test('the time box is soft: it only counts down and then asks (D3)', () => {
+  const start = new Date('2026-10-01T09:00:00Z');
+  const row = { demo: demo.demoRecord({ people: 3, hours_each: 4 }, start) };
+  assert.equal(row.demo.ends_at, '2026-10-01T13:00:00.000Z');
+  const mid = demo.demoView(row, new Date('2026-10-01T11:30:00Z'));
+  assert.equal(mid.remaining_seconds, 5400);
+  assert.equal(mid.time_up, false);
+  assert.equal(mid.builder_hours, 12);
+  const late = demo.demoView(row, new Date('2026-10-01T15:00:00Z'));
+  assert.equal(late.remaining_seconds, 0);
+  assert.equal(late.time_up, true, 'it asks; nothing in the view stops anything');
+  assert.equal(late.offline_on, '2026-10-31T09:00:00.000Z', '30 days after it started (D9)');
+  assert.equal(late.offline_soon, false);
+  assert.equal(demo.demoView(row, new Date('2026-10-29T09:00:00Z')).offline_soon, true, 'the owner is told from three days before');
+  assert.equal(demo.demoView({ demo: null }), null, 'an ordinary project has no demo view');
+  assert.equal(demo.demoView({ demo: { ...row.demo, outcome: 'carried' } }), null, 'a carried-over demo is a real project');
+});
+
+function fakeDb(rows = []) {
+  const writes = [];
+  return { writes, query: async (sql, params) => { if (/^\s*UPDATE/.test(sql)) writes.push(params); return { rows }; } };
+}
+
+test('keep your planet? is answered once', async () => {
+  const db = fakeDb();
+  const inst = { id: 9, demo: demo.demoRecord({ people: 2, hours_each: 3 }) };
+  const r = await demo.settleDemo(db, inst, 'carried');
+  assert.equal(r.ok, true);
+  assert.equal(JSON.parse(db.writes[0][1]).outcome, 'carried');
+  assert.equal((await demo.settleDemo(db, { ...inst, demo: r.demo }, 'kept')).reason, 'already_settled');
+  assert.equal((await demo.settleDemo(db, { id: 1, demo: null }, 'kept')).reason, 'not_a_demo');
+  assert.equal((await demo.settleDemo(db, inst, 'frozen')).reason, 'bad_outcome');
+});
+
+test('the sweep warns three days before and takes a demo nobody carried over offline at 30 days', async () => {
+  const started = new Date('2026-09-01T00:00:00Z');
+  const rows = [
+    { id: 1, owner_builder_id: 7, status: 'active', demo: demo.demoRecord({ people: 1, hours_each: 2 }, started) },
+    { id: 2, owner_builder_id: 7, status: 'active', demo: { ...demo.demoRecord({ people: 1, hours_each: 2 }, new Date('2026-09-04T00:00:00Z')), outcome: 'kept' } },
+    { id: 3, owner_builder_id: 7, status: 'active', demo: demo.demoRecord({ people: 1, hours_each: 2 }, new Date('2026-09-20T00:00:00Z')) },
+  ];
+  const torn = [];
+  const db = fakeDb(rows);
+  const out = await demo.sweepDemos(db, {
+    enqueueTeardown: async (_db, id) => { torn.push(id); },
+    recordEvent: async () => {},
+    now: new Date('2026-10-02T00:00:00Z'),
+  });
+  assert.deepEqual(torn, [1], 'only the one past 30 days goes offline, through the teardown path');
+  assert.equal(out.offline, 1);
+  assert.equal(out.warned, 1, 'the kept demo two days out is warned; the young one is left alone');
+  assert.match(fs.readFileSync(path.join(ROOT, 'modules', 'provisioning', 'demo.js'), 'utf8'), /COALESCE\(demo->>'outcome', ''\) <> 'carried'/, 'a carried-over demo is never swept');
+});
+
+// ── the routes ───────────────────────────────────────────────────────────────
+const api = require('../src/module-api.js');
+const provisioning = require('../modules/provisioning/provisioning.js');
+let created = null;
+let started = null;
+provisioning.getInstanceBySlug = async () => null;
+provisioning.getInstanceByDomain = async () => null;
+provisioning.createInstance = async (_db, args) => {
+  created = args;
+  return { instance: { id: 41, owner_builder_id: 7, slug: args.slug, status: 'requested', hosting_shape: 'byo-host', detail: args.detail || {} }, created: true };
+};
+provisioning.enqueueIntent = async (_db, _id, action) => ({ intent: { id: 9, action, state: 'pending' }, created: true });
+provisioning.getOpenIntent = async () => null;
+provisioning.recordEvent = async () => {};
+demo.startDemoProject = async (_db, _p, id, d) => { started = { id, d }; return null; };
+api.requireBuilder = (req, _res, next) => { req.builder = { id: 7, github_login: 'owner' }; next(); };
+let stored = null;
+provisioning.getInstanceById = async (_db, id) => (id === 41 ? { id: 41, owner_builder_id: 7, demo: stored } : null);
+api.pool.query = async (sql, params) => { if (/UPDATE provisioning_instances SET demo/.test(sql)) stored = JSON.parse(params[1]); return { rows: [] }; };
+
+const express = require('express');
+const app = express();
+app.use(express.json());
+app.use((_req, res, next) => {
+  res.fail = (code, opts) => {
+    const status = typeof opts === 'number' ? opts : (opts && opts.status) || 400;
+    res.status(status).json({ error: { code, message: opts && opts.message } });
+  };
+  next();
+});
+app.use('/api/bongos', require('../modules/provisioning/routes/provisioning.js')());
+app.use('/api/bongos', require('../modules/provisioning/routes/demo.js')());
+const server = app.listen(0);
+after(() => server.close());
+async function post(p, body) {
+  await new Promise((r) => (server.listening ? r() : server.once('listening', r)));
+  const res = await fetch(`http://127.0.0.1:${server.address().port}/api/bongos${p}`, {
+    method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify(body),
+  });
+  return { status: res.status, body: await res.json() };
+}
+
+test('the create files a normal project marked demo, with the demo\'s picked answers under the owner\'s', async () => {
+  const r = await post('/provisioning/instances', { slug: 'reading-list', hosting_shape: 'byo-host', demo: { people: 3, hours_each: 4 }, detail: { team_shape: 'small-team' } });
+  assert.equal(r.status, 201, JSON.stringify(r.body));
+  assert.deepEqual(created.detail, { reward_intents: [], framing: 'managed', team_shape: 'small-team' });
+  assert.deepEqual(started, { id: 41, d: { people: 3, hours_each: 4 } }, 'the row is marked and made private');
+  started = null;
+  const plain = await post('/provisioning/instances', { slug: 'real-one', hosting_shape: 'byo-host' });
+  assert.equal(plain.status, 201);
+  assert.equal(started, null, 'an ordinary project is never marked');
+  assert.equal((await post('/provisioning/instances', { slug: 'bad-demo', hosting_shape: 'byo-host', demo: { people: 99, hours_each: 4 } })).status, 400);
+});
+
+test('keep your planet? over the route: the owner answers once', async () => {
+  stored = demo.demoRecord({ people: 3, hours_each: 4 }, new Date(Date.now() - 5 * 3600000));
+  const r = await post('/provisioning/instances/41/demo', { outcome: 'kept' });
+  assert.equal(r.status, 200, JSON.stringify(r.body));
+  assert.equal(stored.outcome, 'kept');
+  assert.equal(r.body.demo.outcome, 'kept');
+  assert.equal((await post('/provisioning/instances/41/demo', { outcome: 'carried' })).status, 409, 'answered once');
+  assert.equal((await post('/provisioning/instances/99/demo', { outcome: 'carried' })).status, 404, 'not yours, not found');
+  assert.equal((await post('/provisioning/instances/41/demo', { outcome: 'frozen' })).status, 400);
+});
+
+test('the module declares the route, the poller and its migration', () => {
+  const manifest = JSON.parse(fs.readFileSync(path.join(ROOT, 'modules', 'provisioning', 'module.json'), 'utf8'));
+  assert.ok(manifest.contributes.routes.includes('demo'));
+  assert.ok(manifest.contributes.pollers.includes('demo-archive'));
+  assert.match(fs.readFileSync(path.join(ROOT, 'modules', 'provisioning', 'migrations', 'provisioning_035_demo.sql'), 'utf8'), /ADD COLUMN IF NOT EXISTS demo jsonb/);
+  const poller = require('../modules/provisioning/pollers/demo-archive.js');
+  assert.equal(typeof poller.start, 'function');
+  assert.equal(poller.INTERVAL_MS, 3600000);
+});
+
+// ── the hub, RUN ─────────────────────────────────────────────────────────────
+const SLICE = HUB.slice(HUB.indexOf('    /* ── the demo route (task 1004420, BV2.PS09) ──'), HUB.indexOf('    /* ── field wiring ── */'));
+
+test('the hub carries the server\'s limits and fit sentences exactly', () => {
+  assert.ok(SLICE.length > 1000, 'the demo controller was found');
+  const box = {};
+  vm.createContext(box);
+  vm.runInContext(SLICE.slice(SLICE.indexOf('    var DEMO_LIMITS'), SLICE.indexOf('    function demoHandle')).replace('var demoDraft = state.demo', 'var state = {}; var demoDraft = state.demo'), box);
+  assert.deepEqual(JSON.parse(JSON.stringify(box.DEMO_LIMITS)), { people: [...demo.DEMO_LIMITS.people], hours: [...demo.DEMO_LIMITS.hours_each] });
+  for (const [p, h] of [[1, 2], [3, 4], [5, 4], [12, 40]]) {
+    assert.deepEqual(JSON.parse(JSON.stringify(box.demoFit(p, h))), demo.fitCheck(p, h), `${p} × ${h}`);
+  }
+});
+
+class El {
+  constructor(id) {
+    this.id = id; this.hidden = false; this.value = ''; this.textContent = ''; this.attrs = {}; this.listeners = {};
+    const self = this; this.classList = { toggle() {} };
+    this._label = { hidden: false }; this.closest = () => self._label;
+  }
+  setAttribute(k, v) { this.attrs[k] = String(v); }
+  getAttribute(k) { return this.attrs[k] ?? null; }
+  addEventListener(t, fn) { this.listeners[t] = fn; }
+  focus() {}
+}
+
+function bootHub() {
+  const els = {};
+  const $ = (id) => (els[id] = els[id] || new El(id));
+  const steppers = [['people', '1'], ['people', '-1'], ['hours', '1'], ['hours', '-1']].map(([k, by]) => {
+    const b = new El(`step-${k}${by}`); b.attrs['data-demo-step'] = k; b.attrs['data-by'] = by; return b;
+  });
+  const shown = [];
+  const state = { demo: null, description: '', teamShape: null };
+  const sandbox = { $, state, saveDraft() {}, show: (n) => shown.push(n), root: { querySelectorAll: () => steppers } };
+  vm.createContext(sandbox);
+  vm.runInContext(SLICE, sandbox);
+  const click = (id) => $(id).listeners.click.call($(id));
+  return { $, state, shown, steppers, click, sandbox };
+}
+
+test('the door opens the setup, the steppers stay in their limits, and the first read follows them', () => {
+  const h = bootHub();
+  h.click('wizDemo');
+  assert.equal(h.$('forkIntro').hidden, true);
+  assert.equal(h.$('demoSetup').hidden, false);
+  assert.equal(h.$('demoRing').hidden, false, 'the time-box ring on the planet');
+  assert.equal(h.$('wizDemo').attrs['aria-expanded'], 'true');
+  for (let i = 0; i < 20; i += 1) h.steppers[0].listeners.click.call(h.steppers[0]);
+  assert.equal(h.$('demoPeople').textContent, '12', 'people stop at twelve');
+  for (let i = 0; i < 20; i += 1) h.steppers[3].listeners.click.call(h.steppers[3]);
+  assert.equal(h.$('demoHours').textContent, '1', 'hours stop at one');
+  assert.equal(h.$('demoFitSum').textContent, '12 people × 1 hour = 12 builder-hours.');
+  assert.equal(h.$('demoFitVerdict').textContent, demo.fitCheck(12, 1).sentence);
+  h.click('demoBack1');
+  assert.equal(h.$('forkIntro').hidden, false, 'Back returns to the two doors');
+  assert.equal(h.$('wizDemo').attrs['aria-expanded'], 'false');
+});
+
+test('Name my demo planet carries the demo into the ordinary wizard: the idea, the team, the invites', () => {
+  const h = bootHub();
+  h.click('wizDemo');
+  h.$('demoIdea').value = 'A shared reading list.';
+  h.$('demoIdea').listeners.input.call(h.$('demoIdea'));
+  h.click('demoNext1');
+  assert.equal(h.$('demoReady').hidden, false);
+  h.$('demoInvite1').value = '@avery';
+  h.$('demoInvite2').value = 'not a handle!';
+  h.click('demoStart');
+  assert.deepEqual(JSON.parse(JSON.stringify(h.state.demo)), { people: 3, hours_each: 4, idea: 'A shared reading list.', invites: ['avery'] });
+  assert.equal(h.state.description, 'A shared reading list.', 'the idea is the description');
+  assert.equal(h.state.teamShape, 'small-team');
+  assert.deepEqual(h.shown, [3], 'on to the name step');
+});
+
+test('the create sends the demo, the review names it, and the project page asks the question', () => {
+  assert.match(HUB, /demo: state\.demo \? \{ people: state\.demo\.people, hours_each: state\.demo\.hours_each \} : undefined,/);
+  assert.match(HUB, /if \(state\.demo\) \{\n\s*rows\.unshift\(\['Demo',/);
+  assert.match(HUB, /<p class="demoKeepH">Keep your planet\?<\/p>/);
+  assert.match(HUB, /data-demo-settle="carried">Carry it over</);
+  assert.match(HUB, /data-demo-settle="kept">Keep it as a demo</);
+  assert.match(HUB, /\$\('mDemoKeep'\)\.hidden = !\(d\.time_up && !d\.outcome\);/, 'the question waits for the time box (D3)');
+});

package/tests/wizard_front_door.mjs

@@ -113,24 +113,26 @@ test('Proceed is refused until the box is ticked, and the refusal says why in th
   assert.equal(given.ok, true, 'a tick goes on');
 });
 
-test('the fork has no clause of its own — its doors are the answer', () => {
+test('the fork refuses nothing — its doors are the answer, and Begin clears a demo started earlier', () => {
   assert.equal(runValidate(2, false).ok, true, 'the fork asks nothing a validator could refuse');
-  assert.ok(!validateSlice.includes('if (step === 2) {'), 'and no clause for step 2 exists');
+  // task 1004420: "Begin planet creation" is a real project, so a demo the founder
+  // set up and then walked back from must not ride the create
+  assert.match(validateSlice, /if \(step === 2\) \{ state\.demo = null; return true; \}/);
 });
 
 // ── the wiring, executed ───────────────────────────────────────────────────────
 const WIRE_START = "    $('termsAck').checked = !!state.termsAck;";
-const WIRE_END = '    /* ── field wiring ── */';
+const WIRE_END = '    /* ── the demo route (task 1004420, BV2.PS09) ──';
 const wireSlice = SCRIPT.includes(WIRE_START) ? SCRIPT.slice(SCRIPT.indexOf(WIRE_START), SCRIPT.indexOf(WIRE_END)) : null;
 
 function runWiring(initialAck) {
   const handlers = {};
   const mk = (id) => ({
-    id, checked: false, hidden: id === 'demoSoon', textContent: '', className: '', attrs: {},
+    id, checked: false, hidden: false, textContent: '', className: '', attrs: {},
     addEventListener(type, fn) { handlers[id + ':' + type] = fn; },
     setAttribute(k, v) { this.attrs[k] = v; },
   });
-  const els = { termsAck: mk('termsAck'), wizDemo: mk('wizDemo'), demoSoon: mk('demoSoon'), 'h-terms': mk('h-terms') };
+  const els = { termsAck: mk('termsAck'), 'h-terms': mk('h-terms') };
   let saves = 0;
   const sandbox = { $: (id) => els[id], state: { termsAck: initialAck }, saveDraft: () => { saves += 1; } };
   sandbox.globalThis = sandbox;
@@ -141,7 +143,7 @@ function runWiring(initialAck) {
 
 test('the front door\'s wiring is still findable', () => {
   assert.ok(wireSlice && wireSlice.length > 100, 'the wiring block was not found in projects.html');
-  assert.match(wireSlice, /\$\('wizDemo'\)\.addEventListener\('click'/, 'the demo door is part of the slice');
+  assert.match(wireSlice, /\$\('termsAck'\)\.addEventListener\('change'/, 'the tick is part of the slice');
 });
 
 test('the tick mirrors into the draft both ways, and a resumed draft paints its own answer', () => {
@@ -156,17 +158,10 @@ test('the tick mirrors into the draft both ways, and a resumed draft paints its
   assert.equal(saves(), 2, 'each change is saved');
 });
 
-test('the demo door opens a line saying the demo is not open yet, and says so to a screen reader', () => {
-  const { els, handlers } = runWiring(false);
-  assert.equal(els.demoSoon.hidden, true, 'hidden at rest');
-  handlers['wizDemo:click'].call(els.wizDemo);
-  assert.equal(els.demoSoon.hidden, false, 'the placeholder opens');
-  assert.equal(els.wizDemo.attrs['aria-expanded'], 'true');
-  handlers['wizDemo:click'].call(els.wizDemo);
-  assert.equal(els.demoSoon.hidden, true, 'and closes again');
-  assert.equal(els.wizDemo.attrs['aria-expanded'], 'false');
-  assert.match(FORK, /id="wizDemo" aria-controls="demoSoon" aria-expanded="false"/, 'the door names what it opens');
-  assert.match(FORK, /<p class="demoSoon" id="demoSoon" hidden>The demo isn’t open yet\./, 'baked markup, never built by script');
+test('the demo door names what it opens: the demo route\'s setup screen (task 1004420; run in tests/wizard_demo.mjs)', () => {
+  assert.match(FORK, /id="wizDemo" aria-controls="demoSetup" aria-expanded="false"/, 'the door names what it opens');
+  assert.match(FORK, /<div id="demoSetup" class="demoView" hidden>/, 'baked markup, hidden at rest, never built by script');
+  assert.doesNotMatch(FORK, /demoSoon|isn’t open yet/, 'the placeholder that said the demo was not open is gone');
 });
 
 // ── screen 2 · the fork ─────────────────────────────────────────────────────────
@@ -186,7 +181,7 @@ test('screen 2 is the door pill: two equal doors in one object, the accent only
 });
 
 test('the seed stands on the world\'s own field plate — nothing drawn but hairlines', () => {
-  assert.match(FORK, /<div class="forkStage" aria-hidden="true">/, 'decorative, so hidden from a screen reader');
+  assert.match(FORK, /<div class="forkStage" id="forkStage" aria-hidden="true">/, 'decorative, so hidden from a screen reader');
   assert.match(FORK, /<img class="forkSeed" src="\/assets\/world\/r2-chrome-blob-one-cut\.webp" alt="">/, 'a real plate, root-absolute so it is stamped');
   assert.ok(fs.existsSync(path.join(LANDING, 'assets', 'world', 'r2-chrome-blob-one-cut.webp')), 'and it exists on disk');
   assert.match(STYLE, /\.forkStage\{[^}]*background:var\(--sky-bg\) var\(--field-plate\) center\/cover no-repeat;/, 'the field is the plate token, not a new image');
@@ -197,9 +192,10 @@ test('the seed stands on the world\'s own field plate — nothing drawn but hair
   assert.doesNotMatch(block, /#[0-9a-f]{3,8}\b|box-shadow:(?!none)|linear-gradient/i, 'every colour a token, no shadow, no gradient');
 });
 
-test('the two routes are described honestly for today: the demo says coming soon, creation promises no questions that do not exist yet', () => {
+test('the two routes are described honestly for today: the demo is open (task 1004420), creation promises no questions that do not exist yet', () => {
   const routes = (FORK.match(/<div class="forkRoutes">[\s\S]*$/) || [''])[0];
-  assert.match(routes, /Route 1 · demo · coming soon/);
+  assert.match(routes, /Route 1 · demo<\/p>/);
+  assert.doesNotMatch(routes, /coming soon/, 'the demo is built, so the route no longer says it is coming');
   assert.match(routes, /Route 2 · planet creation/);
   assert.doesNotMatch(routes, /seven questions/i, 'the seven planet questions are PS07\'s — the copy must not promise them before they ship');
   assert.doesNotMatch(FORK, /\bBongos\b(?! pair)/, 'no product name baked where a child instance would ship it');