@damiangilgonzalez/harness 1.3.12 → 1.3.13

package/targets/session-memory-adapter.mjs

@@ -1,6 +1,6 @@
 #!/usr/bin/env node
-import { pathToFileURL } from 'node:url';
-import { existsSync, readFileSync } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { existsSync, readFileSync, realpathSync } from 'node:fs';
 import { resolve, join, dirname } from 'node:path';
 import { capture, resume } from './session-memory-core.mjs';
 
@@ -56,15 +56,35 @@ function hookEventName(target, event, native) {
   return names[event] || event;
 }
 
+const COMPACTION_HINT = 'rsc memory: consider compacting at the next phase boundary; nothing was compacted automatically.';
+
+/**
+ * Two different things used to share one channel, and that is the whole bug.
+ *
+ * The resume CONTEXT is information for the model, and it is only ever produced on `start` —
+ * `SessionStart`, one of the few events whose output may carry `hookSpecificOutput.additionalContext`.
+ * The compaction HINT is a message for the PERSON, and it was going out through the same field on
+ * whatever event happened to be running. On `Stop`, `PreCompact` and `SessionEnd` the client rejects
+ * that outright ("Hook JSON output validation failed — hookSpecificOutput.hookEventName: expected one
+ * of …"), so the hook meant to help ended up printing an error after every turn, and after
+ * `/compact` in particular — which is exactly what the hint had just told the person to run.
+ *
+ * So the hint moves to `systemMessage`, which every event accepts. This needs no table of which
+ * event carries what, and it cannot rot when the client adds an event: anything addressed to the
+ * person travels by the universal channel, and only genuine model context uses the narrow one.
+ */
 function nativeOutput(target, eventName, context = '', notice = null, compactionHint = false) {
-  const hint = compactionHint ? 'rsc memory: consider compacting at the next phase boundary; nothing was compacted automatically.' : '';
-  const extra = [context, hint].filter(Boolean).join('\n');
-  if (!extra && !notice) return {};
-  if (target === 'cursor') return { ...(extra ? { additional_context: extra } : {}), ...(notice ? { user_message: notice } : {}) };
-  if (target === 'opencode') return { context: extra, notice };
+  const hint = compactionHint ? COMPACTION_HINT : '';
+  if (!context && !hint && !notice) return {};
+  if (target === 'cursor') {
+    const message = [notice, hint].filter(Boolean).join('\n');
+    return { ...(context ? { additional_context: context } : {}), ...(message ? { user_message: message } : {}) };
+  }
+  if (target === 'opencode') return { context, notice: [notice, hint].filter(Boolean).join('\n') || null };
+  const message = [notice, hint].filter(Boolean).join('\n');
   return {
-    ...(notice ? { systemMessage: notice } : {}),
-    ...(extra ? { hookSpecificOutput: { hookEventName: eventName, additionalContext: extra } } : {}),
+    ...(message ? { systemMessage: message } : {}),
+    ...(context ? { hookSpecificOutput: { hookEventName: eventName, additionalContext: context } } : {}),
   };
 }
 
@@ -78,15 +98,18 @@ export function handleLifecycle({ target, event, native = {}, cwd, settings } =
   try {
     if (!LOCAL_TARGETS.has(target)) throw new Error(`unsupported memory target: ${target}`);
     if (isRemote(target, native)) return { output: {}, capture: null, remote: true, degraded: false };
-    const project = nearestHarness(resolve(cwd || native.cwd || process.env.RSC_PROJECT_CWD || process.cwd()));
+    // Two answers from one path, kept apart on purpose: `project` is where the journal is KEPT (the
+    // nearest harness), `here` is where the agent WORKS and therefore who the session is.
+    const here = resolve(cwd || native.cwd || process.env.RSC_PROJECT_CWD || process.cwd());
+    const project = nearestHarness(here);
     if (!existsSync(project)) throw new Error('project directory unavailable');
     const config = settings || projectSettings(project);
     if (config.enabled === false) return { output: {}, capture: null, remote: false, degraded: false };
     const id = sessionId(native, target);
     const eventName = hookEventName(target, event, native);
     if (event === 'start') {
-      const started = capture({ cwd: project, sessionId: id, target, event: 'start', settings: config });
-      const resumed = resume({ cwd: project, target, settings: config });
+      const started = capture({ cwd: project, worktreeCwd: here, sessionId: id, target, event: 'start', settings: config });
+      const resumed = resume({ cwd: project, worktreeCwd: here, target, settings: config });
       return {
         output: nativeOutput(target, eventName, resumed.context),
         capture: started,
@@ -97,6 +120,7 @@ export function handleLifecycle({ target, event, native = {}, cwd, settings } =
     }
     const captureInput = {
       cwd: project,
+      worktreeCwd: here,
       sessionId: id,
       target,
       event: event === 'end' ? 'sessionEnd' : event,
@@ -106,8 +130,13 @@ export function handleLifecycle({ target, event, native = {}, cwd, settings } =
     if (typeof native.cost === 'number') captureInput.cost = native.cost;
     if (Number.isInteger(native.tool_calls)) captureInput.toolCalls = native.tool_calls;
     const captured = capture(captureInput);
+    // `stop_hook_active` is the client saying "this turn is already running BECAUSE a stop hook
+    // asked for it". Speaking again here is how a Stop hook wakes itself: the student's session did
+    // nine rounds of hook → "—" → hook before the client broke the loop. Record the turn, say
+    // nothing.
+    const silenced = event === 'turn' && Boolean(native?.stop_hook_active);
     return {
-      output: nativeOutput(target, eventName, '', captured.notice, captured.compactionHint),
+      output: silenced ? {} : nativeOutput(target, eventName, '', captured.notice, captured.compactionHint),
       capture: captured,
       remote: false,
       degraded: false,
@@ -126,7 +155,34 @@ function stdinJson() {
   }
 }
 
-if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
+/**
+ * "Was this file run directly?" — the same question `clone-bootstrap.mjs` answers, and the same two
+ * traps, so the same answer. Written out here rather than imported because hooks are materialized
+ * file by file under `.rsc/`: an import would be a second file to copy for six lines.
+ *
+ *   `process.argv[1]` MAY NOT EXIST. Under `node -e`, `--input-type=module` or the REPL there is no
+ *   script path, and `pathToFileURL(undefined)` throws — at module load, so merely IMPORTING this
+ *   file takes the importer down with it. A module that cannot be imported is a module nobody can
+ *   build a tool on top of, and people do exactly that with this package.
+ *
+ *   SYMLINKS MAKE THE TWO SIDES DISAGREE. `import.meta.url` is what the loader resolved (symlinks
+ *   RESOLVED); `process.argv[1]` is the raw string the client passed (symlinks INTACT). One
+ *   symlinked component — `/tmp` and `/var` on macOS, or an ordinary `~/code -> /Volumes/…` — and a
+ *   string compare says "no", the main block never runs, node exits 0 having printed nothing, and
+ *   the hook becomes a silent no-op that `doctor` still reports as wired.
+ */
+function isMainModule(metaUrl) {
+  const invoked = process.argv[1];
+  if (!invoked) return false;
+  const self = fileURLToPath(metaUrl);
+  try {
+    return realpathSync(self) === realpathSync(invoked);
+  } catch {
+    return self === invoked;
+  }
+}
+
+if (isMainModule(import.meta.url)) {
   const result = handleLifecycle({ target: process.argv[2], event: process.argv[3], native: stdinJson() });
   process.stdout.write(`${JSON.stringify(result.output)}\n`);
 }

package/targets/session-memory-core.mjs

@@ -284,6 +284,12 @@ function readRecords(root) {
 
 export function capture(input = {}) {
   const cwd = resolve(input.cwd || process.cwd());
+  // WHERE the journal lives and WHO the session is are two different questions. `cwd` answers the
+  // first — the nearest harness, so a child with no manifest of its own does not scatter journals.
+  // The second has to be asked of git from where the agent actually works: asked from the harness,
+  // every worktree nested under it came back as the harness itself, and a sibling's record then
+  // "matched exactly". See GHSA-8gjp-3r7c-33f4.
+  const here = resolve(input.worktreeCwd || cwd);
   const config = settings(input.settings);
   if (!config.enabled) return { record: null, path: null, notice: null, compactionHint: false };
   const store = chooseMemoryRoot(cwd);
@@ -299,7 +305,7 @@ export function capture(input = {}) {
   const recordPath = join(store.root, 'sessions', `${storageId}.json`);
   let anchor = readJson(anchorPath);
   let existing = readJson(recordPath);
-  const firstSnapshot = snapshot(cwd, null);
+  const firstSnapshot = snapshot(here, null);
   if (!anchor) {
     anchor = {
       sessionId,
@@ -312,10 +318,23 @@ export function capture(input = {}) {
   }
   if (input.event === 'start' && !existing) return { record: null, path: null, notice: null, compactionHint: false };
 
-  const repo = snapshot(cwd, anchor.baselineHead);
+  const repo = snapshot(here, anchor.baselineHead);
+  // Count what CHANGED, not which tool changed it. `editDelta` is +1 per Edit/Write tool event, and
+  // on its own it was blind to everything done through the shell — a heredoc, `sed -i`, a script, a
+  // formatter — which is how automated sessions work. The session that found this had touched dozens
+  // of files and its record said editCount=1, so the compaction hint never reached the long sessions
+  // it exists for.
+  //
+  // `snapshot` already fingerprints every modified file on every event. Comparing those fingerprints
+  // with the previous event's counts a change from any source. `max`, not `+`: an Edit that changed a
+  // file shows up in BOTH signals, and must count once.
+  const previousFingerprints = anchor.lastFingerprints || anchor.baselineFingerprints || {};
+  const observed = Object.entries(repo.fingerprints || {})
+    .filter(([path, fingerprint]) => fingerprint && previousFingerprints[path] !== fingerprint).length;
+  const editDelta = Math.max(finiteOrNull(input.editDelta, true) || 0, observed);
   // Compaction closes a context window, so the edit budget starts again from zero.
   const previousEdits = input.event === 'compact' ? 0 : (existing?.editCount || 0);
-  const editCount = Math.max(0, previousEdits + (finiteOrNull(input.editDelta, true) || 0));
+  const editCount = Math.max(0, previousEdits + editDelta);
   // Hint once per threshold crossed, and only on the edit that crosses it: re-emitting on
   // every later event (Stop in particular) wakes the model again and loops.
   const crossedThreshold = editCount > previousEdits
@@ -358,11 +377,18 @@ export function capture(input = {}) {
   if (errors.length) return { record: null, path: null, notice: null, compactionHint: false, errors };
   atomicJson(recordPath, record);
   existing = record;
+  const compactionHint = Boolean(config.compactionHint && crossedThreshold);
+  // The fingerprints the next event compares against live on the ANCHOR, not on the record: the
+  // record's schema is closed and every field of it is required, so a new field there would fail
+  // validation on every record already written. Written only when they moved, so a read-only shell
+  // command costs no extra disk.
+  const fingerprintsMoved = observed > 0 || !anchor.lastFingerprints;
+  if (fingerprintsMoved) atomicJson(anchorPath, { ...anchor, lastFingerprints: repo.fingerprints || {} });
   return {
     record,
     path: recordPath,
     notice: consumeNotice(store),
-    compactionHint: Boolean(config.compactionHint && crossedThreshold),
+    compactionHint,
   };
 }
 
@@ -414,13 +440,19 @@ export function resume(input = {}) {
   ensureStore(store.root);
   const now = iso(input.now);
   prune(store.root, now, config);
-  const current = snapshot(cwd, null);
-  const records = readRecords(store.root).filter((record) => validAnchor(cwd, record))
+  const here = resolve(input.worktreeCwd || cwd);
+  const current = snapshot(here, null);
+  const records = readRecords(store.root).filter((record) => validAnchor(here, record))
     .sort((a, b) => b.timestamps.updatedAt.localeCompare(a.timestamps.updatedAt));
   let record = records.find((candidate) => candidate.branch === current.branch && candidate.worktree === current.worktree) || null;
   let match = record ? 'exact' : 'none';
+  // Only ever this worktree's own records. The chain used to end in `|| records[0]` — the newest
+  // record in the store, whoever wrote it — which a moved or renamed checkout reached every time,
+  // because its stale records match nothing. A shared store is a place to KEEP several worktrees'
+  // journals, never a reason to hand one of them to another. No continuation is the honest answer
+  // when there is nothing of yours to continue.
   if (!record) {
-    record = records.find((candidate) => candidate.worktree === current.worktree) || records[0] || null;
+    record = records.find((candidate) => candidate.worktree === current.worktree) || null;
     if (record) match = 'nearby';
   }
   const lessons = selectedLessons(store.root, config);

package/targets/session-start.mjs

@@ -30,14 +30,17 @@ const has = (...p) => existsSync(join(root, ...p));
 
 // The npm lookup (up to 1.5 s) starts now and runs while the local checks below do their work;
 // the update block at the end only awaits it.
-const latestVersion = process.env.RSC_NO_UPDATE_CHECK ? Promise.resolve(null)
-  : process.env.RSC_LATEST ? Promise.resolve(process.env.RSC_LATEST)
+// The registry returns the whole package.json on `/latest`, so `rscFixes` arrives in the same
+// response as the version. RSC_LATEST_JSON / RSC_LATEST override the lookup (tests / mirrors).
+const latestDoc = process.env.RSC_NO_UPDATE_CHECK ? Promise.resolve(null)
+  : process.env.RSC_LATEST_JSON ? Promise.resolve().then(() => JSON.parse(process.env.RSC_LATEST_JSON)).catch(() => null)
+  : process.env.RSC_LATEST ? Promise.resolve({ version: process.env.RSC_LATEST })
   : (async () => {
     const ctrl = new AbortController();
     const timer = setTimeout(() => ctrl.abort(), 1500);
     try {
       const res = await fetch('https://registry.npmjs.org/@damiangilgonzalez%2fharness/latest', { signal: ctrl.signal });
-      return (await res.json()).version;
+      return await res.json();
     } catch { return null; } finally { clearTimeout(timer); }
   })();
 
@@ -208,19 +211,31 @@ ACTION: run \`npx @damiangilgonzalez/harness audit\`. Opt out with .rsc/.no-audi
 // it's a relocation, not a delete). Opt out with .rsc/.no-claudemd-check.
 const CLAUDEMD_MAX_LINES = 200;
 if (!has('.rsc', '.no-claudemd-check')) {
+  // WHICH file is the project's instructions is no longer a constant. From Claude Code 2.1.277, a
+  // project with no CLAUDE.md is read through its root AGENTS.md instead — same per-turn cost, same
+  // adherence rot when it grows, and until now nothing measured it. Measure the file that is
+  // actually being loaded: CLAUDE.md when there is one, otherwise AGENTS.md.
+  const name = has('CLAUDE.md') ? 'CLAUDE.md' : (has('AGENTS.md') ? 'AGENTS.md' : null);
   try {
-    const lines = readFileSync(join(root, 'CLAUDE.md'), 'utf8').split('\n').length;
+    const lines = readFileSync(join(root, name), 'utf8').split('\n').length;
     if (lines > CLAUDEMD_MAX_LINES) {
+      // Only the CLAUDE.md claim is unconditional. A client older than 2.1.277 does not read
+      // AGENTS.md at all, and this hook cannot tell which it is talking to (the SessionStart
+      // payload carries no version), so the AGENTS.md line says when the cost applies instead of
+      // asserting it — a notice that overstates its case is the kind that gets opted out of.
+      const why = name === 'CLAUDE.md'
+        ? "it's read every turn, so each line costs context"
+        : "Claude Code 2.1.277+ loads it every turn when there is no CLAUDE.md, so each line costs context";
       process.stdout.write(`
-===== rsc CLAUDE.md hygiene =====
-CLAUDE.md is ${lines} lines — over the ~${CLAUDEMD_MAX_LINES}-line budget (it's read every turn, so each line costs context).
+===== rsc ${name} hygiene =====
+${name} is ${lines} lines — over the ~${CLAUDEMD_MAX_LINES}-line budget (${why}).
 ACTION: offload the Knowledge map / overgrown sections into docs/wiki/index.md and leave a short
-pointer in CLAUDE.md (no info lost — it's a move). The \`harness\` skill owns the procedure.
+pointer in ${name} (no info lost — it's a move). The \`harness\` skill owns the procedure.
 Opt out with .rsc/.no-claudemd-check.
 =================================
 `);
     }
-  } catch { /* no CLAUDE.md → nothing to check */ }
+  } catch { /* no instructions file (name === null) → nothing to check */ }
 }
 
 // Worktree sweep: a worktree whose work already reached the trunk is landed work wearing the same
@@ -287,12 +302,49 @@ function isNewer(a, b) {
   return false;
 }
 
+// "rsc X is out" was being ignored — the maintainer's own workspace sat on 2.0.4 for days with this
+// notice on every session, and two people in two days reported bugs that were already fixed. A
+// version number names nothing anyone recognises. A symptom does: someone who sees a red error after
+// every turn updates the moment they are told that is what the update fixes (`suggest` §3: say what
+// is wrong as a symptom, not as a cause).
+//
+// The symptoms travel for free: the registry's `/latest` document is the published package.json, so
+// its `rscFixes` field — `{ fixedIn, symptom }` — arrives in the response this check already makes.
+// It is text a model will read, so every entry is reduced to one short plain line or dropped.
+const SEMVER_ONLY = /^\d+\.\d+\.\d+$/;
+function fixesSince(list, installed, latest) {
+  if (!Array.isArray(list)) return [];
+  const out = [];
+  for (const item of list) {
+    if (!item || typeof item !== 'object' || typeof item.symptom !== 'string') continue;
+    if (!SEMVER_ONLY.test(String(item.fixedIn))) continue;
+    if (!isNewer(item.fixedIn, installed) || isNewer(item.fixedIn, latest)) continue;
+    const symptom = item.symptom.replace(/[\u0000-\u001f\u007f]+/g, ' ').replace(/\s+/g, ' ').trim().slice(0, 200);
+    if (symptom) out.push({ fixedIn: item.fixedIn, symptom });
+  }
+  return out.slice(0, 8);
+}
+
 if (!process.env.RSC_NO_UPDATE_CHECK) {
   try {
     const installed = readFileSync(join(root, '.rsc', '.version'), 'utf8').trim();
-    const latest = await latestVersion;
+    const doc = await latestDoc;
+    const latest = doc?.version;
     if (installed && latest && isNewer(latest, installed)) {
-      process.stdout.write(`
+      let fixes = [];
+      try { fixes = fixesSince(doc.rscFixes, installed, latest); } catch { fixes = []; }
+      if (fixes.length) {
+        process.stdout.write(`
+===== rsc update available =====
+rsc ${latest} is out — you have ${installed}. It fixes problems this install still has:
+${fixes.map((f) => `  - ${f.symptom} (fixed in ${f.fixedIn})`).join('\n')}
+ACTION: before starting the task, tell the user in one line that the update fixes what they
+may be seeing, and if they say yes, run it in this project:
+  npx @damiangilgonzalez/harness@latest
+================================
+`);
+      } else {
+        process.stdout.write(`
 ===== rsc update available =====
 rsc ${latest} is out — you have ${installed}.
 ACTION: tell the user a new version is available and, if they say yes, run:
@@ -300,6 +352,7 @@ ACTION: tell the user a new version is available and, if they say yes, run:
 (That reinstalls and refreshes the skill content to the latest.)
 ================================
 `);
+      }
     }
   } catch { /* offline / no baseline / parse error → stay silent */ }
 }

package/targets/worktree-reaper.mjs

@@ -16,7 +16,7 @@
 //
 // 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 { existsSync, realpathSync, mkdirSync, readFileSync, writeFileSync, renameSync, chmodSync } from 'node:fs';
 import { join, resolve, dirname, basename, relative, sep } from 'node:path';
 import { spawnSync } from 'node:child_process';
 import { pathToFileURL } from 'node:url';
@@ -54,8 +54,20 @@ 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)\//;
+// Branch shapes the catalog's isolation produces.
+//
+// `worktrees` documents `feat/<slug>`, and while SDD was the only lane that was the whole set:
+// every isolated branch was a feature. 2.0.0 made FTD the default and FTD names a branch for what
+// it is — a fix is not a feature — so `fix/`, `docs/` and `chore/` fell outside, scored as half a
+// signal, and were never swept, while `ftd` promises in writing that the cleanup is automatic once
+// the branch lands. Found by using it: the two fixes released on 2026-09-18 both had to be removed
+// by hand. These are the Conventional Commits types, which is what the commit guard already
+// enforces on every commit in a project rsc governs — so the branch shape and the commit shape now
+// come from the same vocabulary instead of two that drifted apart.
+//
+// Widening one signal, never the conjunction: a branch outside this vocabulary is still `ambiguous`
+// wherever it sits, and one of these in a directory rsc does not own is still `ambiguous` too.
+const RSC_BRANCH = /^(?:feat|feature|fix|docs|chore|refactor|test|perf|ci|build|style)\//;
 
 function git(cwd, args) {
   // 64 MiB, because node's 1 MiB default kills git mid-write on any worktree with a few thousand
@@ -183,13 +195,23 @@ export function provenanceOf(root, wt) {
  * 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;
+export function hasLandedWork(root, wt) {
   if (!wt.branch) return false;
+  // Ask the reflog FIRST. It is the only record that distinguishes the two states that look
+  // identical from the outside: a worktree sitting at the trunk because it was just created there,
+  // and one sitting at the trunk because its work landed by fast-forward and took the trunk with
+  // it. Until 2.0.3 the tip comparison below ran first and answered "nothing landed" for both, so
+  // every branch landed the ordinary FTD way — commit, push, fast-forward — was kept for ever.
+  // Found on 2026-09-18 watching this repo refuse to sweep its own branch for the wrong reason.
   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'));
+  if (log.ok && log.out) return log.out.split('\n').some((line) => line.startsWith('commit'));
+  // No reflog to ask — a fresh clone, or a branch whose reflog has expired. There is then no
+  // evidence this branch ever carried anything, and this whole module fails towards keeping the
+  // directory: unproven is not proven. (The tip comparison that used to sit here is deliberately
+  // gone rather than kept as a fallback: both of its outcomes are this same answer, and a line
+  // that cannot change the result while reading like a guard is the kind of decoration that made
+  // the bug above hard to see.)
+  return false;
 }
 
 export function integrationOf(root, wt, trunk) {
@@ -283,7 +305,7 @@ export function classifyWorktrees(root) {
 
       const integration = integrationOf(root, wt, trunk);
       if (integration !== 'integrated') return { ...base, reasons: [integration] };
-      if (!hasLandedWork(root, wt, trunk)) return { ...base, reasons: ['nothing-landed'] };
+      if (!hasLandedWork(root, wt)) return { ...base, reasons: ['nothing-landed'] };
 
       const { dirty, outside, readable } = contentOutsideHistory(wt.path);
       if (!readable) return { ...base, reasons: ['unreadable'] };
@@ -373,6 +395,144 @@ export function reapWorktree(root, targetPath, { confirmed = false } = {}) {
  * 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.
  */
+/**
+ * The unattended half: remove what classification already called `safe`, and nothing else.
+ *
+ * `sweep` offers and never acts, on purpose — there is a human reading it. This runs from a git hook
+ * the moment work lands, where there is nobody to ask, so the two verdicts that would have become a
+ * question become a refusal instead. It adds NO judgement of its own: the judgement is the dangerous
+ * part, it is written above, and it is already tested in both directions.
+ *
+ * Two properties its caller depends on, both load-bearing:
+ *  - it never throws. The caller is git, mid-merge. A throw here would turn a cleanup into a failed
+ *    merge, which is a far worse bug than the one this fixes.
+ *  - it is silent when there is nothing to do, so the common merge prints nothing.
+ */
+export function autoReap(root) {
+  const result = { reaped: [], skipped: [], disabled: false };
+  try {
+    if (!isCleanupEnabled(root)) {
+      result.disabled = true;
+      return result;
+    }
+    for (const candidate of classifyWorktrees(root)) {
+      // Not the protection, and it must not be mistaken for one: `reapWorktree` refuses an `ask`
+      // on its own, and that refusal is the gate — mutation-tested by 18b and 23. Verified here on
+      // 2026-09-17 by removing this line: every test still passed. It stays because skipping early
+      // avoids re-classifying the whole repository once per candidate, and because the recorded
+      // reason is then the verdict itself rather than a message written for a human to read.
+      if (candidate.verdict !== 'safe') {
+        result.skipped.push({ path: candidate.path, reason: candidate.reasons.join(', ') || candidate.verdict });
+        continue;
+      }
+      const out = reapWorktree(root, candidate.path);
+      if (out.removed) result.reaped.push(candidate.path);
+      else result.skipped.push({ path: candidate.path, reason: out.reason });
+    }
+  } catch (err) {
+    // Swallowed deliberately, and recorded rather than discarded: the merge must survive whatever
+    // went wrong in here, but a silent failure that leaves no trace is how this rots unnoticed.
+    result.skipped.push({ path: root, reason: `cleanup could not run: ${err.message}` });
+  }
+  return result;
+}
+
+export const HOOK_MARKER = '# rsc-managed worktree cleanup (post-merge) v1';
+
+// Every branch exits 0. That is the whole contract with git: this hook runs in the middle of
+// somebody's merge, and a cleanup that can turn a good merge into a failed one is a worse bug than
+// the accumulation it exists to fix. Missing node, missing reaper, broken reaper, unreadable repo —
+// all of them are "do nothing", never "fail".
+const HOOK_BODY = `#!/bin/sh
+${'# rsc-managed worktree cleanup (post-merge) v1'}
+# Retires worktrees whose work has just landed. Installed by rsc; safe to delete.
+# Turn it off for this project with: .rsc/.no-worktree-cleanup
+hook_dir=$(dirname "$0")
+if [ -x "$hook_dir/post-merge.rsc-local" ]; then
+  "$hook_dir/post-merge.rsc-local" "$@" || true
+fi
+root=$(git rev-parse --show-toplevel 2>/dev/null) || exit 0
+[ -f "$root/.rsc/worktree-reaper.mjs" ] || exit 0
+command -v node >/dev/null 2>&1 || exit 0
+node "$root/.rsc/worktree-reaper.mjs" "$root" auto 2>/dev/null || true
+exit 0
+`;
+
+/**
+ * Where git will ACTUALLY look for hooks, asked of git rather than assumed.
+ *
+ * The assumption was `<root>/.git/hooks`, and it is wrong in three ordinary situations at once:
+ * a repo that sets `core.hooksPath` (husky v9 writes `.husky/_`, lefthook and committed
+ * `.githooks/` dispatchers do the same), a linked worktree where `.git` is a FILE and the mkdir
+ * raised ENOTDIR, and a submodule. Reported from a user's repo on 2026-09-18 against 2.0.1: rsc
+ * wrote the hook where git does not look, `doctor` read the same wrong path back, and the report
+ * said `armed` about something that could never run. Verified there and here that a single
+ * `rev-parse` answers all three.
+ *
+ * `--path-format=absolute` needs git 2.31 (Mar 2021). Older git gets the old path — which is
+ * correct whenever `core.hooksPath` is unset, i.e. the case it was always right about.
+ */
+export function hooksDir(root) {
+  const r = git(root, ['rev-parse', '--path-format=absolute', '--git-path', 'hooks']);
+  if (r.ok && r.out) return r.out;
+  return join(real(root), '.git', 'hooks');
+}
+
+// Whether that directory is ours to write in. Inside the repository's own git dir: yes, it is
+// private plumbing that is never cloned and never committed. Anywhere else it belongs to the user
+// or to another tool — a committed `.githooks/` is their source tree (writing there would put rsc
+// in their diff, and moving an existing hook aside would rename a TRACKED file), and `.husky/_` is
+// regenerated by husky, so anything we left there disappears on their next install. Report it and
+// let the person decide; that is P4, and it is the same reasoning the comment on this function has
+// claimed since the hook shipped, finally applied instead of only stated.
+export function hooksDirIsOurs(root, dir) {
+  const r = git(root, ['rev-parse', '--path-format=absolute', '--git-common-dir']);
+  if (!r.ok || !r.out) return false;
+  const gitDir = real(r.out);
+  const target = real(dir);
+  return target === gitDir || target.startsWith(gitDir + sep);
+}
+
+/**
+ * Install the trigger. The judgement has existed and been tested for a while; what never existed was
+ * something that runs it at the moment work lands. `post-merge` is that moment, and it covers both
+ * of ship's landing paths — a local `merge --no-ff` and the `pull --ff-only` after a forge merge.
+ *
+ * A hook lives in `.git/hooks/`, which is not cloned. So this is called on install AND on repair,
+ * and `doctor` reports its absence: a trigger nobody re-installs is a trigger that quietly stops
+ * existing on every machine but the one that ran the installer.
+ *
+ * Somebody else's post-merge is moved aside and chained, never overwritten. Husky and lefthook put
+ * real work in there, and eating it to install a convenience would be indefensible.
+ */
+export function installMergeHook(root) {
+  try {
+    const dir = hooksDir(root);
+    if (!hooksDirIsOurs(root, dir)) {
+      return { installed: false, state: 'unreachable', reason: `git reads hooks from ${dir}, which belongs to this repository or to another tool — rsc will not write there.` };
+    }
+    const hook = join(dir, 'post-merge');
+    mkdirSync(dir, { recursive: true });
+    if (existsSync(hook)) {
+      const current = readFileSync(hook, 'utf8');
+      if (current.includes(HOOK_MARKER)) {
+        // Already ours. Rewrite so an older body converges, but never chain ourselves behind
+        // ourselves — repair runs this repeatedly and stacking would run the cleanup N times.
+        writeFileSync(hook, HOOK_BODY);
+        chmodSync(hook, 0o755);
+        return { installed: true, chained: existsSync(join(dir, 'post-merge.rsc-local')) };
+      }
+      renameSync(hook, join(dir, 'post-merge.rsc-local'));
+      chmodSync(join(dir, 'post-merge.rsc-local'), 0o755);
+    }
+    writeFileSync(hook, HOOK_BODY);
+    chmodSync(hook, 0o755);
+    return { installed: true, chained: existsSync(join(dir, 'post-merge.rsc-local')) };
+  } catch (err) {
+    return { installed: false, state: 'failed', reason: err.message };
+  }
+}
+
 export function refusal(candidate) {
   const d = candidate.details || {};
   const parts = (candidate.reasons || []).map((reason) => {
@@ -449,7 +609,11 @@ export function summarize(candidate, root) {
 if (process.argv[1] && import.meta.url === pathToFileURL(process.argv[1]).href) {
   const root = resolve(process.argv[2] || process.cwd());
   const candidates = classifyWorktrees(root).filter((c) => c.verdict !== 'skip');
-  if (process.argv[3] === 'reap') {
+  if (process.argv[3] === 'auto') {
+    // The unattended entry point, called by the post-merge hook. Prints only what it actually did.
+    const out = autoReap(root);
+    for (const p of out.reaped) process.stdout.write(`rsc: retired worktree ${p}\n`);
+  } else 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) {