@bongos/core 1.19.120 → 1.19.122

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.120",
-  "core_contract": "1.19.120",
-  "source_commit": "aa2b9a92ce2984a3d4095b234ee2757098a5dd5a",
+  "core_version": "1.19.122",
+  "core_contract": "1.19.122",
+  "source_commit": "b8e5d6f6d62653ae415e42551ccb3c3c4e6c6f8a",
   "source_ref": "HEAD",
-  "built_at": "2026-08-14T20:14:51.707Z",
+  "built_at": "2026-08-14T21:05:40.247Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 302,
+    "docs_redacted": 303,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1239,
+    "functional_verbatim": 1244,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1562,
-  "tree_sha256": "84cbdf23f5f59fa6d3b2561ccc3fd1427ed42f8a1254864738f696d9ad68b431",
+  "file_count": 1568,
+  "tree_sha256": "03f0574ec4219110a53d6b8faaa4b93bcc96f0371d85d2a2e412d06d21364892",
   "files": [
     {
       "path": ".claude/skills/blocker-review/SKILL.md",
@@ -57,7 +57,7 @@
     {
       "path": ".claude/skills/builder-end/SKILL.md",
       "mode": "0000644",
-      "sha256": "feeb86dee8244ac7205cc39c67adedfa30544ba9c4b594fd029e7dc4d1ac7383"
+      "sha256": "79afe09324f8b9ac27e0500972af701020d502f4a2502323b821ff5234216f70"
     },
     {
       "path": ".claude/skills/builder-exit/SKILL.md",
@@ -367,7 +367,7 @@
     {
       "path": "clients/bongos-client/index.d.ts",
       "mode": "0000644",
-      "sha256": "167b7dcd701d2a23eec6dec515778e84cb262d95c070a5a749da642e5aada701"
+      "sha256": "eeb9b7bdf6054c92e3c605201c846d67ea20dd927355d2dc72479477c073fc7c"
     },
     {
       "path": "clients/bongos-client/index.mjs",
@@ -382,7 +382,7 @@
     {
       "path": "config/branding.neutral.json",
       "mode": "0000644",
-      "sha256": "48dc7ade227b763df5d9942930200042a3b76a7e1d00c281c43c2ab5304bf0da"
+      "sha256": "dc69c5c9e9041da9cd3c297c3e7c81c8311f42952524297d9f228cc1751af3ea"
     },
     {
       "path": "config/design-tokens.neutral.json",
@@ -1337,12 +1337,12 @@
     {
       "path": "docs/api-reference.md",
       "mode": "0000644",
-      "sha256": "06954a3b30e235ef61a316d4f7414a2eaf2c0f2d3fe1063698e800f3655d1675"
+      "sha256": "b9af2341b7017c6e21b53a611a824b8d3a59653f967e6f83218c9f1d25d0ff58"
     },
     {
       "path": "docs/api/openapi.json",
       "mode": "0000644",
-      "sha256": "3910ea26d65b5afc883d4b3488d605ee5786bda41ef86e280b5a180d6f6fa586"
+      "sha256": "35762381d39e1943558131e97d3541e28d47161a56ec0a3d664942c90fb9fa9b"
     },
     {
       "path": "docs/architecture.md",
@@ -1352,7 +1352,7 @@
     {
       "path": "docs/branding-contract.md",
       "mode": "0000644",
-      "sha256": "bda65bdc06badd4f426468941be2800fd3c50e2ed1dd8bdd4d37d94bc668b4bd"
+      "sha256": "f5918fa955f90ca30412ebce209bf2d51b67fa318f7f04d667262cd42c134745"
     },
     {
       "path": "docs/branding-fill-prompt.md",
@@ -1467,7 +1467,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "e4df7e072247c388228632abf5cb2ed0fdae535d09ea06c4f87e9bcae056769e"
+      "sha256": "f76f816dbbab7668c7dbd1ff7406dee095e043f23262a2c6afd900ff9c59b337"
     },
     {
       "path": "docs/handoff-template.md",
@@ -1642,7 +1642,7 @@
     {
       "path": "docs/recipes/ops-gotchas.md",
       "mode": "0000644",
-      "sha256": "bafbbe9d5b6cde72bd2bdbe0b5578550a282b20e73a5f025da6ab7fdb46f69b1"
+      "sha256": "6374ff40b5b054d57761d25bf7b21059c8b2d8d35354120cc221431edd3260a2"
     },
     {
       "path": "docs/recipes/overnight-builder.md",
@@ -1699,6 +1699,11 @@
       "mode": "0000644",
       "sha256": "732f3b01b7d2e6cc238dd5f48d5ed774f6c2c27ecc737710047758bf85f2d9e5"
     },
+    {
+      "path": "docs/recipes/windows-builders.md",
+      "mode": "0000644",
+      "sha256": "2e24454839aa02d1f3205dd92a6856254e59ca04f88573a1f42641ddb5924e32"
+    },
     {
       "path": "docs/recipes/work-on-a-task-from-your-dev-box.md",
       "mode": "0000644",
@@ -3857,7 +3862,7 @@
     {
       "path": "modules/provisioning/provisioning.js",
       "mode": "0000644",
-      "sha256": "9163b2b0de80a648371d03f89e0da8ff234a1cd4f038a1279f6324ae0921e0f4"
+      "sha256": "59fd212df421b2bdcdfaef4871aa1927c371d3f7d6affafe44e810135acd12b6"
     },
     {
       "path": "modules/provisioning/rate-limit.js",
@@ -3867,7 +3872,7 @@
     {
       "path": "modules/provisioning/routes/provisioning.js",
       "mode": "0000644",
-      "sha256": "232d5ce81dc2821b9b953c7596ab385b89e2d5193891735e3220021437fd06db"
+      "sha256": "321db8769eda7c5f6f385e90edaeec70fc071f0bc2e53e6147705153b0d32d3a"
     },
     {
       "path": "modules/provisioning/tests/liveness.mjs",
@@ -4162,12 +4167,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "05d0b9f864bda27810fdb4395f11dbd2a10c154d990cb9a797b4861b12939200"
+      "sha256": "969a257b3ae8148774d7d64cef01f68be0eec703043a129ae34984f3399208d9"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "e3f4d846962f68ba3a7e53dc71476cf2d516dd7aa031bf03fa18abc9c09b3e07"
+      "sha256": "904c4fce25eeb089d80da1a5a0cfced1a96b99aea4f2bc28e5ce07d66bd8a880"
     },
     {
       "path": "public-docs/index.html",
@@ -4422,7 +4427,7 @@
     {
       "path": "public-landing/projects.html",
       "mode": "0000644",
-      "sha256": "576bc8fe1e3379dd2efa6323f889b65d9c4cbb5164b5e80716a6eee045bad002"
+      "sha256": "925e7964f66d59f2df260a611e602bdeafe3f8f3b73d3d16db7bdfa073b4163c"
     },
     {
       "path": "public-landing/world/assets/clouds/cloud-island-large.png",
@@ -4507,7 +4512,7 @@
     {
       "path": "scripts/gds/api.js",
       "mode": "0000644",
-      "sha256": "8f7332da44883801fb4674747c9e9a60e485353b36df6bebe1db8fc1ebd3558f"
+      "sha256": "96d6b69e9440dac3ed81c490e460a832d385714de0b379650af80817f89ded0f"
     },
     {
       "path": "scripts/gds/api.ps1",
@@ -4657,7 +4662,7 @@
     {
       "path": "scripts/gds/cli-lib.js",
       "mode": "0000644",
-      "sha256": "e86444334085b00ff4256fcb6bf15e5f443dc75bdcbf8ca6eb87f0b41fcd3230"
+      "sha256": "83d27d14600c4c8ec8912c7ad8ce771e0e34903ccc9b567dcc27cb95aeb3c37d"
     },
     {
       "path": "scripts/gds/code.js",
@@ -4887,7 +4892,7 @@
     {
       "path": "scripts/gds/init.js",
       "mode": "0000644",
-      "sha256": "e9fbb7ae477a445252f1171851be93fca14f58e4906d030c93d09b37d517ac20"
+      "sha256": "bde86f3f65cdd4a1ad0e143c58f6517328dd7cdee7c1194c0fa614aaf9df56f6"
     },
     {
       "path": "scripts/gds/install-git-hooks.js",
@@ -5032,7 +5037,7 @@
     {
       "path": "scripts/gds/onboard.js",
       "mode": "0000644",
-      "sha256": "2a8fd60c85b7ef4372a3325d44c9b939f394c5ab1a8364985f2278abfdb8aca4"
+      "sha256": "c6fb2c531c6d84dcb16daea50984e1b24021b6379cf992a01482951b119bf9e4"
     },
     {
       "path": "scripts/gds/onboarding-analyze.js",
@@ -5307,7 +5312,7 @@
     {
       "path": "scripts/gds/ship.js",
       "mode": "0000644",
-      "sha256": "be7d4d35f8f19e4687e9a8444ca36c222895805a7ec35952f92a27ef567ed2b5"
+      "sha256": "7ae14021dbae94ffc5a70cf05081e645ca2dcf9685ccf135658538cb44e79dde"
     },
     {
       "path": "scripts/gds/smoke-batch-claim.sh",
@@ -5384,6 +5389,11 @@
       "mode": "0000644",
       "sha256": "32e0c1f2a955d4cabeae00d3749b283abd70f05f34b5fcbd84be3f35e2e655c8"
     },
+    {
+      "path": "scripts/gds/worktree.js",
+      "mode": "0000644",
+      "sha256": "74fc8349287498ede068156f904aaef3f7dbeafce2b40942dd5a8a2a0208564a"
+    },
     {
       "path": "scripts/hall-preview/README.md",
       "mode": "0000644",
@@ -5707,7 +5717,7 @@
     {
       "path": "src/bongos/serve-internal.js",
       "mode": "0000644",
-      "sha256": "c791369591627f89ff1755ea1d343159716b512e64f92286d27547209da88df7"
+      "sha256": "465211ef9e62fd74828d326ab427b0b21b7b73f6124e842b55f8b23d51660ebe"
     },
     {
       "path": "src/bongos/stealth-gate.js",
@@ -5742,7 +5752,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "16aec96c16dd0b8315db0bc9879b36b75195a81f944ccae84ded61de76b5717f"
+      "sha256": "79041166a496039eff11ecc00334671609fadace4a54645cf2b287a5b5ff1a53"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -5854,6 +5864,11 @@
       "mode": "0000644",
       "sha256": "3a54640e1707b27916b9f0168e1ca12141f34148be975d7cad74f02aac166977"
     },
+    {
+      "path": "tests/api_msys_path_repair.mjs",
+      "mode": "0000644",
+      "sha256": "ebb0a0183ca30ebe5207c4703e85e49c32e958778d76373f597553cf259feb39"
+    },
     {
       "path": "tests/api_pagination_contract.mjs",
       "mode": "0000644",
@@ -7279,10 +7294,15 @@
       "mode": "0000644",
       "sha256": "edb6c5da9ec32536d50f7cb648b81b026b7926f73f891feb0906fc7343b5b11d"
     },
+    {
+      "path": "tests/provisioning_default_domain.mjs",
+      "mode": "0000644",
+      "sha256": "1403cc764270e796b985cc0dc38cbf498001e4726b2bfe53020cc55d12d1ca66"
+    },
     {
       "path": "tests/provisioning_domain_attach.mjs",
       "mode": "0000644",
-      "sha256": "241e1b208abbd54a625af050d541344186d93806846a1e7f1cbb0f93dfbab802"
+      "sha256": "fbbd7397fd03181e9c2ea58ed8accb1a9d9d66d4c904a09265161e1034b02f9f"
     },
     {
       "path": "tests/provisioning_github_app_routes.mjs",
@@ -7297,7 +7317,7 @@
     {
       "path": "tests/provisioning_teardown_intent.mjs",
       "mode": "0000644",
-      "sha256": "c5ebacf7e29be4e6afecedf5b8593eef750d497e0c502cfa2be92a89b2cff0a1"
+      "sha256": "68d328b69cd8b981e8454d679c00a757abeeafb4e083249489eec744cdd4898d"
     },
     {
       "path": "tests/pruned_lockfile_integrity.mjs",
@@ -7609,6 +7629,11 @@
       "mode": "0000644",
       "sha256": "e236bc3d6882bc6ddf5d389371a92a96aec62769f14c37bbca31810bcbea0d61"
     },
+    {
+      "path": "tests/ship_post_land_verify.mjs",
+      "mode": "0000644",
+      "sha256": "6df2fb6fde081c9d98baab346a794946a51e4e51e70d154d41d9e94939180d52"
+    },
     {
       "path": "tests/ship_preflight.mjs",
       "mode": "0000644",
@@ -7824,6 +7849,11 @@
       "mode": "0000644",
       "sha256": "aa1aab27bdfc5761586514fa07dacfad125fb1d5dcc7f01c060cbe3556985454"
     },
+    {
+      "path": "tests/worktree_helper.mjs",
+      "mode": "0000644",
+      "sha256": "367e4c9a63bc8752b94d0fc7af171d34390034adc2a75c8ec15f00b335c077ca"
+    },
     {
       "path": "tests/write_validation_gaps.mjs",
       "mode": "0000644",

package/.claude/skills/builder-end/SKILL.md

@@ -13,7 +13,7 @@ Composes operations that already exist, in a safe order, with the destructive on
 
 1. **Resolve the claim** — `/builder-ship` when there's committed, shippable work; `/builder-release` when there isn't. (It calls the sibling skills; it does not re-implement shipping.)
 2. **Clean-git verify** — refuse to go further if any *tracked* file is uncommitted. This is the same guard `scripts/gds/ship.js` enforces (`trackedDirty` in [`src/bongos/ship-preflight.js`](../../../src/bongos/ship-preflight.js)): untracked scratch is ignored, but a modified/staged/deleted tracked file means real work isn't committed — stop before anything is lost.
-3. **Worktree teardown** — from the main checkout, `git worktree remove` this session's linked worktree, `prune`, and delete the now-merged `claude/<name>` branch.
+3. **Worktree teardown** — from the main checkout, remove this session's linked worktree via `node scripts/gds/worktree.js remove` (junction-aware), `prune`, and delete the now-merged `claude/<name>` branch.
 4. **Box close-out (dev box only)** — if running on a dev box (`/etc/otb/box.env` exists), offer to `close-box` so the box stops billing. Optional and gated on a yes; declining just lets the box idle-park. On a laptop this step is skipped — there's no box to close.
 
 It never pushes to `main`, never `ssh`-es, never runs a deploy — landing is `/builder-ship`'s job (server-mediated). It only ever touches the caller's **own** claim, **own** worktree, and **own** box.
@@ -46,7 +46,7 @@ Proceed only when **all** hold: we're in a linked worktree, the claim is resolve
 You can't remove the worktree you're standing in, so run the removal **from the main checkout** — resolve its path the way `ship.js` does (`findMainWorktree`: parse `git worktree list --porcelain` for the block whose `branch` is `main`). From there:
 
 ```bash
-git worktree remove <this-worktree-path>   # refuses if dirty — that's the safety net; do not --force
+node scripts/gds/worktree.js remove <this-worktree-path>   # junction-aware wrapper: unlinks a node_modules junction FIRST, then runs `git worktree remove` (which still refuses a dirty tree; do not --force)
 git worktree prune
 git branch -d claude/<worktree-name>        # -d (not -D): git refuses an unmerged branch, by design
 ```
@@ -69,7 +69,7 @@ Skip this entirely if step 0 found no `/etc/otb/box.env` (a laptop — there's n
 ## Constraints
 
 - **Own-scoped.** Only this session's claim, this session's worktree, and the caller's own box — never another builder's claim, never another worktree, never `git worktree remove` a path you didn't create, never another builder's box.
-- **Never destroy uncommitted work.** The clean-git verify gates teardown; `git worktree remove` (no `--force`) and `git branch -d` (not `-D`) are the load-bearing safety nets — keep them as written.
+- **Never destroy uncommitted work.** The clean-git verify gates teardown; the dirty-tree refusal in `git worktree remove` and `git branch -d` (not `-D`) are the load-bearing safety nets — keep them as written. But note: that refusal does NOT protect a Windows worktree carrying a `node_modules` junction — node_modules is gitignored, so the clean check passes and `git worktree remove` (even without `--force`) follows the junction and deletes the SHARED node_modules (task 1002809). That is why teardown runs through `node scripts/gds/worktree.js remove`, which unlinks the junction first.
 - **Box close is opt-in and destructive.** On a box, never `close-box` without an explicit yes — it deprovisions the box and any unshipped `/workspace` work is gone. Declining is always fine; the box idle-parks on its own.
 - **Never push / ssh / deploy.** Landing goes through `/builder-ship` (server-mediated); this skill stays local to the builder's machine (its one possible API write is the opt-in own-scoped `close-box`).
 - **The destructive steps (teardown, box-close) never run unattended without a clear go.** Ship vs. release can be inferred from state (commits ⇒ ship, none ⇒ release) and proceed; removing the worktree ends the session and closing the box destroys it, so wait for an explicit yes before steps 3 and 4.

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

@@ -252,7 +252,7 @@ export interface PostProvisioningInstancesIdForceTeardownResponse { ok: boolean;
 export interface PostProvisioningInstancesIdGithubAppRequest { account?: string }
 export interface PostProvisioningInstancesIdGithubAppResponse { state: unknown; account: unknown; post_url: unknown; personal_url: unknown; org_url: unknown; org_login: unknown; manifest: unknown; redirect_url: unknown; expires_at: unknown }
 export interface PostProvisioningInstancesIdTeardownResponse { ok: boolean; queued: unknown; action: unknown; status: unknown; superseded: unknown; message: unknown }
-export interface PostProvisioningInstancesRequest { slug: string; target_ref?: string; hosting_shape?: string; domain?: string; tier?: string; onboard_mode?: string; type?: string }
+export interface PostProvisioningInstancesRequest { slug: string; target_ref?: string; hosting_shape?: string; domain?: string; no_address?: boolean; tier?: string; onboard_mode?: string; type?: string }
 export interface PostSearchMarkRequest { chunk_id?: StringifiableId; useful?: unknown }
 export interface PostSearchRequest { expand?: unknown; q?: string; source_kind?: string; limit?: unknown }
 export interface PostSearchResponse { expand?: unknown; chunk?: unknown; query?: unknown; count?: unknown; total_full_tokens?: unknown; results?: unknown }

package/config/branding.neutral.json

@@ -15,6 +15,7 @@
     "oauthOrigin": "http://localhost:3000",
     "devBoxBase": "",
     "sshBoxBase": "",
+    "instanceBase": "",
     "sandboxPrefix": "sandbox-",
     "termPrefix": "term-"
   },

package/docs/api/openapi.json

@@ -15826,6 +15826,9 @@
             "type": "string",
             "maxLength": 253
           },
+          "no_address": {
+            "type": "boolean"
+          },
           "tier": {
             "type": "string",
             "maxLength": 40

package/docs/api-reference.md

@@ -368,7 +368,7 @@ Base path: `/api/bongos`. Ranks (enforced server-side, [ADR 0016](adr/<redacted>
 | GET | `/api/bongos/provisioning/github-app/status` | `public` | — | GET /provisioning/github-app/status?state=<> — the PUBLIC progress read the onboarding callback page polls (task 2096) to know when setup… |
 | GET | `/api/bongos/provisioning/health` | `public` | — | GET /provisioning/health — liveness + the core version this module mounted against. |
 | GET | `/api/bongos/provisioning/instances` | `any-builder` | — | GET /provisioning/instances — the caller's own instances + each open intent. |
-| POST | `/api/bongos/provisioning/instances` | `any-builder` | `slug`, `target_ref`, `hosting_shape`, `domain`, `tier`, `onboard_mode`, `type` | POST /provisioning/instances — request a new instance. |
+| POST | `/api/bongos/provisioning/instances` | `any-builder` | `slug`, `target_ref`, `hosting_shape`, `domain`, `no_address`, `tier`, `onboard_mode`, `type` | POST /provisioning/instances — request a new instance. |
 | GET | `/api/bongos/provisioning/instances/:id` | `any-builder` | — | GET /provisioning/instances/:id — read one of the caller's own instances. |
 | POST | `/api/bongos/provisioning/instances/:id/domain` | `any-builder` | `domain` | POST /provisioning/instances/:id/domain — give the caller's OWN instance its address (task 1002692, gap 5: no path existed to add a domai… |
 | POST | `/api/bongos/provisioning/instances/:id/force-teardown` | `metic+archon` | — | POST /provisioning/instances/:id/force-teardown — Archon tears down ANY instance. |

package/docs/branding-contract.md

@@ -31,6 +31,7 @@ env override   →   instance config (config/branding.json)   →   neutral star
 | `domains.provisioningOrigin` | **Optional.** Control-plane front-door origin the [provisioning module](../../modules/provisioning/CLAUDE.md) uses to build a new customer's GitHub-App `redirect_url`. Set it when the control plane co-hosts a game whose `publicOrigin` is the game's own domain (OTB = customer 0) so the customer's App carries the PLATFORM brand (e.g. `https://get.cloudbongos.com`), not the game's. **Falls back to `publicOrigin` when unset** — an instance whose `publicOrigin` is already the platform needs no override. Env-overridable: `<PREFIX>_PROVISIONING_ORIGIN`. ([#2101](https://example.com/builders#/task/2101)) |
 | `domains.devBoxBase` | Apex zone the **proxied** browser-terminal + sandbox hosts ride (`term-<login>.<devBoxBase>`, `sandbox-<login>.<devBoxBase>`). Must be a one-label-under-apex zone so free edge TLS (`*.<apex>`) covers it — a two-label host fails edge TLS (the [#771](https://example.com/builders#/task/771) lesson). Empty ⇒ no managed boxes. |
 | `domains.sshBoxBase` | Zone for the **legacy direct-IP SSH** box host (`box-<login>.<sshBoxBase>`, unproxied). Deliberately distinct from `devBoxBase` (one proxied/edge-TLS, one direct-IP). |
+| `domains.instanceBase` | Apex zone new projects get their **auto-assigned** address under (`<slug>.<instanceBase>`, task 1002704 — every project's hall reachable day one; `no_address: true` on the create call opts out). Same one-label-under-apex/edge-TLS constraint as `devBoxBase`. Deliberately NOT derived from `publicOrigin` (on a co-hosting control plane that is the game's domain). Empty ⇒ no auto-assign — creates are domainless unless the caller brings a domain. |
 | `domains.sandboxPrefix` / `termPrefix` | Subdomain prefixes for the sandbox-preview + browser-terminal hosts. |
 | `repo` | `{ owner, name }` GitHub binding. |
 | `db.database` | DB name the GDS pool connects to when neither `DATABASE_URL` nor `PGHOST`/`PGDATABASE` is set (`src/bongos/pool.js`, ADR 0062 §5). `null` in the neutral starter = **fail loud** rather than silently target a host DB. |

package/docs/file-map.md

@@ -56,6 +56,7 @@
 │   ├── recipes/                 ← long-form operational guides (formerly learnings/) — Postgres, Caddy, the pixel-art pipeline, etc.
 │   │   ├── README.md
 │   │   ├── ops-gotchas.md       ← Postgres, Caddy, SSH, Mac toolchain recipes
+│   │   ├── windows-builders.md  ← (task 1002809) the Windows + Git Bash builder loop: worktree junction trap, api.js MSYS auto-repair, --body-file pattern, local test baseline
 │   │   ├── pixel-art-pipeline.md
 │   │   ├── overnight-builder.md ← (#358) operator runbook for the autonomous overnight session-runner
 │   │   ├── builder-box-lifecycle.md ← (#598/ADR 0031) operator runbook: provision/park/wake/deprovision dev boxes, the two sweeps, config env, going-live steps
@@ -170,6 +171,7 @@
 │       ├── smoke-box.sh         ← (#598) hermetic box-lifecycle smoke (no DB/DO/network): runs tests/boxes.mjs + tests/cf_tunnel.mjs (#771 named tunnel) + route-rank + module-load
 │       ├── recall.js            ← `/recall` CLI: two-call progressive-disclosure search (summary → `--expand <id>`) over the GDS retrieval layer (ADR 0060); `node scripts/gds/recall.js <query>`
 │       ├── capture.js           ← file an idea_inbox row from the CLI (the ideas.capture kernel port); backs the "capture a tangent" flow across skills
+│       ├── worktree.js          ← (task 1002809) junction-safe worktree add/remove/list — outside-repo worktrees get a node_modules junction via node (no shell quoting), removed BEFORE `git worktree remove`
 │       ├── learning-capture.js  ← file a `learnings` row (DB-backed short-form rule capture, replacing hand-edited recipe files for a single gotcha)
 │       ├── docs-entropy.js      ← ([#…] docs-entropy) markdown-corpus linter: broken internal links + cross-file duplicate-prose detector across every tracked `.md`; `--verbose` / `--file-ideas`
 │       ├── gen-diagrams.js      ← generates the 5 onboarding diagrams (`.mmd`/`.svg`/`.png` + `assertions.json`) from templates in this file — never hand-edit a `.mmd`/assertions.json; runs on deploy

package/docs/recipes/ops-gotchas.md

@@ -149,6 +149,8 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 
 ## Windows / local dev (PowerShell)
 
+> Git Bash builder-loop gotchas (worktree junctions, api.js path mangling, local test baseline) live in their own recipe: [windows-builders.md](windows-builders.md).
+
 ### PowerShell 5.1 turns a clean `node scripts/gds/*.js` exit into a false failure
 
 - **Symptom:** Running `node scripts/gds/api.js GET /api/gds/me 2>&1` (or the same on `claim.js`/`ship.js`) inside a PowerShell 5.1 session reports failure — `$?` is `$false` and the stderr line surfaces as a `NativeCommandError` — even though node exited 0 and the JSON on stdout is exactly right.

package/docs/recipes/windows-builders.md

@@ -0,0 +1,103 @@
+---
+track: internal
+scope: builder tooling — the Windows + Git Bash builder loop (worktrees, api.js, ship.js, local tests)
+---
+
+# Building on Windows (Git Bash) — the gotchas, and what the tooling now does for you
+
+Everything here was paid for at least once on a real Windows box (task 1002548's learnings, the
+HANDOFF-apex-ui session, task 1002809). Most of it is now **fixed in the tooling** — this recipe
+records what changed, what you still have to know, and the one destructive trap to respect.
+PowerShell-specific gotchas (stderr false-failures, BOM) live in
+[ops-gotchas.md → Windows / local dev](ops-gotchas.md#windows--local-dev-powershell).
+
+## api.js: MSYS path mangling is auto-repaired (no more `MSYS_NO_PATHCONV=1`)
+
+- **Was:** Git Bash rewrites a leading-slash argument before node sees it — `node scripts/gds/api.js GET /tasks/123`
+  arrived as `GET C:/Program Files/Git/tasks/123` and hit the usage error, unless every call was
+  prefixed `MSYS_NO_PATHCONV=1`.
+- **Now (task 1002809):** `api.js` detects the mangled prefix via `EXEPATH` and strips it itself
+  (`repairMsysMangledPath` in `cli-lib.js`). Call it plain; the old env prefix is harmless if you
+  still type it out of habit.
+- **Still true:** judge success by the JSON + status line, not folklore about exit codes — and if
+  you ever see the libuv `UV_HANDLE_CLOSING` assertion after the JSON printed, that teardown class
+  of bug is tracked in [scripts/gds/CLAUDE.md](../../scripts/gds/CLAUDE.md) (task 1002734's
+  `cliExit` rule).
+
+## api.js: inline `--body` loses its quotes — use `--body-file`
+
+Shells on Windows strip/re-split inline JSON quoting. The durable pattern for any POST/PATCH body:
+
+```bash
+# write the JSON with a real editor/tool, then:
+node scripts/gds/api.js POST /tasks --body-file C:/tmp/body.json
+# or pipe it (no temp file):
+node scripts/gds/api.js POST /claims --body-file - <<'EOF'
+{"task_id": 123, "worktree_name": "task-123"}
+EOF
+```
+
+`api.js` now points you here when an inline `--body` fails to parse (task 1002809).
+
+## Worktrees: prefer inside-repo; outside-repo needs the junction helper
+
+Every claim gets its own real worktree (owner directive — see the `/builder-claim` skill). Two
+placements work on Windows:
+
+- **Default — `.claude/worktrees/<name>` (inside the repo).** No `node_modules` setup at all:
+  node's resolution walks up to the main checkout's copy. This is what the harness `EnterWorktree`
+  primitive creates.
+- **Outside the repo (e.g. `C:/tmp/task-N`)** — useful because OneDrive briefly locks in-repo
+  dirs. An outside worktree can't walk up to `node_modules`, so it needs a **junction** — and this
+  is where the destructive trap lives. Use the helper, never hand-rolled `mklink`:
+
+  ```bash
+  node scripts/gds/worktree.js add <task-id> --outside     # worktree + junction, no shell quoting
+  node scripts/gds/worktree.js remove task-<id>            # unlinks the junction FIRST
+  node scripts/gds/worktree.js list                        # shows which worktrees carry junctions
+  ```
+
+### ⚠ The trap (why the helper exists — task 1002809)
+
+- `cmd //c mklink /J` from Git Bash **mangles quoted targets containing spaces** (the target grows
+  a leading `\`), producing a junction that resolves to nothing. The helper uses node's
+  `fs.symlinkSync(target, link, 'junction')` — no shell, no quoting, no elevation.
+- `git worktree remove` (and `--force`) **follows a junction into its target** — with a hand-made
+  junction in place it deletes the **shared `node_modules` of the main checkout**. The helper
+  always unlinks the junction (link only) before calling git. If you ever bypass the helper:
+  remove the junction yourself first (`fs.rmdirSync` / `rmdir` on the link), then
+  `git worktree remove`.
+
+## `Cannot find module 'pg'` (or any dep) inside a worktree
+
+Run `npm install` in the **main checkout**, never in the worktree. Worktrees share the main
+checkout's `node_modules` (by walk-up inside the repo, by junction outside); a second
+`node_modules` inside a worktree only creates drift.
+
+## OneDrive locks `git worktree remove` — the first attempt usually still worked
+
+`git worktree remove` on an in-repo worktree often errors `Permission denied` / `Device or
+resource busy` because OneDrive briefly locks the directory. The failed attempt usually still
+**deregisters** the worktree (`git worktree list` to confirm — the helper's `remove` does this
+check for you); the empty husk directory deletes on its own later. Don't fight it with retries.
+
+## Local unit tests: baseline first, CI is truth
+
+The local `tests/*.mjs` suite has a **large stable failure baseline on Windows boxes** (mostly
+DB-backed tests with no local Postgres — ~184 failures at last count, and the count drifts).
+Before blaming your change: run the suite once *before* touching anything (or on a clean
+checkout), and compare against that. The CI `unit` check on the PR is the authoritative verdict.
+
+## Never pipe `ship.js` through `head`/`tail`
+
+When the pager closes the pipe mid-run, node dies on EPIPE and the land chain aborts silently —
+the task strands at `confirmed` (hit on task 1001860). Run it unpiped or `> file`; a stranded
+confirmed task re-lands by re-running `node scripts/gds/ship.js <id>` (resume is idempotent).
+
+## ship.js: a failed post-land ship call may be a success — now auto-verified
+
+The final `POST /tasks/<id>/ship` after a successful merge can be refused (`task_not_confirmed`)
+because the server already landed the task first (reconcile-on-read or the ~5-min reconciler).
+`ship.js` now normalizes both API error shapes and **verifies the live task status with a GET
+before reporting failure** (task 1002809) — a verified `shipped` prints as the success it is. If
+you see a ship-call failure from older tooling, check `GET /tasks/<id>` before reacting.

package/modules/provisioning/provisioning.js

@@ -111,6 +111,42 @@ function normalizeHostname(h) {
   return s;
 }
 
+// The auto-assigned address for a new project: <slug>.<apex> (task 1002704 — the
+// owner's auto-assign/opt-out decision; every project's hall reachable day one).
+// The apex is branding domains.instanceBase; blank or unparseable → null, so a
+// self-host or unconfigured instance keeps creating domainless instead of
+// guessing (the client's location.hostname guess stays client-side only). PURE.
+function defaultDomainForSlug(slug, apex) {
+  if (!isValidSlug(slug)) return null;
+  const a = String(apex == null ? '' : apex).trim();
+  if (!a) return null;
+  return normalizeHostname(`${slug}.${a}`) || null;
+}
+
+// Labels the platform itself occupies (or has planned) directly under the instance
+// apex, plus the dev-box hostname prefixes. The runner's DNS write is an UPSERT,
+// so a project claiming one of these would overwrite platform records — refuse at
+// the API layer instead (task 1002704; the guard applies to auto-assigned AND
+// bring-your-own hostnames, on create and on attach). Anything deeper than one
+// label under the apex is also refused: it breaks the wildcard-cert rule (one
+// label under the apex — the #771 lesson) and nothing legitimate creates it.
+const RESERVED_APEX_LABELS = new Set([
+  'www', 'api', 'get', 'status', 'builders', 'docs', 'mail', 'admin', 'app',
+  'cdn', 'ns1', 'ns2', 'demo', 'gate', 'downloads',
+]);
+const RESERVED_APEX_PREFIXES = ['term-', 'sandbox-'];
+function isReservedHostname(domain, apex) {
+  const host = normalizeHostname(domain);
+  const zone = normalizeHostname(apex);
+  if (!host || !zone) return false;
+  if (host === zone) return true;
+  if (!host.endsWith(`.${zone}`)) return false;
+  const label = host.slice(0, -(zone.length + 1));
+  if (label.includes('.')) return true;
+  if (RESERVED_APEX_LABELS.has(label)) return true;
+  return RESERVED_APEX_PREFIXES.some((p) => label.startsWith(p));
+}
+
 // The instance lifecycle states for which an on-demand TLS cert may be minted: a
 // host mid-standup ('provisioning' — Caddy's first handshake can land here, while
 // the snippet is written + reloaded) or live ('active'). NOT 'requested' (nothing
@@ -658,6 +694,7 @@ module.exports = {
   PROVISION_ENQUEUE_FROM, DOMAIN_ATTACH_FROM, TIER_MONTHLY_USD, CERT_ELIGIBLE_STATES,
   // pure
   isValidSlug, costEstimateUsd, publicInstance, normalizeHostname,
+  defaultDomainForSlug, isReservedHostname,
   // pure — GitHub App Manifest flow (task 2080)
   githubAppName, buildGithubAppManifest, manifestPostUrl,
   // data access