@bongos/core 1.21.99 → 1.21.101

package/.bongos-core.json

@@ -2,22 +2,22 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.21.99",
-  "core_contract": "1.21.99",
-  "source_commit": "262e039f7737aee04e24db9559e593544fab5532",
+  "core_version": "1.21.101",
+  "core_contract": "1.21.101",
+  "source_commit": "7858ffa1199248ca5c40837b5f21f0e8ef19d47f",
   "source_ref": "HEAD",
-  "built_at": "2026-10-09T12:05:36.533Z",
+  "built_at": "2026-10-09T13:00:03.202Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
-    "docs_redacted": 591,
+    "docs_redacted": 592,
     "agent_docs_stubbed": 28,
     "functional_verbatim": 3019,
     "rules": 3,
     "gate_literals": 3,
     "gate": "passed"
   },
-  "file_count": 3639,
-  "tree_sha256": "6627907aa4a62c0516525dd3273bf188497dd8914388d4fcd5435d4563149bbf",
+  "file_count": 3640,
+  "tree_sha256": "02e0d13b4633dbacbe287ad2057cb25994404d346b87f7f87f013d0f367ee8c2",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -294,6 +294,11 @@
       "mode": "0000644",
       "sha256": "b151b43139e62a6b71efc49edd447ee0c4b6a95deb42d7a840b851ab79ec4782"
     },
+    {
+      "path": "GOVERNMENT.md",
+      "mode": "0000644",
+      "sha256": "a1e334f7814b8294c460be15ad7f3bad0b7ea5be8e2463c1d7f368a149e5f5c0"
+    },
     {
       "path": "LICENSE",
       "mode": "0000644",
@@ -302,7 +307,7 @@
     {
       "path": "README.md",
       "mode": "0000644",
-      "sha256": "9c9e99127efafe70d60e1d464f07815397e436e69dc0b82c2e67f41dbd8dc8d6"
+      "sha256": "abbf022b58c07144e4ae1d57cde3a232237099c1f37474310d56abae1992c141"
     },
     {
       "path": "bin/bongos.js",
@@ -2867,7 +2872,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "d43b9ee9d1bae22277b8e9b9d425aafef3d1c2c5298814fd6a1a319e632917b7"
+      "sha256": "cf3cee3fb9bea331857c69de667438a0c83137849f262712af3de7172e701e26"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2927,7 +2932,7 @@
     {
       "path": "docs/onboarding/primer.md",
       "mode": "0000644",
-      "sha256": "f347c1355e2f1a71f3170a260a9c7cec719624c47b24ba89a6db371868caefdc"
+      "sha256": "bed8d38e81c9b6cf0b67d589f7e6ab4362034776c651c1a3743d6d98d6f6c8eb"
     },
     {
       "path": "docs/onboarding/slash-commands.md",
@@ -10127,12 +10132,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "743e74b9cb354d11b19bb40b81f9640932ac68730487816569ee5796875392a4"
+      "sha256": "dd270ec93485ddb27786d87ba9eb34a588c39492310114df6c22efb4a99ee447"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "e74953a3c03fb015d7f54229580414d430cff7159d5361dca7754eb28d852310"
+      "sha256": "888c5c97454286a61cc39bbe0c14547d92765fa057195303f3f3352410edcfa6"
     },
     {
       "path": "public-docs/index.html",
@@ -10152,7 +10157,7 @@
     {
       "path": "release-notes.json",
       "mode": "0000644",
-      "sha256": "76a1303dec3ba5b72f9a7eb03de1896d6dafc040c8c9260af6c7b8fe2a6e58cf"
+      "sha256": "d1156f6a018933ff1c6f4f4481a4089ac754815318468fa5ce6bdd880105bbdb"
     },
     {
       "path": "scripts/cron/style_guide_audit.sh",
@@ -11237,7 +11242,7 @@
     {
       "path": "scripts/gds/publish-manifest.js",
       "mode": "0000644",
-      "sha256": "e698374e1c0709b343202ccd3b336c4fc8b7b9523f7f15291f99cff0f43fd759"
+      "sha256": "d059af3ab3d980229ea02073b69d8281c7dd8526d8a3a1445e89be51cd36fb50"
     },
     {
       "path": "scripts/gds/publish-watch.js",
@@ -11927,7 +11932,7 @@
     {
       "path": "scripts/gds/worktree.js",
       "mode": "0000644",
-      "sha256": "69f167d079c1900568f740d8d4a1a2288f5ff47146634209f8a1a9350a3aa5e2"
+      "sha256": "40aa204dd081022580bbd016b1f2741ebfc4eb9324d4f60a2ac7da9636d813f1"
     },
     {
       "path": "scripts/hall-preview/README.md",
@@ -12187,7 +12192,7 @@
     {
       "path": "src/bongos/module-scope-map.js",
       "mode": "0000644",
-      "sha256": "4a42901ad09df965b0b42ce2cb75c0993adfd49b560b050d99419cba1ccdcaa4"
+      "sha256": "67711bf6dd6becd1edeb6866279a788fd6360a51d013eed77f2592be0aaab01b"
     },
     {
       "path": "src/bongos/module-store.js",
@@ -12427,7 +12432,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "fe5b5772fd9a33f1aa10b93689e32179c6c81d9dbf9a3a33ee4af2383a3bdb02"
+      "sha256": "515c7e51fc93bf9b5fe62e46252650d733818c4e9fd6e7ab3e310fbd6593564a"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -18202,7 +18207,7 @@
     {
       "path": "tests/worktree_helper.mjs",
       "mode": "0000644",
-      "sha256": "cac88e36d1e2ef2cbe2799275186f0787431b5b636fc52d1325b5dbbfcd56368"
+      "sha256": "0dea42cbad0d17eb63e516a6812050b239c51b0f2f2d13c3a949eff27ec44657"
     },
     {
       "path": "tests/world_tokens.mjs",

package/GOVERNMENT.md

@@ -0,0 +1,145 @@
+# How government works
+
+> This is about **your project's** government. How Cloud Bongos itself is run is a different file: [`GOVERNANCE.md`](GOVERNANCE.md).
+
+Every project on Cloud Bongos has a government. It answers one question: when something needs deciding, who decides, and how? It's not a theme or a label on a page. It's the rules the server actually checks every time someone tries to do something, so the government you pick is the way your project gets steered. Pick it at the start, change it later by vote, and every change is on the record.
+
+A few words you'll see a lot:
+
+- **Rank**: your standing on the project. There are four built-in ranks. **Archon** is the founder. **Metic** is a trusted builder, a rank you earn by shipping. **Thetes** and **Xenos** are newer builders, with Xenos the newest. You can also make your own ranks, like a council.
+- **Board**: the people who get a vote.
+- **Sitting**: one vote on one thing. It stays open until it closes as **passed** or **returned** (sent back).
+- **Amendment**: a proposal to change the rules. The government you have now decides it, not the one you're proposing.
+
+## The four forms you can pick today
+
+A form is just two settings together: who votes, and how many have to agree.
+
+| Form | Who votes | What passes | Good for |
+|---|---|---|---|
+| **Monarchy / BDFL** ("benevolent dictator for life") | Only the founder | The founder's one yes | A solo start, when there's nobody else to ask. Every project is born one. |
+| **Timocratic Republic** | Trusted builders (Metic) and the founder | Passes unless someone objects | A small team where people earned their say by shipping. |
+| **Direct Democracy** | Every builder | Passes unless someone objects | A flat team where everyone in the room counts. |
+| **Foundation** | A council you name | Passes unless someone objects | A bigger project that wants a small group of trustees looking after it. |
+
+For a Foundation, the council is a rank you create and fill yourself. Make that rank first, then switch.
+
+You can also mix your own settings, like "every builder, more than half". If your mix doesn't match a named form it reads as **Custom**. That's fine. Custom is still the real rules, not a guess at the nearest name.
+
+Three more forms are on the list but **not available yet**: **Presidential** (needs elections), **Cooperative** (needs member shares) and **Federation** (for projects made of many teams).
+
+Not sure? Start as a Monarchy and switch once there's someone to share the calls with.
+
+## The dials
+
+### Who votes
+
+The founder only, trusted builders and up, every builder, or a council you name. Whoever holds the rank gets the vote, and nobody keeps it after they lose the rank. A builder who leaves, or gets moved down, is off the board on their very next request.
+
+### How many must agree
+
+| Rule | What it means | If nobody votes |
+|---|---|---|
+| **One yes is enough** | The first yes decides it. | it passes |
+| **Passes unless someone objects** | A yes doesn't end it. It passes once everyone has voted with no objection. One objection sends it back. | it passes |
+| **More than half** | More than half of **everyone on the board** says yes, not just the people who showed up. 3 of 5 carries it, and a tie isn't a majority. | it's returned |
+| **Everyone agrees** | Everyone who votes says yes, and at least one person does. One objection sends it back straight away. People who don't vote don't block it. | it's returned |
+
+An objection has to come with a reason, so whoever proposed it knows what to fix.
+
+### The voting clock
+
+Your constitution (the written-down settings of your government) can give a sitting a time limit, and a sitting closes early once everyone has voted. Look at the last column above: under the first two rules silence means yes. So a building's vote only gets a clock under "more than half" or "everyone agrees". We won't let a deadline pass something nobody read. Out of the box there's no clock.
+
+Honest note: the clock is built, but the walk below doesn't test a clock running out yet. Every sitting it closes, closes on votes.
+
+### Who decides in each building
+
+Your project's decisions are split into nine **buildings**, one per kind of decision. You'll find them on the street in the hall (`/street`).
+
+| Building | What it covers | Who decides as today |
+|---|---|---|
+| **Charter** | The government itself | Always the board, under the rules in force |
+| **Rules** | Project settings (when work counts as stale, ship mode) and editing work categories | Whoever may change project settings |
+| **Disputes** | Security reports: confirm, dispute, mark fixed | Whoever may judge reports |
+| **People** | Giving and taking custom ranks, access requests, invites | Whoever may manage ranks |
+| **Planning** | Creating and ordering goals, new work categories, the focus version | Whoever may create goals |
+| **Automation** | Unattended building (AI agents working with nobody watching): on or off, which goals, priority, pausing a runner | Whoever may switch it on and off |
+| **Review** | Marking a goal's done-when check as met or not met | Whoever may mark work as meeting its checks |
+| **Release** | Clearing a PR's gate, override requests, putting a new version live, releases and deploys | Whoever may put a release live |
+| **Treasury** | Builders' monthly spending limits | Whoever may set spending limits |
+
+Every building except the Charter is in one of three states:
+
+- **As today.** Whoever holds that building's permission acts alone, from its own page. Every building starts here.
+- **By vote.** You pick who sits (a rank, a rank and everyone above it, or a list of ranks) and how they decide: first yes wins, passes unless someone objects, more than half, everyone agrees, or signed off by someone who didn't build it. Once a building is by vote, nobody can act alone there. Try it and you get refused and pointed at the vote instead.
+- **Empty.** Nobody holds it yet, so its matters wait.
+
+The walk put every building to a vote, tried to act alone on all 28 of their direct actions (every one was refused), then set them back to as today and checked all 28 work again. Two things are built but **not walked yet**: the empty state, and a "decides alone" rule where one seated member can still act by themselves.
+
+## What a vote can actually change
+
+This is the part that matters. A passed vote doesn't just get recorded, it **does the thing**. The vote is the authority, so it acts on its own, not through any one person.
+
+| Building | What a passed vote carries out |
+|---|---|
+| **People** | Gives someone a custom rank, or takes it away |
+| **Automation** | Switches unattended building on or off, or allows a goal to be built unattended |
+| **Release** | Approves an override request, or clears the gate on a PR |
+| **Review** | Signs off a done-when check |
+| **Treasury** | Sets a builder's monthly spending limit |
+
+Two more things the walk proved: a returned vote changes nothing, and someone the building doesn't seat can't vote on its matters.
+
+At **Rules, Disputes and Planning** a vote stops people acting alone, but a passed vote there can't carry out an action by itself yet. That's **later**.
+
+## How to change your government
+
+**1. When you found the project.** Every project is born a Monarchy. At the decide step of founding you pick your form. That pick is filed as your first amendment, and your one yes as founder ratifies it. After that, the five founding stages (scope, strategize, charter, legalize, legislation) are each closed by a vote of the government you picked. Pick a Timocratic Republic and you can't close a stage alone: your trusted builders have to say yes too. A stage with unfinished tasks can't be put to a vote at all. Once all five pass the project comes alive, still governed by your pick.
+
+**2. Any time after: the Charter building.** Open the Charter on the street and hit "change how this works". The forms are one tap each. A Foundation needs its council rank first, and the forms that aren't ready yet are shown as later. Or pick who decides and how by hand. Add a reason and file it. That's an amendment, and your current government votes on it.
+
+**3. Any building, the same way.** "Change how this works" on any building drafts a change to who decides there.
+
+(The picker screens are built. The walk tests the amendments they file, not the screens themselves.)
+
+The rules every amendment follows:
+
+- Your current government decides it.
+- There's no settings page. A passed amendment is the only way the rules change. Even editing the database by hand gets refused.
+- If your change would take away your own vote, it stops and asks you to confirm first.
+- Every attempt, passed or returned, stays on the record.
+
+## What can never be changed, and why
+
+Some things no vote can move, and that's on purpose.
+
+- **The Archon rank.** You can't edit it from the government page, so nobody can click the founder out of their own project.
+- **Pushing to main, touching protected files, and server access.** These are enforced outside the app, by git hooks and audits, not by the database. So no rank can ever be given them, not even by vote. A switch that looked like it granted them would be a switch that does nothing, so we don't show one.
+- **A file can't give anyone power.** Editing `CLAUDE.md`, a config file, your settings or your hooks gets you nothing. The server checks your rank against the live database on every request, with no caching.
+- **Nothing outside a vote changes the constitution.** Not an environment variable and not a hand edit. The only way in is an amendment.
+
+These walls are proven by their own tests. The government walk below doesn't cover them.
+
+## Today vs later
+
+| | Today | Later |
+|---|---|---|
+| **Forms** | Monarchy / BDFL, Timocratic Republic, Direct Democracy, Foundation, and your own Custom mix | Presidential, Cooperative, Federation |
+| **Dials** | Who votes, how many must agree, the voting clock | Veto points (how many separate approvals a big change needs), whether the team can replace its leader by vote, judicial review (who can cancel a decision that breaks the charter), a government that changes as you grow |
+| **What a vote does** | People, Automation, Release, Review, Treasury carry out their actions | An action at Rules, Disputes and Planning; grade appeals; standing rules; votes on treasury spending |
+| **Proof** | The walk, in memory, re-run in CI | The same walk against a real database |
+
+## How we know it works
+
+We don't take our own word for it. There's a walk: one repeatable run over a throwaway test project with six people. It founds the project, closes all five stages, switches through every form, puts every building to a vote and tries to act alone everywhere, then passes every kind of matter and checks the thing actually happened.
+
+**119 checks, 119 pass.** Every request goes through the real code that makes every decision. One honest catch: the storage underneath is an in-memory stand-in for the database. A real-database run is later.
+
+Run it yourself:
+
+```sh
+node scripts/gds/government-walk.js
+```
+
+The full pass/fail table is in [`docs/governance/government-walk.md`](docs/governance/government-walk.md). CI re-runs the walk on every change, so if any row flips, the build goes red.

package/README.md

@@ -6,6 +6,8 @@ Cloud Bongos is free software under the **GNU AGPL-3.0** (see [`LICENSE`](./LICE
 
 > **Provenance.** This core was extracted with fresh history from **Example** — the reference instance, built by Hermeslines, and the first project to run on Cloud Bongos. Example now consumes this core as a pinned dependency, the same shape as any other instance. The extraction is a redacted subtree (no instance secrets, IPs, or private identity); the exact pin — `core_version`, `source_commit`, `tree_sha256` — is recorded in [`.cloudbongos-core.json`](./.cloudbongos-core.json).
 
+**How your project decides things** — who votes, what a vote changes, and how to change your government — is in [`GOVERNMENT.md`](./GOVERNMENT.md).
+
 The durable framing for AI agents — methodology, working rules, session protocol, architecture — lives in [`CLAUDE.md`](./CLAUDE.md). Read it before editing code.
 
 ## What's in here

package/docs/module-api-changelog.md

@@ -3035,5 +3035,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.21.97 with no explicit bump. run 37925528587. (task 1002620)
   1.21.99 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.21.98 with no explicit bump. run 37927704012. (task 1002620)
+  1.21.100 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.99 with no explicit bump. run 37931583687. (task 1002620)
+  1.21.101 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.21.100 with no explicit bump. run 37933684016. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/onboarding/primer.md

@@ -116,6 +116,7 @@ Other depth, in roughly the order you'll need it:
 - [`docs/architecture.md`](../architecture.md) — live system: droplet, stack, schema, API surface
 - [`docs/modules-contract.md`](../modules-contract.md) — the product is built as a small core plus swappable `modules/<key>/` (the game, Discord, art, and more); this is the live roster and how a task lands inside one
 - [`docs/canonical-permissions.md`](../canonical-permissions.md) — who can do what (rank gates)
+- [`GOVERNMENT.md`](../../GOVERNMENT.md) — how your project's government works and how to change it, in plain words
 - [`docs/file-map.md`](../file-map.md) — where every folder is and what it contains
 - [`docs/recipes/`](../recipes/) — long-form ops gotchas (read before deploying)
 - [`docs/onboarding/diagrams/`](diagrams/) — pan-and-zoom maps of the task lifecycle, rank ladder, the credit economy, the complete architecture (where your work runs and how it reaches production), and versioning

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.21.99",
+  "version": "1.21.101",
   "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/release-notes.json

@@ -9432,5 +9432,17 @@
       "id": "1004658",
       "text": "There is now one walk anyone can re-run that tests a project's whole government from start to finish, and a table showing the result. It founds a test project with a chosen government and checks that this government, not the f"
     }
+  ],
+  "1.21.100": [
+    {
+      "id": "1004659",
+      "text": "There is now a plain-language guide to how a project's government works: GOVERNMENT.md, linked from the README and the hall primer. It explains the four forms you can pick today, who votes and how many must agree, who decides"
+    }
+  ],
+  "1.21.101": [
+    {
+      "id": "1004582",
+      "text": "Cleaning up a finished worktree no longer crashes on Linux and Mac machines. It used to stop halfway and leave the old workspace registered; now it removes the shortcut to the shared packages safely and carries on."
+    }
   ]
 }

package/scripts/gds/publish-manifest.js

@@ -90,6 +90,7 @@ const PUBLISH_ALLOWLIST = [
   'README.md',
   'LICENSE',
   'GOVERNANCE.md',
+  'GOVERNMENT.md',                   // the plain-language guide to a project's own government (task 1004659)
   'CONTRIBUTING.md',
   'CODE_OF_CONDUCT.md',
   'docs/adr/',                       // sanitized — ADR 0065 §4 "docs/ADRs (sanitized)"

package/scripts/gds/worktree.js

@@ -173,6 +173,24 @@ function nodeModulesState(wtPath) {
   return st.isSymbolicLink() ? 'junction' : 'real-dir';
 }
 
+// Remove a node_modules LINK without ever following it (task 1004582). rmdir is
+// only right for a Windows junction: on Linux/macOS (cloud containers) the link
+// is a plain symlink and rmdir throws ENOTDIR, leaving the worktree registered.
+// unlink removes the link itself on every platform — libuv unlinks a junction
+// too — and refuses a real directory outright, so it can never delete contents.
+// The win32 rmdir fallback covers a reparse point unlink will not take.
+function unlinkNodeModulesLink(linkPath, { platform = process.platform, fsImpl = fs } = {}) {
+  if (!fsImpl.lstatSync(linkPath).isSymbolicLink()) {
+    throw new Error(`${linkPath} is not a link — refusing to remove a real directory`);
+  }
+  try {
+    fsImpl.unlinkSync(linkPath);
+  } catch (e) {
+    if (platform !== 'win32' || (e.code !== 'EPERM' && e.code !== 'EISDIR')) throw e;
+    fsImpl.rmdirSync(linkPath); // on a junction, rmdir removes the LINK only
+  }
+}
+
 function resolveWorktreePath(root, nameOrPath) {
   const all = listWorktrees(root);
   const norm = (p) => path.resolve(p).replace(/\\/g, '/').toLowerCase();
@@ -296,8 +314,8 @@ function cmdRemove(root, argv) {
   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'));
+      // Removes the LINK only, never the target's contents — junction or symlink.
+      unlinkNodeModulesLink(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];
@@ -427,4 +445,5 @@ if (require.main === module) main();
 
 module.exports = {
   worktreeNameFor, needsJunction, removalPlan, nodeModulesState, shadowingNodeModules, huskDisposition,
+  unlinkNodeModulesLink,
 };

package/src/bongos/module-scope-map.js

@@ -596,6 +596,7 @@ const UNOWNED_ROOTS = Object.freeze({
   'CODE_OF_CONDUCT.md': 'project governance text',
   'CONTRIBUTING.md': 'project governance text',
   'GOVERNANCE.md': 'project governance text',
+  'GOVERNMENT.md': 'project governance text',
   // Top-level product/design statements, read by humans before any module matters.
   'README.md': 'repo front door',
   'DESIGN.md': 'top-level design statement',

package/src/module-api.js

@@ -75,7 +75,7 @@ const { responsibilityFor, ROLE_RESPONSIBILITIES } = require('./role-responsibil
 // MAJOR (see allowBoxScope below): passes the request through untouched.
 function deprecatedNoopMiddleware(_req, _res, next) { next(); }
 
-const CORE_VERSION = '1.21.99'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.21.101'; // 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('discord'); log.info('mounted');

package/tests/worktree_helper.mjs

@@ -27,7 +27,7 @@ import os from 'node:os';
 import path from 'node:path';
 
 const require = createRequire(import.meta.url);
-const { worktreeNameFor, needsJunction, removalPlan, nodeModulesState, shadowingNodeModules, huskDisposition } = require('../scripts/gds/worktree.js');
+const { worktreeNameFor, needsJunction, removalPlan, nodeModulesState, shadowingNodeModules, huskDisposition, unlinkNodeModulesLink } = require('../scripts/gds/worktree.js');
 
 const HOUR = 60 * 60 * 1000;
 
@@ -118,16 +118,75 @@ test('nodeModulesState: absent / real-dir / junction classified from disk', () =
     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); }
+    // Removing the link (the helper's own unlink step) must not touch the target.
+    // On Linux CI this is a plain dir-symlink — the case rmdir crashed on with
+    // ENOTDIR (task 1004582); on Windows it is a real junction.
+    unlinkNodeModulesLink(link);
+    eq(fs.existsSync(link), false, 'the link itself is gone');
     eq(fs.existsSync(path.join(target, 'canary.txt')), true, 'target survives link removal');
   } finally {
     fs.rmSync(base, { recursive: true, force: true });
   }
 });
 
+// The win32 rmdir fallback, driven through a fake fs so every platform runs it.
+function fakeFs(unlinkCode) {
+  const calls = [];
+  return {
+    calls,
+    lstatSync: () => ({ isSymbolicLink: () => true }),
+    unlinkSync: (p) => {
+      calls.push(['unlink', p]);
+      if (unlinkCode) { const e = new Error(unlinkCode); e.code = unlinkCode; throw e; }
+    },
+    rmdirSync: (p) => { calls.push(['rmdir', p]); },
+  };
+}
+
+test('unlinkNodeModulesLink: unlink succeeds → rmdir is never called', () => {
+  const f = fakeFs(null);
+  unlinkNodeModulesLink('L', { platform: 'linux', fsImpl: f });
+  eqArr(f.calls, [['unlink', 'L']]);
+});
+
+for (const code of ['EPERM', 'EISDIR']) {
+  test(`unlinkNodeModulesLink: win32 + ${code} falls back to rmdir`, () => {
+    const f = fakeFs(code);
+    unlinkNodeModulesLink('L', { platform: 'win32', fsImpl: f });
+    eqArr(f.calls, [['unlink', 'L'], ['rmdir', 'L']]);
+  });
+  test(`unlinkNodeModulesLink: non-win32 + ${code} rethrows, no rmdir`, () => {
+    const f = fakeFs(code);
+    let thrown = null;
+    try { unlinkNodeModulesLink('L', { platform: 'linux', fsImpl: f }); } catch (e) { thrown = e.code; }
+    eq(thrown, code);
+    eqArr(f.calls, [['unlink', 'L']]);
+  });
+}
+
+test('unlinkNodeModulesLink: win32 + any other code rethrows, no rmdir', () => {
+  const f = fakeFs('EBUSY');
+  let thrown = null;
+  try { unlinkNodeModulesLink('L', { platform: 'win32', fsImpl: f }); } catch (e) { thrown = e.code; }
+  eq(thrown, 'EBUSY');
+  eqArr(f.calls, [['unlink', 'L']]);
+});
+
+test('unlinkNodeModulesLink refuses a REAL directory and leaves it intact', () => {
+  const base = fs.mkdtempSync(path.join(os.tmpdir(), 'wt-helper-test-'));
+  try {
+    const real = path.join(base, 'node_modules');
+    fs.mkdirSync(real);
+    fs.writeFileSync(path.join(real, 'canary.txt'), 'x');
+    let threw = false;
+    try { unlinkNodeModulesLink(real); } catch (_) { threw = true; }
+    eq(threw, true, 'a real dir is refused');
+    eq(fs.existsSync(path.join(real, 'canary.txt')), true, 'its contents survive');
+  } 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', () => {