@bongos/core 1.19.333 → 1.19.334

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.333",
-  "core_contract": "1.19.333",
-  "source_commit": "e1394f609a907900304d1a5f9eeab60dd4dab4a9",
+  "core_version": "1.19.334",
+  "core_contract": "1.19.334",
+  "source_commit": "17d7b23f872fb3f64737ae5ffe270b91ace779a0",
   "source_ref": "HEAD",
-  "built_at": "2026-08-25T00:27:16.274Z",
+  "built_at": "2026-08-25T00:36:48.394Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 324,
+    "docs_redacted": 325,
     "agent_docs_stubbed": 22,
-    "functional_verbatim": 1489,
+    "functional_verbatim": 1490,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1835,
-  "tree_sha256": "7e4b747b97aa29e848619615d0ed0540ea7143880dfa1b905996562b14cec74d",
+  "file_count": 1837,
+  "tree_sha256": "15089adb0fd9a51245746cbd141dd57dceadee53a5e640beb0d7059c7f219610",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1414,10 +1414,15 @@
       "mode": "0000644",
       "sha256": "749040f16b59cc1cd1c49ca40453fed838f31b36af8c8eed2b5de7db00ddb0d0"
     },
+    {
+      "path": "docs/adr/0187-oauth-handshake-cookie-lifetime.md",
+      "mode": "0000644",
+      "sha256": "d59906a447f2459efdef6c3eb97cf8629813ec74776ead700017f02ef76aed9e"
+    },
     {
       "path": "docs/adr/README.md",
       "mode": "0000644",
-      "sha256": "c5af7723dbcc0e4a62a897153b1fa1cf34962a1f8ed72fc7bf9681ba074dab6a"
+      "sha256": "87606f8e07f470f0ff55d7ac733de9d1004d3d15eddf1003a8958566b4147077"
     },
     {
       "path": "docs/api-reference.md",
@@ -4717,12 +4722,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "fec2ee8e4c08dc1587612aab5cec7ddce1e8ec8cb38e247448b31d67a4a5d875"
+      "sha256": "27cc593724db16a7e292e6f8287d3fadfbda3a6eaff49c1c97a08fe5bf175ce5"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "9dcaa3e5d7e79ec753a86f559b9d268b8e5f6f1dab69d89985b0f2dcd306f093"
+      "sha256": "5d2f06a29143a871ca7dd2f20d46ba2b05389a57aafddc6891147baa2a00e124"
     },
     {
       "path": "public-docs/index.html",
@@ -6462,7 +6467,7 @@
     {
       "path": "src/bongos/routes/auth.js",
       "mode": "0000644",
-      "sha256": "bb62110c21a07745a8bcfd3e2cf94f29deec1de5baea9d62fa903febcca54f2b"
+      "sha256": "e2195c0f80c1a7ae3a07e2234d2b97e6a20366b740fe3d0329dd8d8d6f9c1969"
     },
     {
       "path": "src/bongos/routes/backup.js",
@@ -6572,7 +6577,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "00fb85bd32cccb4cc6bf755d6a0fd802c361a5ed12c4e9dfb8707f38b6fb358e"
+      "sha256": "717fc58e2725b43ec1bc0a0e995172992ed0b42cba603c68482292b70da67c57"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -6794,6 +6799,11 @@
       "mode": "0000644",
       "sha256": "92b7033ab16d9d4472fcca4695d9df47938a45bdc62feda87b8771f5a2d59ff2"
     },
+    {
+      "path": "tests/auth_web_recovery.mjs",
+      "mode": "0000644",
+      "sha256": "84b20e0bd1d014ebec22d0ed9b50c45d9b79e26fe509af1444a2fa46a52f03ec"
+    },
     {
       "path": "tests/authorship_audit.mjs",
       "mode": "0000644",

package/docs/adr/0187-oauth-handshake-cookie-lifetime.md

@@ -0,0 +1,84 @@
+# 0187 — The OAuth web-handshake cookies live 30 minutes, and move together
+
+- **Status:** Accepted
+- **Date:** 2026-08-24
+- **Tasks:** [#1003234](https://cloudbongos.com/builders#/task/1003234) (goal 1000058 — the non-cloudbongos project lifecycle; a walk finding from the 2026-08-24 stranger's-walk review, task 1003232)
+- **Builds on:** [ADR 0143](<redacted>.md) (the `gds_oauth_repos` opt-in cookie), #726/#734 (the `gds_return` return cookie and the apex-scoped state)
+- **Related:** [ADR 0141](<redacted>.md) (the federated leg shares the same state cookie)
+
+## 1. Context
+
+`GET /api/gds/auth/web/start` sets three cookies before bouncing the visitor to
+GitHub: the CSRF **state** (`gds_oauth_state`), the validated **return target**
+(`gds_return`) and the **repo-scope opt-in** (`gds_oauth_repos`). All three were
+`maxAge: 10 minutes` — written for a hall builder who already has a GitHub
+account and is back in seconds.
+
+A founder's first sign-in is not that. The project wizard's gate sends them to
+GitHub with `?repos=1`; a stranger with no GitHub account signs up there first,
+verifies an email, sometimes sets up 2FA, and comes back. Past ten minutes the
+callback found no state cookie and answered **"State mismatch"** — and because
+the return and repos cookies had expired with it, the page's "try signing in
+again" door was a bare `/auth/web/start`: the founder re-entered without the
+repository scope and landed on the default post-login landing, nowhere near
+the wizard. The review filed it as a founder-shaped dead end.
+
+The state cookie is CSRF protection for the OAuth callback. Lengthening it is a
+security-posture change, not a copy tweak, and the task said so; hence this
+record.
+
+## 2. Decision
+
+1. **One lifetime, `HANDSHAKE_COOKIE_MS = 30 * 60 * 1000`, for all three
+   cookies.** They MUST move together: a state that outlives its return cookie
+   lands a founder on the default landing with no repo scope; a return that
+   outlives its state lands them on "State mismatch". The constant lives beside
+   the cookie names in `src/bongos/routes/auth.js`; the State-mismatch copy
+   reads it rather than hardcoding a number.
+2. **Every OAuth error page rebuilds its retry door from whatever cookies are
+   still valid** (`recoveryStartHref(req)`: `return` through the same
+   open-redirect allowlist as the callback, `repos=1` from the opt-in cookie),
+   and so does the access-pending page's auto-walk-in. The lifetime change
+   makes the dead end rare; the door change makes it recoverable when it
+   still happens.
+3. The Discord account-link state cookie is a different flow (an already
+   signed-in builder linking an account) and keeps its 10 minutes.
+
+## 3. What did NOT change — the posture, stated plainly
+
+- The state is still **single-use**: the callback clears it (apex-scoped and
+  host-only forms) on every path, and GitHub's authorization code is itself
+  single-use, so a captured state cannot be replayed into a session.
+- Still `httpOnly`, `sameSite=lax`, `secure` behind TLS, apex-scoped — a
+  cross-site page cannot read or send it.
+- The redirect_uri is still pinned to the canonical origin (#734), and
+  `safeReturnTo` still bounds every return target.
+
+What grew is only the **window in which a legitimate handshake may complete**:
+an attacker who could fixate a victim's state cookie (already requiring a
+foothold this cookie's flags deny) has thirty minutes instead of ten to
+complete a login-CSRF against a browser that has not itself finished the
+handshake. Thirty was chosen as the smallest round number that comfortably
+covers a GitHub signup with email verification; sixty was not needed.
+
+## 4. Rejected
+
+- **Keep the state at 10 minutes and lengthen only `return` + `repos`.** That
+  makes the "State mismatch" page recoverable (its door would still carry the
+  return + scope) but keeps the dead-end page itself as the founder's
+  experience — and it breaks the one-lifetime invariant in the other
+  direction, so a builder who *did* come back inside ten minutes could see a
+  return cookie from an older, abandoned start. The three move together.
+- **A server-side state store with a long TTL.** Correct in the abstract, a new
+  table and a sweep for a problem a cookie lifetime solves; not for this task.
+- **Sixty minutes.** Wider than the failure needs.
+
+## 5. Consequences
+
+- `tests/auth_web_recovery.mjs` pins the constant, the three `maxAge` sites in
+  `/auth/web/start`, the copy that reads it, and the recovery helper by value
+  (including the allowlist dropping foreign, protocol-relative and
+  `javascript:` returns).
+- If GitHub's signup flow ever grows past thirty minutes for a typical
+  founder, the constant is the one place to move — and the invariant is that
+  all three cookies move with it.

package/docs/adr/README.md

@@ -260,5 +260,6 @@ This keeps the decision history honest and traceable.
 | 0184 | [**A ship must account for itself: `shipTask` requires a land proof or a declared no-artifact** ([task 1002483](https://cloudbongos.com/builders#/task/1002483), goal 1000024). `db.shipTask` is the confirmed→shipped flip and, since [ADR 0120](<redacted>.md), where the CREDIT is booked — yet its only precondition was `WHERE status = 'confirmed'`, nothing about whether code reached main. The two AUTOMATED paths each proved the land first; the MANUAL route passed nothing, so a task confirmed with no pushed code could be shipped by its claim holder **or by any Metic+ sweeping `/merge-mode`**, booking its `task.shipped` credit. It stayed untracked for two months because its tracking task was closed in June asserting task 1001547 had delivered the gate — it had not, blocker 1000047's own final update says so, and the code agreed with the blocker rather than the closure note: **a hole hidden by a record nobody checked**, which is the same failure the gate is about. Decision: the gate lives at the WRITE, not the route (a route gate leaves the invariant unenforced at the layer that moves the ledger, so the next caller reopens it silently), and `shipTask` is FAIL-CLOSED on a required `landAssurance`. TWO kinds, and the second is why this does not make things worse: `proof` (this task's commit is on main) and **`no_artifact`** — a deliberate DB-only ship, an explicitly supported shape (CLAUDE.md "Direct DB writes are work too") that [task 1002478](https://cloudbongos.com/builders#/task/1002478) documents as a dead end below Archon. A naive proof-only gate would have made 1002478 strictly worse; naming no-artifact as a KIND turns it from an absence the gate must be talked out of into a recorded answer. Both carry a reason, audited post-commit and best-effort (an audit miss must never roll back a landed ship). `ship.js` now declares its own `--db-only`/`--allow-empty` lands, without which this fix would have regressed the very flow CLAUDE.md calls supported. Rejected: (b) gate only the route — leaves the write unguarded; (c) record the residual as tolerable — defensible on blast radius and genuinely close, but it would have been the FOURTH record asserting this was handled with nothing checkable behind it. Does NOT gate confirm: a codeless confirm is still accepted, it simply cannot reach `shipped` or pay.](<redacted>.md) | lifecycle / integrity |
 | 0185 | [**The spark-handoff credit split: 70% developer, 30% spark author** ([task 1002923](https://cloudbongos.com/builders#/task/1002923), BV1.R147, goal 1000062 — completing the chain [task 1002920](https://cloudbongos.com/builders#/task/1002920) mark → [task 1002921](https://cloudbongos.com/builders#/task/1002921) queue → [task 1002922](https://cloudbongos.com/builders#/task/1002922) pickup). [ADR 0172](<redacted>.md) built the ideator streams and paid `captured_by`, the only person an idea then had. The spark handoff created a second: R146 develops a spark IN PLACE, preserving the author while recording a `developed_by`. **R146 therefore shipped paying NOTHING on purpose** — not an oversight but a refusal to guess, because `awardIdeaFullPassCredit`'s idempotency predicate is `(builder_id, reason)`, so paying the DEVELOPER would not have blocked a later payment to the AUTHOR and one idea would have paid twice; the cost of that caution was that a developed Full Idea received stream 2 **never** unless its author resubmitted. Owner decision (2026-08-22): **70/30 favouring the developer**, on BOTH existing streams, one ratio so there is one rule to explain. The reasoning is behavioural, not sentimental — developing someone else's spark is the scarce act the queue depends on, and at an even split it pays HALF what authoring your own Full Idea pays for the same writing work, so the rational move is always to write your own and the R145 queue stays a list nobody reads. The author keeps 30% plus their share of stream 1 on every task shipped under the idea, forever. `IDEA_DEVELOPER_SHARE = 0.70` is a **policy constant in `credits.js`** beside the pass bar and quick factor (ADR 0172's own consequence, the ADR 0023 precedent): a share of someone's earnings deserves a review and a commit, not a runtime edit. **The structural half is what retires R146's caution:** the economy module now derives the payees itself (`ideaCreditParties` reads `captured_by` + `developed_by`), so the caller can no longer choose a recipient — the develop route hands over an idea and a score, never a payee, and books the split like any other path (fail-open; the development has already committed). Three arithmetic properties, each a real bug if missed: the total is **conserved** (developer rounded, author gets the REMAINDER — rounding both pays 6 out of a 5-credit payout); a **self-developed** idea collapses to ONE payee, because two rows for one builder would silently UNDER-pay under the per-builder idempotency predicate, not double-pay (the comparison normalises via `String()` since `bigint` arrives as a string, so a type mismatch cannot become a phantom payee); and **zero-value rows are dropped**. Ids otherwise pass through unconverted — `Number()`-ing a `bigint` risks precision. `builder_id` in the idempotency predicate, which entered as an index optimisation (the R143/IC2 grader finding), is now **load-bearing for correctness**: two payees share one `reason`, so a reason-only predicate would refuse the second, and a partially-booked split completes on the next call. **Not decided here:** stream 3's split (ships with the Board Room, task 1002999), and whether `origin='develop'` in `ideas_task_lineage` belongs to whoever promotes a DEVELOPED idea into a task — ADR 0172 §5 says the row is "set at promotion and at develop (R146)", but R146 creates no task, so that origin stays deliberately unwired rather than invented; it changes who stream 1 pays.](<redacted>.md) | economy / ideator lane |
 | 0186 | [**Per-project idea templates: the seam is already built; the economics are the open problem** ([task 1002932](https://cloudbongos.com/builders#/task/1002932), BV1.R156, goal 1000062 — a SPIKE, output is this ADR plus a task list, no implementation). The literal question — how does a founder define their own idea shape without a schema change or forking the scorer — is **already answered by shipped work**: R141 gave every template function an optional `registry` defaulting to the built-in one, so validation and scoring both read the declaration as data; `ideas_grades.template_key` is per-row with a format CHECK whose own comment says a project key "stays addressable"; and `provisioning_instances.settings jsonb` is an existing per-project home. **No schema change, no fork.** Decision A: a **`project-settings` kernel port**, sibling of `builder-settings`, read via `resolveOptional` so a vanilla instance with no provisioning module degrades to the built-in registry; `base-v1` stays the default and the fallback for an unresolvable key. Rejected a new `ideas_templates` table (second home for data that has one) and a config file (per-instance, but one instance hosts many projects). **Decision B is the finding that matters.** Completeness is normalised 0–100 WITHIN its template (mean of per-field ratios), while karma reads it against an absolute bar (`IDEA_FULL_PASS_BAR = 60`, `IDEA_FULL_PASS_CREDIT = 5`) — so template choice becomes a credit-minting lever: `base-v1` needs ~200 characters for 5 credits, a 1-field template with `substanceMin` 10 needs ~10, a ~20× arbitrage handed to exactly the projects this ADR empowers. Shipping A without B would make the feature a way to print credits. The fix separates the two questions one number is answering: **completeness stays relative** (it is the right signal for triage ordering and the hall meter) and **karma stops reading it**, switching to an absolute substance total the scorer already computes per field and currently discards after averaging. An interim guard (≥3 required fields, ≥120 total `substanceMin`) bounds the arbitrage without fixing it. Decision C: an optional per-field `weight` (default 1) turning the unweighted mean into a weighted one — today's behaviour is the all-weights-1 case, so it is a data addition and one arithmetic line. Decision D: the five base fields are **not** mandatory (forcing them would make "define your own" cosmetic), replaced by two constraints — a template must declare ≥1 required field, and a stored template is validated at WRITE time so a malformed one is refused there rather than discovered inside the capture path, which must never throw. **Boundary note:** goal 1000062's wall is `[ideas, hall-ui]`, so the port task (provisioning + kernel) and the karma task (economy) cannot be claimed under it.](<redacted>.md) | ideas / templates |
+| 0187 | [**The OAuth web-handshake cookies live 30 minutes, and move together** ([task 1003234](https://cloudbongos.com/builders#/task/1003234), goal 1000058). The three cookies `/auth/web/start` sets — the CSRF state, the validated return target, the repo-scope opt-in — were 10 minutes each, a hall builder's timescale; a founder's first sign-in can include a GitHub SIGNUP with email verification and came back past ten minutes to "State mismatch" with the return + repo scope gone, and the page's retry door was a bare start. Decision: one `HANDSHAKE_COOKIE_MS = 30 min` for all three (they MUST move together — a state outliving its return cookie lands on the default landing with no scope, a return outliving its state lands on State mismatch), and every OAuth error page plus the access-pending auto-walk-in rebuilds its door from whatever cookies are still valid (`recoveryStartHref`, through the same open-redirect allowlist). What did NOT change: the state is still single-use, still `httpOnly`/`sameSite=lax`/apex-scoped, the code still the bearer — only the window for a legitimate handshake grew. Rejected: lengthening only return + repos (keeps the dead end and breaks the one-lifetime invariant the other way), a server-side state store, sixty minutes. The Discord-link state cookie is a different flow and keeps 10.](<redacted>.md) | auth / security posture |
 
 > ⚠️ **Numbering collision (known):** two ADRs share `0008`. The numbers were assigned in parallel sessions before the lock could be enforced. The files are kept under their existing filenames to preserve git history, but the table disambiguates them as `0008-a` / `0008-b`. New ADRs should resume at `0040` to avoid further collisions. (`0024` is also a real on-disk duplicate: the cloneable-repo/local-first-memory ADR and the multi-agent-system-architecture ADR were both numbered `0024` in parallel; both keep their filenames, disambiguated as `0024-a` / `0024-b` like `0008`. Likewise `0025` ended up with two on-disk files — the offsite-backup ADR and the structured-criterion↔task-link ADR — both kept under their existing filenames and disambiguated as `0025-a` / `0025-b`; separately, the BFG ADR had also claimed `0025` on 2026-05-30 and yielded to `0026`. A third happened 2026-06-06: `0036` was claimed in parallel by the builders-subdomain ADR ([#726](https://example.com/builders#/task/726)) and this Discord-channels ADR ([#727](https://example.com/builders#/task/727)); the Discord-channels ADR yielded to `0037`. A fourth landed 2026-06-10: `0044` was claimed in parallel by the palette-replacement ADR and the per-box game-preview ADR ([#897](https://example.com/builders#/task/897)); both keep their filenames, disambiguated as `0044-a` / `0044-b` like `0008`. A fifth was caught pre-land 2026-06-13: `0050` was claimed in parallel by the device-flow-admission ADR ([#1000](https://example.com/builders#/task/1000)) and the sandbox-for-everyone ADR ([#1001](https://example.com/builders#/task/1001)); the latter yielded to `0052` before merging, so there is no `0050` duplicate. A sixth was caught pre-land 2026-06-21: the tool-agnostic-design-layer ADR ([#1375](https://example.com/builders#/task/1375)) first collided at `0079` with the value-gated-autonomous-engagement ADR, then at `0080` with the llm-cache-api-transport ADR (both part of the 0075–0080 LLM-cost-reduction series, landed on `main` in parallel); it yielded to `0081` before merging, so there is no `0079`/`0080` design-layer duplicate. A seventh landed 2026-06-23: `0084` was claimed in parallel by the auto-derived-per-task-rank-floor ADR and the remove-default-spend-cap ADR (task 1499); the rank-floor ADR landed on `main` first, so the spend-cap ADR yielded to `0085`, leaving no `0084` duplicate. An eighth landed 2026-06-27: `0095` was claimed in parallel by the borrowed-memory-and-retrieval-concepts ADR (PR #459, landed first) and the cross-agent-context-management ADR ([#1651](https://example.com/builders#/task/1651), PR #460); both keep their filenames, disambiguated as `0095-a` / `0095-b` like `0008`. These two are companions — `0095-a` adopts the memory/retrieval concepts and explicitly defers the grep-vs-semantic question to `0095-b`.)

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.333",
+  "version": "1.19.334",
   "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/src/bongos/routes/auth.js

@@ -21,6 +21,9 @@ function escapeHtml(s) {
 //   subtitle — replaces the default header sub-line
 //   cta      — { href, label } for the primary button (default: retry sign-in)
 //   note     — replaces the default troubleshooting footnote
+//   startHref — the retry sign-in URL (default: a bare /auth/web/start); the
+//              callback passes recoveryStartHref(req) so the founder's return
+//              target + repo-scope opt-in survive the error (task 1003234)
 // The instance's own word for the admitting rank, for per-branch error strings
 // (task 1002616, the 1439 follow-up): core error surfaces never hardcode
 // "Archon" — a non-OTB instance names its own role (branding rankLabels.archon;
@@ -51,7 +54,7 @@ function renderAuthErrorPage(heading, detail, opts = {}) {
     catch { return AUTH_ERROR_FALLBACK; }
   })();
   const subtitle = opts.subtitle || copy.subtitle;
-  const cta = opts.cta || { href: '/api/gds/auth/web/start', label: copy.ctaLabel };
+  const cta = opts.cta || { href: opts.startHref || '/api/gds/auth/web/start', label: copy.ctaLabel };
   const note = opts.note || "If this keeps happening, the GitHub OAuth app's authorized callback URL may be misconfigured. See docs/recipes/ops-gotchas.md (GitHub OAuth section).";
   // The instance name in the tab title comes from the branding pack, never a
   // hardcoded host brand — a non-OTB instance sees its own name (ADR 0062 §3).
@@ -100,7 +103,7 @@ function renderAuthErrorPage(heading, detail, opts = {}) {
 //
 // Branding resolves defensively, exactly as renderAuthErrorPage does — a
 // branding hiccup must degrade to neutral copy, never crash the page.
-function renderAccessPendingPage(login) {
+function renderAccessPendingPage(login, startHref) {
   const worldName = (() => { try { return branding().identity?.worldName || 'The city'; } catch { return 'The city'; } })();
   const epigraph = (() => { try { return branding().copy?.authError?.epigraph || '— access —'; } catch { return '— access —'; } })();
   // The probe takes the login as a query param; everything interpolated into
@@ -124,7 +127,7 @@ function renderAccessPendingPage(login) {
 </header>
 <main>
   <section class="scroll">
-    <div class="landing" id="pending" data-login="${safeLogin}">
+    <div class="landing" id="pending" data-login="${safeLogin}" data-start="${escapeHtml(startHref || '/api/gds/auth/web/start')}">
       <p>We're checking your access now. You'll be signed in automatically as soon as it clears — no need to refresh.</p>
       <p class="landing__note" id="pending-note">Checking…</p>
     </div>
@@ -135,11 +138,14 @@ function renderAccessPendingPage(login) {
   var el = document.getElementById('pending');
   var note = document.getElementById('pending-note');
   var login = el ? el.getAttribute('data-login') : '';
+  /* server-built from the still-valid handshake cookies (task 1003234): the
+     fresh sign-in keeps the wizard return + repo scope a founder started with */
+  var start = (el && el.getAttribute('data-start')) || '/api/gds/auth/web/start';
   var EVERY_MS = 3000;
   var GIVE_UP_MS = 5 * 60 * 1000;
   var started = Date.now();
 
-  function land() { window.location.href = '/api/gds/auth/web/start'; }
+  function land() { window.location.href = start; }
 
   function tick() {
     if (Date.now() - started > GIVE_UP_MS) {
@@ -180,6 +186,18 @@ const RETURN_COOKIE = 'gds_return';
 // include repo") means an ordinary hall sign-in never stores a token, even for a
 // user who previously granted the broader scope (task 1002099 / ADR 0143).
 const REPOS_COOKIE = 'gds_oauth_repos';
+// How long the three /auth/web/start handshake cookies live — the CSRF state,
+// the return target and the repo-scope opt-in — and they MUST move together:
+// a state that outlives its return cookie lands a founder on the default
+// landing with no repo scope, and a return that outlives its state lands them
+// on "State mismatch". They were 10 minutes each, the hall builder's
+// timescale; a founder's first sign-in can include a GitHub SIGNUP (email
+// verification and all) and came back past 10 minutes with all three gone
+// (walk finding, task 1003234). 30 minutes is a security-posture change,
+// deliberately modest: the state is still single-use (the callback clears it),
+// still httpOnly + sameSite=lax, and the code GitHub hands back is still the
+// bearer — only the window in which a legitimate handshake may complete grew.
+const HANDSHAKE_COOKIE_MS = 30 * 60 * 1000;
 
 // The apex domain the instance is served under, read from the instance branding
 // pack's cookieDomain (".amazonprimea.com" → "amazonprimea.com",
@@ -253,6 +271,21 @@ function safeReturnTo(raw) {
   return null;
 }
 
+// The sign-in-again door on every OAuth error page (and the pending page's
+// auto-walk-in), rebuilt from the handshake cookies that are still valid: the
+// return target and the repo-scope opt-in that /auth/web/start stashed. A bare
+// /auth/web/start dropped both, so a founder who hit "State mismatch" from the
+// wizard came back with no repository access and landed on the default
+// landing (task 1003234). Same open-redirect allowlist as the callback.
+function recoveryStartHref(req) {
+  const params = new URLSearchParams();
+  const returnTo = safeReturnTo(parseCookie(req, RETURN_COOKIE));
+  if (returnTo) params.set('return', returnTo);
+  if (parseCookie(req, REPOS_COOKIE) === '1') params.set('repos', '1');
+  const q = params.toString();
+  return '/api/gds/auth/web/start' + (q ? '?' + q : '');
+}
+
 // The canonical sign-in origin, read from the instance branding pack (oauthOrigin,
 // else publicOrigin) so a non-OTB Cloud Bongos instance pins its OAuth redirects to
 // ITS OWN apex instead of a hardcoded "amazonprimea.com" (ADR 0062 §3/§5; the
@@ -422,7 +455,7 @@ module.exports = function buildAuthRouter() {
       httpOnly: true,
       sameSite: 'lax',
       secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
-      maxAge: 10 * 60 * 1000,
+      maxAge: HANDSHAKE_COOKIE_MS,
       // Apex-scoped (#734) so the state survives the host switch: start may run
       // on the subdomain but the callback always lands on the apex.
       ...sessionCookieDomainOpts(req),
@@ -438,7 +471,7 @@ module.exports = function buildAuthRouter() {
         httpOnly: true,
         sameSite: 'lax',
         secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
-        maxAge: 10 * 60 * 1000,
+        maxAge: HANDSHAKE_COOKIE_MS,
         ...sessionCookieDomainOpts(req),
       });
     }
@@ -453,7 +486,7 @@ module.exports = function buildAuthRouter() {
         httpOnly: true,
         sameSite: 'lax',
         secure: req.secure || req.headers['x-forwarded-proto'] === 'https',
-        maxAge: 10 * 60 * 1000,
+        maxAge: HANDSHAKE_COOKIE_MS,
         ...sessionCookieDomainOpts(req),
       });
     }
@@ -519,12 +552,14 @@ module.exports = function buildAuthRouter() {
       return res.status(400).type('text/html').send(renderAuthErrorPage(
         'GitHub refused the handshake',
         `GitHub returned the error code "${error}". This usually means the OAuth app's authorized callback URL doesn't include this server's /api/gds/auth/web/callback path.`,
+        { startHref: recoveryStartHref(req) },
       ));
     }
     if (!code || !state || state !== expectedState) {
       return res.status(400).type('text/html').send(renderAuthErrorPage(
         'State mismatch',
-        'The handshake-cookie did not match the state GitHub returned. This usually means the sign-in took too long (cookie expired after 10 minutes) or the request crossed an origin boundary. Start over and sign in again.',
+        `The handshake-cookie did not match the state GitHub returned. This usually means the sign-in took too long (the cookie expires after ${HANDSHAKE_COOKIE_MS / 60000} minutes) or the request crossed an origin boundary. Start over and sign in again.`,
+        { startHref: recoveryStartHref(req) },
       ));
     }
     try {
@@ -604,15 +639,21 @@ module.exports = function buildAuthRouter() {
           console.error('[gds] web/callback admission classify', probeErr);
         }
         if (expectedSoon) {
-          return res.status(202).type('text/html').send(renderAccessPendingPage(err.login));
+          return res.status(202).type('text/html').send(renderAccessPendingPage(err.login, recoveryStartHref(req)));
         }
+        // The founder-shaped branch (only reachable with open enrollment OFF):
+        // a stranger who was on their way to create a project is told the
+        // approval brings them back to it — the return cookie says where.
+        const founderReturn = safeReturnTo(parseCookie(req, RETURN_COOKIE)) || '';
+        const onWayToProject = founderReturn.startsWith('/projects');
         return res.status(403).type('text/html').send(renderAuthErrorPage(
           'This account is not approved yet',
           `Signing in with GitHub is only for builders the ${admitterLabel()} has already approved. If you are new, request access at the builders’ hall — once the ${admitterLabel()} approves you, this sign-in will let you in. If you were just approved, it may take a moment to be marked invited; try again shortly.`,
           {
             subtitle: 'Sign-in is for approved builders. New here? Request access first.',
             cta: { href: '/builders', label: 'Go to the hall & request access' },
-            note: `Already approved and still blocked? Ask the ${admitterLabel()} to confirm your request was marked “invited.”`,
+            note: (onWayToProject ? 'You were on your way to creating a project — once approved, sign in again and you land back in it. ' : '') +
+              `Already approved and still blocked? Ask the ${admitterLabel()} to confirm your request was marked “invited.”`,
           },
         ));
       }
@@ -620,6 +661,7 @@ module.exports = function buildAuthRouter() {
       res.status(500).type('text/html').send(renderAuthErrorPage(
         'The handshake threw an error',
         `The server tried to exchange the auth code for a session and something went wrong: ${err.message}. Try again; if it persists, ask the ${admitterLabel()} to investigate the server logs.`,
+        { startHref: recoveryStartHref(req) },
       ));
     }
   });
@@ -1080,6 +1122,8 @@ module.exports = function buildAuthRouter() {
 // cookie-domain decision — worth locking down independently of a running server.
 module.exports.safeReturnTo = safeReturnTo;
 module.exports.postLoginLanding = postLoginLanding;
+module.exports.recoveryStartHref = recoveryStartHref;
+module.exports.HANDSHAKE_COOKIE_MS = HANDSHAKE_COOKIE_MS;
 module.exports.sessionCookieDomainOpts = sessionCookieDomainOpts;
 module.exports.reqHost = reqHost;
 // The auth-error page renderer (task 1439): pure over the branding pack, so a

package/src/module-api.js

@@ -1093,8 +1093,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.331 with no explicit bump. run 32793033453. (task 1002620)
 //   1.19.333 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.332 with no explicit bump. run 32793666555. (task 1002620)
+//   1.19.334 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.333 with no explicit bump. run 32794305277. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.333'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.334'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/auth_web_recovery.mjs

@@ -0,0 +1,63 @@
+// tests/auth_web_recovery.mjs — founder-shaped OAuth recovery (task 1003234,
+// goal 1000058). The walk found that every OAuth error page's "try again" door
+// was a bare /auth/web/start — dropping the wizard's return target and the
+// repo-scope opt-in — and that the three handshake cookies expired at 10
+// minutes, i.e. mid GitHub signup. Both are pinned here: the pure helper by
+// value, the call sites and the shared lifetime by reading the source.
+
+import { strict as assert } from 'node:assert';
+import { test } from 'node:test';
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import path from 'node:path';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
+const authRoutes = require(path.join(ROOT, 'src/bongos/routes/auth.js'));
+const { recoveryStartHref, HANDSHAKE_COOKIE_MS } = authRoutes;
+const SRC = fs.readFileSync(path.join(ROOT, 'src/bongos/routes/auth.js'), 'utf8').replace(/\r\n/g, '\n');
+const req = (cookie) => ({ headers: cookie ? { cookie } : {} });
+
+test('the retry door carries the wizard return and the repo-scope opt-in while their cookies are valid', () => {
+  assert.equal(recoveryStartHref(req('gds_return=%2Fprojects%3Fview%3Dnew; gds_oauth_repos=1')),
+    '/api/gds/auth/web/start?return=%2Fprojects%3Fview%3Dnew&repos=1');
+  assert.equal(recoveryStartHref(req('gds_return=%2Fprojects%3Fview%3Dnew')),
+    '/api/gds/auth/web/start?return=%2Fprojects%3Fview%3Dnew', 'a hall sign-in never asks for repos');
+  assert.equal(recoveryStartHref(req('gds_oauth_repos=1')), '/api/gds/auth/web/start?repos=1');
+});
+
+test('with nothing left to rebuild from, the door is the bare start — never a guess', () => {
+  assert.equal(recoveryStartHref(req('')), '/api/gds/auth/web/start');
+  assert.equal(recoveryStartHref(req('gds_session=abc')), '/api/gds/auth/web/start');
+  assert.equal(recoveryStartHref(req('gds_oauth_repos=0')), '/api/gds/auth/web/start', 'only the literal opt-in counts');
+});
+
+test('the door is under the same open-redirect allowlist as the callback', () => {
+  assert.equal(recoveryStartHref(req('gds_return=https%3A%2F%2Fevil.example%2Fx')), '/api/gds/auth/web/start');
+  assert.equal(recoveryStartHref(req('gds_return=%2F%2Fevil.example')), '/api/gds/auth/web/start');
+  assert.equal(recoveryStartHref(req('gds_return=javascript%3Aalert(1)')), '/api/gds/auth/web/start');
+});
+
+test('every OAuth error page and the pending page rebuild their door from the cookies', () => {
+  const start = SRC.indexOf("router.get('/auth/web/callback'");
+  const end = SRC.indexOf("router.get('/auth/discord/start'");
+  const callback = SRC.slice(start, end);
+  assert.equal((callback.match(/\{ startHref: recoveryStartHref\(req\) \}/g) || []).length, 3,
+    'GitHub refused · State mismatch · handshake threw — three pages, three doors');
+  assert.match(callback, /renderAccessPendingPage\(err\.login, recoveryStartHref\(req\)\)/, 'the auto-walk-in lands where the founder was going');
+  assert.match(callback, /const onWayToProject = founderReturn\.startsWith\('\/projects'\);/, 'the founder-shaped NOT_APPROVED note');
+  assert.match(SRC, /const cta = opts\.cta \|\| \{ href: opts\.startHref \|\| '\/api\/gds\/auth\/web\/start', label: copy\.ctaLabel \};/);
+  assert.match(SRC, /data-start="\$\{escapeHtml\(startHref \|\| '\/api\/gds\/auth\/web\/start'\)\}"/, 'the pending page reads its start from a data attribute, never string-built into script');
+  assert.match(SRC, /function land\(\) \{ window\.location\.href = start; \}/);
+});
+
+test('the three handshake cookies share one lifetime, long enough for a GitHub signup', () => {
+  assert.equal(HANDSHAKE_COOKIE_MS, 30 * 60 * 1000);
+  const start = SRC.indexOf("router.get('/auth/web/start'");
+  const end = SRC.indexOf("router.get('/auth/web/admission-status'");
+  const block = SRC.slice(start, end);
+  assert.equal((block.match(/maxAge: HANDSHAKE_COOKIE_MS,/g) || []).length, 3, 'state · return · repos');
+  assert.doesNotMatch(block, /maxAge: 10 \* 60 \* 1000/, 'no handshake cookie is left on the old clock');
+  assert.match(SRC, /the cookie expires after \$\{HANDSHAKE_COOKIE_MS \/ 60000\} minutes/, 'the State-mismatch copy reads the same constant');
+});