@bongos/core 1.21.93 → 1.21.95

package/scripts/gds/provision-github-setup.js

@@ -0,0 +1,148 @@
+'use strict';
+// scripts/gds/provision-github-setup.js — the control-plane runner's check of the two
+// GitHub steps a founder finishes ON GITHUB after the app exists: "Install it on your repo"
+// and "Command-line sign-in is on" (task 1004649; the checklist is derived in
+// modules/provisioning/github-setup.js).
+//
+// WHY THE RUNNER. Only the runner holds the app's credentials (it placed them in the
+// project's chmod-600 web.env; ADR 0111 §2 / ADR 0133 — the web tier never sees a secret).
+// The setup_url redirect GitHub sends after an install carries an installation_id, but
+// GitHub's own docs warn it can be spoofed, so a tick needs GitHub's answer to a question
+// asked with the app's own key:
+//   install — GET /repos/{owner}/{repo}/installation, authenticated as the app (a JWT
+//             signed with its private key). 200 with an id = installed on THIS repo.
+//   device  — POST github.com/login/device/code with the app's client id. GitHub answers a
+//             device code when device flow is on and `device_flow_disabled` when it is off.
+//             The unused code simply expires; nothing is signed in. GitHub has NO manifest
+//             field and NO API that turns device flow on (spike, task 1004649), so this
+//             only ever OBSERVES the founder's own tick on GitHub.
+// A verified fact is recorded once as a provisioning_events row; the checklist reads it.
+//
+// BOUNDED. Only attempts that settled within VERIFY_WINDOW_MS, or whose install was
+// reported within it, are checked, at most SWEEP_LIMIT per tick — so a finished or
+// abandoned project costs nothing, and a founder who ticks device flow later re-opens the
+// window by reinstalling or from the hall (task 1004652 owns "check again").
+// Secrets: web.env is read on the box, parsed in memory, and only NAMES ever reach a log.
+
+const crypto = require('node:crypto');
+const { webEnvPath } = require('./provision-units.js');
+const { SETUP_EVENTS, VERIFY_WINDOW_MS, githubSetupFacts, targetRepo } = require('../../modules/provisioning/github-setup.js');
+
+const SWEEP_LIMIT = 20;
+const UA = 'cloud-bongos-provisioner';
+
+function b64url(input) {
+  return Buffer.from(input).toString('base64').replace(/\+/g, '-').replace(/\//g, '_').replace(/=+$/, '');
+}
+
+// An app JWT (RS256, 9 minutes, iat backdated for skew) — GitHub's app authentication.
+function appJwt({ appId, pem, nowSec = Math.floor(Date.now() / 1000) }) {
+  const head = b64url(JSON.stringify({ alg: 'RS256', typ: 'JWT' }));
+  const body = b64url(JSON.stringify({ iat: nowSec - 60, exp: nowSec + 9 * 60, iss: String(appId) }));
+  const signer = crypto.createSign('RSA-SHA256');
+  signer.update(`${head}.${body}`);
+  signer.end();
+  return `${head}.${body}.${b64url(signer.sign(pem))}`;
+}
+
+// The app's id, private key and client id out of a web.env body. The pem is stored as one
+// line with literal \n (provision-units.js webEnvBody); the client id under the pack's
+// prefix, which this does not need to know. Missing pieces are null. PURE.
+function appCredsFromEnv(body) {
+  const val = (re) => { const m = String(body || '').match(re); return m ? m[1].trim() : null; };
+  const pemLine = val(/^GITHUB_APP_PRIVATE_KEY=(.+)$/m);
+  return {
+    appId: val(/^GITHUB_APP_ID=(\d+)\s*$/m),
+    pem: pemLine ? pemLine.replace(/\\n/g, '\n') : null,
+    clientId: val(/^[A-Z0-9_]+_GITHUB_CLIENT_ID=(\S+)\s*$/m),
+  };
+}
+
+// Is the app installed on owner/repo? true · false (404: the app is real, not installed
+// there) · null (cannot tell — any other answer, or no network).
+async function installedOnRepo({ appId, pem, repo, fetchImpl = globalThis.fetch }) {
+  try {
+    const res = await fetchImpl(`https://api.github.com/repos/${repo}/installation`, {
+      headers: { Authorization: `Bearer ${appJwt({ appId, pem })}`, Accept: 'application/vnd.github+json', 'X-GitHub-Api-Version': '2022-11-28', 'User-Agent': UA },
+    });
+    if (res.status === 404) return false;
+    if (!res.ok) return null;
+    const j = await res.json().catch(() => null);
+    return !!(j && j.id != null);
+  } catch (_) { return null; }
+}
+
+// Does GitHub accept a device-flow start for this client id? true · false
+// (device_flow_disabled) · null (any other answer — never read as "off").
+async function deviceFlowOn({ clientId, fetchImpl = globalThis.fetch }) {
+  try {
+    const res = await fetchImpl('https://github.com/login/device/code', {
+      method: 'POST',
+      headers: { Accept: 'application/json', 'Content-Type': 'application/x-www-form-urlencoded', 'User-Agent': UA },
+      body: `client_id=${encodeURIComponent(clientId)}`,
+    });
+    const j = await res.json().catch(() => null);
+    if (j && j.device_code) return true;
+    if (j && /device_flow_disabled/.test(String(j.error || ''))) return false;
+    return null;
+  } catch (_) { return null; }
+}
+
+// The attempts worth checking this tick: each instance's LATEST attempt, past the
+// credential placement (an app id recorded), settled or reported within the window.
+async function attemptsToVerify(db) {
+  const windowSec = Math.round(VERIFY_WINDOW_MS / 1000);
+  const { rows } = await db.query(
+    `WITH latest AS (
+       SELECT DISTINCT ON (instance_id) * FROM provisioning_oauth_manifests ORDER BY instance_id, created_at DESC)
+     SELECT l.id, l.instance_id, l.created_at, l.requested_by, i.slug, i.target_ref, i.hosting_shape, i.status AS instance_status
+       FROM latest l JOIN provisioning_instances i ON i.id = l.instance_id
+      WHERE l.app_id IS NOT NULL AND l.status IN ('done', 'error') AND i.status = 'active'
+        AND (l.updated_at > now() - ($1 * interval '1 second')
+             OR EXISTS (SELECT 1 FROM provisioning_events e WHERE e.instance_id = l.instance_id
+                         AND e.event = $2 AND e.created_at > now() - ($1 * interval '1 second')))
+      ORDER BY l.updated_at DESC LIMIT ${SWEEP_LIMIT}`,
+    [windowSec, SETUP_EVENTS.installReported]);
+  return rows;
+}
+
+// One tick: for every attempt in the window, check whatever is not verified yet and record
+// what GitHub confirmed. Returns { checked, installed, deviceFlow }.
+async function verifyGithubAppSetups(deps) {
+  const { db, provisioning, log, apply } = deps;
+  const out = { checked: 0, installed: 0, deviceFlow: 0 };
+  const rows = await attemptsToVerify(db);
+  if (!apply) {
+    for (const r of rows) log(`  would check the GitHub install + device flow for ${r.slug} (manifest #${r.id})`);
+    return out;
+  }
+  for (const r of rows) {
+    const facts = await githubSetupFacts(db, r.instance_id, r.created_at);
+    if (facts.installedAt && facts.deviceFlowAt) continue;
+    const onControlBox = r.hosting_shape === 'cloud-host' || r.hosting_shape === 'control-plane';
+    const boxExec = onControlBox ? (deps.controlExec || deps.exec) : deps.exec;
+    const read = boxExec(`${deps.privileged ? 'sudo ' : ''}cat ${webEnvPath(r)}`, { allowFail: true });
+    const creds = appCredsFromEnv(read && read.stdout);
+    out.checked++;
+    const repo = targetRepo(r);
+    const fetchImpl = deps.fetchImpl;
+    if (!facts.installedAt && creds.appId && creds.pem && repo) {
+      if (await installedOnRepo({ appId: creds.appId, pem: creds.pem, repo, fetchImpl })) {
+        await provisioning.recordEvent(db, { instanceId: r.instance_id, ownerBuilderId: r.requested_by, event: SETUP_EVENTS.installed,
+          detail: `the GitHub app is installed on ${repo} (checked with the app's own key)`, actor: 'runner' });
+        out.installed++; log(`  ✓ ${r.slug}: GitHub app installed on ${repo}`);
+      }
+    }
+    if (!facts.deviceFlowAt && creds.clientId) {
+      if (await deviceFlowOn({ clientId: creds.clientId, fetchImpl })) {
+        await provisioning.recordEvent(db, { instanceId: r.instance_id, ownerBuilderId: r.requested_by, event: SETUP_EVENTS.deviceFlow,
+          detail: 'command-line sign-in (device flow) is on for the GitHub app', actor: 'runner' });
+        out.deviceFlow++; log(`  ✓ ${r.slug}: command-line sign-in is on`);
+      }
+    }
+  }
+  if (out.checked) log(`github-setup — checked=${out.checked} installed=${out.installed} device-flow=${out.deviceFlow}`);
+  return out;
+}
+
+module.exports = { appJwt, appCredsFromEnv, installedOnRepo, deviceFlowOn, attemptsToVerify, verifyGithubAppSetups, SWEEP_LIMIT };

package/scripts/gds/provision.js

@@ -1039,6 +1039,13 @@ async function convertManifestCode(code, { fetchImpl = globalThis.fetch, userAge
   };
 }
 
+// The sign-in probe: the project's JSON health answer, which carries auth_configured
+// (src/bongos/routes/healthz.js). NOT healthzCmd — the root /healthz answers a plain "ok",
+// which never parses, so every setup that worked was recorded FAILED (task 1004577).
+function authHealthzCmd(inst) {
+  return `curl -sS --max-time 5 http://127.0.0.1:${inst.port}/api/bongos/healthz`;
+}
+
 // Convert one manifest row's code → creds and PLACE them (rewrite web.env + restart +
 // verify /healthz). Uses the SAME executors provisionInstance does, so co-tenant (local
 // or remote-cohost) and standalone (control-plane-local) are handled identically. Returns { ok, appId, appSlug } | { ok:false, error }.
@@ -1082,15 +1089,19 @@ async function placeManifestCreds(inst, mrow, deps) {
     appId: creds.appId, appPem: creds.appPem,
   }), { mode: 0o600, sudo: true });
   pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
+  // The app now exists AND its credentials are placed — the checklist's first tick, and the
+  // slug the callback page needs to send the founder on to installing it (task 1004649).
+  if (apply && deps.onCredsPlaced) await Promise.resolve().then(() => deps.onCredsPlaced({ appId: creds.appId, appSlug: creds.appSlug })).catch(() => {});
 
-  // 4) verify /healthz reports auth_configured=true (only meaningful under --apply).
+  // 4) verify the project reports auth_configured=true (only meaningful under --apply).
   //    PATIENT (F23): the child must boot before it can answer; losing this race
-  //    used to record a failure for a setup that had succeeded.
+  //    used to record a failure for a setup that had succeeded. The JSON answer lives
+  //    at /api/bongos/healthz — the root /healthz says a plain "ok" (task 1004577).
   if (apply) {
     const sleep = deps.sleep || ((ms) => new Promise((r) => setTimeout(r, ms)));
     let authConfigured = false;
     for (let i = 0; i < MANIFEST_VERIFY_TRIES; i++) {
-      const out = boxExec(healthzCmd(inst), { allowFail: true });
+      const out = boxExec(authHealthzCmd(inst), { allowFail: true });
       if (oauthSecret.parseHealthzAuth(out && out.stdout).authConfigured) { authConfigured = true; break; }
       await sleep(MANIFEST_VERIFY_INTERVAL_MS);
     }
@@ -1149,7 +1160,9 @@ async function drainOAuthManifests(deps) {
     try {
       const inst = await provisioning.getInstanceById(db, mrow.instance_id);
       if (!inst) { await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: 'instance row vanished' }); errors++; continue; }
-      const result = await placeManifestCreds(inst, mrow, deps);
+      // the slug lands on the row the moment the credentials are placed (task 1004649)
+      const onCredsPlaced = (c) => provisioning.resolveOAuthManifest(db, mrow.id, 'converting', { app_id: c.appId, app_slug: c.appSlug });
+      const result = await placeManifestCreds(inst, mrow, { ...deps, onCredsPlaced });
       if (result && result.ok === false) {
         // A SPENT code is terminal, always (F23): GitHub's manifest code is
         // single-use, so resetting the row to 'code_received' guarantees the
@@ -1257,6 +1270,7 @@ async function cmdRunIntents(deps) {
   }
   await snapshotAllCoreVersions(deps); // refresh what the deploy control reads, AFTER the drain (ADR 0293 D3/D6)
   const m = await drainOAuthManifests(deps); // same tick: convert + place any GitHub-App-Manifest creds awaiting the control plane
+  await require('./provision-github-setup.js').verifyGithubAppSetups(deps).catch((e) => log(`  github-setup check failed (non-blocking): ${e.message}`)); // install + device flow, asked of GitHub with the app's key (task 1004649)
   log(`done — ran=${ran} ok=${ok} errors=${errors}; oauth-manifest converted=${m.converted} errors=${m.errors}`);
   return { ran, ok, errors, manifests: m };
 }
@@ -1438,7 +1452,7 @@ module.exports = {
   // restart an unreachable ACTIVE instance (task 1003238) — the settings leg minus the env patch
   restartInstance,
   // GitHub App Manifest flow (task 2080, ADR 0133)
-  convertManifestCode, placeManifestCreds, drainOAuthManifests, MANIFEST_UA,
+  convertManifestCode, placeManifestCreds, drainOAuthManifests, authHealthzCmd, MANIFEST_UA,
   // cross-site identity federation (ADR 0141 §4, task #1002109)
   federationHubOrigin, shouldFederate, federateInstance,
 };

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.93'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.95'; // 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/github_handback_any_device.mjs

@@ -0,0 +1,340 @@
+// tests/github_handback_any_device.mjs — coming back from GitHub works from any tab or
+// device, and the page keeps checking while you are away (task 1004650).
+//
+// Before: the GitHub hand-back sent the founder to /projects?view=new#ghstate=…, and the
+// page knew WHICH project only from that tab's sessionStorage (cb-created-instance). Approve
+// on a phone, or in another window, and you landed on a blank create page. And both wizard
+// polls parked themselves while the tab was hidden — exactly while the founder was on GitHub.
+//
+// Now the callback and setup pages send the founder to the return route, which resolves the
+// one-time state to the project the SERVER remembers for it and lands its signed-in owner on
+// /projects?view=new&id=<project>; the page asks the server's resume read for that project
+// and opens part 03 with nothing in browser storage. The polls keep going while hidden, at
+// a slower pace, and a waiting tick runs at once when the tab is seen again.
+//
+// The whole path runs for real at least once: the REAL setup route's page → its REAL hand-
+// back script → the REAL return route (302) → the REAL page code (sliced out of
+// projects.html and run in a vm, the vm-slice idiom of tests/wizard_intent_resume.mjs) with
+// EMPTY sessionStorage, whose fetches go to the REAL resume route. DB-free: the provisioning
+// data-access fns and the session resolver are stubbed on the cached modules.
+//
+// Run:  node --test --test-reporter=tap tests/github_handback_any_device.mjs
+
+import assert from 'node:assert/strict';
+import { test, before, after } from 'node:test';
+import fs from 'node:fs';
+import path from 'node:path';
+import vm from 'node:vm';
+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 LANDING = path.join(ROOT, 'modules', 'public-landing', 'public');
+// CRLF on a Windows checkout — a vm cannot run a slice with stray \r in it
+const HUB = fs.readFileSync(path.join(LANDING, 'projects.html'), 'utf8').replace(/\r\n/g, '\n');
+const SCRIPT = HUB.slice(HUB.lastIndexOf('<script>'), HUB.lastIndexOf('</script>'));
+
+// ── the world: two builders, a project each, one attempt in flight ───────────────────
+const STATE = 'ab12'.repeat(8);
+const NOW = new Date().toISOString();
+const MINE = { id: 42, owner_builder_id: 7, slug: 'mercury', domain: 'mercury.example.com', target_ref: 'acme/mercury', status: 'active', onboard_mode: 'greenfield', created_at: NOW };
+const THEIRS = { id: 43, owner_builder_id: 8, slug: 'venus', domain: 'venus.example.com', target_ref: 'zed/venus', status: 'active', onboard_mode: 'greenfield', created_at: NOW };
+const ATTEMPT = { id: 99, instance_id: 42, requested_by: 7, state: STATE, status: 'converting', app_slug: 'mercury-app', created_at: NOW, updated_at: NOW, expires_at: new Date(Date.now() + 600000).toISOString() };
+
+const provisioning = require(`${ROOT}/modules/provisioning/provisioning.js`);
+provisioning.getInstanceById = async (_db, id) => [MINE, THEIRS].find((i) => i.id === Number(id)) || null;
+provisioning.getOAuthManifestByState = async (_db, s) => (s === STATE ? ATTEMPT : null);
+provisioning.getLatestOAuthManifestForInstance = async (_db, id) => (Number(id) === 42 ? ATTEMPT : null);
+provisioning.listInstancesForOwner = async (_db, who) => [MINE, THEIRS].filter((i) => i.owner_builder_id === who);
+provisioning.recordEvent = async () => {};
+const githubSetup = require(`${ROOT}/modules/provisioning/github-setup.js`);
+githubSetup.githubSetupFacts = async () => ({});   // nothing verified yet: the install is still to do
+
+// The session is a cookie naming the builder; no cookie is nobody. Both auth doors read it.
+const api = require(`${ROOT}/src/module-api.js`);
+const whoOf = (req) => { const m = /(?:^|;\s*)who=(\d+)/.exec(String(req.headers.cookie || '')); return m ? Number(m[1]) : null; };
+api.resolveSession = async (req) => (whoOf(req) ? { builder_id: whoOf(req), status: 'active', source: 'web' } : null);
+api.requireBuilder = (req, res, next) => {
+  const who = whoOf(req);
+  if (!who) return res.status(401).json({ error: { code: 'unauthenticated' } });
+  req.builder = { id: who };
+  return next();
+};
+
+const express = require('express');
+const githubSetupRoutes = require(`${ROOT}/modules/provisioning/routes/github-setup.js`);
+let server, origin;
+before(async () => {
+  const app = express();
+  app.use('/api/bongos', githubSetupRoutes());
+  server = app.listen(0);
+  await new Promise((r) => server.once('listening', r));
+  origin = `http://127.0.0.1:${server.address().port}`;
+});
+after(() => server && server.close());
+
+const get = (p, who, extra = {}) => fetch(origin + p, { redirect: 'manual', headers: who ? { cookie: `who=${who}` } : {}, ...extra });
+
+// ── the page code, sliced (each boundary asserted below) ──────────────────────────────
+function region(startMark, endMark) {
+  const s = SCRIPT.indexOf(startMark);
+  const e = s < 0 ? -1 : SCRIPT.indexOf(endMark, s);
+  return s > 0 && e > s ? SCRIPT.slice(s, e) : null;
+}
+const POLLS = region("    /* ── C8: the wizard's polls run only while the create view is on stage", '    /* ── live build progress (task 2083)');
+const WATCH_VARS = region('    var pollTimer = null;', "    /* The done panel's own flow vocabularies");
+const START_PROGRESS = (SCRIPT.match(/ {4}function startProgress\(id\) \{[\s\S]*?\n {4}\}/) || [null])[0];
+const DOORS = region("    /* ── the hub's three doors ── */", '    return { enter: enter, leave: leave, onAuth: onAuth };');
+
+test('the page regions are still findable (a rename must fail loudly, not test nothing)', () => {
+  assert.ok(POLLS, 'the wizard poll region (C8 → the manifest poll) was not found');
+  assert.ok(WATCH_VARS, 'the progress watch vars were not found');
+  assert.ok(START_PROGRESS, 'startProgress() was not found');
+  assert.ok(DOORS, "the hub's three doors (createdRecord → enter) were not found");
+  assert.match(POLLS, /var handbackProject = /, 'the hand-back names its project in the poll region');
+  assert.match(DOORS, /function askServerResume\(focus\)/, 'the server resume ask lives with enter()');
+  assert.doesNotMatch(POLLS + DOORS, /innerHTML/, 'no live DOM from strings');
+});
+
+// A miniature browser for the sliced page: empty storage (or storage that throws), the URL
+// the founder landed on, a document whose `hidden` the test flips, recorded timers, and a
+// fetch that goes to the REAL routes as the given builder.
+function page({ url, who, storage = 'empty', name = '', hidden = false, instanceRead = null }) {
+  const u = new URL(url, 'https://hub.example');
+  const store = new Map();
+  const log = { show: [], progress: [], offers: [], fetched: [], timers: [], cleared: 0, resets: 0, rendered: 0 };
+  const listeners = {};
+  const inflight = [];
+  log.inflight = inflight;
+  const sessionStorage = storage === 'throws'
+    ? { getItem() { throw new Error('denied'); }, setItem() { throw new Error('denied'); }, removeItem() { throw new Error('denied'); } }
+    : { getItem: (k) => (store.has(k) ? store.get(k) : null), setItem: (k, v) => store.set(k, String(v)), removeItem: (k) => store.delete(k) };
+  const el = () => ({ addEventListener() {}, focus() {}, hidden: true, textContent: '' });
+  const sandbox = {
+    API: '/api/bongos', DRAFT_KEY: 'cb-create-draft-v10', CREATED_KEY: 'cb-created-instance', DECLINED_KEY: 'cb-resume-declined',
+    location: { search: u.search, hash: u.hash },
+    URLSearchParams, JSON, String, Number, Math, Object, Date, encodeURIComponent, Promise,
+    document: { hidden, addEventListener: (ev, fn) => { (listeners[ev] = listeners[ev] || []).push(fn); } },
+    sessionStorage,
+    setTimeout: (fn, ms) => { log.timers.push({ fn, ms }); return log.timers.length; },
+    clearTimeout: () => { log.cleared += 1; },
+    fetch: (p, opts) => {
+      log.fetched.push(p);
+      const answer = (instanceRead && /\/provisioning\/instances\/\d+$/.test(p))
+        ? Promise.resolve({ ok: true, status: 200, json: async () => instanceRead() })
+        : get(p, who, { method: (opts && opts.method) || 'GET' });
+      inflight.push(answer.then((r) => r.clone().text()).catch(() => null));
+      return answer;
+    },
+    $: el,
+    currentView: 'new', authKnown: true, me: { id: who, github_login: 'founder' },
+    state: { step: 0, name, slug: '', domain: '', mode: 'greenfield', owner: 'founder', repo: '', noAddress: false },
+    live: { instStatus: null, addrReady: false, manifest: null, manifestFailure: null, appSlug: null, setup: null, installUrl: null },
+    instanceId: null, watchPending: false,
+    show(step) { sandbox.state.step = step; log.show.push(step); },
+    renderDone() { log.rendered += 1; }, renderSteps() { log.rendered += 1; },
+    resetForNewProject() { log.resets += 1; },
+    saveDraft() {},
+    setProgress() {}, progressMarkup: () => '', setMoment() {}, renderProgress: () => false, addressReady: () => true,
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext([POLLS, WATCH_VARS, START_PROGRESS, DOORS].join('\n'), sandbox);
+  // the real startProgress runs too; record which project it watches
+  const realStart = sandbox.startProgress;
+  // the resume line is real markup (#wizResume); record what it is told to name
+  sandbox.paintResumeOffer = (rec) => { log.offers.push(rec ? rec.id : null); };
+  sandbox.startProgress = (id) => { log.progress.push(id); return realStart(id); };
+  return { sandbox, log, store, listeners, fire: (ev) => (listeners[ev] || []).forEach((fn) => fn()) };
+}
+// wait until every request the page made has answered and its handlers have run
+async function settle(log) {
+  for (let round = 0; round < 20; round++) {
+    const seen = log.inflight.length;
+    await Promise.all(log.inflight.slice());
+    for (let i = 0; i < 6; i++) await new Promise((r) => setImmediate(r));
+    if (log.inflight.length === seen) return;
+  }
+}
+
+// The served hand-back page, run for real: its own config and script, no opener (a phone
+// has no wizard tab behind it), and where it sends the browser.
+async function handbackFromSetupRoute() {
+  const res = await get(`/api/bongos/provisioning/github-app/setup?installation_id=5&setup_action=install&state=${STATE}`);
+  const html = await res.text();
+  const cfg = JSON.parse((html.match(/window\.__CB_SETUP__=(\{[^<]*?\});/) || [])[1] || 'null');
+  const script = (html.match(/<script>\s*(\(function\(\)\{[\s\S]*?)<\/script>\s*<\/body>/) || [])[1];
+  assert.ok(cfg && script, 'the setup route serves the hand-back page with its config and script');
+  let replaced = null;
+  const timers = [];
+  const back = { href: '' };
+  const sb = { __CB_SETUP__: cfg, opener: null, close() {}, document: { getElementById: (id) => (id === 'back' ? back : null) }, location: { replace: (u) => { replaced = u; } }, setTimeout: (fn) => timers.push(fn), encodeURIComponent };
+  sb.window = sb;
+  vm.runInNewContext(script, sb);
+  while (timers.length) timers.shift()();
+  return { replaced, html };
+}
+
+test('approved on a phone, empty storage: the real hand-back lands on the right project at part 03', async () => {
+  const { replaced, html } = await handbackFromSetupRoute();
+  assert.equal(replaced, `/api/bongos/provisioning/github-app/return?state=${STATE}`, 'the hand-back goes to the return route, not a bare create page');
+  assert.ok(html.includes(`href="/api/bongos/provisioning/github-app/return?state=${STATE}"`), 'the no-script link goes there too');
+
+  const ret = await get(replaced, 7);
+  assert.equal(ret.status, 302, 'the owner is redirected');
+  const landing = ret.headers.get('location');
+  assert.equal(landing, `/projects?view=new&id=42#ghstate=${STATE}`, 'to the project the SERVER remembers for the state');
+  assert.equal(ret.headers.get('cache-control'), 'no-store');
+
+  // the page, with NOTHING in this browser's storage
+  const { sandbox, log, store } = page({ url: landing, who: 7 });
+  assert.equal(store.size, 0, 'the browser starts with empty storage');
+  sandbox.enter(false);           // what onAuth() does once /me answers
+  assert.deepEqual(log.show, [], 'a named hand-back waits for the server instead of painting another project');
+  await settle(log);
+  assert.ok(log.fetched.includes('/api/bongos/provisioning/github-app/resume?id=42'), JSON.stringify(log.fetched));
+  assert.deepEqual(log.show, [2], 'part 03 — the created page — is shown');
+  assert.equal(log.progress[0], 42, 'and it watches project 42');
+  assert.equal(sandbox.state.slug, 'mercury');
+  assert.equal(sandbox.state.repo, 'mercury', 'the install step names the repo the server knows');
+  assert.equal(sandbox.manifestState, STATE, 'the attempt from the fragment keeps being watched');
+  assert.ok(log.fetched.some((p) => p === `/api/bongos/provisioning/github-app/status?state=${STATE}`), 'the state-keyed checklist poll runs');
+  assert.equal(JSON.parse(store.get('cb-created-instance')).id, 42, 'a reload of this tab keeps the project');
+});
+
+test('the same hand-back works where the browser refuses storage outright', async () => {
+  const { sandbox, log } = page({ url: `/projects?view=new&id=42#ghstate=${STATE}`, who: 7, storage: 'throws' });
+  sandbox.enter(false);
+  await settle(log);
+  assert.deepEqual(log.show, [2]);
+  assert.equal(log.progress[0], 42);
+});
+
+test('a different signed-in builder is refused — never shown or landed on the project', async () => {
+  const ret = await get(`/api/bongos/provisioning/github-app/return?state=${STATE}`, 8);
+  const html = await ret.text();
+  assert.equal(ret.status, 404, 'a refusal, not a redirect');
+  assert.equal(ret.headers.get('location'), null);
+  assert.match(html, /This isn’t your project/);
+  assert.doesNotMatch(html, /mercury|view=new&id=|42/, 'the page names no project');
+  const unknown = await (await get(`/api/bongos/provisioning/github-app/return?state=${'cd34'.repeat(8)}`, 8)).text();
+  assert.equal(unknown, html, 'an unknown state reads the same (no oracle about which)');
+  const malformed = await get('/api/bongos/provisioning/github-app/return?state=../../etc', 7);
+  assert.equal(malformed.status, 404);
+
+  // and the resume read gives them nothing either, even for a crafted ?id=42
+  const j = await (await get('/api/bongos/provisioning/github-app/resume?id=42', 8)).json();
+  assert.equal(j.project, null);
+  const { sandbox, log } = page({ url: '/projects?view=new&id=42', who: 8 });
+  sandbox.enter(false);
+  await settle(log);
+  assert.ok(!log.progress.includes(42), 'the page never watches a project that is not theirs');
+  assert.ok(!log.show.includes(2), 'and never opens its part 03');
+});
+
+test('not signed in → through sign-in, then back to the same return', async () => {
+  const ret = await get(`/api/bongos/provisioning/github-app/return?state=${STATE}`, null);
+  assert.equal(ret.status, 302);
+  const loc = ret.headers.get('location');
+  const u = new URL(loc, 'https://hub.example');
+  assert.equal(u.pathname, '/api/bongos/auth/web/start');
+  assert.equal(u.searchParams.get('return'), `/api/bongos/provisioning/github-app/return?state=${STATE}`, 'the return target is the return route itself');
+  assert.equal(u.searchParams.get('repos'), '1', 'with the hub sign-in door’s repo scope');
+});
+
+test('the state stays single-use where it is used: the return route changes nothing', async () => {
+  let writes = 0;
+  const prev = provisioning.attachManifestCode;
+  provisioning.attachManifestCode = async () => { writes += 1; return null; };
+  const a = await get(`/api/bongos/provisioning/github-app/return?state=${STATE}`, 7);
+  const b = await get(`/api/bongos/provisioning/github-app/return?state=${STATE}`, 7);
+  provisioning.attachManifestCode = prev;
+  assert.equal(writes, 0, 'no code exchange, no status change');
+  assert.equal(a.headers.get('location'), b.headers.get('location'), 'the owner can come back again; nobody else can at all');
+});
+
+test('opening the create page later, from any device, resumes part 03 from the server’s view', async () => {
+  const later = page({ url: '/projects?view=new', who: 7 });
+  later.sandbox.enter(false);
+  await settle(later.log);
+  assert.ok(later.log.fetched.includes('/api/bongos/provisioning/github-app/resume'));
+  assert.deepEqual(later.log.show.slice(-1), [2], 'the unfinished project comes back');
+  assert.equal(later.log.progress[0], 42);
+
+  // someone typing a new project keeps their page; the project waits on the resume line
+  const typing = page({ url: '/projects?view=new', who: 7, name: 'Second idea' });
+  typing.sandbox.enter(false);
+  await settle(typing.log);
+  assert.ok(!typing.log.progress.includes(42));
+  assert.deepEqual(typing.log.offers.filter(Boolean), [42]);
+
+  // a deliberate "New project" only offers it
+  const nav = page({ url: '/projects?view=new', who: 7 });
+  nav.sandbox.enter(true);
+  await settle(nav.log);
+  assert.ok(!nav.log.progress.includes(42));
+  assert.deepEqual(nav.log.offers.filter(Boolean), [42]);
+
+  // "Start another project" said no to it in this tab
+  const declined = page({ url: '/projects?view=new', who: 7 });
+  declined.store.set('cb-resume-declined', '42');
+  declined.sandbox.enter(false);
+  await settle(declined.log);
+  assert.ok(!declined.log.progress.includes(42));
+
+  // a connected project is not "in progress"; nor is anything for a builder with none
+  githubSetup.githubSetupFacts = async () => ({ installedAt: NOW });
+  const prevAttempt = { ...ATTEMPT };
+  Object.assign(ATTEMPT, { status: 'done' });
+  const done = await (await get('/api/bongos/provisioning/github-app/resume', 7)).json();
+  Object.assign(ATTEMPT, prevAttempt);
+  githubSetup.githubSetupFacts = async () => ({});
+  assert.equal(done.project, null, 'a project whose GitHub is connected is not resumed');
+  const none = await (await get('/api/bongos/provisioning/github-app/resume', 9)).json();
+  assert.equal(none.project, null);
+  const anon = await get('/api/bongos/provisioning/github-app/resume', null);
+  assert.equal(anon.status, 401, 'signed-in only');
+});
+
+test('a hidden tab keeps checking at the slow pace, and checks at once when seen again', async () => {
+  const { sandbox, log, fire } = page({ url: `/projects?view=new&id=42#ghstate=${STATE}`, who: 7, hidden: true });
+  sandbox.pollManifest(STATE);
+  await settle(log);
+  assert.equal(log.fetched.filter((p) => /github-app\/status/.test(p)).length, 1, 'the hidden tab still asks — it does not park');
+  assert.equal(log.timers.length, 1);
+  assert.equal(log.timers[0].ms, 20000, 'and asks again at the slow pace');
+  assert.equal(sandbox.manifestPending, false, 'nothing is parked');
+
+  // the founder comes back to the laptop: the waiting tick runs now, not in 20s
+  sandbox.document.hidden = false;
+  fire('visibilitychange');
+  await settle(log);
+  assert.equal(log.cleared, 1, 'the slow timer is dropped');
+  assert.equal(log.fetched.filter((p) => /github-app\/status/.test(p)).length, 2, 'and the check runs immediately');
+  assert.equal(log.timers[log.timers.length - 1].ms, 4000, 'then the normal pace');
+
+  // off the create view the poll still parks (C8)
+  sandbox.currentView = 'map';
+  log.timers[log.timers.length - 1].fn();
+  assert.equal(sandbox.manifestPending, true);
+});
+
+test('the laptop left waiting ticks on its own while the phone approves (the owner read, hidden tab)', async () => {
+  let installed = false;
+  const instanceRead = () => ({
+    instance: { ...MINE },
+    github_app: { status: 'done', app_slug: 'mercury-app' },
+    github_setup: { checklist: { approve: 'done', install: installed ? 'done' : 'now', sign_in: 'done', device_flow: 'later', connected: installed }, install_url: null },
+  });
+  const { sandbox, log } = page({ url: '/projects?view=new', who: 7, hidden: true, instanceRead });
+  sandbox.startProgress(42);
+  await settle(log);
+  assert.equal(sandbox.live.setup.install, 'now');
+  assert.equal(log.timers.length, 1, 'still watching while hidden');
+  assert.equal(log.timers[0].ms, 20000, 'at the slow pace');
+  installed = true;              // the phone installed the app; the runner verified it
+  log.timers[0].fn();
+  await settle(log);
+  assert.equal(sandbox.live.setup.install, 'done', 'the checklist ticked without anyone touching the laptop');
+});