@bongos/core 1.21.96 → 1.21.97

package/modules/provisioning/github-setup.js

@@ -40,8 +40,18 @@ const SETUP_EVENTS = Object.freeze({
   // the organisation the founder chose to make the app on (task 1004651); its detail is
   // the org's login. Written by the mint route; absent = the founder's personal account.
   appOrg: 'github-app-org',
+  // the founder pressed "Pick up where it stopped" or "Check again" (task 1004652). Like an
+  // install report it re-opens the runner's checking window; it claims nothing itself.
+  checkRequested: 'github-app-check-requested',
 });
 
+const { effectiveManifestStatus } = require('./manifest-truth');
+
+// GitHub's manifest conversion code lasts an hour from GitHub's redirect, and the redirect
+// comes after the link was minted, so an attempt younger than this can still be converted
+// with the code it already holds — no new approval, so no second app (task 1004652).
+const CODE_LIFE_MS = 60 * 60 * 1000;
+
 // A GitHub login (1-39 chars, letters/digits and single inner hyphens). The org name the
 // mint route takes from the page passes this before it reaches a GitHub URL, and the
 // recorded one passes it again before it reaches a link. PURE.
@@ -89,6 +99,7 @@ async function githubSetupFacts(db, instanceId, since) {
   const org = find(SETUP_EVENTS.appOrg);
   return {
     installReportedAt: at(SETUP_EVENTS.installReported), installedAt: at(SETUP_EVENTS.installed), deviceFlowAt: at(SETUP_EVENTS.deviceFlow),
+    checkRequestedAt: at(SETUP_EVENTS.checkRequested),
     appOrg: org && validGithubLogin(org.detail) ? org.detail : null,
   };
 }
@@ -117,10 +128,65 @@ function githubChecklist(status, appSlug, facts = {}) {
 // 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);
+  const t = (iso) => (iso ? new Date(iso).getTime() : 0);
+  const last = Math.max(t(settled), t(facts.installReportedAt), t(facts.checkRequestedAt));
   return last > 0 && now - last < VERIFY_WINDOW_MS;
 }
 
+// What "Pick up where it stopped" does for this attempt (task 1004652) — a closed
+// vocabulary, and never "make another app" once GitHub has made one:
+//   'reopen'   — the link is still waiting on GitHub: post the SAME attempt again.
+//   'fresh'    — nothing was made on GitHub (the link lapsed, or the runner never took
+//                it up): a new link is safe.
+//   'convert'  — GitHub approved and the code it gave is still young: convert it again.
+//   'check'    — the app exists with its keys placed, a step is unverified and the runner
+//                has stopped checking: ask it to look again (sign-in, install, device flow).
+//   'operator' — GitHub approved but the app's keys never reached us and its code is
+//                spent or too old: only the platform team can finish it.
+//   null       — nothing to pick up: in flight, still being checked, or all done.
+// PURE.
+function pickUpFor(row, status, checklist, verifying, now = Date.now()) {
+  if (!row) return null;
+  if (status === 'pending') return 'reopen';
+  if (status === 'expired') return 'fresh';
+  if (row.app_slug || row.app_id) {
+    if (checklist && checklist.connected && checklist.device_flow === 'done') return null;
+    return verifying ? null : 'check';
+  }
+  if (status !== 'error') return null;
+  if (!(Number(row.attempts) > 0)) return 'fresh';
+  const age = now - new Date(row.created_at || 0).getTime();
+  return row.github_code && age < CODE_LIFE_MS ? 'convert' : 'operator';
+}
+
+// May the mint route make a new link for this instance, given its latest attempt (task
+// 1004652)? null = yes. { reuse } = the latest link is still waiting on GitHub, so hand
+// back the SAME state (a second click, a reopened tab, another device) instead of a second
+// attempt. { refuse, message } = GitHub has approved an app for this project already, so a
+// new link would make a second one. PURE.
+function mintGuard(row, now = Date.now()) {
+  if (!row) return null;
+  const status = effectiveManifestStatus(row, now);
+  if (status === 'pending') return { reuse: row.state, expiresAt: new Date(row.expires_at).toISOString() };
+  if (status === 'expired' || (status === 'error' && !(Number(row.attempts) > 0) && !row.app_id)) return null;
+  if (status === 'code_received' || status === 'converting') {
+    return { refuse: 'github_in_progress', message: 'GitHub already approved this project’s app, and the platform is finishing it. The checklist ticks itself.' };
+  }
+  return { refuse: 'app_exists', message: 'GitHub already made this project’s app, so we won’t make a second one. Pick up where it stopped instead.' };
+}
+
+// Put an approved attempt whose conversion stopped back in the runner's queue, with the
+// code it still holds (pickUpFor 'convert'). The attempt count restarts so the runner
+// tries it again. Only an attempt still in that shape moves; false otherwise.
+async function requeueConversion(db, id) {
+  const { rows } = await db.query(
+    `UPDATE provisioning_oauth_manifests
+        SET status = 'code_received', attempts = 0, last_error = NULL, resolved_at = NULL, updated_at = now()
+      WHERE id = $1 AND status = 'error' AND app_id IS NULL AND github_code IS NOT NULL
+      RETURNING id`, [id]);
+  return rows.length > 0;
+}
+
 // 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.
@@ -129,16 +195,19 @@ function stillVerifying(row, facts = {}, now = Date.now()) {
 // 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, app_org: null };
+  if (!row) return { checklist: githubChecklist(null, null), install_url: null, repo: targetRepo(inst), verifying: false, app_org: null, pick_up: null };
   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);
+  const verifying = stillVerifying(row, facts, now);
   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),
+    verifying,
+    // what "Pick up where it stopped" will do (task 1004652); never a secret, never the code
+    pick_up: pickUpFor(row, status, checklist, verifying, now),
     // the organisation this attempt makes the app on, or null for the founder's account
     // (task 1004651): the page links the app's settings under the right owner
     app_org: validGithubLogin(facts.appOrg) ? facts.appOrg : null,
@@ -147,5 +216,5 @@ async function githubSetupRead(db, inst, row, status, { now = Date.now(), withSt
 
 module.exports = {
   SETUP_EVENTS, VERIFY_WINDOW_MS, installUrlFor, targetRepo, githubSetupFacts, githubChecklist, stillVerifying, githubSetupRead,
-  validGithubLogin,
+  validGithubLogin, pickUpFor, mintGuard, requeueConversion,
 };

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

@@ -91,7 +91,8 @@ module.exports = function buildGithubSetupRouter() {
         status,
         failure,
         ready: status === 'done',
-        terminal: failed || (setup.checklist.connected && (setup.checklist.device_flow === 'done' || !setup.verifying)),
+        // a stopped sign-in the runner is still re-checking is not the end (task 1004652)
+        terminal: (failed && !setup.verifying) || (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.
@@ -101,6 +102,7 @@ module.exports = function buildGithubSetupRouter() {
         repo: setup.repo,
         verifying: setup.verifying,
         app_org: setup.app_org,
+        pick_up: setup.pick_up,
       });
     } catch (err) {
       log.error('[provisioning] GET /provisioning/github-app/status', err);
@@ -184,6 +186,46 @@ module.exports = function buildGithubSetupRouter() {
     }
   });
 
+  // POST /provisioning/instances/:id/github-app/pick-up — "Pick up where it stopped" and
+  // "Check again" (task 1004652). It resumes the latest attempt from the step it stopped at,
+  // with the app GitHub already made, and never mints a new link: 'convert' puts an approved
+  // attempt whose code is still young back in the runner's queue; 'check' records a check
+  // request, which re-opens the runner's checking window for sign-in, the install and
+  // device flow. Every other pick-up is the page's own ('reopen' and 'fresh' go through the
+  // mint route, whose guard reuses or refuses; 'operator' files a blocker), so they are a
+  // 409 naming the action. Answers with the fresh read. rank: any authenticated builder
+  // (requireBuilder), the project's OWNER only — no Archon override, as with the mint route;
+  // anyone else gets the same 404 as a missing project.
+  router.post('/provisioning/instances/:id/github-app/pick-up', api.requireBuilder, returnRateLimit, async (req, res) => {
+    const id = /^\d{1,12}$/.test(String(req.params.id)) ? Number(req.params.id) : null;
+    if (!id) return res.fail('bad_id', 400);
+    try {
+      const inst = await provisioning.getInstanceById(pool, id);
+      if (!ownsLanding(inst, req.builder && req.builder.id)) return res.fail('instance_not_found', 404);
+      const row = await provisioning.getLatestOAuthManifestForInstance(pool, id);
+      const read = async (r) => githubSetup.githubSetupRead(pool, inst, r, r ? provisioning.publicGithubApp(r).status : null, { withState: false });
+      const before = await read(row);
+      const action = before.pick_up;
+      if (action === 'convert') {
+        if (!(await githubSetup.requeueConversion(pool, row.id))) return res.fail('nothing_to_pick_up', { status: 409, message: 'This step has already moved on.' });
+      } else if (action === 'check') {
+        await provisioning.recordEvent(pool, {
+          instanceId: id, ownerBuilderId: req.builder.id, event: githubSetup.SETUP_EVENTS.checkRequested,
+          detail: 'the founder asked to pick up the GitHub setup where it stopped', actor: 'api:self',
+        });
+      } else {
+        return res.fail('nothing_to_pick_up', { status: 409, message: 'Nothing to pick up here.', action: action || null });
+      }
+      const after = await provisioning.getLatestOAuthManifestForInstance(pool, id);
+      const pub = provisioning.publicGithubApp(after);
+      const setup = await read(after);
+      return res.json({ ok: true, action, status: pub.status, failure: pub.failure, app_slug: after.app_slug || null, ...setup });
+    } catch (err) {
+      log.error('[provisioning] POST /provisioning/instances/:id/github-app/pick-up', err);
+      return res.status(500).json({ ok: false, error: 'pick_up_failed' });
+    }
+  });
+
   // 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.

package/modules/provisioning/routes/provisioning.js

@@ -1268,12 +1268,16 @@ module.exports = function provisioningRoutes() {
         return res.fail('org_required', { status: 400, message: 'Name the GitHub organisation to make the app on.' });
       }
       const account = wantsOrg ? 'org' : 'personal';
-      const state = crypto.randomBytes(32).toString('hex');
-      const expiresAt = new Date(Date.now() + MANIFEST_STATE_TTL_MS).toISOString();
-      await provisioning.createOAuthManifest(pool, { instanceId: id, state, requestedBy: req.builder.id, expiresAt });
+      // never a second app (task 1004652): a link still waiting on GitHub is handed back,
+      // and once GitHub has approved one for this project no new link is made
+      const guard = githubSetup.mintGuard(await provisioning.getLatestOAuthManifestForInstance(pool, id));
+      if (guard && guard.refuse) return res.fail(guard.refuse, { status: 409, message: guard.message });
+      const state = guard ? guard.reuse : crypto.randomBytes(32).toString('hex');
+      const expiresAt = guard ? guard.expiresAt : new Date(Date.now() + MANIFEST_STATE_TTL_MS).toISOString();
+      if (!guard) await provisioning.createOAuthManifest(pool, { instanceId: id, state, requestedBy: req.builder.id, expiresAt });
       await provisioning.recordEvent(pool, {
         instanceId: id, ownerBuilderId: req.builder.id, event: 'oauth-manifest-start',
-        detail: 'GitHub App Manifest link minted', actor: 'api:self',
+        detail: guard ? 'GitHub App Manifest link reopened (same attempt)' : 'GitHub App Manifest link minted', actor: 'api:self',
       }).catch(() => {});
       // which account owns this attempt's app, so the page can link its settings there
       // from any tab or device (github-setup.js reads it back as app_org)

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

@@ -608,6 +608,10 @@ body:has(#view-new:not([hidden])) footer.foot{position:relative;z-index:1;backgr
   display:inline-flex;align-items:center;justify-content:center;font-family:var(--font-body);font-size:13px;letter-spacing:0;}
 #panel-done .humanSteps>li.sdone::before{content:"✓";text-transform:none;color:var(--ok);background:color-mix(in srgb,var(--ok) 12%,transparent);border:1px solid var(--ok);}
 #panel-done .humanSteps>li.slocked::before{border:1px solid var(--rule-soft);}
+/* a stopped step (task 1004652, the mockup's "!" dot): what stopped, and the button that fixes it */
+#panel-done .humanSteps>li.sstopped::before{content:"!";color:var(--err);background:color-mix(in srgb,var(--err) 10%,transparent);border:1px solid var(--err);}
+.humanSteps .linklike{display:block;margin-top:10px;min-height:24px;padding:3px 0;background:none;border:0;cursor:pointer;font-family:var(--font-body);font-size:13.5px;color:var(--link-ink);text-decoration:underline;text-underline-offset:3px;text-align:left;}
+.humanSteps .linklike:hover{color:var(--ink);}
 /* the optional step (command-line sign-in, task 1004649): a dashed ring until it ticks */
 #panel-done .humanSteps>li.soptional:not(.sdone)::before{border-style:dashed;}
 #panel-done .humanSteps b{font-size:15px;line-height:24px;}
@@ -6822,7 +6826,7 @@ summary{min-height:24px;padding:3px 0;}
       return '<a href="' + (instanceId ? '?view=manage&id=' + encodeURIComponent(instanceId) : '?view=mine') +
         '">' + label + '</a>';
     }
-    var live = { instStatus: null, addrReady: false, manifest: null, manifestMsg: '', manifestCode: '', manifestFailure: null, appSlug: null, appOrg: null, setup: null, installUrl: null };
+    var live = { instStatus: null, addrReady: false, manifest: null, manifestMsg: '', manifestCode: '', manifestFailure: null, appSlug: null, appOrg: null, setup: null, installUrl: null, pickUp: null, verifying: false, askedPlatform: false };
     var planPromises = {};             /* mode|domain → Promise<steps[]> */
     var lastStepsHtml = '';
     var lastProgHtml = '';            /* same change-only contract, for the progress strip */
@@ -6926,6 +6930,18 @@ summary{min-height:24px;padding:3px 0;}
        the server verified (live.setup, the status poll's `checklist`). Every value that
        reaches the markup goes through esc(). */
     function ghStep(key) { return live.setup && live.setup[key]; }
+    /* "Pick up where it stopped" (task 1004652): a stopped step says what stopped in one plain
+       sentence and carries the action that fixes it, with the app GitHub already made, never a
+       second one. live.pickUp is the server's word for what that action does (github-setup.js
+       pickUpFor); live.verifying is whether the runner is still checking. Static words only. */
+    var ghTabTrouble = null;   /* 'behind' | 'closed': what this page saw of the GitHub tab it opened */
+    var NO_SECOND_APP = 'Nothing is lost, and no second app will be made.';
+    function pickUpBtn() { return '<button type="button" class="ghbtn" data-action="pick-up">Pick up where it stopped</button>'; }
+    function askPlatformBtn() {
+      if (live.askedPlatform === true) return '<p>Sent. The platform team has it and finishes it from here; there is nothing else for you to do.</p>';
+      return (live.askedPlatform === 'failed' ? '<p>That didn’t send. Try again.</p>' : '') +
+        '<button type="button" class="linklike" data-action="ask-platform">Send it to the platform team</button>';
+    }
     function appTitle() { return 'Approve the ' + esc(state.name || state.slug || 'project') + ' app on GitHub'; }
     /* the organisation that owns the app, when the founder made it on one (task 1004651) */
     function appOrgLogin() {
@@ -6950,7 +6966,11 @@ summary{min-height:24px;padding:3px 0;}
       /* GitHub made the app and the platform placed its keys: the slug is recorded only
          after the placement (the runner), so a known slug outside a failure is the tick —
          a fact, whatever the venue says about starting a NEW trip */
-      if (live.manifest !== 'error' && live.manifest !== 'expired' && (ghStep('approve') === 'done' || live.appSlug)) {
+      /* …including when a LATER step stopped (sign-in unconfirmed): the app and its keys are
+         real, so this step stays ticked and the stopped one says so (task 1004652) */
+      var appMade = (ghStep('approve') === 'done' || live.appSlug) && live.manifest !== 'expired' &&
+        (live.manifest !== 'error' || live.manifestFailure === 'sign_in_unconfirmed');
+      if (appMade) {
         return '<li class="sdone" data-onboard-step="oauth-app"><b>' + appTitle() + '</b><p>GitHub made the app, and its keys are on your project.</p></li>';
       }
       /* honesty about the venue (owner walk, 2026-08-12): GitHub rejects app
@@ -6964,24 +6984,24 @@ summary{min-height:24px;padding:3px 0;}
            details (task 1003244). The one refusal a founder can act on — no
            address yet — says where to go instead of what the server said. */
         var snag, raw = '';
-        /* a failure AFTER GitHub's approval left an app on the founder's account,
-           so "nothing was changed" would be false — the server says how far it got
-           (live.manifestFailure, task 1004572) and the words follow it */
-        if (live.manifest === 'expired') snag = 'That setup link expired (they last 30 minutes) — mint a fresh one.';
+        /* a failure AFTER GitHub's approval left an app on the founder's account, so
+           "nothing was changed" would be false, and a new link would make a second app —
+           the server says how far it got (live.manifestFailure, task 1004572) and what
+           picking it up does (live.pickUp, task 1004652); the words and the action follow */
+        var act = '<button type="button" class="ghbtn" data-action="manifest-start">' + GH_ICON + 'Connect GitHub ↗</button>' + manualOauthDetails();
+        if (live.manifest === 'expired') snag = 'That setup link expired (they last 30 minutes) before GitHub was approved, so nothing was made on GitHub. Start a fresh one.';
         else if (live.manifestCode === 'domain_required') snag = 'This project needs an address first — attach one from ' + projectPageLink('its own page') + ', then come back to this step.';
-        else if (live.manifestFailure === 'sign_in_unconfirmed') {
-          var appLink = live.appSlug ? '<a href="' + esc(appSettingsUrl()) + '" target="_blank" rel="noopener">your app on GitHub</a>' : 'the app on your GitHub account';
-          return '<li data-onboard-step="oauth-app"><b>' + appTitle() + '</b><p>GitHub approved the app and the platform placed its credentials on your project, but your project didn’t confirm that sign-in works. Trying again would make a second app on your GitHub account and is unlikely to fix this — it needs a look from the platform team. <a href="/contact">Contact us</a> and mention ' + appLink + '.</p>' +
-            progressMarkup(1, 1, 'Stopped: your project didn’t confirm sign-in.', 'isErr', 'signin') +
-            '<button type="button" class="linklike" data-action="manifest-start">Try again anyway</button></li>';
+        else if (live.pickUp === 'convert') {
+          snag = 'GitHub approved the app, and the platform stopped before it finished collecting the app’s keys. ' + NO_SECOND_APP;
+          act = pickUpBtn();
+        }
+        else if (live.manifestFailure === 'finish_failed') {
+          snag = 'GitHub made the app, but its keys never reached your project, so it can’t be used yet. Making another would leave you with two, so we won’t: the platform team finishes this one. Send it to them from here.';
+          act = askPlatformBtn();
         }
-        else if (live.manifestFailure === 'finish_failed') snag = appOrgLogin()
-          ? 'GitHub approved the app, but the platform couldn’t finish setting up sign-in on your project. The app GitHub made is still on ' + esc(appOrgLogin()) + ' — delete it first (the organisation’s Settings → Developer settings → GitHub Apps) so you don’t end up with two, then try again.'
-          : 'GitHub approved the app, but the platform couldn’t finish setting up sign-in on your project. The app GitHub made is still on your account — delete it first (GitHub → Settings → Developer settings → GitHub Apps) so you don’t end up with two, then try again.';
         else { snag = 'GitHub setup didn’t start. Nothing was changed on GitHub — try again.'; raw = live.manifestMsg; }
-        return '<li data-onboard-step="oauth-app"><b>' + appTitle() + '</b><p>' + snag + '</p>' +
-          (raw ? '<details><summary>Technical details</summary><p>' + esc(raw) + '</p></details>' : '') +
-          '<button type="button" class="ghbtn" data-action="manifest-start">' + GH_ICON + 'Connect GitHub ↗</button>' + manualOauthDetails() + '</li>';
+        return '<li class="sstopped" data-onboard-step="oauth-app"><b>' + appTitle() + '</b><p>' + snag + '</p>' +
+          (raw ? '<details><summary>Technical details</summary><p>' + esc(raw) + '</p></details>' : '') + act + '</li>';
       }
       if (live.manifest === 'code_received' || live.manifest === 'converting') {
         /* GitHub's half of the approval is done — say so, rather than keep telling the
@@ -6992,9 +7012,19 @@ summary{min-height:24px;padding:3px 0;}
       }
       if (live.manifest) {   /* pending — GitHub holds the manifest, nobody has approved it yet */
         autoOpenArmed = true;
-        return '<li data-onboard-step="oauth-app"><b>' + appTitle() + '</b><p>Waiting on GitHub — approve the app in the tab that opened. No GitHub tab? It may have opened behind this window or in another one. Once approved, GitHub takes you straight on to installing it on your repo, then back here; every step ticks itself.</p>' +
+        /* the tab this page opened, as seen from here (task 1004652): behind this window, or
+           closed before the approval. "Reopen GitHub" posts the SAME attempt again (the mint
+           route hands back a link still waiting), so it can never make a second app. */
+        var wait = ghTabTrouble === 'closed'
+          ? 'The GitHub tab closed before the app was approved, so nothing was made on GitHub. Reopen it to carry on with this same setup.'
+          : ghTabTrouble === 'behind'
+            ? 'Your GitHub tab opened behind this window. Reopen it to bring it to the front; it is this same setup, so no second app will be made.'
+            : 'Waiting on GitHub — approve the app in the tab that opened. No GitHub tab? It may have opened behind this window or in another one. Once approved, GitHub takes you straight on to installing it on your repo, then back here; every step ticks itself.';
+        return '<li data-onboard-step="oauth-app"><b>' + appTitle() + '</b><p>' + wait + '</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>';
+          (ghTabTrouble
+            ? '<button type="button" class="ghbtn" data-action="reopen-github">' + GH_ICON + 'Reopen GitHub ↗</button>'
+            : '<button type="button" class="linklike" data-action="reopen-github">No GitHub tab? Reopen GitHub</button>') + '</li>';
       }
       return '<li data-onboard-step="oauth-app"><b>' + appTitle() + '</b><p>One trip to GitHub: approve the app, install it on your repo, and you land back here. No keys to copy, and the secret never leaves the server side.</p>' +
         '<button type="button" class="ghbtn" data-action="manifest-start">' + GH_ICON + 'Connect GitHub ↗</button>' + manualOauthDetails() + '</li>';
@@ -7019,7 +7049,11 @@ summary{min-height:24px;padding:3px 0;}
         (appUrl
           ? 'open <a href="' + appUrl + '" target="_blank" rel="noopener">your app’s settings</a>, check <strong>Enable Device Flow</strong>, and save. '
           : 'GitHub → Settings → Developer settings → GitHub Apps → your app → check <strong>Enable Device Flow</strong> → save. ') +
-        'We tick this when GitHub has it on. Until then builders sign in on the web, and terminal sign-in falls back to a web token from the hall’s Settings page.</p></li>';
+        'We tick this when GitHub has it on. Until then builders sign in on the web, and terminal sign-in falls back to a web token from the hall’s Settings page.</p>' +
+        /* past the runner's checking window (task 1004652): ask it to look again. The
+           install step carries the same action while it is unverified, so it shows here
+           only once the install has ticked. */
+        (live.pickUp === 'check' && ghStep('install') === 'done' ? '<button type="button" class="linklike" data-action="pick-up">Turned it on? Check again</button>' : '') + '</li>';
     }
 
     /* app-install — "Install it on your repo": the ADR 0055 publish credential (task
@@ -7036,6 +7070,12 @@ summary{min-height:24px;padding:3px 0;}
         return '<li class="slocked" data-onboard-step="app-install">' + title + '<p>Comes straight after the approval, on the same trip: pick your repo and you land back here.</p></li>';
       }
       var installUrl = live.installUrl || ('https://github.com/apps/' + encodeURIComponent(live.appSlug) + '/installations/new');
+      /* the runner stopped checking and GitHub never confirmed the install (task 1004652):
+         the link opens the SAME app's install page, and the click asks the runner to look again */
+      if (live.pickUp === 'check') {
+        return '<li class="sstopped" data-onboard-step="app-install">' + title + '<p>GitHub stopped before the app was installed on your repo. ' + NO_SECOND_APP + '</p>' +
+          '<a class="ghbtn" href="' + esc(installUrl) + '" target="_blank" rel="noopener" data-action="pick-up">' + GH_ICON + 'Pick up where it stopped ↗</a></li>';
+      }
       return '<li data-onboard-step="app-install">' + title + '<p>Your GitHub tab goes here next. We check with GitHub that the app is on your repo, and this step ticks itself. Came back without installing it?</p>' +
         '<a class="ghbtn" href="' + esc(installUrl) + '" target="_blank" rel="noopener">' + GH_ICON + 'Install it on your repo ↗</a></li>';
     }
@@ -7050,6 +7090,16 @@ summary{min-height:24px;padding:3px 0;}
       if (!domain) {
         return '<li class="slocked" data-onboard-step="first-sign-in">' + title + '<p>Unlocks with an address — then you open it, sign in with GitHub once, and take the owner’s seat (the founding Archon).</p></li>';
       }
+      /* the app and its keys are placed, but the project never confirmed sign-in (task
+         1004652): the runner re-asks it with the keys already there, so picking it up never
+         makes a second app — and a project that still will not answer goes to the platform team */
+      if (live.manifest === 'error' && live.manifestFailure === 'sign_in_unconfirmed') {
+        return '<li' + (live.verifying ? '' : ' class="sstopped"') + ' data-onboard-step="first-sign-in">' + title + '<p>' +
+          (live.verifying
+            ? 'Your project hasn’t confirmed sign-in yet. We’re asking it again, with the app GitHub already made, and this step ticks itself.'
+            : 'Your project didn’t confirm that sign-in works. ' + NO_SECOND_APP) + '</p>' +
+          (live.pickUp === 'check' ? pickUpBtn() : '') + askPlatformBtn() + '</li>';
+      }
       if (live.manifest !== 'done') {
         return '<li class="slocked" data-onboard-step="first-sign-in">' + title + '<p>Ticks once the platform has seen sign-in work on <code style="font-family:var(--font-mono)">' + esc(domain) + '</code>.</p></li>';
       }
@@ -7144,6 +7194,13 @@ summary{min-height:24px;padding:3px 0;}
     $('humanSteps').addEventListener('click', function (ev) {
       var mBtn = ev.target.closest('[data-action="manifest-start"]');
       if (mBtn) { startManifest(mBtn); return; }
+      /* task 1004652: the pick-up link to GitHub's install page keeps its default (it opens) */
+      var pBtn = ev.target.closest('[data-action="pick-up"]');
+      if (pBtn) { pickUpSetup(pBtn); return; }
+      var rBtn = ev.target.closest('[data-action="reopen-github"]');
+      if (rBtn) { reopenGithub(rBtn); return; }
+      var aBtn = ev.target.closest('[data-action="ask-platform"]');
+      if (aBtn) { askPlatform(aBtn); return; }
       var t = ev.target.closest('.copy');
       if (!t) return;
       navigator.clipboard.writeText(t.getAttribute('data-copy')).then(function () {
@@ -7199,7 +7256,6 @@ summary{min-height:24px;padding:3px 0;}
     var manifestState = null;      /* the one-time state token — kept so a parked poll can resume */
     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
@@ -7244,6 +7300,62 @@ summary{min-height:24px;padding:3px 0;}
       return true;
     }
 
+    /* ── Pick up where it stopped (task 1004652). The server says what the action does
+          (live.pickUp). 'convert' and 'check' are the pick-up route's: it resumes the
+          stopped step with the app GitHub already made, and this page watches again.
+          'reopen' and 'fresh' go through the mint route, which hands back a link still
+          waiting on GitHub and refuses a new one once GitHub has made the app; 'operator'
+          is a blocker filed for the platform team. ── */
+    function pickUpSetup(btn) {
+      if (!instanceId) return;
+      if (live.pickUp === 'reopen' || live.pickUp === 'fresh') { startManifest(btn); return; }
+      if (live.pickUp === 'operator') { askPlatform(btn); return; }
+      var isBtn = btn.tagName === 'BUTTON';
+      if (isBtn) { btn.disabled = true; btn.textContent = 'Picking it up…'; }
+      fetch(API + '/provisioning/instances/' + encodeURIComponent(instanceId) + '/github-app/pick-up', { method: 'POST', credentials: 'same-origin' })
+        .then(function (res) { return res.json().catch(function () { return {}; }); })
+        .then(function (d) {
+          if (d && d.ok) applyPickUp(d);
+          else if (isBtn) { btn.disabled = false; btn.textContent = 'That didn’t go through. Try again'; }
+          watchSetupAgain();
+        })
+        .catch(function () { if (isBtn) { btn.disabled = false; btn.textContent = 'That didn’t go through. Try again'; } });
+    }
+    /* the pick-up route's answer is the fresh read: seed it and redraw at once */
+    function applyPickUp(d) {
+      if (typeof d.status === 'string') { live.manifest = d.status; live.manifestFailure = d.failure || null; rememberManifest(undefined, d.status); }
+      seedSetup(d.checklist, d.install_url, d);
+      lastStepsHtml = '';
+      renderSteps();
+    }
+    /* …and keep watching: the attempt's own poll when this tab knows it, else the instance read */
+    function watchSetupAgain() {
+      if (manifestState) pollManifest(manifestState);
+      else if (!pollTimer && instanceId) startProgress(instanceId);
+    }
+    /* "Reopen GitHub": bring a tab still open to the front, and post the SAME attempt again */
+    function reopenGithub(btn) {
+      if (ghTab && !ghTab.closed) { try { ghTab.focus(); } catch (e) {} }
+      startManifest(btn);
+    }
+    /* the one stop no button on this page can fix (GitHub made the app but its keys never
+       reached the project): filed as a blocker for the platform team, once per attempt */
+    function askPlatform(btn) {
+      if (!instanceId) return;
+      btn.disabled = true; btn.textContent = 'Sending…';
+      fetch(API + '/blockers', {
+        method: 'POST', credentials: 'same-origin', headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({
+          title: 'A project’s GitHub setup needs the platform team',
+          body_md: 'Project ' + instanceId + ': the founder pressed “Send it to the platform team” on the GitHub step. GitHub made the app, but the project cannot finish connecting with it (its latest provisioning_oauth_manifests row says why in last_error), and a new link would make a second app. Once it is sorted, mark that attempt expired so the founder can start a fresh link.',
+          source: 'github-setup', source_ref: 'instance-' + instanceId + '-' + (manifestStartedAt || 'latest')
+        })
+      }).then(function (res) {
+        live.askedPlatform = res.ok ? true : 'failed';
+      }).catch(function () { live.askedPlatform = 'failed'; })
+        .then(function () { lastStepsHtml = ''; renderSteps(); });
+    }
+
     function startManifest(btn) {
       if (!instanceId) return;
       /* an organisation that cannot go ahead says why where it is chosen, before any
@@ -7252,6 +7364,7 @@ summary{min-height:24px;padding:3px 0;}
       if (!acct.ok) { appPick.explain(); return; }
       btn.disabled = true; btn.textContent = 'Preparing GitHub…';
       var tab = window.open('about:blank', 'ghAppSetup');
+      if (tab) { try { tab.focus(); } catch (e) {} watchGhTab(tab); }
       fetch(API + '/provisioning/instances/' + encodeURIComponent(instanceId) + '/github-app', {
         method: 'POST', credentials: 'same-origin',
         /* the founder's own account posts exactly what it always did */
@@ -7275,13 +7388,20 @@ summary{min-height:24px;padding:3px 0;}
         form.submit(); form.remove();
         live.manifest = 'pending'; live.manifestMsg = ''; live.manifestFailure = null;
         noteAppOrg(d.account === 'org' ? d.org_login : null);
-        manifestStartedAt = Date.now(); manifestStale = false;
+        manifestStartedAt = Date.now();
         rememberManifest(d.state, 'pending');
         renderSteps();
         pollManifest(d.state);
       }).catch(function (err) {
         if (String(err && err.message) === 'signing in') return;
         if (tab) { try { tab.close(); } catch (e) {} }
+        /* GitHub already approved an app for this project (task 1004652): no second one —
+           this page was behind, so it re-learns the truth and draws that step's own action */
+        if (err && (err.code === 'app_exists' || err.code === 'github_in_progress')) {
+          lastStepsHtml = '';
+          if (instanceId) startProgress(instanceId);
+          return;
+        }
         live.manifest = 'error'; live.manifestFailure = null; live.manifestMsg = String((err && err.message) || 'could not start');
         live.manifestCode = String((err && err.code) || '');
         renderSteps();
@@ -7296,22 +7416,57 @@ summary{min-height:24px;padding:3px 0;}
     }
     /* the checklist the server derived (task 1004649) — change-only; true when it moved.
        The install link rides only on a state-keyed read; the owner's read keeps the last. */
-    function seedSetup(checklist, installUrl) {
+    function seedSetup(checklist, installUrl, more) {
       if (!checklist || typeof checklist !== 'object') return false;
+      /* what picking it up does, and whether the runner is still checking (task 1004652) */
+      var moreMoved = false;
+      if (more && typeof more === 'object') {
+        var pick = typeof more.pick_up === 'string' ? more.pick_up : null, ver = !!more.verifying;
+        moreMoved = pick !== live.pickUp || ver !== live.verifying;
+        live.pickUp = pick; live.verifying = ver;
+      }
       var next = JSON.stringify(checklist), was = live.setup ? JSON.stringify(live.setup) : '';
       var url = typeof installUrl === 'string' && /^https:\/\/github\.com\/apps\//.test(installUrl) ? installUrl : null;
       var urlMoved = !!url && url !== live.installUrl && (!live.installUrl || /[?&]state=/.test(url) || !/[?&]state=/.test(live.installUrl));
-      if (next === was && !urlMoved) return false;
+      if (next === was && !urlMoved) return moreMoved;
       live.setup = checklist;
       if (urlMoved) live.installUrl = url;
       return true;
     }
     /* still worth watching after sign-in: the install not verified yet, while the runner checks */
     function setupOpen() {
-      return !!(live.setup && !live.setup.connected && live.manifest === 'done');
+      return !!(live.setup && ((!live.setup.connected && live.manifest === 'done') || (live.verifying && live.manifest === 'error')));
+    }
+    /* The GitHub tab this page opened (task 1004652). A tab that opened BEHIND this window
+       (this page kept the focus) or was closed before the approval is noticed within a few
+       seconds — it used to take 90 — and the step offers "Reopen GitHub". */
+    var ghTab = null, ghTabLeft = false, ghTabSince = 0, ghTabTimer = null, ghTabHeard = false;
+    /* PURE: 'closed' · 'behind' (still focused here a few seconds after opening it) · null */
+    function ghTabState(tab, left, since, now, focusedHere) {
+      if (!tab) return null;
+      if (tab.closed) return 'closed';
+      if (!left && focusedHere && now - since > 4000) return 'behind';
+      return null;
+    }
+    function watchGhTab(tab) {
+      if (!ghTabHeard) {   /* this page losing the focus = the GitHub tab came to the front */
+        ghTabHeard = true;
+        window.addEventListener('blur', function () { ghTabLeft = true; });
+        document.addEventListener('visibilitychange', function () { if (document.hidden) ghTabLeft = true; });
+      }
+      ghTab = tab; ghTabLeft = false; ghTabSince = Date.now(); ghTabTrouble = null;
+      if (ghTabTimer) clearInterval(ghTabTimer);
+      ghTabTimer = setInterval(noteManifestWait, 1500);
     }
     function noteManifestWait() {
-      if (live.manifest === 'pending' && !manifestStale && manifestStartedAt && (Date.now() - manifestStartedAt) > 90000) { manifestStale = true; renderSteps(); }
+      if (live.manifest !== 'pending') {
+        if (ghTabTimer) { clearInterval(ghTabTimer); ghTabTimer = null; }
+        ghTabTrouble = null;
+        return;
+      }
+      var focused = !document.hidden && (typeof document.hasFocus !== 'function' || document.hasFocus());
+      var next = ghTabState(ghTab, ghTabLeft, ghTabSince, Date.now(), focused);
+      if (next !== ghTabTrouble) { ghTabTrouble = next; renderSteps(); }
     }
     function pollManifest(stateToken) {
       stopManifestPoll();
@@ -7327,7 +7482,7 @@ summary{min-height:24px;padding:3px 0;}
             if (myGen !== manifestGen) return;
             if (d.app_slug && d.app_slug !== live.appSlug) { live.appSlug = d.app_slug; rememberManifest(undefined, undefined, d.app_slug); renderSteps(); }
             /* the server-verified ticks (task 1004649), and whose account the app is on */
-            var setupMoved = seedSetup(d.checklist, d.install_url);
+            var setupMoved = seedSetup(d.checklist, d.install_url, d);
             if (noteAppOrg(d.app_org)) setupMoved = true;
             if (setupMoved) renderSteps();
             var next = d.ready ? 'done' : (d.status || 'pending');
@@ -7576,7 +7731,7 @@ summary{min-height:24px;padding:3px 0;}
             }
             /* the server-verified checklist rides the same read (task 1004649) */
             if (data.github_setup && !manifestPollTimer) {
-              var seedMoved = seedSetup(data.github_setup.checklist, data.github_setup.install_url);
+              var seedMoved = seedSetup(data.github_setup.checklist, data.github_setup.install_url, data.github_setup);
               if (noteAppOrg(data.github_setup.app_org)) seedMoved = true;
               if (seedMoved) renderSteps();
             }
@@ -7618,8 +7773,8 @@ summary{min-height:24px;padding:3px 0;}
       stopManifestPoll();
       instanceId = null;
       watchPending = false; manifestPending = false; manifestState = null;
-      manifestStartedAt = 0; manifestStale = false;
-      live = { instStatus: null, addrReady: false, manifest: null, manifestMsg: '', manifestCode: '', manifestFailure: null, appSlug: null, appOrg: null, setup: null, installUrl: null };
+      manifestStartedAt = 0; ghTabTrouble = null;
+      live = { instStatus: null, addrReady: false, manifest: null, manifestMsg: '', manifestCode: '', manifestFailure: null, appSlug: null, appOrg: null, setup: null, installUrl: null, pickUp: null, verifying: false, askedPlatform: false };
       lastStepsHtml = '';
       lastProgHtml = '';
       hopReset();

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.96",
+  "version": "1.21.97",
   "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

@@ -9406,5 +9406,11 @@
       "id": "1004651",
       "text": "Founders can now put a new project under a GitHub organisation, not only their own account. When connecting GitHub, they choose \"On my account\" or \"On an organisation\". Their organisations are listed; one they only belong to ("
     }
+  ],
+  "1.21.97": [
+    {
+      "id": "1004652",
+      "text": "Connecting GitHub no longer makes a second app when something goes wrong. If a step stops, the checklist shows which one, says in one plain sentence that nothing is lost, and gives a \"Pick up where it stopped\" button that carr"
+    }
   ]
 }