@bongos/core 1.21.92 → 1.21.94

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

@@ -0,0 +1,113 @@
+// 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.
+'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 } = require('./callback-page');
+
+const log = api.logger('provisioning');
+
+// 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 });
+
+  // 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 = /^[0-9a-f]{16,128}$/i.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>' }));
+    }
+  });
+
+  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) {

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

@@ -601,6 +601,8 @@ 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);}
+/* 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;}
 .alive{margin-top:18px;padding-top:18px;border-top:1px solid var(--rule);}
 #view-new .aliveH{margin:0;font-family:var(--font-display);font-size:28px;font-weight:200;letter-spacing:-.02em;line-height:1.2;text-transform:none;color:var(--ink);}
@@ -6603,7 +6605,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 };
+    var live = { instStatus: null, addrReady: false, manifest: null, manifestMsg: '', manifestCode: '', manifestFailure: null, appSlug: null, setup: null, installUrl: null };
     var planPromises = {};             /* mode|domain → Promise<steps[]> */
     var lastStepsHtml = '';
     var lastProgHtml = '';            /* same change-only contract, for the progress strip */
@@ -6632,6 +6634,9 @@ summary{min-height:24px;padding:3px 0;}
        (task 1002562) — the owner no longer runs `bongos init --adopt` here. */
     function renderStepGithubRepo() {
       var landed = live.instStatus === 'active';
+      /* the one-page checklist (task 1004649) shows only the GitHub steps the founder
+         takes; a repo the platform made or adopted needs nothing, so it is not a row */
+      if (state.mode === 'adopt' || state.repoAutoCreated || landed) return '';
       var repoLabel = state.owner && state.repo ? '<strong>' + esc(state.owner + '/' + state.repo) + '</strong>' : 'your new repository';
       /* Naming a repo without linking it stranded the owner on exactly the path where the
          platform did the work (task 1002855). Adopt links the repo the owner picked;
@@ -6697,27 +6702,34 @@ summary{min-height:24px;padding:3px 0;}
       else window.location.assign(url);
     }
 
+    /* The four GitHub steps of part 03, in the mockup's words and order (task 1004649,
+       docs/design/mocks/day-night-rooms/): Approve the <name> app on GitHub · Install it
+       on your repo · Builders can sign in · Command-line sign-in is on. One click starts
+       ONE trip — approve, straight on to installing, back here — and every tick is what
+       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]; }
+    function appTitle() { return 'Approve the ' + esc(state.name || state.slug || 'project') + ' app on GitHub'; }
+
     /* 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). */
     function renderStepOauthApp() {
       var domain = resolvedDomain();
       if (!domain) {
-        return '<li class="slocked" data-onboard-step="oauth-app"><b>Wire GitHub sign-in</b><p>Unlocks once your project has an address — sign-in needs a real domain. Attach one any time from ' + projectPageLink('this project’s own page') + '.</p></li>';
+        return '<li class="slocked" data-onboard-step="oauth-app"><b>' + appTitle() + '</b><p>Unlocks once your project has an address — sign-in needs a real domain. Attach one any time from ' + projectPageLink('this project’s own page') + '.</p></li>';
+      }
+      /* 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)) {
+        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
          manifests whose hook URL isn't publicly reachable, so a locally-hosted
          platform can't complete the one-click flow — say it BEFORE the bounce. */
       if (!apexBase()) {
-        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') {
-        /* 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>';
+        return '<li class="slocked" data-onboard-step="oauth-app"><b>' + appTitle() + '</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 === 'error' || live.manifest === 'expired') {
         /* a plain sentence first; the raw route text folds under Technical
@@ -6731,86 +6743,98 @@ summary{min-height:24px;padding:3px 0;}
         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="https://github.com/settings/apps/' + esc(live.appSlug) + '" target="_blank" rel="noopener">your app on GitHub</a>' : 'the app on your GitHub account';
-          return '<li data-onboard-step="oauth-app"><b>Wire GitHub sign-in</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>' +
+          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.manifestFailure === 'finish_failed') snag = '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>Wire GitHub sign-in</b><p>' + snag + '</p>' +
+        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 + 'Set up GitHub sign-in</button>' + manualOauthDetails() + '</li>';
+          '<button type="button" class="ghbtn" data-action="manifest-start">' + GH_ICON + 'Connect GitHub ↗</button>' + manualOauthDetails() + '</li>';
       }
       if (live.manifest === 'code_received' || live.manifest === 'converting') {
-        /* GitHub's half is done — say so, rather than keep telling the founder
-           to approve an app they just approved */
+        /* GitHub's half of the approval is done — say so, rather than keep telling the
+           founder to approve an app they just approved */
         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>';
+        return '<li data-onboard-step="oauth-app"><b>' + appTitle() + '</b><p>Approved on GitHub. The platform is placing the app’s keys on your project, and the GitHub tab goes on to installing it on your repo. This step ticks itself.</p>' +
+          progressMarkup(1, 1, 'Placing the app’s keys on your project…', '', '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. No GitHub tab? It may have opened behind this window or in another one. Once approved, the platform places the credentials and verifies sign-in on its own; this step ticks itself.</p>' +
+        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>' +
           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>' +
-        '<button type="button" class="ghbtn" data-action="manifest-start">' + GH_ICON + 'Set up GitHub sign-in</button>' + manualOauthDetails() + '</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>';
     }
 
-    /* device-flow — the one-checkbox repair for terminal sign-in (task 1003051):
-       GitHub creates a manifest-born App with Device Flow OFF and offers no API to
-       enable it, so `bongos setup` in a terminal is refused until the owner ticks
-       the box. Web sign-in works either way; the CLI also has a web-token fallback. */
+    /* device-flow — "Command-line sign-in is on", the OPTIONAL fourth step (task 1004649).
+       GitHub creates a manifest-born App with Device Flow OFF and offers no manifest
+       field and no API to switch it on (the spike in task 1004649), so only the founder's
+       own tick in the app's settings can — and the runner ticks this step when GitHub
+       starts a device sign-in for the app. It never holds the project back: web sign-in
+       works without it, and the CLI falls back to a web token meanwhile. */
     function renderStepDeviceFlow() {
+      var title = '<b>Command-line sign-in is on</b>';
+      if (ghStep('device_flow') === 'done') {
+        return '<li class="sdone soptional" data-onboard-step="device-flow">' + title + '<p>Builders can sign in from a terminal too — the <code style="font-family:var(--font-mono)">bongos setup</code> command builders run on their own machine.</p></li>';
+      }
       if (live.manifest !== 'done') {
-        return '<li class="slocked" data-onboard-step="device-flow"><b>Let builders sign in from a command line — one checkbox</b><p>Unlocks once GitHub sign-in above is wired. It lets builders sign in from a terminal — the <code style="font-family:var(--font-mono)">bongos setup</code> command builders run on their own machine; web sign-in works without it.</p></li>';
+        return '<li class="slocked soptional" data-onboard-step="device-flow">' + title + '<p>Optional — turn it on later. It lets builders sign in from a terminal, with the <code style="font-family:var(--font-mono)">bongos setup</code> command they run on their own machine; web sign-in works without it.</p></li>';
       }
       var appUrl = live.appSlug ? 'https://github.com/settings/apps/' + esc(live.appSlug) : null;
-      return '<li data-onboard-step="device-flow"><b>Let builders sign in from a command line — one checkbox</b><p>' +
+      return '<li class="soptional" data-onboard-step="device-flow">' + title + '<p>Optional — turn it on later. GitHub leaves it off on new apps and lets only you switch it on: ' +
         (appUrl
-          ? 'Open <a href="' + appUrl + '" target="_blank" rel="noopener">your app’s settings</a>, check <strong>Enable Device Flow</strong>, and save. '
+          ? '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. ') +
-        'GitHub leaves it off on new apps and only offers it as this checkbox — until it’s ticked, 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></li>';
     }
 
-    /* app-install — the ADR 0055 publish credential (task 1003049): the sign-in App
-       doubles as it, but only an INSTALLED App can mint push tokens; without this
-       one click every finished task waits at confirmed for a manual merge. */
+    /* app-install — "Install it on your repo": the ADR 0055 publish credential (task
+       1003049). The same trip carries the founder here straight from the approval (task
+       1004649); this step ticks only once the runner has asked GitHub, with the app's own
+       key, and GitHub said the app is on this repo. The button is the way back for a
+       founder who returned without installing. */
     function renderStepAppInstall() {
-      if (live.manifest !== 'done') {
-        return '<li class="slocked" data-onboard-step="app-install"><b>Install the GitHub App on your repo</b><p>Unlocks once GitHub sign-in above is wired — the same app, installed on your repo, is what lets finished work merge and ship itself.</p></li>';
+      var title = '<b>Install it on your repo</b>';
+      if (ghStep('install') === 'done') {
+        return '<li class="sdone" data-onboard-step="app-install">' + title + '<p>The app is on ' + (state.owner && state.repo ? esc(state.owner + '/' + state.repo) : 'your repo') + ', so finished work can merge and ship itself.</p></li>';
       }
-      var installUrl = live.appSlug ? 'https://github.com/apps/' + esc(live.appSlug) + '/installations/new' : null;
-      return '<li data-onboard-step="app-install"><b>Install the GitHub App on your repo</b><p>One click: install the app you just approved on this project’s repo. Without it, finished work waits for a manual merge instead of shipping itself.</p>' +
-        (installUrl
-          ? '<a class="ghbtn" href="' + installUrl + '" target="_blank" rel="noopener">' + GH_ICON + 'Install the app on your repo</a>'
-          : '<p>GitHub → Settings → Developer settings → GitHub Apps → your app → <strong>Install App</strong> → pick this project’s repo.</p>') +
-        '</li>';
+      if (!live.appSlug) {
+        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');
+      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>';
     }
 
+    /* first-sign-in — "Builders can sign in": ticks when the platform has seen sign-in
+       work on the project (the runner's auth_configured check, the manifest 'done'). The
+       door opens only when the project ANSWERS too: a link to an address that does not
+       resolve yet is the worst first impression a founder can get (task 1003232). */
     function renderStepFirstSignIn() {
       var domain = resolvedDomain();
+      var title = '<b>Builders can sign in</b>';
       if (!domain) {
-        return '<li class="slocked" data-onboard-step="first-sign-in"><b>First sign-in</b><p>Unlocks with sign-in above — you’ll open your project’s address, sign in with GitHub once, and be seated as the owner (the founding Archon).</p></li>';
+        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 door opens only when the project ANSWERS and sign-in is wired: a
-         link to an address that does not resolve yet is the worst first
-         impression a founder can get of their own project (task 1003232) */
-      if (live.instStatus !== 'active' || !live.addrReady || live.manifest !== 'done') {
-        return '<li class="slocked" data-onboard-step="first-sign-in"><b>First sign-in</b><p>Unlocks once your project is answering and sign-in above is wired. Then you’ll open <code style="font-family:var(--font-mono)">' + esc(domain) + '</code>, sign in with GitHub once, and be seated as the owner — the founding Archon.</p></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>';
       }
-      return '<li data-onboard-step="first-sign-in"><b>First sign-in</b><p>Open <a href="https://' + esc(domain) + '" target="_blank" rel="noopener"><code style="font-family:var(--font-mono)">' + esc(domain) + '</code></a> and sign in with GitHub once. That seats you as the owner — the founding Archon.</p></li>';
+      var open = live.instStatus === 'active' && live.addrReady;
+      return '<li class="sdone" data-onboard-step="first-sign-in">' + title + '<p>Sign-in works on <code style="font-family:var(--font-mono)">' + esc(domain) + '</code>.' +
+        (open ? ' Open it and sign in with GitHub once to take the owner’s seat — the founding Archon.' : ' The door opens here once your project is answering.') + '</p>' +
+        (open ? '<a class="ghbtn" href="https://' + esc(domain) + '" target="_blank" rel="noopener">Open ' + esc(domain) + ' →</a>' : '') + '</li>';
     }
 
+    /* enter-hall — not a row of the GitHub checklist (the "is alive" block below carries
+       the way in); kept only for a project with no address, whose hall is local */
     function renderStepEnterHall() {
       var domain = resolvedDomain();
-      if (domain && (live.instStatus !== 'active' || !live.addrReady || live.manifest !== 'done')) {
-        return '<li class="slocked" data-onboard-step="enter-hall"><b>Enter your builders hall</b><p>Unlocks with the first sign-in — your project’s home will be <code style="font-family:var(--font-mono)">' + esc(domain) + '/builders</code>.</p></li>';
-      }
-      return domain
-        ? '<li data-onboard-step="enter-hall"><b>Enter your builders hall</b><p>Your project’s home — open <a href="https://' + esc(domain) + '/builders" target="_blank" rel="noopener"><code style="font-family:var(--font-mono)">' + esc(domain) + '/builders</code></a> and start building.</p></li>'
-        : '<li data-onboard-step="enter-hall"><b>Enter your builders hall</b><p>No address yet — run <code style="font-family:var(--font-mono)">bongos dev</code> in your repo checkout to start the local hall on your machine.</p></li>';
+      if (domain) return '';
+      return '<li data-onboard-step="enter-hall"><b>Enter your builders hall</b><p>No address yet — run <code style="font-family:var(--font-mono)">bongos dev</code> in your repo checkout to start the local hall on your machine (on an address it lives at /builders).</p></li>';
     }
 
     var STEP_RENDERERS = {
@@ -6828,9 +6852,13 @@ summary{min-height:24px;padding:3px 0;}
        control-plane wizard cannot reach. Spun out per the direction's §9
        delivery-split as task 1002739. */
 
+    /* the mockup's order: the repo (only when the founder must make it), approve,
+       install, sign-in, command line; a plan step this page has no row for goes last */
+    var STEP_ORDER = ['github-repo', 'oauth-app', 'app-install', 'first-sign-in', 'device-flow', 'enter-hall'];
+    function stepRank(s) { var i = STEP_ORDER.indexOf(s.key); return i < 0 ? STEP_ORDER.length : i; }
     function renderSteps() {
       fetchPlan().then(function (steps) {
-        var html = steps.filter(function (s) { return s && s.kind === 'human'; }).map(function (s) {
+        var html = steps.filter(function (s) { return s && s.kind === 'human'; }).slice().sort(function (a, b) { return stepRank(a) - stepRank(b); }).map(function (s) {
           var r = STEP_RENDERERS[s.key];
           return r ? r(s) : '<li data-onboard-step="' + esc(s.key) + '"><b>' + esc(s.label || s.key) + '</b></li>';
         }).join('');
@@ -6991,6 +7019,22 @@ summary{min-height:24px;padding:3px 0;}
     function manifestInFlight() {
       return live.manifest === 'pending' || live.manifest === 'code_received' || live.manifest === 'converting';
     }
+    /* 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) {
+      if (!checklist || typeof checklist !== 'object') return false;
+      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;
+      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');
+    }
     function noteManifestWait() {
       if (live.manifest === 'pending' && !manifestStale && manifestStartedAt && (Date.now() - manifestStartedAt) > 90000) { manifestStale = true; renderSteps(); }
     }
@@ -7006,6 +7050,7 @@ summary{min-height:24px;padding:3px 0;}
           .then(function (d) {
             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(); }
+            if (seedSetup(d.checklist, d.install_url)) renderSteps();   /* the server-verified ticks (task 1004649) */
             var next = d.ready ? 'done' : (d.status || 'pending');
             var failure = d.failure || null;
             if (next !== live.manifest || failure !== live.manifestFailure) { live.manifest = next; live.manifestFailure = failure; rememberManifest(undefined, next); renderSteps(); }
@@ -7249,6 +7294,8 @@ summary{min-height:24px;padding:3px 0;}
               if (seedChanged) { rememberManifest(undefined, live.manifest, live.appSlug || undefined); renderSteps(); }
               else noteManifestWait();
             }
+            /* the server-verified checklist rides the same read (task 1004649) */
+            if (data.github_setup && !manifestPollTimer && seedSetup(data.github_setup.checklist, data.github_setup.install_url)) renderSteps();
             /* the checklist reflects live state (task 1002694): a status transition —
                e.g. the scaffold landing — re-renders the steps (change-only, so the
                5s tick never clobbers an open dropdown or mid-flight button) */
@@ -7258,7 +7305,7 @@ summary{min-height:24px;padding:3px 0;}
             var terminal = renderProgress(inst);
             /* a GitHub leg still in flight keeps this read alive even once the
                project is up — after a reload it is the ONLY thing watching it */
-            if (!terminal || manifestInFlight()) pollTimer = setTimeout(tick, 5000);
+            if (!terminal || manifestInFlight() || setupOpen()) pollTimer = setTimeout(tick, 5000);
             else stopPolling();
           })
           .catch(function (err) {
@@ -7288,7 +7335,7 @@ summary{min-height:24px;padding:3px 0;}
       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 };
+      live = { instStatus: null, addrReady: false, manifest: null, manifestMsg: '', manifestCode: '', manifestFailure: null, appSlug: null, setup: null, installUrl: null };
       lastStepsHtml = '';
       lastProgHtml = '';
       hopReset();
@@ -7722,7 +7769,8 @@ summary{min-height:24px;padding:3px 0;}
       var list = $('humanSteps'), st = $('ghState');
       if (!list || !st) return;
       if (state.step !== 2) { st.textContent = 'opens once your project exists'; return; }
-      var items = Array.prototype.slice.call(list.children);
+      /* the optional step (command-line sign-in) never holds "connected" back */
+      var items = Array.prototype.slice.call(list.children).filter(function (li) { return !li.classList.contains('soptional'); });
       var done = items.filter(function (li) { return li.classList.contains('sdone'); }).length;
       st.textContent = items.length && done === items.length ? 'connected ✓'
         : manifestInFlight() ? 'waiting on GitHub…'

package/modules/render-deploy/routes/act.js

@@ -26,7 +26,7 @@ const log = api.logger('render-deploy');
 module.exports = function buildRenderDeployActRouter({ makeClient = defaultMakeClient, pool } = {}) {
   const router = express.Router();
 
-  router.post('/render-deploy/act', api.requireBuilder, api.requirePermission('core.pin.move'), async (req, res) => {
+  router.post('/render-deploy/act', api.requireBuilder, api.requirePermission('core.pin.move'), api.requireActAlone('release'), async (req, res) => {
     const db = pool || api.pool;
     // Shape only, and strict: an undeclared field is refused. `confirm` and `expectLiveDeployId`
     // are left to the checks below so each gets its own plain refusal rather than a schema one.

package/modules/security/routes/reports.js

@@ -217,6 +217,7 @@ module.exports = function buildSecurityReportsRouter() {
     '/security/reports/:id/confirm',
     api.requireBuilder,
     api.requirePermission('security.report.adjudicate'),
+    api.requireActAlone('disputes'),
     async (req, res) => {
       // drachmae_awarded is OPTIONAL and deliberately UNTYPED here: the handler
       // accepts a number, a stringified number, '' and null alike, and the inline
@@ -256,6 +257,7 @@ module.exports = function buildSecurityReportsRouter() {
     '/security/reports/:id/dispute',
     api.requireBuilder,
     api.requirePermission('security.report.adjudicate'),
+    api.requireActAlone('disputes'),
     async (req, res) => {
       const id = parseId(req, res, { code: 'bad_report_id', positiveInt: true });
       if (id === null) return;
@@ -281,6 +283,7 @@ module.exports = function buildSecurityReportsRouter() {
     '/security/reports/:id/fix',
     api.requireBuilder,
     api.requirePermission('security.report.adjudicate'),
+    api.requireActAlone('disputes'),
     async (req, res) => {
       const id = parseId(req, res, { code: 'bad_report_id', positiveInt: true });
       if (id === null) return;

package/package-lock.json

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

package/package.json

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

@@ -9382,5 +9382,17 @@
       "id": "1004648",
       "text": "Starting a project is now one page instead of six screens. After signing in, a founder sees \"Make something.\" with three parts: their project (name, kind, a sentence and four quick checks), a short summary of how it will be ru"
     }
+  ],
+  "1.21.93": [
+    {
+      "id": "1004657",
+      "text": "When a project votes that a part of its government is decided by a group, that vote now holds on every page, not only the People page. Before, someone with the right permission could still switch unattended building on, sign o"
+    }
+  ],
+  "1.21.94": [
+    {
+      "id": "1004649",
+      "text": "Connecting GitHub to a new project is now one trip. The founder clicks \"Connect GitHub\", approves the project's app on GitHub, and GitHub carries straight on to installing it on their repo (already picked when the repo is publ"
+    }
   ]
 }