fix(reaper): detect multi-commit squash-merges via GitHub merged-PR state (disk-accumulation root cause) (#1290)

* fix(reaper): detect multi-commit squash-merges via GitHub merged-PR state (disk-accumulation root cause)

The AgentWorktreeReaper's merged-check used `git cherry` (patch-id) ONLY, which
cannot detect a MULTI-commit branch that was SQUASH-merged. Since this project
squash-merges every PR, merged worktrees were kept forever and accumulated
(~118GB/290 observed), contributing to the 2026-06-26 kernel panic. Diagnosed in
the stalled 28730 session (CMT-1812), picked up here.

- New `fetchMergedPrHeadOids()` — ONE `gh pr list --state merged` call per sweep
  (cached 60s, funneled through withSyncOp). Fail-safe to empty map on any error.
- `isMerged` falls back to the PR map ONLY when `git cherry` says unmerged, and
  treats a worktree as merged only when its branch's merged-PR head OID EXACTLY
  matches the worktree HEAD (post-merge commits are still KEPT). isClean still
  independently blocks any dirty worktree.
- New config `monitoring.agentWorktreeReaper.githubMergeCheck` (default true).
  Reaper still ships OFF + dry-run.
- Tests: 9 new; CLAUDE.md awareness updated.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

* docs(release): add Evidence section to reaper squash-merge fragment

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

---------

Co-authored-by: Instar Agent (echo) <echo@instar.local>
Co-authored-by: Claude Opus 4.8 <noreply@anthropic.com>

Author: 3 people

.instar/instar-dev-decisions/2026-06-26T23-07-20-584Z-reaper-squash-merge-aware.json

@@ -0,0 +1,17 @@
+{
+  "ts": "2026-06-26T23:07:20.584Z",
+  "slug": "reaper-squash-merge-aware",
+  "suggestedTier": 2,
+  "declaredTier": 1,
+  "riskFloor": 2,
+  "riskFloorReasons": [
+    "safety-invariant proximity: src/monitoring/AgentWorktreeReaper.ts matches session reaper",
+    "irreversibility: src/core/PostUpdateMigrator.ts touches PostUpdateMigrator",
+    "migration / fleet-rollout surface: src/core/PostUpdateMigrator.ts touches PostUpdateMigrator (fleet migration machinery)"
+  ],
+  "belowFloor": true,
+  "files": 5,
+  "loc": 106,
+  "causalAutopsy": null,
+  "verdict": "blocked"
+}

.instar/instar-dev-decisions/2026-06-26T23-08-05-065Z-reaper-squash-merge-aware.json

@@ -0,0 +1,17 @@
+{
+  "ts": "2026-06-26T23:08:05.065Z",
+  "slug": "reaper-squash-merge-aware",
+  "suggestedTier": 2,
+  "declaredTier": 1,
+  "riskFloor": 2,
+  "riskFloorReasons": [
+    "safety-invariant proximity: src/monitoring/AgentWorktreeReaper.ts matches session reaper",
+    "irreversibility: src/core/PostUpdateMigrator.ts touches PostUpdateMigrator",
+    "migration / fleet-rollout surface: src/core/PostUpdateMigrator.ts touches PostUpdateMigrator (fleet migration machinery)"
+  ],
+  "belowFloor": true,
+  "files": 5,
+  "loc": 106,
+  "causalAutopsy": null,
+  "verdict": "blocked"
+}

.instar/instar-dev-decisions/2026-06-26T23-48-08-434Z-reaper-squash-merge-aware.json

@@ -0,0 +1,20 @@
+{
+  "ts": "2026-06-26T23:48:08.434Z",
+  "slug": "reaper-squash-merge-aware",
+  "suggestedTier": 2,
+  "declaredTier": 1,
+  "riskFloor": 2,
+  "riskFloorReasons": [
+    "safety-invariant proximity: src/monitoring/AgentWorktreeReaper.ts matches session reaper",
+    "irreversibility: src/core/PostUpdateMigrator.ts touches PostUpdateMigrator",
+    "migration / fleet-rollout surface: src/core/PostUpdateMigrator.ts touches PostUpdateMigrator (fleet migration machinery)"
+  ],
+  "belowFloor": true,
+  "files": 5,
+  "loc": 106,
+  "causalAutopsy": {
+    "origin": "latent",
+    "notes": "Latent blind spot in the reaper's git-cherry merged-check: it documents that multi-commit squash-merges are not detected (their per-commit patch-ids differ from the squashed commit) and conservatively KEEPS them. Because this project squash-merges every PR, merged worktrees accumulated forever (~118GB/290 observed) — a contributor to the 2026-06-26 resource-exhaustion kernel panic. Diagnosed in the stalled 28730 session (CMT-1812), picked up here."
+  },
+  "verdict": "pass"
+}

src/commands/server.ts

@@ -15717,7 +15717,13 @@ export async function startServer(options: StartOptions): Promise<void> {
     const { makeAgentWorktreeReaperDeps } = await import('../monitoring/agentWorktreeGit.js');
     const _agentWorktreesDir = path.join(path.dirname(config.stateDir), '.worktrees');
     const agentWorktreeReaper = new AgentWorktreeReaper(
-      makeAgentWorktreeReaperDeps({ instarRepo: config.projectDir, worktreesDir: _agentWorktreesDir }),
+      makeAgentWorktreeReaperDeps({
+        instarRepo: config.projectDir,
+        worktreesDir: _agentWorktreesDir,
+        // Multi-commit squash-merge detection via GitHub merged-PR state (default
+        // on; fail-safe to cherry-only). Off only if explicitly disabled in config.
+        githubMergeCheck: config.monitoring?.agentWorktreeReaper?.githubMergeCheck ?? true,
+      }),
       config.monitoring?.agentWorktreeReaper,
     );
     agentWorktreeReaper.start();

src/core/PostUpdateMigrator.ts

@@ -5856,8 +5856,9 @@ Every guard (monitoring sentinels, reapers, the scheduler, …) is graded by wha
 CLI-created worktrees under \`~/.instar/agents/<agent>/.worktrees/\` accumulate (each is a full source tree). The AgentWorktreeReaper reclaims ones that are **merged + clean + not-in-use** — for a merged branch the work is in main, so removing the checkout loses nothing (the branch + commits remain). It NEVER touches a worktree with uncommitted changes, an unmerged branch, a live lock, or a running process whose cwd is inside it. Ships **OFF + dry-run** (it deletes on a heuristic).
 
 - See what's reclaimable (and why each is kept): \`curl -H "Authorization: Bearer $AUTH" http://localhost:4040/worktrees/agent-reaper\` → per-worktree verdict (in-use / uncommitted-changes / unmerged / reap-eligible) + the reclaimable count.
+- **Squash-merge detection (the accumulation fix):** the merged-check is patch-id (\`git cherry\`) FIRST — which cannot see a MULTI-commit branch that was SQUASH-merged (its commits' SHAs/patch-ids differ from the single squashed commit), so those worktrees used to pile up forever. The reaper now ALSO consults GitHub merged-PR state (ONE \`gh\` call per sweep) and treats a worktree as merged when its branch has a merged PR whose head commit EXACTLY matches the worktree's HEAD (so a branch with commits added AFTER the merge is still kept). Fail-safe: any \`gh\` error degrades to cherry-only (KEEP). Off-switch: \`{"monitoring": {"agentWorktreeReaper": {"githubMergeCheck": false}}}\`.
 - Review the dry-run report FIRST, then enable in \`.instar/config.json\`: \`{"monitoring": {"agentWorktreeReaper": {"enabled": true, "dryRun": false}}}\`. Tune \`maxReapsPerPass\` (default 20).
-- Pairs with the Spotlight-exclusion marker (fewer worktrees = less disk AND less macOS indexing). Proactive: user asks "why is my disk full of worktrees?" / "clean up old worktrees?" → GET /worktrees/agent-reaper.
+- Pairs with the Spotlight-exclusion marker (fewer worktrees = less disk AND less macOS indexing). Proactive: user asks "why is my disk full of worktrees?" / "clean up old worktrees?" / "why is the reaper calling GitHub?" → GET /worktrees/agent-reaper; the gh call is the squash-merge detection above.
 `;
       content += '\n' + section;
       patched = true;

src/core/types.ts

@@ -4947,6 +4947,9 @@ export interface MonitoringConfig {
     dryRun?: boolean;
     reapIntervalMs?: number;
     maxReapsPerPass?: number;
+    /** Catch multi-commit squash-merges via GitHub merged-PR state (default true;
+     *  fail-safe to git-cherry-only). Set false to disable the network call. */
+    githubMergeCheck?: boolean;
   };
   /**
    * OrphanedWorkSentinel — the silent-uncommitted-death backstop (2026-06-12,

src/monitoring/AgentWorktreeReaper.ts

@@ -41,6 +41,14 @@ export interface AgentWorktreeReaperConfig {
    * permanently-unremovable worktree can't be retried forever. 0 disables the brake.
    */
   maxReclaimFailuresPerPath: number;
+  /**
+   * When true (default), merged-detection falls back to GitHub merged-PR state to
+   * catch MULTI-COMMIT squash-merges that `git cherry` (patch-id) cannot — the
+   * disk-accumulation root cause where squash-merged worktrees are kept forever.
+   * One `gh` call per sweep, fail-safe to cherry-only (KEEP) on any error. Set
+   * false to disable the network call and restore the legacy cherry-only behavior.
+   */
+  githubMergeCheck: boolean;
 }
 
 export const DEFAULT_AGENT_WORKTREE_REAPER_CONFIG: AgentWorktreeReaperConfig = {
@@ -49,6 +57,7 @@ export const DEFAULT_AGENT_WORKTREE_REAPER_CONFIG: AgentWorktreeReaperConfig = {
   reapIntervalMs: 24 * 3600 * 1000,
   maxReapsPerPass: 20,
   maxReclaimFailuresPerPath: 3,
+  githubMergeCheck: true,
 };
 
 export interface WorktreeInfo {

src/monitoring/agentWorktreeGit.ts

@@ -11,6 +11,7 @@ import fs from 'node:fs';
 import path from 'node:path';
 import { execFileSync } from 'node:child_process';
 import { SafeGitExecutor } from '../core/SafeGitExecutor.js';
+import { withSyncOp } from '../core/InFlightSyncOpMarker.js';
 import { classifyPorcelain } from '../core/worktreeDirtyCheck.js';
 import type { AgentWorktreeReaperDeps, WorktreeInfo } from './AgentWorktreeReaper.js';
 
@@ -88,6 +89,54 @@ export function isBranchMerged(readGit: ReadGit, repo: string, baseRef: string,
   return lines.every((l) => l.startsWith('-'));
 }
 
+/** Run `gh` and return stdout, or null on ANY failure (gh missing, not authed,
+ *  not a GitHub repo, timeout). Null is the conservative signal → caller keeps. */
+export type RunGh = (args: string[], cwd: string) => string | null;
+
+const defaultRunGh: RunGh = (args, cwd) => {
+  try {
+    // Funnel through withSyncOp so the in-flight marker sees this blocking spawn
+    // (event-loop-resilience spec): the reaper runs in-process on a timer, and a
+    // bounded gh call must not read as a "stuck" event loop to the watchdogs.
+    return withSyncOp(() => execFileSync('gh', args, { cwd, encoding: 'utf-8', timeout: 30_000, maxBuffer: 16 * 1024 * 1024 }));
+  } catch {
+    return null; // @silent-fallback-ok — gh unavailable ⇒ no PR signal ⇒ KEEP (conservative)
+  }
+};
+
+/**
+ * Fetch a map of `headRefName → headRefOid` for MERGED PRs, to detect
+ * MULTI-COMMIT squash-merges that `git cherry` (patch-id) cannot — the
+ * disk-accumulation root cause: a multi-commit branch squash-merged into one
+ * commit on main has different commit SHAs/patch-ids, so cherry reports it
+ * UNMERGED and the worktree is kept forever. A merged PR is the authoritative
+ * "the content is in main" signal; pairing it with an EXACT head-OID match (in
+ * the caller) ensures a branch with commits ADDED AFTER the merge is still kept.
+ *
+ * ONE `gh` call per sweep (bounded `--limit`); fail-safe to an EMPTY map on any
+ * error so the reaper degrades to exactly today's cherry-only behavior (KEEP).
+ */
+export function fetchMergedPrHeadOids(repo: string, opts?: { runGh?: RunGh; limit?: number }): Map<string, string> {
+  const runGh = opts?.runGh ?? defaultRunGh;
+  const limit = opts?.limit ?? 500;
+  const map = new Map<string, string>();
+  const out = runGh(['pr', 'list', '--state', 'merged', '--json', 'headRefName,headRefOid', '--limit', String(limit)], repo);
+  if (!out) return map; // conservative: no signal
+  let arr: unknown;
+  try { arr = JSON.parse(out); } catch { return map; }
+  if (!Array.isArray(arr)) return map;
+  for (const row of arr) {
+    if (!row || typeof row !== 'object') continue;
+    const name = (row as { headRefName?: unknown }).headRefName;
+    const oid = (row as { headRefOid?: unknown }).headRefOid;
+    if (typeof name === 'string' && typeof oid === 'string' && name && oid) {
+      // Latest merged PR for a (reused) branch name wins — gh returns newest first.
+      if (!map.has(name)) map.set(name, oid);
+    }
+  }
+  return map;
+}
+
 /**
  * Build the production git/fs-backed deps for the AgentWorktreeReaper.
  * `worktreesDir` bounds which `git worktree list` entries are considered (the
@@ -101,10 +150,18 @@ export function makeAgentWorktreeReaperDeps(opts: {
   /** Override the process-cwd scanner (testing). Returns the set of worktree
    *  ROOT paths that currently have a live process cwd inside them. */
   cwdRoots?: () => Set<string>;
+  /** When true (default), `isMerged` falls back to GitHub merged-PR state to
+   *  detect multi-commit squash-merges that `git cherry` cannot. Fail-safe:
+   *  any gh error degrades to cherry-only (KEEP). Set false to disable the
+   *  network call entirely (the legacy cherry-only behavior). */
+  githubMergeCheck?: boolean;
+  /** Override the merged-PR map source (testing). Returns headRefName→headRefOid. */
+  mergedPrMap?: () => Map<string, string>;
   now?: () => number;
 }): AgentWorktreeReaperDeps {
   const readGit = opts.readGit ?? defaultReadGit;
   const repo = opts.instarRepo;
+  const githubMergeCheck = opts.githubMergeCheck ?? true;
   const worktreesReal = (() => { try { return fs.realpathSync(opts.worktreesDir); } catch { return opts.worktreesDir; } })();
   const within = (p: string): boolean => {
     const real = (() => { try { return fs.realpathSync(p); } catch { return p; } })();
@@ -144,6 +201,19 @@ export function makeAgentWorktreeReaperDeps(opts: {
     return cwdCache;
   };
 
+  // Merged-PR map (headRefName→headRefOid), cached for a short TTL so a single
+  // reap pass makes ONE `gh` call, not one per worktree. The map only fixes the
+  // multi-commit-squash blind spot in `git cherry`; it is consulted lazily (only
+  // when cherry says unmerged) so a fully cherry-detectable repo never calls gh.
+  const mergedPrMapFn = opts.mergedPrMap ?? (() => fetchMergedPrHeadOids(repo));
+  let prMapCache: Map<string, string> | null = null;
+  let prMapCacheAt = 0;
+  const mergedPrMapCached = (): Map<string, string> => {
+    const t = Date.now();
+    if (!prMapCache || t - prMapCacheAt > 60_000) { prMapCache = mergedPrMapFn(); prMapCacheAt = t; }
+    return prMapCache;
+  };
+
   return {
     listWorktrees: (): WorktreeInfo[] => {
       let porcelain: string;
@@ -189,7 +259,18 @@ export function makeAgentWorktreeReaperDeps(opts: {
     isMerged: (info: WorktreeInfo): boolean => {
       const base = resolveBaseRef(readGit, repo);
       if (!base || !info.headSha) return false;
-      return isBranchMerged(readGit, repo, base, info.headSha);
+      // 1) Patch-id equivalence (fast, offline): fast-forward / merge / rebase /
+      //    single-commit-squash. Never false-positives "merged".
+      if (isBranchMerged(readGit, repo, base, info.headSha)) return true;
+      // 2) Multi-commit squash-merge: `git cherry` cannot see it (SHAs differ).
+      //    Consult GitHub merged-PR state — but require an EXACT head-OID match so
+      //    a branch with commits ADDED AFTER the merge is still KEPT (those would
+      //    be unmerged work). Fail-safe: an empty/missing map ⇒ KEEP.
+      if (githubMergeCheck && info.branch) {
+        const oid = mergedPrMapCached().get(info.branch);
+        if (oid && oid === info.headSha) return true;
+      }
+      return false;
     },
 
     isInUse: (p: string): boolean => {

tests/unit/agent-worktree-reaper.test.ts

@@ -12,7 +12,7 @@ import {
   type AgentWorktreeReaperDeps,
   type WorktreeInfo,
 } from '../../src/monitoring/AgentWorktreeReaper.js';
-import { isBranchMerged, resolveBaseRef, makeAgentWorktreeReaperDeps, REAPER_RESIDUE_DENYLIST, type ReadGit } from '../../src/monitoring/agentWorktreeGit.js';
+import { isBranchMerged, resolveBaseRef, makeAgentWorktreeReaperDeps, fetchMergedPrHeadOids, REAPER_RESIDUE_DENYLIST, type ReadGit, type RunGh } from '../../src/monitoring/agentWorktreeGit.js';
 import fs from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
@@ -131,6 +131,99 @@ describe('isBranchMerged (git cherry) — conservative, never false-positive', (
   });
 });
 
+describe('fetchMergedPrHeadOids — gh-backed multi-commit-squash detection', () => {
+  const ghOut = (rows: Array<{ headRefName: string; headRefOid: string }>): RunGh => () => JSON.stringify(rows);
+
+  it('parses gh merged-PR JSON into a headRefName→headRefOid map', () => {
+    const m = fetchMergedPrHeadOids('/repo', { runGh: ghOut([
+      { headRefName: 'echo/feat-a', headRefOid: 'oidA' },
+      { headRefName: 'echo/feat-b', headRefOid: 'oidB' },
+    ]) });
+    expect(m.get('echo/feat-a')).toBe('oidA');
+    expect(m.get('echo/feat-b')).toBe('oidB');
+    expect(m.size).toBe(2);
+  });
+
+  it('keeps the FIRST (newest) entry when a branch name is reused', () => {
+    const m = fetchMergedPrHeadOids('/repo', { runGh: ghOut([
+      { headRefName: 'echo/reused', headRefOid: 'newest' },
+      { headRefName: 'echo/reused', headRefOid: 'older' },
+    ]) });
+    expect(m.get('echo/reused')).toBe('newest');
+  });
+
+  it('fail-safe to EMPTY map when gh is unavailable (null) — conservative KEEP', () => {
+    const m = fetchMergedPrHeadOids('/repo', { runGh: () => null });
+    expect(m.size).toBe(0);
+  });
+
+  it('fail-safe to EMPTY map on malformed JSON', () => {
+    const m = fetchMergedPrHeadOids('/repo', { runGh: () => 'not json' });
+    expect(m.size).toBe(0);
+  });
+
+  it('ignores rows missing name or oid', () => {
+    const m = fetchMergedPrHeadOids('/repo', { runGh: () => JSON.stringify([
+      { headRefName: 'ok', headRefOid: 'oidOk' },
+      { headRefName: '', headRefOid: 'x' },
+      { headRefOid: 'noName' },
+      { headRefName: 'noOid' },
+    ]) });
+    expect(m.get('ok')).toBe('oidOk');
+    expect(m.size).toBe(1);
+  });
+});
+
+describe('makeAgentWorktreeReaperDeps.isMerged — multi-commit squash via PR map', () => {
+  // readGit: rev-parse resolves a base; cherry reports UNMERGED (a "+" commit),
+  // which is exactly the multi-commit-squash blind spot.
+  const cherryUnmergedGit: ReadGit = (args) => {
+    if (args.includes('rev-parse')) return ''; // base resolves
+    if (args.includes('cherry')) return '+ aaa\n+ bbb'; // looks unmerged
+    throw new Error('unexpected git call: ' + args.join(' '));
+  };
+  const wt = (branch: string, headSha: string) => ({ path: '/x', branch, headSha });
+
+  it('MERGED when cherry says unmerged but a merged PR head-OID matches exactly', () => {
+    const deps = makeAgentWorktreeReaperDeps({
+      instarRepo: '/repo', worktreesDir: '/repo/.worktrees', readGit: cherryUnmergedGit,
+      githubMergeCheck: true,
+      mergedPrMap: () => new Map([['echo/feat', 'SQUASHED_OID']]),
+    });
+    expect(deps.isMerged(wt('echo/feat', 'SQUASHED_OID'))).toBe(true);
+  });
+
+  it('KEEP when the branch advanced past the merged PR (head-OID mismatch = unmerged work)', () => {
+    const deps = makeAgentWorktreeReaperDeps({
+      instarRepo: '/repo', worktreesDir: '/repo/.worktrees', readGit: cherryUnmergedGit,
+      githubMergeCheck: true,
+      mergedPrMap: () => new Map([['echo/feat', 'MERGED_OID']]),
+    });
+    // worktree HEAD is a NEW commit added after the merge → must be KEPT
+    expect(deps.isMerged(wt('echo/feat', 'NEWER_OID_WITH_UNMERGED_WORK'))).toBe(false);
+  });
+
+  it('KEEP when no merged PR exists for the branch', () => {
+    const deps = makeAgentWorktreeReaperDeps({
+      instarRepo: '/repo', worktreesDir: '/repo/.worktrees', readGit: cherryUnmergedGit,
+      githubMergeCheck: true,
+      mergedPrMap: () => new Map(),
+    });
+    expect(deps.isMerged(wt('echo/feat', 'anySha'))).toBe(false);
+  });
+
+  it('KEEP (legacy cherry-only) when githubMergeCheck is disabled — never calls the PR map', () => {
+    const prMap = vi.fn(() => new Map([['echo/feat', 'SQUASHED_OID']]));
+    const deps = makeAgentWorktreeReaperDeps({
+      instarRepo: '/repo', worktreesDir: '/repo/.worktrees', readGit: cherryUnmergedGit,
+      githubMergeCheck: false,
+      mergedPrMap: prMap,
+    });
+    expect(deps.isMerged(wt('echo/feat', 'SQUASHED_OID'))).toBe(false);
+    expect(prMap).not.toHaveBeenCalled();
+  });
+});
+
 describe('makeAgentWorktreeReaperDeps.isInUse — lock OR live process cwd', () => {
   let tmp: string;
   beforeEach(() => { tmp = fs.mkdtempSync(path.join(os.tmpdir(), 'awr-inuse-')); });