@bongos/core 1.19.685 → 1.19.687

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.685",
-  "core_contract": "1.19.685",
-  "source_commit": "b1f9d9ab3a9892d6ccca5a2624ffbe732f23b98b",
+  "core_version": "1.19.687",
+  "core_contract": "1.19.687",
+  "source_commit": "80529e693e8b33d02d80143fce82b5300e5f0c01",
   "source_ref": "HEAD",
-  "built_at": "2026-09-12T21:13:17.682Z",
+  "built_at": "2026-09-12T23:13:15.800Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 477,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2626,
-  "tree_sha256": "39b75c53e1b9736b4820105974401f9c9a67a3b5ed629b7434c0272f0a64d5eb",
+  "tree_sha256": "c85f4828bf21b1e106dfef13e6d603ea2774214cacdaf87ddbdb7f4242506e5c",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -2802,7 +2802,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "aa474c62aed632c8ff75731a38bf22b286866cb6aa30953a64f2ea46e3c83ee2"
+      "sha256": "f596cd52ec02d7e08108da8ce76a21a085aa1455989496d6a8501d1d7955ec5a"
     },
     {
       "path": "docs/modules-contract.md",
@@ -3067,7 +3067,7 @@
     {
       "path": "docs/recipes/windows-builders.md",
       "mode": "0000644",
-      "sha256": "b7d849d1786c7eca4156969d38343425839bef3bae19a10a94b5e54916e3ea09"
+      "sha256": "e5bcc0b4da0755546cb10870052099def2745c890cd8157d36d997e58a0399b3"
     },
     {
       "path": "docs/recipes/work-on-a-task-from-your-dev-box.md",
@@ -5872,7 +5872,7 @@
     {
       "path": "modules/lifecycle/routes/claims.js",
       "mode": "0000644",
-      "sha256": "8a4f6d5513b97e84c44695b88e42c6e5bdc1875e97202be41caf6c739b2fa42e"
+      "sha256": "9d4625ddaaa79e8496e05980153aca1a171d79aad3a32f1711be60be3be05955"
     },
     {
       "path": "modules/lifecycle/routes/closeness.js",
@@ -7377,7 +7377,7 @@
     {
       "path": "modules/ui-design/adapters/figma/index.js",
       "mode": "0000644",
-      "sha256": "859a23a1a10fe74717b37a4c86962750b7fd6d13b56ed801f6e217a245fea956"
+      "sha256": "d550b2604b8e54247482e740dbeea8609cc7a981911ab25f8597ba04e8924059"
     },
     {
       "path": "modules/ui-design/docs/design-contract.md",
@@ -7782,12 +7782,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "e1896f085954a25abf57b98c3e16dc53825a88f657cb70f0839e65cf45960cdc"
+      "sha256": "ad18930429a58c935061b8269dfea3c2fcbb1095eeff26859158679b9faf37d3"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "4f32692ff1a262f499c156645e05890e5814346a1ddbe081846bfbebaf3c6f20"
+      "sha256": "f4d3a3c0536c755502e2f9bafaf07a54fda378a3394b22e0a3a3368992300073"
     },
     {
       "path": "public-docs/index.html",
@@ -7997,7 +7997,7 @@
     {
       "path": "scripts/gds/build-cli-package.js",
       "mode": "0000644",
-      "sha256": "e24710d5546428beba9400831d69eb3101e76bfdb1083916bf12411839e16735"
+      "sha256": "fae58783ca4514ffd3d9d78046148817f5ef3995a9a5805033af0159143d0651"
     },
     {
       "path": "scripts/gds/bump-version.js",
@@ -8712,7 +8712,7 @@
     {
       "path": "scripts/gds/sandbox-stage.js",
       "mode": "0000644",
-      "sha256": "327528f90554c2c60ae9e2ad6a0d5dc177d33d918c34fa83f87fe80e0ca89cfc"
+      "sha256": "583373b1d72c0a98aaafa0b57ecfcb1011fa2df9109fe312fb2f1c70234ae0d8"
     },
     {
       "path": "scripts/gds/search-ingest-db.js",
@@ -9127,7 +9127,7 @@
     {
       "path": "scripts/gds/version-close.js",
       "mode": "0000644",
-      "sha256": "2db9a69b8a64873eee7cd473ce2915df51ccfffb79f289ec01e0419d2861ba3e"
+      "sha256": "dcb89000ad35647f2730479dea5596494e5e46eaafdc9407153541429f528fca"
     },
     {
       "path": "scripts/gds/version-literal-guard.js",
@@ -9547,7 +9547,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "50802a77ae69160c8c739f40a02cae66c61bfd200e3d9a6d6be4024baa382793"
+      "sha256": "c323740fa5182f9e2c200cdbd349d19753cf7d6f2faee9cf98ff44ba13249d2f"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9702,7 +9702,7 @@
     {
       "path": "tests/api_path_404.mjs",
       "mode": "0000644",
-      "sha256": "427f5750b4115fc0ddd30f6f7f8202521d5b31300b191093bc98f8416bb4a228"
+      "sha256": "82ca3700f6dd9d0aa88b39a0d6c45a03c20628201508b619e36a6d77ce0215ce"
     },
     {
       "path": "tests/app_pair.mjs",
@@ -10162,7 +10162,7 @@
     {
       "path": "tests/cli_package.mjs",
       "mode": "0000644",
-      "sha256": "a57516ed9e904cf1c86fe99688415f834dcae1a19f01b22e986f199fa5473258"
+      "sha256": "b81bf677dc884eef7bd88128d024e3eed1699faa31a680b7d5d4cfdbcd11b09c"
     },
     {
       "path": "tests/cli_sessions.mjs",
@@ -10337,7 +10337,7 @@
     {
       "path": "tests/cutover_codemod.mjs",
       "mode": "0000644",
-      "sha256": "827dbb19b8be01a5658b3079620ab977af211a7aaf5b7f82a488bb9715d720fb"
+      "sha256": "434130945232d2a6959281070e6dbee31697904b3455fb3fd09f198a64bb0e33"
     },
     {
       "path": "tests/dead_deps.mjs",
@@ -11492,7 +11492,7 @@
     {
       "path": "tests/lib_sh_resolution.mjs",
       "mode": "0000644",
-      "sha256": "fdefb4971d75dcf6ab1000323211a9fbe732508ae1a0a28c36b8087383ae797e"
+      "sha256": "56798073f73f3d2a51687d9312374ce9d91b6b3cdbe4e97b0637ad09c43dfd6f"
     },
     {
       "path": "tests/lifecycle-card.mjs",
@@ -11622,7 +11622,7 @@
     {
       "path": "tests/migrate_root_resolution.mjs",
       "mode": "0000644",
-      "sha256": "e5cfa24bb69d6fade0f2f8bffd668bbda9490aca335d301abcf6f79154b60690"
+      "sha256": "44a43e21b0dd84f58054fcb27a6cce6bd5674b459ec7ece20b75d3683ad11cba"
     },
     {
       "path": "tests/migration_allocation.mjs",
@@ -11702,7 +11702,7 @@
     {
       "path": "tests/module_loader.mjs",
       "mode": "0000644",
-      "sha256": "5d09d5ccedf777c55509dc98365b46c443848c854158ace66fa17c99ba538737"
+      "sha256": "1199e4b106bb7d4da988cf15cc8030d272eeb87cb9733d4943d200760a7ac90a"
     },
     {
       "path": "tests/module_manifest.mjs",
@@ -11772,7 +11772,7 @@
     {
       "path": "tests/next_number.mjs",
       "mode": "0000644",
-      "sha256": "56e2f23e4edbd87f86fde62c40995fe0eb3053925d18156e21fae8c39e1d1c05"
+      "sha256": "c57c0211709ab041ee895bbb4ade9f4b146b43147570bf282e6d6a808560db76"
     },
     {
       "path": "tests/npmrc.mjs",
@@ -12387,7 +12387,7 @@
     {
       "path": "tests/sandbox_stage.mjs",
       "mode": "0000644",
-      "sha256": "b499ea62cdc1a615e565ce7b0379b2cab83b9aaa8098361f94d3eb93ebc7f927"
+      "sha256": "9942d11ee2f72c23c648961d15e49375e5b030e2346f49050bef7238ca369109"
     },
     {
       "path": "tests/scouting_owner_access_and_reach.mjs",
@@ -12447,7 +12447,7 @@
     {
       "path": "tests/secret_box.mjs",
       "mode": "0000644",
-      "sha256": "886bf7096cbdb3b758010eb0ee24e15bd74033a7bff0064b742585440cdeee79"
+      "sha256": "1eb2218f483f63f28af363fb1f79cff6c79f3b83d5f152c004798e4fd3c5035d"
     },
     {
       "path": "tests/secret_gate.mjs",
@@ -12597,7 +12597,7 @@
     {
       "path": "tests/ship_automerge_injection.mjs",
       "mode": "0000644",
-      "sha256": "0bedb21617810cf1cddc04326049f4424e18589bcb926c69e96597d79bbcddd4"
+      "sha256": "54b21517cd2c2559c9f89383785e4383731b782d809ae80eeea3df15212a34df"
     },
     {
       "path": "tests/ship_base_flag.mjs",
@@ -12652,7 +12652,7 @@
     {
       "path": "tests/ship_preflight.mjs",
       "mode": "0000644",
-      "sha256": "5a8d5d5245191cc3b5847bbc819fd39d3eb1ab083a91bb2cee3d54bd8e77913a"
+      "sha256": "423238e35eea8b6dbeb0d0aae2eda3ee032b4dbe05eeba3786577b3105c92bca"
     },
     {
       "path": "tests/ship_premerge.mjs",

package/docs/module-api-changelog.md

@@ -1829,5 +1829,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.683 with no explicit bump. run 34718471740. (task 1002620)
   1.19.685 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.684 with no explicit bump. run 34719298791. (task 1002620)
+  1.19.686 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.685 with no explicit bump. run 34721104118. (task 1002620)
+  1.19.687 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.686 with no explicit bump. run 34724811506. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/windows-builders.md

@@ -83,10 +83,41 @@ check for you); the empty husk directory deletes on its own later. Don't fight i
 
 ## 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.
+A raw `node --test tests/*.mjs` has a **large stable failure baseline on Windows boxes** (mostly
+DB-backed tests with no local Postgres — the count drifts and is not worth recording). Run
+**`node scripts/gds/run-unit-tests.js`** instead: it is the DB-free gate CI actually runs, so its
+result means something locally.
+
+**That gate's Windows baseline as of task 1003529 (2026-09-12): 4 suites** — `sound_player`
+(task 1003628), `session_caps` (1003827), `skill_preflight` (1003754), `task_recommendations`
+(1003759) — **plus the 6 carried by task 1003848**: `cli_surface`, `module_api_lazy`,
+`search_index_poller`, `search_isolation`, `tool_scan_engine`, `security/mirror`. Everything else
+is green, and a red suite outside those ten is yours.
+
+`logger` is **not** on that list and needs no work: it was the whole of the old "missing deps in
+the worktree" family and task 1003616 fixed it on 2026-09-07 — see the walk-up section below.
+
+**Two of the ten are INTERMITTENT, so a green run does not mean fixed.** `session_caps` and
+`search_isolation` exit `3221226505` (`0xC0000409`, STATUS_STACK_BUFFER_OVERRUN) — the process
+dies during teardown *after* its assertions have all passed, so whether the suite counts them as
+failures depends on timing. Measured in task 1003529: `session_caps` passed inside a full
+`run-unit-tests.js` sweep and failed twice in a row when run on its own, minutes apart, with task
+1003827 still open and nothing on main having touched it. This is the `cliExit` class documented in
+[scripts/gds/CLAUDE.md](../../scripts/gds/CLAUDE.md) — a hard exit while handles are still closing.
+Do not mark either fixed on the strength of one green sweep, and do not let their noise cover a
+real regression: diff by name AND re-run the individual suite.
+
+Two warnings about that list, both paid for:
+
+- **It drifts in BOTH directions.** The measurement before it (2026-08-27, 25 suites) had 7
+  entries already fixed and was missing 6 that had since broken — so more than half of it was
+  wrong within a fortnight. Re-measure; never inherit a list.
+- **Compare NAMES, never counts**, and never bank a local red as "environmental" without a
+  by-name baseline run in a deps-installed `origin/main` worktree. A count that matches can hide
+  one suite fixed and another broken.
+
+The CI `unit` check on the PR is still the authoritative verdict — it tests the MERGE, not your
+branch, so a green branch can red the PR when a regenerated file goes stale against main.
 
 ## Never pipe `ship.js` through `head`/`tail`
 
@@ -124,6 +155,7 @@ you see a ship-call failure from older tooling, check `GET /tasks/<id>` before r
 - **Symptom:** `Cannot find module 'pg'` / `'express'`; `npm test` reports ~300 FAILED; 9 `npm install`s and 2 dead junctions in three days of transcripts.
 - **What the tooling does now:** SessionStart prints one `[otb] node_modules is missing …` line (from `scripts/gds/preflight.js`'s check) when neither the worktree nor the main checkout has it. Install ONCE in the main checkout (`npm ci`); inside-repo worktrees resolve from it.
 - **Rule:** when comparing a local run against CI, compare failing test NAMES against an untouched checkout of `origin/main`, never counts — a ~25-failure Windows baseline has masked real regressions (session logs 2026-08-14, 2026-08-19). `node scripts/gds/ship-check.js --tests` prints the names.
+- **The "a test can't find its dep inside a worktree" family is CLOSED — do not go looking for a worktree bootstrap to repair.** It had exactly one member, `tests/logger.mjs`, which required pino by an absolute `<root>/node_modules/pino`; task 1003616 changed it to a bare specifier with a `require.resolve` skip guard on 2026-09-07. Re-verified in task 1003529 from a fresh `.claude/worktrees/` worktree carrying no `node_modules` of its own: `logger` passes, and the whole gate resolves `pino`/`express` by walk-up to the main checkout. **The bug was never the missing `node_modules`** — an inside-repo worktree is not supposed to have one — it was the absolute path that stopped node walking up. A dep failure here means you are outside the repo (use `worktree.js add --outside`, which makes the junction) or the main checkout was never installed. Task 1003519 was a duplicate row for this same bug and is merged into 1003616.
 
 ## `tests/git_merge_regen.mjs` — when it reds, suspect `.gitattributes` first, not Windows
 
@@ -148,3 +180,36 @@ caught a real bug during task 1003548, so read its assertion before blaming the
 - Several hall files (`people.css`, `people.html`, `style.css`, the privacy spec) and every `.claude/skills/*/SKILL.md` are CRLF; `scripts/gds/*.js` and the tests are LF. An exact-string patch must detect the file's EOL before joining lines (`text.includes('\r\n') ? '\r\n' : '\n'`), or the find matches nothing and the edit is a silent no-op (session log 2026-08-24).
 - A `git diff --stat` that touches every line of a file you barely edited is an EOL flip — check with `git diff --stat --ignore-cr-at-eol`, and restore the original EOL before committing.
 - **`copy-inventory.js --check` no longer reds on line endings alone** (task 1003619). It used to: the generator emits LF and the check byte-compared that against a CRLF worktree file, so `/ship-check` showed one permanent red line on every Windows checkout while the committed content was already correct — and a builder who "fixed" it committed a whole-file CRLF diff. `docs/copy-inventory.md` is now pinned `text eol=lf` in `.gitattributes` (its `.json` sibling always was, via `*.json`), and the check compares EOL-blind so an already-CRLF worktree passes without a re-clone. If it reports STALE now, the content really is stale — regenerate, don't reach for `--ignore-cr-at-eol`. Note `*.md` is deliberately NOT pinned repo-wide; only that one generated artifact is.
+- **A freshness check compares CONTENT, so route it through `sameContent()`** (`scripts/gds/gen-freshness.js`) rather than `===` on file bytes. A pin is the wrong lever on its own: regenerating never clears a byte-wise red, because the write lands LF and git converts it back on the next checkout. `tests/gen_freshness.mjs` enforces this for the four gated generators; `tests/api_client.mjs` was outside that guard and reported the client STALE forever on Windows until task 1003529 (`index.d.ts` and `README.md` are the two generated client files with no `eol=lf` pin).
+
+## Four Windows traps that make a test lie — all four found in one pass (task 1003529)
+
+Four of the suites that pass turned green came back to **real product bugs, not test noise** —
+including `build-cli-package.js`, which could not build at all on Windows. When a suite fails only
+here, suspect these before assuming the platform is at fault:
+
+- **`fs.realpathSync` does NOT expand 8.3 short names; `fs.realpathSync.native` does.** Where TEMP
+  is a short path (`C:\Users\RUNNER~1\…`), `os.tmpdir()` keeps the short form while git and the
+  shell answer with the long one — so two spellings of one directory compare unequal. This alone
+  explained failures in `ship_preflight`, `migrate_root_resolution` and `sandbox_stage`, and the
+  last of those was a genuine bug: the dev box would have git-synced a checkout onto itself.
+- **A REPO-relative path must be POSIX on every platform** — it goes into a task's `touches[]`, a
+  version row, or a generated manifest. `path.join`/`path.relative` emit `\` here. Use
+  `path.posix.*`, or the house spelling `.split(path.sep).join('/')`. This was the bug in
+  `version-close.js`, the Figma adapter and `build-cli-package.js`; the giveaway is a function
+  whose own fallback branch hard-codes `/`.
+- **Node 24 refuses to spawn a `.cmd`**: bare `npm` is `ENOENT` and `npm.cmd` is `EINVAL` (the
+  CVE-2024-27980 mitigation), both surfacing as an inscrutable `null !== 0` from `spawnSync`.
+  `shell: true` works but concatenates args unescaped (DEP0190) and breaks on any path with a
+  space. Invoke npm's own entrypoint through node instead — `npm-cli.js` sits next to
+  `process.execPath` (see `tests/cli_package.mjs`). The same applies to an installed `.bin` shim:
+  run the package's `bin/*.js` directly.
+- **`import()` takes a URL, not a path.** A bare `C:\…` is read as the `c:` protocol and throws
+  `ERR_UNSUPPORTED_ESM_URL_SCHEME` before a single test runs. Use `pathToFileURL(p).href`.
+
+And when the platform genuinely cannot express the assertion, **skip with a stated reason rather
+than leaving it red** — a permanent red is how a suite stops being read. NTFS has no POSIX
+mode triad, so a `0600` claim is skipped on win32 while existence and content stay asserted
+(`tests/secret_box.mjs`, `tests/cli_sessions.mjs`). But reach for a skip last: a `dir` symlink
+needs elevation here, and switching to a **junction** — the unprivileged Windows equivalent, which
+`realpath` resolves identically — kept `sandbox_stage`'s symlink case actually running.

package/modules/lifecycle/routes/claims.js

@@ -68,6 +68,28 @@ function taskNotReadyHint(taskId, currentStatus) {
     : `Task #${idNum} is '${currentStatus}', not 'ready' — only 'ready' tasks are claimable (promote applies to 'backlog': POST /api/bongos/tasks/${idNum}/promote).`;
 }
 
+// task 1003768: the way-forward hint on a REBASE_REQUIRED 409 (ADR 0120 part 3's
+// owed-rebase claim gate). Pure + exported so the wording is pinned by a test,
+// the same contract taskNotReadyHint above carries.
+//
+// WHY THE MENU CHANGED. The old wording offered "(rebase its branch + re-ship, or
+// /merge-mode)". /merge-mode cannot run on a builder machine with no GitHub push
+// credential — and that is the DOCUMENTED DEFAULT posture, not a misconfiguration
+// (ADR 0031 §6 / ADR 0055: landing is server-mediated, /builder-ship uploads a
+// bundle and the SERVER pushes). Meanwhile /strand-fix — whose own frontmatter
+// says it is "the fix for a claim refused 409 REBASE_REQUIRED" — went unmentioned.
+// So the one exit that works everywhere was missing and the first one offered
+// fails on auth for most readers. The gate was always clearable; the MENU was
+// wrong, and this hint is the menu.
+//
+// Ordering is the fix: the universally-available command leads, /merge-mode is
+// marked as needing a push credential rather than dropped (it is still the right
+// tool on a credentialed machine), and /builder-release stays as the give-up exit.
+function rebaseRequiredHint(rebaseTasks) {
+  const ids = (rebaseTasks || []).map((t) => `task ${t.id}`);
+  return `Your queue is gated: ${ids.length} confirmed task(s) await your rebase (${ids.join(', ') || 'unknown'}). Clear it with /strand-fix N (works on any machine), or rebase the branch and re-ship — /merge-mode only if this machine has a GitHub push credential. To give up on one instead, /builder-release it. If CI is simply backed up, waiting is correct: a task already landed clears the gate on its own.`;
+}
+
 // task 1642 (+ the worktree-keying fix) — the pure one-active-claim decision.
 // Working two tasks from one WORKING TREE means every commit lands on the single
 // branch that tree owns; /builder-ship publishes the whole branch, so shipping one
@@ -343,8 +365,7 @@ module.exports = function buildClaimsRouter() {
         // ADR 0120 part 3: name the offending task(s) + the two ways to clear the
         // gate, so the builder isn't left guessing why their claim was refused.
         if (err.code === 'REBASE_REQUIRED') {
-          const ids = (err.rebaseTasks || []).map((t) => `task ${t.id}`);
-          err.hint = `Your queue is gated: ${ids.length} confirmed task(s) await your rebase (${ids.join(', ') || 'unknown'}). Land each (rebase its branch + re-ship, or /merge-mode) — or /builder-release it — then claim new work.`;
+          err.hint = rebaseRequiredHint(err.rebaseTasks);
         }
         // task 1002650: name the blocker(s) and the way forward — the same rule
         // the claimable feed enforces, spoken at the gate instead of a bare 409.
@@ -645,6 +666,10 @@ module.exports = function buildClaimsRouter() {
 module.exports.resolveCreatorSessionId = resolveCreatorSessionId;
 // V4.R14 (#952): the TASK_NOT_READY 409 hint — exported so its wording is pinned.
 module.exports.taskNotReadyHint = taskNotReadyHint;
+// task 1003768: the REBASE_REQUIRED 409 hint — exported so its wording is pinned
+// (tests/claim_gate_rebase.mjs). A remediation menu that names an impossible
+// command is how a builder loses twenty minutes at a gate they met with no context.
+module.exports.rebaseRequiredHint = rebaseRequiredHint;
 // task 1642: the pure session-scoped one-active-claim decision — exported for
 // tests/one_active_claim_per_session.mjs (DB-free) and reuse.
 module.exports.shouldRefuseSessionClaim = shouldRefuseSessionClaim;

package/modules/ui-design/adapters/figma/index.js

@@ -302,7 +302,10 @@ module.exports = {
       const existing = await fsp.readFile(dest, 'utf8').catch(() => null);
       if (existing === content) continue;
       await fsp.writeFile(dest, content, 'utf8');
-      written.push(path.relative(repoRoot, dest));
+      // filePaths is a REPO-relative list the caller commits and puts in a task's
+      // touches[], so it is POSIX on every platform (task 1003529) — path.relative
+      // alone emits 'src\ui\…' on win32.
+      written.push(path.relative(repoRoot, dest).split(path.sep).join('/'));
     }
 
     // Update config/design-sources.json

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.685",
+  "version": "1.19.687",
   "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/build-cli-package.js

@@ -471,7 +471,11 @@ function build(opts = {}) {
     if (!/\.(js|mjs|cjs)$/.test(rel)) continue;
     const text = fs.readFileSync(path.join(REPO_ROOT, rel), 'utf8');
     for (const m of text.matchAll(/\bimport\(\s*['"](\.[^'"]+)['"]\s*\)/g)) {
-      const target = path.relative(REPO_ROOT, path.resolve(path.dirname(path.join(REPO_ROOT, rel)), m[1]));
+      // FILES holds POSIX repo-relative paths, so the resolved target is spelled the
+      // same way before the lookup — path.relative emits 'clients\bongos-client\…' on
+      // win32, which matched nothing and failed every build on Windows (task 1003529).
+      const target = path.relative(REPO_ROOT, path.resolve(path.dirname(path.join(REPO_ROOT, rel)), m[1]))
+        .split(path.sep).join('/');
       if (!FILES.includes(target)) unshipped.push(`${rel} dynamically imports ${target}, which the manifest does not ship`);
     }
   }

package/scripts/gds/sandbox-stage.js

@@ -280,8 +280,15 @@ function sessionCheckoutRoot(deps = {}) {
 // symlinks, so the raw comparison false-negatives "same dir" and the code would
 // wrongly try to git-sync a checkout onto itself. Falls back to path.resolve when
 // the path doesn't exist yet (realpathSync throws ENOENT).
+// On Windows the two sides arrive in different spellings of the same directory:
+// `git rev-parse --show-toplevel` answers with forward slashes and the LONG filename,
+// while a configured servedRoot may be backslashed and 8.3-short (C:\Users\RUNNER~1\…).
+// path.resolve folds the separators and realpathSync.native — unlike realpathSync —
+// expands 8.3, so the comparison is about directories rather than renderings of them.
+// Without both, the same-dir check false-negatived and the box git-synced a checkout
+// onto itself, the very thing this function exists to avoid (task 1003529).
 function realPathOr(p) {
-  try { return fs.realpathSync(p); } catch { return path.resolve(p); }
+  try { return fs.realpathSync.native(path.resolve(p)); } catch { return path.resolve(p); }
 }
 
 function syncWorktreeToServed(deps = {}) {

package/scripts/gds/version-close.js

@@ -140,30 +140,37 @@ function deriveNextVersionId(currentId) {
   return `${m[1]}${Number(m[2]) + 1}`;
 }
 
+// Both derivations below build a REPO-RELATIVE doc path — it is stored on the
+// version row and read as a repo path on every platform — so they use path.posix,
+// never path.join (task 1003529). path.join emits '\' on win32, which produced
+// `limitations\pms-v2-shipped.md`: not a path this repo can resolve, and not what
+// either function's own `!currentPath` fallback returns. Only the separator is
+// platform-dependent here; the input is already a POSIX repo path.
+
 // Derive the next scope-doc path from the current one.
 //   limitations/pms-v2.md      → limitations/pms-v3.md
 //   limitations/current-version.md → limitations/v2.md   (best-effort guess)
 function deriveNextScopePath(currentPath, nextVersionId) {
   if (!currentPath) return `limitations/${nextVersionId.toLowerCase()}.md`;
-  const dir = path.dirname(currentPath);
-  const base = path.basename(currentPath);
+  const dir = path.posix.dirname(currentPath);
+  const base = path.posix.basename(currentPath);
   // e.g. pms-v2.md  → swap number
   const numbered = base.match(/^(.*v)(\d+)(\.md)$/i);
   if (numbered) {
-    return path.join(dir, `${numbered[1]}${Number(numbered[2]) + 1}${numbered[3]}`);
+    return path.posix.join(dir, `${numbered[1]}${Number(numbered[2]) + 1}${numbered[3]}`);
   }
   // Fallback: lower-case the version id.
-  return path.join(dir, `${nextVersionId.toLowerCase()}.md`);
+  return path.posix.join(dir, `${nextVersionId.toLowerCase()}.md`);
 }
 
 // Derive the shipped-archive path. For "limitations/pms-v2.md" → "limitations/pms-v2-shipped.md".
 function deriveShippedPath(currentPath, versionId) {
   if (!currentPath) return `limitations/${versionId.toLowerCase()}-shipped.md`;
-  const dir = path.dirname(currentPath);
-  const base = path.basename(currentPath);
+  const dir = path.posix.dirname(currentPath);
+  const base = path.posix.basename(currentPath);
   const m = base.match(/^(.*)\.md$/i);
   const stem = m ? m[1] : base;
-  return path.join(dir, `${stem}-shipped.md`);
+  return path.posix.join(dir, `${stem}-shipped.md`);
 }
 
 // -------------------------------------------------------------------------

package/src/module-api.js

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

package/tests/api_path_404.mjs

@@ -6,8 +6,11 @@
 //      hint, never the HTML island page (which JSON.parse-faulted on the client).
 //   2. A TASK_NOT_READY 409 names the promote route instead of leaving the caller
 //      to spelunk for it (#506).
+//   3. A REBASE_REQUIRED 409 offers exits the reader's machine can actually take
+//      (task 1003768) — it used to lead with /merge-mode, which needs a GitHub push
+//      credential most builder machines deliberately lack.
 //
-// Both are pinned via the pure exported helpers (no server, no DB).
+// All three are pinned via the pure exported helpers (no server, no DB).
 //
 // Run:  node tests/api_path_404.mjs
 
@@ -16,7 +19,7 @@ import { createRequire } from 'node:module';
 
 const require = createRequire(import.meta.url);
 const { isApiShapedPath, apiPathHint, apiNotFoundBody } = require('../src/bongos/api-path-404.js');
-const { taskNotReadyHint } = require('../modules/lifecycle/routes/claims.js');
+const { taskNotReadyHint, rebaseRequiredHint } = require('../modules/lifecycle/routes/claims.js');
 
 let passed = 0;
 let failed = 0;
@@ -95,5 +98,51 @@ t('taskNotReadyHint: a non-backlog status is explained + still names promote', (
   assert.match(h, /POST \/api\/bongos\/tasks\/953\/promote/);
 });
 
+// ---- rebaseRequiredHint (the 409) ------------------------------------------
+// task 1003768. This gate fires at SESSION START and blocks every new claim, so a
+// builder meets it before they have any context — which makes each command it names
+// load-bearing. Pinned here rather than in tests/claim_gate_rebase.mjs because that
+// suite needs Postgres and sits in the INTEGRATION set, so a pin there would never
+// run in the gate that guards main.
+t('rebaseRequiredHint: leads with /strand-fix, the exit that works on any machine', () => {
+  const h = rebaseRequiredHint([{ id: 1003529 }]);
+  const strand = h.indexOf('/strand-fix');
+  const mergeMode = h.indexOf('/merge-mode');
+  // Both indices are asserted present before they are compared: indexOf returns -1
+  // for a missing needle, and -1 < anything, so a bare `strand < mergeMode` would
+  // report PASS on a hint that had dropped /strand-fix entirely.
+  assert.ok(strand >= 0, 'the hint must name /strand-fix');
+  assert.ok(mergeMode >= 0, 'this pin assumes /merge-mode is still mentioned; update it if that changes');
+  assert.ok(strand < mergeMode, 'the universally-available command must come before the credentialed-machine one');
+});
+
+t('rebaseRequiredHint: never offers /merge-mode unconditionally', () => {
+  const h = rebaseRequiredHint([{ id: 1003529 }]);
+  // Landing is server-mediated and most builder machines hold no push credential
+  // BY DESIGN (ADR 0031 §6 / ADR 0055) — naming /merge-mode without that condition
+  // sends the reader to a command that fails on auth.
+  assert.match(h, /push credential/);
+});
+
+t('rebaseRequiredHint: keeps /builder-release as the give-up exit', () => {
+  assert.match(rebaseRequiredHint([{ id: 7 }]), /\/builder-release/);
+});
+
+t('rebaseRequiredHint: names every gating task, and degrades to "unknown" on none', () => {
+  const h = rebaseRequiredHint([{ id: 11 }, { id: 22 }]);
+  assert.match(h, /task 11, task 22/);
+  assert.match(h, /2 confirmed task\(s\)/);
+  // A gate that cannot name its cause is the failure mode this hint exists to avoid.
+  assert.match(rebaseRequiredHint([]), /unknown/);
+  assert.match(rebaseRequiredHint(undefined), /unknown/, 'a missing list must not throw');
+});
+
+t('rebaseRequiredHint: says waiting is correct when CI is merely backed up', () => {
+  // learning 1000209: an exhausted Actions budget flags every confirmed task
+  // REBASE_REQUIRED, and there the right move is to WAIT — re-shipping or releasing
+  // makes it worse. Cheap to say in the menu; not cheaply detectable server-side.
+  assert.match(rebaseRequiredHint([{ id: 7 }]), /waiting is correct/);
+});
+
 console.log(`\napi_path_404: ${passed} passed, ${failed} failed`);
 process.exit(failed ? 1 : 0);

package/tests/cli_package.mjs

@@ -18,12 +18,27 @@ import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
 import { spawnSync } from 'node:child_process';
-import { fileURLToPath } from 'node:url';
+import { fileURLToPath, pathToFileURL } from 'node:url';
 
 const REPO_ROOT = path.join(path.dirname(fileURLToPath(import.meta.url)), '..');
 const BUILDER = path.join(REPO_ROOT, 'scripts', 'gds', 'build-cli-package.js');
-
-const mod = await import(path.join(REPO_ROOT, 'scripts', 'gds', 'build-cli-package.js'));
+// Running npm from a test (task 1003529). On Windows `npm` is a .cmd shim: bare
+// 'npm' is ENOENT and 'npm.cmd' is EINVAL under Node 24's CVE-2024-27980 mitigation,
+// both surfacing as an inscrutable `null !== 0`. `shell: true` clears it but
+// concatenates args unescaped (DEP0190), which breaks on any tmp path with a space.
+// So invoke npm's own entrypoint through node: no shell, args stay arrays.
+const NPM_CLI = [
+  path.join(path.dirname(process.execPath), 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+  path.join(path.dirname(process.execPath), '..', 'lib', 'node_modules', 'npm', 'bin', 'npm-cli.js'),
+].find((p) => fs.existsSync(p));
+const npm = (args, opts) => (NPM_CLI
+  ? spawnSync(process.execPath, [NPM_CLI, ...args], opts)
+  : spawnSync('npm', args, opts));
+
+// import() takes a URL, not a filesystem path: on win32 a bare 'C:\…' is read as
+// the 'c:' protocol and throws ERR_UNSUPPORTED_ESM_URL_SCHEME before any test runs
+// (task 1003529). pathToFileURL is the portable spelling.
+const mod = await import(pathToFileURL(BUILDER).href);
 const { build, FILES, VERBS, CHECKOUT_ONLY, ALLOWED_SRC_BONGOS, PACKAGE_NAME } = mod.default ?? mod;
 
 function tmpdir(tag) {
@@ -126,7 +141,7 @@ test('the packed tarball installs and every verb runs with no repo present', (t)
   });
   assert.equal(built.status, 0, `build failed:\n${built.stderr}`);
 
-  const packed = spawnSync('npm', ['pack', '--silent', '--pack-destination', site], {
+  const packed = npm(['pack', '--silent', '--pack-destination', site], {
     cwd: buildOut, encoding: 'utf8',
   });
   assert.equal(packed.status, 0, `npm pack failed:\n${packed.stderr}`);
@@ -136,15 +151,20 @@ test('the packed tarball installs and every verb runs with no repo present', (t)
   // An empty directory: no repo, no core, no config, and a HOME of its own so a real session
   // file on this machine cannot make a verb look healthier than it is.
   fs.writeFileSync(path.join(site, 'package.json'), JSON.stringify({ name: 'probe', private: true }));
-  const installed = spawnSync('npm', ['install', '--no-audit', '--no-fund', '--silent', path.join(site, tarball)], {
+  const installed = npm(['install', '--no-audit', '--no-fund', '--silent', path.join(site, tarball)], {
     cwd: site, encoding: 'utf8', env: { ...process.env, HOME: home },
   });
   assert.equal(installed.status, 0, `npm install failed:\n${installed.stderr}`);
 
-  const bongos = path.join(site, 'node_modules', '.bin', 'bongos');
-  assert.ok(fs.existsSync(bongos), 'the package did not install a `bongos` binary');
+  // The installed shim proves npm wired `bin` up; the verbs then run through the
+  // real entrypoint rather than the shim, for the same Node-24-on-Windows reason as
+  // NPM_CLI above — spawning .bin/bongos.cmd is EINVAL (task 1003529).
+  const shim = path.join(site, 'node_modules', '.bin', process.platform === 'win32' ? 'bongos.cmd' : 'bongos');
+  assert.ok(fs.existsSync(shim), 'the package did not install a `bongos` binary');
+  const bongos = path.join(site, 'node_modules', PACKAGE_NAME, 'bin', 'bongos.js');
+  assert.ok(fs.existsSync(bongos), `the installed package has no bin/bongos.js at ${bongos}`);
 
-  const runVerb = (args) => spawnSync(bongos, args, {
+  const runVerb = (args) => spawnSync(process.execPath, [bongos, ...args], {
     cwd: site, encoding: 'utf8', input: '',
     env: { ...process.env, HOME: home, CLOUDBONGOS_API_BASE: 'http://127.0.0.1:45999', NO_COLOR: '1' },
   });

package/tests/cutover_codemod.mjs

@@ -9,6 +9,7 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import path from 'node:path';
 
 const require = createRequire(import.meta.url);
 const cm = require('../scripts/gds/cutover-codemod.js');
@@ -111,7 +112,11 @@ t('isHostFile is true only when isPublishable(rel) === false', () => {
 // ---- precondition -----------------------------------------------------------
 
 t('looksLikeConsumer: false in the monolith (src/module-api.js present), true post-split', () => {
-  const monolith = looksLikeConsumer('/repo', { existsFn: (p) => p.endsWith('/src/module-api.js') });
+  // existsFn is handed a path.join result — '\repo\src\module-api.js' on win32 — so the
+  // probe normalizes before matching its POSIX needle (task 1003529). Unnormalized it
+  // never matched, and the monolith was misread as a consumer: the codemod's own refusal
+  // guard would have let it edit the monolith it exists to protect.
+  const monolith = looksLikeConsumer('/repo', { existsFn: (p) => p.split(path.sep).join('/').endsWith('/src/module-api.js') });
   const consumer = looksLikeConsumer('/repo', { existsFn: () => false });
   assert.equal(monolith, false);
   assert.equal(consumer, true);
@@ -130,9 +135,15 @@ t('planCodemod rewrites host files, skips core files, reports unmapped', () => {
     'modules/lifecycle/db.js': `const api = require('../../src/module-api');`,   // CORE — must be skipped
     'README.md': 'not a js file',
   };
+  // `tree` is keyed by POSIX repo-relative paths, but the walker hands the shim
+  // path.join output — '\consumer\modules\game' on win32 — so both entry points
+  // normalize before slicing (task 1003529). Without it every nested directory
+  // listed empty and only the top-level server.js was ever planned.
+  const toPosix = (p) => String(p).split(path.sep).join('/');
   const fsImpl = {
-    readdirSync: (dir, opts) => {
+    readdirSync: (dirRaw, opts) => {
       // minimal shim: list immediate children of `dir` within the flat `tree`
+      const dir = toPosix(dirRaw);
       const rootPrefix = '/consumer';
       const rel = dir === rootPrefix ? '' : dir.slice(rootPrefix.length + 1);
       const names = new Set();
@@ -149,7 +160,7 @@ t('planCodemod rewrites host files, skips core files, reports unmapped', () => {
         return { name, isDirectory: () => isDir, isFile: () => !isDir };
       });
     },
-    readFileSync: (abs) => tree[abs.slice('/consumer/'.length)],
+    readFileSync: (abs) => tree[toPosix(abs).slice('/consumer/'.length)],
   };
   const isPub = (rel) => rel.startsWith('modules/lifecycle/') || rel.startsWith('src/');
   // Force the filesystem-walk path (no git) so the injected fake fs is exercised.

package/tests/lib_sh_resolution.mjs

@@ -240,7 +240,18 @@ function resolverBlock(f) {
   return src.slice(start, close + 1);
 }
 
+// These two assert on the PATH STRING the shell resolver prints. Everything above
+// checks content and syntax and runs everywhere; only these two compare spellings,
+// and Git Bash answers in its own mount namespace — a Win32 HOME comes back as
+// '/tmp/boxsess-…', which maps to a Git-install mount this side cannot reconstruct
+// without reading Git's mount table (task 1003529). The box scripts these cover run
+// on the Linux dev box, so the claim is verified where it is true rather than
+// left permanently red here — a red nobody can act on is how a suite stops being read.
+const SHELL_PATH_SPELLING_SKIP =
+  'shell path spellings: Git Bash resolves HOME into its own mount namespace (these scripts run on the Linux box)';
+
 test('the resolver prefers the most recently written session across config dirs', (t) => {
+  if (process.platform === 'win32') return t.skip(SHELL_PATH_SPELLING_SKIP);
   const probe = bash(['-n', 'infra/box-report-version.sh']);
   if (!probe) return t.skip('bash not available on this machine');
 
@@ -296,6 +307,7 @@ function heartbeatSfBlock() {
 }
 
 test('box-heartbeat.sh honors OTB_GDS_SESSION, scans, then falls back', (t) => {
+  if (process.platform === 'win32') return t.skip(SHELL_PATH_SPELLING_SKIP);
   const probe = bash(['-n', 'infra/box-heartbeat.sh']);
   if (!probe) return t.skip('bash not available on this machine');
 

package/tests/migrate_root_resolution.mjs

@@ -26,7 +26,27 @@ import path from 'node:path';
 
 const REPO_ROOT = path.resolve(path.dirname(fileURLToPath(import.meta.url)), '..');
 const MIGRATE = path.join(REPO_ROOT, 'scripts', 'migrate.sh');
-const REPO_REAL = realpathSync(REPO_ROOT);
+
+// migrate.sh is a POSIX script, so on Windows it runs under Git Bash and reports
+// paths in MSYS spellings this side cannot compare raw (task 1003529): a leading
+// '/c/Users/…', forward separators concatenated onto a Win32 root, and — because
+// TEMP here is an 8.3 short path (C:\Users\RUNNER~1\…) that the shell round-trip
+// expands — the long form of the very directory mkdtemp just handed us. winPath
+// folds all three into one canonical spelling so each assertion compares
+// DIRECTORIES rather than renderings of them. A no-op on POSIX.
+function winPath(p) {
+  if (process.platform !== 'win32') return p;
+  let s = String(p);
+  const drive = /^\/([a-zA-Z])\/(.*)$/.exec(s);
+  if (drive) s = `${drive[1].toUpperCase()}:/${drive[2]}`;
+  s = s.split('/').join(path.sep);
+  try { return realpathSync.native(s); } catch { return s; } // absent path: best effort
+}
+
+// Every fixture path below is canonicalized on creation, so both sides of every
+// assertion are already in the one spelling and no call site has to remember to.
+const REPO_REAL = winPath(realpathSync(REPO_ROOT));
+const mkFixture = (prefix) => winPath(realpathSync(mkdtempSync(path.join(tmpdir(), prefix))));
 
 let passed = 0;
 let failed = 0;
@@ -54,21 +74,21 @@ function printRoots({ cwd, initCwd } = {}) {
 // A synthetic consumer: a dir with a bongos.config.json pointing at itself, exactly
 // as the post-split amazonprimea repo carries (bongos.config.json { instanceRoot: "." }).
 function makeConsumer() {
-  const dir = realpathSync(mkdtempSync(path.join(tmpdir(), 'r89-consumer-')));
+  const dir = mkFixture('r89-consumer-');
   writeFileSync(path.join(dir, 'bongos.config.json'), JSON.stringify({ instanceRoot: '.' }));
   return dir;
 }
 // A dir with NO bongos.config.json — stands in for the monolith / a stray cwd.
 function makeBare() {
-  return realpathSync(mkdtempSync(path.join(tmpdir(), 'r89-bare-')));
+  return mkFixture('r89-bare-');
 }
 
 // ---- the F6 regression: instance root follows the invocation cwd ----------
 t('consumer run from its own dir: INSTANCE_ROOT resolves to the consumer (not the core)', () => {
   const consumer = makeConsumer();
   const r = printRoots({ cwd: consumer });
-  assert.equal(realpathSync(r.INSTANCE_ROOT), consumer, 'instance root must be the consumer dir');
-  assert.notEqual(realpathSync(r.INSTANCE_ROOT), REPO_REAL, 'must NOT fall back to the script-relative core root');
+  assert.equal(winPath(r.INSTANCE_ROOT), consumer, 'instance root must be the consumer dir');
+  assert.notEqual(winPath(r.INSTANCE_ROOT), REPO_REAL, 'must NOT fall back to the script-relative core root');
 });
 
 t('consumer via npm from elsewhere: INIT_CWD wins over the spawn cwd', () => {
@@ -77,22 +97,22 @@ t('consumer via npm from elsewhere: INIT_CWD wins over the spawn cwd', () => {
   // npm sets INIT_CWD to where `npm run` was invoked (the instance), even if a
   // wrapper cd'd somewhere else first.
   const r = printRoots({ cwd: elsewhere, initCwd: consumer });
-  assert.equal(realpathSync(r.INSTANCE_ROOT), consumer, 'INIT_CWD (the instance) must win');
+  assert.equal(winPath(r.INSTANCE_ROOT), consumer, 'INIT_CWD (the instance) must win');
 });
 
 // ---- the monolith / no-pointer fallback stays script-relative -------------
 t('no bongos.config + no env: INSTANCE_ROOT falls back to the script-relative repo root', () => {
   const bare = makeBare();
   const r = printRoots({ cwd: bare });
-  assert.equal(realpathSync(r.INSTANCE_ROOT), REPO_REAL, 'a stray cwd must NOT masquerade as the instance');
+  assert.equal(winPath(r.INSTANCE_ROOT), REPO_REAL, 'a stray cwd must NOT masquerade as the instance');
 });
 
 // ---- CORE root is always script-relative, regardless of cwd ---------------
 t('CORE_ROOT is always the script-relative repo root, independent of the invocation cwd', () => {
   const consumer = makeConsumer();
   const bare = makeBare();
-  assert.equal(realpathSync(printRoots({ cwd: consumer }).CORE_ROOT), REPO_REAL);
-  assert.equal(realpathSync(printRoots({ cwd: bare }).CORE_ROOT), REPO_REAL);
+  assert.equal(winPath(printRoots({ cwd: consumer }).CORE_ROOT), REPO_REAL);
+  assert.equal(winPath(printRoots({ cwd: bare }).CORE_ROOT), REPO_REAL);
 });
 
 // ==========================================================================
@@ -112,7 +132,7 @@ t('CORE_ROOT is always the script-relative repo root, independent of the invocat
 // `spaced` puts a space in the fixture's own directory name — the whole point of the fixture.
 function makeCore({ spaced, files = ['001_a.sql', '002_b.sql', '006_pms_v2.sql', '019_c.sql'] } = {}) {
   const prefix = spaced ? 'r89 spaced core-' : 'r89-plain-core-';
-  const dir = realpathSync(mkdtempSync(path.join(tmpdir(), prefix)));
+  const dir = mkFixture(prefix);
   mkdirSync(path.join(dir, 'scripts'));
   mkdirSync(path.join(dir, 'migrations'));
   mkdirSync(path.join(dir, 'src'));
@@ -179,7 +199,9 @@ t('core root containing a space: every migration is listed as ONE whole, readabl
   assert.equal(r.applied.length, 4, 'all four must reach apply_migration');
   for (const f of r.applied) {
     assert.ok(existsSync(f), `listed path must exist on disk, got fragment: ${f}`);
-    assert.ok(f.startsWith(core), `listed path must be whole and under the core root: ${f}`);
+    // winPath: the script emits the fixture root with the separators it was handed and
+    // '/' below it, so the raw prefix test compared spellings, not containment.
+    assert.ok(winPath(f).startsWith(core), `listed path must be whole and under the core root: ${f}`);
   }
 });
 

package/tests/module_loader.mjs

@@ -105,12 +105,17 @@ test('discoverModules: scanning the SAME root twice makes every key a duplicate-
   assert.match(errors[0].errors[0], /duplicate module key/);
 });
 
+// dedupeRoots returns RESOLVED absolute filesystem paths, which are
+// platform-shaped — '/a/modules' resolves to 'C:\a\modules' on win32. The claim
+// under test is collapsing, ordering and normalization, never separator style, so
+// the expectations resolve too rather than hard-coding POSIX literals (task 1003529).
 test('dedupeRoots: collapses roots that resolve to the same path, preserving order', () => {
+  const R = (p) => path.resolve(p);
   assert.deepEqual(
     loader.dedupeRoots(['/a/modules', '/a/modules', '/b/modules']),
-    ['/a/modules', '/b/modules'],
+    [R('/a/modules'), R('/b/modules')],
   );
-  assert.deepEqual(loader.dedupeRoots(['/a/modules', '/a/./modules']), ['/a/modules'], 'normalizes before comparing');
+  assert.deepEqual(loader.dedupeRoots(['/a/modules', '/a/./modules']), [R('/a/modules')], 'normalizes before comparing');
   assert.equal(loader.dedupeRoots(['/a/modules', '/b/modules']).length, 2, 'a genuinely diverged pair is kept');
 });
 

package/tests/next_number.mjs

@@ -12,6 +12,7 @@
 
 import { strict as assert } from 'node:assert';
 import { createRequire } from 'node:module';
+import path from 'node:path';
 
 const require = createRequire(import.meta.url);
 const { parseNumbers, nextFree, computeNextNumbers, nextNumbers, padAdr, padMig } =
@@ -105,8 +106,14 @@ function fakeGit(treeByRef) {
     return v.join('\n');
   };
 }
+// The keys are POSIX repo-relative dirs but `p` arrives from path.join, so on win32
+// it is '…\docs\adr' and a raw endsWith('docs/adr') never matched — the ADR arm
+// silently fell through to ENOENT and every count was wrong (task 1003529, idea 1000851).
+// Single-segment keys like 'migrations' matched either way, which is what made this
+// look like a counting bug rather than a separator one.
 const fakeReadDir = (byDir) => (p) => {
-  const key = Object.keys(byDir).find((d) => p.endsWith(d));
+  const posix = String(p).split(path.sep).join('/');
+  const key = Object.keys(byDir).find((d) => posix.endsWith(d));
   if (!key) throw new Error('ENOENT');
   return byDir[key];
 };

package/tests/sandbox_stage.mjs

@@ -20,6 +20,7 @@ import { execFileSync } from 'node:child_process';
 
 const require = createRequire(import.meta.url);
 const sbx = require('../scripts/gds/sandbox-stage.js');
+const { sameContent } = require('../scripts/gds/gen-freshness.js');
 
 let passed = 0, failed = 0;
 function t(name, fn) {
@@ -415,7 +416,10 @@ await ta('syncWorktreeToServed: brings the branch content into the served checko
   assert.equal(r.ok, true);
   assert.equal(r.synced, true);
   assert.equal(r.branch, 'claude/feat');
-  assert.equal(fs.readFileSync(path.join(served, 'public', 'game.js'), 'utf8'), 'BRANCH content\n',
+  // The claim is WHICH content landed, not how its lines end: git checks the fixture
+  // out under the machine's own autocrlf, so on Windows the file comes back CRLF and a
+  // byte-exact compare failed for a reason unrelated to the sync (task 1003529).
+  assert.ok(sameContent(fs.readFileSync(path.join(served, 'public', 'game.js'), 'utf8'), 'BRANCH content\n'),
     'served /workspace now shows the SESSION branch content, not stale main');
 
   g('worktree', 'remove', '--force', wt);
@@ -437,7 +441,11 @@ t('syncWorktreeToServed: a SYMLINKED servedRoot pointing at the session checkout
   // on any OS (it FAILS against the old path.resolve code, PASSES with realpath).
   const linkDir = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-served-link-'));
   const link = path.join(linkDir, 'served');
-  fs.symlinkSync(fs.realpathSync(tmp), link, 'dir');
+  // A 'dir' symlink needs elevation (or Developer Mode) on Windows and threw EPERM,
+  // taking the case out on every Windows checkout. A JUNCTION is the unprivileged
+  // Windows equivalent for a directory and realpath resolves it the same way — the
+  // spelling scripts/gds/worktree.js already uses for exactly this reason (task 1003529).
+  fs.symlinkSync(fs.realpathSync(tmp), link, process.platform === 'win32' ? 'junction' : 'dir');
   try {
     const r = sbx.syncWorktreeToServed({ cwd: tmp, servedRoot: link });
     assert.equal(r.ok, true);

package/tests/secret_box.mjs

@@ -23,9 +23,16 @@ const box = require('../src/bongos/secret-box.js');
 
 let passed = 0;
 let failed = 0;
+let skipped = 0;
+// A case may return { skip: '<reason>' } instead of asserting. It prints as SKIP with
+// its reason and is counted apart from the passes, so a claim this platform cannot make
+// is VISIBLE rather than folded into a green (task 1003529).
 function t(name, fn) {
-  try { fn(); passed++; console.log(`  PASS  ${name}`); }
-  catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
+  try {
+    const r = fn();
+    if (r && r.skip) { skipped++; console.log(`  SKIP  ${name}\n        ${r.skip}`); return; }
+    passed++; console.log(`  PASS  ${name}`);
+  } catch (e) { failed++; console.log(`  FAIL  ${name}\n        ${e.message}`); }
 }
 
 const KEY_HEX = crypto.randomBytes(32).toString('hex');
@@ -141,15 +148,38 @@ t('decrypt rejects a malformed blob', () => {
 
 console.log('\nprovisionMasterKey (task 1398 — productized, idempotent, never-overwrite):');
 
-t('creates a 0600 key file when none exists and env is empty', () => {
+// Split in two (task 1003529): the creation claim holds on every platform, the MODE
+// claim does not, and a test named for 0600 that quietly asserts nothing of the sort on
+// Windows is the lying green this suite is supposed to catch. Now the name matches what
+// each case actually proves, and the untestable half reports as a visible SKIP.
+function provisionToTmp() {
   const dir = mkdtempSync(join(tmpdir(), 'otb-provision-'));
   const file = join(dir, 'builder-secret.key');
   const r = box.provisionMasterKey({ file, env: undefined });
+  return { file, r };
+}
+
+t('creates a key file when none exists and env is empty', () => {
+  const { file, r } = provisionToTmp();
   assert.equal(r.ok, true);
   assert.equal(r.created, true);
   const raw = readFileSync(file, 'utf8');
   assert.match(raw.trim(), /^[0-9a-f]{64}$/, 'wrote a 64-hex (32-byte) key');
   assert.ok(box.decodeMasterKey(raw), 'the written key decodes as a valid master key');
+});
+
+// NTFS has no owner/group/other triad: node reports 0666 for any writable file and
+// chmod(0o600) is silently a no-op — measured on win32 before and after an explicit
+// chmod. Same split, and same reasoning, as the session-file mode test in
+// tests/cli_sessions.mjs. KNOWN RESIDUAL GAP: on Windows nothing here would catch
+// secret-box.js regressing to a world-readable key file; the confidentiality property
+// rests on the per-user profile directory's ACLs, and proving THAT needs an ACL probe
+// this suite does not have. The POSIX run is the coverage.
+t('the key file is mode 0600', () => {
+  if (process.platform === 'win32') {
+    return { skip: 'NTFS has no POSIX mode triad (node reports 0666 and chmod is a no-op) — asserted on POSIX; Windows relies on profile-dir ACLs, which this suite does not probe' };
+  }
+  const { file } = provisionToTmp();
   assert.equal(statSync(file).mode & 0o777, 0o600, 'file is 0600');
 });
 
@@ -185,5 +215,5 @@ t('refuses to clobber a present-but-invalid key file (fail safe, not silent over
   assert.equal(readFileSync(file, 'utf8'), 'garbage-not-a-key', 'the existing file is left untouched');
 });
 
-console.log(`\n${passed} passed, ${failed} failed`);
+console.log(`\n${passed} passed, ${failed} failed${skipped ? `, ${skipped} skipped` : ''}`);
 process.exit(failed ? 1 : 0);

package/tests/ship_automerge_injection.mjs

@@ -31,9 +31,18 @@ const ship = require('../scripts/gds/ship.js');
 
 let passed = 0;
 let failed = 0;
+let skipped = 0;
+// A case may return { skip: '<reason>' } instead of asserting. It prints as SKIP
+// with its reason and is counted apart from the passes — reporting a case that never
+// ran as "ok" is the kind of lying green this suite exists to prevent (task 1003529).
 function test(name, fn) {
   try {
-    fn();
+    const result = fn();
+    if (result && result.skip) {
+      skipped++;
+      console.log(`  SKIP ${name}\n     ${result.skip}`);
+      return;
+    }
     passed++;
     console.log(`  ok  ${name}`);
   } catch (err) {
@@ -150,7 +159,17 @@ test('gitArgvOk: returns false on a failing git command (no throw)', () => {
 
 // ---- 3. Contrast: the OLD shell-string approach WOULD have executed it ----
 
+// This one documents the OLD bug by reproducing it: it asserts that the removed
+// shell-string construction DOES expand `$(…)`. That is a claim about bash, and
+// execSync on Windows goes through cmd.exe, which does not expand it — so the
+// vulnerable shape "passes" here for a reason unrelated to the fix (task 1003529).
+// The security assertions above — that the CURRENT argv build never executes the
+// payload — are platform-neutral and keep running on Windows; only this historical
+// contrast is bash-specific.
 test('contrast: the pre-fix shell-string build DOES execute the payload (documents the bug)', () => {
+  if (process.platform === 'win32') {
+    return { skip: 'documents a bash-specific expansion; execSync goes through cmd.exe here, which never expands $(…)' };
+  }
   const { dir } = makeRepo();
   const sentinel = path.join(dir, 'OLD-PWNED');
   try {
@@ -170,5 +189,5 @@ test('contrast: the pre-fix shell-string build DOES execute the payload (documen
   }
 });
 
-console.log(`\nautoMerge shell-injection (#681) tests: ${passed} passed, ${failed} failed`);
+console.log(`\nautoMerge shell-injection (#681) tests: ${passed} passed, ${failed} failed${skipped ? `, ${skipped} skipped` : ''}`);
 process.exit(failed > 0 ? 1 : 0);

package/tests/ship_preflight.mjs

@@ -164,15 +164,18 @@ test('cleanupMacFinderDupRefs: deletes only " 2" / " 3" suffixed ref files', ()
   // Spin up a throwaway git repo, plant some real refs + some Finder dups,
   // run the cleanup, assert only the dups got removed and `git fetch` no
   // longer fails on them.
+  // These fixtures used to pin `shell: '/bin/bash'`, which is not a Win32 path —
+  // spawnSync returned ENOENT and four tests of platform-neutral behaviour were red
+  // on every Windows checkout (task 1003529). All they need is a shell that
+  // understands `&&`, which the platform default is on both.
   const tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'otb-shippref-'));
   try {
     execSync('git init -q', { cwd: tmp });
     execSync('git config user.email t@t.t && git config user.name t', {
       cwd: tmp,
-      shell: '/bin/bash',
     });
     fs.writeFileSync(path.join(tmp, 'a.txt'), 'x');
-    execSync('git add a.txt && git commit -q -m init', { cwd: tmp, shell: '/bin/bash' });
+    execSync('git add a.txt && git commit -q -m init', { cwd: tmp });
 
     const refsHeads = path.join(tmp, '.git', 'refs', 'heads');
     // Plant Finder duplicates next to the real refs. Use the actual ref
@@ -227,10 +230,9 @@ test('cleanupMacFinderDupRefs: handles linked worktrees (refs in common dir)', (
     execSync('git init -q', { cwd: tmp });
     execSync('git config user.email t@t.t && git config user.name t', {
       cwd: tmp,
-      shell: '/bin/bash',
     });
     fs.writeFileSync(path.join(tmp, 'a.txt'), 'x');
-    execSync('git add a.txt && git commit -q -m init', { cwd: tmp, shell: '/bin/bash' });
+    execSync('git add a.txt && git commit -q -m init', { cwd: tmp });
     execSync('git branch other', { cwd: tmp });
 
     const wt = path.join(tmp, 'wt-linked');
@@ -265,10 +267,9 @@ test('findMainWorktree: returns the main-branch worktree path from a linked work
     execSync('git init -q -b main', { cwd: tmp });
     execSync('git config user.email t@t.t && git config user.name t', {
       cwd: tmp,
-      shell: '/bin/bash',
     });
     fs.writeFileSync(path.join(tmp, 'a.txt'), 'x');
-    execSync('git add a.txt && git commit -q -m init', { cwd: tmp, shell: '/bin/bash' });
+    execSync('git add a.txt && git commit -q -m init', { cwd: tmp });
     execSync('git branch feature', { cwd: tmp });
 
     const wt = path.join(tmp, 'linked');
@@ -279,7 +280,11 @@ test('findMainWorktree: returns the main-branch worktree path from a linked work
     // worktree should return `tmp` (the resolved real path).
     const found = findMainWorktree(wt);
     assert.ok(found, 'expected a path');
-    assert.equal(fs.realpathSync(found), fs.realpathSync(tmp));
+    // realpathSync.native, not realpathSync: where TEMP is an 8.3 short path
+    // (C:\Users\RUNNER~1\…) os.tmpdir() keeps the short form and git reports the long
+    // one, so the plain call compares two spellings of one directory (task 1003529).
+    // Only .native expands 8.3; it is a no-op everywhere else.
+    assert.equal(fs.realpathSync.native(found), fs.realpathSync.native(tmp));
   } finally {
     fs.rmSync(tmp, { recursive: true, force: true });
   }
@@ -291,10 +296,9 @@ test('findMainWorktree: returns null when no worktree is on main', () => {
     execSync('git init -q -b trunk', { cwd: tmp }); // default branch is "trunk", not main
     execSync('git config user.email t@t.t && git config user.name t', {
       cwd: tmp,
-      shell: '/bin/bash',
     });
     fs.writeFileSync(path.join(tmp, 'a.txt'), 'x');
-    execSync('git add a.txt && git commit -q -m init', { cwd: tmp, shell: '/bin/bash' });
+    execSync('git add a.txt && git commit -q -m init', { cwd: tmp });
     // No branch named `main` anywhere.
     assert.equal(findMainWorktree(tmp), null);
   } finally {