@bongos/core 1.21.28 → 1.21.29

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

@@ -15,7 +15,7 @@
 //
 // Shape: no DB, no network, no request object — given a plain options bag it returns
 // a string. `esc` and `callbackPage` are the whole surface; PAGE_STYLE and
-// CALLBACK_SCRIPT stay private because they are only ever this page's own body.
+// HANDBACK_SCRIPT stay private because they are only ever this page's own body.
 'use strict';
 
 const api = require('../../../src/module-api');
@@ -53,73 +53,44 @@ h1{font-family:"Baloo 2",system-ui,sans-serif;font-weight:700;font-size:1.5rem;l
 .sub p{margin:.6rem 0}
 code{font-family:"Fira Code",ui-monospace,SFMono-Regular,monospace;background:rgba(56,189,248,.14);color:var(--sky600);padding:.12em .45em;border-radius:6px;font-size:.9em;overflow-wrap:anywhere}
 @media (prefers-color-scheme:dark){code{color:var(--sky)}}
-.steps{display:flex;align-items:flex-start;justify-content:center;margin:1.9rem 0 1.1rem}
-.step{flex:1 1 0;max-width:9rem;position:relative}
-.step::before{content:"";position:absolute;top:16px;left:-50%;width:100%;height:3px;background:var(--line);z-index:0;transition:background .4s ease}
-.step:first-child::before{display:none}
-.dot{width:34px;height:34px;border-radius:50%;margin:0 auto;display:grid;place-items:center;background:var(--bg3);border:2px solid var(--line);color:var(--inkSoft);font-weight:700;font-size:.95rem;position:relative;z-index:1;transition:all .4s ease}
-.lbl{margin-top:.55rem;font-size:.78rem;color:var(--inkSoft);font-weight:600;line-height:1.25;padding:0 .2rem}
-.step.done .dot{background:var(--ok);border-color:var(--ok);color:#fff}
-.step.done::before{background:var(--ok)}
-.step.active .dot{border-color:var(--sun);color:var(--sun600);animation:pulse 1.5s ease-in-out infinite}
-.step.active .lbl{color:var(--ink)}
-.step.active .dot::after{content:"";position:absolute;inset:-3px;border-radius:50%;border:2px solid transparent;border-top-color:var(--sun);animation:spin .8s linear infinite}
-@keyframes spin{to{transform:rotate(360deg)}}
-@keyframes pulse{0%,100%{box-shadow:0 0 0 4px rgba(249,115,22,.15)}50%{box-shadow:0 0 0 9px rgba(249,115,22,.04)}}
-@media (prefers-reduced-motion:reduce){.step.active .dot,.step.active .dot::after{animation:none}}
-.status-line{min-height:1.4em;color:var(--inkSoft);font-size:.94rem;margin:.4rem auto 0;max-width:24rem;line-height:1.45}
 .cta{margin-top:1.4rem}
 .btn{display:inline-block;background:var(--sun);color:var(--sunInk);text-decoration:none;font-weight:700;font-family:"Baloo 2",system-ui,sans-serif;padding:.72rem 1.5rem;border-radius:999px;font-size:1.02rem;box-shadow:0 10px 22px -8px rgba(249,115,22,.7);transition:transform .15s ease,box-shadow .15s ease}
 .btn:hover{transform:translateY(-1px);box-shadow:0 14px 28px -8px rgba(249,115,22,.8)}
 .muted{color:var(--inkSoft);opacity:.9;font-size:.85rem;margin:1.1rem auto 0;max-width:24rem;line-height:1.45}
-.hidden{display:none!important}
 `;
 
-// Client script for the PROGRESS variant only (task 2096): poll the public status
-// endpoint, advance the stepper, and auto-open the instance the moment its credentials
-// land. 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
-// written just above it. Fails soft — a poll hiccup just retries; a long wait reveals a
-// manual "open" button rather than ever falsely erroring. The auto-open countdown runs
-// ONLY when this page is the wizard's pop-up; a same-tab return (pop-up blocked) keeps
-// the founder here with the door and a way back to the checklist (task 1003236).
-const CALLBACK_SCRIPT = `
+// Client script for the HAND-BACK variant (task 1004548; replaces the task 2096 progress
+// stepper). Placing the credentials takes minutes, and the founder used to wait for it
+// HERE, in a second tab, away from the checklist that still had steps for them. Now the
+// 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.
+// 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 state=cfg.state||'',domain=cfg.domain||'';
-  if(!state||!domain)return;
-  var target='https://'+domain;
-  var pollUrl=location.pathname.replace('/callback','/status')+'?state='+encodeURIComponent(state);
-  var steps=document.getElementById('steps'),statusEl=document.getElementById('status');
-  var cta=document.getElementById('cta'),go=document.getElementById('go'),foot=document.getElementById('foot'),back=document.getElementById('back');
-  /* Opened from the wizard as a pop-up (window.opener alive, or the tab still carries the name the wizard gave it):
-     the checklist is in the other tab, so this one may auto-open the instance. Same-tab fallback (pop-up blocked,
-     form target=_self): this IS the founder's checklist tab — never navigate it away; offer both doors (task 1003236). */
-  var popup=!!window.opener||window.name==='ghAppSetup';
-  var finished=false,tries=0,manual=false;
-  function dot(n){return steps.querySelector('[data-step="'+n+'"]');}
-  function setActive(n){for(var i=1;i<=3;i++){var el=dot(i);if(!el)continue;el.classList.remove('active','done');if(i<n){el.classList.add('done');el.querySelector('.dot').textContent='\\u2713';}else if(i===n){el.classList.add('active');}}}
-  function allDone(){for(var i=1;i<=3;i++){var el=dot(i);if(!el)continue;el.classList.remove('active');el.classList.add('done');el.querySelector('.dot').textContent='\\u2713';}}
-  function ready(){if(finished)return;finished=true;allDone();statusEl.textContent='Your instance is ready \\u2014 sign in with GitHub to claim it as owner.';cta.classList.remove('hidden');
-    if(!popup){go.textContent='Open '+domain+' \\u2192';if(back)back.classList.remove('hidden');if(foot)foot.textContent='Your setup checklist is waiting where you left it \\u2014 finish it first, or open your instance now.';return;}
-    var n=4;(function tick(){if(n<=0){location.href=target;return;}go.textContent='Opening '+domain+' in '+n+'\\u2026';n--;setTimeout(tick,1000);})();}
-  function failed(){if(finished)return;finished=true;statusEl.textContent='Setup didn\\u2019t finish. Open your instance page and start the GitHub sign-in setup again.';cta.classList.remove('hidden');go.textContent='Open '+domain+' \\u2192';}
-  function revealManual(){if(manual||finished)return;manual=true;cta.classList.remove('hidden');go.textContent='Open '+domain+' \\u2192';if(foot)foot.textContent='This is taking a little longer than usual \\u2014 you can open your instance now, or keep waiting.';}
-  function schedule(){if(!finished)setTimeout(poll,3000);}
-  function poll(){tries++;fetch(pollUrl,{headers:{accept:'application/json'},cache:'no-store'}).then(function(r){return r.ok?r.json():null;}).then(function(j){if(!j){schedule();return;}if(j.ready||j.status==='done'){ready();return;}if(j.status==='error'||j.status==='expired'){failed();return;}setActive(2);if(tries===40)revealManual();schedule();}).catch(function(){schedule();});}
-  setActive(2);poll();
+  var back=cfg.back||'/projects?view=new';
+  if(cfg.state)back+='#ghstate='+encodeURIComponent(cfg.state);
+  var link=document.getElementById('back');if(link)link.href=back;
+  var popup=false;
+  try{popup=!!window.opener&&!window.opener.closed;}catch(e){}
+  if(popup){try{window.opener.focus();}catch(e){}try{window.close();}catch(e){}}
+  setTimeout(function(){location.replace(back);},popup?700:300);
 })();
 `;
 
 // 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):
-//   • progress — ok + state + domain: an animated stepper that polls the status endpoint
-//     and auto-opens the instance when its credentials are placed.
+//   • 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).
 //   • message — everything else (errors + the no-domain success fallback): a calm badge
 //     + `body` (server-authored, trusted HTML).
 function callbackPage({ ok, title, body, state, domain }) {
-  const progress = !!(ok && state && domain);
-  const cfgJson = JSON.stringify({ state: state || '', domain: domain || '' }).replace(/</g, '\\u003c');
+  const handback = !!(ok && state && domain);
+  const cfgJson = JSON.stringify({ state: state || '', domain: domain || '', back: '/projects?view=new' }).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">
@@ -127,24 +98,16 @@ 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 (progress) {
+  if (handback) {
     return `${head}
 <main class="card">
+  <div class="badge-warn">✓</div>
   <h1>${esc(title)}</h1>
-  <p class="sub">Finishing sign-in setup for <code>${esc(domain)}</code>.</p>
-  <div class="steps" id="steps" aria-label="Setup progress">
-    <div class="step done" data-step="1"><div class="dot">✓</div><div class="lbl">GitHub app created</div></div>
-    <div class="step active" data-step="2"><div class="dot">2</div><div class="lbl">Placing credentials</div></div>
-    <div class="step" data-step="3"><div class="dot">3</div><div class="lbl">Ready to sign in</div></div>
-  </div>
-  <p class="status-line" id="status">Hang tight — keep this tab open while we finish.</p>
-  <div class="cta hidden" id="cta"><a class="btn" id="go" href="https://${esc(domain)}">Open ${esc(domain)} →</a></div>
-  <p class="muted hidden" id="back"><a href="/projects?view=new">Finish your remaining setup steps →</a></p>
-  <p class="muted" id="foot">This page opens <code>${esc(domain)}</code> for you the moment it’s ready.</p>
-  <noscript><p class="muted">When setup finishes, open <a href="https://${esc(domain)}">${esc(domain)}</a> and sign in with GitHub — that first sign-in makes you the owner.</p></noscript>
+  <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>
 </main>
 <script>window.__CB_SETUP__=${cfgJson};</script>
-<script>${CALLBACK_SCRIPT}</script>
+<script>${HANDBACK_SCRIPT}</script>
 </body></html>`;
   }
   return `${head}

package/modules/provisioning/routes/provisioning.js

@@ -1391,12 +1391,12 @@ module.exports = function provisioningRoutes() {
   });
 
   // GET /provisioning/github-app/status?state=<> — the PUBLIC progress read the onboarding
-  // callback page polls (task 2096) to know when setup is done + where to send the owner.
+  // 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 page then auto-redirects to https://<domain>.
+  // 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 {
@@ -1461,11 +1461,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;
-      // Progress variant (task 2096): the page polls …/github-app/status?state= and
-      // auto-opens the instance the moment its credentials are placed — no "come back
-      // later" dead-end. Falls back to a static success if we have no domain to poll.
+      // 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.
       return sendPage(200, domain
-        ? callbackPage({ ok: true, title: 'Setting up your instance', state, domain })
+        ? callbackPage({ ok: true, title: 'GitHub app created', state, domain })
         : 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) {

package/modules/public-landing/public/projects.html

@@ -423,6 +423,10 @@ h1[tabindex="-1"]:focus:not(:focus-visible){outline:none;}
 .samePath{font-size:13px;font-weight:400;color:var(--ink-faint);margin-top:18px;}
 .samePath a{display:inline-block;padding:3px 0;min-height:24px;line-height:18px;}
 #liveProgress{margin-top:4px;}
+/* the sign-in wait inside its step + the "open it when ready" tick (task 1004548) */
+.humanSteps .prog{margin-top:14px;}
+.autoOpen{display:flex;align-items:flex-start;gap:10px;margin-top:14px;font-size:14px;line-height:1.45;color:var(--ink-soft);cursor:pointer;min-height:24px;}
+.autoOpen input{width:18px;height:18px;margin:1px 0 0;flex:0 0 auto;accent-color:var(--accent);cursor:pointer;}
 
 /* ── the standup strip (task 2083), drawn as the lifecycle rail (DESIGN.md):
    three hairlines, a 7px dot, one lit step — no plate, no connector, no
@@ -6557,6 +6561,35 @@ summary{min-height:24px;padding:3px 0;}
         '<p>The platform team places the generated credentials; this step ticks itself once they land.</p></details>';
     }
 
+    /* "Open it when it's ready" (task 1004548). The founder now waits for sign-in on
+       this checklist instead of on the callback page, so the auto-open lives here: a
+       tick, on unless they untick it (remembered per browser), that opens the project
+       the moment it answers AND sign-in is wired. Armed only by a wait this page has
+       actually watched, so revisiting a long-finished checklist never jumps away. */
+    var AUTO_OPEN_KEY = 'cb-open-when-ready';
+    var autoOpenArmed = false;
+    var autoOpened = false;
+    function autoOpenPref() {
+      try { return localStorage.getItem(AUTO_OPEN_KEY) !== '0'; } catch (e) { return true; }
+    }
+    function autoOpenTick() {
+      return '<label class="autoOpen"><input type="checkbox" data-action="auto-open"' + (autoOpenPref() ? ' checked' : '') + '>' +
+        '<span>Open my project automatically when it’s ready</span></label>';
+    }
+    function maybeAutoOpen() {
+      var domain = resolvedDomain();
+      if (autoOpened || !autoOpenArmed || !domain || !autoOpenPref()) return;
+      if (live.manifest !== 'done' || live.instStatus !== 'active' || !live.addrReady) return;
+      autoOpened = true;
+      var url = 'https://' + domain;
+      /* a new tab keeps this checklist (two steps follow sign-in); a browser that
+         blocks an unprompted tab gets this one sent instead — the founder asked */
+      var w = null;
+      try { w = window.open(url, '_blank'); } catch (e) {}
+      if (w) { try { w.opener = null; } catch (e) {} }
+      else window.location.assign(url);
+    }
+
     /* oauth-app — the ADR 0133 one-click GitHub-App manifest flow is the primary path
        (gap 3 / idea 1000676); locked until a domain exists (the App needs the real
        callback host — the server refuses domainless with domain_required). */
@@ -6572,7 +6605,12 @@ summary{min-height:24px;padding:3px 0;}
         return '<li class="slocked" data-onboard-step="oauth-app"><b>Wire GitHub sign-in</b><p>This platform is running on a local address, and GitHub refuses app setups it can’t reach over the public internet — so the one-click flow can’t complete here. On a publicly-addressed platform this is one click.</p>' + manualOauthDetails() + '</li>';
       }
       if (live.manifest === 'done') {
-        return '<li class="sdone" data-onboard-step="oauth-app"><b>GitHub sign-in is wired</b><p>Credentials placed and verified — sign-in on <code style="font-family:var(--font-mono)">' + esc(domain) + '</code> is live.</p></li>';
+        /* the wait ends HERE now, not on the callback page (task 1004548): once the
+           project answers too, the step carries the door itself */
+        var open = live.instStatus === 'active' && live.addrReady;
+        return '<li class="sdone" data-onboard-step="oauth-app"><b>GitHub sign-in is wired</b><p>Credentials placed and verified — sign-in on <code style="font-family:var(--font-mono)">' + esc(domain) + '</code> is live.' +
+          (open ? '' : ' The door below opens once your project is answering.') + '</p>' +
+          (open ? '<a class="ghbtn" href="https://' + esc(domain) + '" target="_blank" rel="noopener">Open ' + esc(domain) + ' →</a>' : '') + '</li>';
       }
       if (live.manifest === 'error' || live.manifest === 'expired') {
         /* a plain sentence first; the raw route text folds under Technical
@@ -6589,10 +6627,14 @@ summary{min-height:24px;padding:3px 0;}
       if (live.manifest === 'code_received') {
         /* GitHub's half is done — say so, rather than keep telling the founder
            to approve an app they just approved */
-        return '<li data-onboard-step="oauth-app"><b>Wire GitHub sign-in</b><p>GitHub’s part is done. The platform is placing the credentials on your project now — this step ticks itself.</p></li>';
+        autoOpenArmed = true;
+        return '<li data-onboard-step="oauth-app"><b>Wire GitHub sign-in</b><p>GitHub’s part is done. The platform is placing the credentials on your project now — this usually takes a few minutes, and this step ticks itself.</p>' +
+          progressMarkup(1, 1, 'Placing credentials and checking sign-in works…', '', 'signin') + autoOpenTick() + '</li>';
       }
       if (live.manifest) {   /* pending — GitHub holds the manifest, nobody has approved it yet */
+        autoOpenArmed = true;
         return '<li data-onboard-step="oauth-app"><b>Wire GitHub sign-in</b><p>Waiting on GitHub — approve the app in the tab that opened. Once approved, the platform places the credentials and verifies sign-in on its own; this step ticks itself.</p>' +
+          progressMarkup(0, 0, 'Waiting for your approval on GitHub…', '', 'signin') + autoOpenTick() +
           (manifestStale ? '<button type="button" class="linklike" data-action="manifest-start">Didn’t get to GitHub? Start the setup again</button>' : '') + '</li>';
       }
       return '<li data-onboard-step="oauth-app"><b>Wire GitHub sign-in — one click</b><p>Approve a pre-filled GitHub App and the platform wires sign-in by itself: no keys to copy, and the secret never leaves the server side.</p>' +
@@ -6678,6 +6720,7 @@ summary{min-height:24px;padding:3px 0;}
         if (html === lastStepsHtml) return;   /* change-only re-render — polls never clobber open UI */
         lastStepsHtml = html;
         $('humanSteps').innerHTML = html;
+        maybeAutoOpen();
       });
     }
 
@@ -6730,6 +6773,12 @@ summary{min-height:24px;padding:3px 0;}
       });
     });
 
+    $('humanSteps').addEventListener('change', function (ev) {
+      var box = ev.target.closest && ev.target.closest('[data-action="auto-open"]');
+      if (!box) return;
+      try { localStorage.setItem(AUTO_OPEN_KEY, box.checked ? '1' : '0'); } catch (e) {}
+    });
+
     /* ── C8: the wizard's polls run only on stage, exactly like the sky.
        Off-view or hidden-tab, a due tick parks itself instead of fetching;
        enter() and the visibility flip resume whatever was parked. ── */
@@ -6754,6 +6803,13 @@ summary{min-height:24px;padding:3px 0;}
     var manifestPending = false;
     var manifestStartedAt = 0;     /* when the founder was sent to GitHub */
     var manifestStale = false;     /* ~90s with no approval → offer to start again */
+    /* the GitHub hand-back (task 1004548): the callback page returns the founder here
+       with the attempt's one-time state in the fragment (#ghstate=…), so a checklist
+       that page opened — not only the tab that started the setup — keeps watching the
+       same attempt. Read once at load, before the router's replaceState drops it. */
+    var handbackState = (function () {
+      try { var m = /[#&]ghstate=([0-9a-f]{16,128})/i.exec(location.hash || ''); return m ? m[1] : null; } catch (e) { return null; }
+    })();
     /* the manifest leg survives a reload: token + last status ride the CREATED
        record, so enter() re-seeds the step instead of re-offering "Set up
        GitHub sign-in" for an app the founder already approved (task 1003232) */
@@ -6846,7 +6902,9 @@ summary{min-height:24px;padding:3px 0;}
       standup: { names: ['Request filed', 'Standing it up', 'Live'], cls: '' },
       revive: { names: ['Revive queued', 'Standing it up', 'Back live'], cls: '' },
       teardown: { names: ['Teardown queued', 'Winding down', 'Torn down'], cls: 'flowDown' },
-      settings: { names: ['Change saved', 'Restarting to apply it', 'Applied'], cls: '' }
+      settings: { names: ['Change saved', 'Restarting to apply it', 'Applied'], cls: '' },
+      /* the GitHub sign-in wait, drawn inside its checklist step (task 1004548) */
+      signin: { names: ['Approve on GitHub', 'Placing credentials', 'Ready to sign in'], cls: '' }
     };
     /* No live-region attributes here: this strip is destroyed and rebuilt on
        every 5s tick, and a live region that is itself replaced never announces.
@@ -7171,6 +7229,13 @@ summary{min-height:24px;padding:3px 0;}
       /* restore the opt-out too — without it resolvedDomain() re-derives the
          assigned address and the done panel promises one that doesn't exist */
       state.noAddress = !!created.noaddr;
+      /* a hand-back from the callback page names the attempt GitHub just approved */
+      if (handbackState) {
+        created.manifest_state = handbackState;
+        if (created.manifest !== 'done') created.manifest = 'code_received';
+        rememberManifest(handbackState, created.manifest);
+        handbackState = null;
+      }
       /* the manifest leg's last known truth, kept across a reload */
       if (created.manifest) { live.manifest = created.manifest; live.appSlug = created.app_slug || null; }
       if (created.manifest_state && created.manifest !== 'done' && created.manifest !== 'error' && created.manifest !== 'expired') {

package/package-lock.json

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

package/package.json

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

package/release-notes.json

@@ -8924,5 +8924,11 @@
       "id": "1004492",
       "text": "The Builders Hall now asks what you are doing when you arrive: Building, Artistry, Ideating or Governing, or Legacy mode for the hall exactly as it was. It asks once per session (or never again, if you untick the box), artists"
     }
+  ],
+  "1.21.29": [
+    {
+      "id": "1004548",
+      "text": "After approving GitHub sign-in, founders go straight back to their setup checklist to wait, and can tick a box to have their project open automatically when it's ready."
+    }
   ]
 }

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.28'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.29'; // 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/provisioning_callback_page.mjs

@@ -38,7 +38,7 @@ test('esc renders an absent value as the empty string, never "null"/"undefined"'
   assert.equal(esc(false), 'false');
 });
 
-test('the progress variant escapes the title + domain it interpolates', () => {
+test('the hand-back variant escapes the title + domain it interpolates', () => {
   const html = callbackPage({
     ok: true,
     title: 'Setting up <your> instance',
@@ -49,9 +49,9 @@ test('the progress variant escapes the title + domain it interpolates', () => {
   assert.match(html, /evil&quot;\.example\.com/, 'the domain rides through esc');
   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 progress variant: the stepper + the config block the client script reads
-  assert.match(html, /id="steps"/);
-  assert.match(html, /__CB_SETUP__=\{"state":"GOODSTATE","domain":"evil\\"\.example\.com"\}/);
+  // 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"\}/);
 });
 
 test('the message variant escapes the title but passes server-authored body HTML through', () => {
@@ -63,7 +63,7 @@ test('the message variant escapes the title but passes server-authored body HTML
   assert.match(html, /<h1>This setup link has &lt;expired&gt;<\/h1>/);
   assert.match(html, /<div class="sub"><p>Ask the owner for a fresh link\.<\/p><\/div>/,
     'body is trusted server-authored HTML — the route composes it, a request never does');
-  assert.doesNotMatch(html, /id="steps"/, 'no stepper without ok + state + domain');
+  assert.doesNotMatch(html, /id="back"/, 'no hand-back without ok + state + domain');
   assert.match(html, /badge-warn">⚠️</, 'a failure wears the warning badge');
 });
 

package/tests/provisioning_github_app_routes.mjs

@@ -93,44 +93,43 @@ console.log('\nGET /provisioning/github-app/callback (the public GitHub redirect
 {
   const res = await fetch(`${base}/provisioning/github-app/callback?code=GHCODE123&state=GOODSTATE`);
   const html = await res.text();
-  t('good state → 200 text/html progress page wired to auto-open', res.status === 200 && /text\/html/.test(res.headers.get('content-type') || '') && /Setting up your instance/.test(html) && /Placing credentials/.test(html) && /__CB_SETUP__/.test(html) && html.includes('GOODSTATE'), `status=${res.status}`);
+  t('good state → 200 text/html hand-back page', res.status === 200 && /text\/html/.test(res.headers.get('content-type') || '') && /GitHub app created/.test(html) && /__CB_SETUP__/.test(html) && html.includes('GOODSTATE'), `status=${res.status}`);
   t('the page names the instance host', /mercury\.example\.com/.test(html));
-  // task 1003236: a same-tab return (pop-up blocked → form target=_self) must never be
-  // navigated away from the checklist. The page carries a hidden way back, and the
-  // countdown sits behind the pop-up guard.
-  t('carries a hidden "finish your remaining setup steps" link back to the wizard', /<p class="muted hidden" id="back"><a href="\/projects\?view=new">Finish your remaining setup steps/.test(html));
-  t('the auto-open countdown is reachable only past the pop-up guard', /var popup=!!window\.opener\|\|window\.name==='ghAppSetup';/.test(html) && /if\(!popup\)\{[^}]*return;\}\s*var n=4;\(function tick\(\)\{if\(n<=0\)\{location\.href=target;/.test(html) && (html.match(/location\.href=target/g) || []).length === 1);
+  // task 1004548: the founder no longer waits here — the page hands them back to the
+  // checklist, which shows the wait. A manual way back is always on the page.
+  t('carries a plain "back to my checklist" link (works without script)', /<a class="btn" id="back" href="\/projects\?view=new">Back to my checklist/.test(html));
+  t('no progress stepper or countdown left on the page', !/id="steps"/.test(html) && !/Placing credentials/.test(html) && !/location\.href=target/.test(html));
 
   // Run the served script itself (not a copy) against a minimal DOM, once as the
-  // wizard's pop-up and once as a same-tab return, and watch what it does to location.
+  // wizard's pop-up and once as a same-tab return, and watch what it does.
   const script = (html.match(/<script>\s*(\(function\(\)\{[\s\S]*?)<\/script>\s*<\/body>/) || [])[1];
-  t('the progress page ships the client script', typeof script === 'string' && script.length > 200);
-  async function runCallback({ opener, name }) {
+  t('the hand-back page ships the client script', typeof script === 'string' && script.length > 100);
+  async function runCallback({ opener }) {
     const vm = await import('node:vm');
-    const el = () => { const cls = new Set(); return { textContent: '', classList: { add: (...c) => c.forEach((x) => cls.add(x)), remove: (...c) => c.forEach((x) => cls.delete(x)), contains: (c) => cls.has(c) }, querySelector: () => el() }; };
-    const els = { steps: el(), status: el(), cta: el(), go: el(), foot: el(), back: el() };
-    els.steps.querySelector = () => el();
-    els.back.classList.add('hidden'); els.cta.classList.add('hidden');
+    const back = { href: '/projects?view=new' };
     const timers = [];
+    const calls = { close: 0, focusOpener: 0, replaced: null };
     const sandbox = {
-      __CB_SETUP__: { state: 'GOODSTATE', domain: 'mercury.example.com' },
-      opener, name,
-      document: { getElementById: (id) => els[id] || null },
-      location: { pathname: '/api/bongos/provisioning/github-app/callback', href: 'about:callback' },
-      fetch: async () => ({ ok: true, json: async () => ({ ok: true, ready: true, status: 'done' }) }),
+      __CB_SETUP__: { state: 'GOODSTATE', domain: 'mercury.example.com', back: '/projects?view=new' },
+      opener: opener ? { closed: false, focus: () => { calls.focusOpener++; } } : null,
+      close: () => { calls.close++; },
+      document: { getElementById: (id) => (id === 'back' ? back : null) },
+      location: { replace: (u) => { calls.replaced = u; } },
       setTimeout: (fn) => { timers.push(fn); return timers.length; },
       encodeURIComponent,
     };
     sandbox.window = sandbox;
     vm.runInNewContext(script, sandbox);
-    for (let i = 0; i < 5; i++) await new Promise((r) => setImmediate(r)); // let the poll's promise chain settle
-    for (let guard = 0; guard < 10 && timers.length; guard++) { const fn = timers.shift(); fn(); }
-    return { href: sandbox.location.href, go: els.go.textContent, backHidden: els.back.classList.contains('hidden'), foot: els.foot.textContent };
+    const replacedBeforeTimer = calls.replaced;
+    while (timers.length) timers.shift()();
+    return { ...calls, replacedBeforeTimer, backHref: back.href };
   }
-  const popup = await runCallback({ opener: {}, name: 'ghAppSetup' });
-  t('as the wizard’s pop-up it still counts down and opens the instance', popup.href === 'https://mercury.example.com', JSON.stringify(popup));
-  const sameTab = await runCallback({ opener: null, name: '' });
-  t('as a same-tab return it stays put: door shown, way back revealed, no navigation', sameTab.href === 'about:callback' && sameTab.go === 'Open mercury.example.com →' && sameTab.backHidden === false && /checklist is waiting/.test(sameTab.foot), JSON.stringify(sameTab));
+  const want = '/projects?view=new#ghstate=GOODSTATE';
+  const popup = await runCallback({ opener: true });
+  t('as the wizard’s pop-up it focuses the checklist tab and closes itself', popup.focusOpener === 1 && popup.close === 1 && popup.replacedBeforeTimer === null, JSON.stringify(popup));
+  t('…and if the browser refuses the close, the pop-up becomes the checklist', popup.replaced === want, JSON.stringify(popup));
+  const sameTab = await runCallback({ opener: false });
+  t('as a same-tab return it goes straight back to the checklist, carrying the attempt in the fragment', sameTab.close === 0 && sameTab.replaced === want && sameTab.backHref === want, JSON.stringify(sameTab));
 }
 {
   const res = await fetch(`${base}/provisioning/github-app/callback?code=X&state=NOPE`);

package/tests/wizard_auto_open.mjs

@@ -0,0 +1,94 @@
+// tests/wizard_auto_open.mjs — the checklist's "Open my project automatically when it's
+// ready" tick (task 1004548).
+//
+// WHY. The GitHub-App callback page used to hold the founder on its own stepper and open
+// the instance itself. Since task 1004548 it hands them straight back to the checklist,
+// so the auto-open moved there. The rule it must keep: open ONCE, only when sign-in is
+// wired AND the project answers, only after a wait this page actually watched (so a
+// revisit to a long-finished checklist never jumps away), never when the founder
+// unticked it — and prefer a new tab, falling back to this one when the browser blocks
+// an unprompted tab.
+//
+// Executed, not read: the real AUTO_OPEN_KEY…maybeAutoOpen region is sliced out of the
+// page's inline script and run in a node:vm under stubs (the vm-slice idiom of
+// tests/wizard_intent_resume.mjs). The slice boundaries are asserted, so a rename fails
+// loudly instead of testing nothing.
+//
+// Run:  node --test tests/wizard_auto_open.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 { fileURLToPath } from 'node:url';
+
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const LANDING = path.join(ROOT, 'modules', 'public-landing', 'public');
+const HUB = fs.readFileSync(path.join(LANDING, 'projects.html'), 'utf8').replace(/\r\n/g, '\n');
+const SCRIPT = HUB.slice(HUB.lastIndexOf('<script>'), HUB.lastIndexOf('</script>'));
+
+const START = SCRIPT.indexOf("    var AUTO_OPEN_KEY = 'cb-open-when-ready';");
+const END = SCRIPT.indexOf('    /* oauth-app — the ADR 0133 one-click GitHub-App manifest flow', START);
+const SLICE = SCRIPT.slice(START, END);
+
+test('the auto-open region is still findable (a rename must fail loudly)', () => {
+  assert.ok(START > 0 && END > START, 'both slice boundaries found');
+  assert.match(SLICE, /function maybeAutoOpen\(\)/);
+  assert.match(SLICE, /function autoOpenTick\(\)/);
+});
+
+const READY = { manifest: 'done', instStatus: 'active', addrReady: true };
+
+function run({ live = READY, armed = true, pref = null, popupBlocked = false, ticks = 1 } = {}) {
+  const store = new Map();
+  if (pref !== null) store.set('cb-open-when-ready', pref);
+  const calls = { opened: [], assigned: [] };
+  const sandbox = {
+    live: { ...live },
+    resolvedDomain: () => 'mercury.example.com',
+    localStorage: { getItem: (k) => (store.has(k) ? store.get(k) : null), setItem: (k, v) => store.set(k, v) },
+    window: {
+      open: (u, t) => { calls.opened.push([u, t]); return popupBlocked ? null : { opener: 'checklist' }; },
+      location: { assign: (u) => { calls.assigned.push(u); } },
+    },
+  };
+  sandbox.globalThis = sandbox;
+  vm.createContext(sandbox);
+  vm.runInContext(`${SLICE}\nautoOpenArmed = ${armed ? 'true' : 'false'};\nfor (var i = 0; i < ${ticks}; i++) maybeAutoOpen();\nvar tickHtml = autoOpenTick();`, sandbox);
+  return { calls, sandbox };
+}
+
+test('ready + armed + ticked (the default) → opens the project ONCE, in a new tab', () => {
+  const { calls } = run({ ticks: 3 });
+  assert.deepEqual(calls.opened, [['https://mercury.example.com', '_blank']], 'one new tab, however many renders follow');
+  assert.deepEqual(calls.assigned, [], 'this checklist stays put');
+});
+
+test('a browser that blocks the unprompted tab sends THIS tab instead — the founder asked', () => {
+  const { calls } = run({ popupBlocked: true });
+  assert.deepEqual(calls.assigned, ['https://mercury.example.com']);
+});
+
+test('nothing opens until sign-in is wired AND the project answers', () => {
+  for (const live of [
+    { ...READY, manifest: 'code_received' },
+    { ...READY, instStatus: 'provisioning' },
+    { ...READY, addrReady: false },
+  ]) {
+    const { calls } = run({ live });
+    assert.deepEqual([calls.opened, calls.assigned], [[], []], JSON.stringify(live));
+  }
+});
+
+test('unticked → never opens, and the tick renders unticked', () => {
+  const { calls, sandbox } = run({ pref: '0' });
+  assert.deepEqual([calls.opened, calls.assigned], [[], []]);
+  assert.doesNotMatch(sandbox.tickHtml, / checked/);
+  assert.match(run().sandbox.tickHtml, / checked>/, 'the default is ticked');
+});
+
+test('a checklist that never watched the wait (a revisit) does not jump away', () => {
+  const { calls } = run({ armed: false });
+  assert.deepEqual([calls.opened, calls.assigned], [[], []]);
+});

package/tests/wizard_intent_resume.mjs

@@ -70,10 +70,10 @@ test('both slices are still findable (a rename must fail loudly, not silently pa
 // A faithful miniature: the stubs record what enterCreated ASKS FOR, which is the whole
 // contract — which panel is shown, whether the answers were reset, and what the offer
 // above step 1 was told to name.
-function runEnter({ focus, resumeIntent = false, draft = null, record }) {
+function runEnter({ focus, resumeIntent = false, draft = null, record, handbackState = null }) {
   const store = new Map();
   if (draft) store.set('draft', JSON.stringify(draft));
-  const calls = { show: [], resets: 0, offer: [], done: 0, progress: [], polls: 0, focused: 0 };
+  const calls = { show: [], resets: 0, offer: [], done: 0, progress: [], polls: 0, focused: 0, remembered: [] };
   // state.step is the DONE step for the whole life of a finished standup — the value
   // a draft-blind reading would have trusted
   const state = { step: draft ? draft.step : 6, name: 'Mercury', slug: 'mercury', domain: '', mode: 'greenfield', noAddress: false, modules: null };
@@ -83,6 +83,8 @@ function runEnter({ focus, resumeIntent = false, draft = null, record }) {
     live: { manifest: null, appSlug: null },
     manifestState: null,
     manifestPending: false,
+    handbackState,   // the #ghstate=… a GitHub hand-back carries (task 1004548); null on a plain arrival
+    rememberManifest(st, status) { calls.remembered.push([st, status]); },
     sessionStorage: { getItem: (k) => (store.has(k) ? store.get(k) : null) },
     resetForNewProject() { calls.resets += 1; state.step = 1; state.name = ''; state.slug = ''; },
     paintResumeOffer(c) { calls.offer.push(c ? (c.name || c.slug) : null); },
@@ -111,6 +113,19 @@ test('a reload / Back / identity settle (focus false) still resumes the done pan
   assert.deepEqual(calls.offer, [null], 'the offer is down — the done panel is on stage, not step 1');
 });
 
+test('a hand-back from the GitHub callback page resumes watching THAT attempt (task 1004548)', () => {
+  const { calls, sandbox } = runEnter({ focus: false, record: { ...REC }, handbackState: 'ab'.repeat(32) });
+  assert.deepEqual(calls.show, [[6, false]], 'the founder lands on their checklist');
+  assert.equal(sandbox.manifestState, 'ab'.repeat(32), 'the sign-in step polls the attempt GitHub just approved');
+  assert.equal(sandbox.manifestPending, true, 'and the poll is queued for resumePolls()');
+  assert.equal(sandbox.live.manifest, 'code_received', 'it shows the wait, not "Set up GitHub sign-in" again');
+  assert.deepEqual(calls.remembered, [['ab'.repeat(32), 'code_received']], 'the attempt is kept across a reload');
+  assert.equal(sandbox.handbackState, null, 'read once — a later arrival is not a hand-back');
+  const done = runEnter({ focus: false, record: { ...REC, manifest: 'done' }, handbackState: 'cd'.repeat(32) });
+  assert.equal(done.sandbox.live.manifest, 'done', 'a finished setup is never walked back to waiting');
+  assert.equal(done.sandbox.manifestPending, false, 'and nothing is polled for it');
+});
+
 test('a deliberate "New project" click after a finished standup opens a FRESH step 1', () => {
   const { calls, state } = runEnter({ focus: true, record: REC });
   assert.equal(calls.done, 0, 'the previous project\'s done panel is not painted');