@ericrisco/rsc 1.2.0 → 1.2.1

package/manifest.json

@@ -1,5 +1,5 @@
 {
-  "version": "1.2.0",
+  "version": "1.2.1",
   "counts": {
     "skills": 272,
     "agents": 33,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ericrisco/rsc",
-  "version": "1.2.0",
+  "version": "1.2.1",
   "description": "Eric Risco's agent-skills catalog as a granular, self-recommending CLI installer.",
   "type": "module",
   "bin": {

package/scripts/rsc.js

@@ -487,6 +487,52 @@ async function main() {
       say('Use: npx @ericrisco/rsc registry refresh | registry status');
       return;
     }
+    case 'worktrees': {
+      // The deterministic half of "the cleanup is the default". `ship` and the `worktrees` skill call
+      // this instead of judging by eye, which is what turns a rule that was only ever written down
+      // into one that actually runs.
+      const W = await import('../targets/worktree-reaper.mjs');
+      // From inside a worktree, home is the main checkout — you cannot remove the floor you stand on.
+      const root = W.resolveMainRoot(process.cwd());
+      const sub = argv[1];
+
+      if (!W.isCleanupEnabled(root)) {
+        say(`worktree cleanup is off for this project (.rsc/${W.OPT_OUT}). Delete that file to turn it back on.`);
+        return;
+      }
+
+      const candidates = W.classifyWorktrees(root).filter((c) => c.verdict !== 'skip');
+
+      if (sub === 'reap') {
+        const one = argv[2] && !argv[2].startsWith('--') ? argv[2] : undefined;
+        // Naming a path SELECTS it; it does not accept the risk of removing it. Conflating the two
+        // meant the strongest refusal in the module — "holds files that are in no commit" — was
+        // defeated by an argument the sweep itself told the agent to type.
+        const confirmed = argv.includes('--confirm');
+        const targets = one ? [one] : candidates.filter((c) => c.verdict === 'safe').map((c) => c.path);
+        if (!targets.length) { say('nothing to clean up.'); return; }
+        for (const t of targets) {
+          const out = W.reapWorktree(root, t, { confirmed });
+          if (out.removed) {
+            say(`✅ removed ${out.path}`);
+            if (out.branchKept) say(`   branch ${out.branch} kept — git will not delete it safely, and while it exists the commits are recoverable.`);
+          } else {
+            say(`⏸  kept ${t} — ${out.reason}`);
+            if (one && !confirmed) say('   If that is acceptable and you want it gone anyway: add --confirm');
+            process.exitCode = 1;
+          }
+        }
+        return;
+      }
+
+      if (!candidates.length) { say('No worktrees to clean up.'); return; }
+      say(`${candidates.length} worktree(s) whose work has landed:`);
+      for (const c of candidates) say(W.describe(c));
+      say('');
+      say('Remove the safe ones:  npx @ericrisco/rsc worktrees reap');
+      say('Remove one by name:    npx @ericrisco/rsc worktrees reap <path> [--confirm]');
+      return;
+    }
     case 'capabilities': {
       // "What do I already have that solves this?" — the deterministic step the
       // automation-gap rule requires BEFORE anyone proposes creating a skill or an
@@ -760,7 +806,7 @@ async function main() {
       return void (await runPurge(argv.includes('--dry-run'), argv.includes('--with-docs')));
     default:
       say(`rsc: unknown command '${cmd}'.`);
-      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | memory <on|off|status|save|resume|learn|metrics> | sello <on|off|status|…> | backups | restore <id|latest> | upgrade | repair | uninstall <id> | purge');
+      say('Use: npx @ericrisco/rsc | add <id...> | install --profile <p> | consult "<text>" | list | capabilities [--full|gap-log] | audit | registry refresh | doctor | sync | memory <on|off|status|save|resume|learn|metrics> | sello <on|off|status|…> | worktrees [reap [path] [--confirm]] | backups | restore <id|latest> | upgrade | repair | uninstall <id> | purge');
       say('Any command takes --target <claude|codex|cursor|copilot|gemini|…> (comma-separate for several)');
       say('   → without it, rsc uses the assistant already installed here; if two are, it asks instead of guessing.');
       process.exitCode = 1;

package/skills/ship/SKILL.md

@@ -116,12 +116,17 @@ Stacked PR / feature-track support still fits inside the three landing options:
 git switch main && git pull --ff-only
 git merge --no-ff feature/<slug> -m "feat: <what shipped> (<spec-slug>)"   # no AI trailer
 git push origin main
-git branch -d feature/<slug>          # delete merged branch; -D only if intentionally dropping unmerged work
+npx @ericrisco/rsc worktrees reap <path-of-this-feature-worktree>   # by name: this one, not all of them
+git branch -d feature/<slug> 2>/dev/null || true   # no worktree involved? then the branch alone
 git push origin --delete feature/<slug> 2>/dev/null || true
 ```
 
 Use `--no-ff` so the feature is one legible merge commit tied to the spec. Confirm the trunk still builds after the merge if the repo has a local gate (defer the actual run to `verify`).
 
+**Name the path.** Bare `worktrees reap` retires *every* worktree that currently qualifies, which is not what landing one branch means — with `parallel` running two streams, it is how shipping A deletes B. Pass the path of the worktree this branch lived in; capture it before you switch, since you are usually standing in it (`WT=$(pwd)`).
+
+Naming a path selects it, it does not accept the risk of removing it: a worktree holding anything unsaved is still refused, with the reason. Add `--confirm` only after the user has seen that reason and said yes. Run it from anywhere — it finds the main checkout itself.
+
 ### Option 2 — pull request
 
 Write the **commit(s)** clean, push, then open the PR with `gh`. The PR body links the spec/plan and lists what shipped — **and carries no AI attribution.**
@@ -158,6 +163,8 @@ Implements `02-DOCS/wiki/sdd/specs/<slug>.md`. <the user-facing reason>
 
 Then either let the gate run (team/CI) or self-merge once green: `gh pr merge --squash --delete-branch` (or `--merge` to preserve the history). Squash when the branch history is noisy; preserve when each commit is meaningful.
 
+Once it is merged, pull the trunk and reap the one you landed — `git switch main && git pull --ff-only && npx @ericrisco/rsc worktrees reap "$WT"`. A squashed pull request is exactly the case the reaper judges by content rather than by commit identity, so it is recognised as landed; the local branch is kept, because git will not delete a squashed branch safely and while it exists the work is recoverable.
+
 For stacked PRs, create each PR against the previous branch or against a feature-track branch, with bodies that name their dependency:
 
 ```markdown
@@ -172,13 +179,13 @@ Never stack to hide review risk. Stack because each slice is independently revie
 - **Park:** leave the branch, push it so it's not lost (`git push -u origin feature/<slug>`), and log *why it's parked* to `02-DOCS/wiki/sdd/decisions.md`. Do not merge.
 - **Discard:** deletion is **destructive and unrecoverable** once the branch is gone from both sides, so it takes an explicit confirmation that quotes the branch name (the literal `yes, delete feature/<slug>`) before `git branch -D`. Anything ambiguous means keep it. Log the discard and the reason so the dead-end is remembered, not re-attempted.
 
-**If the work lived in a worktree, clean it up provenance-aware.** After the merge/park/discard, only
-remove a worktree **rsc created** (under `.worktrees/`/`worktrees/` or the `../<repo>-<slug>` dir),
-never one the user or a native tool owns. Guard first: confirm it's a linked worktree
-(`git rev-parse --git-dir` ≠ `--git-common-dir`), rule out a submodule
-(`git rev-parse --show-superproject-working-tree` is empty), `cd` to the main working tree before
-removing, and run `git worktree prune` after. Full procedure: `../worktrees/SKILL.md` (Provenance-aware
-cleanup). If a native `EnterWorktree`-style tool created it, exit through that tool, not raw git.
+**Park and discard do NOT reap.** The cleanup default acts only on work that is already in the trunk;
+a parked branch is the opposite of that, and `worktrees reap` refuses it by design. Leave the worktree
+where it is — the next `ship` that lands the branch will retire it. Discarding a worktree along with
+unmerged work stays what it always was: explicit, confirmed with the quoted branch name, and logged.
+
+If a native `EnterWorktree`-style tool created the workspace, exit through that tool rather than the
+reaper — it owns its own lifecycle and its tracking has to stay consistent.
 
 ## Commit message discipline
 

package/skills/worktrees/SKILL.md

@@ -109,39 +109,47 @@ git switch -c feat/<slug> origin/<default-branch>
 ```
 
 ```bash
-# when the work is done and merged (or abandoned) — clean up the worktree
-git worktree remove ../<repo>-<slug>      # refuses if dirty; resolve first, don't force blindly
-git branch -d feat/<slug>                  # -d (safe) not -D, unless the user confirms discarding
+# when the work has landed — the cleanup is the default, and it is a command, not a judgement call
+npx @ericrisco/rsc worktrees reap
 ```
 
 Either way, the contract is identical: **after this step, the cwd is an isolated branch off a clean
 base, and the default-branch checkout is exactly as it was.** Confirm that out loud (at the dial's
 level) before handing to `implement`.
 
-### Provenance-aware cleanup (don't remove a workspace you didn't create)
+### Cleanup is the default, and it is not yours to judge
 
-Removing the wrong worktree leaves phantom state and can destroy someone else's in-progress work.
-Before any `git worktree remove`, clear these guards:
+A worktree whose work is already in the trunk is retired **by default** — you do not decide that by
+reading the situation, because "is this safe to delete?" is a deterministic question and a wrong
+answer costs a directory that cannot be brought back. Ask the command:
 
 ```bash
-# 1) Are we even inside a linked worktree? (GIT_DIR != GIT_COMMON_DIR ⇒ yes)
-[ "$(git rev-parse --git-dir)" != "$(git rev-parse --git-common-dir)" ] && echo "linked worktree"
-# 2) Submodule false-positive guard — never treat a submodule as a worktree to remove
-git rev-parse --show-superproject-working-tree   # non-empty ⇒ this is a submodule; STOP
-# 3) cd to the MAIN working tree before removing (you cannot remove the worktree you stand in)
-cd "$(git rev-parse --git-common-dir)/.."
-git worktree remove <path>
-git worktree prune                                # self-heal stale administrative entries
+npx @ericrisco/rsc worktrees        # every landed worktree, with a verdict and a reason
+npx @ericrisco/rsc worktrees reap   # retire the ones that are safe with nothing to lose
+npx @ericrisco/rsc worktrees reap <path>   # retire one the user has just confirmed
 ```
 
-- **Only remove worktrees rsc/you created** — those under `.worktrees/` or `worktrees/`, or the
-  `../<repo>-<slug>` this skill made. A worktree the user or a native tool owns is **not yours to
-  delete**; leave it and say so.
-- **Native tool owns its own lifecycle.** If you isolated via a native `EnterWorktree`-style tool,
-  exit through that tool's `remove`/`keep` — do **not** hand-run `git worktree remove` on a workspace
-  the native tool created; let it clean up so its tracking stays consistent.
-- **`git worktree prune`** after a remove clears stale metadata when a directory vanished out from
-  under git — cheap self-healing, safe to run.
+Three things have to hold before a worktree is retired without asking, and each fails towards
+**keeping** it:
+
+- **rsc created it** — location *and* branch shape both match. Only one matches → it might be the
+  user's, so it is asked about, never removed silently. Neither → foreign; not touched, not offered.
+- **The branch adds nothing the trunk does not have** — asked about *content*, so a squash-merged
+  pull request counts as landed. Its branch is kept even so: git will not delete it safely, and while
+  it exists the commits survive a wrong call.
+- **Nothing inside would be lost** — not just "no pending changes": untracked and ignored files count,
+  because a worktree that git calls clean can still hold the only copy of a `.env` or a local
+  database. Installed dependencies and build output are the one carve-out.
+
+Anything else is reported with the reason and the way out. A refusal you cannot act on is not safety.
+
+**The native tool owns its own lifecycle.** If you isolated via a native `EnterWorktree`-style tool,
+exit through that tool's `remove`/`keep`; the reaper is for worktrees git alone knows about.
+
+**When the command is unavailable** (no rsc in this project), the manual equivalent is: confirm it is
+a linked worktree (`git rev-parse --git-dir` ≠ `--git-common-dir`), rule out a submodule
+(`git rev-parse --show-superproject-working-tree` must be empty), `cd` to the main working tree, then
+`git worktree remove` and `git worktree prune`. Never `-D` a branch to make the cleanup succeed.
 
 ## Model tier — `light` (opt-in routing)
 

package/targets/claude.js

@@ -85,6 +85,9 @@ export function wireHook(paths) {
   // Shared by session-start + userprompt-gate. Hooks are materialized file by file, so a module
   // they import must be copied as their SIBLING — a subdirectory import would break once copied.
   copyFileSync(join(HERE, 'hook-once.mjs'), join(paths.projectRoot, '.rsc', 'hook-once.mjs'));
+  // Same reason: session-start imports the reaper for the landed-worktree sweep, so it travels as a
+  // sibling too. Missing it does not break startup — the sweep is wrapped — it just goes silent.
+  copyFileSync(join(HERE, 'worktree-reaper.mjs'), join(paths.projectRoot, '.rsc', 'worktree-reaper.mjs'));
   copyFileSync(join(HERE, 'session-start.mjs'), scriptDest);
 
   const suggestMd = `${paths.skillDir('suggest')}/SKILL.md`;

package/targets/session-start.mjs

@@ -209,6 +209,37 @@ Opt out with .rsc/.no-claudemd-check.
   } catch { /* no CLAUDE.md → nothing to check */ }
 }
 
+// Worktree sweep: a worktree whose work already reached the trunk is landed work wearing the same
+// clothes as live work, and the list stops being readable once a couple of them pile up. `ship`
+// retires the one it just landed; this is for the merge that happened somewhere else — a pull request
+// accepted in the forge, a merge by hand, a session that ended before ship. It only ever NAMES them:
+// at session start the user has asked for nothing, and acting on disk before they say a word is how a
+// safeguard earns itself an opt-out. Silent when there is nothing to say. Off with .rsc/.no-worktree-cleanup.
+if (has('.git')) {
+  try {
+    // No opt-out check here: `classifyWorktrees` returns nothing when the project turned the cleanup
+    // off, so a second check could never fail and would only look like protection (P2). Test 36 holds
+    // the behaviour end to end, through this hook.
+    const W = await import('./worktree-reaper.mjs');
+    {
+      const candidates = W.classifyWorktrees(root).filter((c) => c.verdict !== 'skip');
+      if (candidates.length) {
+        process.stdout.write(`
+===== rsc worktree cleanup =====
+${candidates.length} worktree(s) hold work that is already in the trunk:
+${candidates.map((c) => W.summarize(c, root)).join('\n')}
+ACTION: offer to retire them in ONE line and wait for a yes. On a yes run:
+  npx @ericrisco/rsc worktrees reap          (the ones marked safe)
+  npx @ericrisco/rsc worktrees reap <path>   (one the user confirmed by name)
+A yes in bulk covers only the safe ones; anything marked \`ask\` is confirmed on its own.
+A no holds for this session. Permanent off: .rsc/.no-worktree-cleanup
+================================
+`);
+      }
+    }
+  } catch { /* reaper missing or git unhappy → say nothing; this is never worth breaking startup for */ }
+}
+
 // Update check: compare the installed version (.rsc/.version, written at install)
 // against the latest published on npm, and nudge the agent to offer an update.
 // Fail-silent (offline / missing baseline / parse error → nothing). Disable with

package/targets/worktree-reaper.mjs

@@ -0,0 +1,458 @@
+#!/usr/bin/env node
+// rsc worktree reaper — the deterministic half of "the cleanup is the default".
+//
+// The catalog told agents, in prose, to remove a worktree once its work had landed. Prose is not an
+// executor: `ship` carried the procedure in a paragraph under "park/discard", the block that runs on
+// a direct merge never mentioned it, and nothing at all fired when the merge happened in the forge.
+// So worktrees accumulated, and a list where live work and landed work look identical is a list
+// nobody can act on — least of all the non-technical profile the harness claims to serve.
+//
+// This module owns the one judgement that must never be made by feel: *can this be removed without
+// asking?* Three questions decide it, and every one of them fails towards keeping the directory:
+//
+//   provenance  — did rsc create it? (derived from the content, never from a registry: P3)
+//   integration — does the branch still carry anything the trunk does not have?
+//   contents    — is there anything inside that was never in git and cannot be regenerated?
+//
+// Imported by `.rsc/session-start.mjs` (the sweep) and by `scripts/rsc.js` (`rsc worktrees`), so the
+// rule exists once and both entry points cannot drift apart. Same shape as `sello.mjs`.
+import { existsSync, realpathSync } from 'node:fs';
+import { join, resolve, dirname, basename, relative, sep } from 'node:path';
+import { spawnSync } from 'node:child_process';
+
+// git reports worktree paths with every symlink resolved; callers hand us whatever they were given.
+// On macOS that alone is enough to make every comparison here fail, because /tmp and /var are
+// symlinks — and a path comparison that silently never matches would turn this whole module into a
+// no-op that looks healthy. Compare real paths on both sides, always.
+function real(p) {
+  try { return realpathSync.native(resolve(p)); } catch { return resolve(p); }
+}
+
+export const OPT_OUT = '.no-worktree-cleanup';
+
+// Content that lives outside git and is nevertheless disposable, as a table the test reads rather
+// than conditionals it cannot see. Without this carve-out the default would never be automatic:
+// virtually every worktree has dependencies installed inside it, and asking every single time is how
+// a safeguard gets switched off (P7). The list ages — an ecosystem missing from it sends the
+// worktree down the confirmation path, which is noise, not loss.
+export const REGENERABLE = [
+  'node_modules', 'bower_components', 'jspm_packages', '.pnpm-store', '.yarn',
+  'venv', '.venv', 'env', '.tox', '__pycache__', '.pytest_cache', '.mypy_cache', '.ruff_cache',
+  'dist', 'build', 'out', 'target', 'bin', 'obj', '.next', '.nuxt', '.svelte-kit', '.astro',
+  '.turbo', '.parcel-cache', '.cache', '.gradle', '.dart_tool', 'Pods', 'vendor',
+  'coverage', '.nyc_output',
+];
+
+// Junk that is disposable wherever it appears, matched by filename. Kept SEPARATE from the table
+// above, and deliberately tiny, because the two cannot share a matching rule: the first entries are
+// directory names, and matching them against a *filename* is what made `config/env` — a dotenv file
+// full of live credentials — read as build output and get deleted with no confirmation at all. A
+// directory name means something only as a directory.
+export const REGENERABLE_FILES = ['.DS_Store', 'Thumbs.db', '.coverage'];
+
+// Trunk candidates, most authoritative first. The remote tip beats a local branch that may be stale.
+const TRUNKS = ['origin/main', 'main', 'origin/master', 'master'];
+
+// Branch shapes `worktrees` imposes on the isolation it creates.
+const RSC_BRANCH = /^(?:feat|feature)\//;
+
+function git(cwd, args) {
+  // 64 MiB, because node's 1 MiB default kills git mid-write on any worktree with a few thousand
+  // stray files and hands back a truncated-but-successful-looking result. Measured: in the 1.0-1.15 MB
+  // band the same unchanged worktree flipped between verdicts across runs.
+  const r = spawnSync('git', ['-C', cwd, ...args], { encoding: 'utf8', maxBuffer: 64 * 1024 * 1024 });
+  // `raw` matters for porcelain output: its leading space is a status code, not padding, and
+  // trimming it shifted every path by one character — so the message naming the file about to be
+  // lost named a file that does not exist. A refusal has to be true to be actionable (P6).
+  return { ok: r.status === 0, out: (r.stdout || '').trim(), raw: r.stdout || '', err: (r.stderr || '').trim() };
+}
+
+/**
+ * The MAIN working tree for wherever we are standing.
+ *
+ * You cannot remove the directory you are inside, and closing a branch from the worktree you built it
+ * in is the most common way this is reached — so without this the common case is exactly the one that
+ * never gets cleaned. `--show-toplevel` is the wrong question here: inside a linked worktree it
+ * answers with that worktree. The common git dir is the only thing that points home.
+ */
+export function resolveMainRoot(cwd = process.cwd()) {
+  const probe = git(cwd, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  if (probe.ok && probe.out) {
+    const home = real(dirname(probe.out));
+    // In the bare-repo layout (`proj/.bare` plus sibling worktrees) the parent of the common dir is
+    // not a repository at all, so every git question from there fails and the feature silently does
+    // nothing. That layout is one of the two mainstream worktree workflows; fall back to the git dir.
+    if (git(home, ['rev-parse', '--git-dir']).ok) return home;
+    return real(probe.out);
+  }
+  const legacy = git(cwd, ['rev-parse', '--git-common-dir']);
+  if (legacy.ok && legacy.out) return real(dirname(resolve(cwd, legacy.out)));
+  return real(cwd);
+}
+
+/** Is this ref one of the trunk names? Deleting one is never a side effect of a cleanup. */
+export function isTrunkName(branch) {
+  return TRUNKS.some((t) => t === branch || t.endsWith(`/${branch}`));
+}
+
+/** The cleanup is on unless this project turned it off. Same shape as the other guards' switches. */
+export function isCleanupEnabled(root) {
+  return !existsSync(join(root, '.rsc', OPT_OUT));
+}
+
+/** The first trunk ref that actually exists, or null when there is nothing to compare against. */
+export function resolveTrunk(root) {
+  return TRUNKS.find((ref) => git(root, ['rev-parse', '--verify', '--quiet', `${ref}^{commit}`]).ok) || null;
+}
+
+/** Every working tree git knows about. The first entry is always the main one. */
+export function listWorktrees(root) {
+  const { ok, out } = git(root, ['worktree', 'list', '--porcelain']);
+  if (!ok) return [];
+  const trees = [];
+  let cur = null;
+  for (const line of out.split('\n')) {
+    if (line.startsWith('worktree ')) {
+      cur = { path: real(line.slice('worktree '.length)), branch: null, head: null, locked: false, isMain: trees.length === 0 };
+      trees.push(cur);
+    } else if (!cur) continue;
+    else if (line.startsWith('HEAD ')) cur.head = line.slice('HEAD '.length);
+    else if (line.startsWith('branch ')) cur.branch = line.slice('branch '.length).replace(/^refs\/heads\//, '');
+    // A lock is the strongest "do not touch this" git lets a person express. Dropping the line meant
+    // the sweep announced locked worktrees as removable and only git's own refusal stopped it.
+    else if (line === 'locked' || line.startsWith('locked ')) cur.locked = true;
+  }
+  // `git worktree list --porcelain` does not quote paths and has no -z form, so a directory whose name
+  // contains a newline fabricates an extra entry that inherits the real one's HEAD and branch. It can
+  // never be deleted (git refuses a path that is not a working tree), but it would be displayed, and
+  // `status --ignored` would be run against whatever it points at. Ask git whether each parsed path
+  // really belongs to this repository; a forgery does not.
+  const home = git(root, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  if (!home.ok || !home.out) return trees;
+  return trees.filter((wt) => {
+    if (wt.isMain) return true;
+    const mine = git(wt.path, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+    if (!mine.ok || real(mine.out) !== real(home.out)) return false;
+    // Belonging to this repository is not enough: any directory *inside* the checkout answers the
+    // same. A genuine worktree is its own root, so git's toplevel from there is the path itself.
+    const top = git(wt.path, ['rev-parse', '--show-toplevel']);
+    return top.ok && real(top.out) === wt.path;
+  });
+}
+
+/**
+ * Whose worktree is this? Derived, because a list of "worktrees rsc created" is the parallel
+ * accounting P3 forbids — and a stale one would authorise deleting something it no longer describes.
+ *
+ * Two independent signals, and the conjunction is what counts as certainty. Deriving gets it wrong in
+ * both directions and only one of them is benign: ours, renamed by hand, is never cleaned (it
+ * accumulates, nothing is lost), while one the user made by hand that happens to match the
+ * convention would be indistinguishable from ours. So one signal alone is `ambiguous`, not `rsc`.
+ */
+export function provenanceOf(root, wt) {
+  const p = wt.path;
+  const home = real(root);
+  const inside = (dir) => p === dir || p.startsWith(dir + sep);
+  const location = inside(join(home, '.worktrees'))
+    || inside(join(home, 'worktrees'))
+    || (dirname(p) === dirname(home) && basename(p).startsWith(`${basename(home)}-`));
+  const branch = Boolean(wt.branch && RSC_BRANCH.test(wt.branch));
+  if (location && branch) return 'rsc';
+  if (location || branch) return 'ambiguous';
+  return 'foreign';
+}
+
+/**
+ * Does the branch still carry anything the trunk does not have?
+ *
+ * Reachability alone answers "no" for every pull request the forge squashed or rebased — the most
+ * common way work lands anywhere — because those rewrite the commit identities. So the question is
+ * asked about content, which is what the contract actually says: if merging this branch into the
+ * trunk would not change the trunk's tree, the branch adds nothing.
+ *
+ * Cheapest first, and anything that cannot be answered is answered as "still carries work".
+ */
+/**
+ * Did this branch ever carry a commit of its own?
+ *
+ * A branch cut ten seconds ago adds nothing the trunk does not have, so every content test calls it
+ * integrated — and "integrated" was being read as "landed", which turned a live workspace that had
+ * merely run an install into a directory to delete. Nothing landed from a branch that never committed.
+ *
+ * The reflog is git's own record of the ref moving; when it cannot answer, the answer is no, because
+ * accumulating a stale worktree costs a directory and the other mistake costs someone's afternoon.
+ */
+export function hasLandedWork(root, wt, trunk) {
+  const tip = git(root, ['rev-parse', `${trunk}^{commit}`]);
+  if (tip.ok && wt.head && tip.out === wt.head) return false;
+  if (!wt.branch) return false;
+  const log = git(root, ['reflog', 'show', '--format=%gs', wt.branch]);
+  if (!log.ok || !log.out) return false;
+  return log.out.split('\n').some((line) => line.startsWith('commit'));
+}
+
+export function integrationOf(root, wt, trunk) {
+  const head = wt.head || (wt.branch ? git(root, ['rev-parse', wt.branch]).out : null);
+  if (!head) return 'unknown';
+  if (git(root, ['merge-base', '--is-ancestor', head, trunk]).ok) return 'integrated';
+
+  const merged = git(root, ['merge-tree', '--write-tree', trunk, head]);
+  // A conflict exits non-zero with a tree on stdout; an unsupported flag (git < 2.38) exits non-zero
+  // with usage on stderr and nothing usable. Neither is integration, but only the second is ignorance.
+  if (!merged.ok && !merged.out) return 'unknown';
+  const trunkTree = git(root, ['rev-parse', `${trunk}^{tree}`]);
+  if (!merged.ok || !trunkTree.ok) return 'not-integrated';
+  return merged.out.split('\n')[0].trim() === trunkTree.out ? 'integrated' : 'not-integrated';
+}
+
+/**
+ * What is inside that git would not miss? Split into what git calls dirty (tracked changes) and what
+ * git cannot see at all — untracked and *ignored* files.
+ *
+ * The second half is the one that matters and the one every "is it clean?" check forgets: a worktree
+ * with nothing pending can still hold the only copy of an .env, a local database or a page of notes,
+ * and removing the directory takes them with it. `--ignored` is the only way to be told they exist.
+ */
+export function contentOutsideHistory(wtPath) {
+  const { ok, raw } = git(wtPath, ['status', '--porcelain', '-z', '-uall', '--ignored=matching']);
+  const dirty = [];
+  const outside = [];
+  if (!ok) return { dirty, outside, readable: false };
+  const fields = raw.split('\0');
+  for (let i = 0; i < fields.length; i++) {
+    const entry = fields[i];
+    if (entry.length < 4) continue;
+    const code = entry.slice(0, 2);
+    const path = entry.slice(3);
+    // A rename emits TWO fields: the target, then the bare origin path with no status code. Treating
+    // that origin as another entry sliced three characters off it, so the refusal named a file that
+    // does not exist — the exact failure the `raw` comment above exists to prevent (P6).
+    if (code[0] === 'R' || code[0] === 'C') { i++; dirty.push(path); continue; }
+    if (code === '??' || code === '!!') {
+      if (!isRegenerable(path)) outside.push(path);
+    } else dirty.push(path);
+  }
+  return { dirty, outside, readable: true };
+}
+
+// A directory name counts anywhere it is used as a DIRECTORY; a filename counts only as a filename.
+// Matching the table against the last segment made `config/env` — a dotenv full of live credentials —
+// read as a virtualenv and get deleted. Matching it only at position 0 fixed that and broke every
+// monorepo, where the disposable directory is `packages/app/node_modules`. Position is the whole rule.
+function isRegenerable(path) {
+  const parts = path.split('/').filter(Boolean);
+  // git reports a wholly-ignored directory with a trailing slash and does not expand it, so there the
+  // last segment is a directory too. Getting this wrong is what made `node_modules/` itself — the most
+  // common entry there is — fail the very carve-out written for it.
+  const isDir = path.endsWith('/');
+  const dirs = isDir ? parts : parts.slice(0, -1);
+  return dirs.some((d) => REGENERABLE.includes(d))
+    || (!isDir && REGENERABLE_FILES.includes(parts[parts.length - 1]));
+}
+
+/**
+ * Every worktree with a verdict: `safe` (remove without asking), `ask` (confirm first, and the
+ * reasons say why), `skip` (not ours, or still carrying work — never offered).
+ *
+ * Returns nothing at all when the cleanup is off or the trunk cannot be resolved: with no trunk there
+ * is no way to tell landed work from live work, and guessing is the one thing this must not do.
+ */
+// No submodule guard here, deliberately. It was written because a submodule *looks* like a worktree,
+// and a planted mutant proved it could never fire: `git worktree list` does not report submodules, so
+// nothing this iterates can ever be one. A guard that cannot fail is the decorative gate P2 exists to
+// forbid — the invariant is structural, and test 32 is what holds it.
+export function classifyWorktrees(root) {
+  if (!isCleanupEnabled(root)) return [];
+  const trunk = resolveTrunk(root);
+  if (!trunk) return [];
+
+  return listWorktrees(root)
+    .filter((wt) => !wt.isMain && wt.path !== real(root))
+    .map((wt) => {
+      const base = { path: wt.path, branch: wt.branch, verdict: 'skip', reasons: [], details: {} };
+
+      // A detached worktree has no branch, so half the provenance signal cannot even be asked for and
+      // every message about it interpolates `null`. Nothing to reason about; leave it alone.
+      if (!wt.branch) return { ...base, reasons: ['detached'] };
+
+      const provenance = provenanceOf(root, wt);
+      if (provenance === 'foreign') return { ...base, reasons: ['foreign'] };
+
+      if (wt.locked) return { ...base, reasons: ['locked'] };
+
+      const integration = integrationOf(root, wt, trunk);
+      if (integration !== 'integrated') return { ...base, reasons: [integration] };
+      if (!hasLandedWork(root, wt, trunk)) return { ...base, reasons: ['nothing-landed'] };
+
+      const { dirty, outside, readable } = contentOutsideHistory(wt.path);
+      if (!readable) return { ...base, reasons: ['unreadable'] };
+
+      const reasons = [];
+      if (dirty.length) reasons.push('dirty');
+      if (outside.length) reasons.push('content-outside-history');
+      if (provenance === 'ambiguous') reasons.push('provenance-ambiguous');
+
+      return {
+        ...base,
+        verdict: reasons.length ? 'ask' : 'safe',
+        reasons,
+        details: { dirty, outside },
+      };
+    });
+}
+
+/**
+ * Remove one worktree, and its branch only when git will do it the safe way.
+ *
+ * The branch rule is the recovery net for the one judgement here that is inferred rather than proven:
+ * a squash-merged branch is equivalent by content and not by identity, so `branch -d` refuses it. We
+ * do not override that refusal. The directory goes, the branch stays, and while the branch exists the
+ * commits are recoverable even if the equivalence was judged wrong. Never `-D`.
+ *
+ * `--force` on the worktree removal is not a relaxation: our own gate above is strictly stronger than
+ * git's, because git's refusal ignores ignored files and ours does not. By this point the contents
+ * have already been classified as either nothing, or regenerable, or explicitly confirmed.
+ */
+export function reapWorktree(root, targetPath, { confirmed = false } = {}) {
+  const target = real(targetPath);
+  if (!isCleanupEnabled(root)) {
+    return { removed: false, reason: `cleanup is off for this project (.rsc/${OPT_OUT}); remove it by hand with \`git worktree remove\`` };
+  }
+  if (target === real(root)) {
+    return { removed: false, reason: 'that is the main working tree, not a worktree to remove' };
+  }
+
+  const candidate = classifyWorktrees(root).find((c) => c.path === target);
+  if (!candidate) {
+    return { removed: false, reason: `${target} is not a worktree of this repository, or the trunk could not be resolved` };
+  }
+  if (candidate.verdict === 'skip') {
+    return { removed: false, reason: refusal(candidate) };
+  }
+  if (candidate.verdict === 'ask' && !confirmed) {
+    return { removed: false, reason: refusal(candidate) };
+  }
+
+  const removal = git(root, ['worktree', 'remove', '--force', target]);
+  if (!removal.ok) {
+    return { removed: false, reason: `git refused to remove it: ${removal.err || removal.out}` };
+  }
+
+  // `-d` refuses an unmerged branch, which is the recovery net — but it happily deletes the TRUNK,
+  // which is an ancestor of everything. A sibling checkout of `main` classified as ambiguous, the user
+  // confirmed removing a stray directory, and the trunk ref went with it.
+  const branchDeleted = candidate.branch && !isTrunkName(candidate.branch)
+    ? git(root, ['branch', '-d', candidate.branch]).ok
+    : false;
+  // No `git worktree prune` here. It has no expiry of its own, so running it while another worktree's
+  // volume happens to be unmounted de-registers that worktree immediately — and this project lives on
+  // an external drive. `git worktree remove` already clears the entry it owns.
+
+  return {
+    removed: true,
+    path: target,
+    branch: candidate.branch,
+    branchDeleted,
+    branchKept: Boolean(candidate.branch) && !branchDeleted,
+  };
+}
+
+/**
+ * Every refusal carries the way out, because the person receiving it may not be able to deduce one (P6).
+ *
+ * EVERY reason, not the first one recorded. A worktree that is both dirty and holding an untracked
+ * file used to be described by the dirty half alone — so the user read "uncommitted changes in
+ * README.md", judged that a nuisance, confirmed, and the confirmation landed on a `production.env`
+ * the message never mentioned. The module knew. It just did not say.
+ */
+export function refusal(candidate) {
+  const d = candidate.details || {};
+  const parts = (candidate.reasons || []).map((reason) => {
+    switch (reason) {
+      case 'foreign':
+        return 'it was not created by rsc, so it is not ours to delete. Remove it yourself with `git worktree remove` if you want it gone.';
+      case 'not-integrated':
+        return `\`${candidate.branch}\` still carries work that is not in the trunk. Land it (\`ship\`) or discard it deliberately first.`;
+      case 'unknown':
+        return `whether \`${candidate.branch}\` is integrated could not be determined (old git, or no comparable trunk). Check with \`git log --oneline <trunk>..${candidate.branch}\` and remove it by hand if you are satisfied.`;
+      case 'detached':
+        return 'it has no branch checked out (detached HEAD), so there is nothing to judge as landed. Left alone.';
+      case 'locked':
+        return 'it is locked. Unlock it deliberately (`git worktree unlock`) if you really want it gone.';
+      case 'nothing-landed':
+        return `\`${candidate.branch}\` has never carried a commit, so nothing landed from it — this is a live workspace, not leftovers.`;
+      case 'unreadable':
+        return 'git could not report the state of that directory; nothing was touched.';
+      case 'dirty':
+        return `it has uncommitted changes: ${list(d.dirty)}. Commit, stash or discard them first.`;
+      case 'content-outside-history':
+        return `it holds files that are in no commit and would be lost: ${list(d.outside)}. Move or copy them out first.`;
+      case 'provenance-ambiguous':
+        return `only half of the rsc convention matches (\`${candidate.branch}\`), so it may be yours rather than ours. Confirm before it is removed.`;
+      default:
+        return null;
+    }
+  }).filter(Boolean);
+  return parts.length ? parts.join(' Also: ') : 'nothing was removed.';
+}
+
+// Naming what is at risk is the point; naming ten thousand of them is a denial of service against the
+// reader and against the context window. Show enough to recognise, then say how many are left.
+const SHOWN = 5;
+function list(items = []) {
+  if (!items.length) return 'none';
+  const head = items.slice(0, SHOWN).join(', ');
+  return items.length > SHOWN ? `${head} and ${items.length - SHOWN} more` : head;
+}
+
+/** One line per candidate, for someone who asked — the CLI names what is at risk. */
+export function describe(candidate) {
+  const who = `${candidate.path}${candidate.branch ? ` (${candidate.branch})` : ''}`;
+  if (candidate.verdict === 'safe') return `  safe  ${who} — landed and empty of anything unsaved`;
+  return `  ${candidate.verdict === 'skip' ? 'keep' : 'ask '}  ${who} — ${refusal(candidate)}`;
+}
+
+/**
+ * One line per candidate for the session-start sweep, which nobody asked for.
+ *
+ * That block is injected into the model's context on every startup, so it is held to a stricter rule
+ * than the CLI: paths relative to the repository (P9 — nothing distributed carries machine paths) and
+ * **counts instead of filenames**. The files this would otherwise enumerate are, by construction, the
+ * ones outside git: the .env, the private key, the client folder — exactly what the user marked as
+ * not-for-sharing. Enough to decide whether to look; nothing that leaks by being read.
+ */
+export function summarize(candidate, root) {
+  const where = relative(real(root), candidate.path) || candidate.path;
+  const who = `${where}${candidate.branch ? ` (${candidate.branch})` : ''}`;
+  if (candidate.verdict === 'safe') return `  safe  ${who} — landed, nothing unsaved inside`;
+  if (candidate.verdict === 'skip') return `  keep  ${who} — ${candidate.reasons.join(', ')}`;
+  const d = candidate.details || {};
+  const why = candidate.reasons.map((r) => {
+    if (r === 'dirty') return `${d.dirty.length} uncommitted change(s)`;
+    if (r === 'content-outside-history') return `${d.outside.length} file(s) in no commit`;
+    if (r === 'provenance-ambiguous') return 'provenance unclear';
+    return r;
+  }).join(', ');
+  return `  ask   ${who} — ${why}; ask before removing`;
+}
+
+// CLI: `node worktree-reaper.mjs <root> [reap [path]]`. `scripts/rsc.js` is the public entry point;
+// this exists so the materialized copy in .rsc/ is runnable on its own.
+if (process.argv[1] && resolve(process.argv[1]) === resolve(new URL(import.meta.url).pathname)) {
+  const root = resolve(process.argv[2] || process.cwd());
+  const candidates = classifyWorktrees(root).filter((c) => c.verdict !== 'skip');
+  if (process.argv[3] === 'reap') {
+    const one = process.argv[4];
+    const targets = one ? [resolve(one)] : candidates.filter((c) => c.verdict === 'safe').map((c) => c.path);
+    for (const t of targets) {
+      const out = reapWorktree(root, t, { confirmed: Boolean(one) });
+      process.stdout.write(out.removed
+        ? `removed ${t}${out.branchKept ? ` (branch ${out.branch} kept — git will not delete it safely)` : ''}\n`
+        : `kept ${t} — ${out.reason}\n`);
+    }
+  } else if (!candidates.length) {
+    process.stdout.write('no worktrees to clean up.\n');
+  } else {
+    process.stdout.write(candidates.map(describe).join('\n') + '\n');
+  }
+}