@bongos/core 1.21.93 → 1.21.95

package/tests/github_one_trip.mjs

@@ -0,0 +1,297 @@
+// tests/github_one_trip.mjs — "Connect GitHub in one trip: approving the app goes straight
+// to installing it on the repo, and the checklist ticks itself" (task 1004649).
+//
+// Four layers, DB-free and network-free:
+//   1. modules/provisioning/github-setup.js — each checklist step's state from server facts,
+//      the honest "not yet" states included; the install link; the verify window (PURE).
+//   2. scripts/gds/provision-github-setup.js — the runner's check, asked of GitHub with the
+//      app's OWN key: the creds read back out of a REAL webEnvBody, a JWT that verifies,
+//      installed / not installed / cannot tell, device flow on / off / cannot tell, and the
+//      tick recording only what GitHub confirmed — never a secret in a log line.
+//   3. the REAL projection (githubSetupRead) run into the REAL page renderers (projects.html,
+//      the vm-slice idiom): each server state draws the step the founder should see.
+//   4. the device-flow finding is written down where the next builder will look.
+//
+// Run:  node --test tests/github_one_trip.mjs
+
+import assert from 'node:assert/strict';
+import { test } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+import crypto from 'node:crypto';
+import { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GS = require(path.join(ROOT, 'modules', 'provisioning', 'github-setup.js'));
+const RUN = require(path.join(ROOT, 'scripts', 'gds', 'provision-github-setup.js'));
+const UNITS = require(path.join(ROOT, 'scripts', 'gds', 'provision-units.js'));
+const HUB = fs.readFileSync(path.join(ROOT, 'modules', 'public-landing', 'public', 'projects.html'), 'utf8').replace(/\r\n/g, '\n');
+const SCRIPT = HUB.slice(HUB.lastIndexOf('<script>'), HUB.lastIndexOf('</script>'));
+
+// ── 1. the checklist from server facts ──────────────────────────────────────
+
+test('each step reads only what the server has seen — the honest "not yet" states included', () => {
+  const none = GS.githubChecklist(null, null);
+  assert.deepEqual(none, { approve: 'todo', install: 'todo', sign_in: 'todo', device_flow: 'todo', connected: false }, 'never started');
+  assert.equal(GS.githubChecklist('pending', null).approve, 'now', 'waiting for the approval on GitHub');
+  for (const s of ['code_received', 'converting']) {
+    const c = GS.githubChecklist(s, null);
+    assert.equal(c.approve, 'now', `${s}: approved, but no keys placed yet — not ticked`);
+    assert.equal(c.install, 'todo', `${s}: nothing to install before the app is named`);
+  }
+  const placed = GS.githubChecklist('converting', 'mercury-app');
+  assert.deepEqual([placed.approve, placed.install, placed.sign_in, placed.device_flow], ['done', 'now', 'now', 'todo'], 'keys placed: approve ticks, install and sign-in are under way');
+  const signedIn = GS.githubChecklist('done', 'mercury-app');
+  assert.deepEqual([signedIn.install, signedIn.sign_in, signedIn.device_flow, signedIn.connected], ['now', 'done', 'later', false],
+    'sign-in verified is NOT connected: the install has not been confirmed by GitHub');
+  const installed = GS.githubChecklist('done', 'mercury-app', { installedAt: '2026-10-08T10:00:00Z' });
+  assert.equal(installed.connected, true, 'approve + install + sign-in = connected');
+  assert.equal(installed.device_flow, 'later', 'device flow stays optional and never holds "connected" back');
+  assert.equal(GS.githubChecklist('done', 'mercury-app', { installedAt: 'x', deviceFlowAt: 'y' }).device_flow, 'done');
+  // a REPORTED install (the setup_url redirect, spoofable) ticks nothing
+  assert.equal(GS.githubChecklist('done', 'mercury-app', { installReportedAt: '2026-10-08T10:00:00Z' }).install, 'now');
+  // failures: where it stopped
+  assert.equal(GS.githubChecklist('error', null).approve, 'stopped');
+  assert.equal(GS.githubChecklist('expired', null).approve, 'stopped');
+  const signInFailed = GS.githubChecklist('error', 'mercury-app');
+  assert.deepEqual([signInFailed.approve, signInFailed.sign_in], ['done', 'stopped'], 'an app exists; sign-in is where it stopped');
+});
+
+test('the install link names the app and carries the attempt; the repo is strict', () => {
+  assert.equal(GS.installUrlFor({ appSlug: null, state: 'abc' }), null);
+  assert.equal(GS.installUrlFor({ appSlug: 'mercury-app', state: 'ab cd' }), 'https://github.com/apps/mercury-app/installations/new?state=ab%20cd');
+  assert.equal(GS.installUrlFor({ appSlug: 'mercury-app' }), 'https://github.com/apps/mercury-app/installations/new');
+  assert.equal(GS.targetRepo({ target_ref: 'acme/mercury' }), 'acme/mercury');
+  assert.equal(GS.targetRepo({ target_ref: 'acme/mercury.git' }), 'acme/mercury');
+  for (const bad of ['', 'acme', '../x/y', 'a/b/c', 'acme/mer cury', '-acme/x']) assert.equal(GS.targetRepo({ target_ref: bad }), null, bad);
+});
+
+test('the runner checks for a bounded window after the attempt settles, re-opened by an install report', () => {
+  const now = Date.parse('2026-10-08T12:00:00Z');
+  assert.equal(GS.stillVerifying({ resolved_at: '2026-10-08T11:00:00Z' }, {}, now), true);
+  assert.equal(GS.stillVerifying({ resolved_at: '2026-10-08T09:00:00Z' }, {}, now), false);
+  assert.equal(GS.stillVerifying({ resolved_at: '2026-10-08T09:00:00Z' }, { installReportedAt: '2026-10-08T11:30:00Z' }, now), true);
+  assert.equal(GS.stillVerifying(null, {}, now), false);
+});
+
+test('githubSetupRead: one events read since the attempt began; the owner read leaves the state off', async () => {
+  const seen = [];
+  const db = { query: async (sql, params) => { seen.push({ sql, params }); return { rows: [{ event: GS.SETUP_EVENTS.installed, at: '2026-10-08T10:00:00Z' }] }; } };
+  const row = { instance_id: 42, state: 'S1', created_at: '2026-10-08T09:00:00Z', app_slug: 'mercury-app', status: 'done' };
+  const pub = await GS.githubSetupRead(db, { target_ref: 'acme/mercury' }, row, 'done', { now: Date.parse('2026-10-08T10:30:00Z') });
+  assert.equal(seen.length, 1);
+  assert.match(seen[0].sql, /FROM provisioning_events/);
+  assert.deepEqual(seen[0].params, [42, Object.values(GS.SETUP_EVENTS), '2026-10-08T09:00:00Z']);
+  assert.equal(pub.checklist.install, 'done');
+  assert.equal(pub.install_url, null, 'no install link once it is verified');
+  const notYet = await GS.githubSetupRead({ query: async () => ({ rows: [] }) }, {}, row, 'done', { withState: false });
+  assert.equal(notYet.install_url, 'https://github.com/apps/mercury-app/installations/new', 'the owner read never carries the state token');
+  const broken = await GS.githubSetupRead({ query: async () => { throw new Error('db down'); } }, {}, row, 'done');
+  assert.equal(broken.checklist.install, 'now', 'a failed read is "nothing verified yet", never a 500');
+});
+
+// ── 2. the runner's check ───────────────────────────────────────────────────
+
+const { privateKey, publicKey } = crypto.generateKeyPairSync('rsa', { modulusLength: 2048 });
+const PEM = privateKey.export({ type: 'pkcs1', format: 'pem' });
+const INST = { id: 42, slug: 'mercury', port: 4100, domain: 'mercury.example.com', target_ref: 'acme/mercury', hosting_shape: 'co-tenant' };
+const ENV = UNITS.webEnvBody(INST, { clientId: 'Iv23liABCDEF123456', clientSecret: 's'.repeat(40), appId: 5189633, appPem: PEM });
+
+test('the app creds come back out of the web.env the runner itself writes', () => {
+  const c = RUN.appCredsFromEnv(ENV);
+  assert.equal(c.appId, '5189633');
+  assert.equal(c.clientId, 'Iv23liABCDEF123456');
+  assert.equal(c.pem.trim(), PEM.trim(), 'the one-line pem is restored to real newlines');
+  assert.deepEqual(RUN.appCredsFromEnv(''), { appId: null, pem: null, clientId: null });
+});
+
+test('the app JWT is RS256, signed by the app key, issued by the app id, under ten minutes', () => {
+  const jwt = RUN.appJwt({ appId: 5189633, pem: PEM, nowSec: 1_800_000_000 });
+  const [h, b, s] = jwt.split('.');
+  const ok = crypto.createVerify('RSA-SHA256').update(`${h}.${b}`).verify(publicKey, Buffer.from(s, 'base64url'));
+  assert.equal(ok, true);
+  const body = JSON.parse(Buffer.from(b, 'base64url').toString());
+  assert.equal(body.iss, '5189633');
+  assert.ok(body.exp - body.iat <= 600);
+});
+
+test('installed / not installed / cannot tell — only a 200 with an id is "installed"', async () => {
+  const calls = [];
+  const answer = (status, body) => async (url, opts) => { calls.push({ url, opts }); return { status, ok: status >= 200 && status < 300, json: async () => body }; };
+  assert.equal(await RUN.installedOnRepo({ appId: 1, pem: PEM, repo: 'acme/mercury', fetchImpl: answer(200, { id: 99 }) }), true);
+  assert.equal(calls[0].url, 'https://api.github.com/repos/acme/mercury/installation');
+  assert.match(calls[0].opts.headers.Authorization, /^Bearer [\w-]+\.[\w-]+\.[\w-]+$/, 'asked as the app');
+  assert.equal(await RUN.installedOnRepo({ appId: 1, pem: PEM, repo: 'acme/mercury', fetchImpl: answer(404, {}) }), false);
+  assert.equal(await RUN.installedOnRepo({ appId: 1, pem: PEM, repo: 'acme/mercury', fetchImpl: answer(500, {}) }), null);
+  assert.equal(await RUN.installedOnRepo({ appId: 1, pem: PEM, repo: 'acme/mercury', fetchImpl: async () => { throw new Error('offline'); } }), null);
+});
+
+test('device flow on / off / cannot tell — read from GitHub\'s own answer to a device sign-in start', async () => {
+  const with_ = (body) => async () => ({ status: 200, ok: true, json: async () => body });
+  assert.equal(await RUN.deviceFlowOn({ clientId: 'Iv1', fetchImpl: with_({ device_code: 'dc', user_code: 'AB-CD' }) }), true);
+  assert.equal(await RUN.deviceFlowOn({ clientId: 'Iv1', fetchImpl: with_({ error: 'device_flow_disabled' }) }), false);
+  assert.equal(await RUN.deviceFlowOn({ clientId: 'Iv1', fetchImpl: with_({ error: 'slow_down' }) }), null, 'any other answer is never read as off');
+});
+
+// A fake db that answers the runner's two reads: the attempts in the window, and the facts.
+function fakeDb({ attempts, facts = [] }) {
+  return { query: async (sql) => (/WITH latest AS/.test(sql) ? { rows: attempts } : /FROM provisioning_events/.test(sql) ? { rows: facts } : { rows: [] }) };
+}
+const ATTEMPT = { id: 18, instance_id: 42, created_at: '2026-10-08T09:00:00Z', requested_by: 7, slug: 'mercury', target_ref: 'acme/mercury', hosting_shape: 'co-tenant', instance_status: 'active' };
+
+test('the runner records what GitHub confirmed — and only that — reading the creds on the box', async () => {
+  const events = [], logs = [], cmds = [];
+  const fetchImpl = async (url) => (/\/installation$/.test(url)
+    ? { status: 200, ok: true, json: async () => ({ id: 31337 }) }
+    : { status: 200, ok: true, json: async () => ({ error: 'device_flow_disabled' }) });
+  const out = await RUN.verifyGithubAppSetups({
+    apply: true, privileged: true, log: (m) => logs.push(m), fetchImpl,
+    db: fakeDb({ attempts: [ATTEMPT] }),
+    exec: (cmd) => { cmds.push(cmd); return { ok: true, stdout: ENV }; },
+    provisioning: { recordEvent: async (_db, e) => { events.push(e); } },
+  });
+  assert.deepEqual(out, { checked: 1, installed: 1, deviceFlow: 0 });
+  assert.deepEqual(cmds, ['sudo cat /etc/mercury/web.env'], 'the creds are read where the runner placed them');
+  assert.deepEqual(events.map((e) => e.event), ['github-app-installed'], 'device flow off records nothing');
+  assert.match(events[0].detail, /acme\/mercury/);
+  const said = logs.join('\n') + JSON.stringify(events);
+  assert.doesNotMatch(said, /BEGIN RSA|s{40}|Iv23liABCDEF123456/, 'no key, secret or client id ever reaches a log or an event');
+});
+
+test('an attempt already fully verified is skipped; dry-run asks GitHub nothing', async () => {
+  let asked = 0;
+  const deps = {
+    apply: true, log: () => {}, fetchImpl: async () => { asked++; return { status: 200, ok: true, json: async () => ({}) }; },
+    db: fakeDb({ attempts: [ATTEMPT], facts: [{ event: 'github-app-installed', at: '2026-10-08T10:00:00Z' }, { event: 'github-app-device-flow', at: '2026-10-08T10:00:00Z' }] }),
+    exec: () => { throw new Error('must not read the box'); }, provisioning: { recordEvent: async () => { throw new Error('nothing to record'); } },
+  };
+  assert.deepEqual(await RUN.verifyGithubAppSetups(deps), { checked: 0, installed: 0, deviceFlow: 0 });
+  const lines = [];
+  await RUN.verifyGithubAppSetups({ ...deps, apply: false, log: (m) => lines.push(m), db: fakeDb({ attempts: [ATTEMPT] }) });
+  assert.equal(asked, 0);
+  assert.match(lines.join('\n'), /would check the GitHub install \+ device flow for mercury/);
+});
+
+test('the window query takes each project\'s LATEST attempt, past placement, still settling or newly reported', async () => {
+  let sql = '', params = null;
+  await RUN.attemptsToVerify({ query: async (q, p) => { sql = q; params = p; return { rows: [] }; } });
+  assert.match(sql, /DISTINCT ON \(instance_id\)[\s\S]*ORDER BY instance_id, created_at DESC/);
+  assert.match(sql, /l\.app_id IS NOT NULL AND l\.status IN \('done', 'error'\) AND i\.status = 'active'/);
+  assert.match(sql, /LIMIT 20/);
+  assert.deepEqual(params, [GS.VERIFY_WINDOW_MS / 1000, 'github-app-install-reported']);
+  assert.match(fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'provision.js'), 'utf8'), /require\('\.\/provision-github-setup\.js'\)\.verifyGithubAppSetups\(deps\)/, 'it runs on every runner tick, after the conversions');
+});
+
+// ── 3. the real projection into the real renderers ──────────────────────────
+
+const RS = SCRIPT.indexOf('    /* The four GitHub steps of part 03');
+const RE = SCRIPT.indexOf('    var STEP_RENDERERS = {', RS);
+const SS = SCRIPT.indexOf('    /* the checklist the server derived (task 1004649)');
+const SE = SCRIPT.indexOf('    function pollManifest(stateToken) {', SS);
+const PS = SCRIPT.indexOf('    function stepsPaint() {');
+const PE = SCRIPT.indexOf('    (function hopInput()', PS);
+
+test('the regions are findable (a rename must fail loudly)', () => {
+  assert.ok(RS > 0 && RE > RS && SS > 0 && SE > SS && PS > 0 && PE > PS);
+});
+
+function page({ manifest, appSlug = null }) {
+  const sandbox = {
+    live: { manifest, manifestMsg: '', manifestCode: '', manifestFailure: null, appSlug, setup: null, installUrl: null, instStatus: 'active', addrReady: true },
+    state: { name: 'Mer<cury', slug: 'mercury', owner: 'acme', repo: 'mercury', step: 2 },
+    manifestStale: false, autoOpenArmed: false,
+    resolvedDomain: () => 'mercury.example.com', apexBase: () => 'example.com',
+    esc: (x) => String(x).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])),
+    GH_ICON: '', manualOauthDetails: () => '', projectPageLink: (t) => t, autoOpenTick: () => '',
+    progressMarkup: (a, b, note) => `<prog>${note}</prog>`, encodeURIComponent, JSON, Array,
+  };
+  vm.createContext(sandbox);
+  vm.runInContext(`${SCRIPT.slice(RS, RE)}\n${SCRIPT.slice(SS, SE)}\n${SCRIPT.slice(PS, PE)}`, sandbox);
+  return sandbox;
+}
+const ROWS = ['renderStepOauthApp', 'renderStepAppInstall', 'renderStepFirstSignIn', 'renderStepDeviceFlow'];
+function draw(sb) {
+  return ROWS.map((f) => vm.runInContext(`${f}()`, sb));
+}
+function cls(li) { return ((li.match(/^<li(?: class="([^"]*)")?/) || [])[1] || '').split(/\s+/).filter(Boolean); }
+
+async function serverSays(status, appSlug, eventRows) {
+  const db = { query: async () => ({ rows: eventRows }) };
+  const row = { instance_id: 42, state: 'S1', created_at: '2026-10-08T09:00:00Z', resolved_at: new Date().toISOString(), app_slug: appSlug };
+  return GS.githubSetupRead(db, { target_ref: 'acme/mercury' }, row, status);
+}
+
+test('the mockup\'s four steps, in its words and order, the typed name escaped', () => {
+  const sb = page({ manifest: null });
+  const rows = draw(sb);
+  const titles = rows.map((li) => (li.match(/<b>([^<]*)<\/b>/) || [])[1]);
+  assert.deepEqual(titles, ['Approve the Mer&lt;cury app on GitHub', 'Install it on your repo', 'Builders can sign in', 'Command-line sign-in is on']);
+  assert.match(rows[0], /data-action="manifest-start"[^>]*>Connect GitHub ↗/, 'one click starts the one trip');
+  assert.equal(SCRIPT.match(/var STEP_ORDER = \[([^\]]*)\]/)[1], "'github-repo', 'oauth-app', 'app-install', 'first-sign-in', 'device-flow', 'enter-hall'", 'drawn in the mockup\'s order');
+});
+
+test('each server state draws the step the founder should see — from the REAL projection', async () => {
+  // keys placed, nothing verified on GitHub yet
+  let sb = page({ manifest: 'converting', appSlug: 'mercury-app' });
+  let d = await serverSays('converting', 'mercury-app', []);
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)})`, sb);
+  let rows = draw(sb);
+  assert.deepEqual(rows.map(cls), [['sdone'], [], ['slocked'], ['slocked', 'soptional']]);
+  assert.match(rows[1], /href="https:\/\/github\.com\/apps\/mercury-app\/installations\/new\?state=S1"/, 'the way back to the install, with the attempt');
+  assert.equal(vm.runInContext('stepsPaint.toString().length > 0', sb), true);
+
+  // sign-in verified, install still unconfirmed: NOT connected
+  sb = page({ manifest: 'done', appSlug: 'mercury-app' });
+  d = await serverSays('done', 'mercury-app', []);
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)})`, sb);
+  rows = draw(sb);
+  assert.deepEqual(rows.map(cls), [['sdone'], [], ['sdone'], ['soptional']]);
+  assert.match(rows[3], /Optional — turn it on later\./);
+  assert.equal(vm.runInContext('setupOpen()', sb), true, 'the page keeps watching for the install');
+
+  // GitHub confirmed the install to the runner: connected, device flow still optional
+  sb = page({ manifest: 'done', appSlug: 'mercury-app' });
+  d = await serverSays('done', 'mercury-app', [{ event: 'github-app-installed', at: '2026-10-08T10:00:00Z' }]);
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)})`, sb);
+  rows = draw(sb);
+  assert.deepEqual(rows.map(cls), [['sdone'], ['sdone'], ['sdone'], ['soptional']]);
+  assert.match(rows[1], /The app is on acme\/mercury/);
+  assert.equal(vm.runInContext('setupOpen()', sb), false);
+  // the part's state line, from these very rows: the optional step does not hold it back
+  const items = rows.map((li) => ({ classList: { contains: (c) => cls(li).includes(c) } }));
+  const ghState = { textContent: '' };
+  sb.$ = (id) => (id === 'humanSteps' ? { children: items } : id === 'ghState' ? ghState : null);
+  sb.manifestInFlight = () => false;
+  vm.runInContext('stepsPaint()', sb);
+  assert.equal(ghState.textContent, 'connected ✓');
+
+  // and once GitHub has device flow on, the fourth ticks too
+  sb = page({ manifest: 'done', appSlug: 'mercury-app' });
+  d = await serverSays('done', 'mercury-app', [{ event: 'github-app-installed', at: '2026-10-08T10:00:00Z' }, { event: 'github-app-device-flow', at: '2026-10-08T10:05:00Z' }]);
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)})`, sb);
+  assert.deepEqual(cls(draw(sb)[3]), ['sdone', 'soptional']);
+});
+
+test('seedSetup is change-only, and an install link must be GitHub\'s', () => {
+  const sb = page({ manifest: 'done', appSlug: 'a' });
+  const c = JSON.stringify(GS.githubChecklist('done', 'a'));
+  assert.equal(vm.runInContext(`seedSetup(${c}, 'https://github.com/apps/a/installations/new?state=S')`, sb), true);
+  assert.equal(vm.runInContext(`seedSetup(${c}, 'https://github.com/apps/a/installations/new?state=S')`, sb), false, 'nothing moved, nothing redrawn');
+  assert.equal(vm.runInContext(`seedSetup(${c}, 'https://github.com/apps/a/installations/new')`, sb), false, 'a stateless link never replaces the one carrying the attempt');
+  assert.equal(vm.runInContext('live.installUrl', sb), 'https://github.com/apps/a/installations/new?state=S');
+  const sb2 = page({ manifest: 'done', appSlug: 'a' });
+  vm.runInContext(`seedSetup(${c}, 'javascript:alert(1)')`, sb2);
+  assert.equal(vm.runInContext('live.installUrl', sb2), null);
+  assert.equal(vm.runInContext('seedSetup(null, null)', sb2), false);
+});
+
+// ── 4. the finding is written down ──────────────────────────────────────────
+
+test('the device-flow finding lives in the direction doc, and the code points at it', () => {
+  const doc = fs.readFileSync(path.join(ROOT, 'docs', 'design', 'project-startup-direction.md'), 'utf8');
+  assert.match(doc, /Device flow cannot be switched on for the founder \(spike, task 1004649\)/);
+  assert.match(fs.readFileSync(path.join(ROOT, 'modules', 'provisioning', 'github-setup.js'), 'utf8'), /docs\/design\/project-startup-direction\.md/);
+});

package/tests/projects_hub.mjs

@@ -355,8 +355,12 @@ test('C8 — the wizard polls stop dead off the new view, like the sky off the m
   // guard — merged unguarded they would poll a hidden view for up to 33
   // minutes. Both ticks must consult the same gate the sky consults.
   assert.match(SCRIPT, /function wizPollActive\(\)/, 'the wizard needs its own stage guard');
-  assert.match(SCRIPT, /!document\.hidden && currentView === 'new'/,
-    'the guard is hidden-tab aware and view-scoped');
+  assert.match(SCRIPT, /function wizPollActive\(\) \{\s*return currentView === 'new';\s*\}/,
+    'the guard is view-scoped');
+  // a HIDDEN tab slows the wizard's polls instead of stopping them (task 1004650): that
+  // is exactly when the founder is on GitHub. tests/github_handback_any_device.mjs runs it.
+  assert.match(SCRIPT, /return document\.hidden \? Math\.max\(ms, HIDDEN_POLL_MS\) : ms;/,
+    'a hidden tab keeps checking at the slow pace');
   const gatedTicks = (SCRIPT.match(/if \(!wizPollActive\(\)\)/g) || []).length;
   assert.ok(gatedTicks >= 2, `both wizard ticks (progress + manifest) must check the guard, found ${gatedTicks}`);
   assert.match(SCRIPT, /if \(v === 'new'\) wizard\.enter\(focus\); else wizard\.leave\(\);/,

package/tests/projects_hub_dns_ready.mjs

@@ -165,7 +165,8 @@ 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');
+  // task 1004649: "Builders can sign in" opens its door only on a resolving address
+  assert.match(SCRIPT, /var open = live\.instStatus === 'active' && live\.addrReady;\n\s*return '<li class="sdone" data-onboard-step="first-sign-in">/, 'the sign-in step\'s door waits for the address');
   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');

package/tests/projects_hub_pre_uat.mjs

@@ -185,14 +185,18 @@ test('the 33-minute hand-off keeps a snag honest and keeps its flow', () => {
   assert.match(SCRIPT, /progressMarkup\(1, 1, m\.slice\(5\), 'isErr', watchFlow\)/, 'the session-expiry message keeps its flow too');
 });
 
-test('First sign-in and Enter your builders hall unlock only when the project answers AND sign-in is wired', () => {
+test('"Builders can sign in" ticks on verified sign-in, and its door opens only when the project answers (task 1004649)', () => {
+  // the one-page checklist (task 1004649): the step's tick is the server's 'done';
+  // the door to the project still waits for a resolving address (task 1004505)
   const first = fn('renderStepFirstSignIn');
+  assert.match(first, /<b>Builders can sign in<\/b>/);
+  assert.match(first, /if \(live\.manifest !== 'done'\) \{\n\s*return '<li class="slocked"/, 'locked until the platform has seen sign-in work');
+  assert.match(first, /var open = live\.instStatus === 'active' && live\.addrReady;/, 'the door gates on status and a resolving address');
+  assert.match(first, /\(open \? '<a class="ghbtn" href="https:\/\/' \+ esc\(domain\)/, 'and only then links the address');
+  // the hall is the "is alive" block's way in; the step survives only for the local hall
   const hall = fn('renderStepEnterHall');
-  for (const [name, body] of [['first-sign-in', first], ['enter-hall', hall]]) {
-    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/);
+  assert.match(hall, /if \(domain\) return '';/);
+  assert.match(hall, /bongos dev/);
 });
 
 test('the domainless build is standing, not "Live"', () => {
@@ -208,7 +212,7 @@ test('the fallback checklist carries every human step the canonical plan has', (
 test('the manifest step acknowledges code_received, offers a restart after a stall, and rides the CREATED record', () => {
   // 'converting' is the same stage — it used to fall through to "waiting for approval" (task 1004572)
   assert.match(SCRIPT, /if \(live\.manifest === 'code_received' \|\| live\.manifest === 'converting'\)/, 'GitHub’s half is acknowledged');
-  assert.match(SCRIPT, /GitHub’s part is done/);
+  assert.match(SCRIPT, /Approved on GitHub\. The platform is placing the app’s keys on your project/);
   assert.match(SCRIPT, /manifestStale \? '<button type="button" class="linklike" data-action="manifest-start">/, 'a stalled wait gets a restart door');
   assert.match(SCRIPT, /\(Date\.now\(\) - manifestStartedAt\) > 90000/, 'after ~90 seconds');
   assert.match(SCRIPT, /function rememberManifest\(stateToken, status, appSlug\)/);
@@ -610,10 +614,14 @@ test('teardown copy is state-aware: a queued project is told nothing was built',
 
 test('founder voice on the Device Flow step and the manual OAuth fallback', () => {
   const df = fn('renderStepDeviceFlow');
-  assert.equal((df.match(/<b>Let builders sign in from a command line — one checkbox<\/b>/g) || []).length, 2, 'both branches carry the outcome-first title');
+  // the mockup's words (task 1004649): one title, in every branch
+  assert.match(df, /var title = '<b>Command-line sign-in is on<\/b>';/, 'the outcome-first title');
   assert.doesNotMatch(df, /<b>Enable Device Flow — one checkbox<\/b>/);
   assert.match(df, /the <code style="font-family:var\(--font-mono\)">bongos setup<\/code> command builders run on their own machine/, 'the command is glossed, not bare-coded');
-  assert.doesNotMatch(df, /Optional/, 'not optional — a manifest-born App has Device Flow off');
+  // GitHub has no manifest field and no API for device flow (task 1004649's spike), so the
+  // step is OPTIONAL by design and never holds the project back
+  assert.equal((df.match(/Optional — turn it on later\./g) || []).length, 2, 'the not-yet branches say it is optional');
+  assert.equal((df.match(/class="[^"]*soptional/g) || []).length, 3, 'every branch is marked optional, so "connected" never waits on it');
   assert.equal((df.match(/<strong>Enable Device Flow<\/strong>/g) || []).length, 2, 'GitHub’s own checkbox label stays verbatim in the instructions');
   const manual = fn('manualOauthDetails');
   assert.match(manual, /The platform team places the generated credentials; this step ticks itself once they land\.<\/p><\/details>/);

package/tests/provision.mjs

@@ -1740,13 +1740,54 @@ await ta('drainOAuthManifests (--apply): claims a code_received row, places cred
   };
   const r = await P.drainOAuthManifests(deps);
   assert.deepEqual(r, { converted: 1, errors: 0 });
-  assert.equal(resolved.length, 1);
-  assert.equal(resolved[0].status, 'done');
-  assert.equal(resolved[0].patch.app_slug, 'app-3');
-  assert.equal(resolved[0].patch.github_code, null, 'a done row holds no re-convertible code (F23)');
+  // task 1004649: the slug lands the moment the creds are placed (still 'converting'),
+  // so the callback page can send the founder on to the install before sign-in is checked
+  assert.deepEqual(resolved.map((x) => x.status), ['converting', 'done']);
+  assert.deepEqual(resolved[0].patch, { app_id: 3, app_slug: 'app-3' });
+  assert.equal(resolved[1].patch.app_slug, 'app-3');
+  assert.equal(resolved[1].patch.github_code, null, 'a done row holds no re-convertible code (F23)');
   assert.ok(events.includes('oauth-manifest-done'));
 });
 
+await ta('the sign-in check reads the JSON health answer, never the root /healthz "ok" (task 1004577)', async () => {
+  // The REAL answers of the two endpoints (src/bongos/serve-internal.js answers GET /healthz
+  // with a plain "ok"; src/bongos/routes/healthz.js answers /api/bongos/healthz with JSON).
+  // The old probe hit /healthz, never parsed, and recorded every working setup as FAILED.
+  const real = (cmd) => (/\/api\/bongos\/healthz/.test(cmd) ? '{"ok":true,"auth_configured":true}'
+    : /\/healthz/.test(cmd) ? 'ok' : '');
+  const inst = { ...coTenant, domain: 'mercury.example.com' };
+  const probes = [];
+  const deps = {
+    apply: true, privileged: false, log: () => {}, sleep: async () => {},
+    convertManifestCode: async () => ({ clientId: 'Iv1.abcdef0123456789', clientSecret: 'z'.repeat(40), appId: 7, appSlug: 'mercury-app' }),
+    exec: (cmd) => { if (/healthz/.test(cmd)) probes.push(cmd); return { ok: true, stdout: real(cmd) }; },
+    writeFile: () => ({ ok: true }),
+  };
+  const r = await P.placeManifestCreds(inst, { github_code: 'C', attempts: 1 }, deps);
+  assert.equal(r.ok, true, 'a project whose JSON health says auth_configured is verified');
+  assert.ok(probes.length >= 1 && probes.every((c) => /\/api\/bongos\/healthz/.test(c)), 'only the JSON endpoint is asked');
+  assert.equal(P.authHealthzCmd({ port: 4100 }), 'curl -sS --max-time 5 http://127.0.0.1:4100/api/bongos/healthz');
+  // and a plain "ok" is no verdict either way: it never reads as configured
+  const plain = await P.placeManifestCreds(inst, { github_code: 'C', attempts: 1 }, { ...deps, exec: () => ({ ok: true, stdout: 'ok' }) });
+  assert.equal(plain.ok, false, 'a bare "ok" never confirms sign-in');
+  const oauthSecret = require('../scripts/gds/oauth-secret.js');
+  assert.deepEqual(oauthSecret.parseHealthzAuth('ok'), { ok: false, authConfigured: false, parseError: true });
+  assert.match(readFileSync(new URL('../scripts/gds/oauth-secret.js', import.meta.url), 'utf8'), /127\.0\.0\.1:\$\{port\}\/api\/bongos\/healthz/, 'the manual placement probes the same JSON answer');
+});
+
+await ta('the slug is recorded only AFTER the credentials are placed (task 1004649)', async () => {
+  const order = [];
+  const inst = { ...coTenant, domain: 'mercury.example.com' };
+  await P.placeManifestCreds(inst, { github_code: 'C', attempts: 1 }, {
+    apply: true, privileged: false, log: () => {}, sleep: async () => {},
+    convertManifestCode: async () => ({ clientId: 'Iv1.abcdef0123456789', clientSecret: 'z'.repeat(40), appId: 7, appSlug: 'mercury-app' }),
+    exec: (cmd) => { if (/systemctl restart/.test(cmd)) order.push('restart'); return { ok: true, stdout: '{"auth_configured":true}' }; },
+    writeFile: (p) => { if (/web\.env$/.test(p)) order.push('write'); return { ok: true }; },
+    onCredsPlaced: async (c) => { order.push(`slug:${c.appSlug}`); },
+  });
+  assert.deepEqual(order, ['write', 'restart', 'slug:mercury-app'], 'the first tick means the keys are on the project');
+});
+
 await ta('a SPENT code is never re-converted — terminal error, no code_received reset (F23)', async () => {
   // A stateful one-row store: claimNext honors status, resolve writes it back —
   // exactly the reset loop that used to re-convert a burned code on the next tick.
@@ -1804,11 +1845,12 @@ await ta('a sign-in check that never confirms still records WHICH App GitHub mad
       recordEvent: async () => {},
     },
   });
-  assert.equal(resolves.length, 1);
-  assert.equal(resolves[0].status, 'error');
-  assert.equal(resolves[0].patch.app_slug, 'mercury-cloudbongos-com', 'the error row names the App');
-  assert.equal(resolves[0].patch.app_id, 5189633);
-  assert.equal(resolves[0].patch.github_code, null, 'the burned code is still scrubbed');
+  // the slug is recorded at placement (task 1004649), then the row settles as an error
+  assert.deepEqual(resolves.map((x) => x.status), ['converting', 'error']);
+  const settled = resolves[1];
+  assert.equal(settled.patch.app_slug, 'mercury-cloudbongos-com', 'the error row names the App');
+  assert.equal(settled.patch.app_id, 5189633);
+  assert.equal(settled.patch.github_code, null, 'the burned code is still scrubbed');
 });
 
 await ta('a failure BEFORE GitHub handed over credentials claims no App (task 1004572)', async () => {

package/tests/provisioning_callback_page.mjs

@@ -50,8 +50,9 @@ test('the hand-back variant escapes the title + domain it interpolates', () => {
   assert.doesNotMatch(html, /Setting up <your> instance/, 'no raw title anywhere on the page');
   assert.doesNotMatch(html, /https:\/\/evil"\.example\.com/, 'no unescaped domain in an href');
   // it IS the hand-back variant (task 1004548): the way back + the config block the client script reads
-  assert.match(html, /id="back" href="\/projects\?view=new"/);
-  assert.match(html, /__CB_SETUP__=\{"state":"GOODSTATE","domain":"evil\\"\.example\.com","back":"\/projects\?view=new"\}/);
+  // the way back is the return route, which names the project on the server (task 1004650)
+  assert.ok(html.includes('id="back" href="/api/bongos/provisioning/github-app/return?state=GOODSTATE"'));
+  assert.match(html, /__CB_SETUP__=\{"state":"GOODSTATE","domain":"evil\\"\.example\.com","back":"\/api\/bongos\/provisioning\/github-app\/return\?state=GOODSTATE"\}/);
 });
 
 test('the message variant escapes the title but passes server-authored body HTML through', () => {