@bongos/core 1.19.119 → 1.19.121

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.119",
-  "core_contract": "1.19.119",
-  "source_commit": "1a3ff47e4556fdab934c24fb8e01bbb4bb01d095",
+  "core_version": "1.19.121",
+  "core_contract": "1.19.121",
+  "source_commit": "5bc8620889777dfaeebdc0bef12a6ac24c036e61",
   "source_ref": "HEAD",
-  "built_at": "2026-08-14T20:02:21.430Z",
+  "built_at": "2026-08-14T20:40:48.360Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 302,
+    "docs_redacted": 303,
     "agent_docs_stubbed": 21,
-    "functional_verbatim": 1239,
+    "functional_verbatim": 1243,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 1562,
-  "tree_sha256": "df9b1ed828fdacdb04089002baf65d5176be91c467884f599031bbd8218cae30",
+  "file_count": 1567,
+  "tree_sha256": "c642320ac42a83f1863a48c74b443b0c761d83a85ad45114720ee0a9f60bc850",
   "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",
@@ -1467,7 +1467,7 @@
     {
       "path": "docs/file-map.md",
       "mode": "0000644",
-      "sha256": "e4df7e072247c388228632abf5cb2ed0fdae535d09ea06c4f87e9bcae056769e"
+      "sha256": "f76f816dbbab7668c7dbd1ff7406dee095e043f23262a2c6afd900ff9c59b337"
     },
     {
       "path": "docs/handoff-template.md",
@@ -1577,7 +1577,7 @@
     {
       "path": "docs/recipes/core-release-pipeline.md",
       "mode": "0000644",
-      "sha256": "80d1e530d5c15bad53c3bcead244dfbb824236d1db0d281a41abd09f009f300d"
+      "sha256": "512d67da7fba233e31f318b3fa8aacb377fecaf4f1810696f8357507620424db"
     },
     {
       "path": "docs/recipes/devbox-app-release.md",
@@ -1642,7 +1642,7 @@
     {
       "path": "docs/recipes/ops-gotchas.md",
       "mode": "0000644",
-      "sha256": "1e35b15c1f366aae52aedbd12e4a193343f8fd13b2fc6bdec13f927b7a22e5f4"
+      "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",
@@ -4162,12 +4167,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "2a008b4ca09e8abb2613478eb696fb66b63b4dd075cee7bbd6d7fb60a9866513"
+      "sha256": "f4b51e6942ce9cd2f52b077f67e671feb4ac93e03d08a2fc487981205fc362b9"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "ce8caad093e4acd61c3de150836996162c8265ed1ceb09a27130bbe58ea10aaf"
+      "sha256": "1d7889d13a0d5ab2930528a5b8efdde5e9b28cb1467f5f0b29dec2e60ce722f0"
     },
     {
       "path": "public-docs/index.html",
@@ -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",
@@ -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",
@@ -5742,7 +5752,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "a990b6b2c309018a149e0190b2fcd74a0d6e2b3754cfdd3eabdf505038a19d87"
+      "sha256": "180b8c272ae0895dc57e67f1a0558c603bb811e6bda5d0dee4d1547239851728"
     },
     {
       "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",
@@ -7609,6 +7624,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 +7844,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/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/core-release-pipeline.md

@@ -130,6 +130,59 @@ Also: an instance can have **more than one plane to update** (e.g. a web instanc
 
 ---
 
+## The pin-bump runbook — cloudbongos.com, one paste per step (task 1002767)
+
+The generic mechanics are [upgrading-the-core](upgrading-the-core.md); this is the **operational sequence for the live mothership** — registry pin, pull-deploy repo at `/home/lars/cloudbongos-instance`, `cloudbongos.service` serving `127.0.0.1:3002`. Every trap below cost a real round trip on the 2026-08-13 (`1.19.91 → 1.19.94`) run; the goal is that the next bump is one paste, not fifteen.
+
+**Cadence: bump once, at session end.** One upgrade covers every release the session landed (publish-on-merge cuts one per merge — you don't chase each). Don't bump per-ship.
+
+### Step 1 — pick the version (your machine, main checkout)
+
+```bash
+git fetch origin --tags
+git tag --list 'core-v*' --contains <your-merge-sha> | sort -V | head -1
+```
+
+**Failure this prevents — pinning a release that predates your work.** The version your own ship report printed is usually the release cut for the *previous* merge (ADR 0161 publishes *after* each land). The version to pin is the newest tag that **contains** your merge. If no tag contains it, the publish lane hasn't finished (or is disarmed): a green `publish` *check* is not evidence of a publish — read the Publish **step log** for `+ @bongos/core@<version>`. The package is private, so an anonymous `npm view` proves nothing either.
+
+### Step 2 — the bump (the owner runs this line, via `!` in the session)
+
+The permission classifier blocks the agent from running a mutating `sudo -u lars` over ssh, so this paste is the **owner's**. The `!` prefix also keeps ssh honest: a bare `ssh host` is non-interactive here — it connects, prints the MOTD, and exits — so the command must ride as an argument.
+
+```
+! ssh -i ~/.ssh/otb_builder jaxri@REDACTED_IP "sudo -n -u lars bash -c 'cd /home/lars/cloudbongos-instance && export NPM_TOKEN=\$(grep -oP \"(?<=_authToken=).*\" /home/lars/.npmrc | head -1) && [ -n \"\$NPM_TOKEN\" ] || { echo EMPTY NPM_TOKEN — aborting; exit 12; }; ./node_modules/.bin/bongos upgrade --registry --to <VER> --service cloudbongos.service --health-url http://127.0.0.1:3002/healthz --commit-pin'"
+```
+
+What each piece is for — each guards a failure that actually happened:
+
+- **Token extraction runs as lars** (the whole command is inside `sudo -u lars bash -c`). Reading `/home/lars/.npmrc` as `jaxri` is `Permission denied`, which yields an **empty** `NPM_TOKEN`, which sends npm to the **public** registry, which 404s on the private `@bongos/core` — and the upgrade rolls back cleanly, having taught you nothing. The `[ -n "$NPM_TOKEN" ] || exit` guard aborts instead of half-running.
+- **`--to <VER>` is required** — `bongos upgrade` refuses to guess a target.
+- **`--service` + `--health-url` buy the automatic rollback.** Point the health URL at `http://127.0.0.1:3002/healthz`, **not the public URL** — a pre-launch `basic_auth` on the apex makes a healthy boot look failed and triggers a needless rollback.
+- **`--commit-pin` commits AND pushes the pin.** The instance is a pull-deploy repo: the next sync runs `git reset --hard origin/main`, which reverts an uncommitted pin, and `npm ci` then reinstalls the old core. Nothing errors. This is exactly how live sat 13 releases behind (task 1002712). The same applies to any tracked instance-config edit (`config/branding.json`): commit + push or the next deploy tick undoes it. A commit that fails to *push* saves nothing — deploy.sh resets to the remote.
+- **The `core_upgrades` ledger row needs `PGDATABASE`.** The migrate step resolves the instance DB itself, but the ledger write reads only the env — under `sudo -u lars bash -c` there is none, so the run logs `ledger skipped (no DATABASE_URL or PGDATABASE)`. The bump still succeeds. If you want the row: read the DB name once (`! ssh -i ~/.ssh/otb_builder jaxri@REDACTED_IP "sudo -n -u lars grep -A1 '\"db\"' /home/lars/cloudbongos-instance/config/branding.json"`) and splice `export PGDATABASE=<name> &&` into the paste before the `bongos upgrade` call.
+
+### Step 3 — verify on the box, not from your browser
+
+```
+! ssh -i ~/.ssh/otb_builder jaxri@REDACTED_IP "curl -s http://127.0.0.1:3002/version"
+```
+
+`coreVersion` must equal the target. This is the proof; the deploy tool's own output is not.
+
+**Failure this prevents — trusting a stale or gated public view.** The apex may sit behind pre-launch `basic_auth`, and HTML rides the CDN. (The classic *stylesheet* staleness — new HTML styled by a 4-hour-old `cosmos.css` — was fixed by content-hashed asset URLs in task 1002766, so a broken-*looking* page is no longer expected; if you must check publicly, use a cold profile or `fetch(url, {cache:'reload'})`.)
+
+### Step 4 — prove the pin is durable
+
+The `--commit-pin` output already reports commit + push. To prove durability the hard way, force a deploy tick and re-read the version — a reverted pin shows up here and nowhere else:
+
+```
+! ssh -i ~/.ssh/otb_builder jaxri@REDACTED_IP "sudo -n systemctl start cloudbongos-deploy.service; sleep 5; curl -s http://127.0.0.1:3002/version"
+```
+
+If `coreVersion` regressed: the pin didn't reach `origin/main` — re-run the bump and watch for the `PIN NOT COMMITTED` warning text, or commit+push `package.json` + `package-lock.json` in the instance repo by hand.
+
+---
+
 ## Detecting divergence
 
 [`scripts/gds/deploy-divergence.js`](../../scripts/gds/deploy-divergence.js) is the comparison that was missing during the ten-day incident. It runs **warn-only at the end of every ship** and can be run by hand any time:

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.
@@ -198,6 +200,12 @@ Organized by topic, not chronology. New entries go in the matching section; crea
 - **Related:** publish-on-merge (ADR 0161) pushes a `release: core X.Y.Z` carrier commit after every land, so on an instance that DOES deploy, the deploy run belongs to the carrier's sha, not the merge commit's. A strict sha match never hit — hence the same permanent `pending`. The probe now also accepts a successful `main` deploy that started after the merge.
 - **The wait is bounded.** A probe stuck at `deploy=pending` for a reason that never resolves looks identical to a slow deploy on any single sweep, so after `<redacted>` (default 30 min) a task whose land is *provable on main* ships anyway, and the sweep logs `deploy still unconfirmed after Nmin`. This lifts only the deploy gate — the per-task land proof is untouched, so it can never become a branch-reuse false-ship. Raise the env var on an instance whose real deploy legitimately takes longer than 30 minutes.
 
+### Moving the live cloudbongos.com pin — use the runbook, not memory
+
+- **What:** the end-of-session pin bump (registry-pinned mothership) is a scripted sequence now: [the pin-bump runbook](core-release-pipeline.md#<redacted>). One paste per step; each step names the failure it prevents.
+- **The three that bite hardest** if you freelance it: an NPM token extracted as the wrong user comes back **empty**, npm silently hits the public registry, 404s on the private package, and rolls back cleanly (you learn nothing); a pin left **uncommitted or unpushed** is reverted by the pull-deploy's `git reset --hard` on the next tick — this is how live sat 13 releases behind; and a `--health-url` pointed at the **public apex** instead of `127.0.0.1:3002` reads pre-launch `basic_auth` as a failed boot and triggers a needless rollback.
+- **Cadence:** once per session, at close — one bump covers all the session's releases. The version to pin is the newest `core-v*` tag that **contains** your merge, not the one your ship report printed.
+
 ---
 
 ## Status page + monitoring

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/package-lock.json

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

package/package.json

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

@@ -18,12 +18,15 @@
 // on a 2xx, 1 on any non-2xx or transport error, 2 on bad invocation.
 
 const fs = require('node:fs');
-const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanceAndExit, cliExit } = require('./cli-lib');
+const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanceAndExit, cliExit, repairMsysMangledPath } = require('./cli-lib');
 
 
 (async () => {
   const method = (process.argv[2] || '').toUpperCase();
-  const urlPath = process.argv[3];
+  // task 1002809: Git Bash converts the leading-slash path arg into a Windows
+  // path under the Git install root before node sees it; undo that so builders
+  // don't need the MSYS_NO_PATHCONV=1 prefix.
+  const urlPath = repairMsysMangledPath(process.argv[3]);
   if (!method || !urlPath || !urlPath.startsWith('/')) {
     console.error("usage: node scripts/gds/api.js <METHOD> <path> [--body '<json>' | --body-file <file|->] [--quiet]");
     process.exit(2);
@@ -46,6 +49,13 @@ const { cliClient, arg, stripBom, resolveQuiet, isBoxScope, printBoxScopeGuidanc
     if (raw != null && raw.trim()) body = JSON.parse(raw);
   } catch (e) {
     console.error(`api: could not read/parse JSON body: ${e.message}`);
+    // task 1002809: inline --body is the usual culprit — shells (especially on
+    // Windows) strip or re-split the quotes before node sees them. Teach the
+    // durable pattern instead of leaving a bare parse error.
+    if (bodyFile == null && bodyInline != null) {
+      console.error('  Inline --body often loses its quoting through the shell. Durable pattern:');
+      console.error('  write the JSON to a file and pass --body-file <path>, or pipe it via --body-file -');
+    }
     process.exit(2);
   }
 

package/scripts/gds/cli-lib.js

@@ -771,6 +771,34 @@ function parseSessionRequest(text) {
   return { timeBudgetMin, mode, parallel };
 }
 
+// task 1002809: Git Bash (MSYS) rewrites a leading-slash argument into a Windows
+// path under the Git install root BEFORE node sees it — `/tasks/123` arrives as
+// `C:/Program Files/Git/tasks/123` — unless the builder remembers
+// MSYS_NO_PATHCONV=1. Undo it here so no one needs the env prefix. EXEPATH (set
+// by Git Bash) points INSIDE the install (`…\Git\bin`), while the mangled prefix
+// is the install root (`…\Git`), so we strip the LONGEST ancestor of EXEPATH
+// that prefixes the arg — never the bare drive root (that would "repair"
+// arbitrary Windows paths). Case-insensitive, both slash styles. Pure + exported
+// for tests/api_msys_path_repair.mjs; no-op off win32 or without EXEPATH.
+function repairMsysMangledPath(raw, { exepath = process.env.EXEPATH, platform = process.platform } = {}) {
+  if (!raw || raw.startsWith('/')) return raw;
+  if (platform !== 'win32' || !exepath) return raw;
+  const rawFwd = String(raw).replace(/\\/g, '/');
+  const rawLower = rawFwd.toLowerCase();
+  let ancestor = String(exepath).replace(/\\/g, '/').replace(/\/+$/, '');
+  let best = null;
+  while (ancestor.includes('/')) {
+    // Stop before the bare drive root ("C:" after the last slice).
+    if (/^[a-z]:$/i.test(ancestor)) break;
+    if (rawLower.startsWith(ancestor.toLowerCase() + '/') && (best === null || ancestor.length > best.length)) {
+      best = ancestor;
+    }
+    ancestor = ancestor.slice(0, ancestor.lastIndexOf('/'));
+  }
+  if (best === null) return raw;
+  return rawFwd.slice(best.length);
+}
+
 module.exports = {
   API_BASE,
   hallBase,
@@ -784,6 +812,7 @@ module.exports = {
   arg,
   hasFlag,
   stripBom,
+  repairMsysMangledPath,
   resolveQuiet,
   readSessionToken,
   apiCall,

package/scripts/gds/ship.js

@@ -3122,6 +3122,40 @@ function playShipBell() {
   playSound(shipWav);
 }
 
+// task 1002809: normalize an API error body across BOTH wire shapes — the live
+// ADR 0116 (R01) envelope `{ error: { code, message } }` and the legacy flat
+// `{ error: 'code' }`. Same normalization as claim.js:formatClaimFailure and
+// cli-lib:isBoxScope; pure + exported for tests/ship_post_land_verify.mjs.
+function normalizeApiError(data) {
+  const errRaw = data ? data.error : undefined;
+  const isEnvelope = errRaw !== null && typeof errRaw === 'object';
+  return {
+    code: isEnvelope ? errRaw.code : errRaw,
+    message: isEnvelope ? errRaw.message : undefined,
+  };
+}
+
+// task 1002809: classify a FAILED post-land POST /tasks/<id>/ship. The merge
+// already succeeded, so the server may simply have landed the task first
+// (reconcile-on-read — task 1049 — or the ~5-min reconciler racing this call).
+// The old check compared `data.error === 'task_not_confirmed'` — dead against
+// the envelope shape, so the already-landed SUCCESS rendered as a failure with
+// an "[object Object]" reason (the HANDOFF-apex-ui "400 after a successful
+// land" gotcha). liveStatus is the task's status from a verify GET (null when
+// that GET itself failed): 'shipped' is authoritative success whatever the
+// error said; task_not_confirmed with no live status keeps the task-1049
+// benefit of the doubt; any KNOWN non-shipped status stays a loud failure.
+// Pure + exported for tests/ship_post_land_verify.mjs.
+function postLandShipOutcome({ code, liveStatus }) {
+  if (liveStatus === 'shipped') {
+    return { alreadyShipped: true, why: 'the server landed it first — the failed ship call lost that race, nothing to fix' };
+  }
+  if (liveStatus == null && code === 'task_not_confirmed') {
+    return { alreadyShipped: true, why: 'the server reconciled it from the merged PR' };
+  }
+  return { alreadyShipped: false };
+}
+
 // Step 3 of the lifecycle: confirmed → shipped. Merge the branch into main,
 // deploy, flip the task to shipped, and fire the Discord broadcast (only when
 // the change actually deploys — #94 / ADR 0032; best-effort). Side-effecting;
@@ -3146,17 +3180,26 @@ async function mergeAndDeploy({ taskId, summary, advanceToMerge, skipMerge, dbOn
 
   const ship = await (await cliClient()).tasks.postTasksIdShip({ id: taskId, body: {} });
   if (!ship.ok) {
-    // task 1049: the server's publish-status reconcile-on-read may have already
-    // flipped this task to shipped (a concurrent status read saw merge+deploy).
-    // That's a SUCCESS — don't print it as a failure.
-    if (ship.status === 409 && ship.data && ship.data.error === 'task_not_confirmed') {
-      console.log(`Task #${taskId} is now: shipped (the server reconciled it from the merged PR).`);
+    // task 1049 / 1002809: the server may have already flipped this task to
+    // shipped (reconcile-on-read, or the reconciler racing this call). Verify
+    // the LIVE status before treating the refusal as a failure — the old
+    // flat-shape string check never matched the R01 envelope, so this success
+    // path was dead and every reconciled land reported as a failed ship.
+    const { code, message } = normalizeApiError(ship.data);
+    let liveStatus = null;
+    try {
+      const t = await (await cliClient()).tasks.getTasksId({ id: taskId });
+      if (t.ok && t.data && t.data.task) liveStatus = t.data.task.status;
+    } catch (_) { /* verify is best-effort; fall back to the code-based call */ }
+    const outcome = postLandShipOutcome({ code, liveStatus });
+    if (outcome.alreadyShipped) {
+      console.log(`Task #${taskId} is now: shipped (${outcome.why}).`);
     } else {
-      console.error(`  /tasks/${taskId}/ship failed:`, ship.data);
+      const e = message || code || `HTTP ${ship.status}`;
+      console.error(`  /tasks/${taskId}/ship failed: ${e}${liveStatus ? ` (task is at '${liveStatus}')` : ''}`);
       // The merge itself succeeded — only the status flip failed, so a re-run
       // resumes cleanly (task 941). Report it rather than letting the card claim
       // the land is in progress.
-      const e = (ship.data && (ship.data.message || ship.data.error)) || `HTTP ${ship.status}`;
       return landBailed(`merged, but the ship call failed — ${e}`, `node scripts/gds/ship.js ${taskId}`);
     }
   } else {
@@ -4418,6 +4461,8 @@ module.exports = {
   // task 1049 (B): pure CI-land outcome classifier — a timed-out-but-armed PR is
   // 'pending' (success), not failure. Exported so the semantics are unit-tested.
   classifyLandOutcome,
+  normalizeApiError,
+  postLandShipOutcome,
   // task 1718: pure poll-path decision — enable-failure polls the SERVER (not a
   // dead-end strand at confirmed), enable-success watches GitHub. Exported so the
   // regression test locks in that a worktree enable-failure still waits for the land.

package/scripts/gds/worktree.js

@@ -0,0 +1,252 @@
+#!/usr/bin/env node
+// scripts/gds/worktree.js — junction-safe worktree lifecycle (task 1002809).
+//
+// The trap this kills: a worktree OUTSIDE the repo root (C:/tmp/wt-N — used to
+// dodge OneDrive file locks) can't resolve node_modules by walking up, so
+// Windows builders hand-made junctions with `cmd //c mklink` from Git Bash —
+// which mangles quoted targets containing spaces (dead junction) — and then
+// `git worktree remove` FOLLOWED the junction and deleted the SHARED
+// node_modules of the main checkout. This helper creates junctions with
+// fs.symlinkSync(..., 'junction') (no shell, no quoting) and always removes the
+// junction BEFORE git worktree remove. Worktrees INSIDE the repo
+// (.claude/worktrees/<name>, the project default) need no junction at all.
+//
+// Usage:
+//   node scripts/gds/worktree.js add <task-id|name> [--path <dir> | --outside] [--base <ref>]
+//   node scripts/gds/worktree.js remove <name|path> [--force]
+//   node scripts/gds/worktree.js list
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { arg, hasFlag } = require('./cli-lib');
+
+// -- pure helpers (exported for tests/worktree_helper.mjs) --------------------
+
+// A numeric task id becomes the conventional task-<id>; an explicit name passes
+// through; anything with path separators or dot-traversal is rejected (null).
+function worktreeNameFor(raw) {
+  const s = String(raw == null ? '' : raw).trim();
+  if (!s || s === '.' || s === '..') return null;
+  if (/^\d+$/.test(s)) return `task-${s}`;
+  if (!/^[A-Za-z0-9._-]+$/.test(s)) return null;
+  return s;
+}
+
+// Is the worktree OUTSIDE the repo root? Inside the repo, node's resolution
+// walks up to the main checkout's node_modules; outside it can't. Pure string
+// compare (case-insensitive, both slash styles); callers pass absolute paths.
+function isOutsideRepo({ wtPath, repoRoot }) {
+  const norm = (p) => String(p).replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  const wt = norm(wtPath);
+  const root = norm(repoRoot);
+  return !(wt === root || wt.startsWith(root + '/'));
+}
+
+// Only a win32 worktree outside the repo root gets a junction (the OneDrive
+// dodge); posix symlink semantics differ and aren't the trap this fixes.
+function needsJunction({ wtPath, repoRoot, platform }) {
+  if (platform !== 'win32') return false;
+  return isOutsideRepo({ wtPath, repoRoot });
+}
+
+// Ordered removal steps. The junction MUST go before git worktree remove (git
+// follows it into the shared node_modules); a REAL node_modules dir is left for
+// git to refuse — this tool never deletes real directories.
+function removalPlan({ nodeModulesState }) {
+  return nodeModulesState === 'junction'
+    ? ['unlink-junction', 'git-worktree-remove']
+    : ['git-worktree-remove'];
+}
+
+// -- CLI ----------------------------------------------------------------------
+
+function git(args, opts = {}) {
+  return execFileSync('git', args, { encoding: 'utf8', ...opts }).trim();
+}
+
+// Main checkout root from any worktree — same derivation as merge-lock.js.
+function mainWorktreeRoot() {
+  const common = git(['rev-parse', '--git-common-dir']);
+  const abs = path.isAbsolute(common) ? common : path.resolve(process.cwd(), common);
+  return path.dirname(abs);
+}
+
+function listWorktrees(root) {
+  const out = git(['worktree', 'list', '--porcelain'], { cwd: root });
+  return out.split('\n').filter((l) => l.startsWith('worktree ')).map((l) => l.slice('worktree '.length));
+}
+
+function nodeModulesState(wtPath) {
+  const p = path.join(wtPath, 'node_modules');
+  let st;
+  try { st = fs.lstatSync(p); } catch (_) { return 'absent'; }
+  return st.isSymbolicLink() ? 'junction' : 'real-dir';
+}
+
+function resolveWorktreePath(root, nameOrPath) {
+  const all = listWorktrees(root);
+  const norm = (p) => path.resolve(p).replace(/\\/g, '/').toLowerCase();
+  const byPath = all.find((w) => norm(w) === norm(nameOrPath));
+  if (byPath) return byPath;
+  // Case-insensitive, matching the filesystem (and the byPath compare above).
+  const byName = all.filter((w) => path.basename(w).toLowerCase() === String(nameOrPath).toLowerCase());
+  if (byName.length === 1) return byName[0];
+  if (byName.length > 1) {
+    console.error(`worktree: "${nameOrPath}" matches ${byName.length} worktrees — pass the full path:`);
+    for (const w of byName) console.error(`  ${w}`);
+    process.exit(2);
+  }
+  return null;
+}
+
+function cmdAdd(root, argv) {
+  const name = worktreeNameFor(argv[1]);
+  if (!name) {
+    console.error('worktree add: pass a task id (→ task-<id>) or a simple name (letters/digits/._-).');
+    process.exit(2);
+  }
+  const explicitPath = arg('--path', argv);
+  const outside = hasFlag('--outside', argv);
+  // --outside exists to dodge OneDrive file locks — a Windows problem. On posix
+  // an outside-repo worktree would just lose node_modules resolution (no
+  // junction is created there), so refuse rather than hand back a silently
+  // broken tree; the in-repo default works everywhere.
+  if (outside && process.platform !== 'win32') {
+    console.error('worktree add: --outside is a Windows OneDrive dodge; use the default in-repo location here');
+    console.error('  (an outside-repo worktree on this platform cannot resolve the shared node_modules).');
+    process.exit(2);
+  }
+  const wtPath = path.resolve(explicitPath
+    || (outside ? path.join('C:/tmp', name)
+                : path.join(root, '.claude', 'worktrees', name)));
+  // Default base origin/main so the branch starts current; best-effort fetch
+  // first (offline still works off the local ref).
+  const base = arg('--base', argv) || 'origin/main';
+  try { execFileSync('git', ['fetch', 'origin', 'main'], { cwd: root, stdio: 'ignore', timeout: 15000 }); } catch (_) { /* offline is fine */ }
+
+  console.log(`worktree add: ${wtPath}  (branch ${name}, base ${base})`);
+  try {
+    execFileSync('git', ['worktree', 'add', wtPath, '-b', name, base], { cwd: root, stdio: 'inherit' });
+  } catch (e) {
+    console.error(`worktree add failed — ${e.message}`);
+    console.error('  (a branch of that name may already exist: remove it or pick another name)');
+    process.exit(1);
+  }
+
+  if (needsJunction({ wtPath, repoRoot: root, platform: process.platform })) {
+    const target = path.join(root, 'node_modules');
+    if (!fs.existsSync(target)) {
+      console.error(`⚠ ${target} does not exist — run npm install in the MAIN checkout first`);
+      console.error('  (worktrees never get their own node_modules; they share the main one).');
+    } else {
+      // fs.symlinkSync with type 'junction' needs no shell and no elevation —
+      // this is the fix for the mangled `cmd //c mklink` quoting trap.
+      fs.symlinkSync(target, path.join(wtPath, 'node_modules'), 'junction');
+      console.log(`  node_modules junction → ${target}`);
+      console.log('  (remove this worktree with `node scripts/gds/worktree.js remove` — it unlinks the junction first;');
+      console.log('   a bare `git worktree remove` would follow the junction into the SHARED node_modules.)');
+    }
+  } else if (isOutsideRepo({ wtPath, repoRoot: root })) {
+    // Explicit --path outside the repo on posix: no junction is created here,
+    // so say plainly that node_modules won't resolve rather than fail later.
+    console.log('  ⚠ this worktree is outside the repo — node_modules will NOT resolve from here on this platform.');
+  }
+  console.log('');
+  console.log('Next:');
+  console.log(`  cd "${wtPath}"`);
+  console.log('  node scripts/gds/claim.js <task-id>   (worktree auto-detected)');
+}
+
+function cmdRemove(root, argv) {
+  const target = argv[1];
+  if (!target) {
+    console.error('usage: node scripts/gds/worktree.js remove <name|path> [--force]');
+    process.exit(2);
+  }
+  const wtPath = resolveWorktreePath(root, target);
+  if (!wtPath) {
+    console.error(`worktree remove: "${target}" is not a registered worktree (see: git worktree list).`);
+    process.exit(1);
+  }
+  if (path.resolve(wtPath).toLowerCase() === path.resolve(root).toLowerCase()) {
+    console.error('worktree remove: refusing to remove the MAIN checkout.');
+    process.exit(2);
+  }
+  const state = nodeModulesState(wtPath);
+  for (const step of removalPlan({ nodeModulesState: state })) {
+    if (step === 'unlink-junction') {
+      // rmdir on a junction removes the LINK only, never the target's contents.
+      fs.rmdirSync(path.join(wtPath, 'node_modules'));
+      console.log('  removed node_modules junction (link only — the shared node_modules is untouched)');
+    } else {
+      const args = ['worktree', 'remove', ...(hasFlag('--force', argv) ? ['--force'] : []), wtPath];
+      try {
+        execFileSync('git', args, { cwd: root, stdio: 'inherit' });
+        console.log(`worktree removed: ${wtPath}`);
+      } catch (e) {
+        // OneDrive briefly locks the dir; the failed attempt usually still
+        // DEREGISTERS the worktree — verify instead of fighting it with retries.
+        const still = listWorktrees(root).some((w) => path.resolve(w).toLowerCase() === path.resolve(wtPath).toLowerCase());
+        if (!still) {
+          console.log(`worktree deregistered: ${wtPath}`);
+          console.log('  (the directory husk is briefly locked — OneDrive — and deletes on its own later)');
+        } else {
+          console.error(`worktree remove failed — ${e.message}`);
+          // The worktree is still live but its junction is already unlinked —
+          // restore it so the tree stays usable (node_modules keeps resolving)
+          // instead of stranding the builder back at hand-rolled mklink.
+          if (state === 'junction') {
+            try {
+              fs.symlinkSync(path.join(root, 'node_modules'), path.join(wtPath, 'node_modules'), 'junction');
+              console.error('  node_modules junction restored — the worktree remains fully usable.');
+            } catch (restoreErr) {
+              console.error(`  could not restore the node_modules junction (${restoreErr.message}) —`);
+              console.error('  re-create it: node -e "require(\'fs\').symlinkSync(\'<main>/node_modules\', \'<wt>/node_modules\', \'junction\')"');
+            }
+          }
+          if (state === 'real-dir') {
+            console.error('  node_modules here is a REAL directory (not a junction) — if it and the other');
+            console.error('  untracked files are disposable, re-run with --force.');
+          } else {
+            console.error('  re-run with --force if the leftover untracked files are disposable.');
+          }
+          process.exit(1);
+        }
+      }
+    }
+  }
+  console.log(`  (branch "${path.basename(wtPath)}" left in place — the land/ship pipeline owns branch cleanup)`);
+}
+
+function cmdList(root) {
+  const all = listWorktrees(root);
+  for (const w of all) {
+    const isMain = path.resolve(w).toLowerCase() === path.resolve(root).toLowerCase();
+    const tag = isMain ? 'main checkout' : `node_modules: ${nodeModulesState(w)}`;
+    console.log(`${w}   [${tag}]`);
+  }
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  let root;
+  try {
+    root = mainWorktreeRoot();
+  } catch (e) {
+    console.error('worktree: not a git repo (cannot resolve the main checkout):', e.message);
+    process.exit(2);
+  }
+  if (cmd === 'add') return cmdAdd(root, argv);
+  if (cmd === 'remove') return cmdRemove(root, argv);
+  if (cmd === 'list') return cmdList(root);
+  console.error('usage: node scripts/gds/worktree.js add <task-id|name> [--path <dir> | --outside] [--base <ref>]');
+  console.error('       node scripts/gds/worktree.js remove <name|path> [--force]');
+  console.error('       node scripts/gds/worktree.js list');
+  process.exit(2);
+}
+
+if (require.main === module) main();
+
+module.exports = { worktreeNameFor, needsJunction, removalPlan, nodeModulesState };

package/src/module-api.js

@@ -665,8 +665,12 @@ const { validateOrRespond, LIMITS, parseId, asyncHandler, corsPublicGet, parsePa
 //         landed since 1.19.117 with no explicit bump. run 31833658900. (task 1002620)
 //   1.19.119 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
 //         landed since 1.19.118 with no explicit bump. run 31835957309. (task 1002620)
+//   1.19.120 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.119 with no explicit bump. run 31836959112. (task 1002620)
+//   1.19.121 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+//         landed since 1.19.120 with no explicit bump. run 31838955115. (task 1002620)
 // ---------------------------------------------------------------------------
-const CORE_VERSION = '1.19.119'; // CI auto-patch carrier (ADR 0161); see changelog above
+const CORE_VERSION = '1.19.121'; // CI auto-patch carrier (ADR 0161); see changelog above
 
 // A namespaced logger so a module's log lines are attributable + consistent.
 // Usage: const log = api.logger('dev-box'); log.info('mounted');

package/tests/api_msys_path_repair.mjs

@@ -0,0 +1,104 @@
+// tests/api_msys_path_repair.mjs
+//
+// Unit tests for repairMsysMangledPath (task 1002809). Git Bash (MSYS) rewrites
+// a leading-slash argument into a Windows path under the Git install root before
+// node ever sees it — `/tasks/123` arrives as `C:/Program Files/Git/tasks/123` —
+// unless the builder remembers MSYS_NO_PATHCONV=1. api.js undoes that mangling
+// itself so no builder needs the env prefix.
+//
+// Contract proved here:
+//   1. A path that already starts with '/' is returned untouched (the repair is
+//      a no-op everywhere the shell behaved).
+//   2. A mangled path is repaired by stripping the LONGEST ancestor of EXEPATH
+//      that prefixes it — EXEPATH is `<git-root>\bin` while the msys root that
+//      prefixes mangled args is `<git-root>`, so ancestor-walking is required.
+//   3. The drive root alone is never treated as the msys root (stripping `C:/`
+//      would "repair" any Windows path into nonsense).
+//   4. Non-win32, missing EXEPATH, and unrelated Windows paths pass through.
+//
+// Run:  node tests/api_msys_path_repair.mjs
+
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import { fileURLToPath } from 'node:url';
+
+const require = createRequire(import.meta.url);
+const { repairMsysMangledPath } = require('../scripts/gds/cli-lib.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed++;
+    console.log(`  FAIL ${name}`);
+    console.log(`     ${err.message}`);
+  }
+}
+function eq(actual, expected, msg) {
+  if (actual !== expected) throw new Error(`${msg || 'mismatch'}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+}
+
+const GIT_BASH = { exepath: 'C:\\Program Files\\Git\\bin', platform: 'win32' };
+
+test('already-correct path is untouched', () => {
+  eq(repairMsysMangledPath('/api/gds/inbox', GIT_BASH), '/api/gds/inbox');
+  eq(repairMsysMangledPath('/tasks/1002809', GIT_BASH), '/tasks/1002809');
+});
+
+test('mangled path is repaired via EXEPATH ancestor (forward slashes)', () => {
+  eq(repairMsysMangledPath('C:/Program Files/Git/tasks/1002809', GIT_BASH), '/tasks/1002809');
+  eq(repairMsysMangledPath('C:/Program Files/Git/api/gds/inbox', GIT_BASH), '/api/gds/inbox');
+});
+
+test('mangled path with backslashes is repaired and normalized', () => {
+  eq(repairMsysMangledPath('C:\\Program Files\\Git\\claims', GIT_BASH), '/claims');
+});
+
+test('prefix match is case-insensitive (Windows paths are)', () => {
+  eq(repairMsysMangledPath('c:/program files/git/tasks/5', GIT_BASH), '/tasks/5');
+});
+
+test('longest matching ancestor wins (a legit /Git/... path survives)', () => {
+  // Original arg /Git/tasks/9 mangles to <root>/Git/tasks/9 — stripping the
+  // git root must give back /Git/tasks/9, not /tasks/9.
+  eq(repairMsysMangledPath('C:/Program Files/Git/Git/tasks/9', GIT_BASH), '/Git/tasks/9');
+});
+
+test('drive root alone is never stripped', () => {
+  // Root-level install: EXEPATH C:\Git\bin → msys root C:/Git is strippable...
+  eq(repairMsysMangledPath('C:/Git/tasks/7', { exepath: 'C:\\Git\\bin', platform: 'win32' }), '/tasks/7');
+  // ...but C:/ by itself is not a valid msys root — an unrelated Windows path
+  // must pass through unchanged, not get "repaired" into /tmp/x.json.
+  eq(repairMsysMangledPath('C:/tmp/x.json', GIT_BASH), 'C:/tmp/x.json');
+});
+
+test('non-win32 platform passes through', () => {
+  eq(repairMsysMangledPath('C:/Program Files/Git/tasks/1', { exepath: 'C:\\Program Files\\Git\\bin', platform: 'linux' }), 'C:/Program Files/Git/tasks/1');
+});
+
+test('missing EXEPATH passes through (empty = not a Git Bash shell)', () => {
+  eq(repairMsysMangledPath('C:/Program Files/Git/tasks/1', { exepath: '', platform: 'win32' }), 'C:/Program Files/Git/tasks/1');
+});
+
+test('empty/undefined input passes through', () => {
+  eq(repairMsysMangledPath('', GIT_BASH), '');
+  eq(repairMsysMangledPath(undefined, GIT_BASH), undefined);
+});
+
+// Static wiring check (the cli_exit_no_abort.mjs pattern): the pure helper being
+// correct is worthless if api.js stops applying it to its positional path arg —
+// that exact mutation survived every behavioural test here.
+test('api.js applies the repair to process.argv[3] (static)', () => {
+  const src = fs.readFileSync(fileURLToPath(new URL('../scripts/gds/api.js', import.meta.url)), 'utf8');
+  if (!/repairMsysMangledPath\(\s*process\.argv\[3\]\s*\)/.test(src)) {
+    throw new Error('api.js no longer wraps process.argv[3] in repairMsysMangledPath(...)');
+  }
+});
+
+console.log('');
+console.log(`api_msys_path_repair: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/tests/ship_post_land_verify.mjs

@@ -0,0 +1,114 @@
+// tests/ship_post_land_verify.mjs
+//
+// Unit tests for the post-land ship-call outcome (task 1002809). After a
+// successful merge, ship.js POSTs /tasks/<id>/ship; the server may have landed
+// the task first (reconcile-on-read, or the ~5-min reconciler racing this call),
+// in which case it refuses with task_not_confirmed. The old code compared
+// `ship.data.error === 'task_not_confirmed'` — the legacy FLAT shape — but the
+// live server emits the ADR 0116 (R01) envelope `{ error: { code, … } }`, so the
+// string test never matched and an already-landed SUCCESS rendered as
+// "merged, but the ship call failed — [object Object]" (the HANDOFF-apex-ui
+// '400 task_not_confirmed AFTER a successful land' gotcha). Same bug class as
+// claim.js task 1476 / cli-lib isBoxScope task 1002162.
+//
+// What we prove here (pure helpers only — the live GET verify is exercised by
+// every real ship):
+//   1. normalizeApiError reads BOTH body shapes (envelope + flat) and survives
+//      missing/odd bodies.
+//   2. postLandShipOutcome: a live status of 'shipped' is SUCCESS whatever the
+//      error code or HTTP status was (the GET verify is authoritative).
+//   3. task_not_confirmed with the verify GET unavailable keeps the task-1049
+//      benefit-of-the-doubt success (the server reconciled it).
+//   4. A known live status that is NOT shipped stays a loud failure — never
+//      paper over a genuinely stranded task.
+//
+// Run:  node tests/ship_post_land_verify.mjs
+
+import { createRequire } from 'node:module';
+
+const require = createRequire(import.meta.url);
+const ship = require('../scripts/gds/ship.js');
+const { normalizeApiError, postLandShipOutcome } = ship;
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed++;
+    console.log(`  FAIL ${name}`);
+    console.log(`     ${err.message}`);
+  }
+}
+function eq(actual, expected, msg) {
+  if (actual !== expected) throw new Error(`${msg || 'mismatch'}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+}
+
+// ---- 1. normalizeApiError: both wire shapes ----
+
+test('normalizeApiError reads the R01 envelope', () => {
+  const { code, message } = normalizeApiError({ error: { code: 'task_not_confirmed', message: 'not at confirmed' } });
+  eq(code, 'task_not_confirmed');
+  eq(message, 'not at confirmed');
+});
+
+test('normalizeApiError reads the legacy flat shape', () => {
+  const { code, message } = normalizeApiError({ error: 'task_not_confirmed' });
+  eq(code, 'task_not_confirmed');
+  eq(message, undefined);
+});
+
+test('normalizeApiError survives missing/odd bodies', () => {
+  eq(normalizeApiError(null).code, undefined);
+  eq(normalizeApiError({}).code, undefined);
+  eq(normalizeApiError({ error: { message: 'no code' } }).message, 'no code');
+});
+
+test('normalizeApiError survives { error: null } (typeof null is object)', () => {
+  eq(normalizeApiError({ error: null }).code, null);
+  eq(normalizeApiError({ error: null }).message, undefined);
+});
+
+// ---- 2. live status 'shipped' is success regardless of code/status ----
+
+test('verified shipped ⇒ success even on an unexpected code', () => {
+  const out = postLandShipOutcome({ code: 'internal_error', liveStatus: 'shipped' });
+  eq(out.alreadyShipped, true);
+  if (!out.why || typeof out.why !== 'string') throw new Error('expected a human why-line');
+});
+
+test('verified shipped ⇒ success on task_not_confirmed (409 or 400 alike)', () => {
+  eq(postLandShipOutcome({ code: 'task_not_confirmed', liveStatus: 'shipped' }).alreadyShipped, true);
+});
+
+// ---- 3. verify GET unavailable: keep the task-1049 reconcile success ----
+
+test('task_not_confirmed with no live status keeps the reconciled success', () => {
+  const out = postLandShipOutcome({ code: 'task_not_confirmed', liveStatus: null });
+  eq(out.alreadyShipped, true);
+  // The why feeds `shipped (${why})` directly — an absent why prints
+  // "shipped (undefined)", the same garbage-output class this task fixes.
+  if (!out.why || typeof out.why !== 'string') throw new Error('expected a human why-line');
+});
+
+test('an unknown code with no live status is a failure (no blind success)', () => {
+  eq(postLandShipOutcome({ code: 'internal_error', liveStatus: null }).alreadyShipped, false);
+});
+
+// ---- 4. a known non-shipped status stays a loud failure ----
+
+test('task_not_confirmed but live status confirmed ⇒ failure, not success', () => {
+  const out = postLandShipOutcome({ code: 'task_not_confirmed', liveStatus: 'confirmed' });
+  eq(out.alreadyShipped, false);
+});
+
+test('task_not_confirmed but live status completed ⇒ failure', () => {
+  eq(postLandShipOutcome({ code: 'task_not_confirmed', liveStatus: 'completed' }).alreadyShipped, false);
+});
+
+console.log('');
+console.log(`ship_post_land_verify: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);

package/tests/worktree_helper.mjs

@@ -0,0 +1,145 @@
+// tests/worktree_helper.mjs
+//
+// Unit tests for the pure decision helpers behind scripts/gds/worktree.js
+// (task 1002809) — the junction-safe worktree lifecycle for Windows builders.
+//
+// The trap this tooling kills: a worktree OUTSIDE the repo root (C:/tmp/wt-N,
+// used to dodge OneDrive locks) needs a node_modules junction back to the main
+// checkout; `cmd //c mklink` from Git Bash mangles quoted targets with spaces
+// (dead junction), and `git worktree remove` FOLLOWS the junction and deletes
+// the SHARED node_modules. The helper creates junctions with
+// fs.symlinkSync(..., 'junction') (no shell involved) and always removes the
+// junction BEFORE git worktree remove.
+//
+// What we prove here:
+//   1. worktreeNameFor: a numeric task id becomes task-<id>; an explicit name
+//      passes through; junk is rejected.
+//   2. needsJunction: only win32 AND a path outside the repo root.
+//   3. removalPlan: a junction is unlinked BEFORE git worktree remove; a real
+//      node_modules dir is never touched by us (git refuses; we surface that);
+//      absent node_modules goes straight to git worktree remove.
+//
+// Run:  node tests/worktree_helper.mjs
+
+import { createRequire } from 'node:module';
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+const require = createRequire(import.meta.url);
+const { worktreeNameFor, needsJunction, removalPlan, nodeModulesState } = require('../scripts/gds/worktree.js');
+
+let passed = 0;
+let failed = 0;
+function test(name, fn) {
+  try {
+    fn();
+    passed++;
+    console.log(`  ok  ${name}`);
+  } catch (err) {
+    failed++;
+    console.log(`  FAIL ${name}`);
+    console.log(`     ${err.message}`);
+  }
+}
+function eq(actual, expected, msg) {
+  if (actual !== expected) throw new Error(`${msg || 'mismatch'}: expected ${JSON.stringify(expected)}, got ${JSON.stringify(actual)}`);
+}
+function eqArr(actual, expected, msg) {
+  eq(JSON.stringify(actual), JSON.stringify(expected), msg);
+}
+
+// ---- 1. worktreeNameFor ----
+
+test('numeric task id becomes task-<id>', () => {
+  eq(worktreeNameFor('1002809'), 'task-1002809');
+});
+
+test('an explicit task-N name passes through', () => {
+  eq(worktreeNameFor('task-77'), 'task-77');
+});
+
+test('a plain name passes through', () => {
+  eq(worktreeNameFor('spike-tiles'), 'spike-tiles');
+});
+
+test('junk (path separators, empty) is rejected with null', () => {
+  eq(worktreeNameFor('a/b'), null);
+  eq(worktreeNameFor('..'), null);
+  eq(worktreeNameFor(''), null);
+});
+
+// ---- 2. needsJunction ----
+
+const REPO = 'C:\\Users\\rocke\\OneDrive\\Desktop\\Cloud Bongos\\cloud-bongos';
+
+test('outside-repo worktree on win32 needs a junction', () => {
+  eq(needsJunction({ wtPath: 'C:\\tmp\\task-9', repoRoot: REPO, platform: 'win32' }), true);
+});
+
+test('inside-repo worktree resolves node_modules by walking up — no junction', () => {
+  eq(needsJunction({ wtPath: REPO + '\\.claude\\worktrees\\task-9', repoRoot: REPO, platform: 'win32' }), false);
+});
+
+test('non-win32 never gets a junction (symlink semantics differ; not the trap)', () => {
+  eq(needsJunction({ wtPath: '/tmp/task-9', repoRoot: '/home/u/repo', platform: 'linux' }), false);
+});
+
+test('a sibling dir that merely shares the repo prefix is still outside', () => {
+  eq(needsJunction({ wtPath: REPO + '-other\\task-9', repoRoot: REPO, platform: 'win32' }), true);
+});
+
+test('path compare is case-insensitive (Windows filesystems are)', () => {
+  eq(needsJunction({ wtPath: REPO.toUpperCase() + '\\.CLAUDE\\WORKTREES\\TASK-9', repoRoot: REPO, platform: 'win32' }), false);
+  eq(needsJunction({ wtPath: 'c:\\TMP\\task-9', repoRoot: REPO, platform: 'win32' }), true);
+});
+
+// ---- 2b. nodeModulesState — the classifier that picks the removal order ----
+// Behavioural, against a real scratch dir: a dir-symlink stands in for the
+// junction (node's lstat reports both as symbolic links, on every platform).
+
+test('nodeModulesState: absent / real-dir / junction classified from disk', () => {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-helper-test-'));
+  try {
+    eq(nodeModulesState(path.join(base, 'wt-absent')), 'absent');
+
+    const wtReal = path.join(base, 'wt-real');
+    fs.mkdirSync(path.join(wtReal, 'node_modules'), { recursive: true });
+    eq(nodeModulesState(wtReal), 'real-dir');
+
+    const target = path.join(base, 'shared-nm');
+    fs.mkdirSync(target);
+    fs.writeFileSync(path.join(target, 'canary.txt'), 'x');
+    const wtJct = path.join(base, 'wt-junction');
+    fs.mkdirSync(wtJct);
+    const link = path.join(wtJct, 'node_modules');
+    fs.symlinkSync(target, link, 'junction');
+    eq(nodeModulesState(wtJct), 'junction');
+
+    // Removing the link (the helper's unlink step) must not touch the target.
+    // win32 junctions need rmdir; a posix dir-symlink needs unlink — cover both
+    // so this file passes on Linux CI and the real Windows box alike.
+    try { fs.rmdirSync(link); } catch (_) { fs.unlinkSync(link); }
+    eq(fs.existsSync(path.join(target, 'canary.txt')), true, 'target survives link removal');
+  } finally {
+    fs.rmSync(base, { recursive: true, force: true });
+  }
+});
+
+// ---- 3. removalPlan — junction-first ordering is the whole point ----
+
+test('junction node_modules: unlink FIRST, then git worktree remove', () => {
+  eqArr(removalPlan({ nodeModulesState: 'junction' }), ['unlink-junction', 'git-worktree-remove']);
+});
+
+test('absent node_modules: straight to git worktree remove', () => {
+  eqArr(removalPlan({ nodeModulesState: 'absent' }), ['git-worktree-remove']);
+});
+
+test('a REAL node_modules dir is left for git to refuse — we never rm it', () => {
+  eqArr(removalPlan({ nodeModulesState: 'real-dir' }), ['git-worktree-remove']);
+});
+
+console.log('');
+console.log(`worktree_helper: ${passed} passed, ${failed} failed`);
+process.exit(failed > 0 ? 1 : 0);