@bongos/core 1.20.83 → 1.21.1

package/tests/npm_release_release.mjs

@@ -99,6 +99,41 @@ test('an unreadable registry and a missing dispatcher both release nothing, and
   assert.equal((await requestRelease({ version: '1.20.73', registry: REG, dispatch: null })).body.error.code, 'dispatch_unavailable');
 });
 
+// ── the refusal names the credential the server actually uses (task 1004518) ─────────
+
+test('a server on the access token is told to edit the ACCESS TOKEN', async () => {
+  const saved = process.env.GITHUB_PUSH_TOKEN;
+  process.env.GITHUB_PUSH_TOKEN = 'PAT';
+  try {
+    const d = await gp.dispatchWorkflow({ workflow: 'publish.yml' }, { appToken: async () => null, repoInfo: REPO, fetchImpl: async () => ({ ok: false, status: 403 }) });
+    assert.equal(d.credential, 'token');
+    const r = await requestRelease({ version: '1.20.73', registry: REG, dispatch: async () => d });
+    assert.match(r.body.error.message, /access token \(GITHUB_PUSH_TOKEN/);
+    assert.doesNotMatch(r.body.error.message, /GitHub App/);
+  } finally {
+    if (saved === undefined) delete process.env.GITHUB_PUSH_TOKEN; else process.env.GITHUB_PUSH_TOKEN = saved;
+  }
+});
+
+test('a server on a GitHub App is told to edit the APP — the App wins over a token, as resolveToken orders them', async () => {
+  const saved = process.env.GITHUB_PUSH_TOKEN;
+  process.env.GITHUB_PUSH_TOKEN = 'PAT';
+  try {
+    let auth = null;
+    const d = await gp.dispatchWorkflow({ workflow: 'publish.yml' }, {
+      appToken: async () => 'APPTOK', repoInfo: REPO,
+      fetchImpl: async (_u, opts) => { auth = opts.headers.Authorization || opts.headers.authorization; return { ok: false, status: 403 }; },
+    });
+    assert.equal(d.credential, 'app');
+    assert.match(String(auth), /APPTOK/, 'the App token is the one sent');
+    const r = await requestRelease({ version: '1.20.73', registry: REG, dispatch: async () => d });
+    assert.match(r.body.error.message, /the server's GitHub App needs/);
+    assert.doesNotMatch(r.body.error.message, /access token/);
+  } finally {
+    if (saved === undefined) delete process.env.GITHUB_PUSH_TOKEN; else process.env.GITHUB_PUSH_TOKEN = saved;
+  }
+});
+
 test('GitHub refusing for want of Actions: write is named as exactly that', async () => {
   const r = await requestRelease({ version: '1.20.73', registry: REG, dispatch: async () => ({ ok: false, code: 'REFUSED', status: 403 }) });
   assert.equal(r.status, 502);
@@ -113,7 +148,7 @@ test('dispatchWorkflow POSTs ref + inputs to the workflow\'s dispatches endpoint
   let captured = null;
   const fetchImpl = async (url, opts) => { captured = { url, opts, body: JSON.parse(opts.body) }; return { ok: false, status: 204 }; };
   const r = await gp.dispatchWorkflow({ workflow: 'publish.yml', ref: 'main', inputs: { release_version: '1.20.73' } }, { token: 'T', repoInfo: REPO, fetchImpl });
-  assert.deepEqual(r, { ok: true });
+  assert.deepEqual(r, { ok: true, credential: 'token' });
   assert.equal(captured.url, 'https://api.github.com/repos/someowner/somerepo/actions/workflows/publish.yml/dispatches');
   assert.equal(captured.opts.method, 'POST');
   assert.deepEqual(captured.body, { ref: 'main', inputs: { release_version: '1.20.73' } });
@@ -135,7 +170,7 @@ test('dispatchWorkflow: no credential is UNCONFIGURED; a 403 is REFUSED with its
   } finally {
     if (saved !== undefined) process.env.GITHUB_PUSH_TOKEN = saved;
   }
-  assert.deepEqual(await gp.dispatchWorkflow({ workflow: 'publish.yml' }, { token: 'T', repoInfo: REPO, fetchImpl: async () => ({ ok: false, status: 403 }) }), { ok: false, code: 'REFUSED', status: 403 });
+  assert.deepEqual(await gp.dispatchWorkflow({ workflow: 'publish.yml' }, { token: 'T', repoInfo: REPO, fetchImpl: async () => ({ ok: false, status: 403 }) }), { ok: false, code: 'REFUSED', status: 403, credential: 'token' });
   assert.equal((await gp.dispatchWorkflow({ workflow: 'publish.yml' }, { token: 'T', repoInfo: REPO, fetchImpl: async () => { throw new Error('down'); } })).code, 'UNREACHABLE');
 });
 

package/tests/projects_hub.mjs

@@ -765,7 +765,9 @@ test('the table is in the world: a masthead, then ledger rows — no panel, no s
   assert.match(COSMOS, /\.tbl \.tblRow:hover\{border-top-color:var\(--ink-faint\);\}/, 'hover is the hairline taking ink, not an accent tint');
   assert.match(COSMOS, /\.rowGo\{[^}]*border:1px solid var\(--rule\);border-radius:var\(--radius-pill\);/, 'the row\'s door is the mine row\'s hairline pill');
   assert.match(HUB, /<a class="rowGo" href="\/">view<\/a>/, 'the self row\'s door');
-  assert.match(SCRIPT, /'<a class="rowGo" href="' \+ esc\(safeHttpUrl\(p\.origin\)\)/, 'the generated rows\' door');
+  assert.match(SCRIPT, /'<a class="rowGo" href="' \+ esc\(siteHref\(p\)\)/, 'the generated rows\' door');
+  assert.match(SCRIPT, /function siteHref\(p\) \{ return p\._inst && !addressReady\(p\._inst\) \? '' : safeHttpUrl\(p\.origin\); \}/,
+    'scheme-checked, and none for your own project until its address answers (task 1004505)');
   assert.match(COSMOS, /\.mastObj\{display:block;--dia:clamp\(96px,10vw,132px\);[^}]*background-image:var\(--plate-set-cut\);/, 'the object is the set\'s small bead by token, in both modes');
   assert.doesNotMatch(COSMOS, /mix-blend-mode:var\(--mast/, 'the cutout needs no blend — the view wrap is a stacking context');
 });
@@ -1426,7 +1428,7 @@ test('the save sends the choice and shows the platform’s receipt verbatim —
 test('what the project RUNS comes only from its own manifest, and every answer is said', () => {
   const runs = fnHub('loadVisRuns');
   const manifest = fnHub('ensureManifest');
-  assert.match(runs, /inst\.status !== 'active' \|\| !inst\.domain/, 'only a live project with an address can be asked');
+  assert.match(runs, /inst\.status !== 'active' \|\| !addressReady\(inst\)/, 'only a live project whose address answers can be asked (task 1004505)');
   assert.match(manifest, /'https:\/\/' \+ domain \+ '\/api\/bongos\/instance'/,
     'the same public GET /instance the platform’s runner reads after a restart');
   assert.doesNotMatch(runs, /fetch\(/, 'the card fires no GET of its own — one manifest read serves the pair (task 1003554)');
@@ -1631,7 +1633,7 @@ test('the joinability save sends the one key and shows the platform’s receipt
 
 test('what the project RUNS for joinability comes only from its own manifest, and every answer is said', () => {
   const runs = fnHub('loadJoinRuns');
-  assert.match(runs, /inst\.status !== 'active' \|\| !inst\.domain/, 'only a live project with an address can be asked');
+  assert.match(runs, /inst\.status !== 'active' \|\| !addressReady\(inst\)/, 'only a live project whose address answers can be asked (task 1004505)');
   assert.match(runs, /ensureManifest\(inst\.domain\)/, 'the same public GET /instance the runner reads, through the shared reader');
   assert.doesNotMatch(runs, /fetch\(/, 'the second card of the pair adds no round trip of its own (task 1003554)');
   assert.match(runs, /p && p\.joinability/, 'the manifest key is brand.project.joinability');

package/tests/projects_hub_dns_ready.mjs

@@ -0,0 +1,153 @@
+// tests/projects_hub_dns_ready.mjs
+//
+// No address link renders before the platform's own lookup answers (task 1004505,
+// BV2.PS17). A founder's first click on a name that does not resolve yet is cached as
+// "not found" by their resolver for the zone's negative TTL (30 minutes on
+// cloudbongos.com), so the hub holds every door to the address until the instance read
+// carries `dns_resolves` (the server's sighting — modules/provisioning/dns-resolves.js)
+// or a verified up probe. The status alone, 'active' included, is never enough.
+//
+// EXECUTED by the vm-slice idiom: the done panel's renderProgress, the card's
+// addressRow and the row's orbFor are sliced verbatim out of projects.html and run
+// under a narrow stub, and the markup they write is read back. Every slice boundary is
+// asserted, so a rename fails loudly instead of testing nothing. vm-born values are
+// compared as primitives or through JSON.
+//
+// The runner half (the record is created first) is tests/provision_dns_first.mjs.
+//
+// Run:  node tests/projects_hub_dns_ready.mjs
+
+import { test } from 'node:test';
+import { strict as assert } from 'node:assert';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import { fileURLToPath } from 'node: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');
+
+function slice(from, to) {
+  const a = HUB.indexOf(from);
+  const b = HUB.indexOf(to, a + 1);
+  assert.ok(a > 0, `slice start must exist: ${from}`);
+  assert.ok(b > a, `slice end must follow it: ${to}`);
+  return HUB.slice(a, b);
+}
+
+const PROGRESS = slice('var PROG_FLOWS = {', 'function startProgress(');
+const OVERLAY = slice('function verifiedAt(inst)', 'function chipMarkup(');
+const ADDRESS = slice('var ADDRESS_SETTING_UP', 'function publishRow(');
+const ORB = slice('function orbFor(', '/* ── progress strips');
+for (const [name, region] of [['renderProgress', PROGRESS], ['addressReady', OVERLAY], ['addressRow', ADDRESS], ['orbFor', ORB]]) {
+  assert.ok(region.includes(`function ${name}(`), `the slice must carry ${name}`);
+}
+
+function boot() {
+  const liveProgress = { innerHTML: '' };
+  const sandbox = {
+    $: (id) => (id === 'liveProgress' ? liveProgress : null),
+    esc: (s) => String(s == null ? '' : s).replace(/[&<>"']/g, (c) => (
+      { '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])),
+    projectPageLink: (label) => '<a href="?view=manage&id=1">' + label + '</a>',
+    relTime: () => '2 minutes ago',
+    canRestart: () => false,
+    planetOf: () => ({ tpl: 'blob-tint', acc: 'var(--a1)' }),
+    planetAttrs: () => '',
+    FRESH_MS: 12 * 60 * 1000,
+    LIVE_MOMENT_MS: 10 * 60 * 1000,
+    lastProgHtml: '',
+  };
+  vm.createContext(sandbox);
+  vm.runInContext(PROGRESS + '\n' + OVERLAY + '\n' + ADDRESS + '\n' + ORB, sandbox);
+  return { sandbox, progress: () => liveProgress.innerHTML };
+}
+
+const NOW = () => new Date().toISOString();
+const base = { id: 1, slug: 'lantern', status: 'active', domain: 'lantern.cloudbongos.com', last_verified_at: null, last_verified_up: null, dns_note: null };
+const ADDRESS_LINK = /<a [^>]*href="https:\/\/lantern\.cloudbongos\.com/;
+
+test('active but not yet resolved: the done panel holds the link, says so, and keeps watching', () => {
+  const h = boot();
+  const terminal = h.sandbox.renderProgress({ ...base, dns_resolves: false });
+  assert.equal(terminal, false, 'the panel keeps polling until the lookup answers');
+  assert.doesNotMatch(h.progress(), ADDRESS_LINK);
+  assert.doesNotMatch(h.progress(), /lantern\.cloudbongos\.com/, 'and does not even name it to be typed');
+  assert.match(h.progress(), /your address is being set up/);
+});
+
+test('a down probe on a never-resolved address is still "being set up", never a link', () => {
+  const h = boot();
+  h.sandbox.renderProgress({ ...base, dns_resolves: false, last_verified_up: false, last_verified_at: NOW() });
+  assert.doesNotMatch(h.progress(), ADDRESS_LINK);
+  assert.match(h.progress(), /being set up/);
+});
+
+test('once the lookup answers, the done panel links the address', () => {
+  const h = boot();
+  const terminal = h.sandbox.renderProgress({ ...base, dns_resolves: true });
+  assert.equal(terminal, false, 'resolving is not yet answering — the panel still waits for the probe');
+  assert.match(h.progress(), ADDRESS_LINK);
+  const live = boot();
+  assert.equal(live.sandbox.renderProgress({ ...base, dns_resolves: true, last_verified_up: true, last_verified_at: NOW() }), true);
+  assert.match(live.progress(), ADDRESS_LINK);
+});
+
+test('the card and the manage page: no link and no name before the lookup answers, in every pre-live state', () => {
+  const { sandbox } = boot();
+  for (const status of ['requested', 'provisioning', 'active']) {
+    const row = sandbox.addressRow({ ...base, status, dns_resolves: false });
+    assert.doesNotMatch(row, /<a /, `${status}: no link`);
+    assert.doesNotMatch(row, /lantern\.cloudbongos\.com/, `${status}: no name`);
+    assert.equal(row, sandbox.ADDRESS_SETTING_UP, `${status}: the being-set-up line`);
+    assert.doesNotMatch(sandbox.addressRow({ ...base, status, dns_resolves: false }, true), /<a /, `${status}: the manage page too`);
+  }
+});
+
+test('the card links the address once it resolves, and keeps a verified-up project linked', () => {
+  const { sandbox } = boot();
+  assert.match(sandbox.addressRow({ ...base, dns_resolves: true }), ADDRESS_LINK);
+  assert.match(sandbox.addressRow({ ...base, last_verified_up: true, last_verified_at: NOW() }), ADDRESS_LINK, 'an up probe is the same proof');
+});
+
+test('a manual-DNS note still names the address (pointing it is the owner\'s step) but never links it', () => {
+  const { sandbox } = boot();
+  const note = 'Automatic DNS isn\'t set up on this platform — point it at your server.';
+  for (const status of ['provisioning', 'active']) {
+    const row = sandbox.addressRow({ ...base, status, dns_resolves: false, dns_note: note });
+    assert.match(row, /<code>lantern\.cloudbongos\.com<\/code>/);
+    assert.doesNotMatch(row, /<a /);
+  }
+});
+
+test('the row\'s planet opens the site only once the address answers', () => {
+  const { sandbox } = boot();
+  assert.match(sandbox.orbFor({ ...base, dns_resolves: false }), /^<span /);
+  assert.match(sandbox.orbFor({ ...base, dns_resolves: true }), /^<a [^>]*href="https:\/\/lantern\.cloudbongos\.com"/);
+});
+
+test('addressReady: a domain plus a sighting or an up probe — never the status alone', () => {
+  const { sandbox } = boot();
+  const cases = [
+    [{ ...base }, false],
+    [{ ...base, dns_resolves: true }, true],
+    [{ ...base, last_verified_up: true }, true],
+    [{ ...base, last_verified_up: false }, false],
+    [{ ...base, domain: null, dns_resolves: true }, false],
+  ];
+  assert.equal(JSON.stringify(cases.map(([i]) => sandbox.addressReady(i))), JSON.stringify(cases.map(([, want]) => want)));
+});
+
+test('every door to the address on the page asks addressReady', () => {
+  const SCRIPT = HUB;
+  assert.match(SCRIPT, /inst\.status === 'active' && addressReady\(inst\)\) acts\.push\('<a class="btn small ghost" href="https:\/\/' \+ esc\(inst\.domain\) \+ '" target="_blank" rel="noopener">View<\/a>'\)/, 'the row\'s View');
+  assert.match(SCRIPT, /inst\.status === 'active' && addressReady\(inst\)\) acts\.push\('<a class="btn small ghost" href="https:\/\/' \+ esc\(inst\.domain\) \+ '" target="_blank" rel="noopener">Open site →<\/a>'\)/, 'the manage page\'s Open site');
+  assert.match(SCRIPT, /live\.instStatus !== 'active' \|\| !live\.addrReady \|\| live\.manifest !== 'done'/, 'first sign-in and the hall step stay locked');
+  assert.match(SCRIPT, /live\.addrReady = addressReady\(inst\); renderSteps\(\);/, 'and unlock on the tick the lookup answers');
+  assert.equal((SCRIPT.match(/inst\.status !== 'active' \|\| !addressReady\(inst\)\) \{ (vis|join)Runs\(''\); return; \}/g) || []).length, 2,
+    'the browser\'s own manifest reads wait for the name too');
+  // the only raw address hrefs left are behind one of those gates
+  const raw = SCRIPT.match(/href="https:\/\/' \+ esc\(inst\.domain\)/g) || [];
+  assert.equal(raw.length, 4, 'orb, the card link, View and Open site — each gated above or in addressRow');
+});

package/tests/projects_hub_pre_uat.mjs

@@ -67,7 +67,11 @@ test('addressRow branches by state before it trusts the domain — torn down and
   assert.doesNotMatch(body, /shows an error page/, 'the pre-park promise is gone — teardown removes the proxy block that served it');
   assert.match(body, /if \(inst\.status === 'error'\) return 'Address <code>/, 'snagged has its own line');
   assert.match(body, /nothing is answering there yet/);
-  assert.equal((body.match(/— it answers there once the instance is live\.'/g) || []).length, 1, 'the standup promise survives only for queued / standing-up');
+  // task 1004505: a queued or standing-up project no longer names its address — the
+  // name is held, with the link, until the platform's own lookup has seen it answer
+  assert.doesNotMatch(body, /it answers there once the instance is live/, 'the old pre-live line named an address that may not resolve yet');
+  assert.match(body, /if \(!addressReady\(inst\)\) \{/, 'an active project without a sighting is held too');
+  assert.match(SCRIPT, /var ADDRESS_SETTING_UP = 'Your address is being set up — it shows here, with a link, as soon as it answers\.';/);
   assert.match(body, /We keep checking every few minutes/, 'an unreachable project says what the platform is doing');
 });
 
@@ -185,7 +189,7 @@ test('First sign-in and Enter your builders hall unlock only when the project an
   const first = fn('renderStepFirstSignIn');
   const hall = fn('renderStepEnterHall');
   for (const [name, body] of [['first-sign-in', first], ['enter-hall', hall]]) {
-    assert.match(body, /live\.instStatus !== 'active' \|\| live\.manifest !== 'done'/, `${name} gates on both`);
+    assert.match(body, /live\.instStatus !== 'active' \|\| !live\.addrReady \|\| live\.manifest !== 'done'/, `${name} gates on status, a resolving address (task 1004505) and sign-in`);
     assert.match(body, /class="slocked"/, `${name} has a locked rendering`);
   }
   assert.match(first, /Unlocks once your project is answering and sign-in above is wired/);
@@ -357,8 +361,8 @@ test('the row carries two doors and nothing that acts; the address field is a se
   assert.doesNotMatch(card, /<button/, 'no sender survives on a row');
   assert.doesNotMatch(card, /attachFold|<div class="attach">/, 'and no field either');
   assert.match(card, /'<div class="actions">' \+ acts\.join\(''\)/, 'one doors strip, always rendered');
-  assert.match(card, /inst\.status === 'active' && inst\.domain\) acts\.push\([\s\S]{0,180}>View<\/a>'\)/,
-    'View only where the project is live and has an address to open');
+  assert.match(card, /inst\.status === 'active' && addressReady\(inst\)\) acts\.push\([\s\S]{0,180}>View<\/a>'\)/,
+    'View only where the project is live and its address answers (task 1004505)');
   assert.match(card, /acts\.push\('<a class="btn small ghost" data-manage="' \+ iid \+ '" href="\?view=manage&id=' \+ iid \+ '">Manage<\/a>'\);/,
     'Manage on every row, as a real link');
   // the section on the manage page: the heading is the disclosure, so the field
@@ -730,7 +734,7 @@ test('the done panel re-learns the GitHub-App leg from the instance read, yieldi
   assert.match(sp, /if \(ga\.app_slug\) live\.appSlug = ga\.app_slug;\n\s*live\.manifest = seeded;/);
   assert.match(sp, /if \(seedChanged\) \{ rememberManifest\(undefined, live\.manifest, live\.appSlug \|\| undefined\); renderSteps\(\); \}/, 'change-only: an identical tick neither rewrites the bridge nor re-renders');
   const seedAt = sp.indexOf('var ga = data.github_app;');
-  const statusAt = sp.indexOf("if (inst && inst.status !== live.instStatus)");
+  const statusAt = sp.indexOf("if (inst && (inst.status !== live.instStatus || addressReady(inst) !== live.addrReady))");
   assert.ok(seedAt > 0 && seedAt < statusAt, 'the manifest seed lands before the status re-render, so one renderSteps() paints both');
   /* the bridge moved from enter() to enterCreated() when task 1003503 split the
      created-record branch out — same seed, same place in the same flow */

package/tests/provision_dns_first.mjs

@@ -0,0 +1,171 @@
+// tests/provision_dns_first.mjs
+//
+// A new project's address never gets stuck on "site can't be reached" (task 1004505,
+// BV2.PS17). Live on 2026-10-01: a project took 3.6 minutes to stand up, its DNS
+// record was created partway through, and the founder's first click — offered early
+// by the hub — reached a home resolver before the record existed. That resolver cached
+// the "not found" for the zone's negative TTL (1800s on cloudbongos.com), so the
+// project stayed unreachable on that network for up to half an hour after it was live.
+//
+// What these tests pin, at unit altitude (a live project cannot be created here):
+//   • the runner's DNS UPSERT is its FIRST mutation — before the status flips to
+//     'provisioning', before any command on the box, before any file is written, and
+//     so before anything that can make the address visible or reachable;
+//   • a DNS failure stops the run before anything else was touched;
+//   • at the end of the standup the runner asks its own resolver once and records the
+//     answer (dns_resolves), before the row reads 'active' — only for a record it made.
+// The hub half (no address link until dns_resolves) is tests/projects_hub_dns_ready.mjs.
+//
+// Hermetic: recorded executors, a fake db, no shell, no network.
+//
+// Run:  node tests/provision_dns_first.mjs
+
+import { strict as assert } from 'node:assert';
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+// The app-user preflight reads the account this runs as; pin a valid one so the run
+// reaches the steps under test on any machine.
+process.env.PROVISION_APP_USER = 'bongos';
+const P = require('../scripts/gds/provision.js');
+
+let passed = 0, failed = 0;
+async function ta(name, fn) {
+  try { await fn(); passed++; console.log(`  PASS  ${name}`); }
+  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+}
+
+const HOOK = '/opt/infra/box-dns-cloudflare.sh';
+const MEMINFO = 'MemTotal:        2015216 kB\nMemAvailable:    1135180 kB\n';
+const lantern = { id: 7, slug: 'lantern', hosting_shape: 'co-tenant', status: 'requested', owner_builder_id: 3, port: 3003, db_name: 'lantern', domain: 'lantern.cloudbongos.com', target_ref: null };
+
+// One ordered ledger across both executors, the file writes and the status writes.
+function rig({ apply = true, hookThrows = false, answers = true } = {}) {
+  const events = [], logs = [];
+  const deps = {
+    apply, log: (m) => logs.push(String(m)),
+    db: { query: async (sql) => (/count\(\*\)/.test(sql) ? { rows: [{ n: 1 }] } : { rows: [] }) },
+    provisioning: {
+      setInstanceStatus: async (_db, _id, status) => { events.push({ where: 'status', status }); },
+      recordEvent: async () => {},
+      recordDnsNote: async () => {},
+      lookupAnswers: async (host) => { events.push({ where: 'lookup', host }); return answers; },
+      recordDnsResolved: async (_db, id) => { events.push({ where: 'resolved', id }); },
+    },
+    exec: (cmd, opts) => { events.push({ where: 'box', cmd, env: opts && opts.env }); return { ok: true, stdout: /meminfo/.test(cmd) ? MEMINFO : '' }; },
+    controlExec: (cmd, opts) => {
+      events.push({ where: 'control', cmd, env: opts && opts.env });
+      if (hookThrows && cmd === HOOK) throw new Error('zone not reachable');
+      return { ok: true, stdout: '' };
+    },
+    writeFile: (p) => { events.push({ where: 'write', path: p }); return { ok: true }; },
+    controlWriteFile: (p) => { events.push({ where: 'write', path: p }); return { ok: true }; },
+    checkDnsTokenScope: async () => ({ reachable: true, zone: 'cloudbongos.com' }),
+    checkCaddyWiring: () => null,
+    sleep: async () => {},
+  };
+  const at = (pred) => events.findIndex(pred);
+  const hookAt = () => at((e) => e.cmd === HOOK);
+  return { deps, events, logs, at, hookAt };
+}
+
+async function withHook(hook, fn) {
+  const saved = P.CONFIG.dnsHook, savedIp = P.CONFIG.publicIp;
+  P.CONFIG.dnsHook = hook;
+  P.CONFIG.publicIp = '203.0.113.9';
+  try { return await fn(); } finally { P.CONFIG.dnsHook = saved; P.CONFIG.publicIp = savedIp; }
+}
+
+console.log('the DNS record comes first:');
+
+await ta('the UPSERT runs before the status flips, before any box command that changes it, and before any file is written', async () => {
+  await withHook(HOOK, async () => {
+    const r = rig();
+    const res = await P.provisionInstance(lantern, r.deps);
+    assert.equal(res.ok, true, JSON.stringify(res));
+    const hook = r.hookAt();
+    assert.ok(hook >= 0, 'the record was created');
+    assert.deepEqual(r.events[hook].env, { BOX_HOSTNAME: 'lantern.cloudbongos.com', BOX_IP: '203.0.113.9', CLOUDFLARE_ZONE: 'cloudbongos.com', BOX_PROXIED: '0' });
+    assert.equal(r.events[hook].where, 'control', 'the Cloudflare token never leaves the control plane');
+    const provisioning = r.at((e) => e.status === 'provisioning');
+    const active = r.at((e) => e.status === 'active');
+    assert.ok(hook < provisioning, `DNS (${hook}) before the provisioning flip (${provisioning})`);
+    assert.ok(provisioning < active, 'and the run still ends active');
+    const firstWrite = r.at((e) => e.where === 'write');
+    assert.ok(firstWrite > hook, 'web.env and the Caddy snippet are written after the record exists');
+    const caddyWrite = r.at((e) => e.where === 'write' && /lantern\.caddy$/.test(e.path));
+    const reload = r.at((e) => /systemctl reload caddy/.test(e.cmd || ''));
+    assert.ok(caddyWrite > hook && reload > hook, 'the address is made reachable only after its record exists');
+    // Every box command before the record is a read-only preflight question.
+    for (const e of r.events.slice(0, hook)) {
+      assert.ok((e.where === 'box' || e.where === 'control') && !/createdb|useradd|systemctl (enable|reload|restart)|install /.test(e.cmd), `nothing mutating before DNS: ${JSON.stringify(e)}`);
+    }
+  });
+});
+
+await ta('a DNS failure stops the run before the status flips and before anything is written', async () => {
+  await withHook(HOOK, async () => {
+    const r = rig({ hookThrows: true });
+    await assert.rejects(() => P.provisionInstance(lantern, r.deps), /zone not reachable/);
+    assert.equal(r.events.filter((e) => e.where === 'status').length, 0, 'no status write');
+    assert.equal(r.events.filter((e) => e.where === 'write').length, 0, 'no file written');
+    assert.ok(!r.events.some((e) => /createdb|systemctl/.test(e.cmd || '')), 'no database, no unit');
+  });
+});
+
+await ta('dry run: the plan names the DNS step before the server, database and Caddy steps', async () => {
+  await withHook(HOOK, async () => {
+    const r = rig({ apply: false });
+    await P.provisionInstance(lantern, r.deps);
+    const idx = (re) => r.logs.findIndex((l) => re.test(l));
+    const dns = idx(/\[dns\] upsert A lantern\.cloudbongos\.com/);
+    assert.ok(dns >= 0, r.logs.join('\n'));
+    for (const re of [/\[server\]/, /\[db\] create/, /\[config\]/, /\[caddy\]/, /\[healthz\]/]) {
+      assert.ok(idx(re) > dns, `${re} after the DNS step:\n${r.logs.join('\n')}`);
+    }
+  });
+});
+
+console.log('\nthe runner records whether its own lookup answers:');
+
+await ta('an answering name is recorded as resolving BEFORE the row reads active', async () => {
+  await withHook(HOOK, async () => {
+    const r = rig({ answers: true });
+    await P.provisionInstance(lantern, r.deps);
+    const lookup = r.at((e) => e.where === 'lookup');
+    const resolved = r.at((e) => e.where === 'resolved');
+    const active = r.at((e) => e.status === 'active');
+    assert.ok(lookup > r.hookAt(), 'the lookup comes long after the record went in');
+    assert.ok(resolved > lookup && resolved < active, `resolved (${resolved}) before active (${active})`);
+    assert.equal(r.events[lookup].host, 'lantern.cloudbongos.com');
+  });
+});
+
+await ta('a name that does not answer yet is NOT recorded — the hub keeps holding the link', async () => {
+  await withHook(HOOK, async () => {
+    const r = rig({ answers: false });
+    const res = await P.provisionInstance(lantern, r.deps);
+    assert.equal(res.ok, true);
+    assert.equal(r.at((e) => e.where === 'resolved'), -1);
+  });
+});
+
+await ta('no hook (manual DNS): no lookup is made, so the control plane never caches a miss for it', async () => {
+  await withHook(null, async () => {
+    const r = rig();
+    await P.provisionInstance(lantern, r.deps);
+    assert.equal(r.at((e) => e.where === 'lookup'), -1);
+    assert.equal(r.hookAt(), -1);
+  });
+});
+
+await ta('dry run: no lookup, nothing recorded', async () => {
+  await withHook(HOOK, async () => {
+    const r = rig({ apply: false });
+    await P.provisionInstance(lantern, r.deps);
+    assert.equal(r.at((e) => e.where === 'lookup'), -1);
+  });
+});
+
+console.log(`\nprovision_dns_first: ${passed} passed, ${failed} failed`);
+process.exit(failed ? 1 : 0);

package/tests/provision_settings_apply.mjs

@@ -75,6 +75,9 @@ ${NEUTRAL_PREFIX}_NIGHT_TINT=on
 ${NEUTRAL_PREFIX}_ARTIST_GATE_SINCE=
 ${NEUTRAL_PREFIX}_LOOK_ACCENT=
 ${NEUTRAL_PREFIX}_LOGO_URL=
+${NEUTRAL_PREFIX}_FOUNDING_BIRTH=
+${NEUTRAL_PREFIX}_DEMO_PEOPLE=
+${NEUTRAL_PREFIX}_DEMO_HOURS=
 `;
 
 t('replaces an existing KEY= line where it stands; every other line survives byte-for-byte', () => {
@@ -142,6 +145,8 @@ t('settingsEnvVarsFor: the runner pushes the SAME pair webEnvBody writes at stan
     // custom accent and the logo address as companions, empty when there is none
     [`${NEUTRAL_PREFIX}_LOOK`]: 'own', [`${NEUTRAL_PREFIX}_NIGHT_TINT`]: 'on',
     [`${NEUTRAL_PREFIX}_LOOK_ACCENT`]: '', [`${NEUTRAL_PREFIX}_LOGO_URL`]: '',
+    // the birth marker and a demo's box (task 1004506), empty on an un-stamped row
+    [`${NEUTRAL_PREFIX}_FOUNDING_BIRTH`]: '', [`${NEUTRAL_PREFIX}_DEMO_PEOPLE`]: '', [`${NEUTRAL_PREFIX}_DEMO_HOURS`]: '',
   });
   const body = P.webEnvBody(inst, {});
   for (const [k, v] of Object.entries(vars)) assert.match(body, new RegExp(`^${k}=${v}$`, 'm'), `${k} at standup`);
@@ -242,7 +247,7 @@ await ta('dry-run PLANS the patch: reads nothing real, writes NOTHING (no synthe
   assert.equal(r.ok, true);
   assert.equal(r.healthy, null, 'nothing ran, nothing observed');
   assert.equal(writes.length, 0, 'a dry-run must not plan a two-line overwrite of web.env');
-  assert.ok(logs.some((l) => /would patch .*_PLATFORM_VISIBILITY, .*_JOINABILITY, .*_VISIBILITY, .*_JOIN_GRANT, .*_ARTIST_GATE, .*_SPEND_PAYER, .*_LOOK, .*_NIGHT_TINT, .*_ARTIST_GATE_SINCE, .*_LOOK_ACCENT, .*_LOGO_URL in \/etc\/spike\/web\.env in place/.test(l)), logs.join('\n'));
+  assert.ok(logs.some((l) => /would patch .*_PLATFORM_VISIBILITY, .*_JOINABILITY, .*_VISIBILITY, .*_JOIN_GRANT, .*_ARTIST_GATE, .*_SPEND_PAYER, .*_LOOK, .*_NIGHT_TINT, .*_ARTIST_GATE_SINCE, .*_LOOK_ACCENT, .*_LOGO_URL, .*_FOUNDING_BIRTH, .*_DEMO_PEOPLE, .*_DEMO_HOURS in \/etc\/spike\/web\.env in place/.test(l)), logs.join('\n'));
   assert.ok(cmds.some((c) => /restart spike/.test(c)), 'the restart is still in the plan');
   assert.ok(logs.some((l) => /dry-run — nothing ran/.test(l)), 'the closing line does not claim a restart happened');
 });

package/tests/provisioning_settings_env.mjs

@@ -124,6 +124,9 @@ t('settingsEnvVars is the single source both legs derive from — same keys, sam
     // The look and its night tint (ADR 0358, task 1004421), with their two companions:
     // a custom look's accent and the logo address, empty when there is none.
     CLOUDBONGOS_LOOK: 'own', CLOUDBONGOS_NIGHT_TINT: 'on', CLOUDBONGOS_LOOK_ACCENT: '', CLOUDBONGOS_LOGO_URL: '',
+    // The birth marker and a demo's box (task 1004506): empty on a row the create
+    // route never stamped, which is every row made before it shipped (spec D8).
+    CLOUDBONGOS_FOUNDING_BIRTH: '', CLOUDBONGOS_DEMO_PEOPLE: '', CLOUDBONGOS_DEMO_HOURS: '',
   });
   // varsOf splits on '=', so an empty value reads as '' on both sides — the point
   // of the comparison is that the standup lines carry exactly the same key set.
@@ -132,9 +135,55 @@ t('settingsEnvVars is the single source both legs derive from — same keys, sam
     X_PLATFORM_VISIBILITY: 'public', X_JOINABILITY: 'apply', X_VISIBILITY: 'public', X_JOIN_GRANT: 'full',
     X_ARTIST_GATE: 'strict', X_ARTIST_GATE_SINCE: '', X_SPEND_PAYER: 'none',
     X_LOOK: 'own', X_NIGHT_TINT: 'on', X_LOOK_ACCENT: '', X_LOGO_URL: '',
+    X_FOUNDING_BIRTH: '', X_DEMO_PEOPLE: '', X_DEMO_HOURS: '',
   }, 'defaults, explicitly');
 });
 
+console.log('\nThe birth marker rides the same transport (task 1004506):');
+
+t('a stamped row carries its birth; only a stamped DEMO carries the box', () => {
+  const at = '2026-10-01T12:00:00.000Z';
+  const real = provisioning.settingsEnvVars({ settings: { founding_birth: at } }, 'X');
+  assert.equal(real.X_FOUNDING_BIRTH, at);
+  assert.equal(real.X_DEMO_PEOPLE, '', 'a real project has no demo box');
+  assert.equal(real.X_DEMO_HOURS, '');
+  const bornDemo = provisioning.settingsEnvVars({ settings: { founding_birth: at }, demo: { people: 3, hours_each: 4, outcome: null } }, 'X');
+  assert.deepEqual([bornDemo.X_FOUNDING_BIRTH, bornDemo.X_DEMO_PEOPLE, bornDemo.X_DEMO_HOURS], [at, '3', '4']);
+  const oldDemo = provisioning.settingsEnvVars({ settings: {}, demo: { people: 3, hours_each: 4 } }, 'X');
+  assert.deepEqual([oldDemo.X_FOUNDING_BIRTH, oldDemo.X_DEMO_PEOPLE, oldDemo.X_DEMO_HOURS], ['', '', ''],
+    'a demo made before the birth shipped is not born into anything, box and all');
+  assert.equal(provisioning.settingsEnvVars({ settings: { founding_birth: 'yesterday' } }, 'X').X_FOUNDING_BIRTH, '', 'a mangled stamp reads as none');
+});
+
+t('the stamp can neither leak as a setting nor be written by a client patch', () => {
+  const { BIRTH_KEY } = require('../modules/provisioning/birth.js');
+  assert.ok(!(BIRTH_KEY in provisioning.SETTINGS_VOCAB));
+  assert.ok(!(BIRTH_KEY in provisioning.PLANET_VOCAB));
+  assert.ok(!(BIRTH_KEY in provisioning.effectiveSettings({ settings: { [BIRTH_KEY]: '2026-10-01T00:00:00.000Z' } })));
+});
+
+t('stampBirth writes the row it is given, once: an existing stamp is kept', () => {
+  const { stampBirth, BIRTH_KEY } = require('../modules/provisioning/birth.js');
+  const seen = [];
+  // This harness is synchronous; the statement is issued before stampBirth's first await.
+  stampBirth({ query: async (sql, params) => { seen.push({ sql, params }); return { rows: [] }; } }, 41, new Date('2026-10-01T00:00:00.000Z'));
+  assert.equal(seen.length, 1);
+  assert.match(seen[0].sql, /UPDATE provisioning_instances/);
+  assert.match(seen[0].sql, /WHERE id = \$1 AND NOT \(COALESCE\(settings, '\{\}'::jsonb\) \? \$2::text\)/, 'write-once');
+  assert.deepEqual(seen[0].params, [41, BIRTH_KEY, '2026-10-01T00:00:00.000Z']);
+});
+
+t('the instance reads the marker into founding.*, and never publishes it to the client', () => {
+  const read = (env) => JSON.parse(execFileSync(process.execPath, ['-e',
+    "const b=require('./src/branding.js');const r=(b.branding||b)();console.log(JSON.stringify({f:r.founding||null,c:'founding' in b.clientBranding(r)}))"],
+    { cwd: ROOT, encoding: 'utf8', env: { ...process.env, ...env } }));
+  assert.deepEqual(read({}), { f: null, c: false }, 'no env, no founding block');
+  assert.deepEqual(read({ CLOUDBONGOS_FOUNDING_BIRTH: '2026-10-01T00:00:00.000Z', CLOUDBONGOS_DEMO_PEOPLE: '3', CLOUDBONGOS_DEMO_HOURS: '4' }),
+    { f: { birth: '2026-10-01T00:00:00.000Z', demoPeople: '3', demoHours: '4' }, c: false });
+  assert.deepEqual(read({ CLOUDBONGOS_FOUNDING_BIRTH: '', CLOUDBONGOS_DEMO_PEOPLE: '', CLOUDBONGOS_DEMO_HOURS: '' }), { f: null, c: false },
+    'the empty lines every un-born instance carries resolve to nothing');
+});
+
 console.log('\nThe artist gate rides the same transport (ADR 0241, task 1003575):');
 
 t('the stamp is carried only when the gate was actually RAISED, and it is the row\'s own value', () => {