@bongos/core 1.21.96 → 1.21.98

package/docs/design/project-startup-direction.md

@@ -77,6 +77,19 @@ This table replaces the blended flow's table below for every hub-side capability
 - **The server checks the name, never the page's copy.** The mint route takes `{ account: 'org', org }`, checks the name against GitHub's login rules (letters, digits and single inner dashes, up to 39), and builds `github.com/organizations/<org>/settings/apps/new`. `account: 'org'` with no usable organisation is refused (`org_required`) rather than quietly made personal. The organisation is recorded as a `github-app-org` event, and the checklist reads give it back as `app_org`, so the app's settings link points at the organisation from any tab or device. The repo route makes the repo with `POST /orgs/{org}/repos`, private and empty like the personal one. GitHub's refusals come back as a 409 with the reason (the organisation restricts which apps may act for it; the founder may not create repos there; no such organisation), never as a 403, which the page reads as "sign in again".
 - **The install follows the repo.** The install step already targets the repo's owner (the project's `target_ref`), so an organisation-owned repo installs there. Proof: `tests/github_org_account.mjs`.
 
+### Picking up where it stopped, as built (task 1004652)
+
+- **Never a second app.** The mint route reads the latest attempt first. A link still waiting on GitHub is handed back, with the same state (a second click, "Reopen GitHub", another device). Once GitHub has approved an app for the project, no new link is made (`app_exists`, or `github_in_progress` while the runner converts it). A new link is minted only when nothing was made on GitHub: the link lapsed, or the runner never took it up.
+- **Every state has its sentence and its button.** The server names what picking it up does (`pick_up`, from `pickUpFor` in `modules/provisioning/github-setup.js`), and the stopped step carries it:
+  - waiting on GitHub → "Reopen GitHub", the same link posted again. A tab that opened behind the window, or was closed before the approval, is noticed within a few seconds (it used to take 90).
+  - the link lapsed, or GitHub setup never started → "Connect GitHub ↗", a fresh link (nothing was made).
+  - approved, but the conversion stopped while GitHub's code is under an hour old → "Pick up where it stopped" re-queues the same attempt with the code it holds.
+  - approved, but the app's keys never reached the project (code spent or too old) → "Send it to the platform team" files a blocker from the page; GitHub offers no way to delete an app or re-issue its keys by API, so only a person can finish it.
+  - keys placed but sign-in unconfirmed → the runner asks the project again on every tick in its checking window, and the attempt becomes done with the same app. After the window: "Pick up where it stopped", plus "Send it to the platform team" for a project that still will not answer.
+  - the install never confirmed after the window → the mockup's "GitHub stopped before the app was installed on your repo. Nothing is lost, and no second app will be made." with "Pick up where it stopped ↗", which opens the same app's install page and asks the runner to look again.
+  - device flow still off after the window → "Turned it on? Check again".
+- **Check again re-opens the window.** `POST /provisioning/instances/:id/github-app/pick-up` (the owner only) re-queues a young conversion or records a `github-app-check-requested` event, which re-opens the runner's two-hour window exactly as an install report does. A runner placement that fails after GitHub's conversion now says the code is spent, and GitHub's 404 on a conversion drops the dead code, so a pick-up never re-queues a code that cannot convert. Proof: `tests/github_pick_up.mjs`.
+
 ### Who builds it
 
 | Task | Builds |

package/docs/module-api-changelog.md

@@ -3029,5 +3029,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.94 with no explicit bump. run 37907054923. (task 1002620)
   1.21.96 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.95 with no explicit bump. run 37914843597. (task 1002620)
+  1.21.97 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.96 with no explicit bump. run 37920956545. (task 1002620)
+  1.21.98 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.97 with no explicit bump. run 37925528587. (task 1002620)
 ---------------------------------------------------------------------------
 ```