@bongos/core 1.18.0 → 1.18.18

package/docs/adr/0145-free-hosted-project-tier-isolation-and-domain-separation.md

@@ -0,0 +1,62 @@
+# 0145 — A free "own-repo" hosted project tier needs domain separation + per-project isolation (not a bare cloudbongos.com subdomain)
+
+- **Status:** Accepted — owner decided 2026-07-15: **keep `cloudbongos.com`** (no separate domain), **container** isolation, **all-free** for now. Choosing the literal same domain makes hardening core sign-in a required prerequisite (see "Decisions" + "Required build sequence"). Build unblocked ([task 1002251](https://cloudbongos.com/builders#/task/1002251)); blocker 1000080 resolved.
+- **Date:** 2026-07-15
+- **Deciders:** Lars (owner/Archon) chose the direction after a security review; Claude ran the review + designed.
+- **Task:** [task 1002249](https://cloudbongos.com/builders#/task/1002249) · **Follow-up to** [ADR 0141](<redacted>.md) (federated hub IdP) and [ADR 0143](<redacted>.md) (the `/create` wizard).
+
+## Context
+
+Owner design review of the `/create` wizard ([public-landing/create.html](../../public-landing/create.html)) asked that a new project be reachable at a **free `<handle>.<platform>` address that works out of the box** (sign-in included), with **bring-your-own-domain** as the optional upgrade — i.e. the handle becomes a real subdomain, not just an internal name.
+
+Today `/create` always provisions the **`standalone`** shape (the owner's own GitHub repo + a pinned `@bongos/core`, run **control-plane-local** on the hub box), and sign-in on a standalone requires the owner to hand-create their own GitHub OAuth app. The natural-looking implementation was: default the address to `<handle>.cloudbongos.com` and extend the hub federation ([ADR 0141](<redacted>.md)) — which already gives co-tenant instances zero-setup sign-in — to standalone instances on that subdomain. A pre-build security review found this **UNSAFE** on two independent counts.
+
+### Finding 1 — the hub session cookie is shared across all `*.cloudbongos.com` (account takeover)
+
+The hub's `gds_session` cookie is issued with `Domain=.cloudbongos.com` on the apex/`builders.`/`status.` hosts, by design, so one sign-in is shared across those subdomains ([src/bongos/auth.js](../../src/bongos/auth.js): `SESSION_COOKIE`, `configuredCookieApex`, `sessionCookieDomainOpts`, the `res.cookie(SESSION_COOKIE, …)` call). A cookie with `Domain=.cloudbongos.com` is sent by the browser to **every** `*.cloudbongos.com` host — including an owner's `mercury.cloudbongos.com`. `httpOnly` does not help (it blocks `document.cookie`, not a server reading its own `req.headers.cookie`); `sameSite:lax` does not help (apex and subdomain are the **same registrable domain** = same site). So a standalone instance running **the owner's code** on a cloudbongos.com subdomain would receive the live hub session token of any signed-in visitor and could replay it against the hub → full account takeover. The neutral core ships `cookieDomain: ""` (host-only, safe); the **live hub must** set `.cloudbongos.com` for its own cross-subdomain sign-in, so the risk is real in production.
+
+The co-tenant instances that federate on cloudbongos.com subdomains today (e.g. `demo.cloudbongos.com`) are safe **only because they run platform-controlled code** ([modules/provisioning/provisioning.js](../../modules/provisioning/provisioning.js): `co-tenant` = a process on THIS control-plane checkout; `standalone` = the owner's OWN repo checkout). The precedent does **not** extend to owner code — it relies on exactly the first-party-code-on-every-subdomain property that owner code breaks. This is why [ADR 0141](<redacted>.md) §4 scoped federation to co-tenant.
+
+### Finding 2 — control-plane-local standalone runs owner code on the hub box, sudo-capable (pre-existing)
+
+A `standalone` runs **on the hub box** ([scripts/gds/provision.js](../../scripts/gds/provision.js): `standaloneBase`, control-plane-local IP) as the **same UID as the hub** (`serviceUnit` hardcodes `User=lars`), and its deploy runs `npm ci` (not `--ignore-scripts`) in a **passwordless-sudo-capable** runner context. A malicious owner could ship a `postinstall` and get code execution as `lars` with sudo on the hub box → the hub's signing key, every instance's secrets, the hub DB. This is a pre-existing property of running owner code on the hub box at all, independent of federation, but any free "run your code for you" tier would expose it at scale.
+
+The federation protocol itself is sound: the hub binds the minted audience to the instance's exact origin (the `#1002108` fix; asymmetric Ed25519 so one instance can't forge for another). A leaked per-instance client secret is contained to its own origin. The weakness is **placement** (shared cookie domain) and **execution** (owner code on the hub box), not the protocol.
+
+## Decision
+
+**Do not** put an owner-code instance on a bare `cloudbongos.com` subdomain, and **do not** extend federation to `standalone` as it exists today. A free "your-own-repo, works-out-of-the-box" tier is delivered **only** once both conditions the review identified are met:
+
+1. **Domain separation.** Free owner instances live under a **different registrable domain** than the hub (e.g. a dedicated `*.<apps-domain>`), so they are cross-site from cloudbongos.com and **never receive the `gds_session` cookie**. (Alternative: make the hub session cookie host-only on a dedicated auth host — but that breaks today's `builders.`/`status.` shared sign-in and is a larger redesign.)
+2. **Per-project isolation.** Owner code must not run as a sudo-capable, same-UID-as-hub process on the hub box: isolate each instance (its own droplet — the existing `dedicated` shape — or a container with a distinct UID, `npm ci --ignore-scripts`, verified-pinned-core-only, and no passwordless sudo in the deploy path).
+
+Only after (1)+(2) is the origin-bound, asymmetric federation ([ADR 0141](<redacted>.md) §4) safe to extend to these instances, giving the zero-setup sign-in.
+
+Points 1 & 2 of the same design review (drop the redundant Home-step "create repo" button; collapse the repo picker on select) were **unrelated to this and already shipped** ([task 1002247](https://cloudbongos.com/builders#/task/1002247)).
+
+## Decisions (owner — resolved 2026-07-15)
+
+- **Domain: keep `cloudbongos.com`** (no separate domain). The owner accepts the "same-site" tradeoff: because tenants (`<handle>.cloudbongos.com`) share the registrable domain with the hub, the browser's same-site protections between them are off, so **Finding 1 is closed by hardening core sign-in** (below) rather than by domain separation. This is the fragile/expert path — it needs strict, permanent cookie/CSRF/CORS hygiene, and one lapse reopens the takeover hole. (Rejected: the separate cloudbongos-branded sibling domain, e.g. `cloudbongos.app`, which the browser would treat as a different site and isolate for free — the industry-standard approach, à la `github.io`.)
+- **Isolation: containers.** Each tenant runs in its own container (distinct UID, `npm ci --ignore-scripts`, no passwordless sudo, not as `lars` on the hub box) — closes Finding 2.
+- **Cost: all-free for now.** Containers make many-instances-per-box cheap; a spend cap is revisited at scale ([§4](../../CLAUDE.md)).
+
+## Required build sequence (task 1002251)
+
+Keeping `cloudbongos.com` makes the sign-in hardening a **hard, security-critical prerequisite** — it changes sign-in for *every* user of the hub, so it lands and is verified on its own before any tenant is placed on a subdomain:
+
+1. **Harden core sign-in (FIRST).** Make `gds_session` a host-only `__Host-` cookie so tenant subdomains never receive it (Finding 1) and cannot toss a parent-domain cookie at the hub; **rework the `builders.`/`status.` shared sign-in** that currently depends on the `.cloudbongos.com`-scoped cookie ([src/bongos/auth.js](../../src/bongos/auth.js) `APEX_COOKIE_HOSTS`); add **CSRF tokens** across all state-changing hub endpoints (SameSite no longer defends against same-site tenants). Audit every hub cookie + CORS rule for `.cloudbongos.com` scope.
+2. **Container isolation.** Provision tenant instances in per-instance containers (distinct UID, `--ignore-scripts`, no sudo in the deploy path) — closes Finding 2.
+3. **Extend federation.** With 1+2 done, extend the origin-bound Ed25519 federation ([ADR 0141](<redacted>.md) §4) to these isolated same-domain instances for zero-setup sign-in.
+4. **Frontend.** Rebuild the `/create` Address step (the stashed redesign is the starting point) + the summary + the federated done-panel.
+
+## Consequences
+
+- The `/create` "free `<handle>.cloudbongos.com`, out of the box" flow is **not built**; the frontend redesign that assumed it is stashed, not shipped. Until this tier exists, `/create` stays own-repo + bring-your-own-domain (safe today).
+- Finding 2 (owner code as sudo-capable `lars` on the hub box) is a **standing risk for the current control-plane-local `standalone` shape** and should be hardened regardless of this tier.
+- If the cost model lands as "platform-subsidized free," a hard spend cap + a cheaper fallback (container isolation, or the co-tenant tier below) is required per [§4](../../CLAUDE.md).
+
+## Alternatives considered
+
+- **(A) Free co-tenant tier (rejected by owner for this ask).** A free `<handle>.cloudbongos.com` running **platform** code on the shared box (like `demo.cloudbongos.com`) is safe + $0 + already federates — but gives the user no separate repo of their own. Closest safe match to "free + out of the box," at the cost of "your own repo."
+- **(C) Keep today's model, honest copy (deferred).** Own repo + bring-your-own-domain, with the `/create` copy clarified (handle = platform name; domain = the real address, needed for sign-in). Safe and shippable now; delivers no free address.
+- **(B) — chosen:** free address + own repo, made safe via domain separation + isolation, accepting the cost. This ADR records why B is required to be safe and what it depends on.

package/docs/adr/0146-configurable-reward-mode-cost-plus-only.md

@@ -0,0 +1,53 @@
+# ADR 0146 — Configurable reward mode: `cost-plus-only` (retire the per-task estimate payout per-instance)
+
+**Date:** 2026-07-16
+**Status:** Accepted
+**Discipline:** engineer (GDS / economy)
+**Task:** [#1002270](https://cloudbongos.com/builders#/task/1002270) (BONGOS-V1, under goal 1000037)
+
+## Context — the problem
+
+A shipped task pays a builder from **two reward streams that land on the same balance**:
+
+1. **The per-task ESTIMATE** — `credits_reward × kind multiplier` ([ADR 0023](<redacted>.md)). A **unitless author estimate** set when the task is authored (or auto-assigned by the no-zero-reward backstop, ADR 0096). It is what a builder sees advertised at claim time, and — since [ADR 0120](<redacted>.md) — it books at ship as `credit_log.reason = 'task.shipped'`, plus a 25% idea-promotion slice ([ADR 0023](<redacted>.md)) to the idea's original capturer.
+2. **The cost-plus SESSION reward** — `round(true_cost_usd × 1.20)`, 1 drachma = $1 ([ADR 0054](<redacted>.md)). Grounded in the session's **real API spend**, booked as `session.token_reward`.
+
+[ADR 0054](<redacted>.md) named this the **"two drachma conventions, one ledger"** tension and explicitly flagged reconciling them as a deferred future-review trigger: one stream is unitless bounty points, the other is dollars, and they are summed into one `total_credits`. Goal 1000037 changed only *when* both pay (on land), never *whether* both pay.
+
+The owner's stated intent for Cloud Bongos is that **a credit means one dollar of cost-plus value and nothing else**. Under the two-stream model that is not true — roughly half of a shipped task's payout is the arbitrary estimate. The owner asked to make the cost-plus reward the **sole** equity reward for Cloud Bongos, and for that choice to be **configurable in the economy module** (so other instances are unaffected and can choose differently).
+
+## Decision
+
+Add a per-instance reward **mode** to the existing reward policy, resolved by the economy module.
+
+- **Config:** `branding.reward.mode` — a new field beside the existing `{ marginPct, usdPeg }` ([the branding contract](../branding-contract.md)):
+  - `"cost-plus-and-estimate"` — **the default.** Pay both streams, exactly as before. Every existing instance keeps its current behavior on upgrade with no config change.
+  - `"cost-plus-only"` — the cost-plus session reward is the **sole equity reward**; the per-task estimate payout is withheld.
+- **Resolution + gate — entirely inside the economy module** (`modules/economy/credits.js`):
+  - a new **pure** `rewardPolicy(rawReward)` maps the raw branding object → `{ marginPct, usdPeg, mode, perTaskCredit }`, where `perTaskCredit = mode !== 'cost-plus-only'`. `rewardConfig()` delegates to it. (Mirrors the pure/impure split of `computeSessionTokenReward`, so the mapping is unit-testable without touching the memoized `branding()` cache.)
+  - `insertMultipliedConfirmCredit(...)` — the **single** writer of the per-task estimate credit — short-circuits to a zero return (**no `credit_log` INSERT**) when `perTaskCredit` is false. Its `config` argument defaults to the resolved `rewardConfig()`; the sole live caller (`lifecycle` `awardLandingCredit`) omits it and gets the resolved instance policy per call.
+- **The idea-promotion slice cascades automatically.** `awardLandingCredit` passes the (now `0`) `creditsAwarded` into `maybeAwardIdeaPromotionBonus`, which already no-ops on a non-positive base — so a fraction of an unpaid estimate is correctly `0`, with **zero lifecycle changes**.
+- **The estimate is preserved as an advertised guide, not a payout.** `tasks.credits_reward` still rides the row: it is shown at claim time and still drives the no-zero-reward claim gate (ADR 0096). Only the *payout* is suppressed.
+- **Fail-safe default.** An unknown / garbage `mode` resolves to the default (pay both). A config typo can never silently zero out every builder's per-task reward.
+
+**Cloud Bongos selects `cost-plus-only`.** Other instances (including the reference founder instance) keep the default and are untouched.
+
+## What this does NOT change
+
+- **The cost-plus session reward** — untouched. Same formula, same `marginPct`/`usdPeg`, same `session.token_reward` path. In `cost-plus-only` mode it is simply the only equity stream.
+- **Achievements and the net-negative (+1 simplification) ship bonus** — deliberately **out of scope**. They are a separate, small behavioral-nudge category (badges + a symbolic +1), not the per-task estimate. If a future owner wants literally *nothing but* cost-plus, gating those is a one-line follow-up; this ADR does not.
+- **The `KIND_MULTIPLIERS` table and `credits_reward` semantics** — unchanged. The multiplier is still computed (for the return shape / audit) even when the payout is withheld.
+
+## Consequences
+
+- **Backward-compatible by construction.** Absence of `mode` ⇒ default ⇒ current behavior. No migration, no data change.
+- **Reversible.** Flipping `mode` back to the default resumes per-task payouts from the next ship; nothing is destroyed. (Historical rows are untouched — this is not a clawback; see [ADR 0120](<redacted>.md) part 4 for the separate one-time backlog re-gate.)
+- **Builder-facing expectation gap (follow-up).** ~~In `cost-plus-only` mode the "Est." shown at claim time is a *guide*, not a promise — the builder is actually paid the cost-plus amount. Surfacing "this instance pays cost-plus only" in the hall / claim UI is a captured follow-up idea, not part of this task.~~ **Resolved by task [#1002469](https://cloudbongos.com/builders#/task/1002469).** The gap was not theoretical: it cost a real session on 2026-07-26, where a correct `Credits +0` was diagnosed as a broken reward gate. The resolved policy is now exposed on the `reward` port (`rewardConfig`), projected onto `clientBranding()` for the hall and returned on `GET /me` + `POST /claims` for the CLI — **the CLI must take it from the server**, since an instance's `config/branding.json` is not in a builder's checkout and a local read always reports the paying default. Claim, `/builder-start`, the ship card, and the hall now label the estimate as an estimate and name the real payer. The hall fix also closed a live misread: `taskCreditValue` falls back to the estimate when a settled task has `credits_awarded === 0` — which under `cost-plus-only` is *every* shipped task — so the plain label was presenting an unpaid estimate as the actual ledger payout.
+- **The two-conventions tension is resolved for `cost-plus-only` instances** (one dollar-denominated stream) and left intact for default instances — the ADR 0054 trigger is addressed by *config*, not by forcing one model on everyone.
+
+## Alternatives considered
+
+- **A boolean `reward.perTaskCredit`** instead of a `mode` enum. Rejected: `"cost-plus-only"` reads self-documentingly at the config site and in prose (it is the vocabulary the decision was made in), and the enum extends cleanly if a third policy is ever wanted. The code derives the boolean internally.
+- **Gate in the lifecycle (`awardLandingCredit`) via a port predicate.** Rejected: it would spread economy policy across the kernel↔module boundary. The knob belongs *inside the economy module* (the owner's explicit ask); gating the single credit writer keeps it there and needs no lifecycle change.
+- **Remove `credits_reward` / stop advertising an estimate entirely.** Rejected: the estimate is still useful as a claim-time guide and is load-bearing for the no-zero-reward claim gate. Suppress the *payout*, keep the *signal*.
+- **Make the cost-plus reward the only stream globally (no knob).** Rejected: the core ships to instances that may legitimately want the bounty-style per-task reward. A per-instance knob with a backward-compatible default respects the core ↔ host split (ADR 0062 §7).

package/docs/adr/0147-standalone-live-docs-regen.md

@@ -0,0 +1,39 @@
+# ADR 0147 — Carry ADR 0110's deploy-regen of generated docs to STANDALONE instances
+
+- **Status:** Accepted
+- **Date:** 2026-07-17
+- **Track:** internal
+- **Builds on:** [ADR 0110](<redacted>.md) (untrack + deploy-regen the whole-file nav docs), [ADR 0108](<redacted>.md) (standalone instance = own repo + pinned `@bongos/core`), [ADR 0062](<redacted>.md) §8 (`gen-session-index.js`), [ADR 0063](<redacted>.md) (`gen-repo-map.js`)
+- **Task:** [#1002314](https://cloudbongos.com/builders#/task/1002314)
+
+## Context
+
+The owner's report: *"All of the docs in cloudbongos.com did not transfer well from primea. Make sure any new project is also set up with live-updating docs."*
+
+The generated navigation docs (`repo-map.md`, `session-log-index.md`, `file-map.md`, the onboarding diagrams, the API reference) stay fresh on the **example monorepo** because ADR 0110's regen-on-deploy is wired into `scripts/deploy/deploy-prod.sh` + `infra/box-source-fetch.sh`. **STANDALONE instances (ADR 0108) never got that step.** A standalone instance is its own lean repo with `@bongos/core` vendored in `node_modules`; it deploys via a bespoke pull script and updates the core via `bongos upgrade`. Two concrete defects left its `docs/` frozen and nearly empty (cloudbongos.com had only the 3 API-doc files):
+
+1. **`gen-session-index.js` hardcoded the core root** — `REPO_ROOT = path.resolve(__dirname,'..','..')`, the exact ADR 0108 configurable-root bug `gen-repo-map.js`/`gen-file-map.js` warn against. On a standalone instance it read/wrote `node_modules/@bongos/core/docs/session-logs`, never the instance's own sessions. It was left behind in the configurable-root migration.
+2. **No standalone regen-on-deploy path.** The bespoke pull-deploy (`git reset --hard origin/main` → migrate → restart) regenerated *nothing*; `bongos init` + `bongos upgrade` only regenerated the API docs (`regenerateApiArtifacts`). So the whole-file nav docs were never seeded and never refreshed on a standalone box.
+
+There is no `scripts/deploy/` in the neutral core — `deploy-prod.sh` is the monorepo's, not something a standalone instance runs.
+
+## Decision
+
+Carry ADR 0110's model to the standalone path — the standalone analogue of the `deploy-prod.sh` regen block.
+
+1. **Fix the root bug.** `gen-session-index.js` resolves `REPO_ROOT = resolveInstanceRoot()` (mirrors `gen-file-map.js`), so it indexes the instance's own `docs/session-logs/` and writes the instance's `docs/session-log-index.md` + the instance-root `CLAUDE.md` §13 snippet. On the monorepo/at-ship it still resolves via the cwd fallback.
+2. **A shared regen seam.** `upgrade.regenerateNavDocs({instanceDir, coreRoot})` runs the whole-file nav generators against the instance root, best-effort + LOUD (a broken generator prints `::ERROR::` but never fails the deploy/bump — ADR 0110 §2 "accepted staleness"). A thin CLI, `scripts/gds/regen-instance-docs.js`, is the one-liner a standalone deploy calls.
+3. **Wired at every refresh point.** `bongos init` seeds it at standup; `bongos upgrade` refreshes it on a core bump; `provision.js`'s standalone deploy runs it after migrate; a bespoke pull-deploy (e.g. cloudbongos.com's `deploy.sh`) calls the CLI after `git reset --hard` + migrate.
+4. **Gitignored on the instance.** `provision.js`'s `INSTANCE_GITIGNORE` ignores `docs/session-log-index.md` (+ `docs/repo-map.md` for parity), so `git reset --hard` never wipes the regenerated file and no branch can ever diff it — the same reasoning ADR 0110 applies on the monorepo.
+
+**Scope — deliberately `session-index` only.** It is the one *gitignored, whole-file, instance-content* nav doc. Explicitly excluded:
+
+- **`repo-map.md`** — CORE-scoped: `gen-repo-map` writes to `resolveCoreRoot()` (the platform-code map), not the instance. A pure standalone instance runs the core from `node_modules` and has ~no code of its own to map, so an instance-level repo-map is empty/meaningless; the core ships its own. An instance-scoped map for **brownfield/adopted** repos (which *do* carry their own code) is a separate enhancement (task 1001655).
+- **`file-map.md` + the API docs** — TRACKED/committed (seeded at init, refreshed at ship/upgrade). Regenerating them on the box would perpetually dirty the tree that `deploy.sh` `git reset --hard`es. `file-map` is also HYBRID (hand-written prose + generated sections) so it cannot leave git; **seeding a fresh instance's `file-map.md` at standup is a follow-up** (it needs a scaffolded `file-map.md` skeleton with the section markers + a `file-map.notes.json`).
+- **Diagrams** — the headless-browser + authed-GDS-session exception (same as ADR 0110 / task 1001641). They do not migrate to the box; they are rendered at package/CI time and shipped.
+
+## Consequences
+
+- A freshly-init'd standalone instance seeds `session-log-index.md`, and its deploy + `bongos upgrade` keep it live against the *instance's* sessions — the "docs didn't transfer" gap is closed for every new project, not just cloudbongos.com.
+- **Accepted staleness (inherited from ADR 0110 §2):** the served whole-file doc is fresh only after a deploy/upgrade, not at merge — tolerable for a navigation index. A generator that breaks leaves a stale/absent file with no *blocking* backstop; the `::ERROR::` line is the alarm.
+- **Follow-ups:** (a) seed `file-map.md` at standup (scaffold skeleton + notes); (b) an instance-scoped `repo-map` for brownfield/adopted repos (task 1001655); (c) productize a continuous pull-deploy timer for standalone instances (today only cloudbongos.com has a bespoke one) so content-only commits redeploy without a manual pull.

package/docs/adr/0148-task-scoped-box-source-access.md

@@ -0,0 +1,48 @@
+# 0148 — Task-scoped box source access (rank-scope → claim-scope)
+
+- **Status:** Accepted (spike R90 / task 1002378 — the architecture pass for goal 1000051). Confirms the build shape of R92–R95.
+- **Date:** 2026-07-18
+- **Deciders:** Lars (owner) — "claim a task → the box pulls only that module's code, on a base Bongos instance; the GitHub token stays on the server." Corrected the earlier "bring-your-own-GitHub" framing.
+- **Extends:** ADR 0031 §6 (box source-access, task 600), ADR 0086 (goals + `scope_modules` scope wall), ADR 0093 (the `lifecycle` port), ADR 0052 (sandbox-for-everyone starter scope). Spec: [`docs/specs/<redacted>.md`](../specs/<redacted>.md).
+
+## Context
+
+A builder's dev box already pulls **scoped** source from the control plane — the GitHub token stays server-side (`box-credential.js`), the box calls `GET /box/source-access` authenticated as the builder, and **git cone-mode sparse-checkout** materializes only the returned folders (`infra/box-source-fetch.sh`, cron `*/10`). Today the scope is a coarse **rank** bucket: `boxScopeForRank(rank)` → `full` (Metic+, whole repo) or `starter` (a fixed `STARTER_SPARSE_PATHS` slice). We want the box to instead carry **the code the builder's claimed task needs**, on top of a base instance — moving the scope from *rank* to *task/module*.
+
+The question this spike answers: **how does `box-access` derive the sparse paths from the builder's active claim(s) without breaking the dev-box↔core module boundary**, and what exactly do R92–R95 build.
+
+## Decision
+
+**Scope = `BASE ∪ (union of the builder's active claims' goals' `scope_modules`, mapped to globs)`.** The claimed task's **goal** is the unit of "what code this work needs" — its `scope_modules` is the already-declared module footprint (the ADR 0086 scope wall), so we reuse it rather than inventing a new per-task field. Union across active claims (owner decision). The transport (`/box/source-access` → `cloneSpecForScope` → sparse-checkout) is unchanged; only *what scope is computed* changes.
+
+**The seam — four small pieces, each already has a home:**
+
+1. **The map is already on the doorway.** `src/module-api.js` exposes `moduleScopeMap` (since doorway `1.12.0`, BV1.R86). So `box-access` reads `api.moduleScopeMap.scopeForModule(key).globs` directly — **no new kernel edit**. The only change is dev-box's `module.json` `coreVersion` `^1.2.0` → `^1.12.0` (core is 1.18.x; satisfied).
+
+2. **The claims read is a small lifecycle-port add.** The `lifecycle` port already exposes `<redacted>`; add a sibling **`<redacted>(builderId)`** that JOINs `claims → tasks → goals` for the builder's active claims and returns the **set-union of `goals.scope_modules`** (empty array when no active claim). dev-box resolves it via `seams.resolveOptional('lifecycle')` — the ADR 0093 module-consumes-port pattern — and adds `lifecycle` to its `consumes` (optional; a vanilla instance without it degrades gracefully to the rank fallback).
+
+3. **`box-access` gains a pure scope→paths function.** `sparsePathsForScopeKeys(scopeKeys, moduleScopeMap)` = `BASE_SPARSE_PATHS ∪ ⋃ directoryGlobs(scopeForModule(key))`. `decideSourceAccess({rank, status, scopeKeys})` gains the optional `scopeKeys`: **present → task-scope spec; absent/empty → base-only; no lifecycle port → the existing rank fallback.** Rank still governs ALLOW/DENY and the provision floor (a below-floor/inactive builder is still 403); rank no longer picks the module *breadth* once a claim drives it.
+
+4. **The route resolves + passes.** In `GET /box/source-access` (which already reads `gdsDb.getBuilderById` via the doorway), resolve the lifecycle port, `const scopeKeys = await lifecycle?.<redacted>(req.builder.id)`, and pass it into `decideSourceAccess`. One added read on an existing handler.
+
+**`BASE_SPARSE_PATHS`** (the "pre-existing Bongos instance" — always present so Claude has context + can run `/builder-*`): the non-product subset of today's `STARTER_SPARSE_PATHS` — `.devcontainer`, `.claude`, `scripts`, `src/bongos`, `docs`, `infra` (+ top-level files, auto by cone mode). Task-module globs layer on top.
+
+### The cone-mode constraint (load-bearing)
+
+Git **cone-mode** sparse-checkout accepts only **directory** entries — a file path aborts the whole `sparse-checkout set` (already documented in `box-access.js`). Module `scope_modules` → globs are of two shapes:
+- **Directory globs** (`modules/dev-box/`, `devbox-app/`, `modules/onboarding/`, `modules/hall-ui/`) — cone-friendly, added directly.
+- **File-list globs** (the `kernel` key = individual `src/bongos/*.js` files) — NOT cone-friendly, BUT their parent `src/bongos` is already in `BASE`, so a `kernel`-scoped task needs no extra sparse entry.
+
+So R93 filters task globs to directory entries; file-list keys are covered by base. (A future move to non-cone sparse patterns could pull individual files, but it is out of scope — cone mode stays.)
+
+## Consequences
+
+- **Confirmed R92–R95 shapes** (the spike's deliverable):
+  - **R92** — dev-box `module.json` `coreVersion` → `^1.12.0` + `consumes:['lifecycle']`; add `lifecycle` port read `<redacted>(builderId)` (db.js query + `lifecycle.js` delegation + a DB-integration test). *Smaller than planned — the map is already exposed.*
+  - **R93** — `box-access.js`: `BASE_SPARSE_PATHS`, pure `sparsePathsForScopeKeys()`, `decideSourceAccess({…, scopeKeys})` with the three-way branch; unit tests (0/1/N keys, cone-filter, fallback).
+  - **R94** — `routes/box.js`: resolve lifecycle + pass `scopeKeys`; graceful when the port is absent.
+  - **R95** — folded into R93's pure decision: 0 claims → base-only; N claims → base ∪ all N goals' scopes. Kept as its own test-focused task.
+- **Behavior change to flag:** an **idle Metic+** (no active claim) now gets **base-only**, not the whole-repo `full` clone they get today. That is the intent (the box is task-scoped), but it is a regression for a Metic+ who relied on an idle box holding everything. Preserving idle full-access would be a config toggle — **deferred**, not built here.
+- **Security posture unchanged (C4):** the credential is still server-issued per fetch from `box-credential.js`; the box never stores the GitHub token durably. This spike does not touch the token model. The deferred hardening (short-lived per-claim credential + hard "can't over-pull" enforcement) is unaffected and still deferred — task-scope here is what the box *asks for*, not yet an *enforced* ceiling.
+- **C4 verified (R102 / task 1002390):** the server-side-token posture is pinned by [`tests/box_credential.mjs`](../../tests/box_credential.mjs) (7 assertions): the credential is sourced only from the prod env (unset → `configured:false`, no fabricated token — ADR 0022); the secret lands in **no** field but `.token` (so the `source_grant` audit — now `scope=<sparse> cred=<rank> mode=…` — carries no secret); the credential scope stays **rank**-based (a separate `BOX_SOURCE_STARTER_REPO_URL` is a hard boundary that only `full` crosses, and an unexpected `task`/`base` label fail-closes to the non-full repo, never the crown jewels); the **claim-scoped `decideSourceAccess` decision carries no secret** (the token is minted *separately* by `box-credential.js`, so changing the sparse breadth never touches the token model); and an inactive/below-floor builder is denied **before** any credential is issued (instant, credential-layer revocation). The **deferred hardening** — a genuinely short-lived, per-claim-*minted* credential plus a hard "can't over-pull" isolation (physically separate per-task materialization) — remains explicitly OUT of scope for this goal; task-scope is the box's *ask*, and the token model is unchanged.
+- **No new migration, no kernel/doorway change, no protected-path edit** beyond the additive lifecycle-port read — R92–R95 all sit inside the `dev-box` + `lifecycle` surface the goal is already scoped to (plus the R91 scope-map prep for the separate C2 chain).

package/docs/adr/0149-bongos-dev-local-launcher.md

@@ -0,0 +1,57 @@
+# 0149 — `bongos dev`: a one-command local launcher for a standalone instance
+
+- **Status:** Accepted (owner decision — "we need a better option to stand up the local host").
+- **Date:** 2026-07-19
+- **Deciders:** Lars (owner) — chose a one-command local launcher over a cloud dev box or a recipe-only fix.
+- **Extends:** [ADR 0108](<redacted>.md) (a standalone instance repo pins the core as a dependency), [ADR 0062 §5](<redacted>.md) (the core owns its own pool + branding). Sibling of `local-preview-lib.js` (task 1056 — the game-only local sandbox) and `onboard`/`provision.js` (the *cloud* standup path).
+
+## Context
+
+The project-creation flow scaffolds a repo whose `config/branding.json` points at `http://localhost:<port>` (each new project gets its own auto-incremented port — the trial produced test3→`:3005`, test4→`:3006`). The repo is **configured** to run on the owner's own machine, but the platform shipped **no command that actually starts it there**.
+
+An owner who cloned a fresh project hit a wall (session export, 2026-07-19): `npm install` works, but then standing the instance up by hand is a six-part assembly — install + start Postgres, `createdb`, run migrations, export `PORT`/`PGDATABASE`/`PGHOST`/OAuth env, launch the server — before `bongos login` can even connect. The guided command that *does* exist, `bongos onboard`, provisions a **cloud** server (needs a public domain + DigitalOcean/Cloudflare tokens); the Docker path (`docs/recipes/self-host.md`) runs a **vanilla** brand on `:3000`, not the repo's brand on its own port. So *local-on-your-Mac* — exactly what a freshly-created project is configured for — was the one unsupported path.
+
+Three silent mismatches made the manual path especially error-prone:
+
+1. **Port.** `src/platform-server.js:44` reads `PORT` from env and **ignores branding** — so the server comes up on `3000` while branding (and every printed link) says `:3006`.
+2. **DB name.** The server pool falls back to the OS username (`src/bongos/pool.js:47` via `instanceDbName()`, which is `null` in a fresh pack), while `scripts/migrate.sh:52` defaults to `example`. They only agree if `PGDATABASE` is set for **both**.
+3. **Socket.** node-pg defaults to the Linux peer socket `/var/run/postgresql` (`pool.js:46`), which does not exist under Homebrew Postgres on a Mac — you must set `PGHOST`.
+
+A fourth failure was operational: the manual server ran **unmanaged in the background**, so a stale server for one project (`:3005`) was still answering when the owner tried the next project — they signed into the wrong instance by accident.
+
+## Decision
+
+Ship **`bongos dev`** — one idempotent command that stands up *this* instance locally and hands off to sign-in.
+
+```
+bongos dev            up: Postgres → createdb → migrate → server → sign-in
+bongos dev stop       stop the background server this launched
+bongos dev status     is it up? what URL? is sign-in configured?
+```
+
+`bongos dev` (default) runs, in order:
+
+1. **Preflight** — `psql`/`createdb`/`pg_isready` present (clear `brew install` guidance if not); `bash` present for migrations.
+2. **Postgres up** — if not running, start it (Homebrew `postgresql@N`, else `pg_ctl` with `PGDATA`), poll until ready.
+3. **`createdb`** the instance's database if absent (migrate.sh does not create it).
+4. **Migrate** — run the core `migrate.sh` with `MEDUSA_GDS_ONLY=1` (a fresh local instance never wants OTB's instance seeds).
+5. **Start the server** DETACHED but **managed** (pid/log keyed per instance), poll `/healthz` + `/api/gds/healthz`.
+6. **Sign in** — if creds resolve and the machine isn't already signed in to this instance, run `bongos login <origin>`; otherwise print the exact command (`--no-login` skips).
+
+**It resolves the three mismatches from one source of truth (branding):** `PORT` = the port in `domains.publicOrigin`; `PGDATABASE` = `db.database` → repo dir name → `cloudbongos_dev`, exported for **both** migrate and the server; `PGHOST` defaults to TCP `localhost` (an explicit env override still wins). The pure resolution + process management live in `scripts/gds/dev-lib.js` (fully injectable, unit-tested in `tests/dev_lib.mjs`); the side-effecting orchestration is `scripts/gds/dev.js`.
+
+**Managed-not-orphaned** is the fix for the wrong-instance accident: the background server has a pid/log keyed per `(dbName, port)`, so `bongos dev status`/`stop` make it visible and killable and a re-run is a no-op. `--foreground` runs it attached (Ctrl-C lifecycle) for those who prefer it.
+
+**The one irreducibly-manual step** — a GitHub OAuth App — is only surfaced when no creds resolve (env `<PREFIX>_GITHUB_CLIENT_ID/SECRET` or `~/.config/<configDir>/gds-github.json`, mirroring `auth.js:loadGithubCreds`). A machine that already ran another instance carries usable creds and skips it entirely.
+
+## Alternatives considered
+
+- **Cloud dev box** (`bongos box` + `bongos code`) — the platform's blessed remote-dev model, but it needs the project *hosted* first and adds cloud cost; overkill for "try this project on my Mac." Rejected by the owner for the local case (still the right answer for remote/multi-machine work).
+- **Docker** (`self-host.md`) — real, but serves the *vanilla* brand on `:3000`; matching the repo's brand + port needs a `docker-compose.override.yml` and a port change, and Docker Desktop is heavy for a non-technical owner. Kept as the Windows / container path.
+- **Recipe only** (no command) — fastest, but leaves the six-step assembly and the three mismatches in the owner's hands every time. Rejected; the recipe ([`docs/recipes/local-dev.md`](../recipes/local-dev.md)) now just documents `bongos dev`.
+
+## Consequences
+
+- A freshly-created, localhost-configured project goes from `git clone` to a running, signed-in instance with `npm install` then `bongos dev` — no manual DB/env/port work.
+- Windows is not covered by the native path (migrations need `bash`); those users take the Docker path. Noted in help + the recipe.
+- `bongos dev` runs a repo verb (needs the installed core), so it is **not** bundled into the standalone on-ramp binary — it needs a real checkout + `npm install`, which the flow already has.

package/docs/adr/0150-box-first-boot-bringup-vendored-instances.md

@@ -0,0 +1,68 @@
+# 0150 — Box first-boot bring-up on vendored instances: resolve `infra/` from the instance root, fail loud on empty user-data
+
+- **Status:** Accepted (spike BV1.R97 / task 1002385 — the C2 diagnosis for goal 1000051 / 1000052). Confirms the build shape of R98 (task 1002386) + R99 (task 1002387).
+- **Date:** 2026-07-19
+- **Deciders:** Lars (owner) — "continue with C2" (make cloudbongos boxes stop coming up bare). Claude diagnosed + designed the fix.
+- **Extends:** [ADR 0144](<redacted>.md) (its first follow-up item root-caused this), [ADR 0108](<redacted>.md) (the `resolveCoreRoot()`/`resolveInstanceRoot()` split this fix rides), [ADR 0031](<redacted>.md) (box lifecycle), [ADR 0148](<redacted>.md) (task-scoped source access — which only matters once a box actually boots).
+
+## Context
+
+"cloudbongos boxes come up bare" — a freshly provisioned box reaches `active` but has **no clone, no toolchain, no browser terminal** (`term-<login>` returns Cloudflare 530). The task-scoped source-access mechanism (ADR 0148, C1) is irrelevant until a box actually boots with the base instance present — so C2 is the practical foundation.
+
+There are two provisioning paths in the fleet's history:
+
+- **The reference (example) path** — `scripts/gds/box.js` renders a DigitalOcean cloud-init from `infra/builder-box-cloud-init.yaml` (+ ~12 gz+b64-inlined scripts: `box-source-fetch.sh`, the cloudflared/ttyd units, `box-heartbeat.sh`, …). The cloud-init is what clones the source, installs the toolchain, and starts the terminal. A box is "non-bare" **because** its user-data ran.
+- **The cloudbongos path** ([ADR 0144](<redacted>.md)) — native `cloudbongos-box-*` runners against the local DB, but the **same `box.js`** renders the same cloud-init.
+
+## Root cause (code-grounded + live-confirmed)
+
+The box boots bare because **`box.js` renders EMPTY user-data and no one notices**:
+
+1. `box.js` sets `REPO_ROOT = path.resolve(__dirname, '..', '..')` ([`scripts/gds/box.js:47`](../../scripts/gds/box.js)). On a **vendored** instance `box.js` lives at `node_modules/@bongos/core/scripts/gds/box.js`, so `REPO_ROOT` resolves to the **vendored-core package root**.
+2. The R89 packaging split moved `scripts/gds/` **into** `@bongos/core` but **kept `infra/` as instance content** — `infra/` is **not** in the core publish-manifest, so `node_modules/@bongos/core/infra/` **does not exist**.
+3. `readCloudInit()` reads the template at `REPO_ROOT/infra/builder-box-cloud-init.yaml` ([`box.js:258`](../../scripts/gds/box.js)). Missing dir → `readFileSync` **throws** → the surrounding `try { … } catch { return null }` ([`box.js:313`](../../scripts/gds/box.js)) swallows it → **`readCloudInit` returns `null`**.
+4. The caller treats `null` as *zero bytes, fine*: `const userDataBytes = userData ? … : 0` then `if (userDataBytes > MAX_USERDATA_BYTES) fail()` ([`box.js:453-455`](../../scripts/gds/box.js)). `0 > 64KiB` is false, so the **only** size guard passes and provisioning proceeds with empty user-data. DigitalOcean logs "No user-data found"; the box is bare Ubuntu.
+5. Even a **partial** `infra/` half-wires a box: `fileGzB64()` ([`box.js:268-275`](../../scripts/gds/box.js)) warns on a missing inlined file but still **returns `''`** (fail-soft), so the placeholder is substituted with nothing and that component silently never boots.
+
+**Live re-confirmation (2026-07-19, on the cloudbongos droplet):**
+
+- `infra/` **is present at the instance root** — `/home/lars/cloudbongos/infra/builder-box-cloud-init.yaml` exists.
+- `infra/` **is absent in the vendored core** — `/home/lars/cloudbongos/node_modules/@bongos/core/infra/` is gone. The ADR 0144 stopgap (hand-copying `infra/` into `node_modules`) was **wiped by a core reinstall** since 2026-07-15, exactly as that ADR warned.
+- `bongos.config.json` at the instance root already declares `{"instanceRoot": "."}` — so `resolveInstanceRootExplicit()` deterministically resolves to `/home/lars/cloudbongos`, where the real `infra/` lives.
+- Fleet is idle (1 box, `destroyed`), so the bug is **latent but live**: nothing is broken this instant, but the **next** provision boots bare.
+
+So the failure is a **packaging-locality bug**, not a logic bug: `box.js` looks for `infra/` in the one place it isn't (the core package) instead of the one place it is (the instance root).
+
+## Decision
+
+### R98 — make the box clone the base instance on boot
+
+**Prong A — resolve `infra/` from the instance root** (ride [ADR 0108](<redacted>.md), exactly like [`scripts/migrate.sh:35`](../../scripts/migrate.sh) resolves its roots). A new `resolveBoxInfraDir()` in `box.js` returns the first candidate that actually contains `builder-box-cloud-init.yaml`, in order:
+
+1. an explicit `<PREFIX>_BOX_INFRA_DIR` env override (escape hatch);
+2. `resolveInstanceRootExplicit()/infra` — the env / `bongos.config.json` pointer (cloudbongos: `{"instanceRoot":"."}` → `/home/lars/cloudbongos/infra`);
+3. `REPO_ROOT/infra` — the dev single-checkout case (and the old node_modules workaround location, for continuity);
+4. a bounded walk **up out of `node_modules`** from the core root, so a vendored `…/node_modules/@bongos/core` finds its host instance root even with no pointer set.
+
+All `infra/` reads (`readCloudInit`'s template + every `fileGzB64`) route through this resolved dir. **The neutral core still ships no `infra/`** — this changes only how `box.js` *locates* instance-owned infra, not what the core packages.
+
+**Prong B — fail loud, never provision empty.** Two backstops so a bare box can never be created silently again:
+
+- `readCloudInit()` **throws** an actionable error when no `infra/` dir with the template is found (stop returning `null`);
+- `cmdProvision` aborts with `fail(...)` if the rendered user-data is empty / 0 bytes, naming the candidate dirs searched and pointing at this ADR — **before** touching DigitalOcean.
+
+(Optionally escalate `fileGzB64` to hard-fail for the load-bearing inlined files, or assert no `__…_B64__` placeholders survive the render, so a *partial* `infra/` also surfaces rather than half-wiring.)
+
+### R99 — toolchain builds on the box
+
+Once `infra/` resolves and `box-source-fetch.sh` runs on first boot, the base instance clones. R99 then ensures the **runtimes** are present so a pulled module is actually buildable/runnable by Claude on the box: verify the cloud-init (or the devcontainer/`box-source-fetch` bring-up) installs Node + the common build tools, and that on a fresh box a pulled module's `npm ci` / build / test commands run. Concrete scope is R99's own; this ADR only fixes *getting the code + bootstrap onto the box*.
+
+## Consequences
+
+- **Reinstall-proof.** The fix reads the instance's own `infra/` (or an explicit pointer), so a core `npm ci` / `bongos upgrade` can never wipe it — the fragile ADR 0144 workaround-in-`node_modules` is retired.
+- **Portable.** Every vendored instance benefits: `box.js` stops assuming `infra/` ships inside the core package. This is a **core** fix (lands on core `main`), not a cloudbongos-only patch.
+- **Fail-loud tradeoff (intended).** A genuinely infra-less instance can no longer provision a box — it errors clearly instead of creating a useless bare one. A bare box is worse than a legible failure.
+- **Go-live gap.** The fix lands on core `main`; it reaches cloudbongos.com only via the separate release (package-core + `bongos upgrade`). The fleet is idle today, so nothing is broken this instant; the next box provision needs the fix live (or the `node_modules` workaround re-applied as a one-off) — flagged to the owner in the session handoff.
+- **No new migration, no doorway/kernel change.** The fix is contained to `scripts/gds/box.js` + a unit test; it reuses the existing `src/instance-config.js` resolvers.
+- **R99 landed (task 1002387) — toolchain + test-runnability.** Core-side audit: the `.devcontainer` toolchain is complete (Node 22 via features + `build-essential`/`pkg-config`/Python 3.12 in the Dockerfile, with a build-time integrity healthcheck); the root `package.json` declares **no npm workspaces**, so a task-scoped *sparse* checkout can't break `npm ci`; and the task-scoped BASE already carries the top-level `package.json` + lockfile (cone-mode ancestor inclusion), so `npm ci` has what it needs. The one real gap: a module's **tests live in the top-level `tests/` dir** (`tests/box_*.mjs` + `tests/helpers.mjs`), which was in **neither** `BASE_SPARSE_PATHS` nor `STARTER_SPARSE_PATHS` — so a task-scoped or starter box pulled the module source but **not its tests**, and "a pulled module's build/test commands run" failed. Fix: add `tests` to both scope lists (`modules/dev-box/box-access.js`) — a cone-mode dir carrying only test code, no product runtime. Pinned by the updated `tests/box_access.mjs` + `tests/box_task_scope.mjs`. **Deferred to the live proof (R104, task 1002392):** the end-to-end "fresh box → `npm ci` → a pulled module's build/test actually runs" on the cloudbongos plane — the toolchain *install* rides the instance-only cloud-init (now reachable thanks to R98) and provisioning a box is owner-gated (spends money), so the live demonstration belongs to the C5 proof, not this core change.
+- **R98 landed (task 1002386).** `scripts/gds/box.js` gained `boxInfraCandidates()`/`resolveBoxInfraDir()` (the ordered instance-root-first search) + `BOX_INFRA_TEMPLATE`; `readCloudInit` now routes every `infra/` read through the resolved dir and **throws** on a missing/incomplete `infra/` instead of returning `null`; `cmdProvision` resolves the source up front (dry-run + apply, printing `cloud-init source: <dir>`), catches the throw into a clean `fail()` with box state `error`, and refuses to provision on empty user-data. Pinned by [`tests/box_infra_resolve.mjs`](../../tests/box_infra_resolve.mjs) (8 assertions: candidate ordering incl. the node_modules walk-up, first-with-template selection, `null` when none, and the two fail-loud throws). Backward-compatible: a dev single-checkout still resolves `REPO_ROOT/infra`.