@bongos/core 1.19.370 → 1.19.371

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.370",
-  "core_contract": "1.19.370",
-  "source_commit": "ebdccda3c80527bbbaaf2aa022f22c30b8353d93",
+  "core_version": "1.19.371",
+  "core_contract": "1.19.371",
+  "source_commit": "587eb4ed0b68da54bf63fb01b69fab937450bd66",
   "source_ref": "HEAD",
-  "built_at": "2026-08-25T22:03:32.779Z",
+  "built_at": "2026-08-25T22:08:11.031Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 334,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 1900,
-  "tree_sha256": "8d54fad99843ef1feeef5e52a4e23dd1dca2c6f5ba1e72eff5ce6aee06684aa3",
+  "tree_sha256": "55cb6adeadbe8a337b32bba8352f2dbc38d655ec2cdd807c550d527b9f49822d",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -1862,7 +1862,7 @@
     {
       "path": "docs/recipes/work-on-a-task-from-your-dev-box.md",
       "mode": "0000644",
-      "sha256": "15a8fa87b11a3d3ab86551f9bc54adaf84c2a7a2b8fb7fc6915c0d16e5f5199d"
+      "sha256": "be4d67926e39c9f9c146f5f709d30595057058f5c4444c1e87ed92e37b3f3190"
     },
     {
       "path": "docs/research/cursor-competitive-analysis.md",
@@ -4902,12 +4902,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "9dff8f392336cdd431ed666c04b21e660115a6fdba3040fd0f6c280aafbfe0a7"
+      "sha256": "9013a462765ac09e02093fd322534183ef67983cba7fb17b01ffd9e514c904ba"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "416d8ecc99b8e45e6d71bda6f0be7f1a57fdb24cd1a08f11093184e4b8e8622d"
+      "sha256": "02ba6d7d5c371b3b07671bb84216d7a38a23b9ab97f3ab491d218fb31f9afa46"
     },
     {
       "path": "public-docs/index.html",
@@ -6792,7 +6792,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "4844a8a3d51f23328f5c31766f10a194579f779b225d024bdb20f62f0ee4f0c1"
+      "sha256": "acc072cf951d0eb479345626f462425a47d7f8a0247db473375fa614f64e7589"
     },
     {
       "path": "src/module-loader/catalog.js",

package/docs/recipes/work-on-a-task-from-your-dev-box.md

@@ -1,12 +1,13 @@
 # Work on a task from your dev box
 
-> Your dev box is **task-scoped**: claim a task and the box pulls **only the code
-> that task needs** — the module(s) its work touches, on top of a small base
-> instance — never the whole repo. Your GitHub token never leaves the server; the
-> box fetches its slice through the control plane. See
-> [ADR 0148](../adr/<redacted>.md) (the scope model) and
-> [ADR 0150](../adr/<redacted>.md) (how the box
-> comes up).
+> Your dev box serves your **rank scope**: Metic+ boxes carry the **whole repo**;
+> newcomer (starter) boxes carry the safe starter surface. Task-scoped slices are
+> **paused** per [ADR 0193](../adr/<redacted>.md) (the
+> machinery from [ADR 0148](../adr/<redacted>.md) remains;
+> `BOX_TASK_SCOPE=on` re-enables it). Your GitHub token never leaves the server —
+> see "How git works on a box" below, and
+> [ADR 0150](../adr/<redacted>.md) for how the
+> box comes up.
 
 ## TL;DR
 
@@ -15,32 +16,48 @@ In your dev box's terminal:
 ```bash
 /builder-start          # see what you can claim
 /builder-claim <N>      # claim task N (locks it to your session)
-/builder-sync           # pull task N's code onto the box now (re-scopes in place)
+/builder-sync           # pull the latest main onto the box right now
 # …work in /workspace…
 /builder-ship           # smoke + review, then land + deploy — awards credits
 ```
 
-That's the whole loop. `/builder-sync` is the new step: it materializes the claimed
-task's code within seconds instead of waiting for the box's ~10-minute refresh.
+That's the whole loop. `/builder-sync` pulls fresh code within seconds instead of
+waiting for the box's ~10-minute refresh.
+
+## How git works on a box — read this BEFORE diagnosing "stuck"
+
+The box holds **no stored git credential, ever** — and that is the design, not a
+fault ([ADR 0055](../adr/<redacted>.md)):
+
+- **Reads are server-mediated, per request.** Every remote git operation goes
+  through `/usr/local/bin/otb-git-credential`, which asks the control plane
+  (`GET /box/source-access`) for a **short-lived, read-only** credential. The
+  server checks your **live** rank + status on every single request — demotion or
+  deactivation cuts off the next fetch instantly.
+- **`git push` always fails with 403 here — by design.** The read credential
+  cannot write. Landing code is the server's job: `/builder-ship` uploads your
+  work, opens the PR, and lands it. Never try to fix the 403 by embedding a
+  token or editing git config.
+- **Source refreshes from `main` every ~10 minutes** (the `box-source-fetch`
+  cron; log at `/tmp/box-source-fetch.log`). `/builder-sync` runs the same fetch
+  on demand.
+- **If a remote git op says `could not read Username`, or the sync log shows
+  401:** the box's GDS session expired. Run `/builder-reauth`, then
+  `/builder-sync`. That is the whole fix.
+
+The box writes these same facts to `/workspace/CLAUDE.local.md` on every sync, so
+a Claude session on the box loads them automatically (the file is gitignored and
+box-written — don't edit it).
 
 ## The model — what's on your box
 
-A task-scoped box carries two layers:
-
-1. **The base instance** — always present, whatever you've claimed: the methodology
-   (`CLAUDE.md`, `.claude/`), the build tooling (`scripts/`, `src/bongos/`),
-   `docs/`, `infra/`, and the **test suite** (`tests/`). Enough for Claude to hold
-   context and run the `/builder-*` CLI, and to run your module's tests.
-2. **Your claimed task's code** — the module directories the task's goal scopes
-   (`goals.scope_modules` → globs, [ADR 0086](../adr/<redacted>.md)). Claim a `dev-box` task → you get
-   `modules/dev-box/`; claim a `game` task → you get the game world too. Nothing
-   else.
-
-What you do **not** get: other builders' modules, the product/game runtime (unless
-your task is game-scoped), and — the point — **no GitHub credential on the box**.
-The box asks the control plane (`GET /box/source-access`) for its slice on each
-fetch; the server holds the token and returns a scoped, cone-mode sparse-checkout
-spec. Lose the claim or a rank, and the next fetch is cut off at the server.
+- **Metic and above:** the full repo in `/workspace` — same tree as a laptop
+  clone, refreshed from `main` by the sync cron.
+- **Below Metic (starter):** the starter surface — methodology (`CLAUDE.md`,
+  `.claude/`), build tooling (`scripts/`, `src/bongos/`), `docs/`, `infra/`,
+  `tests/`, and the sandbox-runnable product code. Rank, checked live by the
+  server, is what bounds a box — not the task you claimed
+  ([ADR 0193](../adr/<redacted>.md)).
 
 ## Step by step
 
@@ -51,11 +68,10 @@ If you haven't yet, run **`/builder-connect`** (or follow the
 box, then **`/builder-setup`** once on the box to sign the Bongos CLI in. The browser
 terminal drops you into `/workspace` — the one working folder.
 
-> **`bongos shell` / `bongos code` re-scope on connect (BV1.R101).** Connecting with
-> either verb runs the sync for you first, so you land in `/workspace` already scoped
-> to your active claim — no manual `/builder-sync` needed just to arrive. (The browser
-> terminal drops you straight into `/workspace`; run `/builder-sync` there if you
-> claimed or switched since your last sync.)
+> **`bongos shell` / `bongos code` sync on connect (BV1.R101).** Connecting with
+> either verb runs the source fetch for you first, so you land in `/workspace`
+> already fresh. (The browser terminal drops you straight into `/workspace`; run
+> `/builder-sync` there if you want the latest immediately.)
 
 ### 2. See what you can claim — `/builder-start`
 
@@ -64,21 +80,18 @@ claims. Pick one.
 
 ### 3. Claim it — `/builder-claim <N>`
 
-Locks task N to your session. **This is what drives your box's scope:** source
-access is computed from your **active claim** — its task → goal → `scope_modules`.
+Locks task N to your session so no parallel session collides with your work.
 
-### 4. Pull the code now — `/builder-sync`
+### 4. Freshen the code — `/builder-sync`
 
-Re-runs the box's source-fetch immediately, so `/workspace` re-scopes to task N's
-modules within seconds. (A ~10-minute cron does this on its own as a backstop — you
-just don't want to wait for it.) Off a box there's nothing to sync — your source is
-your local checkout — and the command tells you so.
+Re-runs the box's source fetch immediately so `/workspace` is on the current
+`main` before you branch. (The ~10-minute cron does this on its own as a
+backstop.) Off a box there's nothing to sync — your source is your local
+checkout — and the command tells you so.
 
 ### 5. Work — in `/workspace`
 
-`/workspace` now holds the base instance **plus** task N's module code. One folder:
-when you switch tasks it **re-scopes in place**, so there are no per-task folders to
-manage.
+One folder, always. When you switch tasks, keep working in place.
 
 ### 6. Ship — `/builder-ship`
 
@@ -90,19 +103,20 @@ One box, one working folder, one active claim at a time (the server enforces
 one-claim-per-session). To move to a different task:
 
 1. `/builder-ship` (or `/builder-release`) the current claim.
-2. `/builder-claim <M>` the new one.
-3. `/builder-sync` — the box re-scopes to task M in place.
+2. `/builder-claim <M>` the new one — and keep working in `/workspace`.
 
 ## Notes + gotchas
 
-- **`tests/` is always in the base** — so a module's tests run on the box (they
-  live in the top-level `tests/`, not inside `modules/<key>/`).
-- **Idle boxes rest.** A box with no activity is reclaimed after ~10–15 min; the
-  next connect re-provisions a fresh one and re-fetches your scope. **Uncommitted
-  work on a reaped box is lost** — ship or commit before you step away.
+- **`tests/` is on every box** — a starter box can run the suite for the code it
+  holds (tests live in the top-level `tests/`, not inside `modules/<key>/`).
+- **Idle boxes park, they don't die.** After ~2 hours of no activity the box is
+  **parked**: a snapshot is kept and the droplet is destroyed, so compute billing
+  stops and a wake restores your filesystem. Only weeks of staying parked lead to
+  reclaim (with a warning first). Still: **ship or commit before you step away** —
+  a snapshot is a safety net, not a workflow.
 - **`/builder-sync` is idempotent** — safe to re-run; it just does, on demand, what
   the cron does on its schedule.
-- **A fresh box comes up with the base already cloned.** If a box ever comes up
+- **A fresh box comes up with the code already cloned.** If a box ever comes up
   *bare* (no code, no terminal), that's the packaging bug
   [ADR 0150](../adr/<redacted>.md) fixed on the
   control plane — flag it rather than working around it.

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.370",
+  "version": "1.19.371",
   "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/module-api.js

@@ -1170,8 +1170,10 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.368 with no explicit bump. run 32903289072. (task 1002620)
 //   1.19.370 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.369 with no explicit bump. run 32904231221. (task 1002620)
+//   1.19.371 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.370 with no explicit bump. run 32904582252. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.370'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.371'; // 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');