@bongos/core 1.19.646 → 1.19.647

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.646",
-  "core_contract": "1.19.646",
-  "source_commit": "9648a16f755cae6136582c0d0ca4930a566a11af",
+  "core_version": "1.19.647",
+  "core_contract": "1.19.647",
+  "source_commit": "8fa0f8d28d7d61f52297185e5c669d70a60480de",
   "source_ref": "HEAD",
-  "built_at": "2026-09-10T18:10:26.956Z",
+  "built_at": "2026-09-10T18:40:35.458Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 470,
     "agent_docs_stubbed": 24,
-    "functional_verbatim": 2106,
+    "functional_verbatim": 2107,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 2600,
-  "tree_sha256": "69d3719087a6b6e7fb7c1a0d4889c6bf272f0258a7d7cc72458179525775f6df",
+  "file_count": 2601,
+  "tree_sha256": "7cebbe4108e45c224a38f2068e1e7a1d00552500b0b6f6d7f5c111d45f63a037",
   "files": [
     {
       "path": ".claude/skills/backlog-review/SKILL.md",
@@ -362,12 +362,12 @@
     {
       "path": "clients/bongos-client/README.md",
       "mode": "0000644",
-      "sha256": "65fb7649709e966a90f431d57b8855bd39951684a754320c4a797da9e3ccac13"
+      "sha256": "03379a98721207feab9a9b4c03862051ee6d52a29a0bc467ed73ae1d36bf49cd"
     },
     {
       "path": "clients/bongos-client/bongos-client.global.js",
       "mode": "0000644",
-      "sha256": "ea404e8d932d396796888692651965072cb8d828b3d6e9ebb93bc205fb00f7b9"
+      "sha256": "ec75333abb0ee49b89320a86e73b56f2f3872c13c596b1e67f36e705b8ba1210"
     },
     {
       "path": "clients/bongos-client/examples/hello-world.mjs",
@@ -377,17 +377,17 @@
     {
       "path": "clients/bongos-client/index.cjs",
       "mode": "0000644",
-      "sha256": "a6fb1af25ba5d2ef74cee69f2e126811d535b193422d44ee6f2f4efb787d7584"
+      "sha256": "bce3dcdbe37505e0fa526e02b7b379ca9ab378f6c34b41345621d55170d9f19d"
     },
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "c109144665c545407dc0a56a8d08e77b277d7a1636ab3740d0e81e43c563f616"
+      "sha256": "a6b15120b937f2a73d47ef180956068560eb3ac3efe5cf58f3a021b544ff9bc0"
     },
     {
       "path": "clients/bongos-client/index.mjs",
       "mode": "0000644",
-      "sha256": "0b96a51d69f2aeb6485eea84d80254ee1a4f90a8292c6b33e9bb89075f8cc187"
+      "sha256": "3fbcb50de89350e95b86180e828a16b897be32a1f8b4cdf78cc060e1c5afff86"
     },
     {
       "path": "clients/bongos-client/package.json",
@@ -1892,12 +1892,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "72bfc066767c1c7301516d4f747c8a29725c2d623b5be1d916e6baa11e20a988"
+      "sha256": "0fa07d5f61ab66a43e0c51e51cfac8223afcb1aa12ea7342a226cb1832c0be62"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "ac3c10aa8cc2cdad0d6878a7b2c51bb668b5207a2cd9649ee87da871e190494e"
+      "sha256": "02c082bff4c5bebbf13cefeeb46a6b9cdff430cc32b65dd4e78a72248c6fd74f"
     },
     {
       "path": "docs/architecture.md",
@@ -2772,7 +2772,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "f4ceea78bdb8f6ba5fec64415aed58610a8ab011d3a8b550e517515904c8cfce"
+      "sha256": "0f1d4f5ea01f97e24ee83708c35267828f6d7fb2c64a47db9b7b94c43205951a"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3814,6 +3814,11 @@
       "mode": "0000644",
       "sha256": "06b53d66e710dfbf602011459ec8d69adce8e281632927daea0735f8078b2f86"
     },
+    {
+      "path": "migrations/core_237_box_widen_paths.sql",
+      "mode": "0000644",
+      "sha256": "2cda282b43ea71dd82ddf4e5ece90f11ad4013cbee0820f0a33391f202feff9c"
+    },
     {
       "path": "modules/agents/lib/validate.js",
       "mode": "0000644",
@@ -4212,7 +4217,7 @@
     {
       "path": "modules/dev-box/app/src/vendor/bongos-client.cjs",
       "mode": "0000644",
-      "sha256": "a6fb1af25ba5d2ef74cee69f2e126811d535b193422d44ee6f2f4efb787d7584"
+      "sha256": "bce3dcdbe37505e0fa526e02b7b379ca9ab378f6c34b41345621d55170d9f19d"
     },
     {
       "path": "modules/dev-box/app/test/unit.mjs",
@@ -4222,7 +4227,7 @@
     {
       "path": "modules/dev-box/box-access.js",
       "mode": "0000644",
-      "sha256": "a51e16aba67547c0692d9422587f83d8ce40f0e45830463b80bfd188401eb6c0"
+      "sha256": "7bc7c746f2518cb465773a205c8e9fe7efc30852c857001255be92ad8e340bca"
     },
     {
       "path": "modules/dev-box/box-credential.js",
@@ -4237,7 +4242,7 @@
     {
       "path": "modules/dev-box/boxes.js",
       "mode": "0000644",
-      "sha256": "a56b75218b3ac3fed0bb495b9c7f41b2794dafa5f3e6ec28cbb21a97e9b25b7b"
+      "sha256": "667993d81db36e1ddd1307013044f3d40b6baca3c6f5271b77332d10fa290063"
     },
     {
       "path": "modules/dev-box/db.js",
@@ -4252,7 +4257,7 @@
     {
       "path": "modules/dev-box/routes/box.js",
       "mode": "0000644",
-      "sha256": "bbe6ed7344f7e5dd1d4dba79e636f4bc02806d25193edb0609f41c850ffbad4c"
+      "sha256": "b61996de3fa3dbdc9b8fb639fd53aba5c1c2567350dc602b39ebbbd3a93164ac"
     },
     {
       "path": "modules/discord/CLAUDE.md",
@@ -7722,12 +7727,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "8def408bd91446b93b180b2696465b9bedaf1f8ebe15c671cd4f66a41f6b03da"
+      "sha256": "b271a576a07b28caf13c7d64f1ba8407e3a4d5e53d13accf0da4ad461f94382e"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "62ee3c0059ddc570ef2fef4f2288b7714d9eb95f64d390f67720eb7d07c92cd5"
+      "sha256": "e6e4d441aab1b961398eb377d6ac1e4cb9f072efcfa26bd5f51b878b116a8a3e"
     },
     {
       "path": "public-docs/index.html",
@@ -7917,7 +7922,7 @@
     {
       "path": "scripts/gds/box-sync.js",
       "mode": "0000644",
-      "sha256": "981544bfd56d486c2017edd744c86089659771a74399b4780455821c45e3b3a9"
+      "sha256": "33a79ddd2049419fe7df09cd7b5fe3da9163728a36bc8fe1351d89dcf2463a11"
     },
     {
       "path": "scripts/gds/box.js",
@@ -9482,7 +9487,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "bb3a06612cea7d25b04efabda8659ed8a71b66859bab279f9b4e8a1e5dbadff3"
+      "sha256": "5394603956c3ec34e8377f82a7f493d7c029f0db1d99b236a0e024fd619fe869"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9862,7 +9867,7 @@
     {
       "path": "tests/box_access.mjs",
       "mode": "0000644",
-      "sha256": "fcad6c578c2d8698d6ad93fe04f500734d589013590f006910f1bc33fc908642"
+      "sha256": "911a764f72976298daa17855acb836d0ada3215b480961ae8607e1fc3634f882"
     },
     {
       "path": "tests/box_auth_check.mjs",
@@ -9932,7 +9937,7 @@
     {
       "path": "tests/box_sync_scope_report.mjs",
       "mode": "0000644",
-      "sha256": "010525c500aa1d5133f85a1a2ea7c23e9a680b08493a6f3b78c69a5108501468"
+      "sha256": "4b1df674e2e53ce9d521bab3c43c2b3959dee7daa51b97dfa9b23c20e2a41f94"
     },
     {
       "path": "tests/box_task_scope.mjs",

package/clients/bongos-client/README.md

@@ -5,7 +5,7 @@ A **generated**, zero-dependency typed client for the Bongos API — produced fr
 by hand; it regenerates when the spec changes, so it can never drift from the routes.
 
 - API version: **v1** (served at `/api/bongos/v1`)
-- 360 operations across 55 resource groups
+- 362 operations across 55 resource groups
 
 ## Use it from your project
 

package/clients/bongos-client/bongos-client.global.js

@@ -205,6 +205,10 @@ function createClient(opts = {}) {
       postBoxTerminal: (args) => request("POST", "/box/terminal", { hasBody: true }, args),
       // POST /box/version — rank: any-builder — POST /box/version
       postBoxVersion: (args) => request("POST", "/box/version", { hasBody: true }, args),
+      // GET /box/widen — rank: any-builder — GET /box/widen
+      getBoxWiden: (args) => request("GET", "/box/widen", { hasBody: false }, args),
+      // POST /box/widen — rank: any-builder — POST /box/widen
+      postBoxWiden: (args) => request("POST", "/box/widen", { hasBody: true }, args),
     },
     "boxes": {
       // GET /boxes — rank: metic+archon — GET /boxes

package/clients/bongos-client/index.cjs

@@ -204,6 +204,10 @@ function createClient(opts = {}) {
       postBoxTerminal: (args) => request("POST", "/box/terminal", { hasBody: true }, args),
       // POST /box/version — rank: any-builder — POST /box/version
       postBoxVersion: (args) => request("POST", "/box/version", { hasBody: true }, args),
+      // GET /box/widen — rank: any-builder — GET /box/widen
+      getBoxWiden: (args) => request("GET", "/box/widen", { hasBody: false }, args),
+      // POST /box/widen — rank: any-builder — POST /box/widen
+      postBoxWiden: (args) => request("POST", "/box/widen", { hasBody: true }, args),
     },
     "boxes": {
       // GET /boxes — rank: metic+archon — GET /boxes

package/clients/bongos-client/index.d.ts

@@ -29,6 +29,7 @@ export interface GetBoxMeResponse { box: unknown; open_intent: unknown; cost: un
 export interface GetBoxSourceAccessResponse { scope: unknown; mode: unknown; sparse_paths: unknown; repo_url: unknown; credential: unknown; configured: unknown; separate_starter_repo: unknown; expires_at: unknown; ttl_seconds: unknown; guidance: unknown }
 export interface GetBoxSshKeyResponse { keys: unknown }
 export interface GetBoxTerminalResponse { state: unknown; url: unknown; credential: unknown; hint: unknown; warming_up?: boolean; terminal_at?: unknown }
+export interface GetBoxWidenResponse { widen_paths: unknown; admitted: unknown; ignored: unknown; max: unknown }
 export interface GetBoxesResponse { boxes: unknown }
 export interface GetBuildersDirectoryResponse { builders: unknown }
 export interface GetBuildersIdActiveClaimsResponse { builder_id: unknown; claims: unknown; stale_hours: unknown; stale_hours_source: unknown }
@@ -222,6 +223,8 @@ export interface PostBoxTerminalRequest { url: string; credential?: string }
 export interface PostBoxTerminalResponse { ok: boolean; state: unknown }
 export interface PostBoxVersionRequest { sha: string; committed_at?: string }
 export interface PostBoxVersionResponse { ok: boolean; state: unknown }
+export interface PostBoxWidenRequest { add?: unknown[]; remove?: unknown[]; clear?: boolean }
+export interface PostBoxWidenResponse { ok: boolean; widen_paths: unknown; admitted: unknown; ignored: unknown; max: unknown }
 export interface PostBoxesBuilderIdCloseResponse { ok: boolean; queued: unknown; action: unknown; state: unknown; message: unknown }
 export interface PostClaimsBatchReleaseRequest { claim_ids: unknown[]; force?: boolean }
 export interface PostClaimsBatchReleaseResponse { released: unknown; failures: unknown }
@@ -536,6 +539,10 @@ export interface BongosClient {
     postBoxTerminal(args: RequestArgs & { body: PostBoxTerminalRequest }): Promise<PostBoxTerminalResponse>;
     /** POST /box/version — rank: any-builder */
     postBoxVersion(args: RequestArgs & { body: PostBoxVersionRequest }): Promise<PostBoxVersionResponse>;
+    /** GET /box/widen — rank: any-builder */
+    getBoxWiden(args?: RequestArgs): Promise<GetBoxWidenResponse>;
+    /** POST /box/widen — rank: any-builder */
+    postBoxWiden(args?: RequestArgs & { body?: PostBoxWidenRequest }): Promise<PostBoxWidenResponse>;
   };
   "boxes": {
     /** GET /boxes — rank: metic+archon */

package/clients/bongos-client/index.mjs

@@ -201,6 +201,10 @@ export function createClient(opts = {}) {
       postBoxTerminal: (args) => request("POST", "/box/terminal", { hasBody: true }, args),
       // POST /box/version — rank: any-builder — POST /box/version
       postBoxVersion: (args) => request("POST", "/box/version", { hasBody: true }, args),
+      // GET /box/widen — rank: any-builder — GET /box/widen
+      getBoxWiden: (args) => request("GET", "/box/widen", { hasBody: false }, args),
+      // POST /box/widen — rank: any-builder — POST /box/widen
+      postBoxWiden: (args) => request("POST", "/box/widen", { hasBody: true }, args),
     },
     "boxes": {
       // GET /boxes — rank: metic+archon — GET /boxes

package/docs/api/openapi.json

@@ -2275,6 +2275,91 @@
         ]
       }
     },
+    "/box/widen": {
+      "get": {
+        "operationId": "get_box_widen",
+        "tags": [
+          "box"
+        ],
+        "summary": "GET /box/widen",
+        "description": "GET /box/widen — the caller's own recorded widen set (task 1003087). rank: any authenticated builder, own resource. Reports what is STORED plus what is currently ADMITTED, because those differ whenever a request sits outside the builder's rank scope — showing only the stored list would let a Xenos believe a widen took effect that the fetch quietly drops.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/dev-box/routes/box.js",
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/GetBoxWidenResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/BadRequest"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      },
+      "post": {
+        "operationId": "post_box_widen",
+        "tags": [
+          "box"
+        ],
+        "summary": "POST /box/widen",
+        "description": "POST /box/widen — record extra sparse-checkout directories that must SURVIVE the */10 source-fetch (task 1003087, idea 1000793). rank: any authenticated builder, OWN box (builder_id-scoped in SQL, so no id from the body can point this at someone else's box). Deliberately NOT allowBoxScope. The on-box crons read source-access with a box-scoped session (ADR 0053); this is a WRITE that changes what the box pulls forever after, so it takes the builder's own session — the same posture that keeps a stolen box token from re-scoping the checkout it was stolen from. add/remove are applied to the stored set and the result is re-normalized, so the endpoint is idempotent: widening twice is not an error, and neither is removing something that was never there. A path outside the caller's rank scope is ACCEPTED into storage but reported in `ignored` rather than refused. That is the honest shape: rank can change, and a builder promoted to Metic should find the widen they asked for as a Xenos simply start working, instead of having been silently discarded months earlier. What it can never do is take effect early — admissibleWidenPaths is re-evaluated against the LIVE rank on every single fetch.\n\n**Rank:** `any-builder` — Any authenticated builder (row-level ownership enforced in-handler).",
+        "x-rank": "any-builder",
+        "x-source": "modules/dev-box/routes/box.js",
+        "requestBody": {
+          "required": false,
+          "content": {
+            "application/json": {
+              "schema": {
+                "$ref": "#/components/schemas/PostBoxWidenRequest"
+              }
+            }
+          },
+          "x-validated": true
+        },
+        "responses": {
+          "200": {
+            "description": "Success.",
+            "content": {
+              "application/json": {
+                "schema": {
+                  "$ref": "#/components/schemas/PostBoxWidenResponse"
+                }
+              }
+            }
+          },
+          "400": {
+            "$ref": "#/components/responses/ValidationFailed"
+          },
+          "401": {
+            "$ref": "#/components/responses/Unauthorized"
+          },
+          "403": {
+            "$ref": "#/components/responses/Forbidden"
+          }
+        },
+        "security": [
+          {
+            "builderSession": []
+          }
+        ]
+      }
+    },
     "/boxes": {
       "get": {
         "operationId": "get_boxes",
@@ -16801,6 +16886,21 @@
           "hint"
         ]
       },
+      "GetBoxWidenResponse": {
+        "type": "object",
+        "properties": {
+          "widen_paths": {},
+          "admitted": {},
+          "ignored": {},
+          "max": {}
+        },
+        "required": [
+          "widen_paths",
+          "admitted",
+          "ignored",
+          "max"
+        ]
+      },
       "GetBoxesResponse": {
         "type": "object",
         "properties": {
@@ -19429,6 +19529,40 @@
           "state"
         ]
       },
+      "PostBoxWidenRequest": {
+        "type": "object",
+        "properties": {
+          "add": {
+            "type": "array"
+          },
+          "remove": {
+            "type": "array"
+          },
+          "clear": {
+            "type": "boolean"
+          }
+        },
+        "additionalProperties": false
+      },
+      "PostBoxWidenResponse": {
+        "type": "object",
+        "properties": {
+          "ok": {
+            "type": "boolean"
+          },
+          "widen_paths": {},
+          "admitted": {},
+          "ignored": {},
+          "max": {}
+        },
+        "required": [
+          "ok",
+          "widen_paths",
+          "admitted",
+          "ignored",
+          "max"
+        ]
+      },
       "PostBoxesBuilderIdCloseResponse": {
         "type": "object",
         "properties": {
@@ -22806,9 +22940,9 @@
       "description": "A required dependency/feature is not configured or is temporarily down."
     }
   },
-  "x-endpoint-count": 360,
-  "x-schema-count": 398,
+  "x-endpoint-count": 362,
+  "x-schema-count": 401,
   "x-undocumented-bodies": 9,
-  "x-response-schemas": 268,
+  "x-response-schemas": 270,
   "x-generated-by": "scripts/gds/gen-api-docs.js"
 }

package/docs/api-reference.md

@@ -2,7 +2,7 @@
 
 # Bongos API reference
 
-> **Generated from the live route files** — the route file is authoritative. 360 endpoints across 58 route files.
+> **Generated from the live route files** — the route file is authoritative. 362 endpoints across 58 route files.
 > Machine-readable spec: [`docs/api/openapi.json`](api/openapi.json) (OpenAPI 3.1). Rendered docs site: **`/docs`** (e.g. `cloudbongos.com/docs`).
 
 Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>.md)): `public` < `any-builder` < `metic+archon` < `archon`.
@@ -81,7 +81,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | POST | `/api/bongos/blockers/:id/link` | `metic+archon` | `task_id` | Link an existing blocker to a task. |
 | POST | `/api/bongos/blockers/:id/resolve` | `metic+archon` | `resolution_note` | Resolve. |
 
-## `box` (18)
+## `box` (20)
 
 | Method | Path | Rank | Body | Description |
 |---|---|---|---|---|
@@ -103,6 +103,8 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/box/terminal` | `any-builder` | — | GET /box/terminal — the caller reads their box's web-terminal URL + credential (the Chromebook on-ramp, ADR 0038: ttyd behind a Cloudflar… |
 | POST | `/api/bongos/box/terminal` | `any-builder` | `url`, `credential` | POST /box/terminal — the box publishes its current web-terminal URL + the per-box basic-auth credential. |
 | POST | `/api/bongos/box/version` | `any-builder` | `sha`, `committed_at` | POST /box/version — the box reports its /workspace HEAD commit so the server can flag a stale box (idea 332 / task 1316, ADR 0072). |
+| GET | `/api/bongos/box/widen` | `any-builder` | — | GET /box/widen — the caller's own recorded widen set (task 1003087). |
+| POST | `/api/bongos/box/widen` | `any-builder` | `add`, `remove`, `clear` | POST /box/widen — record extra sparse-checkout directories that must SURVIVE the */10 source-fetch (task 1003087, idea 1000793). |
 
 ## `boxes` (4)
 

package/docs/module-api-changelog.md

@@ -1741,5 +1741,7 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.644 with no explicit bump. run 34511775606. (task 1002620)
   1.19.646 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.645 with no explicit bump. run 34512629504. (task 1002620)
+  1.19.647 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.646 with no explicit bump. run 34515733973. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/migrations/core_237_box_widen_paths.sql

@@ -0,0 +1,40 @@
+-- core_237_box_widen_paths.sql — let a builder's own sparse-checkout widening
+-- survive the */10 source-fetch tick (task 1003087, goal 1000095, idea 1000793).
+--
+-- THE BUG THIS EXISTS FOR. The box's source-fetch cron re-applies the
+-- SERVER-COMPUTED sparse set every ~10 minutes. A builder who runs
+-- `git sparse-checkout add <path>` to see code their task scope did not pull gets
+-- it deleted out from under them on the next tick — including WHILE A COMMAND IS
+-- RUNNING. A live test suite died mid-run with MODULE_NOT_FOUND that read exactly
+-- like a code bug. It also breaks gen-repo-map, whose output is TREE-DEPENDENT:
+-- a sparse tree regenerates different nested CLAUDE.md symbol blocks than CI's
+-- full tree, so a box-committed regen reds CI's freshness gate (learning 1000192;
+-- it stranded PR #254 until the tree was widened).
+--
+-- WHY THE FIX LIVES IN THE DATABASE AND NOT IN THE FETCH SCRIPT. The obvious fix
+-- is "make box-source-fetch.sh union the builder's additions". It cannot be done
+-- there from this repo: the fetch script is INSTANCE-owned, not shipped by the
+-- neutral core (ADR 0150). More importantly it would not work — the cron asks the
+-- SERVER for the set on every tick, so anything the script remembers locally is
+-- one `git sparse-checkout set` away from being overwritten anyway. Recording the
+-- widening server-side is what makes it tick-surviving: the union is computed in
+-- GET /box/source-access, so EVERY fetch — cron included — already returns it,
+-- and no instance-owned file has to change.
+--
+-- ONE COLUMN, NOT A TABLE. A widen set is small (capped in box-access.js), has no
+-- attributes of its own, and is meaningless apart from its box — the same shape
+-- as the existing array-ish per-box state on this table. A join table would buy
+-- nothing and cost a query on the hot source-fetch path.
+--
+-- NOT AN AUTHORITY GRANT. This column widens what is MATERIALIZED on the box, not
+-- what the builder may author. The wall stays where ADR 0148 put it — goal-scope
+-- -check against the module globs, not what happens to be on disk — and
+-- box-access.js admits a widen path only when the builder's RANK scope already
+-- reaches it, so a Xenos cannot widen past the starter surface. Empty default, so
+-- every existing box is unchanged until its owner asks for something.
+
+ALTER TABLE builder_boxes
+  ADD COLUMN IF NOT EXISTS widen_paths text[] NOT NULL DEFAULT '{}';
+
+COMMENT ON COLUMN builder_boxes.widen_paths IS
+  'Builder-requested extra sparse-checkout directories, unioned into the server-computed set on every source fetch so they survive the */10 cron (task 1003087). Admitted only within the builder''s rank scope — see modules/dev-box/box-access.js admissibleWidenPaths.';

package/modules/dev-box/app/src/vendor/bongos-client.cjs

@@ -204,6 +204,10 @@ function createClient(opts = {}) {
       postBoxTerminal: (args) => request("POST", "/box/terminal", { hasBody: true }, args),
       // POST /box/version — rank: any-builder — POST /box/version
       postBoxVersion: (args) => request("POST", "/box/version", { hasBody: true }, args),
+      // GET /box/widen — rank: any-builder — GET /box/widen
+      getBoxWiden: (args) => request("GET", "/box/widen", { hasBody: false }, args),
+      // POST /box/widen — rank: any-builder — POST /box/widen
+      postBoxWiden: (args) => request("POST", "/box/widen", { hasBody: true }, args),
     },
     "boxes": {
       // GET /boxes — rank: metic+archon — GET /boxes

package/modules/dev-box/box-access.js

@@ -254,6 +254,117 @@ function sparsePathsForScopeKeys(scopeKeys, moduleScopeMap) {
   return [...base, ...extra];
 }
 
+// ---------------------------------------------------------------------------
+// PURE: builder-requested WIDENING (task 1003087 / idea 1000793)
+// ---------------------------------------------------------------------------
+
+// A builder sometimes needs a directory their task scope did not pull — to run
+// the full suite, to read a caller, to regenerate a TREE-DEPENDENT artifact. The
+// obvious move, `git sparse-checkout add <path>`, does not survive: the */10
+// source-fetch cron re-applies the SERVER-computed set and deletes the addition,
+// including WHILE A COMMAND IS RUNNING (a live suite died mid-run with
+// MODULE_NOT_FOUND that read exactly like a code bug; a box-committed
+// gen-repo-map regen off a narrow tree reds CI's freshness gate — learning
+// 1000192, which stranded PR #254).
+//
+// So the widening is recorded SERVER-side and unioned in HERE, which is what
+// makes it tick-surviving: the cron asks this endpoint for the set on every tick,
+// so it gets the union too. Nothing in the instance-owned fetch script changes —
+// which matters, because the neutral core does not ship it (ADR 0150).
+
+// Bounds. Small on purpose: this is an escape hatch for a handful of dirs, not a
+// second scope system. Over the cap the extras are dropped, not an error — a
+// truncated widen still fetches, and failing the source pull over it would be a
+// far worse trade than materializing less.
+const MAX_WIDEN_PATHS = 24;
+const MAX_WIDEN_PATH_LEN = 200;
+
+// withinAny(p, roots) — is p one of roots, or underneath one? Cone mode
+// materializes a directory and everything below it, so "already covered" and
+// "inside the allowed surface" are the same ancestor walk.
+function withinAny(p, roots) {
+  let q = p;
+  for (;;) {
+    if (roots.includes(q)) return true;
+    const cut = q.lastIndexOf('/');
+    if (cut < 0) return false;
+    q = q.slice(0, cut);
+  }
+}
+
+// normalizeWidenPath — repo-relative POSIX directory, or null when it is not one.
+//
+// This is a path that reaches `git sparse-checkout set` on a box, so it is
+// validated as INPUT rather than trusted: absolute paths, Windows drive letters,
+// '..' traversal and empty segments are all refused rather than normalized away,
+// because "cleaned up into something that still works" is how a traversal becomes
+// a shrug. Backslashes are folded to '/' first so a Windows-typed path is judged
+// on what it means, not on its separator.
+function normalizeWidenPath(raw) {
+  if (typeof raw !== 'string') return null;
+  // BACKSLASH by char code, not as a literal: this file is edited through
+  // tooling that has silently collapsed a doubled backslash before, and a
+  // separator fold that quietly stops folding is invisible until a Windows
+  // path slips through as one long segment.
+  const BACKSLASH = String.fromCharCode(92);
+  let p = raw.trim().split(BACKSLASH).join('/');
+  while (p.startsWith('./')) p = p.slice(2);
+  p = p.replace(/\/+/g, '/').replace(/\/+$/, '');
+  if (!p || p === '.' || p.length > MAX_WIDEN_PATH_LEN) return null;
+  if (p.startsWith('/') || /^[A-Za-z]:/.test(p)) return null;
+  const segs = p.split('/');
+  if (!segs.every((s) => s && s !== '.' && s !== '..' && /^[A-Za-z0-9._-]+$/.test(s))) return null;
+  return p;
+}
+
+// admissibleWidenPaths — the widen requests this builder's RANK actually permits,
+// normalized, deduped, capped and sorted.
+//
+// THIS IS THE SECURITY BOUNDARY OF THE FEATURE, so it is stated plainly: widening
+// changes what is MATERIALIZED on a box, and rank decides how much of the repo a
+// box may hold at all (ADR 0031 section 9.2 — 'full' for Metic+, the 'starter'
+// surface below that). Honoring an arbitrary widen would hand a Xenos the whole
+// tree through a convenience flag, which is a rank escalation dressed as
+// ergonomics. So:
+//   - a builder whose RANK scope is 'full' may widen anywhere (they are already
+//     entitled to the entire repo; the widen only decides what gets pulled);
+//   - anyone else may widen only INSIDE the starter surface. That is not a null
+//     grant: a task-scoped box is BASE union its modules, which is NARROWER than
+//     starter, so this is exactly the room to climb back to what their rank
+//     already allowed — and no further.
+// The authoring wall is untouched either way. What a builder may CHANGE is still
+// goal-scope-check against the module globs, never what happens to be on disk
+// (ADR 0148).
+function admissibleWidenPaths(widenPaths, rank) {
+  const unrestricted = boxScopeForRank(rank) === 'full';
+  const out = [];
+  const seen = new Set();
+  for (const raw of Array.isArray(widenPaths) ? widenPaths : []) {
+    const p = normalizeWidenPath(raw);
+    if (!p || seen.has(p)) continue;
+    if (!unrestricted && !withinAny(p, STARTER_SPARSE_PATHS)) continue;
+    seen.add(p);
+    out.push(p);
+    if (out.length >= MAX_WIDEN_PATHS) break;
+  }
+  return out.sort();
+}
+
+// withWidenPaths — union admitted widen dirs into a computed sparse set, skipping
+// any the set already covers (cone mode pulls a dir and everything under it, so
+// adding 'scripts/gds' when 'scripts' is present is noise in the git command and
+// noise in the box's scope readout). A null set is the 'full' clone — there is
+// nothing to widen into, so it passes through untouched.
+function withWidenPaths(sparsePaths, admitted) {
+  if (!Array.isArray(sparsePaths) || !admitted || admitted.length === 0) return sparsePaths;
+  const out = [...sparsePaths];
+  for (const dir of admitted) {
+    if (withinAny(dir, out)) continue;
+    out.push(dir);
+  }
+  return out;
+}
+
 // ---------------------------------------------------------------------------
 // PURE: the per-fetch access decision (consumed by GET /box/source-access)
 // ---------------------------------------------------------------------------
@@ -295,7 +406,7 @@ function sparsePathsForScopeKeys(scopeKeys, moduleScopeMap) {
 //   { allowed:false, reason:'BUILDER_INACTIVE' }
 //   { allowed:false, reason:'INSUFFICIENT_RANK', required, actual }
 //   { allowed:true,  scope, spec }
-function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR, scopeKeys, hasActiveClaims, moduleScopeMap } = {}) {
+function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR, scopeKeys, hasActiveClaims, moduleScopeMap, widenPaths } = {}) {
   if (status && status !== 'active') {
     return { allowed: false, reason: 'BUILDER_INACTIVE' };
   }
@@ -307,23 +418,32 @@ function decideSourceAccess({ rank, status, floor = DEFAULT_PROVISION_FLOOR, sco
       actual: rank ?? null,
     };
   }
+  // The builder's own widening, narrowed to what their rank already reaches
+  // (task 1003087). Computed once here so every sparse branch below unions the
+  // SAME set — a widen that applied to one scope and not another would be a
+  // surprise that only surfaces when a claim changes.
+  const widen = admissibleWidenPaths(widenPaths, rank);
+
   // Claim-driven task scope (present → the box asks for exactly its work's code).
   if (Array.isArray(scopeKeys)) {
     if (scopeKeys.length > 0) {
-      const sparsePaths = sparsePathsForScopeKeys(scopeKeys, moduleScopeMap);
+      const sparsePaths = withWidenPaths(sparsePathsForScopeKeys(scopeKeys, moduleScopeMap), widen);
       return { allowed: true, scope: 'task', spec: { scope: 'task', mode: 'sparse', sparsePaths } };
     }
     // Empty. A builder mid-claim whose goals declare no wall gets the rank scope,
     // NOT a stripped box — the planning gap is not theirs to pay for.
     if (!hasActiveClaims) {
-      const sparsePaths = sparsePathsForScopeKeys([], moduleScopeMap);
+      const sparsePaths = withWidenPaths(sparsePathsForScopeKeys([], moduleScopeMap), widen);
       return { allowed: true, scope: 'base', spec: { scope: 'base', mode: 'sparse', sparsePaths } };
     }
   }
   // No claim signal (no lifecycle port on this instance), or claims with an
   // undeclared goal wall: the pre-ADR-0148 rank fallback.
   const scope = boxScopeForRank(rank);
-  return { allowed: true, scope, spec: cloneSpecForScope(scope) };
+  const spec = cloneSpecForScope(scope);
+  // 'full' carries sparsePaths null (the whole repo) — withWidenPaths passes it
+  // through, because there is no sparse set to widen INTO.
+  return { allowed: true, scope, spec: { ...spec, sparsePaths: withWidenPaths(spec.sparsePaths, widen) } };
 }
 
 // scopeMetadata — PURE. The credential-FREE projection of a source-access
@@ -470,6 +590,10 @@ module.exports = {
   boxCanHoldSource,
   cloneSpecForScope,
   sparsePathsForScopeKeys, // ADR 0148 — BASE ∪ the claims' module dirs (cone-mode)
+  MAX_WIDEN_PATHS,         // task 1003087 — the builder-widening cap
+  normalizeWidenPath,      // task 1003087 — repo-relative dir, or null
+  admissibleWidenPaths,    // task 1003087 — the widen requests this RANK permits
+  withWidenPaths,          // task 1003087 — union a widen set into a sparse set
   scopeMetadata, // BV1.R100 — credential-free projection for GET /box/scope
   // pure — decisions
   decideSourceAccess,

package/modules/dev-box/boxes.js

@@ -397,6 +397,26 @@ function decideEnsureAction({ boxState, rank, status, blocked = false, floor = D
 // DB helpers (async). Each takes the pg pool (or a client mid-transaction).
 // ---------------------------------------------------------------------------
 
+// setBoxWidenPaths — replace a box row's builder-requested widen set (task
+// 1003087). Whole-set replace rather than add/remove SQL: the set is tiny and
+// capped, the caller has already normalized and rank-filtered it, and a
+// read-modify-write in one statement keeps two concurrent widens from
+// interleaving into a half-applied list.
+//
+// Returns the stored array, or null when the builder has no box row — the
+// caller turns that into a 404 rather than silently creating one, because a
+// widen with no box to apply it to is a request that has not happened yet.
+async function setBoxWidenPaths(db, builderId, paths) {
+  const { rows } = await db.query(
+    `UPDATE builder_boxes
+        SET widen_paths = $2::text[], updated_at = now()
+      WHERE builder_id = $1
+      RETURNING widen_paths`,
+    [builderId, Array.isArray(paths) ? paths : []]
+  );
+  return rows[0] ? rows[0].widen_paths : null;
+}
+
 async function getBoxByBuilderId(db, builderId) {
   const { rows } = await db.query(
     `SELECT * FROM builder_boxes WHERE builder_id = $1`,
@@ -891,6 +911,7 @@ module.exports = {
   decideEnsureAction,
   // db
   getBoxByBuilderId,
+  setBoxWidenPaths,
   ensureBoxRow,
   listBoxes,
   recordEvent,

package/modules/dev-box/routes/box.js

@@ -480,8 +480,16 @@ module.exports = function buildBoxRouter() {
           hasActiveClaims = undefined;
         }
       }
-      const decision = boxAccess.decideSourceAccess({ rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: api.moduleScopeMap });
+      // Read the box BEFORE deciding: its widen_paths are an INPUT to the sparse
+      // set now (task 1003087). A builder-requested directory is unioned in here,
+      // which is what makes it survive the */10 cron — the cron re-asks THIS
+      // endpoint every tick, so the union comes back with it instead of being
+      // deleted by the next `git sparse-checkout set`.
       const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
+      const decision = boxAccess.decideSourceAccess({
+        rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: api.moduleScopeMap,
+        widenPaths: box ? box.widen_paths : null,
+      });
       const auditDeny = (reason, extra) =>
         box && boxAccess.recordSourceEvent(pool, {
           box, builderId: req.builder.id, event: 'source_deny',
@@ -598,7 +606,13 @@ module.exports = function buildBoxRouter() {
           hasActiveClaims = undefined;
         }
       }
-      const decision = boxAccess.decideSourceAccess({ rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: api.moduleScopeMap });
+      // Same widen input as the real fetch — this readout exists precisely so it
+      // cannot drift from what the box will actually hold.
+      const scopeBox = await boxes.getBoxByBuilderId(pool, req.builder.id);
+      const decision = boxAccess.decideSourceAccess({
+        rank, status, scopeKeys, hasActiveClaims, moduleScopeMap: api.moduleScopeMap,
+        widenPaths: scopeBox ? scopeBox.widen_paths : null,
+      });
       if (!decision.allowed) {
         return res.fail('SOURCE_ACCESS_REVOKED', 403, {
           reason: decision.reason,
@@ -753,6 +767,98 @@ module.exports = function buildBoxRouter() {
     }
   });
 
+  // GET /box/widen — the caller's own recorded widen set (task 1003087).
+  // rank: any authenticated builder, own resource. Reports what is STORED plus
+  // what is currently ADMITTED, because those differ whenever a request sits
+  // outside the builder's rank scope — showing only the stored list would let a
+  // Xenos believe a widen took effect that the fetch quietly drops.
+  router.get('/box/widen', auth.requireBuilder, async (req, res) => {
+    try {
+      const builder = await gdsDb.getBuilderById(req.builder.id);
+      const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
+      if (!box) return res.fail('no_box', 404, { message: 'no dev box for this builder' });
+      const stored = Array.isArray(box.widen_paths) ? box.widen_paths : [];
+      const admitted = boxAccess.admissibleWidenPaths(stored, builder ? builder.rank : null);
+      res.json({
+        widen_paths: stored,
+        admitted,
+        ignored: stored.filter((p) => !admitted.includes(boxAccess.normalizeWidenPath(p))),
+        max: boxAccess.MAX_WIDEN_PATHS,
+      });
+    } catch (err) {
+      log.error('[gds] GET /box/widen', err);
+      res.fail('widen_read_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
+  // POST /box/widen — record extra sparse-checkout directories that must SURVIVE
+  // the */10 source-fetch (task 1003087, idea 1000793). rank: any authenticated
+  // builder, OWN box (builder_id-scoped in SQL, so no id from the body can point
+  // this at someone else's box).
+  //
+  // Deliberately NOT allowBoxScope. The on-box crons read source-access with a
+  // box-scoped session (ADR 0053); this is a WRITE that changes what the box
+  // pulls forever after, so it takes the builder's own session — the same posture
+  // that keeps a stolen box token from re-scoping the checkout it was stolen from.
+  //
+  // add/remove are applied to the stored set and the result is re-normalized, so
+  // the endpoint is idempotent: widening twice is not an error, and neither is
+  // removing something that was never there.
+  //
+  // A path outside the caller's rank scope is ACCEPTED into storage but reported
+  // in `ignored` rather than refused. That is the honest shape: rank can change,
+  // and a builder promoted to Metic should find the widen they asked for as a
+  // Xenos simply start working, instead of having been silently discarded months
+  // earlier. What it can never do is take effect early — admissibleWidenPaths is
+  // re-evaluated against the LIVE rank on every single fetch.
+  router.post('/box/widen', auth.requireBuilder, async (req, res) => {
+    if (validateOrRespond(req, res, {
+      add: { type: 'array' },
+      remove: { type: 'array' },
+      clear: { type: 'boolean' },
+    })) return;
+    try {
+      const box = await boxes.getBoxByBuilderId(pool, req.builder.id);
+      if (!box) return res.fail('no_box', 404, { message: 'no dev box for this builder' });
+      const builder = await gdsDb.getBuilderById(req.builder.id);
+
+      const current = Array.isArray(box.widen_paths) ? box.widen_paths : [];
+      const next = new Set(req.body && req.body.clear === true ? [] : current);
+
+      const rejected = [];
+      for (const raw of Array.isArray(req.body && req.body.add) ? req.body.add : []) {
+        const p = boxAccess.normalizeWidenPath(raw);
+        if (!p) { rejected.push(String(raw).slice(0, 120)); continue; }
+        next.add(p);
+      }
+      for (const raw of Array.isArray(req.body && req.body.remove) ? req.body.remove : []) {
+        const p = boxAccess.normalizeWidenPath(raw);
+        if (p) next.delete(p);
+      }
+      if (rejected.length) {
+        return res.fail('bad_widen_path', 400, {
+          rejected,
+          message: 'a widen path must be a repo-relative directory: no absolute paths, no "..", no drive letters',
+        });
+      }
+
+      const stored = [...next].sort().slice(0, boxAccess.MAX_WIDEN_PATHS);
+      const saved = await boxes.setBoxWidenPaths(pool, req.builder.id, stored);
+      if (saved === null) return res.fail('no_box', 404, { message: 'no dev box for this builder' });
+      const admitted = boxAccess.admissibleWidenPaths(saved, builder ? builder.rank : null);
+      res.json({
+        ok: true,
+        widen_paths: saved,
+        admitted,
+        ignored: saved.filter((p) => !admitted.includes(p)),
+        max: boxAccess.MAX_WIDEN_PATHS,
+      });
+    } catch (err) {
+      log.error('[gds] POST /box/widen', err);
+      res.fail('widen_failed', { status: 500, message: 'internal error' });
+    }
+  });
+
   // GET /box/authorized-keys — the box pulls its builder's authorized_keys.
   // rank: any authenticated builder (own resource) — but the ALLOW/DENY is decided
   // INSIDE from the caller's LIVE rank+status (boxAccess.decideSourceAccess), NOT a

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.646",
+  "version": "1.19.647",
   "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/scripts/gds/box-sync.js

@@ -15,6 +15,18 @@
 //
 // Usage:  node scripts/gds/box-sync.js            # re-fetch now
 //         node scripts/gds/box-sync.js --dry-run  # print what it WOULD run
+//         node scripts/gds/box-sync.js --widen <dir>    # keep <dir> across ticks
+//         node scripts/gds/box-sync.js --unwiden <dir>  # stop keeping it
+//         node scripts/gds/box-sync.js --widen-list     # what is kept, and what is ignored
+//
+// WHY --widen EXISTS (task 1003087 / idea 1000793). `git sparse-checkout add`
+// does not survive: the */10 cron re-applies the SERVER-computed set and deletes
+// the addition, sometimes MID-COMMAND — a live test suite died with
+// MODULE_NOT_FOUND that read exactly like a code bug. --widen records the
+// directory server-side instead, so every fetch (the cron included) returns it
+// in the set and it stops being deleted. It is capped, and it can never widen
+// past what your RANK already reaches — a request outside it is stored but
+// reported as ignored rather than silently applied.
 
 const fs = require('node:fs');
 const path = require('node:path');
@@ -36,7 +48,78 @@ function resolveFetchScript(opts = {}) {
   try { return fs.existsSync(p) ? p : null; } catch { return null; }
 }
 
+// valueAfter(argv, flag) — the argument following a flag, or null. Kept tiny and
+// pure so the arg handling is testable without spawning anything.
+function valueAfter(argv, flag) {
+  const i = argv.indexOf(flag);
+  if (i < 0) return null;
+  const v = argv[i + 1];
+  return typeof v === 'string' && v && !v.startsWith('--') ? v : null;
+}
+
+// formatWidenReport — PURE. The lines to print for a /box/widen body. Reports
+// IGNORED entries loudly: a widen the server accepted into storage but will not
+// apply (because it is outside your rank scope) looks identical to a working one
+// unless it is said out loud, and a silently-inert widen is exactly the class of
+// bug this whole task is about.
+function formatWidenReport(body) {
+  if (!body || typeof body !== 'object' || Array.isArray(body)) {
+    return ['widen: could not read your widen set.'];
+  }
+  const kept = Array.isArray(body.widen_paths) ? body.widen_paths : [];
+  const ignored = Array.isArray(body.ignored) ? body.ignored : [];
+  const out = [];
+  out.push(kept.length
+    ? `widen: keeping ${kept.length} path(s) across ticks: ${kept.join(', ')}`
+    : 'widen: nothing kept — the fetch set is whatever your claim scope says.');
+  if (ignored.length) {
+    out.push(`widen: IGNORED (outside your rank scope, stored but not applied): ${ignored.join(', ')}`);
+  }
+  return out;
+}
+
+// The --widen family. Talks to the control plane, so it works off a box too —
+// unlike the fetch itself, the widen set is server state you can inspect and
+// edit from anywhere.
+async function runWiden(argv) {
+  const { apiCall } = require('./cli-lib');
+  const add = valueAfter(argv, '--widen');
+  const remove = valueAfter(argv, '--unwiden');
+  const clear = argv.includes('--widen-clear');
+  const listOnly = !add && !remove && !clear;
+
+  const r = listOnly
+    ? await apiCall('GET', '/api/gds/box/widen')
+    : await apiCall('POST', '/api/gds/box/widen', {
+      ...(add ? { add: [add] } : {}),
+      ...(remove ? { remove: [remove] } : {}),
+      ...(clear ? { clear: true } : {}),
+    });
+
+  if (!r || (r.status !== 200 && r.status !== 201)) {
+    const code = r && r.data && r.data.error ? r.data.error : `HTTP ${r ? r.status : '?'}`;
+    if (code === 'no_box') {
+      console.error('widen: you have no dev box — there is nothing to widen. Provision one first.');
+    } else if (code === 'bad_widen_path') {
+      const bad = r.data && r.data.rejected ? r.data.rejected.join(', ') : '';
+      console.error(`widen: refused ${bad} — give a repo-relative DIRECTORY (no leading /, no "..").`);
+    } else {
+      console.error(`widen: failed (${code}).`);
+    }
+    return 1;
+  }
+  for (const line of formatWidenReport(r.data)) console.log(line);
+  if (!listOnly) console.log('widen: run `box-sync` (no flags) to apply it to the checkout now.');
+  return 0;
+}
+
 function main(argv = process.argv.slice(2)) {
+  // The widen family is server state, not a fetch — handled before the on-a-box
+  // check, so it works from a laptop too.
+  if (argv.some((a) => a === '--widen' || a === '--unwiden' || a === '--widen-list' || a === '--widen-clear')) {
+    runWiden(argv).then((code) => process.exit(code), () => process.exit(1));
+    return;
+  }
   const dryRun = argv.includes('--dry-run') || argv.includes('-n');
   const script = resolveFetchScript();
   if (!script) {
@@ -130,4 +213,4 @@ async function reportScope() {
 
 if (require.main === module) main();
 
-module.exports = { resolveFetchScript, FETCH_SCRIPT, formatScopeReport };
+module.exports = { resolveFetchScript, FETCH_SCRIPT, formatScopeReport, formatWidenReport, valueAfter };

package/src/module-api.js

@@ -71,7 +71,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // there. scripts/gds/bump-version.js still rewrites the literal below; it appends
 // the entry to that file. Look for a version's history there, not here.
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.646'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.647'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/box_access.mjs

@@ -414,5 +414,160 @@ t('1003227 config/ is a cone-mode DIRECTORY entry (a file path aborts the whole
   }
 });
 
+// ---------------------------------------------------------------------------
+// task 1003087 / idea 1000793 — builder widening that SURVIVES the */10 tick
+//
+// The bug: the cron re-applies the server-computed sparse set, so a builder's
+// own `git sparse-checkout add` is deleted — sometimes mid-command (a live suite
+// died with MODULE_NOT_FOUND that read exactly like a code bug). The widen set is
+// therefore recorded server-side and unioned in HERE, on the same path the cron
+// asks every tick. These pin the two halves that matter: it actually widens, and
+// it cannot be used to climb past the rank scope.
+// ---------------------------------------------------------------------------
+
+console.log('\nnormalizeWidenPath — a repo-relative directory, or nothing:');
+
+t('accepts a plain repo-relative dir and strips the noise around it', () => {
+  assert.equal(access.normalizeWidenPath('docs'), 'docs');
+  assert.equal(access.normalizeWidenPath('  docs  '), 'docs');
+  assert.equal(access.normalizeWidenPath('./docs/'), 'docs');
+  assert.equal(access.normalizeWidenPath('docs//adr'), 'docs/adr');
+});
+
+t('folds a Windows separator rather than judging the path on it', () => {
+  const BS = String.fromCharCode(92);
+  assert.equal(access.normalizeWidenPath(`modules${BS}game`), 'modules/game');
+});
+
+t('REFUSES traversal, absolute paths and drive letters outright', () => {
+  // Refused, never "cleaned up into something that still works" — this string
+  // reaches `git sparse-checkout set` on a real box.
+  for (const bad of ['../etc', 'a/../../b', '/etc/passwd', 'C:/Windows', '..', '.', '']) {
+    assert.equal(access.normalizeWidenPath(bad), null, `${JSON.stringify(bad)} must be refused`);
+  }
+});
+
+t('refuses a non-string, an over-long path, and odd characters', () => {
+  assert.equal(access.normalizeWidenPath(null), null);
+  assert.equal(access.normalizeWidenPath(42), null);
+  assert.equal(access.normalizeWidenPath({}), null);
+  assert.equal(access.normalizeWidenPath('a'.repeat(500)), null);
+  assert.equal(access.normalizeWidenPath('modules/ga me'), null);
+  assert.equal(access.normalizeWidenPath('modules/rm -rf'), null);
+});
+
+console.log('\nadmissibleWidenPaths — rank is the ceiling, and it is the whole point:');
+
+t('a Metic (full rank scope) may widen anywhere', () => {
+  assert.deepEqual(access.admissibleWidenPaths(['modules/game'], 'metic'), ['modules/game']);
+  assert.deepEqual(access.admissibleWidenPaths(['migrations'], 'archon'), ['migrations']);
+});
+
+t('a Xenos may NOT widen past the starter surface — that would be rank escalation', () => {
+  // The security property of this feature stated as a test: if an arbitrary widen
+  // were honored, a convenience flag would hand a starter-scoped builder the whole
+  // repo, which is the rank gate defeated rather than a checkout preference.
+  assert.deepEqual(access.admissibleWidenPaths(['modules/game'], 'xenos'), []);
+  assert.deepEqual(access.admissibleWidenPaths(['migrations'], 'xenos'), []);
+  assert.deepEqual(access.admissibleWidenPaths(['modules/lifecycle'], 'thetes'), []);
+});
+
+t('a Xenos MAY widen INSIDE starter — a task box is narrower than their rank allows', () => {
+  // Not a null grant: task scope is BASE union modules, which is narrower than
+  // starter, so this is the room to climb back to what rank already permitted.
+  assert.deepEqual(access.admissibleWidenPaths(['docs/adr'], 'xenos'), ['docs/adr']);
+  assert.deepEqual(access.admissibleWidenPaths(['src/world'], 'xenos'), ['src/world']);
+});
+
+t('normalizes, dedupes and sorts, and drops the invalid without failing the rest', () => {
+  const got = access.admissibleWidenPaths(['./docs/', 'docs', '../etc', 'art'], 'metic');
+  assert.deepEqual(got, ['art', 'docs'], 'one invalid entry must not discard the valid ones');
+});
+
+t('is capped, so a widen set can never become a second scope system', () => {
+  const many = Array.from({ length: access.MAX_WIDEN_PATHS + 20 }, (_, i) => `docs/d${i}`);
+  assert.equal(access.admissibleWidenPaths(many, 'metic').length, access.MAX_WIDEN_PATHS);
+});
+
+t('a missing / non-array widen set is simply no widening', () => {
+  for (const v of [undefined, null, 'docs', 42, {}]) {
+    assert.deepEqual(access.admissibleWidenPaths(v, 'metic'), []);
+  }
+});
+
+console.log('\nwithWidenPaths — union into the computed set, without redundancy:');
+
+t('adds a dir the set does not already cover', () => {
+  assert.deepEqual(access.withWidenPaths(['src/bongos'], ['docs']), ['src/bongos', 'docs']);
+});
+
+t('skips a dir an ANCESTOR already covers — cone mode pulls the whole subtree', () => {
+  assert.deepEqual(access.withWidenPaths(['scripts'], ['scripts/gds']), ['scripts'],
+    'adding scripts/gds under scripts is noise in the git command and in the scope readout');
+});
+
+t('passes a null sparse set (the full clone) straight through', () => {
+  assert.equal(access.withWidenPaths(null, ['docs']), null,
+    'a full clone already holds everything — there is nothing to widen INTO');
+});
+
+t('an empty widen set returns the computed set untouched', () => {
+  const base = ['src/bongos', 'scripts'];
+  assert.deepEqual(access.withWidenPaths(base, []), base);
+});
+
+console.log('\ndecideSourceAccess — the widen reaches the spec the box actually fetches:');
+
+t('a task-scoped box gets its widen unioned into the sparse set', () => {
+  const d = access.decideSourceAccess({
+    rank: 'metic', status: 'active', scopeKeys: [], hasActiveClaims: false,
+    moduleScopeMap: {}, widenPaths: ['modules/game'],
+  });
+  assert.equal(d.allowed, true);
+  assert.ok(d.spec.sparsePaths.includes('modules/game'),
+    'the widen must reach the SPEC — this is the value the cron writes into sparse-checkout');
+});
+
+t('an out-of-scope widen never reaches the spec for a starter-scoped builder', () => {
+  const d = access.decideSourceAccess({
+    rank: 'xenos', status: 'active', scopeKeys: [], hasActiveClaims: false,
+    moduleScopeMap: {}, widenPaths: ['modules/game'],
+  });
+  assert.ok(!d.spec.sparsePaths.includes('modules/game'));
+});
+
+t('no widenPaths leaves every scope byte-identical to before the feature', () => {
+  const withArg = access.decideSourceAccess({
+    rank: 'metic', status: 'active', scopeKeys: [], hasActiveClaims: false, moduleScopeMap: {}, widenPaths: [],
+  });
+  const without = access.decideSourceAccess({
+    rank: 'metic', status: 'active', scopeKeys: [], hasActiveClaims: false, moduleScopeMap: {},
+  });
+  assert.deepEqual(withArg.spec, without.spec, 'a box that asked for nothing must fetch exactly what it always did');
+});
+
+t('a full-clone builder is unaffected — sparsePaths stays null', () => {
+  const d = access.decideSourceAccess({ rank: 'metic', status: 'active', widenPaths: ['docs'] });
+  assert.equal(d.spec.sparsePaths, null);
+  assert.equal(d.spec.mode, 'full');
+});
+
+t('widening cannot resurrect access for an inactive or below-floor builder', () => {
+  // The widen set is read from the box row, so it must not become a way around
+  // the ALLOW/DENY gate that runs before any scope is computed.
+  const inactive = access.decideSourceAccess({ rank: 'metic', status: 'inactive', widenPaths: ['docs'] });
+  assert.equal(inactive.allowed, false);
+  assert.equal(inactive.reason, 'BUILDER_INACTIVE');
+  assert.equal(inactive.spec, undefined);
+});
+
+t('every admitted widen path is still a DIRECTORY — cone mode aborts on a file', () => {
+  for (const p of access.admissibleWidenPaths(['docs/adr', 'src/world'], 'metic')) {
+    assert.ok(!p.endsWith('/'), `${p} must not carry a trailing slash`);
+    const last = p.split('/').pop();
+    assert.ok(!/\.[a-z0-9]+$/i.test(last), `${p} looks like a FILE — cone mode would abort the set`);
+  }
+});
+
 console.log(`\nbox_access.mjs: ${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);

package/tests/box_sync_scope_report.mjs

@@ -18,6 +18,8 @@ import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
 const { formatScopeReport } = require('../scripts/gds/box-sync.js');
+// task 1003087 — the widen read-out lives in the same module.
+const sync = require('../scripts/gds/box-sync.js');
 
 let passed = 0;
 let failed = 0;
@@ -77,5 +79,48 @@ t('an unknown scope value is reported verbatim rather than swallowed', () => {
   assert.match(joined({ scope: 'something-new', sparse_paths: [] }), /something-new/);
 });
 
+// ---------------------------------------------------------------------------
+// task 1003087 — the --widen read-out
+//
+// The whole feature exists because a widen that silently stops applying is
+// indistinguishable from one that works. So the report must say when the server
+// stored a path it will NOT apply (outside the caller's rank scope) — otherwise
+// this fix reintroduces its own bug one layer up.
+// ---------------------------------------------------------------------------
+
+const widenLines = (body) => sync.formatWidenReport(body).join('\n');
+
+t('an empty widen set says so plainly rather than printing nothing', () => {
+  assert.match(widenLines({ widen_paths: [], ignored: [] }), /nothing kept/i);
+});
+
+t('a kept set names the paths and the count', () => {
+  const out = widenLines({ widen_paths: ['docs', 'modules/game'], ignored: [] });
+  assert.match(out, /2 path/);
+  assert.match(out, /docs/);
+  assert.match(out, /modules\/game/);
+});
+
+t('an IGNORED path is called out loudly, not folded into the kept list', () => {
+  const out = widenLines({ widen_paths: ['docs', 'modules/game'], ignored: ['modules/game'] });
+  assert.match(out, /IGNORED/);
+  assert.match(out, /rank scope/i,
+    'the reason must be named — "stored but not applied" with no why is the silent failure again');
+});
+
+t('a garbage / missing body degrades to one honest line rather than throwing', () => {
+  for (const bad of [null, undefined, 'nope', 42, []]) {
+    assert.match(widenLines(bad), /could not read/i);
+  }
+});
+
+t('valueAfter reads the argument after a flag, and refuses the next flag as a value', () => {
+  assert.equal(sync.valueAfter(['--widen', 'docs'], '--widen'), 'docs');
+  assert.equal(sync.valueAfter(['--widen', '--dry-run'], '--widen'), null,
+    'consuming the next FLAG as a path would silently widen to something nobody typed');
+  assert.equal(sync.valueAfter(['--widen'], '--widen'), null);
+  assert.equal(sync.valueAfter([], '--widen'), null);
+});
+
 console.log(`\nbox_sync_scope_report.mjs: ${passed} passed, ${failed} failed`);
 process.exit(failed === 0 ? 0 : 1);