@bongos/core 1.21.175 → 1.21.176

package/scripts/bongos/worktree.js

@@ -0,0 +1,449 @@
+#!/usr/bin/env node
+// scripts/bongos/worktree.js — junction-safe worktree lifecycle (task 1002809).
+//
+// The trap this kills: a worktree OUTSIDE the repo root (C:/tmp/wt-N — used to
+// dodge OneDrive file locks) can't resolve node_modules by walking up, so
+// Windows builders hand-made junctions with `cmd //c mklink` from Git Bash —
+// which mangles quoted targets containing spaces (dead junction) — and then
+// `git worktree remove` FOLLOWED the junction and deleted the SHARED
+// node_modules of the main checkout. This helper creates junctions with
+// fs.symlinkSync(..., 'junction') (no shell, no quoting) and always removes the
+// junction BEFORE git worktree remove. Worktrees INSIDE the repo
+// (.claude/worktrees/<name>, the project default) need no junction at all.
+//
+// THE OTHER SHARED-STATE TRAP — `git stash` (task 1003344). The stash stack
+// belongs to the REPOSITORY, not the worktree: every worktree shares one stack
+// with the main checkout and with each other, so a stash here and a pop there
+// hands one agent another's tree and silently drops the original entry. Commit
+// on your own branch instead — a commit is worktree-local, a stash is not. The
+// full rule (named-stash escape hatch, clean-baseline advice, and the
+// `git fsck --unreachable` recovery path) has ONE canonical copy, in
+// scripts/bongos/CLAUDE.md under "Gotchas / invariants", and is learning 1000215,
+// 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/bongos/worktree.js add <task-id|name> [--path <dir> | --outside] [--base <ref>]
+//   node scripts/bongos/worktree.js remove <name|path> [--force]
+//   node scripts/bongos/worktree.js prune-husks [--force]
+//   node scripts/bongos/worktree.js list
+
+const fs = require('node:fs');
+const path = require('node:path');
+const { execFileSync } = require('node:child_process');
+const { arg, hasFlag } = require('./cli-lib');
+const { registerMergeDriver, MERGE_DRIVER_NAME } = require('./install-git-hooks');
+
+// -- pure helpers (exported for tests/worktree_helper.mjs) --------------------
+
+// A numeric task id becomes the conventional task-<id>; an explicit name passes
+// through; anything with path separators or dot-traversal is rejected (null).
+function worktreeNameFor(raw) {
+  const s = String(raw == null ? '' : raw).trim();
+  if (!s || s === '.' || s === '..') return null;
+  if (/^\d+$/.test(s)) return `task-${s}`;
+  if (!/^[A-Za-z0-9._-]+$/.test(s)) return null;
+  return s;
+}
+
+// Is the worktree OUTSIDE the repo root? Inside the repo, node's resolution
+// walks up to the main checkout's node_modules; outside it can't. Pure string
+// compare (case-insensitive, both slash styles); callers pass absolute paths.
+function isOutsideRepo({ wtPath, repoRoot }) {
+  const norm = (p) => String(p).replace(/\\/g, '/').replace(/\/+$/, '').toLowerCase();
+  const wt = norm(wtPath);
+  const root = norm(repoRoot);
+  return !(wt === root || wt.startsWith(root + '/'));
+}
+
+// Only a win32 worktree outside the repo root gets a junction (the OneDrive
+// dodge); posix symlink semantics differ and aren't the trap this fixes.
+function needsJunction({ wtPath, repoRoot, platform }) {
+  if (platform !== 'win32') return false;
+  return isOutsideRepo({ wtPath, repoRoot });
+}
+
+// A node_modules directory sitting BETWEEN an inside-repo worktree and the repo
+// root — e.g. `.claude/worktrees/node_modules` — shadowing the main checkout's.
+// Returns its path, or null. Pure: `existsFn` is injected so this is testable
+// without building a directory tree.
+//
+// WHY THIS IS WORTH DETECTING (task 1003627). An inside-repo worktree deliberately
+// gets NO junction: node's resolution walks up to the main checkout, which is the
+// documented design. But walk-up stops at the FIRST node_modules it meets, so a
+// stray one on the way up silently wins for EVERY inside-repo worktree at once.
+//
+// Measured, not assumed: with the same package present at both levels, a probe in
+// `<root>/worktrees/wt` resolved to the main checkout's copy with no stray, and to
+// the stray the moment one existed one level up.
+//
+// The failure is quiet in the worst way — `require('pino')` still SUCCEEDS, just
+// from somewhere nobody installed on purpose, so a partial or stale stray reads as
+// a mysterious version skew rather than as a path problem. Two agents hit this on
+// 2026-09-04 (tasks 1002331, 1003577) and both concluded `worktree.js add` had
+// failed to create a junction. It had not: for an inside-repo worktree there is no
+// junction to create, and needsJunction — a pure win32-and-outside-root string
+// compare, unchanged since task 1002809 — never consulted a directory at all. The
+// missing piece was never a junction; it was anyone SAYING that the stray was there.
+function shadowingNodeModules({ wtPath, repoRoot, existsFn }) {
+  const exists = existsFn || ((p) => fs.existsSync(p));
+  if (isOutsideRepo({ wtPath, repoRoot })) return null; // outside gets a junction instead
+  let dir = path.dirname(path.resolve(wtPath));
+  const root = path.resolve(repoRoot);
+  // Walk from the worktree's PARENT up to (but not including) the repo root: a
+  // node_modules AT the root is the one we want resolution to reach.
+  while (dir !== root && dir.length > root.length) {
+    const candidate = path.join(dir, 'node_modules');
+    if (exists(candidate)) return candidate;
+    const parent = path.dirname(dir);
+    if (parent === dir) break; // hit the filesystem root without meeting repoRoot
+    dir = parent;
+  }
+  return null;
+}
+
+// Ordered removal steps. The junction MUST go before git worktree remove (git
+// follows it into the shared node_modules); a REAL node_modules dir is left for
+// git to refuse — this tool never deletes real directories.
+function removalPlan({ nodeModulesState }) {
+  return nodeModulesState === 'junction'
+    ? ['unlink-junction', 'git-worktree-remove']
+    : ['git-worktree-remove'];
+}
+
+// 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 = {}) {
+  return execFileSync('git', args, { encoding: 'utf8', ...opts }).trim();
+}
+
+// Main checkout root from any worktree — same derivation as merge-lock.js.
+function mainWorktreeRoot() {
+  const common = git(['rev-parse', '--git-common-dir']);
+  const abs = path.isAbsolute(common) ? common : path.resolve(process.cwd(), common);
+  return path.dirname(abs);
+}
+
+function listWorktrees(root) {
+  const out = git(['worktree', 'list', '--porcelain'], { cwd: root });
+  return out.split('\n').filter((l) => l.startsWith('worktree ')).map((l) => l.slice('worktree '.length));
+}
+
+function nodeModulesState(wtPath) {
+  const p = path.join(wtPath, 'node_modules');
+  let st;
+  try { st = fs.lstatSync(p); } catch (_) { return 'absent'; }
+  return st.isSymbolicLink() ? 'junction' : 'real-dir';
+}
+
+// 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();
+  const byPath = all.find((w) => norm(w) === norm(nameOrPath));
+  if (byPath) return byPath;
+  // Case-insensitive, matching the filesystem (and the byPath compare above).
+  const byName = all.filter((w) => path.basename(w).toLowerCase() === String(nameOrPath).toLowerCase());
+  if (byName.length === 1) return byName[0];
+  if (byName.length > 1) {
+    console.error(`worktree: "${nameOrPath}" matches ${byName.length} worktrees — pass the full path:`);
+    for (const w of byName) console.error(`  ${w}`);
+    process.exit(2);
+  }
+  return null;
+}
+
+function cmdAdd(root, argv) {
+  const name = worktreeNameFor(argv[1]);
+  if (!name) {
+    console.error('worktree add: pass a task id (→ task-<id>) or a simple name (letters/digits/._-).');
+    process.exit(2);
+  }
+  const explicitPath = arg('--path', argv);
+  const outside = hasFlag('--outside', argv);
+  // --outside exists to dodge OneDrive file locks — a Windows problem. On posix
+  // an outside-repo worktree would just lose node_modules resolution (no
+  // junction is created there), so refuse rather than hand back a silently
+  // broken tree; the in-repo default works everywhere.
+  if (outside && process.platform !== 'win32') {
+    console.error('worktree add: --outside is a Windows OneDrive dodge; use the default in-repo location here');
+    console.error('  (an outside-repo worktree on this platform cannot resolve the shared node_modules).');
+    process.exit(2);
+  }
+  const wtPath = path.resolve(explicitPath
+    || (outside ? path.join('C:/tmp', name)
+                : path.join(root, '.claude', 'worktrees', name)));
+  // Default base origin/main so the branch starts current; best-effort fetch
+  // first (offline still works off the local ref).
+  const base = arg('--base', argv) || 'origin/main';
+  try { execFileSync('git', ['fetch', 'origin', 'main'], { cwd: root, stdio: 'ignore', timeout: 15000 }); } catch (_) { /* offline is fine */ }
+
+  console.log(`worktree add: ${wtPath}  (branch ${name}, base ${base})`);
+  try {
+    execFileSync('git', ['worktree', 'add', wtPath, '-b', name, base], { cwd: root, stdio: 'inherit' });
+  } catch (e) {
+    console.error(`worktree add failed — ${e.message}`);
+    console.error('  (a branch of that name may already exist: remove it or pick another name)');
+    process.exit(1);
+  }
+
+  // Register the otb-regen merge driver (task 1003537). .gitattributes routes the
+  // generated files through it, but git honours that ONLY where merge.otb-regen.driver is
+  // configured — which install-git-hooks.js does per CLONE, on /builder-setup. A builder
+  // who never ran the installer got a silent TEXTUAL merge of files no textual merge can
+  // resolve: measured on task 1002334, a scripts/bongos/CLAUDE.md symbol block matching
+  // neither generator, clean enough that nothing flagged it until fitness ran in CI.
+  // Worktree-per-claim is the default path to a new tree, so doing it here is what closes
+  // that gap for a clone whose owner never ran setup. git config is shared with every
+  // linked worktree, so registering against the main root covers this tree and all later
+  // ones. Idempotent, and best-effort on purpose: failing to register only restores the
+  // pre-existing fallback-to-conflict behaviour, which must never fail `worktree add`.
+  const driver = registerMergeDriver(root);
+  if (driver.ok) {
+    console.log(`  merge driver '${MERGE_DRIVER_NAME}' registered (generated files auto-regenerate on merge)`);
+  } else {
+    console.log(`  ⚠ could not register the '${MERGE_DRIVER_NAME}' merge driver: ${driver.error}`);
+    console.log('    (generated files will merge textually here; ship.js still self-heals the same set)');
+  }
+
+  if (needsJunction({ wtPath, repoRoot: root, platform: process.platform })) {
+    const target = path.join(root, 'node_modules');
+    if (!fs.existsSync(target)) {
+      console.error(`⚠ ${target} does not exist — run npm install in the MAIN checkout first`);
+      console.error('  (worktrees never get their own node_modules; they share the main one).');
+    } else {
+      // fs.symlinkSync with type 'junction' needs no shell and no elevation —
+      // this is the fix for the mangled `cmd //c mklink` quoting trap.
+      fs.symlinkSync(target, path.join(wtPath, 'node_modules'), 'junction');
+      console.log(`  node_modules junction → ${target}`);
+      console.log('  (remove this worktree with `node scripts/bongos/worktree.js remove` — it unlinks the junction first;');
+      console.log('   a bare `git worktree remove` would follow the junction into the SHARED node_modules.)');
+    }
+  } else if (isOutsideRepo({ wtPath, repoRoot: root })) {
+    // Explicit --path outside the repo on posix: no junction is created here,
+    // so say plainly that node_modules won't resolve rather than fail later.
+    console.log('  ⚠ this worktree is outside the repo — node_modules will NOT resolve from here on this platform.');
+  } else {
+    // Inside the repo: no junction by design, node walks up to the main checkout.
+    // But walk-up stops at the FIRST node_modules, so name a stray one in between
+    // — it silently captures every inside-repo worktree and `require` still
+    // succeeds, which is what makes it so hard to spot (task 1003627).
+    const shadow = shadowingNodeModules({ wtPath, repoRoot: root });
+    if (shadow) {
+      console.log(`  ⚠ a stray node_modules sits between this worktree and the repo root: ${shadow}`);
+      console.log("     node's walk-up stops THERE, not at the main checkout — so this worktree (and every other");
+      console.log('     one beside it) resolves dependencies from a directory nobody installed on purpose.');
+      console.log('     Delete it, then re-run: dependencies belong in the MAIN checkout only.');
+    }
+  }
+  console.log('');
+  console.log('Next:');
+  console.log(`  cd "${wtPath}"`);
+  console.log('  node scripts/bongos/claim.js <task-id>   (worktree auto-detected)');
+}
+
+function cmdRemove(root, argv) {
+  const target = argv[1];
+  if (!target) {
+    console.error('usage: node scripts/bongos/worktree.js remove <name|path> [--force]');
+    process.exit(2);
+  }
+  const wtPath = resolveWorktreePath(root, target);
+  if (!wtPath) {
+    console.error(`worktree remove: "${target}" is not a registered worktree (see: git worktree list).`);
+    process.exit(1);
+  }
+  if (path.resolve(wtPath).toLowerCase() === path.resolve(root).toLowerCase()) {
+    console.error('worktree remove: refusing to remove the MAIN checkout.');
+    process.exit(2);
+  }
+  const state = nodeModulesState(wtPath);
+  for (const step of removalPlan({ nodeModulesState: state })) {
+    if (step === 'unlink-junction') {
+      // 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];
+      try {
+        execFileSync('git', args, { cwd: root, stdio: 'inherit' });
+        console.log(`worktree removed: ${wtPath}`);
+      } catch (e) {
+        // OneDrive briefly locks the dir; the failed attempt usually still
+        // DEREGISTERS the worktree — verify instead of fighting it with retries.
+        const still = listWorktrees(root).some((w) => path.resolve(w).toLowerCase() === path.resolve(wtPath).toLowerCase());
+        if (!still) {
+          console.log(`worktree deregistered: ${wtPath}`);
+          // 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/bongos/worktree.js prune-husks)');
+        } else {
+          console.error(`worktree remove failed — ${e.message}`);
+          // The worktree is still live but its junction is already unlinked —
+          // restore it so the tree stays usable (node_modules keeps resolving)
+          // instead of stranding the builder back at hand-rolled mklink.
+          if (state === 'junction') {
+            try {
+              fs.symlinkSync(path.join(root, 'node_modules'), path.join(wtPath, 'node_modules'), 'junction');
+              console.error('  node_modules junction restored — the worktree remains fully usable.');
+            } catch (restoreErr) {
+              console.error(`  could not restore the node_modules junction (${restoreErr.message}) —`);
+              console.error('  re-create it: node -e "require(\'fs\').symlinkSync(\'<main>/node_modules\', \'<wt>/node_modules\', \'junction\')"');
+            }
+          }
+          if (state === 'real-dir') {
+            console.error('  node_modules here is a REAL directory (not a junction) — if it and the other');
+            console.error('  untracked files are disposable, re-run with --force.');
+          } else {
+            console.error('  re-run with --force if the leftover untracked files are disposable.');
+          }
+          process.exit(1);
+        }
+      }
+    }
+  }
+  console.log(`  (branch "${path.basename(wtPath)}" left in place — the land/ship pipeline owns branch cleanup)`);
+}
+
+// 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) {
+    const isMain = path.resolve(w).toLowerCase() === path.resolve(root).toLowerCase();
+    const tag = isMain ? 'main checkout' : `node_modules: ${nodeModulesState(w)}`;
+    console.log(`${w}   [${tag}]`);
+  }
+}
+
+function main() {
+  const argv = process.argv.slice(2);
+  const cmd = argv[0];
+  let root;
+  try {
+    root = mainWorktreeRoot();
+  } catch (e) {
+    console.error('worktree: not a git repo (cannot resolve the main checkout):', e.message);
+    process.exit(2);
+  }
+  if (cmd === 'add') return cmdAdd(root, argv);
+  if (cmd === 'remove') return cmdRemove(root, argv);
+  if (cmd === 'prune-husks') return cmdPruneHusks(root, argv);
+  if (cmd === 'list') return cmdList(root);
+  console.error('usage: node scripts/bongos/worktree.js add <task-id|name> [--path <dir> | --outside] [--base <ref>]');
+  console.error('       node scripts/bongos/worktree.js remove <name|path> [--force]');
+  console.error('       node scripts/bongos/worktree.js prune-husks [--force]');
+  console.error('       node scripts/bongos/worktree.js list');
+  process.exit(2);
+}
+
+if (require.main === module) main();
+
+module.exports = {
+  worktreeNameFor, needsJunction, removalPlan, nodeModulesState, shadowingNodeModules, huskDisposition,
+  unlinkNodeModulesLink,
+};

package/scripts/discord/post.js

@@ -20,7 +20,7 @@
 // (src/bongos/routes/builders.js), an outage heads-up
 // (modules/provisioning/pollers/liveness-notify.js) and the style-guide audit
 // (scripts/cron/style_guide_audit.sh). Builder housekeeping names its channel:
-// scripts/gds/pulse.js's reclaim nudge passes --channel ship_feed.
+// scripts/bongos/pulse.js's reclaim nudge passes --channel ship_feed.
 
 const fs = require('node:fs');
 const { postWebhook } = require('./lib');

package/scripts/gds/README.md

@@ -0,0 +1,9 @@
+# scripts/gds/ — forwarders only (@bongos-forwarder)
+
+Generated by `scripts/bongos/codemod-rename-scripts-gds.js` (task 1004848); do not edit.
+
+The builder CLI moved to [`scripts/bongos/`](../bongos/). Every executable file here is a
+forwarder that runs the real script at the same path under `scripts/bongos/` and warns once, so
+callers this repo cannot update in the same change — systemd units on a box, cron routines, a
+hosted project's hooks and skills before its next core upgrade — keep working. Point new code at
+`scripts/bongos/`. Task 1003706 removes this directory once a release has carried it.

package/scripts/gds/abandon.js

@@ -1,137 +1,7 @@
 #!/usr/bin/env node
-// Abandon a task — the terminal "retire this task" transition (task 987).
-//
-// Usage:
-//   node scripts/gds/abandon.js <task-id> [--reason "..."]
-//
-// Sets the task's status to 'abandoned' (the missing first-class lifecycle
-// transition — the GDS already had promote/ship/confirm/resolve). Use this to
-// retire a task that is no longer relevant — a stale chore, or a duplicate of
-// work another session already shipped — instead of leaving it in 'ready' as
-// claimable noise.
-//
-// Metic+ (the route is requireRank('metic', 'archon') as of ADR 0152; Archon-only
-// before that). Refuses on a shipped task (immutable history) and on a task with an
-// active claim (release it first); idempotent on an already-abandoned task. The
-// abandon + reason are recorded in audit_log by the server's writing middleware, so
-// the ledger stays complete. Retired the wrong task? POST /tasks/<id>/promote
-// restores it to backlog at the same rank (db.restoreTask) — no Archon SQL needed.
-
-const { errCode, cliClient, requireSession, arg } = require('./cli-lib');
-// task 1003153 — the live-status set, shared with the dead-edge detector so
-// "who did this cut strand" means the same thing in both places.
-const { LIVE_STATUSES } = require('../../modules/lifecycle/dead-deps.js');
-// task 1003779 — the other thing a cut leaves behind: the code itself.
-const { leftoversForTask, leftoverNotice } = require('../../modules/lifecycle/abandon-leftovers.js');
-const { execFileSync } = require('node:child_process');
-
-// Best-effort git, always. Every call here is advisory decoration on an abandon
-// that has ALREADY landed, so a missing git, a detached network or a shallow
-// clone must return "I don't know" — never throw, and never abort the command.
-function git(args, ms = 20000) {
-  return execFileSync('git', args, { encoding: 'utf8', timeout: ms, stdio: ['ignore', 'pipe', 'ignore'] });
-}
-
-// The remote branches this task owns. ONE network round trip, scoped to the two
-// name shapes worktree.js produces — listing all 800-odd heads to filter locally
-// would be the expensive way to learn the same thing.
-function remoteBranchesFor(taskId) {
-  try {
-    const out = git(['ls-remote', '--heads', 'origin', `refs/heads/task-${taskId}`, `refs/heads/task-${taskId}-*`]);
-    return out.split('\n').map((l) => l.split('\t')[1] || '').filter(Boolean)
-      .map((r) => r.replace(/^refs\/heads\//, ''));
-  } catch (_) { return null; }  // null = could not look
-}
-
-// How many commits the branch carries that main does not. Returns null when it
-// cannot be determined, which leftoversForTask reports as undetermined rather
-// than folding into "clean" — see that module's header.
-function commitsAheadOfMain(branch) {
-  try {
-    git(['fetch', 'origin', '--quiet', branch, 'main']);
-    const n = Number(String(git(['rev-list', '--count', 'FETCH_HEAD', '--not', 'origin/main'])).trim());
-    return Number.isFinite(n) ? n : null;
-  } catch (_) { return null; }
-}
-
-
-(async () => {
-  await requireSession();
-  const args = process.argv.slice(2);
-  const taskId = Number(args[0]);
-  if (!Number.isFinite(taskId)) {
-    console.error('usage: node scripts/gds/abandon.js <task-id> [--reason "..."]');
-    process.exit(2);
-  }
-  const reason = arg('--reason', args) || '';
-
-  const api = await cliClient();
-  const r = await api.tasks.postTasksIdAbandon({ id: taskId, body: { reason } });
-  if (!r.ok) {
-    // ADR 0116 nests the slug at error.code; a flat `r.data.error === '…'` compares an
-    // object to a string and never matches, so every branch below was unreachable
-    // against a live server (task 1003658).
-    const code = errCode(r.data);
-    if (code === 'cannot_abandon_shipped') {
-      console.error(`Task #${taskId} is shipped — shipped work is immutable history and cannot be abandoned.`);
-    } else if (code === 'task_has_active_claim') {
-      console.error(`Task #${taskId} has an active claim. Release it first:`);
-      console.error(`  node scripts/gds/release.js ${taskId}`);
-    } else if (code === 'task_not_found') {
-      console.error(`Task #${taskId} not found.`);
-    } else if (r.status === 403) {
-      console.error('Abandoning a task needs Metic+ rank (ADR 0152).');
-    } else {
-      console.error(`abandon failed (${r.status}):`, r.data);
-    }
-    process.exit(1);
-  }
-
-  if (r.data.alreadyAbandoned) {
-    console.log(`Task #${r.data.taskId} (${r.data.taskTitle}) was already abandoned — no change.`);
-  } else {
-    console.log(`Abandoned task #${r.data.taskId}: ${r.data.taskTitle}`);
-    console.log(`Status: ${r.data.previousStatus} -> abandoned.`);
-  }
-
-  // task 1003153 — REPORT what this cut just stranded. An abandoned task can
-  // never ship, so every LIVE task depending on it is now permanently gated:
-  // it will not auto-promote (task_is_fully_unblocked wants status='shipped')
-  // and cannot be claimed (DEPS_NOT_SHIPPED). Per the owner ruling the gate
-  // stays strict, which makes surfacing this at cut time the whole remedy —
-  // the edge needs a deliberate decision, and the person cutting the task is
-  // the one who knows. Best-effort: never fail an abandon over the report.
-  try {
-    const dep = await api.tasks.getTasksId({ id: taskId, query: { include: 'deps' } });
-    const dependents = (dep?.data?.task?.blocks || []).filter((b) => LIVE_STATUSES.has(String(b.status)));
-    if (dependents.length) {
-      console.log('');
-      console.log(`⚠ TOP PRIORITY — this cut just STRANDED ${dependents.length} live task(s) that depend on #${taskId}:`);
-      for (const b of dependents) console.log(`    #${b.id}  [${b.status}]  ${b.title}`);
-      console.log('  They can never auto-promote or be claimed while this edge stands, because an');
-      console.log('  abandoned task can never ship. Resolve each edge deliberately — do not leave it:');
-      console.log(`    drop the edge:    node scripts/gds/api.js DELETE /api/bongos/dependencies --body '{"from_kind":"task","from_id":<dependent>,"to_kind":"task","to_id":${taskId}}'`);
-      console.log(`    or restore this:  node scripts/gds/api.js POST /api/bongos/tasks/${taskId}/promote`);
-      console.log('  Sweep for any you miss:  node scripts/gds/audit-deps.js --stranded');
-    }
-  } catch (_) { /* the abandon already landed — the report is advisory */ }
-
-  // task 1003779 — REPORT the code this cut orphaned. Abandoning retires the ROW;
-  // the branch and its PR stay exactly where they were, reading as live work.
-  // Task 1002464 was cut carrying two commits never merged to main, and the
-  // follow-up filed off its review (task 1003626) then sat at 'ready' asking for
-  // changes to a function that exists nowhere on main — 'sequence.js --check'
-  // called it clear to run. Nothing had said the branch was dead, so nothing could.
-  // Same posture as the stranded-dependents report above: best-effort, and it
-  // never fails an abandon that already landed.
-  try {
-    const branches = remoteBranchesFor(taskId);
-    if (branches && branches.length) {
-      const notice = leftoverNotice(taskId, leftoversForTask(taskId, { branches, aheadCount: commitsAheadOfMain }));
-      if (notice) console.log(notice);
-    }
-  } catch (_) { /* advisory only */ }
-})().catch((err) => {
-  console.error('fatal:', err);
-  process.exit(1);
-});
+// scripts/gds/abandon.js — @bongos-forwarder (task 1004848). Generated by
+// scripts/bongos/codemod-rename-scripts-gds.js; do not edit.
+// The real script is scripts/bongos/abandon.js. This forwarder keeps callers that still name
+// the old path working, and warns once so they get repointed. Task 1003706 removes it.
+'use strict';
+require('../bongos/forwarder.js').forward(module, 'abandon.js');