@bongos/core 1.19.727 → 1.19.729

package/.bongos-core.json

@@ -2,11 +2,11 @@
   "artifact": "bongos-core",
   "manifest_schema": 1,
   "generator": "scripts/gds/package-core.js",
-  "core_version": "1.19.727",
-  "core_contract": "1.19.727",
-  "source_commit": "8860409e2ae4203c97fdcf95d358324f1a5a6bc7",
+  "core_version": "1.19.729",
+  "core_contract": "1.19.729",
+  "source_commit": "399870dc41f0d71a77a79d1d48131070fbfe9828",
   "source_ref": "HEAD",
-  "built_at": "2026-09-13T14:53:19.653Z",
+  "built_at": "2026-09-13T15:18:33.790Z",
   "redaction": {
     "model": "docs-redacted+functional-verbatim",
     "docs_redacted": 477,
@@ -17,7 +17,7 @@
     "gate": "passed"
   },
   "file_count": 2602,
-  "tree_sha256": "90088f98c9e09359faf4ac7099d2444ec5c2434976bf00f808739710cfd4588f",
+  "tree_sha256": "787a5eba74a590d18c09c0e87a40655d7eb5dcdcd9865660bc209392db78f8ca",
   "files": [
     {
       "path": ".claude/skills/ask-for-help/SKILL.md",
@@ -272,7 +272,7 @@
     {
       "path": ".claude/skills/worktree-clean/SKILL.md",
       "mode": "0000644",
-      "sha256": "a51d79d257e7d502dc9becbd2f45e05af881b840ee287ce0e450ebb64a93dec4"
+      "sha256": "4819fe448f4e35c3c7c3f4784718d51a7a4469f3c644d1b6c57b693b79da129e"
     },
     {
       "path": ".devcontainer/Dockerfile",
@@ -2482,7 +2482,7 @@
     {
       "path": "docs/module-api-changelog.md",
       "mode": "0000644",
-      "sha256": "0fe647bae4864d656c91c5a89051ba630819dc6a792cea693bd7a0e4cecfa630"
+      "sha256": "635d466437068d5f1e6875cb6307c836dc57eb10c2ac7a50c39aba18c423f386"
     },
     {
       "path": "docs/modules-contract.md",
@@ -2747,7 +2747,7 @@
     {
       "path": "docs/recipes/windows-builders.md",
       "mode": "0000644",
-      "sha256": "6760a34d404aa68c61896983c8aa621bd26244e5c98ed056045b3467359c4b53"
+      "sha256": "eef830271b0e77a161c61759970346b63730d3e6049b4944d24586abadb843de"
     },
     {
       "path": "docs/recipes/work-on-a-task-from-your-dev-box.md",
@@ -7512,12 +7512,12 @@
     {
       "path": "package-lock.json",
       "mode": "0000644",
-      "sha256": "6cda7a3bc2dfd1ee7c15be6da4033a876e7222411c5e13057599d4568f557e01"
+      "sha256": "51b06b26595e4850db318f091ea0cf01399add4ddff70489a7bd42c62e6dc85c"
     },
     {
       "path": "package.json",
       "mode": "0000644",
-      "sha256": "b7e89ddb86b30e922b78a438509453e72eab5e4d0293c6769f70fa0d3335dcda"
+      "sha256": "46d1603b0da9d38a1afe85820cfce1f1f485e26f692a7b077bf8951793dc1ac6"
     },
     {
       "path": "public-docs/index.html",
@@ -8822,7 +8822,7 @@
     {
       "path": "scripts/gds/stale-worktrees.js",
       "mode": "0000644",
-      "sha256": "40c5ef66ef5efc3754da367e64604af765d2e595986fc7af1af10f793d1a57e0"
+      "sha256": "b615f8cdf4b1e74d997fff9e8eaa7f5c77276eefaa02f1a0c0becd80f8697620"
     },
     {
       "path": "scripts/gds/start.js",
@@ -8907,7 +8907,7 @@
     {
       "path": "scripts/gds/worktree.js",
       "mode": "0000644",
-      "sha256": "af95d7ae434d587dae654e24640163c44ac293edb11d2c0deb979b855701ac85"
+      "sha256": "69f167d079c1900568f740d8d4a1a2288f5ff47146634209f8a1a9350a3aa5e2"
     },
     {
       "path": "scripts/hall-preview/README.md",
@@ -9317,7 +9317,7 @@
     {
       "path": "src/module-api.js",
       "mode": "0000644",
-      "sha256": "ee4b22adb7ca8da6d689ac51fff3b65f6dfb4f6319e1685cd1e8d89b760f0903"
+      "sha256": "c96971200e4ddee6375444c84cd0433158c026423638822b76ae941fa50f3956"
     },
     {
       "path": "src/module-loader/catalog.js",
@@ -9987,7 +9987,7 @@
     {
       "path": "tests/cli_package.mjs",
       "mode": "0000644",
-      "sha256": "b81bf677dc884eef7bd88128d024e3eed1699faa31a680b7d5d4cfdbcd11b09c"
+      "sha256": "334c952eadfdd7d5ee467cfd50a9f178a23389e94288cdb6a431c69c6e8e327c"
     },
     {
       "path": "tests/cli_sessions.mjs",
@@ -12647,7 +12647,7 @@
     {
       "path": "tests/stale_worktrees.mjs",
       "mode": "0000644",
-      "sha256": "e003d6391d14212198c0e55494190e702adc0a27c2820362afe3d676c67a4963"
+      "sha256": "97ca351bc03b3d56b99239739818c11fea384691ee597b54a0c4bef60be196f6"
     },
     {
       "path": "tests/start_env_guard.mjs",
@@ -13017,7 +13017,7 @@
     {
       "path": "tests/worktree_helper.mjs",
       "mode": "0000644",
-      "sha256": "9d511e7cf21cea05cc565e9e5022c7c86cd3cf0d67053125ec27aeae3348e30a"
+      "sha256": "cac88e36d1e2ef2cbe2799275186f0787431b5b636fc52d1325b5dbbfcd56368"
     },
     {
       "path": "tests/world_tokens.mjs",

package/.claude/skills/worktree-clean/SKILL.md

@@ -1,27 +1,29 @@
 ---
 name: worktree-clean
 description: >-
-  Remove per-claim worktrees whose work already landed, via the junction-safe worktree.js remove — never raw git worktree remove, which follows the node_modules junction. Triggers: "/worktree-clean", "prune stale worktrees", or the SessionStart line "Stale worktrees: N".
+  Remove per-claim worktrees whose work landed, and sweep the husks a locked remove leaves, via junction-safe worktree.js — never raw git worktree remove, which follows the node_modules junction. Triggers: "/worktree-clean", "prune stale worktrees", "worktree husks".
 ---
 
 **Script skill (authoritative).** Two scripts do the work; this skill only sequences them and shows the list before anything is removed.
 
 ## What this skill does
 
-1. `node scripts/gds/stale-worktrees.js` — the list. A worktree is **stale** when its branch is an ancestor of `origin/main` (the land happened) or the branch is gone (the ship deleted it). Detached worktrees and unmerged branches are **live** and never touched. Run `git fetch origin` first so "merged into main" reflects today's main, not the last fetch.
+1. `node scripts/gds/stale-worktrees.js` — the list. A worktree is **stale** when its branch is an ancestor of `origin/main` (the land happened) or the branch is gone (the ship deleted it). Detached worktrees and unmerged branches are **live** and never touched. Run `git fetch origin` first so "merged into main" reflects today's main, not the last fetch. The same call also names **husks** — directories under `.claude/worktrees/` that git does not list as worktrees at all (step 6).
 2. Show the stale list to the builder (names + why). The worktree holding the **current claim** is never stale by construction (its branch is unmerged), but say so if the builder asks.
 3. For each stale name: `node scripts/gds/worktree.js remove <name>`. That helper unlinks any node_modules junction BEFORE `git worktree remove`, which is the whole reason raw git is off-limits here (learning in `scripts/gds/CLAUDE.md` → "Gotchas / invariants"; the `git-guard.js` PreToolUse hook blocks the raw form).
    - A worktree with untracked leftovers (`.playwright-mcp/`, a stray screenshot) refuses without `--force`. Show the `git -C <path> status --porcelain` output; if it is only untracked junk, re-run with `--force`. If it shows **modified tracked files**, skip it and report — someone's uncommitted work is not this skill's to delete.
 4. `git worktree prune` — clears any registrations whose directory is already gone.
 5. Print the tally: removed / skipped (with why) / still live. Stale branches stay — a merged branch is harmless and `git branch -d` is the ship's business, not a cleanup chore.
+6. `node scripts/gds/worktree.js prune-husks` — the **husks**: directories still under `.claude/worktrees/` that git no longer lists. They are the residue of an OneDrive-locked `git worktree remove`, which deregisters the worktree but cannot delete the directory (task 1002594). Nothing else can see them: a deregistered husk is absent from `git worktree list`, which is all step 1's stale scan reads. The sweep deletes only an **empty** husk that this session is not standing in and that has not been touched in 24h — the harness parks live session directories in the same folder and a fresh one looks exactly like residue. It prints the reason for every skip; `--force` waives only the 24h rule.
 
 ## Safety
 
 - Read-only until step 3; the list is shown first.
 - Never `--force` over modified tracked files.
 - Never deletes branches, never touches the primary checkout, never calls `git worktree remove` directly.
+- The husk sweep uses `rmdir`, never a recursive delete: a husk that gained files between the check and the call is refused by the filesystem, not emptied.
 - No claim is needed: worktrees are local machine state, not project state — nothing here is committed.
 
 ## Calls
 
-`node scripts/gds/stale-worktrees.js [--json]` · `node scripts/gds/worktree.js remove <name> [--force]` · `git worktree prune`.
+`node scripts/gds/stale-worktrees.js [--json]` · `node scripts/gds/worktree.js remove <name> [--force]` · `node scripts/gds/worktree.js prune-husks [--force]` · `git worktree prune`.

package/docs/module-api-changelog.md

@@ -1928,5 +1928,9 @@ is load-bearing: the script throws rather than guess if it is missing, and
         landed since 1.19.725 with no explicit bump. run 34763380132. (task 1002620)
   1.19.727 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
         landed since 1.19.726 with no explicit bump. run 34763937238. (task 1002620)
+  1.19.728 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.727 with no explicit bump. run 34764630913. (task 1002620)
+  1.19.729 — CI auto-patch (publish-on-merge, ADR 0161): carrier for merges
+        landed since 1.19.728 with no explicit bump. run 34765179905. (task 1002620)
 ---------------------------------------------------------------------------
 ```

package/docs/recipes/windows-builders.md

@@ -79,7 +79,23 @@ checkout's `node_modules` (by walk-up inside the repo, by junction outside); a s
 `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.
+check for you). Don't fight it with retries.
+
+The empty husk directory does **not** delete on its own — this page and the helper both used to
+say it did, and nothing ever swept one (task 1002594; 20 directories under `.claude/worktrees/`
+for 13 registered worktrees when it was finally measured). Worse, a husk is invisible to
+`stale-worktrees.js`, which reads `git worktree list` — precisely the list a deregistered
+directory has left. Sweep them when the lock has cleared:
+
+```bash
+node scripts/gds/worktree.js prune-husks
+```
+
+It deletes only an **empty** husk that the current process is not standing in and that has not
+been touched in 24 hours, and prints the reason for every skip. Those rules are not paranoia: the
+Claude Code harness creates its own session directory under `.claude/worktrees/` — not a git
+worktree at all, and live while that session runs — so a fresh one is indistinguishable from
+residue. `--force` waives the 24-hour rule and nothing else.
 
 ## Local unit tests: baseline first, CI is truth
 

package/package-lock.json

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@bongos/core",
-  "version": "1.19.727",
+  "version": "1.19.729",
   "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/stale-worktrees.js

@@ -13,20 +13,35 @@
 // deleted it). Both are pure git facts, so this runs in well under a second at
 // SessionStart. The primary checkout is never listed.
 //
+// THE SECOND LEAK — HUSKS (task 1002594). Under OneDrive, `git worktree remove`
+// often errors 'Permission denied' / 'Device or resource busy' but still
+// DEREGISTERS the worktree, so `worktree.js remove` treats deregistration as
+// success and tells the builder the locked directory "deletes on its own later".
+// Nothing ever deleted it. That residue is invisible to the scan above BY
+// CONSTRUCTION: a deregistered husk is, by definition, absent from
+// `git worktree list`, which is the only thing classifyWorktrees reads. Measured
+// on 2026-09-13 in this checkout: 20 directories under .claude/worktrees/, 13
+// registered — 7 husks that no probe had ever named. So the husk scan reads the
+// DISK and subtracts what git knows: the mirror image of the stale scan.
+//
 // Usage:
 //   node scripts/gds/stale-worktrees.js --line   # ONE line, or nothing; always exit 0
-//   node scripts/gds/stale-worktrees.js --json   # { stale: [{name, path, branch, why}], live: [...] }
-//   node scripts/gds/stale-worktrees.js          # human report; exit 0 clean, 1 stale found
+//   node scripts/gds/stale-worktrees.js --json   # { stale: [...], live: [...], husks: [...] }
+//   node scripts/gds/stale-worktrees.js          # human report; exit 0 clean, 1 stale/husks found
 //
-// Removal is deliberately NOT here — `/worktree-clean` walks this list through
-// `node scripts/gds/worktree.js remove <name>`, the junction-safe path.
+// Removal is deliberately NOT here — `/worktree-clean` walks these lists through
+// `node scripts/gds/worktree.js remove <name>` and `worktree.js prune-husks`,
+// the junction-safe paths.
 
 'use strict';
 
 const { execFileSync } = require('child_process');
+const fs = require('fs');
 const path = require('path');
 
 const MAIN_REF = 'origin/main';
+// Where worktree.js add puts a worktree by default; the only place husks collect.
+const WORKTREES_SUBDIR = path.join('.claude', 'worktrees');
 
 function git(args, cwd) {
   return execFileSync('git', args, { cwd, encoding: 'utf8', stdio: ['ignore', 'pipe', 'ignore'] });
@@ -64,6 +79,20 @@ function classifyWorktrees(worktrees, { isMerged, branchExists }) {
   return { stale, live };
 }
 
+// Directories sitting in .claude/worktrees/ that git does not list as a worktree —
+// the deregister-then-never-delete residue. Pure (the directory listing and the
+// registered paths are both injected) so the set arithmetic is testable without
+// creating directories. Case- and separator-insensitive on both sides, because the
+// porcelain and fs.readdirSync disagree about drive-letter case on Windows.
+function classifyHusks({ dirNames, worktreePaths, worktreesRoot }) {
+  const norm = (p) => path.resolve(p).replace(/\\/g, '/').toLowerCase();
+  const registered = new Set(worktreePaths.map(norm));
+  return dirNames
+    .filter((name) => !registered.has(norm(path.join(worktreesRoot, name))))
+    .sort()
+    .map((name) => ({ name, path: path.join(worktreesRoot, name) }));
+}
+
 // Three git calls total, whatever the worktree count: the list, every local branch,
 // every branch already merged into origin/main. Per-worktree subprocesses would be
 // N+1 over exactly the number this probe exists to shrink.
@@ -77,18 +106,40 @@ function scan(cwd) {
   let merged;
   try { merged = refNames(git(['branch', '--merged', MAIN_REF, '--format=%(refname:short)'], cwd)); }
   catch { merged = new Set(); } // no origin/main yet (fresh clone, no fetch) → nothing is provably stale
-  return classifyWorktrees(worktrees, {
+  const r = classifyWorktrees(worktrees, {
     branchExists: (b) => existing.has(b),
     isMerged: (b) => merged.has(b),
   });
+  // The main checkout is always the first porcelain entry, so the husk directory is
+  // derivable without a second git call.
+  const mainRoot = worktrees.length ? worktrees[0].path : cwd;
+  const worktreesRoot = path.join(mainRoot, WORKTREES_SUBDIR);
+  let dirNames = [];
+  try {
+    dirNames = fs.readdirSync(worktreesRoot, { withFileTypes: true })
+      .filter((d) => d.isDirectory()).map((d) => d.name);
+  } catch { dirNames = []; } // no worktrees dir yet → no husks, not an error
+  r.husks = classifyHusks({ dirNames, worktreePaths: worktrees.map((w) => w.path), worktreesRoot });
+  return r;
+}
+
+function namesOf(list) {
+  const names = list.slice(0, 6).map((s) => s.name).join(', ');
+  return names + (list.length > 6 ? ` +${list.length - 6} more` : '');
 }
 
 function lineFor(r) {
-  if (!r.stale.length) return '';
-  const names = r.stale.slice(0, 6).map((s) => s.name).join(', ');
-  const more = r.stale.length > 6 ? ` +${r.stale.length - 6} more` : '';
-  return `Stale worktrees: ${r.stale.length} whose work already landed (${names}${more}). `
-    + 'Run /worktree-clean — never `git worktree remove` (it follows the node_modules junction).';
+  const husks = r.husks || [];
+  const parts = [];
+  if (r.stale.length) {
+    parts.push(`Stale worktrees: ${r.stale.length} whose work already landed (${namesOf(r.stale)}). `
+      + 'Run /worktree-clean — never `git worktree remove` (it follows the node_modules junction).');
+  }
+  if (husks.length) {
+    parts.push(`Worktree husks: ${husks.length} deregistered dir(s) still on disk (${namesOf(husks)}). `
+      + 'Run node scripts/gds/worktree.js prune-husks.');
+  }
+  return parts.join(' ');
 }
 
 function main() {
@@ -102,12 +153,16 @@ function main() {
   }
   if (argv.includes('--json')) { console.log(JSON.stringify(r, null, 2)); return; }
   if (argv.includes('--line')) { const l = lineFor(r); if (l) console.log(l); return; }
-  console.log(`  Worktrees: ${r.live.length} live, ${r.stale.length} stale`);
+  const husks = r.husks || [];
+  console.log(`  Worktrees: ${r.live.length} live, ${r.stale.length} stale, ${husks.length} husks`);
   for (const s of r.stale) console.log(`    stale  ${s.name}  (${s.why})`);
+  for (const h of husks) console.log(`    husk   ${h.name}  (on disk, not registered)`);
   for (const l of r.live) console.log(`    live   ${l.name}  [${l.branch || 'detached'}]`);
-  if (r.stale.length) { console.log('  Remove with: node scripts/gds/worktree.js remove <name>   (or /worktree-clean)'); process.exit(1); }
+  if (r.stale.length) console.log('  Remove with: node scripts/gds/worktree.js remove <name>   (or /worktree-clean)');
+  if (husks.length) console.log('  Sweep husks with: node scripts/gds/worktree.js prune-husks');
+  if (r.stale.length || husks.length) process.exit(1);
 }
 
 if (require.main === module) main();
 
-module.exports = { parseWorktreeList, classifyWorktrees, lineFor };
+module.exports = { parseWorktreeList, classifyWorktrees, classifyHusks, lineFor };

package/scripts/gds/worktree.js

@@ -22,9 +22,22 @@
 // which claim.js surfaces at claim time. Deliberately short here: two full
 // copies of the same prose would drift apart.
 //
+// THE RESIDUE `remove` LEAVES — HUSKS (task 1002594). Under OneDrive, the
+// `git worktree remove` below often errors 'Permission denied' / 'Device or
+// resource busy' while still DEREGISTERING the worktree, so this tool has always
+// accepted deregistration as success. What it then TOLD the builder was wrong:
+// the locked directory does not "delete on its own later", and no probe could
+// even see it, because stale-worktrees.js reads `git worktree list` and a
+// deregistered husk is by definition absent from it. Measured 2026-09-13: 20
+// directories under .claude/worktrees/, 13 registered. `prune-husks` is the
+// deferred half of deregister-then-delete-later, and it is deliberately manual —
+// the harness parks LIVE session directories in the same folder, so see
+// huskDisposition for the three rules that keep a sweep from deleting one.
+//
 // 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 prune-husks [--force]
 //   node scripts/gds/worktree.js list
 
 const fs = require('node:fs');
@@ -110,6 +123,31 @@ function removalPlan({ nodeModulesState }) {
     : ['git-worktree-remove'];
 }
 
+// A husk younger than this may still be a LIVE session's directory rather than
+// abandoned residue, so the default sweep leaves it for tomorrow.
+const HUSK_QUIET_MS = 24 * 60 * 60 * 1000;
+
+// Should this deregistered husk be deleted? Pure, so the safety rules can be proved
+// without creating directories.
+//
+// WHY EACH RULE (task 1002594). The husks that collect under .claude/worktrees/ are
+// not all the same animal: most are the OneDrive-lock residue cmdRemove below leaves
+// behind, but the harness also creates a session directory there that is not a git
+// worktree at all and is LIVE while its session runs. Deleting one of those pulls the
+// floor out from under another agent's cwd. So: never a directory this process is
+// standing in, never one holding files (residue is empty by construction — anything
+// else is somebody's leftovers to inspect by hand), and by default never one touched
+// today, because "recently created and empty" is exactly what a fresh session dir
+// looks like. `force` waives only the age rule; in-use and non-empty are absolute.
+function huskDisposition({ isCwdOrAncestor, isEmpty, ageMs, force }) {
+  if (isCwdOrAncestor) return { action: 'skip', why: 'in use — this session is inside it' };
+  if (!isEmpty) return { action: 'skip', why: 'not empty — inspect by hand' };
+  if (!force && ageMs < HUSK_QUIET_MS) {
+    return { action: 'skip', why: 'touched in the last 24h — may be a live session dir (--force sweeps it)' };
+  }
+  return { action: 'delete', why: 'empty, deregistered' };
+}
+
 // -- CLI ----------------------------------------------------------------------
 
 function git(args, opts = {}) {
@@ -272,7 +310,11 @@ function cmdRemove(root, argv) {
         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)');
+          // This used to claim the husk "deletes on its own later". It does not:
+          // nothing deleted it and nothing could see it either, since a deregistered
+          // directory is absent from `git worktree list` (task 1002594).
+          console.log('  (the directory husk is still locked — OneDrive — and stays on disk.');
+          console.log('   Sweep it once the lock clears: node scripts/gds/worktree.js prune-husks)');
         } else {
           console.error(`worktree remove failed — ${e.message}`);
           // The worktree is still live but its junction is already unlinked —
@@ -301,6 +343,56 @@ function cmdRemove(root, argv) {
   console.log(`  (branch "${path.basename(wtPath)}" left in place — the land/ship pipeline owns branch cleanup)`);
 }
 
+// The other half of the OneDrive story (task 1002594): cmdRemove above accepts a
+// failed `git worktree remove` as long as the worktree got DEREGISTERED, and tells
+// the builder the locked directory "deletes on its own later". Nothing did — and
+// nothing could even SEE the residue, because stale-worktrees.js reads
+// `git worktree list` and a deregistered husk is by definition absent from it. This
+// is the sweep that makes that promise true.
+function cmdPruneHusks(root, argv) {
+  const force = hasFlag('--force', argv);
+  const worktreesRoot = path.join(root, '.claude', 'worktrees');
+  const registered = new Set(listWorktrees(root).map((p) => path.resolve(p).replace(/\\/g, '/').toLowerCase()));
+  let entries;
+  try { entries = fs.readdirSync(worktreesRoot, { withFileTypes: true }); }
+  catch { console.log('no .claude/worktrees directory — nothing to sweep.'); return; }
+
+  const cwd = path.resolve(process.cwd());
+  const now = Date.now();
+  let deleted = 0;
+  let skipped = 0;
+  for (const ent of entries) {
+    if (!ent.isDirectory()) continue;
+    const huskPath = path.join(worktreesRoot, ent.name);
+    if (registered.has(path.resolve(huskPath).replace(/\\/g, '/').toLowerCase())) continue; // a real worktree: `remove` owns it
+    let isEmpty;
+    let ageMs;
+    try {
+      isEmpty = fs.readdirSync(huskPath).length === 0;
+      ageMs = now - fs.statSync(huskPath).mtimeMs;
+    } catch (e) {
+      console.log(`  skip    ${ent.name}  (unreadable — ${e.message})`);
+      skipped += 1;
+      continue;
+    }
+    // path.relative is '' for the cwd itself and has no leading '..' for an ancestor.
+    const rel = path.relative(path.resolve(huskPath), cwd);
+    const isCwdOrAncestor = rel === '' || !rel.startsWith('..');
+    const { action, why } = huskDisposition({ isCwdOrAncestor, isEmpty, ageMs, force });
+    if (action === 'skip') { console.log(`  skip    ${ent.name}  (${why})`); skipped += 1; continue; }
+    try {
+      fs.rmdirSync(huskPath); // rmdir, never rm -r: it refuses a directory that gained files since the check
+      console.log(`  removed ${ent.name}`);
+      deleted += 1;
+    } catch (e) {
+      // Still locked (OneDrive) — say so plainly; the next sweep gets it.
+      console.log(`  skip    ${ent.name}  (still locked — ${e.code || e.message}; it will sweep next run)`);
+      skipped += 1;
+    }
+  }
+  console.log(`husks: ${deleted} removed, ${skipped} skipped.`);
+}
+
 function cmdList(root) {
   const all = listWorktrees(root);
   for (const w of all) {
@@ -322,13 +414,17 @@ function main() {
   }
   if (cmd === 'add') return cmdAdd(root, argv);
   if (cmd === 'remove') return cmdRemove(root, argv);
+  if (cmd === 'prune-husks') return cmdPruneHusks(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 prune-husks [--force]');
   console.error('       node scripts/gds/worktree.js list');
   process.exit(2);
 }
 
 if (require.main === module) main();
 
-module.exports = { worktreeNameFor, needsJunction, removalPlan, nodeModulesState, shadowingNodeModules };
+module.exports = {
+  worktreeNameFor, needsJunction, removalPlan, nodeModulesState, shadowingNodeModules, huskDisposition,
+};

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.727'; // CI auto-patch carrier (ADR 0161); changelog: docs/module-api-changelog.md
+const CORE_VERSION = '1.19.729'; // 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/cli_package.mjs

@@ -185,7 +185,13 @@ test('the packed tarball installs and every verb runs with no repo present', (t)
   // base or on missing arguments. Failing that way is fine; failing to find a file is not.
   const LOAD_ARGS = {
     login:   ['login'],
-    reauth:  ['reauth'],
+    // `--no-open` is load-bearing, not cosmetic (task 1003909). HOME is a throwaway here, so
+    // there is no session and reauth takes its no-session path — which launches the builder's
+    // default browser at the dead API base (`rundll32 url.dll,FileProtocolHandler` on Windows).
+    // Without the flag, every run of this suite pops a connection-refused tab on the machine
+    // under test. The flag skips only the spawn: the script still loads, still prints its
+    // guidance, still exits 10, so every assertion below is unchanged.
+    reauth:  ['reauth', '--no-open'],
     setup:   ['setup'],
     box:     ['box'],
     shell:   ['shell'],
@@ -203,9 +209,42 @@ test('the packed tarball installs and every verb runs with no repo present', (t)
     'every advertised verb needs an entry here, or it goes unexercised',
   );
 
+  // No verb may launch a GUI on the machine running the suite (task 1003909). A script that can
+  // spawn a browser has two ways to be safe here, and it must pick one:
+  //   * it offers an opt-out flag   → the LOAD_ARGS entry above passes it, or
+  //   * it stops short of the launch → STOPS_SHORT_OF_LAUNCH names a marker that must stay absent.
+  // Proving it, rather than assuming it, is the point: a verb that starts reaching its launcher
+  // fails here instead of on someone's desktop.
+  const LAUNCHES_BROWSER = /FileProtocolHandler|xdg-open/;
+  const OPT_OUT = '--no-open';
+  const STOPS_SHORT_OF_LAUNCH = {
+    // `bongos login` opens a browser from inside the device flow, several network steps past the
+    // instance-URL prompt — and with empty stdin that prompt is never answered, so the process
+    // ends right there. `▸ Connecting to` is the first thing printed once a URL is accepted, so
+    // its ABSENCE is the proof this run stopped well short of the launch.
+    login: /Connecting to/,
+  };
+  const mustStopShort = {};
+  for (const [verb, args] of Object.entries(LOAD_ARGS)) {
+    const src = fs.readFileSync(path.join(REPO_ROOT, 'scripts', 'gds', VERBS[verb].script), 'utf8');
+    if (!LAUNCHES_BROWSER.test(src)) continue;
+    if (src.includes(OPT_OUT)) {
+      assert.ok(args.includes(OPT_OUT),
+        `bongos ${verb} can spawn a browser and accepts ${OPT_OUT} — pass it in LOAD_ARGS, or this suite opens a window on the builder's machine`);
+      continue;
+    }
+    assert.ok(STOPS_SHORT_OF_LAUNCH[verb],
+      `bongos ${verb} can spawn a browser and has no ${OPT_OUT} — give it one, or add a STOPS_SHORT_OF_LAUNCH entry proving this run never reaches the launch`);
+    mustStopShort[verb] = STOPS_SHORT_OF_LAUNCH[verb];
+  }
+
   for (const [verb, args] of Object.entries(LOAD_ARGS)) {
     const res = runVerb(args);
     const all = `${res.stdout}\n${res.stderr}`;
+    if (mustStopShort[verb]) {
+      assert.doesNotMatch(all, mustStopShort[verb],
+        `bongos ${verb} got past the point where it can spawn a browser on this machine:\n${all}`);
+    }
     assert.ok(!/Cannot find module|MODULE_NOT_FOUND|ERR_MODULE_NOT_FOUND/.test(all),
       `bongos ${verb} hit a missing file — the manifest is incomplete:\n${all}`);
     assert.ok(!/ERR_REQUIRE_ESM|SyntaxError|ReferenceError/.test(all),

package/tests/stale_worktrees.mjs

@@ -2,7 +2,7 @@
 // facts (task 1003365): no repo, no API, just the porcelain text + two predicates.
 import { test } from 'node:test';
 import assert from 'node:assert/strict';
-import { parseWorktreeList, classifyWorktrees, lineFor } from '../scripts/gds/stale-worktrees.js';
+import { parseWorktreeList, classifyWorktrees, classifyHusks, lineFor } from '../scripts/gds/stale-worktrees.js';
 
 const PORCELAIN = [
   'worktree C:/repo',
@@ -64,3 +64,59 @@ test('--line caps the named list at six', () => {
   assert.match(line, /\+2 more/);
   assert.doesNotMatch(line, /task-7/);
 });
+
+// ---- husks (task 1002594) ----
+//
+// The stale scan above reads `git worktree list`, so it is blind BY CONSTRUCTION to
+// the residue of an OneDrive-locked remove: that directory was deregistered, which is
+// precisely what makes it absent from the porcelain. The husk scan is the mirror —
+// disk minus git.
+
+const WT_ROOT = 'C:/repo/.claude/worktrees';
+
+test('a directory on disk that git does not list is a husk', () => {
+  const husks = classifyHusks({
+    dirNames: ['task-1', 'task-2', 'leftover'],
+    worktreePaths: ['C:/repo', 'C:/repo/.claude/worktrees/task-1', 'C:/repo/.claude/worktrees/task-2'],
+    worktreesRoot: WT_ROOT,
+  });
+  assert.deepEqual(husks.map((h) => h.name), ['leftover']);
+});
+
+test('a registered worktree is never a husk, whatever the drive-letter case or separator', () => {
+  const husks = classifyHusks({
+    dirNames: ['task-1'],
+    worktreePaths: ['C:/repo', 'c:\\repo\\.claude\\worktrees\\task-1'],
+    worktreesRoot: WT_ROOT,
+  });
+  assert.deepEqual(husks, []);
+});
+
+test('every directory is a husk when git lists no worktrees but the main checkout', () => {
+  const husks = classifyHusks({
+    dirNames: ['b', 'a'],
+    worktreePaths: ['C:/repo'],
+    worktreesRoot: WT_ROOT,
+  });
+  assert.deepEqual(husks.map((h) => h.name), ['a', 'b']); // sorted, so the report is stable
+});
+
+test('--line names husks even when nothing is stale, and stays empty when neither exists', () => {
+  assert.equal(lineFor({ stale: [], live: [], husks: [] }), '');
+  assert.equal(lineFor({ stale: [], live: [] }), ''); // husks absent entirely (older caller)
+  const line = lineFor({ stale: [], live: [], husks: [{ name: 'task-9' }] });
+  assert.match(line, /Worktree husks: 1 /);
+  assert.match(line, /task-9/);
+  assert.match(line, /prune-husks/);
+  assert.doesNotMatch(line, /Stale worktrees/);
+});
+
+test('--line reports both leaks in one line when both exist', () => {
+  const line = lineFor({
+    stale: [{ name: 'task-1', why: 'merged into main' }],
+    live: [],
+    husks: [{ name: 'task-2' }],
+  });
+  assert.match(line, /Stale worktrees: 1 /);
+  assert.match(line, /Worktree husks: 1 /);
+});

package/tests/worktree_helper.mjs

@@ -27,7 +27,9 @@ import os from 'node:os';
 import path from 'node:path';
 
 const require = createRequire(import.meta.url);
-const { worktreeNameFor, needsJunction, removalPlan, nodeModulesState, shadowingNodeModules } = require('../scripts/gds/worktree.js');
+const { worktreeNameFor, needsJunction, removalPlan, nodeModulesState, shadowingNodeModules, huskDisposition } = require('../scripts/gds/worktree.js');
+
+const HOUR = 60 * 60 * 1000;
 
 let passed = 0;
 let failed = 0;
@@ -189,6 +191,41 @@ test('the nearest stray wins, matching node\'s own resolution order', () => {
     'node stops at the first node_modules it meets walking up');
 });
 
+// ---- 5. huskDisposition (task 1002594) ----
+//
+// A husk is a directory under .claude/worktrees/ that git does not list as a
+// worktree — the residue of an OneDrive-locked `git worktree remove` that
+// deregistered but could not delete. Three of the four inputs are SAFETY rules, and
+// each one has a real directory behind it: the harness puts live session dirs in the
+// same folder, and they look exactly like fresh residue.
+
+test('an old, empty, unused husk is swept', () => {
+  eq(huskDisposition({ isCwdOrAncestor: false, isEmpty: true, ageMs: 48 * HOUR, force: false }).action, 'delete');
+});
+
+test('the directory this session is standing in is never swept — not even with --force', () => {
+  eq(huskDisposition({ isCwdOrAncestor: true, isEmpty: true, ageMs: 48 * HOUR, force: true }).action, 'skip');
+});
+
+test('a husk holding files is never swept — not even with --force', () => {
+  eq(huskDisposition({ isCwdOrAncestor: false, isEmpty: false, ageMs: 48 * HOUR, force: true }).action, 'skip');
+});
+
+test('a husk touched in the last 24h is held back — a live session dir looks just like this', () => {
+  const d = huskDisposition({ isCwdOrAncestor: false, isEmpty: true, ageMs: 2 * HOUR, force: false });
+  eq(d.action, 'skip');
+  eq(/24h/.test(d.why), true, 'the skip reason names the age rule');
+});
+
+test('--force waives the age rule, and only the age rule', () => {
+  eq(huskDisposition({ isCwdOrAncestor: false, isEmpty: true, ageMs: 2 * HOUR, force: true }).action, 'delete');
+});
+
+test('in-use outranks every other rule', () => {
+  eq(huskDisposition({ isCwdOrAncestor: true, isEmpty: false, ageMs: 0, force: true }).why,
+    'in use — this session is inside it');
+});
+
 console.log('');
 console.log(`worktree_helper: ${passed} passed, ${failed} failed`);
 process.exit(failed > 0 ? 1 : 0);