@bongos/core 1.21.93 → 1.21.95

package/modules/provisioning/github-setup.js

@@ -0,0 +1,129 @@
+'use strict';
+
+// modules/provisioning/github-setup.js — "Connect GitHub" in one trip, and the checklist
+// that ticks itself (task 1004649; the design of record is docs/design/mocks/day-night-rooms/
+// part 03: Approve the <name> app on GitHub · Install it on your repo · Builders can sign in ·
+// Command-line sign-in is on).
+//
+// WHY. A founder used to make three separate trips to github.com after Create (approve the
+// app, tick "Enable Device Flow", install the app on the repo), and nothing ever checked the
+// last two. Now the manifest carries a setup_url, so GitHub sends the founder from "app
+// created" straight on to "install it on your repo" and then back to the project page — and
+// every tick on the checklist is a fact the SERVER has seen, never a click the page assumed:
+//
+//   approve  — GitHub created the app AND the runner placed its credentials (the runner
+//              records the app's slug only after the placement write, provision.js).
+//   install  — the runner, holding the app's own key, asked GitHub whether the app is
+//              installed on the project's repo and GitHub said yes ('github-app-installed').
+//              The installation_id GitHub appends to the setup_url is NOT trusted: GitHub's
+//              docs warn it can be spoofed, so that redirect only records that the founder
+//              SAYS they installed it ('github-app-install-reported'), which makes the
+//              runner look again.
+//   sign_in  — the runner saw the project report auth_configured (the manifest row 'done').
+//   device   — the runner started a device-flow sign-in with the app's client id and GitHub
+//              did not refuse it with device_flow_disabled ('github-app-device-flow').
+//              GitHub offers no manifest field and no API to switch device flow on (the
+//              spike in this task, written up in docs/design/project-startup-direction.md),
+//              so this step is OPTIONAL: it reads 'later' until the founder ticks the box on
+//              GitHub, and it never holds the project back from being alive.
+//
+// No new columns (ADR 0083 §5 additive rule; this task carries no migration): the verified
+// facts are rows of the existing append-only provisioning_events ledger, read since the
+// latest attempt began. The db is injected.
+
+// The provisioning_events names this leg writes. One table, so the runner (which writes the
+// verified ones), the setup redirect (which writes the reported one) and the reader agree.
+const SETUP_EVENTS = Object.freeze({
+  installReported: 'github-app-install-reported',
+  installed: 'github-app-installed',
+  deviceFlow: 'github-app-device-flow',
+});
+
+// How long after an attempt settles the runner keeps checking for the install and the
+// device-flow tick. Past it the checklist stops promising a self-tick for device flow
+// (the step says "turn it on later"); a fresh install report re-opens the window.
+const VERIFY_WINDOW_MS = 2 * 60 * 60 * 1000;
+
+// The one-trip install page for the app GitHub just created, carrying the attempt's state
+// so GitHub hands it back on the setup_url redirect. null until the app's slug is known.
+// PURE. (The callback page narrows it to the repo with /permissions?suggested_target_id
+// when it can learn the numeric ids — see callback-page.js.)
+function installUrlFor({ appSlug, state } = {}) {
+  if (!appSlug) return null;
+  const q = state ? `?state=${encodeURIComponent(state)}` : '';
+  return `https://github.com/apps/${encodeURIComponent(appSlug)}/installations/new${q}`;
+}
+
+// owner/repo from the instance's target_ref, or null. Strict — this string reaches a
+// public read and the callback page's GitHub lookup.
+const REPO_REF_RE = /^[A-Za-z0-9][A-Za-z0-9-]{0,38}\/[A-Za-z0-9._-]{1,100}$/;
+function targetRepo(inst) {
+  const ref = String((inst && inst.target_ref) || '').trim().replace(/\.git$/, '');
+  return REPO_REF_RE.test(ref) ? ref : null;
+}
+
+// The verified facts for one instance since `since` (the attempt's created_at): when each
+// setup event was first seen, or null. One indexed read (idx_provisioning_events_instance).
+async function githubSetupFacts(db, instanceId, since) {
+  const { rows } = await db.query(
+    `SELECT event, min(created_at) AS at FROM provisioning_events
+      WHERE instance_id = $1 AND event = ANY($2) AND created_at >= $3
+      GROUP BY event`,
+    [instanceId, Object.values(SETUP_EVENTS), since || new Date(0).toISOString()]);
+  const at = (name) => {
+    const r = rows.find((x) => x.event === name);
+    return r && r.at ? new Date(r.at).toISOString() : null;
+  };
+  return { installReportedAt: at(SETUP_EVENTS.installReported), installedAt: at(SETUP_EVENTS.installed), deviceFlowAt: at(SETUP_EVENTS.deviceFlow) };
+}
+
+// Each checklist step's state, from the latest attempt's EFFECTIVE status (manifest-truth's
+// vocabulary) + the facts above. A closed vocabulary the page turns into words:
+//   'done' · 'now' (waiting on GitHub, the founder or the platform) · 'todo' (not reached)
+//   · 'stopped' (this attempt failed at this step) · 'later' (device flow only: optional, off).
+// PURE.
+function githubChecklist(status, appSlug, facts = {}) {
+  const s = String(status || '');
+  const inFlight = s === 'pending' || s === 'code_received' || s === 'converting';
+  const failed = s === 'error' || s === 'expired';
+  const approve = appSlug ? 'done' : inFlight ? 'now' : failed ? 'stopped' : 'todo';
+  const install = facts.installedAt ? 'done' : appSlug ? 'now' : 'todo';
+  const signIn = s === 'done' ? 'done' : appSlug && failed ? 'stopped' : appSlug ? 'now' : 'todo';
+  const device = facts.deviceFlowAt ? 'done' : s === 'done' ? 'later' : 'todo';
+  return {
+    approve, install, sign_in: signIn, device_flow: device,
+    // what "is alive" waits for — device flow is optional by design
+    connected: approve === 'done' && install === 'done' && signIn === 'done',
+  };
+}
+
+// Is the runner still checking this attempt? While it is, an install or a 'later'
+// device-flow step can still tick itself, so the page keeps polling. PURE.
+function stillVerifying(row, facts = {}, now = Date.now()) {
+  const settled = row && (row.resolved_at || row.updated_at);
+  const last = Math.max(settled ? new Date(settled).getTime() : 0, facts.installReportedAt ? new Date(facts.installReportedAt).getTime() : 0);
+  return last > 0 && now - last < VERIFY_WINDOW_MS;
+}
+
+// What the public status poll and the owner's instance read add for this leg: the checklist,
+// the install link (until the install is verified), the repo it belongs on, and whether the
+// runner is still checking. `status` is manifest-truth's EFFECTIVE status. Never the raw row.
+// `withState` false (the owner's instance read) leaves the state token off the install
+// link: that read never carries the token (task 1003235), and a stateless install still
+// lands on the setup page, which sends the founder back to their projects.
+// A failed facts read is "nothing verified yet" — the honest 'now' states, never a 500.
+async function githubSetupRead(db, inst, row, status, { now = Date.now(), withState = true } = {}) {
+  if (!row) return { checklist: githubChecklist(null, null), install_url: null, repo: targetRepo(inst), verifying: false };
+  let facts = {};
+  // through module.exports so a route test can stub the one DB read on the cached module
+  try { facts = await module.exports.githubSetupFacts(db, row.instance_id, row.created_at); } catch (_) { facts = {}; }
+  const checklist = githubChecklist(status, row.app_slug, facts);
+  return {
+    checklist,
+    install_url: checklist.install === 'done' ? null : installUrlFor({ appSlug: row.app_slug, state: withState ? row.state : null }),
+    repo: targetRepo(inst),
+    verifying: stillVerifying(row, facts, now),
+  };
+}
+
+module.exports = { SETUP_EVENTS, VERIFY_WINDOW_MS, installUrlFor, targetRepo, githubSetupFacts, githubChecklist, stillVerifying, githubSetupRead };

package/modules/provisioning/module.json

@@ -21,7 +21,8 @@
       "repo-private",
       "render-standup",
       "look",
-      "demo"
+      "demo",
+      "github-setup"
     ],
     "migrations": true,
     "pollers": [

package/modules/provisioning/provisioning.js

@@ -754,6 +754,9 @@ function buildGithubAppManifest({ instanceName, slug, instanceDomain, mothership
     // is never called while inactive; point it at the mothership so it's a real host.
     hook_attributes: { url: `${String(mothershipOrigin || '').replace(/\/+$/, '')}/api/bongos/provisioning/github-app/webhook`, active: false },
     redirect_url: redirectUrl,
+    // One trip (task 1004649): after the install GitHub sends the founder here with the
+    // attempt's state, and the route hands them back to the project page.
+    setup_url: redirectUrl.replace(/\/callback$/, '/setup'), setup_on_update: true,
     callback_urls: [
       `${instOrigin}/api/gds/auth/web/callback`,
       `${instOrigin}/api/bongos/auth/web/callback`,

package/modules/provisioning/routes/callback-page.js

@@ -27,6 +27,16 @@ function esc(s) {
   ));
 }
 
+// The way back to the project (task 1004650): the hub's return route, keyed on the attempt's
+// one-time state. The SERVER resolves that state to the project it was minted for and lands
+// its signed-in owner on that project's part 03 (routes/github-setup.js), so the hand-back no
+// longer depends on what the starting tab kept in sessionStorage — approving on a phone or in
+// another window lands on the right project. No state names no project: the projects list.
+const RETURN_PATH = '/api/bongos/provisioning/github-app/return';
+function returnHref(state) {
+  return state ? `${RETURN_PATH}?state=${encodeURIComponent(state)}` : '/projects?view=mine';
+}
+
 // Accent pair resolved from the instance's own branding — the pack is the palette
 // authority (task 1002810); the literal fallbacks are the neutral pack's values, so
 // a branding validation error still paints the current family, never a stale one.
@@ -65,15 +75,15 @@ code{font-family:"Fira Code",ui-monospace,SFMono-Regular,monospace;background:rg
 // page hands them straight back: as the wizard's pop-up it closes itself so the checklist
 // tab is in front again (that tab is already polling the same status and shows the wait);
 // if the browser refuses the close, or this was a same-tab return (pop-up blocked), this
-// tab becomes the checklist. The one-time state rides the URL FRAGMENT — never sent to a
-// server — so a checklist opened here can keep watching the same attempt.
+// tab becomes the checklist. The way back is the return route (returnHref above): the
+// server names the project for the state, so the checklist opened here is the right one
+// whatever this browser remembers (task 1004650).
 // Deliberately contains NO backticks and NO ${...} so it survives the outer template
 // literal verbatim; the only server data it reads is the JSON config block above it.
 const HANDBACK_SCRIPT = `
 (function(){
   var cfg=window.__CB_SETUP__||{};
-  var back=cfg.back||'/projects?view=new';
-  if(cfg.state)back+='#ghstate='+encodeURIComponent(cfg.state);
+  var back=cfg.back||'/projects?view=mine';
   var link=document.getElementById('back');if(link)link.href=back;
   var popup=false;
   try{popup=!!window.opener&&!window.opener.closed;}catch(e){}
@@ -82,15 +92,67 @@ const HANDBACK_SCRIPT = `
 })();
 `;
 
+// Client script for the ONE-TRIP variant (task 1004649). GitHub just created the app and
+// sent the founder here; the runner now turns GitHub's code into credentials and names the
+// app. This page waits for that name on the state-keyed status poll, then sends the founder
+// straight on to installing the app — narrowed to the project's own repo when GitHub will
+// tell an anonymous caller the repo's numeric ids (a public repo; a private one falls back
+// to the plain install page, where GitHub asks which account). GitHub's setup_url brings
+// them back to the checklist afterwards. Already installed, or the attempt stopped → back
+// to the checklist at once, which says what happened. A wait past five minutes stops and
+// says so; the way back is always on the page. Same no-backtick / no-${...} rule as above.
+const INSTALL_SCRIPT = `
+(function(){
+  var cfg=window.__CB_SETUP__||{};
+  var back=cfg.back||'/projects?view=mine';
+  var link=document.getElementById('back');if(link)link.href=back;
+  var note=document.getElementById('note');
+  var say=function(t){if(note)note.textContent=t;};
+  var tries=0,MAX=150;
+  function narrow(base,ownerId,repoId){
+    var parts=String(base).split('?');
+    return parts[0]+'/permissions?'+(parts[1]?parts[1]+'&':'')+'suggested_target_id='+encodeURIComponent(ownerId)+'&repository_ids[]='+encodeURIComponent(repoId);
+  }
+  function go(url){say('Opening the install page on GitHub…');location.replace(url);}
+  function toInstall(d){
+    if(!d.repo){go(d.install_url);return;}
+    fetch('https://api.github.com/repos/'+d.repo,{headers:{Accept:'application/vnd.github+json'}})
+      .then(function(r){return r.ok?r.json():null;})
+      .then(function(j){go(j&&j.id&&j.owner&&j.owner.id?narrow(d.install_url,j.owner.id,j.id):d.install_url);})
+      .catch(function(){go(d.install_url);});
+  }
+  function tick(){
+    tries++;
+    fetch('/api/bongos/provisioning/github-app/status?state='+encodeURIComponent(cfg.state||''))
+      .then(function(r){return r.ok?r.json():null;})
+      .then(function(d){
+        if(d&&d.checklist&&d.checklist.install==='done'){location.replace(back);return;}
+        if(d&&(d.status==='error'||d.status==='expired')){location.replace(back);return;}
+        if(d&&d.install_url){toInstall(d);return;}
+        again();
+      })
+      .catch(again);
+  }
+  function again(){
+    if(tries>=MAX){say('This is taking longer than usual. Go back to your project: the install step waits for you there.');return;}
+    setTimeout(tick,2000);
+  }
+  tick();
+})();
+`;
+
 // The standalone landing page for the public GitHub redirect (the mothership serves it;
 // it is NOT the hall shell). Two variants share the Cloud Bongos brand shell (task 2096):
 //   • hand-back — ok + state + domain: a brief "GitHub app created" that returns the
 //     founder to their setup checklist, where the wait is shown (task 1004548).
+//   • install — the hand-back's inputs + next:'install' (task 1004649): "GitHub app
+//     created", then straight on to installing it on the repo (INSTALL_SCRIPT).
 //   • message — everything else (errors + the no-domain success fallback): a calm badge
 //     + `body` (server-authored, trusted HTML).
-function callbackPage({ ok, title, body, state, domain }) {
+function callbackPage({ ok, title, body, state, domain, next }) {
   const handback = !!(ok && state && domain);
-  const cfgJson = JSON.stringify({ state: state || '', domain: domain || '', back: '/projects?view=new' }).replace(/</g, '\\u003c');
+  const back = returnHref(state);
+  const cfgJson = JSON.stringify({ state: state || '', domain: domain || '', back }).replace(/</g, '\\u003c');
   const head = `<!doctype html><html lang="en"><head><meta charset="utf-8">
 <meta name="viewport" content="width=device-width, initial-scale=1">
 <meta name="color-scheme" content="light dark">
@@ -98,13 +160,26 @@ function callbackPage({ ok, title, body, state, domain }) {
 <link rel="preconnect" href="https://fonts.googleapis.com"><link rel="preconnect" href="https://fonts.gstatic.com" crossorigin>
 <link href="https://fonts.googleapis.com/css2?family=Baloo+2:wght@600;700;800&family=Quicksand:wght@400;500;600;700&family=Fira+Code&display=swap" rel="stylesheet">
 <style>${PAGE_STYLE}</style></head><body>`;
+  if (handback && next === 'install') {
+    return `${head}
+<main class="card">
+  <div class="badge-warn">✓</div>
+  <h1>${esc(title)}</h1>
+  <p class="sub">Next, install it on your repo. Taking you there now.</p>
+  <p class="muted" id="note" role="status" aria-live="polite">Waiting for GitHub to hand over the app…</p>
+  <div class="cta"><a class="btn" id="back" href="${esc(back)}">Back to my project</a></div>
+</main>
+<script>window.__CB_SETUP__=${cfgJson};</script>
+<script>${INSTALL_SCRIPT}</script>
+</body></html>`;
+  }
   if (handback) {
     return `${head}
 <main class="card">
   <div class="badge-warn">✓</div>
   <h1>${esc(title)}</h1>
   <p class="sub">Taking you back to your setup checklist — it finishes setting up <code>${esc(domain)}</code> there.</p>
-  <div class="cta"><a class="btn" id="back" href="/projects?view=new">Back to my checklist →</a></div>
+  <div class="cta"><a class="btn" id="back" href="${esc(back)}">Back to my checklist →</a></div>
 </main>
 <script>window.__CB_SETUP__=${cfgJson};</script>
 <script>${HANDBACK_SCRIPT}</script>
@@ -119,4 +194,4 @@ function callbackPage({ ok, title, body, state, domain }) {
 </body></html>`;
 }
 
-module.exports = { esc, callbackPage };
+module.exports = { esc, callbackPage, returnHref, RETURN_PATH };

package/modules/provisioning/routes/github-setup.js

@@ -0,0 +1,221 @@
+// modules/provisioning/routes/github-setup.js — the GitHub leg's two PUBLIC, state-keyed
+// routes: the progress poll the project page and the callback page read, and the setup_url
+// GitHub sends the founder to after installing the app (task 1004649 — "Connect GitHub in
+// one trip"; ADR 0133 is the manifest design).
+//
+// Its own routes file (declared in module.json) because routes/provisioning.js sits at the
+// 1500-line size ratchet; the status poll moved here from it unchanged in key and contract.
+// Both routes are public by the same model as the manifest callback: the unguessable,
+// single-use `state` minted for the signed-in owner is the only key, and neither route
+// reveals a secret or changes authority. The checklist they report is derived in
+// ../github-setup.js from what the control-plane runner has VERIFIED.
+//
+// Two signed-in routes join them (task 1004650 — the hand-back from any tab or device):
+// the RETURN route the callback and setup pages send the founder to, which lands the state's
+// own project for its owner and nobody else, and the RESUME read the project page asks when
+// its tab remembers nothing — so a phone, a second window or a fresh tab picks up part 03 of
+// the right project from what the server knows, never from sessionStorage.
+'use strict';
+
+const express = require('express');
+const api = require('../../../src/module-api');
+const { pool } = api;
+const provisioning = require('../provisioning');
+const githubSetup = require('../github-setup');
+const { makeAskRateLimiter } = require('../rate-limit');
+const { callbackPage, returnHref } = require('./callback-page');
+
+const log = api.logger('provisioning');
+
+// The state tokens this leg mints are hex (provisioning.js); anything else is not one of ours.
+const STATE_RE = /^[0-9a-f]{16,128}$/i;
+
+// An attempt or a project older than this is not "in progress" for the resume read: a
+// founder who walked away a week ago and opens the create page gets a fresh page.
+const RESUME_WINDOW_MS = 7 * 24 * 60 * 60 * 1000;
+
+// Is this instance one the hand-back may land on for this builder? Strictly the OWNER —
+// no Archon override: the return route names a project to whoever holds the state, and a
+// project page is where its owner, and only its owner, connects GitHub. A gone project is
+// no landing either. PURE.
+function ownsLanding(inst, builderId) {
+  return !!(inst && builderId != null && String(inst.owner_builder_id) === String(builderId)
+    && !inst.torn_down_at && inst.status !== 'torn_down');
+}
+
+// The project page's resume record: just what part 03 needs to name and watch the project
+// (the page reads the rest from the owner's instance read). Never the state token. PURE.
+function resumeRecord(inst) {
+  return { id: inst.id, slug: inst.slug, domain: inst.domain || null, onboard_mode: inst.onboard_mode || 'greenfield', repo: githubSetup.targetRepo(inst) };
+}
+
+// The project page to land on: part 03 of that project, by id. The state rides the
+// FRAGMENT (never sent to a server) so the page can keep watching that attempt. PURE.
+function landingHref(instanceId, state) {
+  return `/projects?view=new&id=${encodeURIComponent(String(instanceId))}${state ? `#ghstate=${encodeURIComponent(state)}` : ''}`;
+}
+
+// GitHub's installation id is digits; anything else is dropped before it reaches a log line.
+function installationIdOf(q) {
+  const s = String((q && q.installation_id) || '');
+  return /^\d{1,20}$/.test(s) ? s : null;
+}
+
+module.exports = function buildGithubSetupRouter() {
+  const router = express.Router();
+  // the page polls every few seconds, the callback page every two — per-IP, in-module
+  const statusRateLimit = makeAskRateLimiter({ max: 120 });
+  const setupRateLimit = makeAskRateLimiter({ max: 30 });
+  const returnRateLimit = makeAskRateLimiter({ max: 30 });
+
+  // GET /provisioning/github-app/status?state=<> — the PUBLIC progress read (task 1004548;
+  // the checklist since task 1004649). Reveals the manifest lifecycle status, the
+  // instance's own (already-public) domain and repo, the App's public slug, and the
+  // four-step checklist with the one-trip install link — never a secret. `ready` is true
+  // iff sign-in is verified (the auto-open signal). `terminal` now waits for the install
+  // too: a finished sign-in with the app not yet installed is not the end of the trip.
+  // rank: public — no session, no mutation, no secret; an unknown state is a 404 no-op.
+  router.get('/provisioning/github-app/status', statusRateLimit, async (req, res) => {
+    try {
+      const state = String(req.query.state || '');
+      if (!state) return res.status(400).json({ ok: false, error: 'missing_state' });
+      const row = await provisioning.getOAuthManifestByState(pool, state);
+      if (!row) return res.status(404).json({ ok: false, error: 'unknown_state' });
+      const inst = await provisioning.getInstanceById(pool, row.instance_id).catch(() => null);
+      // EFFECTIVE status + how far a failure got (task 1004572, manifest-truth.js)
+      const { status, failure } = provisioning.publicGithubApp(row);
+      const setup = await githubSetup.githubSetupRead(pool, inst, row, status);
+      const failed = status === 'error' || status === 'expired';
+      return res.json({
+        ok: true,
+        status,
+        failure,
+        ready: status === 'done',
+        terminal: failed || (setup.checklist.connected && (setup.checklist.device_flow === 'done' || !setup.verifying)),
+        domain: inst && inst.domain ? inst.domain : null,
+        instance_status: inst ? inst.status : null,
+        // The App's public slug (task 1003049) — its GitHub page is public by design.
+        app_slug: row.app_slug || null,
+        checklist: setup.checklist,
+        install_url: setup.install_url,
+        repo: setup.repo,
+        verifying: setup.verifying,
+      });
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/github-app/status', err);
+      return res.status(500).json({ ok: false, error: 'status_check_failed' });
+    }
+  });
+
+  // GET /provisioning/github-app/setup?installation_id=&setup_action=&state= — the App's
+  // setup_url (task 1004649). GitHub sends the founder's BROWSER here after they install
+  // the app (or change its repos), carrying the state we put on the install link. GitHub's
+  // own docs warn the installation_id can be spoofed, so this route trusts NOTHING it is
+  // handed: it records only that an install was REPORTED for the attempt — which makes the
+  // runner ask GitHub, with the app's own key, whether the app really is on the repo — and
+  // hands the founder back to the project page. A missing or unknown state gets the same
+  // way back, without the attempt. rank: public — a browser redirect with no session; no
+  // secret revealed, no authority changed, the only write an audit row.
+  router.get('/provisioning/github-app/setup', setupRateLimit, async (req, res) => {
+    const sendPage = (status, page) => res.status(status).type('html').send(page);
+    try {
+      const state = String(req.query.state || '');
+      const row = STATE_RE.test(state) ? await provisioning.getOAuthManifestByState(pool, state) : null;
+      if (!row) {
+        return sendPage(200, callbackPage({ ok: true, title: 'Installed on GitHub',
+          body: '<p>GitHub has installed the app. Go back to your project’s page: it checks the install itself.</p><p><a class="btn" href="/projects?view=mine">Back to my projects →</a></p>' }));
+      }
+      const id = installationIdOf(req.query);
+      const action = String(req.query.setup_action || '') === 'update' ? 'update' : 'install';
+      await provisioning.recordEvent(pool, {
+        instanceId: row.instance_id, ownerBuilderId: row.requested_by, event: githubSetup.SETUP_EVENTS.installReported,
+        detail: `GitHub returned from the app ${action}${id ? ` (installation ${id}, unverified)` : ''}; awaiting the runner's check`, actor: 'github',
+      }).catch(() => {});
+      const inst = await provisioning.getInstanceById(pool, row.instance_id).catch(() => null);
+      const domain = inst && inst.domain ? inst.domain : null;
+      return sendPage(200, domain
+        ? callbackPage({ ok: true, title: 'Installed on GitHub', state, domain })
+        : callbackPage({ ok: true, title: 'Installed on GitHub',
+          body: '<p>GitHub has installed the app. We check it on your project’s page.</p><p><a class="btn" href="/projects?view=mine">Back to my projects →</a></p>' }));
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/github-app/setup', err);
+      return sendPage(500, callbackPage({ ok: false, title: 'Something went wrong',
+        body: '<p>We couldn’t record GitHub’s response. Your project’s page checks the install itself.</p><p><a class="btn" href="/projects?view=mine">Back to my projects →</a></p>' }));
+    }
+  });
+
+  // GET /provisioning/github-app/return?state=<> — where the callback and setup pages send
+  // the founder back (task 1004650). The SERVER resolves the one-time state to the project
+  // it was minted for and 302s that project's signed-in OWNER to its part 03
+  // (/projects?view=new&id=<id>), so the hand-back works from any tab, window or device —
+  // nothing in browser storage is read. Not signed in → through the web sign-in and back
+  // here. Signed in as anyone else, an unknown or malformed state, or a gone project → one
+  // refusal page that names no project (no oracle about which). The state stays single-use
+  // where it matters: only the manifest callback's code exchange consumes it, and this route
+  // changes nothing — it reveals a project's page only to the person who already owns it.
+  // rank: public — as a GATE: it is a browser redirect, so no middleware 401s a signed-out
+  // visitor (they are sent through sign-in instead). WHO lands is decided in-handler from
+  // the live session: the project's own owner, no Archon override, and nobody else ever
+  // learns which project the state names. It reveals no secret and writes nothing.
+  router.get('/provisioning/github-app/return', returnRateLimit, async (req, res) => {
+    res.set('Cache-Control', 'no-store');
+    res.set('Referrer-Policy', 'no-referrer');
+    const refuse = () => res.status(404).type('html').send(callbackPage({ ok: false, title: 'This isn’t your project',
+      body: '<p>This link is for a project on another account, or it has expired — sign in with the account that started the project, or open your own projects.</p><p><a class="btn" href="/projects?view=mine">My projects →</a></p>' }));
+    try {
+      const state = String(req.query.state || '');
+      if (!STATE_RE.test(state)) return refuse();
+      const session = await api.resolveSession(req);
+      if (!session) {
+        // the relative return passes the web flow's open-redirect guard (safeReturnTo);
+        // the repo scope rides every hub sign-in door (ADR 0364)
+        return res.redirect(302, `/api/bongos/auth/web/start?return=${encodeURIComponent(returnHref(state))}&repos=1`);
+      }
+      if (session.status === 'inactive') return refuse();
+      const row = await provisioning.getOAuthManifestByState(pool, state);
+      const inst = row ? await provisioning.getInstanceById(pool, row.instance_id).catch(() => null) : null;
+      if (!ownsLanding(inst, session.builder_id)) return refuse();
+      return res.redirect(302, landingHref(inst.id, state));
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/github-app/return', err);
+      return res.status(500).type('html').send(callbackPage({ ok: false, title: 'Something went wrong',
+        body: '<p>We couldn’t find your project just now — it is on your projects page.</p><p><a class="btn" href="/projects?view=mine">My projects →</a></p>' }));
+    }
+  });
+
+  // GET /provisioning/github-app/resume[?id=<n>] — the project page's "which project am I
+  // connecting?" read when its tab remembers nothing (task 1004650): a hand-back on another
+  // device, a fresh tab, a cleared browser. With an id: that project, if the caller owns it.
+  // Without: the caller's newest project whose GitHub checklist is not connected yet, made or
+  // last tried within a week — so opening the create page later resumes part 03 from the
+  // server's view. Either way { project: null } when there is none; never the state token.
+  // rank: any authenticated builder (requireBuilder), own projects only — no Archon override.
+  router.get('/provisioning/github-app/resume', api.requireBuilder, async (req, res) => {
+    try {
+      const me = req.builder && req.builder.id;
+      const asked = String(req.query.id || '');
+      if (asked) {
+        if (!/^\d{1,12}$/.test(asked)) return res.json({ ok: true, project: null });
+        const inst = await provisioning.getInstanceById(pool, Number(asked)).catch(() => null);
+        return res.json({ ok: true, project: ownsLanding(inst, me) ? resumeRecord(inst) : null });
+      }
+      const now = Date.now();
+      const owned = (await provisioning.listInstancesForOwner(pool, me)).filter((i) => ownsLanding(i, me)).slice(0, 5);
+      // the (at most five) candidates are read together; the newest unfinished one wins
+      const open = await Promise.all(owned.map(async (inst) => {
+        const row = await provisioning.getLatestOAuthManifestForInstance(pool, inst.id);
+        const touched = Math.max(Date.parse(inst.created_at) || 0, row ? Date.parse(row.created_at) || 0 : 0);
+        if (now - touched > RESUME_WINDOW_MS) return false;
+        const setup = await githubSetup.githubSetupRead(pool, inst, row, row ? provisioning.publicGithubApp(row).status : null, { withState: false });
+        return !setup.checklist.connected;
+      }));
+      const found = owned.find((_inst, i) => open[i]);
+      return res.json({ ok: true, project: found ? resumeRecord(found) : null });
+    } catch (err) {
+      log.error('[provisioning] GET /provisioning/github-app/resume', err);
+      return res.status(500).json({ ok: false, error: 'resume_read_failed' });
+    }
+  });
+
+  return router;
+};

package/modules/provisioning/routes/provisioning.js

@@ -62,7 +62,7 @@ const { requireRoomOnBox } = require('../capacity-gate');   // a full box refuse
 const { adoptCredentialFault } = require('../credential-preflight'); const { termsAcknowledgement } = require('../terms-ack');
 const catalogBridge = require('../catalog-bridge');
 const capacity = require('../capacity');   // the box's slot ceiling (ADR 0285, task 1003927)
-const { callbackPage } = require('./callback-page');
+const { callbackPage } = require('./callback-page'); const githubSetup = require('../github-setup');
 // the LOUD body validators (task 1003504) — lifted out when this file hit the size ratchet
 const { badProjectDetail, badModuleSelection, badProjectType, screenedOut } = require('./body-validators'); const demo = require('../demo'); const birth = require('../birth');
 const { failFrom } = require('../public-refusal');   // every catch: a declared refusal reaches the owner, anything else stays opaque (task 1004126)
@@ -171,11 +171,7 @@ module.exports = function provisioningRoutes() {
   const router = express.Router();
   // Per-IP limiter for the public tls-check `ask` endpoint (SEC review, task 1945).
   const askRateLimit = makeAskRateLimiter();
-  // A separate, more generous per-IP limiter for the public status-poll endpoint (task
-  // 2096): the onboarding page polls it every ~3s while it waits, so legitimate volume is
-  // higher than tls-check's one-shot ask. 120/min/IP gives comfortable headroom while
-  // still shedding a flood; in-memory, own bucket (does not share tls-check's budget).
-  const statusRateLimit = makeAskRateLimiter({ max: 120 });
+  // (The public status poll and its own limiter moved to ./github-setup.js, task 1004649.)
   // Limiter for the slug-availability check (task 1002898 N10). Signed-in-only, but a
   // session is cheap and the route answers a yes/no about EVERY project slug on the
   // instance — an enumeration oracle if left unthrottled. A wizard debouncing one handle
@@ -675,6 +671,9 @@ module.exports = function provisioningRoutes() {
         instance: ownerInstance(inst),
         open_intent: open ? { action: open.action, state: open.state } : null,
         github_app: provisioning.publicGithubApp(manifest),
+        // the four-step checklist from what the runner verified (task 1004649) — the
+        // install link rides WITHOUT the state token this read never carries
+        github_setup: await githubSetup.githubSetupRead(pool, inst, manifest, manifest ? provisioning.publicGithubApp(manifest).status : null, { withState: false }),
       });
     } catch (err) {
       log.error('[provisioning] GET /provisioning/instances/:id', err);
@@ -1392,41 +1391,8 @@ module.exports = function provisioningRoutes() {
     }
   });
 
-  // GET /provisioning/github-app/status?state=<> — the PUBLIC progress read the onboarding
-  // setup checklist polls (task 1004548) to know when setup is done + where to send the owner.
-  // Same public-by-state model as the callback: the unguessable, single-use `state` token
-  // is the only key, and the response reveals only the manifest lifecycle status + the
-  // instance's own (already-public) domain — never a secret. Per-IP rate-limited because
-  // the page polls it every ~3s. `ready` is true iff the manifest reached 'done' (creds
-  // placed + /healthz verified) — the setup checklist then opens https://<domain>.
-  // rank: public — no session, no mutation, no secret; an unknown state is a 404 no-op.
-  router.get('/provisioning/github-app/status', statusRateLimit, async (req, res) => {
-    try {
-      const state = String(req.query.state || '');
-      if (!state) return res.status(400).json({ ok: false, error: 'missing_state' });
-      const row = await provisioning.getOAuthManifestByState(pool, state);
-      if (!row) return res.status(404).json({ ok: false, error: 'unknown_state' });
-      const inst = await provisioning.getInstanceById(pool, row.instance_id).catch(() => null);
-      // EFFECTIVE status + how far a failure got (task 1004572, manifest-truth.js)
-      const { status, failure } = provisioning.publicGithubApp(row);
-      return res.json({
-        ok: true,
-        status,
-        failure,
-        ready: status === 'done',
-        terminal: status === 'done' || status === 'error' || status === 'expired',
-        domain: inst && inst.domain ? inst.domain : null,
-        instance_status: inst ? inst.status : null,
-        // The App's public slug (task 1003049): lets the wizard render the one-click
-        // install link (github.com/apps/<slug>/installations/new) for the app-install
-        // step. Public info — the App's page is public by design (task 1003048).
-        app_slug: row.app_slug || null,
-      });
-    } catch (err) {
-      log.error('[provisioning] GET /provisioning/github-app/status', err);
-      return res.status(500).json({ ok: false, error: 'status_check_failed' });
-    }
-  });
+  // GET /provisioning/github-app/status + /setup — the state-keyed poll and the App's
+  // setup_url — live in ./github-setup.js (task 1004649).
 
   // GET /provisioning/github-app/callback?code=&state= — GitHub redirects the owner's
   // BROWSER here after they approve the App Manifest (task 2080, ADR 0133). It is a
@@ -1465,11 +1431,11 @@ module.exports = function provisioningRoutes() {
       }).catch(() => {});
       const inst = await provisioning.getInstanceById(pool, row.instance_id).catch(() => null);
       const domain = inst && inst.domain ? inst.domain : null;
-      // Hand-back variant (task 1004548): the page returns the founder to their setup
-      // checklist, which shows the wait for the credentials and opens the instance when
-      // it's ready. Falls back to a static success if we have no domain to point at.
+      // One trip (task 1004649): the page waits for the runner to name the app, then sends
+      // the founder on to installing it on their repo; GitHub's setup_url brings them back
+      // to the checklist. Falls back to a static success if we have no domain to point at.
       return sendPage(200, domain
-        ? callbackPage({ ok: true, title: 'GitHub app created', state, domain })
+        ? callbackPage({ ok: true, title: 'GitHub app created', state, domain, next: 'install' })
         : callbackPage({ ok: true, title: 'GitHub app created',
           body: '<p>Nice — GitHub created the app. We’re placing its credentials on your instance now; this finishes on its own within a few minutes.</p><p class="muted">You can close this tab.</p>' }));
     } catch (err) {