@bongos/core 1.21.96 → 1.21.98

package/package-lock.json

@@ -1,12 +1,12 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.96",
+  "version": "1.21.98",
   "lockfileVersion": 3,
   "requires": true,
   "packages": {
     "": {
       "name": "@bongos/core",
-      "version": "1.21.96",
+      "version": "1.21.98",
       "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.98",
   "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,21 @@
       "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"
+    }
+  ],
+  "1.21.98": [
+    {
+      "id": "1004654",
+      "text": "The artist studio now has a day room. From 7 in the morning until 7 in the evening, by the clock on the artist's own computer, the studio shows a sunny sky with drifting clouds, a sun instead of the moon, lighter buildings wit"
+    },
+    {
+      "id": "1004592",
+      "text": "When someone restores a cut task or takes a task back off the board, it now stays put until a person promotes it. Before, the automatic promoter put it straight back on the claimable list within about five minutes."
+    }
   ]
 }

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

@@ -19,14 +19,19 @@
 // A verified fact is recorded once as a provisioning_events row; the checklist reads it.
 //
 // BOUNDED. Only attempts that settled within VERIFY_WINDOW_MS, or whose install was
-// reported within it, are checked, at most SWEEP_LIMIT per tick — so a finished or
-// abandoned project costs nothing, and a founder who ticks device flow later re-opens the
-// window by reinstalling or from the hall (task 1004652 owns "check again").
+// reported or a check requested within it, are checked, at most SWEEP_LIMIT per tick — so
+// a finished or abandoned project costs nothing, and "Pick up where it stopped" / "Check
+// again" on the project page re-opens the window (task 1004652).
+// SIGN-IN, TOO (task 1004652). An attempt that stopped because the project did not confirm
+// sign-in in time ('error' with the app's keys placed) is re-asked on each tick in the
+// window, with the keys already placed: when the project now answers auth_configured the
+// attempt becomes 'done' — the same app, never a second one.
 // Secrets: web.env is read on the box, parsed in memory, and only NAMES ever reach a log.
 
 const crypto = require('node:crypto');
 const { webEnvPath } = require('./provision-units.js');
 const { SETUP_EVENTS, VERIFY_WINDOW_MS, githubSetupFacts, targetRepo } = require('../../modules/provisioning/github-setup.js');
+const { parseHealthzAuth } = require('./oauth-secret.js');
 
 const SWEEP_LIMIT = 20;
 const UA = 'cloud-bongos-provisioner';
@@ -95,22 +100,29 @@ async function attemptsToVerify(db) {
   const { rows } = await db.query(
     `WITH latest AS (
        SELECT DISTINCT ON (instance_id) * FROM provisioning_oauth_manifests ORDER BY instance_id, created_at DESC)
-     SELECT l.id, l.instance_id, l.created_at, l.requested_by, i.slug, i.target_ref, i.hosting_shape, i.status AS instance_status
+     SELECT l.id, l.instance_id, l.created_at, l.requested_by, l.status, i.slug, i.port, i.target_ref, i.hosting_shape, i.status AS instance_status
        FROM latest l JOIN provisioning_instances i ON i.id = l.instance_id
       WHERE l.app_id IS NOT NULL AND l.status IN ('done', 'error') AND i.status = 'active'
         AND (l.updated_at > now() - ($1 * interval '1 second')
              OR EXISTS (SELECT 1 FROM provisioning_events e WHERE e.instance_id = l.instance_id
-                         AND e.event = $2 AND e.created_at > now() - ($1 * interval '1 second')))
+                         AND e.event = ANY($2) AND e.created_at > now() - ($1 * interval '1 second')))
       ORDER BY l.updated_at DESC LIMIT ${SWEEP_LIMIT}`,
-    [windowSec, SETUP_EVENTS.installReported]);
+    [windowSec, [SETUP_EVENTS.installReported, SETUP_EVENTS.checkRequested]]);
   return rows;
 }
 
+// Does the project answer that sign-in is configured? The project's JSON health read
+// (the same probe as provision.js authHealthzCmd — the root /healthz says a plain "ok").
+function signInAnswers(r, boxExec) {
+  const out = boxExec(`curl -sS --max-time 5 http://127.0.0.1:${r.port}/api/bongos/healthz`, { allowFail: true });
+  return parseHealthzAuth(out && out.stdout).authConfigured === true;
+}
+
 // One tick: for every attempt in the window, check whatever is not verified yet and record
 // what GitHub confirmed. Returns { checked, installed, deviceFlow }.
 async function verifyGithubAppSetups(deps) {
   const { db, provisioning, log, apply } = deps;
-  const out = { checked: 0, installed: 0, deviceFlow: 0 };
+  const out = { checked: 0, installed: 0, deviceFlow: 0, signIn: 0 };
   const rows = await attemptsToVerify(db);
   if (!apply) {
     for (const r of rows) log(`  would check the GitHub install + device flow for ${r.slug} (manifest #${r.id})`);
@@ -118,9 +130,17 @@ async function verifyGithubAppSetups(deps) {
   }
   for (const r of rows) {
     const facts = await githubSetupFacts(db, r.instance_id, r.created_at);
-    if (facts.installedAt && facts.deviceFlowAt) continue;
+    const signInStopped = r.status === 'error';
+    if (facts.installedAt && facts.deviceFlowAt && !signInStopped) continue;
     const onControlBox = r.hosting_shape === 'cloud-host' || r.hosting_shape === 'control-plane';
     const boxExec = onControlBox ? (deps.controlExec || deps.exec) : deps.exec;
+    if (signInStopped && signInAnswers(r, boxExec)) {
+      await provisioning.resolveOAuthManifest(db, r.id, 'done', { github_code: null });
+      await provisioning.recordEvent(db, { instanceId: r.instance_id, ownerBuilderId: r.requested_by, event: 'oauth-manifest-done',
+        detail: 'sign-in confirmed on a later check, with the app already made', actor: 'runner' }).catch(() => {});
+      out.signIn++; log(`  ✓ ${r.slug}: sign-in now confirmed`);
+    }
+    if (facts.installedAt && facts.deviceFlowAt) { out.checked++; continue; }
     const read = boxExec(`${deps.privileged ? 'sudo ' : ''}cat ${webEnvPath(r)}`, { allowFail: true });
     const creds = appCredsFromEnv(read && read.stdout);
     out.checked++;
@@ -141,7 +161,7 @@ async function verifyGithubAppSetups(deps) {
       }
     }
   }
-  if (out.checked) log(`github-setup — checked=${out.checked} installed=${out.installed} device-flow=${out.deviceFlow}`);
+  if (out.checked) log(`github-setup — checked=${out.checked} installed=${out.installed} device-flow=${out.deviceFlow} sign-in=${out.signIn}`);
   return out;
 }
 

package/scripts/gds/provision.js

@@ -1081,14 +1081,22 @@ async function placeManifestCreds(inst, mrow, deps) {
   // 3) rewrite web.env with the creds + restart the unit (never logs the secret — the
   //    writeFile logs only a byte count; the value is base64/temp-file placed).
   log(`  [oauth-manifest] place creds in ${webEnvPath(inst)} + restart ${inst.slug}`);
-  boxWriteFile(webEnvPath(inst), webEnvBody(inst, {
-    clientId: creds.clientId, clientSecret: creds.clientSecret, ownerLogin: await ownerLoginOf(inst, deps.db),
-    // The App id + private key double as the ADR 0055 publish credential (task
-    // 1003049); older Apps (pre-permission manifests) return a pem too — placing
-    // it is harmless and heals once the owner grants the permissions + installs.
-    appId: creds.appId, appPem: creds.appPem,
-  }), { mode: 0o600, sudo: true });
-  pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
+  try {
+    boxWriteFile(webEnvPath(inst), webEnvBody(inst, {
+      clientId: creds.clientId, clientSecret: creds.clientSecret, ownerLogin: await ownerLoginOf(inst, deps.db),
+      // The App id + private key double as the ADR 0055 publish credential (task
+      // 1003049); older Apps (pre-permission manifests) return a pem too — placing
+      // it is harmless and heals once the owner grants the permissions + installs.
+      appId: creds.appId, appPem: creds.appPem,
+    }), { mode: 0o600, sudo: true });
+    pmFor(deps).restartService(inst, { exec: boxExec, sudoP });
+  } catch (e) {
+    // The code is spent and the keys are not placed: a retry would re-convert a burned
+    // code, so say so (codeSpent) and name the app GitHub made for the platform team
+    // (task 1004652 — the wizard offers to send it to them; the slug stays OFF the row,
+    // because a recorded slug reads as "keys placed").
+    return { ok: false, codeSpent: apply, error: `GitHub made the app ${creds.appSlug || creds.appId || '?'}, but placing its keys failed: ${e.message}` };
+  }
   // The app now exists AND its credentials are placed — the checklist's first tick, and the
   // slug the callback page needs to send the founder on to installing it (task 1004649).
   if (apply && deps.onCredsPlaced) await Promise.resolve().then(() => deps.onCredsPlaced({ appId: creds.appId, appSlug: creds.appSlug })).catch(() => {});
@@ -1182,7 +1190,10 @@ async function drainOAuthManifests(deps) {
         converted++;
       }
     } catch (e) {
-      await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: e.message }).catch(() => {});
+      // GitHub's 404 means the code is used or past its hour: drop it, so "pick up where it
+      // stopped" (task 1004652) never re-queues a dead code. Any other failure keeps it.
+      const dead = /conversion failed: (Not Found|HTTP 404)/.test(String(e.message));
+      await provisioning.resolveOAuthManifest(db, mrow.id, 'error', { last_error: e.message, ...(dead ? { github_code: null } : {}) }).catch(() => {});
       errors++; log(`  ✖ oauth-manifest #${mrow.id}: ${e.message}`);
     }
   }

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

@@ -168,7 +168,7 @@ await test("restore: clears only an 'Abandoned: …' value_summary, leaving any
   assert.match(sql, /status = 'backlog'/);
   assert.match(sql, /value_summary LIKE 'Abandoned: %' THEN NULL ELSE value_summary END/,
     'the retire stamp is cleared conditionally — an unrelated summary survives');
-  assert.equal(upd.params.length, 1, 'only the task id is bound');
+  assert.deepEqual(upd.params, [TASK, null], 'the task id, then the parking builder (none passed here)');
 });
 
 await test('restore: clears merged_into_task_id + triage_note (task 1001478 grade finding)', async () => {

package/tests/github_one_trip.mjs

@@ -153,7 +153,7 @@ test('the runner records what GitHub confirmed — and only that — reading the
     exec: (cmd) => { cmds.push(cmd); return { ok: true, stdout: ENV }; },
     provisioning: { recordEvent: async (_db, e) => { events.push(e); } },
   });
-  assert.deepEqual(out, { checked: 1, installed: 1, deviceFlow: 0 });
+  assert.deepEqual(out, { checked: 1, installed: 1, deviceFlow: 0, signIn: 0 });
   assert.deepEqual(cmds, ['sudo cat /etc/mercury/web.env'], 'the creds are read where the runner placed them');
   assert.deepEqual(events.map((e) => e.event), ['github-app-installed'], 'device flow off records nothing');
   assert.match(events[0].detail, /acme\/mercury/);
@@ -168,7 +168,7 @@ test('an attempt already fully verified is skipped; dry-run asks GitHub nothing'
     db: fakeDb({ attempts: [ATTEMPT], facts: [{ event: 'github-app-installed', at: '2026-10-08T10:00:00Z' }, { event: 'github-app-device-flow', at: '2026-10-08T10:00:00Z' }] }),
     exec: () => { throw new Error('must not read the box'); }, provisioning: { recordEvent: async () => { throw new Error('nothing to record'); } },
   };
-  assert.deepEqual(await RUN.verifyGithubAppSetups(deps), { checked: 0, installed: 0, deviceFlow: 0 });
+  assert.deepEqual(await RUN.verifyGithubAppSetups(deps), { checked: 0, installed: 0, deviceFlow: 0, signIn: 0 });
   const lines = [];
   await RUN.verifyGithubAppSetups({ ...deps, apply: false, log: (m) => lines.push(m), db: fakeDb({ attempts: [ATTEMPT] }) });
   assert.equal(asked, 0);
@@ -181,7 +181,7 @@ test('the window query takes each project\'s LATEST attempt, past placement, sti
   assert.match(sql, /DISTINCT ON \(instance_id\)[\s\S]*ORDER BY instance_id, created_at DESC/);
   assert.match(sql, /l\.app_id IS NOT NULL AND l\.status IN \('done', 'error'\) AND i\.status = 'active'/);
   assert.match(sql, /LIMIT 20/);
-  assert.deepEqual(params, [GS.VERIFY_WINDOW_MS / 1000, 'github-app-install-reported']);
+  assert.deepEqual(params, [GS.VERIFY_WINDOW_MS / 1000, ['github-app-install-reported', 'github-app-check-requested']], 'an install report or a check request (task 1004652) re-opens it');
   assert.match(fs.readFileSync(path.join(ROOT, 'scripts', 'gds', 'provision.js'), 'utf8'), /require\('\.\/provision-github-setup\.js'\)\.verifyGithubAppSetups\(deps\)/, 'it runs on every runner tick, after the conversions');
 });
 
@@ -202,7 +202,7 @@ function page({ manifest, appSlug = null }) {
   const sandbox = {
     live: { manifest, manifestMsg: '', manifestCode: '', manifestFailure: null, appSlug, setup: null, installUrl: null, instStatus: 'active', addrReady: true },
     state: { name: 'Mer<cury', slug: 'mercury', owner: 'acme', repo: 'mercury', step: 2 },
-    manifestStale: false, autoOpenArmed: false,
+    autoOpenArmed: false,
     resolvedDomain: () => 'mercury.example.com', apexBase: () => 'example.com',
     esc: (x) => String(x).replace(/[&<>"']/g, (c) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[c])),
     GH_ICON: '', manualOauthDetails: () => '', projectPageLink: (t) => t, autoOpenTick: () => '',

package/tests/github_org_account.mjs

@@ -68,6 +68,7 @@ let targetRef = 'founder/mercury';
 const events = [];
 provisioning.getInstanceById = async () => ({ id: 42, owner_builder_id: 7, slug: 'mercury', domain: 'mercury.example.com', target_ref: targetRef, status: 'requested' });
 provisioning.createOAuthManifest = async (_db, row) => ({ id: 99, ...row });
+provisioning.getLatestOAuthManifestForInstance = async () => null;   // no earlier attempt (task 1004652's mint guard)
 provisioning.recordEvent = async (_db, e) => { events.push(e); };
 const branding = require(path.join(ROOT, 'src/branding.js'));
 const realBranding = branding.branding;
@@ -164,9 +165,9 @@ function page({ state = {}, live = {} } = {}) {
     live: { manifest: null, manifestMsg: '', manifestFailure: null, appSlug: null, appOrg: null, setup: null, installUrl: null, ...live },
     repoAccess: true, instanceId: 42, me: { github_login: 'founder' },
     hopForRepoAccess: () => false, syncHome() {}, saveDraft() {},
-    rememberManifest() {}, renderSteps() {}, pollManifest() {},
+    rememberManifest() {}, renderSteps() {}, pollManifest() {}, watchGhTab() {},
   };
-  sandbox.manifestStartedAt = 0; sandbox.manifestStale = false;
+  sandbox.manifestStartedAt = 0;
   vm.createContext(sandbox);
   vm.runInContext([PICKER, ENSURE_REPO, NOTE_ORG, START, SETTINGS, "var appPick = acctPicker('aa', { needsOwner: true });"].join('\n'), sandbox);
   return { sb: sandbox, els, posted, forms, settle: () => new Promise((r) => setTimeout(r, 60)) };

package/tests/github_pick_up.mjs

@@ -0,0 +1,366 @@
+// tests/github_pick_up.mjs — "GitHub retry picks up where it stopped, never makes a second
+// app, and every failure has a button that fixes it" (task 1004652).
+//
+// WHY. Retrying the GitHub step used to mint a new link, which makes a SECOND app on the
+// founder's account; "Start again" appeared only after 90 seconds; and two failures ended
+// at "contact us" or "delete the orphan app by hand". Now every state part 03 can reach
+// has one sentence and an action that resumes from that step with the app already made.
+//
+// Four layers, DB-free and network-free:
+//   1. modules/provisioning/github-setup.js — pickUpFor (what the action does, for EVERY
+//      status × app × verified-facts shape), mintGuard (reuse or refuse, never a second
+//      attempt once GitHub approved one), and the checking window a check request re-opens.
+//   2. the runner — a stopped sign-in is re-asked with the keys already placed and becomes
+//      'done'; a placement that throws after GitHub's conversion is a SPENT code (never
+//      re-queued); GitHub's 404 on a conversion drops the dead code.
+//   3. the REAL status route's answer run into the REAL page (seedSetup + the step renderers):
+//      every reachable state draws a sentence and an action, none a chore or "contact us".
+//   4. the page's own actions: pick-up posts to the pick-up route and watches again, Reopen
+//      GitHub goes through the mint route (which hands back the SAME state), and "Send it to
+//      the platform team" files a blocker without a secret.
+//
+// Run:  node --test tests/github_pick_up.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 { createRequire } from 'node:module';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const GS = require(path.join(ROOT, 'modules', 'provisioning', 'github-setup.js'));
+const RUN = require(path.join(ROOT, 'scripts', 'gds', 'provision-github-setup.js'));
+const P = require(path.join(ROOT, 'scripts', 'gds', 'provision.js'));
+const HUB = fs.readFileSync(path.join(ROOT, 'modules', 'public-landing', 'public', 'projects.html'), 'utf8').replace(/\r\n/g, '\n');
+const SCRIPT = HUB.slice(HUB.lastIndexOf('<script>'), HUB.lastIndexOf('</script>'));
+
+const NOW = Date.parse('2026-10-09T12:00:00Z');
+const ago = (min) => new Date(NOW - min * 60000).toISOString();
+const SOON = new Date(NOW + 10 * 60000).toISOString();
+
+// ── 1. what picking it up does ──────────────────────────────────────────────
+
+test('pickUpFor: every attempt shape has its action, and none of them is "make another app"', () => {
+  const c = (status, slug, facts) => GS.githubChecklist(status, slug, facts);
+  const at = (row, status, facts = {}, verifying = false) => GS.pickUpFor(row, status, c(status, row && row.app_slug, facts), verifying, NOW);
+  assert.equal(at(null, null), null, 'no attempt: Connect GitHub is the first click, not a pick-up');
+  assert.equal(at({ attempts: 0 }, 'pending'), 'reopen', 'waiting on GitHub: post the SAME link again');
+  assert.equal(at({ attempts: 0 }, 'expired'), 'fresh', 'lapsed before approval: nothing was made, a new link is safe');
+  assert.equal(at({ attempts: 0 }, 'error'), 'fresh', 'the runner never took it up: nothing was made');
+  assert.equal(at({ attempts: 1 }, 'code_received'), null, 'in flight: nothing to pick up');
+  assert.equal(at({ attempts: 1 }, 'converting'), null);
+  // GitHub approved; the conversion stopped
+  assert.equal(at({ attempts: 2, github_code: 'C', created_at: ago(20) }, 'error'), 'convert', 'the code is still young: convert it again');
+  assert.equal(at({ attempts: 2, github_code: 'C', created_at: ago(61) }, 'error'), 'operator', 'past GitHub\'s hour the code is dead');
+  assert.equal(at({ attempts: 2, github_code: null, created_at: ago(5) }, 'error'), 'operator', 'a spent code: the app exists, its keys never reached us');
+  // the app exists with its keys placed
+  const app = { attempts: 1, app_id: 5, app_slug: 'mercury-app' };
+  assert.equal(at(app, 'error'), 'check', 'sign-in unconfirmed, the runner stopped asking: ask again');
+  assert.equal(at(app, 'error', {}, true), null, 'still asking: nothing to press');
+  assert.equal(at(app, 'done'), 'check', 'install never confirmed and the window closed: check again');
+  assert.equal(at(app, 'done', { installedAt: ago(1) }), 'check', 'device flow still off after the window: check again');
+  assert.equal(at(app, 'done', { installedAt: ago(1), deviceFlowAt: ago(1) }), null, 'all four ticked: nothing left');
+});
+
+test('mintGuard: a waiting link is handed back, and once GitHub approved an app no new link is made', () => {
+  assert.equal(GS.mintGuard(null, NOW), null);
+  assert.deepEqual(GS.mintGuard({ status: 'pending', state: 'S', expires_at: SOON }, NOW), { reuse: 'S', expiresAt: SOON });
+  assert.equal(GS.mintGuard({ status: 'pending', state: 'S', expires_at: ago(1) }, NOW), null, 'lapsed: mint fresh');
+  assert.equal(GS.mintGuard({ status: 'error', attempts: 0 }, NOW), null, 'nothing made: mint fresh');
+  for (const row of [{ status: 'error', attempts: 1, app_id: 5 }, { status: 'done', attempts: 1, app_id: 5 }, { status: 'error', attempts: 3, app_id: null }]) {
+    assert.equal(GS.mintGuard(row, NOW).refuse, 'app_exists', JSON.stringify(row));
+  }
+  assert.equal(GS.mintGuard({ status: 'converting', attempts: 1 }, NOW).refuse, 'github_in_progress');
+});
+
+test('a check request re-opens the runner\'s checking window, like an install report', () => {
+  const settled = { resolved_at: ago(5 * 60) };
+  assert.equal(GS.stillVerifying(settled, {}, NOW), false);
+  assert.equal(GS.stillVerifying(settled, { checkRequestedAt: ago(1) }, NOW), true);
+  assert.equal(GS.SETUP_EVENTS.checkRequested, 'github-app-check-requested');
+});
+
+// ── 2. the runner ───────────────────────────────────────────────────────────
+
+const STOPPED = { id: 21, instance_id: 42, created_at: ago(300), requested_by: 7, status: 'error', slug: 'mercury', port: 4100, target_ref: 'acme/mercury', hosting_shape: 'co-tenant', instance_status: 'active' };
+function runnerDeps({ healthz, facts = [] }) {
+  const resolved = [], events = [], cmds = [];
+  return {
+    resolved, events, cmds,
+    deps: {
+      apply: true, log: () => {}, fetchImpl: async () => ({ status: 500, ok: false, json: async () => ({}) }),
+      db: { query: async (sql) => (/WITH latest AS/.test(sql) ? { rows: [STOPPED] } : /FROM provisioning_events/.test(sql) ? { rows: facts } : { rows: [] }) },
+      exec: (cmd) => { cmds.push(cmd); return { ok: true, stdout: /healthz/.test(cmd) ? healthz : '' }; },
+      provisioning: {
+        resolveOAuthManifest: async (_db, id, status, patch) => { resolved.push({ id, status, patch }); },
+        recordEvent: async (_db, e) => { events.push(e); },
+      },
+    },
+  };
+}
+
+test('a stopped sign-in is asked again with the keys already placed, and becomes done — the same attempt', async () => {
+  const w = runnerDeps({ healthz: '{"ok":true,"auth_configured":true}' });
+  const out = await RUN.verifyGithubAppSetups(w.deps);
+  assert.equal(out.signIn, 1);
+  assert.ok(w.cmds.includes('curl -sS --max-time 5 http://127.0.0.1:4100/api/bongos/healthz'), 'the JSON health read, as the placement uses (authHealthzCmd)');
+  assert.equal(w.cmds[0], P.authHealthzCmd({ port: 4100 }), 'byte-for-byte the placement probe');
+  assert.deepEqual(w.resolved, [{ id: 21, status: 'done', patch: { github_code: null } }], 'attempt 21 itself — nothing new is made');
+  assert.ok(w.events.some((e) => e.event === 'oauth-manifest-done'));
+  // still not answering: nothing changes, the next tick asks again
+  const no = runnerDeps({ healthz: '{"ok":true,"auth_configured":false}' });
+  assert.equal((await RUN.verifyGithubAppSetups(no.deps)).signIn, 0);
+  assert.deepEqual(no.resolved, []);
+  // an attempt that is 'done' is never re-asked
+  const done = runnerDeps({ healthz: '{"auth_configured":true}', facts: [{ event: 'github-app-installed', at: ago(1) }, { event: 'github-app-device-flow', at: ago(1) }] });
+  STOPPED.status = 'done';
+  try { await RUN.verifyGithubAppSetups(done.deps); } finally { STOPPED.status = 'error'; }
+  assert.deepEqual(done.cmds, [], 'a finished attempt costs nothing');
+});
+
+const INST = { id: 1, slug: 'mercury', hosting_shape: 'co-tenant', status: 'active', owner_builder_id: 7, port: 3003, db_name: 'mercury', domain: 'mercury.example.com' };
+const CREDS = { clientId: 'Iv1.abcdef0123456789', clientSecret: 'z'.repeat(40), appId: 9, appSlug: 'm-app' };
+
+test('keys that fail to land after GitHub\'s conversion are a SPENT code: never re-queued, the app named for the platform team', async () => {
+  const r = await P.placeManifestCreds(INST, { github_code: 'C', attempts: 1 }, {
+    apply: true, log: () => {}, convertManifestCode: async () => CREDS,
+    exec: () => ({ ok: true, stdout: '' }), writeFile: () => { throw new Error('ssh: connection reset'); },
+  });
+  assert.equal(r.ok, false);
+  assert.equal(r.codeSpent, true, 'the code is burned: a retry would 404 forever');
+  assert.match(r.error, /GitHub made the app m-app, but placing its keys failed: ssh: connection reset/);
+  assert.equal(r.appSlug, undefined, 'no slug on the row: a recorded slug reads as "keys placed"');
+  // …and the drain records it so: error, code dropped — pickUpFor then says 'operator', not 'convert'
+  let claims = 0; const resolved = [];
+  await P.drainOAuthManifests({
+    apply: true, log: () => {}, db: {}, exec: () => ({ ok: true, stdout: '' }), writeFile: () => { throw new Error('disk full'); },
+    convertManifestCode: async () => CREDS,
+    provisioning: {
+      claimNextOAuthManifest: async () => (claims++ === 0 ? { id: 31, instance_id: 1, github_code: 'C', attempts: 1 } : null),
+      getInstanceById: async () => INST, resolveOAuthManifest: async (_db, id, status, patch) => { resolved.push({ id, status, patch }); }, recordEvent: async () => {},
+    },
+  });
+  assert.equal(resolved.length, 1);
+  assert.equal(resolved[0].status, 'error');
+  assert.equal(resolved[0].patch.github_code, null);
+  assert.equal(GS.pickUpFor({ attempts: 1, github_code: null, created_at: ago(1) }, 'error', GS.githubChecklist('error', null), false, NOW), 'operator');
+});
+
+test('GitHub\'s 404 on a conversion drops the dead code; any other failure keeps it for a pick-up', async () => {
+  const drain = async (message) => {
+    let claims = 0; const resolved = [];
+    await P.drainOAuthManifests({
+      apply: true, log: () => {}, db: {}, exec: () => ({ ok: true }), writeFile: () => ({ ok: true }),
+      convertManifestCode: async () => { throw new Error(message); },
+      provisioning: {
+        claimNextOAuthManifest: async () => (claims++ === 0 ? { id: 32, instance_id: 1, github_code: 'C', attempts: 1 } : null),
+        getInstanceById: async () => INST, resolveOAuthManifest: async (_db, id, status, patch) => { resolved.push({ status, patch }); }, recordEvent: async () => {},
+      },
+    });
+    return resolved[0];
+  };
+  const dead = await drain('GitHub manifest conversion failed: Not Found');
+  assert.equal(dead.status, 'error');
+  assert.equal(dead.patch.github_code, null);
+  const flaky = await drain('GitHub manifest conversion failed: HTTP 502');
+  assert.equal(flaky.status, 'error');
+  assert.ok(!('github_code' in flaky.patch), 'the code may still convert: "Pick up where it stopped" re-queues it');
+});
+
+// ── 3. the REAL status route into the REAL page ─────────────────────────────
+
+const provisioning = require(path.join(ROOT, 'modules', 'provisioning', 'provisioning.js'));
+let attempt = null;
+provisioning.getOAuthManifestByState = async (_db, state) => (state === 'S1' ? attempt : null);
+provisioning.getInstanceById = async () => ({ id: 42, owner_builder_id: 7, slug: 'mercury', domain: 'mercury.example.com', target_ref: 'acme/mercury', status: 'active' });
+let eventRows = [];
+const realQuery = { query: async () => ({ rows: eventRows }) };
+const api = require(path.join(ROOT, 'src', 'module-api.js'));
+api.pool.query = realQuery.query;   // the one read the status route makes: the verified facts
+const express = require('express');
+const app = express();
+app.use('/api/bongos', require(path.join(ROOT, 'modules', 'provisioning', 'routes', 'github-setup.js'))());
+
+const RS = SCRIPT.indexOf('    /* The four GitHub steps of part 03');
+const RE = SCRIPT.indexOf('    var STEP_RENDERERS = {', RS);
+const SS = SCRIPT.indexOf('    /* the checklist the server derived (task 1004649)');
+const SE = SCRIPT.indexOf('    function setupOpen() {', SS);
+const AS = SCRIPT.indexOf('    /* ── Pick up where it stopped (task 1004652).');
+const AE = SCRIPT.indexOf('    function startManifest(btn) {', AS);
+
+test('the page regions are findable (a rename must fail loudly)', () => {
+  assert.ok(RS > 0 && RE > RS && SS > 0 && SE > SS && AS > 0 && AE > AS);
+});
+
+const esc = (x) => String(x).replace(/[&<>"']/g, (ch) => ({ '&': '&amp;', '<': '&lt;', '>': '&gt;', '"': '&quot;', "'": '&#39;' }[ch]));
+function page(extra = {}) {
+  const sandbox = {
+    live: { manifest: null, manifestMsg: '', manifestCode: '', manifestFailure: null, appSlug: null, appOrg: null, setup: null, installUrl: null, instStatus: 'active', addrReady: true, pickUp: null, verifying: false, askedPlatform: false },
+    state: { name: 'Mercury', slug: 'mercury', owner: 'acme', repo: 'mercury' }, autoOpenArmed: false,
+    resolvedDomain: () => 'mercury.example.com', apexBase: () => 'example.com', esc,
+    GH_ICON: '', manualOauthDetails: () => '<details>manual</details>', projectPageLink: (t) => t, autoOpenTick: () => '',
+    progressMarkup: (a, b, note) => `<prog>${note}</prog>`, encodeURIComponent, JSON,
+    ...extra,
+  };
+  vm.createContext(sandbox);
+  vm.runInContext(`${SCRIPT.slice(RS, RE)}\n${SCRIPT.slice(SS, SE)}\n${SCRIPT.slice(AS, AE)}`, sandbox);
+  return sandbox;
+}
+// what the page's poll does with one answer (pollManifest's tick, minus the timer)
+function seedFrom(sb, d) {
+  sb.live.appSlug = d.app_slug || null;
+  vm.runInContext(`seedSetup(${JSON.stringify(d.checklist)}, ${JSON.stringify(d.install_url)}, ${JSON.stringify(d)})`, sb);
+  sb.live.manifest = d.ready ? 'done' : d.status;
+  sb.live.manifestFailure = d.failure || null;
+}
+const ROWS = ['renderStepOauthApp', 'renderStepAppInstall', 'renderStepFirstSignIn', 'renderStepDeviceFlow'];
+const CHORE = /\/contact|Contact us|delete it|Developer settings → GitHub Apps\) so|Try again anyway|Start the setup again|by hand/;
+
+// every shape the status derivation can reach, as rows the real route reads
+const SHAPES = [
+  ['waiting on GitHub', { status: 'pending', attempts: 0, expires_at: SOON }, []],
+  ['link lapsed', { status: 'pending', attempts: 0, expires_at: ago(1) }, []],
+  ['runner never took it up', { status: 'error', attempts: 0, expires_at: ago(1) }, []],
+  ['approved, converting', { status: 'converting', attempts: 1, expires_at: ago(1) }, []],
+  ['conversion stopped, code young', { status: 'error', attempts: 3, github_code: 'C', created_at: ago(15), expires_at: ago(1), resolved_at: ago(10) }, []],
+  ['conversion stopped, code spent', { status: 'error', attempts: 1, github_code: null, created_at: ago(15), expires_at: ago(1), resolved_at: ago(10) }, []],
+  ['sign-in unconfirmed, re-asking', { status: 'error', attempts: 1, app_id: 5, app_slug: 'mercury-app', created_at: ago(15), resolved_at: ago(10) }, []],
+  ['sign-in unconfirmed, window over', { status: 'error', attempts: 1, app_id: 5, app_slug: 'mercury-app', created_at: ago(300), resolved_at: ago(290) }, []],
+  ['signed in, install unverified, checking', { status: 'done', attempts: 1, app_id: 5, app_slug: 'mercury-app', created_at: ago(15), resolved_at: ago(10) }, []],
+  ['signed in, install never confirmed, window over', { status: 'done', attempts: 1, app_id: 5, app_slug: 'mercury-app', created_at: ago(300), resolved_at: ago(290) }, []],
+  ['installed, device flow off, window over', { status: 'done', attempts: 1, app_id: 5, app_slug: 'mercury-app', created_at: ago(300), resolved_at: ago(290) }, [{ event: 'github-app-installed', at: ago(280) }]],
+  ['all four ticked', { status: 'done', attempts: 1, app_id: 5, app_slug: 'mercury-app', created_at: ago(300), resolved_at: ago(290) }, [{ event: 'github-app-installed', at: ago(280) }, { event: 'github-app-device-flow', at: ago(280) }]],
+];
+
+async function statusSays(row, events) {
+  attempt = { id: 99, instance_id: 42, requested_by: 7, state: 'S1', ...row };
+  eventRows = events;
+  const server = app.listen(0);
+  await new Promise((r) => server.once('listening', r));
+  try {
+    const res = await fetch(`http://127.0.0.1:${server.address().port}/api/bongos/provisioning/github-app/status?state=S1`);
+    return await res.json();
+  } finally { server.close(); }
+}
+
+test('every state the setup can reach: the REAL status answer draws a sentence and an action — never a chore, never "contact us"', async (t) => {
+  // the page reads NOW from the real clock; age the rows against it
+  const shift = Date.now() - NOW;
+  const aged = (row) => Object.fromEntries(Object.entries(row).map(([k, v]) => [k, /_at$/.test(k) && v ? new Date(Date.parse(v) + shift).toISOString() : v]));
+  const seen = {};
+  for (const [name, row, events] of SHAPES) {
+    const d = await statusSays(aged(row), events.map((e) => ({ ...e, at: new Date(Date.parse(e.at) + shift).toISOString() })));
+    assert.equal(d.ok, true, name);
+    const sb = page();
+    seedFrom(sb, d);
+    const html = ROWS.map((f) => vm.runInContext(`${f}()`, sb)).join('\n');
+    seen[name] = { pick: d.pick_up, html };
+    assert.doesNotMatch(html, CHORE, `${name}: no manual chore and no "contact us"`);
+    // a stopped step always carries the action that fixes it
+    for (const li of html.split('\n').filter((x) => /class="sstopped/.test(x))) {
+      assert.match(li, /data-action="(pick-up|manifest-start|ask-platform)"/, `${name}: a stopped step has its button — ${li.slice(0, 120)}`);
+    }
+    // a pick-up the server offers is on the page
+    if (d.pick_up === 'check' || d.pick_up === 'convert') assert.match(html, /data-action="pick-up"/, `${name}: ${d.pick_up} is offered`);
+    if (d.pick_up === 'operator') assert.match(html, /data-action="ask-platform"/, `${name}: the platform team is one click away`);
+    if (d.pick_up === 'reopen') assert.match(html, /data-action="reopen-github"/, `${name}: the same link can be reopened`);
+    // a new link is offered ONLY where nothing was made on GitHub
+    if (/data-action="manifest-start"/.test(html)) assert.ok(d.pick_up === 'fresh', `${name}: Connect GitHub is offered only when no app exists (pick_up=${d.pick_up})`);
+  }
+  assert.equal(seen['waiting on GitHub'].pick, 'reopen');
+  assert.equal(seen['link lapsed'].pick, 'fresh');
+  assert.equal(seen['conversion stopped, code young'].pick, 'convert');
+  assert.equal(seen['conversion stopped, code spent'].pick, 'operator');
+  assert.equal(seen['sign-in unconfirmed, re-asking'].pick, null);
+  assert.match(seen['sign-in unconfirmed, re-asking'].html, /We’re asking it again/);
+  assert.equal(seen['sign-in unconfirmed, window over'].pick, 'check');
+  assert.match(seen['signed in, install never confirmed, window over'].html, /GitHub stopped before the app was installed on your repo\. Nothing is lost, and no second app will be made\./, 'the mockup\'s sentence, from the real read');
+  assert.match(seen['installed, device flow off, window over'].html, /Turned it on\? Check again/);
+  assert.equal(seen['all four ticked'].pick, null);
+  assert.doesNotMatch(seen['all four ticked'].html, /sstopped|data-action="pick-up"/);
+  t.diagnostic(Object.entries(seen).map(([k, v]) => `${k}: ${v.pick}`).join(' · '));
+});
+
+// ── 4. the page's own actions ───────────────────────────────────────────────
+
+function actions({ pickUp, answer, manifestState = null, blockerStatus = 201 }) {
+  const calls = { fetched: [], polled: [], progress: [], started: 0, renders: 0 };
+  const sb = page({
+    API: '/api/bongos', instanceId: 42, manifestState, pollTimer: null, lastStepsHtml: 'x', manifestStartedAt: 1700000000000, ghTab: null,
+    fetch: async (url, init) => {
+      calls.fetched.push({ url, init });
+      if (/\/blockers$/.test(url)) return { ok: blockerStatus < 300, status: blockerStatus, json: async () => ({}) };
+      return { ok: true, status: 200, json: async () => answer };
+    },
+    rememberManifest: () => {}, renderSteps: () => { calls.renders++; },
+    pollManifest: (s) => calls.polled.push(s), startProgress: (id) => calls.progress.push(id),
+    startManifest: () => { calls.started++; },
+  });
+  sb.live.pickUp = pickUp;
+  return { sb, calls };
+}
+const settle = () => new Promise((r) => setTimeout(r, 20));
+const btn = () => ({ tagName: 'BUTTON', disabled: false, textContent: '' });
+
+test('pick-up posts to the pick-up route, seeds its fresh read, and watches again', async () => {
+  const answer = { ok: true, action: 'convert', status: 'code_received', failure: null, checklist: GS.githubChecklist('code_received', null), install_url: null, verifying: false, pick_up: null };
+  const { sb, calls } = actions({ pickUp: 'convert', answer, manifestState: 'S1' });
+  vm.runInContext('pickUpSetup', sb)(btn());
+  await settle();
+  assert.equal(calls.fetched.length, 1);
+  assert.equal(calls.fetched[0].url, '/api/bongos/provisioning/instances/42/github-app/pick-up');
+  assert.equal(calls.fetched[0].init.method, 'POST');
+  assert.equal(calls.started, 0, 'no new link is minted');
+  assert.equal(sb.live.manifest, 'code_received', 'the step moves on at once');
+  assert.equal(sb.live.pickUp, null);
+  assert.deepEqual(calls.polled, ['S1'], 'the attempt\'s own poll runs again');
+  // without the state (a reload, another device) the instance read watches instead
+  const other = actions({ pickUp: 'check', answer: { ...answer, action: 'check', status: 'error', verifying: true } });
+  vm.runInContext('pickUpSetup', other.sb)(btn());
+  await settle();
+  assert.deepEqual(other.calls.progress, [42]);
+  assert.equal(other.sb.live.verifying, true);
+});
+
+test('Reopen GitHub and a lapsed link go through the mint route (which hands back the SAME waiting state); a refused pick-up says so', async () => {
+  for (const pickUp of ['reopen', 'fresh']) {
+    const { sb, calls } = actions({ pickUp, answer: {} });
+    vm.runInContext('pickUpSetup', sb)(btn());
+    await settle();
+    assert.equal(calls.started, 1, pickUp);
+    assert.equal(calls.fetched.length, 0, `${pickUp}: the pick-up route is not asked`);
+  }
+  const r = actions({ pickUp: null, answer: {} });
+  vm.runInContext('reopenGithub', r.sb)(btn());
+  assert.equal(r.calls.started, 1);
+  // a refusal (409) re-enables the button with a plain line
+  const refused = actions({ pickUp: 'check', answer: { ok: false } });
+  const b = btn();
+  vm.runInContext('pickUpSetup', refused.sb)(b);
+  await settle();
+  assert.equal(b.disabled, false);
+  assert.match(b.textContent, /That didn’t go through\. Try again/);
+});
+
+test('"Send it to the platform team" files one blocker for the attempt, with no secret, and the step says it was sent', async () => {
+  const { sb, calls } = actions({ pickUp: 'operator', answer: {} });
+  vm.runInContext('pickUpSetup', sb)(btn());
+  await settle();
+  const filed = calls.fetched.find((c) => /\/blockers$/.test(c.url));
+  assert.ok(filed, 'POST /api/bongos/blockers');
+  assert.equal(filed.url, '/api/bongos/blockers');
+  const body = JSON.parse(filed.init.body);
+  assert.equal(body.source, 'github-setup');
+  assert.equal(body.source_ref, 'instance-42-1700000000000', 'one per attempt: a second press is the same blocker');
+  assert.match(body.body_md, /Project 42/);
+  assert.doesNotMatch(filed.init.body, /state|github_code|secret=|Iv1\./i, 'no token, code or secret');
+  assert.equal(sb.live.askedPlatform, true);
+  assert.ok(calls.renders > 0);
+  const failed = actions({ pickUp: 'operator', answer: {}, blockerStatus: 500 });
+  vm.runInContext('askPlatform', failed.sb)(btn());
+  await settle();
+  assert.equal(failed.sb.live.askedPlatform, 'failed');
+});