@bongos/core 1.25.4 → 1.25.6

package/modules/provisioning/module.json

@@ -20,6 +20,7 @@
       "core-upgrade",
       "env-manifest",
       "repo-private",
+      "update-subscription",
       "render-standup",
       "look",
       "demo",

package/modules/provisioning/paid-shape-gate.js

@@ -104,6 +104,7 @@ const ONE_FREE_SHAPES = Object.freeze(new Set(['cloud-host']));
 // the response closes, so a second request sent meanwhile — from any web process — is
 // refused (the wizard never sends two). ./free-place-lock.js says how it is held.
 const freePlace = require('./free-place-lock');
+const { isTestProject } = require('./test-project');
 
 // Shapes that are not requestable through this route AT ALL — no permission admits them,
 // because there is no rank at which "ask the API for a second control plane" is a
@@ -159,7 +160,8 @@ function shapeAuthority(rawShape) {
 async function otherLiveProjects(db, builderId, shape, rawSlug) {
   const slug = String(rawSlug || '').trim().toLowerCase();
   const rows = await provisioning.listInstancesForOwner(db, builderId);
-  return rows.filter((r) => r.hosting_shape === shape && r.status !== 'torn_down' && r.slug !== slug);
+  // A test project holds no free place (task 1005036): it is for trying features, and only an archon makes one.
+  return rows.filter((r) => r.hosting_shape === shape && r.status !== 'torn_down' && r.slug !== slug && !isTestProject(r));
 }
 
 // requireAuthorityForShape — the create route's shape gate. Mount it AFTER requireBuilder

package/modules/provisioning/provisioning.js

@@ -23,7 +23,7 @@ const { normalizeModuleSelection, effectiveModules } = require('./starter-bundle
 // pure declarations beside this file, for the same reason: storage and the read
 // projection both have to read them.
 const { PLANET_PHYSICS_QUESTIONS, canonicalAnswer } = require('./planet-physics');
-const { softLimitsFor } = require('./soft-limits'); const { demoView } = require('./demo');   // the demo marker's owner view (task 1004420)
+const { softLimitsFor } = require('./soft-limits'); const { demoView } = require('./demo'); const { isTestProject, TEST_COMPANION_ENV } = require('./test-project');   // the demo marker's owner view (task 1004420); the test mark (task 1005036)
 const { dnsResolves, recordDnsResolved, lookupAnswers } = require('./dns-resolves');   // has the platform's lookup seen the address answer (task 1004505)
 const { LOOK_SETTINGS_VOCAB, LOOK_DEFAULTS, LOOK_COMPANION_ENV } = require('./look'); const { BIRTH_COMPANION_ENV } = require('./birth'); // born into genesis (task 1004506)
 
@@ -453,7 +453,7 @@ function publicInstance(row) {
     detail,
     // Which startup options those answers hide, grey or annotate, each with its reason
     // (BV2.PS02, spec D6). Advice only — `enforced: false` says so on every read.
-    soft_limits: softLimitsFor(detail), demo: demoView(row),   // null unless a demo nobody carried over (task 1004420, ./demo.js)
+    soft_limits: softLimitsFor(detail), demo: demoView(row), is_test: isTestProject(row),   // null unless a demo nobody carried over (task 1004420, ./demo.js)
     // The creation picker's module set (task 1002339): the always-on core, what
     // the owner ends up with, and whether that came from their own toggles or
     // from the type's starter bundle because they never answered. Resolved, not
@@ -513,7 +513,7 @@ function settingsEnvVars(row, prefix) {
 // cutoff and every unresolved review counts, which is the right answer for a
 // project that has been strict since it stood up.
 const SETTINGS_COMPANION_ENV = Object.freeze({
-  ARTIST_GATE_SINCE: (row) => artistGateStrictSince(row) || '', ...LOOK_COMPANION_ENV, ...BIRTH_COMPANION_ENV, // + accent, logo (look.js); birth, demo box (birth.js)
+  ARTIST_GATE_SINCE: (row) => artistGateStrictSince(row) || '', ...LOOK_COMPANION_ENV, ...BIRTH_COMPANION_ENV, ...TEST_COMPANION_ENV, // + accent, logo (look.js); birth, demo box (birth.js); test mark (test-project.js)
 });
 
 // The web.env block the runner writes at STANDUP (task 1003139): a comment that

package/modules/provisioning/routes/provisioning.js

@@ -64,7 +64,7 @@ const catalogBridge = require('../catalog-bridge');
 const capacity = require('../capacity');   // the box's slot ceiling (ADR 0285, task 1003927)
 const { callbackPage } = require('./callback-page'); const githubSetup = require('../github-setup');
 // the LOUD body validators (task 1003504) — lifted out when this file hit the size ratchet
-const { badProjectDetail, badModuleSelection, badProjectType, screenedOut } = require('./body-validators'); const demo = require('../demo'); const birth = require('../birth');
+const { badProjectDetail, badModuleSelection, badProjectType, screenedOut } = require('./body-validators'); const demo = require('../demo'); const birth = require('../birth'); const testProject = require('../test-project');
 const { failFrom } = require('../public-refusal');   // every catch: a declared refusal reaches the owner, anything else stays opaque (task 1004126)
 const { settingsPush, failPushConflict } = require('../settings-push');   // a settings save's push + receipt, shared with routes/look.js (task 1004421)
 const { requireProjectOwner, projectActor, isProjectOwner } = require('../route-helpers');   // the owner-or-archon gate (task 1004159, ADR 0328)
@@ -164,6 +164,10 @@ function ownerInstance(row) {
 function fleetInstance(row) {
   return {
     owner: { id: row.owner_builder_id, github_login: row.github_login, display_name: row.display_name, rank: row.rank },
+    // Fleet-only (task 1004150): which rows take unattended upgrades, and under what rule. Kept off
+    // publicInstance, which feeds owner reads — who auto-upgrades is an operator's question.
+    update_channel: row.update_channel || 'patch',
+    update_subscribed: row.update_subscribed === true,
     ...ownerInstance(row),
   };
 }
@@ -357,7 +361,7 @@ module.exports = function provisioningRoutes() {
       // exactly the set the panel preselected. An explicit [] is the different
       // answer "none of them". maxItems is a sanity ceiling well above a catalog
       // that is three modules wide today.
-      modules: { type: 'array', itemsType: 'string', maxItems: 50 }, terms_acknowledged: { type: 'boolean' }, demo: { type: 'object' }, ship_mode: { type: 'string', enum: ['auto', 'manual'] }, genesis: { type: 'boolean' },   // the wizard's terms tick (task 1004417, ../terms-ack.js); the demo route's { people, hours_each } (task 1004420, ../demo.js)
+      modules: { type: 'array', itemsType: 'string', maxItems: 50 }, terms_acknowledged: { type: 'boolean' }, demo: { type: 'object' }, ship_mode: { type: 'string', enum: ['auto', 'manual'] }, genesis: { type: 'boolean' }, test: { type: 'boolean' },   // the wizard's terms tick (task 1004417, ../terms-ack.js); the demo route's { people, hours_each } (task 1004420, ../demo.js)
     })) return;
     const body = req.body || {};
     const detailFault = badProjectDetail(body.detail);
@@ -368,6 +372,8 @@ module.exports = function provisioningRoutes() {
     if (screened) return res.fail('screened_out', screened);
     const demoAsk = demo.parseDemo(body.demo);   // a demo is a normal project marked demo, its picked answers under the owner's own (task 1004420)
     if (!demoAsk.ok) return res.fail('bad_demo', { status: 400, message: demoAsk.reason });
+    const testAsk = testProject.parseTestAsk(body, req.builder);   // a test project: archon only; genesis only on one (task 1005036, ../test-project.js)
+    if (!testAsk.ok) return res.fail(testAsk.code, { status: testAsk.status, message: testAsk.message });
     const slug = String(body.slug || '').trim().toLowerCase();
     if (!provisioning.isValidSlug(slug)) {
       return res.fail('bad_slug', 400, { reason: 'lowercase, 2–40 chars of [a-z0-9-], no leading/trailing/double dash' });
@@ -473,8 +479,9 @@ module.exports = function provisioningRoutes() {
       // provision intent exists, so the runner's web.env already carries the marker and the demo's box.
       // Best-effort: a project that misses its marker opens as an ordinary hall; the create still stands.
       // Genesis is OFF by default (owner, 2026-11-01): a new project opens as the full hall. Only a demo (its
-      // time box lives on the birth marker) or an explicit `genesis: true` (the test toggle) is born into it.
-      if (created && (demoAsk.demo || body.genesis === true)) await birth.stampBirth(pool, instance.id).catch((err) => log.error('[provisioning] birth marker not stamped', err));
+      // time box lives on the birth marker) or a test project asking for genesis is born into it.
+      if (created && (demoAsk.demo || testAsk.genesis)) await birth.stampBirth(pool, instance.id).catch((err) => log.error('[provisioning] birth marker not stamped', err));
+      if (created && testAsk.test) await testProject.stampTestProject(pool, instance.id).catch((err) => log.error('[provisioning] test mark not stamped', err));
       // The wizard's ship mode (task 1004629) rides beside it; a miss means the project asks at its first ship.
       if (created) await birth.stampShipMode(pool, instance.id, body.ship_mode).catch((err) => log.error('[provisioning] ship mode not stamped', err));
       const demoRow = created && demoAsk.demo ? await demo.startDemoProject(pool, provisioning, instance.id, demoAsk.demo) : null;

package/modules/provisioning/routes/update-subscription.js

@@ -0,0 +1,51 @@
+// modules/provisioning/routes/update-subscription.js — POST /provisioning/instances/:id/update-subscription
+// (task 1004150, ADR 0325 decision 5).
+//
+// WHY. Whether the nightly sweep moves an instance on its own was only a line in
+// config/update-subscriptions.json, so the fleet roster could not report it and a restored
+// backup brought back every row with an empty roster. The flag lives on the row now
+// (provisioning_037); this is how an operator arms or disarms it. It changes a rule, never the
+// core: nothing is queued.
+//
+// Its own routes file (declared in module.json) because routes/provisioning.js sits at the
+// size ratchet — the routes/repo-private.js precedent.
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { pool, validateOrRespond, parseId } = api;
+const provisioning = require('../provisioning');
+const { failFrom } = require('../public-refusal');
+
+const log = api.logger('provisioning');
+
+module.exports = function buildUpdateSubscriptionRouter() {
+  const router = express.Router();
+
+  // Body: { subscribed: boolean }. Gate: the 'provisioning.fleet.manage' permission — the fleet's own.
+  router.post('/provisioning/instances/:id/update-subscription', api.requireBuilder, api.requirePermission('provisioning.fleet.manage'), async (req, res) => {
+    const id = parseId(req, res);
+    if (!id) return;
+    if (validateOrRespond(req, res, { subscribed: { type: 'boolean', required: true } }, { strict: true })) return;
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!inst) return res.fail('instance_not_found', 404);
+      const subscribed = req.body.subscribed === true;
+      const was = inst.update_subscribed === true;
+      if (was !== subscribed) {
+        await pool.query('UPDATE provisioning_instances SET update_subscribed = $2, updated_at = now() WHERE id = $1', [id, subscribed]);
+        await provisioning.recordEvent(pool, {
+          instanceId: id, ownerBuilderId: inst.owner_builder_id, event: 'update-subscription-changed',
+          detail: `unattended patch upgrades ${subscribed ? 'armed' : 'disarmed'} by ${req.builder.github_login || req.builder.id}`,
+          actor: `api:fleet:${req.builder.id}`,
+        }).catch(() => {});
+      }
+      res.json({ ok: true, update_subscribed: subscribed, previous: was, changed: was !== subscribed });
+    } catch (err) {
+      log.error('[provisioning] POST /provisioning/instances/:id/update-subscription', err);
+      failFrom(res, err, 'update_subscription_failed');
+    }
+  });
+
+  return router;
+};

package/modules/provisioning/test-project.js

@@ -0,0 +1,65 @@
+'use strict';
+
+// modules/provisioning/test-project.js — a TEST project: one made to try features that are not
+// live yet (task 1005036, idea 1001299; owner, 2026-11-01).
+//
+// A test project is an ordinary project with a mark on it. The mark changes four things and
+// nothing else: it is labelled, it never reaches the public map, it does not count toward a
+// builder's one free hosted project, and it is the only kind that may switch not-yet-live
+// features on (genesis today; the opt-in modules through the hall's own toggle). A project
+// without the mark behaves exactly as before, which is the property the tests pin.
+//
+// WHO MAY MAKE ONE. Archon only — a plain rank test, as route-helpers.js's archon override
+// is, never a permission atom. Unfinished features are for the people building the platform,
+// and a test project is not a way around the one-free-project limit for anyone else.
+//
+// WHERE THE MARK LIVES. The reserved settings-jsonb key `test_project`, stamped once on the
+// row the create route just made (never on an existing row), like `founding_birth` beside it.
+// It is out of SETTINGS_VOCAB, so the settings PATCH cannot write it and effectiveSettings
+// never projects it. It reaches the instance as the companion TEST_PROJECT, which
+// src/branding.js maps onto `project.test` — that is how the hall labels itself and how the
+// instance refuses the feature switches on a project that is not a test one.
+
+const TEST_KEY = 'test_project';
+
+const storedOf = (row) => (row && row.settings && typeof row.settings === 'object' && !Array.isArray(row.settings) ? row.settings : {});
+
+// isTestProject(row) — PURE. True only for a row stamped 'on'.
+function isTestProject(row) {
+  return storedOf(row)[TEST_KEY] === 'on';
+}
+
+// parseTestAsk(body, builder) — PURE. What the create request asks for: { ok: true, test, genesis },
+// or { ok: false, status, code, message }. `genesis: true` is the test project's way of being
+// born with genesis on, so it means nothing without `test: true`.
+function parseTestAsk(body, builder) {
+  const b = body && typeof body === 'object' ? body : {};
+  const test = b.test === true;
+  const genesis = b.genesis === true;
+  if (genesis && !test) {
+    return { ok: false, status: 400, code: 'genesis_needs_test', message: 'Genesis is only switched on for a test project: send "test": true as well.' };
+  }
+  if (test && !(builder && builder.rank === 'archon')) {
+    return { ok: false, status: 403, code: 'test_project_forbidden', message: 'Only an archon can create a test project.' };
+  }
+  return { ok: true, test, genesis };
+}
+
+// stampTestProject(db, instanceId) — the create route's one write, on the row it just made.
+// Write-once: a mark already there is kept (the WHERE says so).
+async function stampTestProject(db, instanceId) {
+  await db.query(
+    `UPDATE provisioning_instances
+        SET settings = COALESCE(settings, '{}'::jsonb) || jsonb_build_object($2::text, 'on')
+      WHERE id = $1 AND NOT (COALESCE(settings, '{}'::jsonb) ? $2::text)`,
+    [instanceId, TEST_KEY],
+  );
+}
+
+// The companion env (SETTINGS_COMPANION_ENV): 'on' for a test project, empty for every other,
+// so the runner's in-place patch never leaves a stale line behind.
+const TEST_COMPANION_ENV = Object.freeze({
+  TEST_PROJECT: (row) => (isTestProject(row) ? 'on' : ''),
+});
+
+module.exports = { isTestProject, parseTestAsk, stampTestProject, TEST_COMPANION_ENV };

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.25.4",
+  "version": "1.25.6",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.25.4",
+      "version": "1.25.6",
       "license": "AGPL-3.0-or-later",
       "dependencies": {
         "express": "^4.21.2",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.25.4",
+  "version": "1.25.6",
   "description": "Cloud Bongos — the AI-first build platform core (GDS + platform surfaces + module system), installed as a versioned dependency (ADR 0108).",
   "license": "AGPL-3.0-or-later",
   "main": "src/platform-server.js",

package/release-notes.json

@@ -11718,5 +11718,25 @@
       "id": "1005249",
       "text": "Your details now sit on your character at the bottom left of the game: hover to see them, click to open your full profile without leaving the scene. The old profile card at the top right is gone."
     }
+  ],
+  "1.25.5": [
+    {
+      "id": "1004748",
+      "text": "Archon can now switch on a card requirement for a builder who has registered a card, with every change recorded."
+    },
+    {
+      "id": "1004150",
+      "text": "The fleet view can now show which projects get automatic patch upgrades, and the nightly upgrade run says so out loud when it has nothing to do."
+    }
+  ],
+  "1.25.6": [
+    {
+      "id": "1005036",
+      "text": "An archon can now create a test project: a project marked for trying features that are not finished. It stays off the public map, does not use up anyone's one free hosted project, and is the only kind where the guided setup ca"
+    },
+    {
+      "id": "1005219",
+      "text": "Opening the builders' hall now starts on the Game or Classic choice. Signed out, your pick takes you to sign in and then straight to that menu."
+    }
   ]
 }

package/scripts/bongos/government-walk.js

@@ -610,8 +610,8 @@ async function runWalk() {
   const instanceRoot = fs.mkdtempSync(path.join(os.tmpdir(), 'government-walk-'));
   process.env.BONGOS_INSTANCE_ROOT = instanceRoot;
   delete process.env.DATABASE_URL; // the walk never touches a real database
-  // The modules' info lines (a fence switched, a budget set) would bury the table.
-  if (!process.env.LOG_LEVEL) process.env.LOG_LEVEL = 'warn';
+  process.env.BONGOS_TEST_PROJECT = 'on'; // a TEST project: only one starts genesis by hand (task 1005036)
+  if (!process.env.LOG_LEVEL) process.env.LOG_LEVEL = 'warn'; // info lines would bury the table
 
   const req = (rel) => require(path.join(ROOT, rel));
   const api = req('src/module-api.js');

package/scripts/bongos/update-channel.js

@@ -333,13 +333,14 @@ function loadSubscriptions({ instanceDir = process.cwd(), fsImpl = fs, file = SU
 const CHANNEL_DB_ENV = 'UPDATE_CHANNEL_DB';
 const CHANNEL_SOURCE_DEPLOY = 'deploy';
 const CHANNEL_SOURCE_ROSTER = 'roster';
-const DB_CHANNELS_SQL = 'SELECT slug, update_channel FROM provisioning_instances';
+const DB_CHANNELS_SQL = 'SELECT slug, update_channel, update_subscribed FROM provisioning_instances';
 const DB_CHANNELS_TIMEOUT_MS = 15000;
 
 // PURE. psql's stderr reduced to a class that is safe to log.
 function psqlFailureClass(stderr) {
   const s = String(stderr || '');
   if (/relation .*provisioning_instances.* does not exist/i.test(s)) return 'no provisioning_instances table (provisioning module off?)';
+  if (/column .*update_subscribed.* does not exist/i.test(s)) return 'no update_subscribed column (migration provisioning_037 not applied)';
   if (/column .*update_channel.* does not exist/i.test(s)) return 'no update_channel column (migration provisioning_029 not applied)';
   if (/authentication failed|role .* does not exist|permission denied/i.test(s)) return 'the sweep\'s database login was refused';
   if (/could not connect|connection refused|no such file or directory|could not translate host/i.test(s)) return 'database unreachable';
@@ -366,11 +367,32 @@ function readDbChannels({ env = process.env, run = spawnSync } = {}) {
   }
   if (r.status !== 0) return { ok: false, reason: `psql exit ${r.status}: ${psqlFailureClass(r.stderr)}` };
   const channels = new Map();
+  const subscribed = new Map();
   for (const line of String(r.stdout || '').split('\n')) {
-    const [slug, ch] = line.split('\t');
-    if (slug && ch) channels.set(slug.trim(), ch.trim());
+    const [slug, ch, sub] = line.split('\t');
+    if (!slug || !ch) continue;
+    channels.set(slug.trim(), ch.trim());
+    subscribed.set(slug.trim(), String(sub || '').trim() === 't');
   }
-  return { ok: true, channels };
+  return { ok: true, channels, subscribed };
+}
+
+// PURE. Merge the two places a subscription can be written: the project row
+// (provisioning_instances.update_subscribed, task 1004150) and the roster file. The file is an
+// OVERRIDE — an entry in it is subscribed whatever the row says, so an operator's current arming
+// is not dropped — but a row subscribed with NO file entry can't be upgraded (the file carries the
+// `dir`), and it is returned in `unreachable` rather than vanishing, because "subscribed on the
+// fleet view, never touched by the sweep" is the silent failure this column exists to end.
+function applyDbSubscriptions(instances, db) {
+  const subscribed = db && db.ok && db.subscribed instanceof Map ? db.subscribed : null;
+  const slugs = new Set(instances.map((i) => i.slug));
+  const out = instances.map((inst) => {
+    if (!subscribed) return { ...inst, subscribedSource: CHANNEL_SOURCE_ROSTER };
+    if (subscribed.get(inst.slug) === true) return { ...inst, subscribedSource: CHANNEL_SOURCE_DEPLOY };
+    return { ...inst, subscribedSource: CHANNEL_SOURCE_ROSTER, subscribedNote: 'subscribed by the roster file only (the project row says not subscribed)' };
+  });
+  const unreachable = subscribed ? [...subscribed].filter(([slug, on]) => on && !slugs.has(slug)).map(([slug]) => slug) : [];
+  return { instances: out, unreachable };
 }
 
 // PURE. Give each roster entry the channel it is actually under, and say where it came from:
@@ -496,6 +518,7 @@ module.exports = {
   readDbChannels,
   CHANNEL_DB_ENV,
   applyDbChannels,
+  applyDbSubscriptions,
   channelLine,
   psqlFailureClass,
   CHANNEL_SOURCE_DEPLOY,

package/scripts/bongos/update-sweep.js

@@ -593,16 +593,29 @@ function main({ instanceRoot: defaultRoot = process.cwd() } = {}) {
   // CONTROL PLANE's database — this process's own env, never an entry's `env`, which points at that
   // instance's database. A core too old to carry the reader keeps the roster, as before.
   const db = typeof channel.readDbChannels === 'function' ? channel.readDbChannels({ env: process.env }) : null;
-  const instances = db ? channel.applyDbChannels(loaded.instances, db) : loaded.instances;
-  if (db && !db.ok && instances.length) console.log(`  • update rules: read from the roster — ${db.reason}`);
+  const withChannels = db ? channel.applyDbChannels(loaded.instances, db) : loaded.instances;
+  if (db && !db.ok && withChannels.length) console.log(`  • update rules: read from the roster — ${db.reason}`);
+  // Who is subscribed is also on the project row (task 1004150). The roster file stays an override.
+  const merged = db && typeof channel.applyDbSubscriptions === 'function'
+    ? channel.applyDbSubscriptions(withChannels, db) : { instances: withChannels, unreachable: [] };
+  const instances = merged.instances;
 
   const roster = only ? instances.filter((i) => i.slug === only || i.dir === only) : instances;
   const mode = apply ? 'apply' : 'dry-run';
   console.log(`core-update-subscription (${mode}) — ${roster.length} subscribed instance(s)${present ? '' : ' [no roster file — nothing subscribed]'}`);
-  for (const inst of roster) if (inst.channelNote) console.log(channel.channelLine(inst));
+  for (const inst of roster) {
+    if (inst.channelNote) console.log(channel.channelLine(inst));
+    if (inst.subscribedNote) console.log(`  • ${inst.slug}: ${inst.subscribedNote}`);
+  }
   if (only && roster.length === 0) console.error(`  ! --only ${only} matched no subscribed instance`);
 
   let upgraded = 0, skipped = 0, failed = 0, upToDate = 0, healed = 0;
+  // Subscribed on the project row but absent from this roster: there is no `dir` to upgrade, so say
+  // so and count it a skip. Silence here is how a restored backup reported failed=0 on a dead sweep.
+  for (const slug of only ? [] : merged.unreachable) {
+    console.error(`  ! ${slug}: subscribed on its project row, but this roster has no entry with a dir for it — not upgraded`);
+    skipped++;
+  }
   const refusalsFile = refusalsPath();
   const refusals = readRefusals(refusalsFile);
 
@@ -817,6 +830,7 @@ function main({ instanceRoot: defaultRoot = process.cwd() } = {}) {
     upgraded++;
   }
 
+  if (!only && roster.length === 0 && skipped === 0) console.log('\ncore-update-subscription: NOTHING SUBSCRIBED — no instance was considered, so no upgrade was attempted (this is not a clean run).');
   console.log(`\ncore-update-subscription: upgraded=${upgraded} up-to-date=${upToDate} skipped=${skipped} failed=${failed}${healed ? ` healed=${healed}` : ''} (${mode})`);
   return failed > 0 ? 1 : 0;
 }

package/src/bongos/api-errors.js

@@ -89,6 +89,8 @@ const OVERRIDES = Object.freeze({
   bfg_write_disabled: 'forbidden',
   target_is_system_principal: 'forbidden',
   cannot_change_own_tester: 'forbidden',
+  cannot_disable_own_card_requirement: 'forbidden',
+  no_card_registered: 'conflict',
   self_vote_forbidden: 'forbidden',
   self_dep: 'conflict',
   newcomer_must_ship_first: 'forbidden',

package/src/bongos/db.js

@@ -724,6 +724,48 @@ async function setBuilderTester({ builderId, isTester }) {
   });
 }
 
+// setRequireCard — an Archon switches the hardware-card requirement on or off for one
+// builder (task 1004748, ADR 0382 D3/D4). Switching ON needs at least one registered
+// card, so nobody is locked out by the switch. The audit row is written in the SAME
+// transaction as the flag, so a change cannot happen without its entry; unlike the
+// generic request log it names the builder it was done TO.
+async function setRequireCard({ builderId, required, actorBuilderId, ip = null, userAgent = null }) {
+  return withTx(async (client) => {
+    const { rows: found } = await client.query(
+      `SELECT id, system_role, require_card FROM builders WHERE id = $1 FOR UPDATE`,
+      [builderId]
+    );
+    const before = found[0];
+    if (!before) return null;
+    if (before.system_role) throw { code: 'TARGET_IS_SYSTEM_PRINCIPAL' };
+    if (required) {
+      const { rows: cards } = await client.query(
+        `SELECT 1 FROM passkey_credentials WHERE builder_id = $1 LIMIT 1 FOR SHARE`,
+        [builderId]
+      );
+      if (!cards[0]) throw { code: 'NO_CARD_REGISTERED' };
+    }
+    const { rows } = await client.query(
+      `UPDATE builders SET require_card = $2 WHERE id = $1
+       RETURNING id, github_login, display_name, rank, status, require_card`,
+      [builderId, !!required]
+    );
+    await client.query(
+      `INSERT INTO audit_log
+         (builder_id, route, method, request_body_redacted, response_status, ip, user_agent, surface)
+       VALUES ($1, $2, 'PATCH', $3, 200, $4, $5, NULL)`,
+      [
+        actorBuilderId,
+        `${require('./api-prefix').API_PREFIX}/builders/:id/card-requirement`,
+        { target_builder_id: String(builderId), require_card: !!required, was: before.require_card === true },
+        ip,
+        userAgent,
+      ]
+    );
+    return rows[0];
+  });
+}
+
 async function reactivateBuilder({ builderId, actorBuilderId }) {
   return withTx(async (client) => {
     const { rows } = await client.query(
@@ -1183,6 +1225,7 @@ module.exports = {
   RANKS,
   setBuilderRank,
   setBuilderTester,
+  setRequireCard,
   getLatestRankChangeForBuilder,
   deactivateBuilder,
   reactivateBuilder,

package/src/bongos/route-rank-check.js

@@ -194,6 +194,7 @@ const EXPECTED_RANKS = {
   // builder authority — rank + lifecycle status mutation
   'PATCH /builders/:id/rank': 'perm:builder.rank.set',
   'PATCH /builders/:id/status': 'perm:builder.status.set',
+  'PATCH /builders/:id/card-requirement': 'perm:builder.rank.set',
   // task 1004561: the Treasury desk sets a builder's monthly limit through it
   'PATCH /builders/:id/budget': 'perm:builder.budget.set',
   // session revocation (kill another builder's / all sessions)

package/src/bongos/routes/builders.js

@@ -421,6 +421,43 @@ module.exports = function buildBuildersRouter() {
     }
   });
 
+  // PATCH /builders/:id/card-requirement — an Archon switches the hardware-card
+  // requirement on or off for one builder (task 1004748, ADR 0382 D4). Body:
+  // { require_card: boolean }. Default is off for everyone. Switching ON refuses 409
+  // no_card_registered unless the builder has a registered card, so the switch cannot
+  // lock anyone out. You cannot switch OFF your own requirement (403
+  // cannot_disable_own_card_requirement) — a stolen session must not be able to drop
+  // it; another Archon does it. Every change writes an audit row naming the target.
+  // rank: archon. Gate: requirePermission('builder.rank.set') (the non-delegable atom that
+  // guards the step-up's own target route) then requireCardStepUp; read fresh per request.
+  router.patch('/builders/:id/card-requirement', auth.requireBuilder, auth.requirePermission('builder.rank.set'), requireCardStepUp, async (req, res) => {
+    if (validateOrRespond(req, res, { require_card: { required: true, type: 'boolean' } })) return;
+    const targetId = parseId(req, res, { code: 'bad_builder_id', positiveInt: true });
+    if (targetId === null) return;
+    const required = req.body.require_card;
+    if (!required && String(targetId) === String(req.builder.id)) {
+      return res.fail('cannot_disable_own_card_requirement', 403);
+    }
+    try {
+      const builder = await db.setRequireCard({
+        builderId: targetId,
+        required,
+        actorBuilderId: req.builder.id,
+        ip: req.ip || null,
+        userAgent: req.headers['user-agent'] || null,
+      });
+      if (!builder) return res.fail('builder_not_found', 404);
+      res.json({ builder });
+    } catch (err) {
+      if (err && err.code === 'TARGET_IS_SYSTEM_PRINCIPAL') return res.fail('target_is_system_principal', 403);
+      if (err && err.code === 'NO_CARD_REGISTERED') {
+        return res.fail('no_card_registered', 409, { message: 'That builder has no registered card yet; they must register one before the requirement can be switched on.' });
+      }
+      log.error('[gds] PATCH /builders/:id/card-requirement', err);
+      res.fail('card_requirement_change_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // PATCH /builders/:id/capabilities — the owner gives or takes a builder's server
   // access (task 1004950, ADR 0395). Body: { server: boolean }. A task that needs
   // the server is shown to and claimable by a builder only while this is on.

package/src/branding.js

@@ -94,6 +94,9 @@ const ENV_OVERRIDES = [
   ['NIGHT_TINT', ['project', 'nightTint']],
   ['LOOK_ACCENT', ['project', 'lookAccent']],
   ['LOGO_URL', ['project', 'logoUrl']],
+  // 'on' only on a TEST project (task 1005036, modules/provisioning/test-project.js): the hall labels itself
+  // and the not-yet-live feature switches open. Empty on every other project.
+  ['TEST_PROJECT', ['project', 'test']],
   // The birth marker (task 1004506): set by the platform only on a project created
   // through the startup flow, so a project made before that never has it (spec D8).
   // FOUNDING_BIRTH is when the platform made the row; DEMO_PEOPLE / DEMO_HOURS are the
@@ -258,6 +261,10 @@ function clientBranding(b = branding()) {
         mark: b.identity?.company?.mark || '',
       },
     },
+    // A TEST project (task 1005036, modules/provisioning/test-project.js): the hall labels itself and the
+    // not-yet-live feature switches open. Beside `project`, not in it: that block is the settings the
+    // platform pushes, key for key, and this is a mark, not a setting.
+    testProject: b.project?.test === 'on',
     currency: {
       label: b.currency?.label || 'credits',
       symbol: b.currency?.symbol || '',

package/src/module-api.js

@@ -81,7 +81,7 @@ const { sleep } = require('./sleep');
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.25.4'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.25.6'; // 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/builder_card_requirement.mjs

@@ -0,0 +1,75 @@
+// tests/builder_card_requirement.mjs
+//
+// Task 1004748 (ADR 0382 D3/D4) — an Archon switches the hardware-card requirement on
+// per builder. DB-free: the shared pool's client is a recorder.
+//
+// Run:  node tests/builder_card_requirement.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+import { makeRunner } from './helpers.mjs';
+
+const require = createRequire(import.meta.url);
+const { pool } = require('../src/bongos/pool');
+const { test, summary } = makeRunner();
+
+let builderRow; let hasCard; const sent = [];
+pool.connect = async () => ({
+  query: async (sql, params = []) => {
+    const q = String(sql);
+    sent.push({ sql: q, params });
+    if (/^\s*(BEGIN|COMMIT|ROLLBACK)/i.test(q)) return { rows: [] };
+    if (/FROM builders WHERE id/.test(q)) return { rows: builderRow ? [builderRow] : [] };
+    if (/FROM passkey_credentials/.test(q)) return { rows: hasCard ? [{}] : [] };
+    if (/UPDATE builders SET require_card/.test(q)) return { rows: [{ id: params[0], require_card: params[1] }] };
+    return { rows: [] };
+  },
+  release() {},
+});
+
+const { setRequireCard } = require('../src/bongos/db');
+const reset = () => { sent.length = 0; };
+
+await test('switching on refuses a builder with no registered card, writes nothing', async () => {
+  reset(); builderRow = { id: '7', system_role: null, require_card: false }; hasCard = false;
+  await assert.rejects(setRequireCard({ builderId: '7', required: true, actorBuilderId: '1' }), { code: 'NO_CARD_REGISTERED' });
+  assert.equal(sent.some((s) => /UPDATE builders|INSERT INTO audit_log/.test(s.sql)), false);
+});
+
+await test('switching on with a card sets the flag and audits the target in the same transaction', async () => {
+  reset(); hasCard = true;
+  const r = await setRequireCard({ builderId: '7', required: true, actorBuilderId: '1' });
+  assert.equal(r.require_card, true);
+  const audit = sent.find((s) => /INSERT INTO audit_log/.test(s.sql));
+  assert.ok(audit);
+  assert.equal(audit.params[0], '1');
+  assert.deepEqual(audit.params[2], { target_builder_id: '7', require_card: true, was: false });
+});
+
+await test('switching off needs no card and is audited', async () => {
+  reset(); hasCard = false; builderRow = { id: '7', system_role: null, require_card: true };
+  const r = await setRequireCard({ builderId: '7', required: false, actorBuilderId: '1' });
+  assert.equal(r.require_card, false);
+  assert.deepEqual(sent.find((s) => /INSERT INTO audit_log/.test(s.sql)).params[2].was, true);
+});
+
+await test('unknown builder is null; a system principal is refused', async () => {
+  reset(); builderRow = null;
+  assert.equal(await setRequireCard({ builderId: '9', required: false, actorBuilderId: '1' }), null);
+  builderRow = { id: '9', system_role: 'runner', require_card: false };
+  await assert.rejects(setRequireCard({ builderId: '9', required: false, actorBuilderId: '1' }), { code: 'TARGET_IS_SYSTEM_PRINCIPAL' });
+});
+
+await test('route: rank atom + step-up gate, self-disable refused, 409 mapped, errors classified', async () => {
+  const fs = await import('node:fs');
+  const src = fs.readFileSync(new URL('../src/bongos/routes/builders.js', import.meta.url), 'utf8');
+  const line = src.split(/\r?\n/).find((l) => l.includes("router.patch('/builders/:id/card-requirement'"));
+  assert.match(line, /requirePermission\('builder\.rank\.set'\), requireCardStepUp/);
+  assert.match(src, /cannot_disable_own_card_requirement', 403/);
+  assert.match(src, /NO_CARD_REGISTERED[\s\S]{0,80}no_card_registered', 409/);
+  const { classify } = require('../src/bongos/api-errors');
+  assert.equal(classify('no_card_registered'), 'conflict');
+  assert.equal(classify('cannot_disable_own_card_requirement'), 'forbidden');
+});
+
+summary();

package/tests/currency_label.mjs

@@ -84,7 +84,9 @@ test('clientBranding is a SMALL allow-list — no server-only field leaks to the
   // had been failing since that landed (task 1002470).
   // `project` joined the allow-list in task 1003140: the per-project policy is public
   // by nature and is the settings read-back a manage page needs (see clientBranding).
-  assert.deepEqual(Object.keys(projected).sort(), ['copy', 'currency', 'identity', 'project', 'rankLabels', 'reward', 'theme']);
+  assert.deepEqual(Object.keys(projected).sort(), ['copy', 'currency', 'identity', 'project', 'rankLabels', 'reward', 'testProject', 'theme']);
+  // `testProject` joined in task 1005036: the platform's test-project mark ('on' or
+  // not), public by nature: the hall labels itself and opens its not-yet-live switches.
   // `artistGate` joined in task 1003575 (ADR 0241) — the project's artist strictness,
   // public for the same read-back reason as its neighbours. Its companion stamp
   // (artistGateSince) deliberately does NOT: that is platform bookkeeping the server