kenaz 0.0.0-stage → 0.3.2

package/core/.claude/hooks/worktree-create.js

@@ -0,0 +1,1232 @@
+#!/usr/bin/env node
+'use strict';
+
+/**
+ * worktree-create.js — Claude Code `WorktreeCreate` hook.
+ *
+ * PROBLEM (TASK_1586): The Agent/Task tool's `isolation: "worktree"` creates the
+ * isolated worktree from the SESSION cwd's git repo. In production the Kenaz
+ * dashboard launches the interactive session with cwd = kenaz-core (a bundled
+ * file COPY — NOT a git checkout), while the user's actual project is a separate
+ * git repo. The harness then fails: "not in a git repository".
+ *
+ * FIX: when configured as a WorktreeCreate hook, the harness DELEGATES worktree
+ * creation entirely to this script (it no longer runs `git worktree add` itself).
+ * This script:
+ *   - Branch 1 (dev / same-repo): session cwd IS a git repo → create the worktree
+ *     in that repo at the harness-proposed path (faithful passthrough).
+ *   - Branch 2 (production): session cwd is NOT a git repo → resolve the active
+ *     project from ~/.kenaz/projects.json (same source as Rust get_current_project)
+ *     and create the worktree inside THAT git repo.
+ *   - No git target resolvable → exit non-zero with a readable message so the
+ *     dispatch degrades cleanly instead of surfacing a raw harness error.
+ *
+ * Contract (code.claude.com/docs hooks.md):
+ *   stdin  JSON: { session_id, transcript_path, cwd, hook_event_name,
+ *                  worktree_path (proposed, ignorable), isolation_reason }
+ *   env:        CLAUDE_PROJECT_DIR, CLAUDE_SESSION_ID
+ *   stdout:     the chosen worktree path (exit 0). Path is fully hook-controlled
+ *               and MAY live in a different git repo than cwd.
+ *   non-zero:   blocks worktree creation.
+ *
+ * Cross-platform (GEN-009): pure node + git CLI, path.join, no shell.
+ *
+ * Hardening history:
+ *   TASK_1586 -- Branch 2 production redirect (non-git cwd -> projects.json target)
+ *   TASK_1639 -- remove --force idempotency removed; uniquify loop added
+ *   TASK_1647 -- longpaths flag; failed-add rollback; lock-resilient GC; shorter paths
+ *   TASK_1777 -- sibling placement OUTSIDE the repo tree: the harness worktree-
+ *                isolation guard denies Edit/Write on any path under the shared
+ *                checkout; a worktree nested at <repo>/.formation/worktrees/wt-*
+ *                is entirely inside the shared checkout, so isolated agents could
+ *                not use Edit/Write at all (absolute fwd/back-slash AND relative
+ *                path forms all denied — verified empirically in TASK_1777).
+ *   TASK_1827 -- landed-marker GC: ancestry / patch-equivalence inference is
+ *                PROVEN WRONG on a known-answer control (ansuz-wt-68ed9c57-12936
+ *                was file-scoped-checkout merged and fully verified, yet both
+ *                `git cherry` and `merge-base --is-ancestor` still reported it
+ *                unmerged — file-scoped checkout + fresh commit changes the
+ *                patch-id parent context, and ancestry never held to begin
+ *                with). The merger is the only party that KNOWS the work landed,
+ *                so the merger records it: post-complete writes a landed marker
+ *                on verified merge success, and the main thread's manual
+ *                file-scoped merges use `mark-landed` (CLI below). GC reclaims
+ *                ONLY worktrees with a landed marker — no inference, no bypass.
+ *
+ * CLI subcommands (TASK_1827/TASK_1876; no args = normal WorktreeCreate hook mode):
+ *   node .claude/hooks/worktree-create.js mark-landed <wt-name|path|branch> [--task TASK_X] [--repo <path>] [--by <who>]
+ *   node .claude/hooks/worktree-create.js gc [--dry-run] [--repo <path>]
+ *   node .claude/hooks/worktree-create.js gc --review [--repo <path>]
+ *   node .claude/hooks/worktree-create.js gc --approve <wt-name...> | --approve --all [--repo <path>]
+ *
+ *   TASK_1876 — the automatic half of the contract above now actually runs:
+ *   post-complete's direct-commit fast-path (the dominant merge-confirmation
+ *   point under subagent-default dispatch) calls appendLandedMarker with
+ *   via=post-complete-direct-commit; gc reports a `marker-starved: N` stderr
+ *   count on every run; gc --review/--approve give the backlog an
+ *   evidence-based batch path that reclaims through this same GC (never a
+ *   second deletion implementation).
+ */
+
+const fs = require('fs');
+const path = require('path');
+const os = require('os');
+const { execFileSync } = require('child_process');
+// TASK_2057: shared __kenaz_core__ token resolver (same file, no cross-dir
+// require needed here -- ansuz-boot-fast.js reaches this same module from
+// .specialist/tools/).
+const { resolveVirtualPath } = require('./core-resolve.js');
+// TASK_2163: chart files are keyed by project identity + task id. Loaded
+// lazily and guarded (Ansuz review): this hook also runs from the installed
+// kenaz-core copy, and a load failure at module scope would break EVERY
+// worktree creation over a cleanup heuristic.
+function chartReadPath(repo, id) {
+  try {
+    return require('../../.specialist/tools/lib/chart-path.js').getChartReadPath(id, { projectPath: repo });
+  } catch {
+    return path.join(repo, '.specialist', 'sessions', 'chart_' + id + '.json');
+  }
+}
+
+function readStdin() {
+  try { return fs.readFileSync(0, 'utf8'); } catch { return ''; }
+}
+
+/**
+ * Run a git command in `repo`.
+ * Always passes `-c core.longpaths=true` so Windows long-path checkouts work
+ * on repos that have not set core.longpaths globally. On macOS/Linux the flag is
+ * a no-op (GEN-009). We do NOT write to any git config file here.
+ */
+function git(repo, args) {
+  return execFileSync('git', ['-C', repo, '-c', 'core.longpaths=true', ...args], {
+    stdio: ['ignore', 'pipe', 'pipe'],
+  }).toString().trim();
+}
+
+function isGitRepo(dir) {
+  if (!dir) return false;
+  try {
+    return execFileSync('git', ['-C', dir, 'rev-parse', '--is-inside-work-tree'], {
+      stdio: ['ignore', 'pipe', 'ignore'],
+    }).toString().trim() === 'true';
+  } catch { return false; }
+}
+
+function gitTopLevel(dir) {
+  try { return git(dir, ['rev-parse', '--show-toplevel']); } catch { return null; }
+}
+
+/** Resolve the active project's git repo from ~/.kenaz/projects.json (mirrors Rust get_current_project). */
+function resolveTargetRepo() {
+  try {
+    const home = process.env.HOME || os.homedir();
+    const raw = fs.readFileSync(path.join(home, '.kenaz', 'projects.json'), 'utf8');
+    const pj = JSON.parse(raw);
+    const proj = (pj.projects || []).find((p) => p.id === pj.currentProjectId);
+    // TASK_2057: the core entry's path is the literal token "__kenaz_core__",
+    // not a real path (dev/PROJECT_REGISTRY_DUPLICATE_ASSESSMENT.md) --
+    // resolve it before probing isGitRepo, or this always failed for core.
+    const resolvedPath = proj && proj.path ? resolveVirtualPath(proj.path) : null;
+    if (resolvedPath && isGitRepo(resolvedPath)) return gitTopLevel(resolvedPath);
+  } catch { /* fall through */ }
+  return null;
+}
+
+/**
+ * Garbage-collect stale sibling agent worktrees in BOTH base dirs:
+ *   - sibling (current, TASK_1777): <repoParent>/.kenaz-worktrees/<repoName>
+ *   - legacy in-repo (pre-TASK_1777 husks): <repo>/.formation/worktrees
+ *
+ * The harness does NOT reliably fire WorktreeRemove on subagent completion when a
+ * WorktreeCreate hook is configured (observed: worktree persists post-completion),
+ * so worktrees would otherwise accumulate across sessions. This sweep bounds that.
+ *
+ * TASK_1826: two GC-eligible naming families (anything else — e.g. squad
+ * `<sessionId>-<memberId>` detached worktrees — is never touched):
+ *   wt-<sid8>-<pid>   → branch ansuz-wt-<sid8>-<pid>   (Agent tool, this hook)
+ *   task_<taskid>     → branch task/<taskid>           (Formation setupUnitWorktree)
+ * Branch derivation differs per family; never apply one family's string
+ * surgery to the other.
+ *
+ * SAFETY (TASK_1827 — reclaim is a strict CONJUNCTION, no bypass):
+ *   A sibling is removed ONLY when ALL hold:
+ *   - it is not the worktree we are about to (re)create (keepPath),
+ *   - its directory mtime is older than GC_MIN_AGE_MS (won't touch a concurrently
+ *     live session's fresh worktree). NEVER shorten this — it is the only guard
+ *     against deleting a live concurrent session's worktree,
+ *   - it has a LANDED MARKER in the ledger (written by post-complete on verified
+ *     merge success, or by the `mark-landed` CLI after a manual file-scoped
+ *     merge). Missing marker → ALWAYS kept, with a diagnostic. Ancestry /
+ *     patch-equivalence inference is NOT used: both were disproven on a
+ *     known-answer control (see file header),
+ *   - if the branch still exists, its tip matches the tip recorded in the
+ *     marker (commits made AFTER the landing were never verified → keep),
+ *   - it has no uncommitted change outside the daemon-noise allowlist —
+ *     evaluated ONLY when the directory is a FUNCTIONING standalone worktree
+ *     (its `rev-parse --show-toplevel` resolves to itself). A husk whose .git
+ *     link is already gone resolves to the PARENT repo (or errors on a pruned
+ *     gitdir), so its porcelain would describe the wrong tree entirely
+ *     (TASK_1826); a husk cannot host a live agent, so with a landed marker it
+ *     is reclaimable as-is.
+ *   Every keep decision emits a stderr diagnostic naming the condition and the
+ *   file(s) responsible — silent retention left users unable to see why 19 of
+ *   21 worktrees never collected.
+ */
+const GC_MIN_AGE_MS = 2 * 60 * 60 * 1000; // 2h
+
+// ── TASK_1827: landed-marker ledger ─────────────────────────────────────────
+// Format: append-only JSONL, one entry per landing event:
+//   { v:1, branch, worktree, task, tip, via, by, at }
+// WHY THIS FORM (over the alternatives):
+//   - vs in-worktree marker file: dies with the worktree (no audit trail),
+//     dirties the worktree's porcelain, and is unreachable on husks / the
+//     worktree_missing post-complete path.
+//   - vs git refs (refs/kenaz-landed/*): not hand-editable, needs git plumbing
+//     to inspect/revoke, and cannot carry who/why/when metadata legibly.
+//   - JSONL in-repo: human-readable, greppable, revocable by deleting a line,
+//     survives worktree deletion, readable with zero infrastructure (no
+//     dashboard). Located under .formation/worktrees/ which is wholesale
+//     gitignored (line ".formation/worktrees/"), so the ledger itself never
+//     shows up as git-status noise — the exact failure mode this card fights.
+function landedLedgerPath(repo) {
+  return path.join(repo, '.formation', 'worktrees', 'landed-ledger.jsonl');
+}
+
+function appendLandedMarker(repo, { branch, worktree, task, tip, via, by }) {
+  const entry = {
+    v: 1,
+    branch: branch || null,
+    worktree: worktree || null,
+    task: task || null,
+    tip: tip || null,
+    via: via || 'unknown',
+    by: by || null,
+    at: new Date().toISOString(),
+  };
+  const ledger = landedLedgerPath(repo);
+  fs.mkdirSync(path.dirname(ledger), { recursive: true });
+  fs.appendFileSync(ledger, JSON.stringify(entry) + '\n');
+  return entry;
+}
+
+/** Read the ledger into lookup maps. Later entries win. Bad lines are skipped. */
+function readLandedIndex(repo) {
+  const byBranch = new Map();
+  const byName = new Map();
+  try {
+    const raw = fs.readFileSync(landedLedgerPath(repo), 'utf8');
+    for (const line of raw.split('\n')) {
+      const t = line.trim();
+      if (!t) continue;
+      try {
+        const e = JSON.parse(t);
+        if (e && e.branch) byBranch.set(e.branch, e);
+        if (e && e.worktree) byName.set(e.worktree, e);
+      } catch { /* skip malformed line — revocation by hand-editing is allowed */ }
+    }
+  } catch { /* no ledger yet */ }
+  return { byBranch, byName };
+}
+
+/** Branch derivation per naming family (TASK_1826). Unknown families → null. */
+function deriveBranchForName(name) {
+  if (name.startsWith('wt-')) return 'ansuz-wt-' + name.slice(3);
+  if (name.startsWith('task_')) return 'task/' + name.slice(5);
+  return null;
+}
+
+// ── TASK_1827: daemon-noise classification for dirty paths ──────────────────
+// The tracked/untracked dichotomy CANNOT separate the two observed specimens
+// (ansuz_project_pins.json = daemon state, TASK_1739_HANDOFF.md = agent
+// deliverable — BOTH untracked). Discrimination is therefore an explicit
+// path allowlist of known daemon/harness writers, read from
+// .kenaz/specialist/daemon-manifest.yaml: state_files + static_paths +
+// gc_disposable_paths (new GC-only section). Everything NOT on the list —
+// tracked source, untracked deliverables like HANDOFF docs — is real work and
+// blocks reclaim. Rejected alternatives: glob heuristics ("*.jsonl is noise")
+// would eat real agent logs; age-based rules say nothing about a file's
+// nature; tracked/untracked fails both specimens above. commit_exclude_files
+// (user configs, TASK_1818) are deliberately NOT noise: user-authored bytes
+// are never discardable.
+// thrift: flat-list YAML subset parser (the manifest is flat lists only);
+// switch to .vendor/js-yaml.cjs if the manifest ever gains nesting.
+const GC_NOISE_MANIFEST_SECTIONS = ['state_files', 'static_paths', 'gc_disposable_paths'];
+
+function loadGcNoisePaths(repo) {
+  const out = [];
+  try {
+    const raw = fs.readFileSync(path.join(repo, '.kenaz', 'specialist', 'daemon-manifest.yaml'), 'utf8');
+    let section = null;
+    for (const line of raw.split('\n')) {
+      const key = line.match(/^([A-Za-z0-9_]+):\s*(#.*)?$/);
+      if (key) { section = key[1]; continue; }
+      if (!GC_NOISE_MANIFEST_SECTIONS.includes(section)) continue;
+      const item = line.match(/^\s*-\s*(.+?)\s*$/);
+      if (!item) continue;
+      let v = item[1];
+      if ((v.startsWith('"') && v.endsWith('"')) || (v.startsWith("'") && v.endsWith("'"))) {
+        v = v.slice(1, -1);
+      }
+      if (v && !v.startsWith('#')) out.push(v.replace(/\\/g, '/'));
+    }
+  } catch { /* manifest unreadable → empty noise set → ALL dirt kept (safe direction) */ }
+  return out;
+}
+
+function isNoisePath(relPath, noisePaths) {
+  const p = relPath.replace(/\\/g, '/');
+  for (const n of noisePaths) {
+    if (n.endsWith('/')) { if (p.startsWith(n)) return true; }
+    else if (n.endsWith('*')) {
+      // TASK_1840: trailing-* prefix match for filenames with a variable part
+      // (e.g. .kenaz/specialist/progress_note_* matches
+      // progress_note_TASK_1793.json). Same-directory ONLY: the remainder must
+      // not contain '/', so a wildcard entry can never silently cover a whole
+      // subtree the way a '/'-suffixed directory entry does.
+      const rest = p.slice(n.length - 1);
+      if (p.startsWith(n.slice(0, -1)) && !rest.includes('/')) return true;
+    }
+    else if (p === n) return true;
+  }
+  return false;
+}
+
+// ── TASK_1840: progress-note landed gate ────────────────────────────────────
+// Agents write .kenaz/specialist/progress_note_<TASK_ID>.json in their worktree
+// AFTER the final commit (per the dispatch prompt), leaving permanent dirt that
+// made the worktree unreclaimable forever. The manifest wildcard entry makes
+// the path expressible, but the LOCAL copy is only disposable when the note is
+// CONFIRMED merged into the core chart (phase-gate.js `note` appends it to
+// <repo>/.specialist/sessions/chart_<TASK_ID>.json -> progress_notes[]).
+// Returns: null  = not a progress-note path (no gating applies),
+//          true  = note landed in the core chart (disposable),
+//          false = not confirmed landed -> treated as REAL work (keep).
+// Unknown/unreadable chart -> false (safe direction: keep).
+// TASK_2163: chart-path.js resolves the REAL core sessions dir regardless of
+// what `repo` is (it walks up from its own file location, not from `repo`),
+// and keys the chart by `repo` as project identity -- core repo -> flat
+// legacy filename (unchanged), sub-project repo -> the keyed subdirectory
+// that sub-project's phase-gate/etc. runs actually wrote to (getChartReadPath
+// also falls back to the pre-fix flat path, so charts written before this
+// fix still resolve). Previously this hand-built path.join(repo,
+// '.specialist', 'sessions', ...) directly, which could only ever succeed
+// for the core repo (sub-projects have no .specialist/ of their own).
+const PROGRESS_NOTE_RE = /^\.kenaz\/specialist\/progress_note_(.+?)(?:\.json)?$/;
+
+function isLandedProgressNote(repo, relPath) {
+  const m = relPath.replace(/\\/g, '/').match(PROGRESS_NOTE_RE);
+  if (!m) return null;
+  if (!repo) return false;
+  try {
+    const chart = JSON.parse(fs.readFileSync(
+      chartReadPath(repo, m[1]), 'utf8'));
+    return Array.isArray(chart.progress_notes) && chart.progress_notes.length > 0;
+  } catch { return false; }
+}
+
+/**
+ * Classify a worktree's `status --porcelain` output into daemon noise vs real
+ * work. Returns { real: string[], noise: string[] }. Uses its own raw git call
+ * (NOT the trimming git() helper — trimming eats the leading space of the
+ * first " M path" line) with core.quotePath=false so CJK paths stay literal.
+ */
+function classifyWorktreeDirt(worktreeDir, noisePaths, repo) {
+  const raw = execFileSync('git', ['-C', worktreeDir, '-c', 'core.longpaths=true',
+    '-c', 'core.quotePath=false', 'status', '--porcelain'],
+    { stdio: ['ignore', 'pipe', 'pipe'] }).toString();
+  const real = [];
+  const noise = [];
+  for (const line of raw.split('\n')) {
+    if (!line.trim()) continue;
+    let rel = line.slice(3);
+    const arrow = rel.indexOf(' -> '); // rename: judge the destination path
+    if (arrow >= 0) rel = rel.slice(arrow + 4);
+    rel = rel.replace(/\\/g, '/');
+    // TASK_1840: a noise-matched progress note is disposable ONLY when its
+    // content is confirmed merged into the core chart. false = keep as real
+    // work; null = not a progress note, the plain noise-list verdict stands.
+    const noisy = isNoisePath(rel, noisePaths)
+      && isLandedProgressNote(repo, rel) !== false;
+    (noisy ? noise : real).push(rel);
+  }
+  return { real, noise };
+}
+
+function gcStaleWorktrees(repo, keepPath, opts) {
+  const dryRun = !!(opts && opts.dryRun);
+  // TASK_1827 follow-up: KEEP diagnostics are opt-in (verbose), because this GC
+  // also runs inline in WorktreeCreate hook mode, whose ONLY contract is "write
+  // the worktree path to stdout". Emitting one line per kept worktree there made
+  // the harness fail every dispatch with "hook succeeded but returned no worktree
+  // path" — 21 kept worktrees produced 21 lines around the single line that
+  // matters. Reclaim/failure notices below stay unconditional: they report an
+  // action actually taken, and there is at most a handful per run.
+  // Run `node .claude/hooks/worktree-create.js gc --dry-run` for the full report.
+  const verbose = !!(opts && opts.verbose);
+  const notice = (msg) => process.stderr.write('[worktree-create] gc: ' + msg + '\n');
+  const diag = (msg) => { if (verbose) notice(msg); };
+  // TASK_1876: count (and optionally collect) worktrees kept at the
+  // missing-marker conjunct. Before this, the structural gap "the merger never
+  // records landings" was invisible unless someone ran --dry-run AND read 30
+  // per-tree diag lines; measured result: 30/31 worktrees accumulated silently.
+  // The count is emitted UNCONDITIONALLY as ONE stderr line (see below) so the
+  // gap reads 0 when healthy and non-zero the moment the auto path degrades.
+  let markerStarved = 0;
+  let reclaimedCount = 0;
+  const starvedOut = (opts && opts.collectStarved) || null;
+  try {
+    const wtDirs = [
+      siblingWorktreeBase(repo),                   // sibling layout (TASK_1777)
+      path.join(repo, '.formation', 'worktrees'),  // legacy in-repo layout (old husks)
+    ];
+    const landed = readLandedIndex(repo);
+    const noisePaths = loadGcNoisePaths(repo);
+    const keep = path.resolve(keepPath).replace(/\\/g, '/').toLowerCase();
+    const now = Date.now();
+    for (const wtDir of wtDirs) {
+    if (!fs.existsSync(wtDir)) continue;
+    for (const name of fs.readdirSync(wtDir)) {
+      // Two GC-eligible naming families (TASK_1826). Unknown names (e.g. squad
+      // `<sessionId>-<memberId>` detached worktrees) are never touched.
+      // NOTE: .claude/worktrees/agent-* (harness-owned) is deliberately OUTSIDE
+      // both base dirs and must never be added here — deleting a live one kills
+      // a running agent (TASK_1827 exclusion).
+      const branch = deriveBranchForName(name);
+      if (!branch) continue;
+      const p = path.join(wtDir, name);
+      const rp = path.resolve(p).replace(/\\/g, '/').toLowerCase();
+      if (rp === keep) continue;
+      let st;
+      try { st = fs.statSync(p); } catch { continue; }
+      if (!st.isDirectory()) continue;
+      if (now - st.mtimeMs < GC_MIN_AGE_MS) {
+        // Too fresh — maybe a live concurrent session. Not inspected further
+        // (no git command is run against it).
+        const ageMin = Math.round((now - st.mtimeMs) / 60000);
+        diag(name + ' kept — too fresh (mtime ' + ageMin + 'm < 2h), not inspected');
+        continue;
+      }
+      // CONJUNCT (TASK_1827): landed marker. The merger records the landing;
+      // GC never infers it. Missing marker → keep, no bypass.
+      const marker = landed.byBranch.get(branch) || landed.byName.get(name);
+      if (!marker) {
+        markerStarved += 1;
+        if (starvedOut) starvedOut.push({ name, branch, dir: p, baseDir: wtDir });
+        diag(name + ' kept — no landed marker for branch ' + branch
+          + ' (merge not recorded; after verifying the work landed, run:'
+          + ' node .claude/hooks/worktree-create.js mark-landed ' + name + ')');
+        continue;
+      }
+      // Marker staleness: if the branch still exists and its tip moved past
+      // what was recorded at landing time, the newer commits were never
+      // verified as landed — keep. (Not inference: just checking the recorded
+      // fact still describes the current branch state.)
+      let tip = null;
+      try {
+        tip = git(repo, ['rev-parse', '--verify', '--quiet', 'refs/heads/' + branch]);
+      } catch { tip = null; } // branch already deleted — normal post-merge state
+      // TASK_2253: a null-tip marker (written after the branch was already
+      // deleted) cannot vouch for a branch that exists NOW — a re-dispatch may
+      // have reused the name with unverified commits. Staleness unverifiable →
+      // keep (safe direction); `git branch -D` below never runs on this path.
+      if (tip && !marker.tip) {
+        diag(name + ' kept — branch ' + branch + ' exists (tip ' + tip.slice(0, 8)
+          + ') but landed marker has no tip, so staleness cannot be verified'
+          + ' (branch name may have been reused). After verifying the work landed, re-run:'
+          + ' node .claude/hooks/worktree-create.js mark-landed ' + name);
+        continue;
+      }
+      if (tip && marker.tip && tip !== marker.tip) {
+        diag(name + ' kept — branch ' + branch + ' tip ' + tip.slice(0, 8)
+          + ' differs from landed-marker tip ' + String(marker.tip).slice(0, 8)
+          + ' (commits after landing were never verified)');
+        continue;
+      }
+      // Is this directory a FUNCTIONING standalone worktree? A husk whose .git
+      // link is gone resolves `--show-toplevel` upward to the PARENT repo (or
+      // errors on a pruned gitdir), so running `status --porcelain` there would
+      // report the parent repo's dirt — the wrong tree entirely (observed on 4
+      // real husks in KenazAI core, TASK_1826).
+      let topLevel = null;
+      try { topLevel = git(p, ['rev-parse', '--show-toplevel']); } catch { topLevel = null; }
+      const isOwnWorktree = topLevel !== null
+        && path.resolve(topLevel).replace(/\\/g, '/').toLowerCase() === rp;
+      let huskNote = '';
+      if (isOwnWorktree) {
+        // CONJUNCT: no uncommitted change outside the daemon-noise allowlist.
+        // Tracked source modifications and untracked deliverables (e.g.
+        // TASK_XXXX_HANDOFF.md) are real work → keep, naming the files.
+        let dirt = null;
+        try { dirt = classifyWorktreeDirt(p, noisePaths, repo); } catch { dirt = null; }
+        if (dirt === null) {
+          diag(name + ' kept — cannot read git status (unable to judge dirtiness)');
+          continue;
+        }
+        if (dirt.real.length > 0) {
+          const shown = dirt.real.slice(0, 5).join(', ')
+            + (dirt.real.length > 5 ? ' (+' + (dirt.real.length - 5) + ' more)' : '');
+          diag(name + ' kept — uncommitted non-daemon change(s): ' + shown);
+          continue;
+        }
+        if (dirt.noise.length > 0) {
+          diag(name + ' dirty only with daemon noise (' + dirt.noise.slice(0, 5).join(', ')
+            + (dirt.noise.length > 5 ? ', …' : '') + ') — noise does not block reclaim');
+        }
+      } else {
+        // Unlinked husk: no functioning .git link → a live agent cannot be
+        // using it (no git op works there). Dirtiness is unknowable, but the
+        // landed marker (checked above) asserts the work landed — reclaimable.
+        huskNote = ' [unlinked husk: '
+          + (topLevel === null ? 'broken .git link' : 'no own .git — resolves to parent repo') + ']';
+      }
+      // All conjuncts hold: landed marker present (tip unchanged), old enough,
+      // not keepPath, no real uncommitted work.
+      if (dryRun) {
+        diag(name + ' RECLAIMABLE (dry-run — not removed) — landed ' + marker.at
+          + ' via ' + (marker.via || 'unknown') + huskNote);
+        continue;
+      }
+      // TASK_1844: drop node_modules junctions/symlinks FIRST — Git for
+      // Windows recurses through junctions on delete and would empty the MAIN
+      // checkout's node_modules (measured; see unlinkNodeModulesLinks). This
+      // also covers pre-TASK_1844 worktrees where agents hand-built junctions.
+      unlinkNodeModulesLinks(p);
+      // Lock-resilient removal: try git remove --force, fall back to fs.rmSync
+      // with retries, then prune. If still locked -> log to stderr (observable)
+      // but never throw (GC must remain non-blocking).
+      let removed = false;
+      try {
+        git(repo, ['worktree', 'remove', '--force', p]);
+        removed = true;
+      } catch { /* git locked -- fall through to fs fallback */ }
+      if (!removed) {
+        try {
+          fs.rmSync(p, { recursive: true, force: true, maxRetries: 3, retryDelay: 200 });
+          try { git(repo, ['worktree', 'prune']); } catch { /* best-effort */ }
+          removed = true;
+        } catch {
+          // Still locked -- emit a single observable diagnostic line and skip.
+          notice(name + ' locked, skipped');
+        }
+      }
+      if (removed) {
+        try { git(repo, ['branch', '-D', branch]); } catch { /* already gone or unregistered */ }
+        reclaimedCount += 1;
+        notice(name + ' reclaimed — landed ' + marker.at + ' via ' + (marker.via || 'unknown') + huskNote);
+      }
+    }
+    }
+    // TASK_1876 (R4): ALWAYS report the marker-starved count — one line, stderr
+    // only (C1: hook-mode stdout carries exactly the worktree path, nothing
+    // else; that contract broke every dispatch once before, see the verbose
+    // comment above). Both values are reachable: 0 when every eligible tree
+    // has a marker, N when the recording duty is being missed — a signal
+    // pinned at one value would be no signal.
+    notice('marker-starved: ' + markerStarved
+      + ' worktree(s) kept only because no landed marker was recorded'
+      + (markerStarved > 0
+        ? ' — run: node .claude/hooks/worktree-create.js gc --review'
+        : ''));
+    if (!dryRun) {
+      try { git(repo, ['worktree', 'prune']); } catch { /* skip */ }
+    }
+    return { markerStarved, reclaimed: reclaimedCount };
+  } catch { /* GC is best-effort — never block creation */ }
+  // Unknown outcome (mid-sweep failure) is null, NOT a healthy-looking zero.
+  return null;
+}
+
+function emit(p) { process.stdout.write(String(p).replace(/\\/g, '/') + '\n'); process.exit(0); }
+function fail(msg) { process.stderr.write('[worktree-create] ' + msg + '\n'); process.exit(1); }
+
+/**
+ * Build a short worktree directory name using only the first 8 chars of the
+ * session UUID. Format: wt-<sid8>-<pid>  (e.g. wt-b19fbb34-23468).
+ * The pid suffix keeps concurrent subagents that share a session_id unique.
+ * Collision recovery is handled by the uniquify loop below.
+ */
+function makeWtName(sessionId, pid) {
+  const sid8 = sessionId.slice(0, 8);
+  return 'wt-' + sid8 + '-' + pid;
+}
+
+/**
+ * Sibling worktree base dir: <repoParent>/.kenaz-worktrees/<repoName>.
+ *
+ * TASK_1777: worktrees MUST live OUTSIDE the repo tree. The harness
+ * worktree-isolation guard denies Edit/Write on any path under the shared
+ * checkout; a worktree nested inside the repo has every one of its paths also
+ * under the shared checkout, so the guard denied ALL agent Edit/Write calls
+ * (agents were forced to fall back to Bash patch scripts). Sibling placement
+ * is the only layout the guard accepts. Bonus: shorter paths (MAX_PATH).
+ */
+function siblingWorktreeBase(repo) {
+  return path.join(path.dirname(repo), '.kenaz-worktrees', path.basename(repo));
+}
+
+// ── TASK_1844: node_modules provisioning ────────────────────────────────────
+// A fresh worktree is a bare checkout: zero node_modules. Every frontend-ish
+// dispatch then re-invented dependency access ad hoc (measured: 5-7 wasted tool
+// calls per task — locate main-repo tsc → link node_modules → verify junction →
+// retry). Fix: at creation time, link each of the main checkout's node_modules
+// dirs into the worktree so `npx tsc --noEmit` etc. work immediately.
+//
+// Mechanism: fs.symlinkSync with type 'junction' on Windows (junctions need NO
+// admin privilege, unlike real directory symlinks which EPERM for non-elevated
+// users), plain directory symlink on macOS/Linux (type arg is ignored there).
+// GEN-008/GEN-009: locations are discovered by scanning the repo (no hardcoded
+// package dirs), pure node + git CLI, no shell.
+//
+// Trade-off (accepted): all worktrees SHARE the main checkout's node_modules.
+// Read-only consumers (tsc, eslint, next lint) are safe under parallel
+// dispatch; an agent running `npm install` inside a worktree would mutate the
+// shared store — same exposure the previous ad-hoc junction workaround had,
+// and dispatch prompts forbid minute-scale installs anyway.
+//
+// Failure policy (requirement 5): a bare worktree beats a failed dispatch —
+// every error here is a stderr warning, never a hook failure, and NEVER
+// touches stdout (see emit() contract).
+
+// Descend at most this many directory levels below the repo root when looking
+// for node_modules (deepest real specimen: .specialist/Ansuz/tools/node_modules
+// at depth 3). Dot-dirs ARE descended (that specimen lives in one).
+const NODE_MODULES_SCAN_DEPTH = 3;
+// Never descend into these: VCS internals, dependency stores themselves, and
+// build outputs whose node_modules are artifacts (dashboard/.next/standalone,
+// target/debug/nextjs-server) that no in-worktree tool resolves against.
+const NODE_MODULES_SCAN_PRUNE = new Set([
+  '.git', 'node_modules', '.next', 'target', 'dist', 'build', 'out',
+  'vendor', 'worktrees', '.kenaz-worktrees',
+]);
+
+/**
+ * Return repo-relative paths ('' = root) of every directory that directly
+ * contains a node_modules dir, up to NODE_MODULES_SCAN_DEPTH levels deep.
+ */
+function findNodeModulesParents(repo) {
+  const found = [];
+  const walk = (dir, rel, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const ent of entries) {
+      if (!ent.isDirectory()) continue;
+      if (ent.name === 'node_modules') { found.push(rel); continue; }
+      if (NODE_MODULES_SCAN_PRUNE.has(ent.name)) continue;
+      if (depth + 1 <= NODE_MODULES_SCAN_DEPTH) {
+        walk(path.join(dir, ent.name), rel ? rel + '/' + ent.name : ent.name, depth + 1);
+      }
+    }
+  };
+  walk(repo, '', 0);
+  return found;
+}
+
+/**
+ * Ensure `relPath` (posix-style, relative to the worktree root) is git-ignored
+ * INSIDE the worktree — otherwise `git status` drowns in dependency files and
+ * `git add -A` sweeps the whole store into a commit (TASK_1819: 392-file
+ * incident). Repos that already ignore node_modules pass the check-ignore fast
+ * path; otherwise the pattern is appended to the worktree's PRIVATE exclude
+ * file (rev-parse --git-path info/exclude → .git/worktrees/<name>/info/exclude),
+ * which is per-worktree state and never touches tracked files or the shared
+ * .git/info/exclude. Throws on failure — caller skips creating that link.
+ */
+function ensureWorktreeIgnores(worktreePath, relPath) {
+  try {
+    execFileSync('git', ['-C', worktreePath, 'check-ignore', '-q', '--', relPath],
+      { stdio: ['ignore', 'ignore', 'ignore'] });
+    return; // exit 0 → already ignored (repo .gitignore covers it)
+  } catch { /* not ignored → add per-worktree exclude */ }
+  const gp = execFileSync('git', ['-C', worktreePath, 'rev-parse', '--git-path', 'info/exclude'],
+    { stdio: ['ignore', 'pipe', 'pipe'] }).toString().trim();
+  const excludeFile = path.isAbsolute(gp) ? gp : path.resolve(worktreePath, gp);
+  fs.mkdirSync(path.dirname(excludeFile), { recursive: true });
+  fs.appendFileSync(excludeFile, '/' + relPath + '/\n');
+}
+
+/**
+ * Unlink node_modules junctions/symlinks inside `root` (a worktree about to be
+ * removed). MUST run before any `git worktree remove`: Git for Windows RECURSES
+ * THROUGH junctions when deleting and EMPTIES THE LINK TARGET — measured
+ * 2026-08-13 (TASK_1844 control test): a junction into the source repo's
+ * node_modules + `git worktree remove --force` → source node_modules wiped.
+ * Node's fs.rmSync({recursive}) in contrast unlinks the reparse point without
+ * traversal (also measured, populated-target control). Only the link itself is
+ * removed here; a REAL node_modules directory (agent ran a package manager) is
+ * left for the normal removal path. Best-effort: never throws.
+ */
+function unlinkNodeModulesLinks(root) {
+  const walk = (dir, depth) => {
+    let entries;
+    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
+    for (const ent of entries) {
+      const p = path.join(dir, ent.name);
+      if (ent.name === 'node_modules') {
+        try {
+          if (fs.lstatSync(p).isSymbolicLink()) {
+            try { fs.unlinkSync(p); } catch { fs.rmdirSync(p); }
+          }
+        } catch { /* best-effort */ }
+        continue;
+      }
+      let isDir = false;
+      try { const st = fs.lstatSync(p); isDir = st.isDirectory() && !st.isSymbolicLink(); }
+      catch { continue; }
+      if (!isDir || NODE_MODULES_SCAN_PRUNE.has(ent.name)) continue;
+      if (depth + 1 <= NODE_MODULES_SCAN_DEPTH) walk(p, depth + 1);
+    }
+  };
+  walk(root, 0);
+}
+
+/**
+ * Link every discovered <repo>/<rel>/node_modules into the worktree at
+ * <worktree>/<rel>/node_modules. Per-entry and overall failures degrade to
+ * stderr warnings (requirement 5). A repo with no node_modules (requirement 4:
+ * non-frontend projects) yields an empty list and this is a no-op.
+ */
+function linkNodeModules(repo, worktreePath) {
+  const warn = (msg) => process.stderr.write('[worktree-create] node_modules: ' + msg + '\n');
+  let parents;
+  try { parents = findNodeModulesParents(repo); } catch (e) {
+    warn('scan failed (' + ((e && e.message) || 'unknown') + ') — worktree stays bare');
+    return;
+  }
+  for (const rel of parents) {
+    const target = path.join(repo, rel, 'node_modules');
+    const linkParent = rel ? path.join(worktreePath, rel) : worktreePath;
+    const linkPath = path.join(linkParent, 'node_modules');
+    try {
+      // Parent dir absent from the checkout = the package dir holds no tracked
+      // files (pure build artifact in the main repo) → nothing there needs deps.
+      if (!fs.existsSync(linkParent)) continue;
+      // Already present (including a broken pre-existing link) → leave it alone.
+      let exists = false;
+      try { fs.lstatSync(linkPath); exists = true; } catch { exists = false; }
+      if (exists) continue;
+      // Ignore-cover BEFORE linking: if we cannot guarantee git ignores the
+      // link, not linking is the safer state (see ensureWorktreeIgnores).
+      ensureWorktreeIgnores(worktreePath, rel ? rel + '/node_modules' : 'node_modules');
+      // Windows: 'junction' works without elevation (real dir symlinks EPERM
+      // for non-admin users). POSIX: the type argument is ignored by node and a
+      // normal directory symlink is created.
+      fs.symlinkSync(target, linkPath, process.platform === 'win32' ? 'junction' : 'dir');
+    } catch (e) {
+      warn('link skipped for "' + (rel || '.') + '": ' + ((e && e.message) || 'unknown'));
+    }
+  }
+}
+
+function main() {
+  // TASK_1866: hook mode MUST receive the harness's WorktreeCreate JSON object
+  // on stdin. Without this gate, main() fabricated a session id ('session'
+  // fallback) and silently built a wt-session-<pid> worktree whenever someone
+  // merely inspected the module via `node -e "require(...)"` — which IS the
+  // settings.json hook wiring, so require.main === undefined lands here.
+  // Observed three times on 2026-08-13 (TASK_1840 agent wt-session-7028, main
+  // thread ansuz-wt-session-11624, main thread --help wt-session-17644).
+  // The criterion is deliberately "stdin parses to a JSON object", NOT a TTY
+  // heuristic: the real harness always pipes the hook JSON, while under a test
+  // harness stdin may be neither a TTY nor carry data. The stdin JSON contract
+  // itself (file header) is unchanged.
+  let input = null;
+  try { input = JSON.parse(readStdin()); } catch { input = null; }
+  if (input === null || typeof input !== 'object' || Array.isArray(input)) {
+    fail('hook mode requires the WorktreeCreate JSON object on stdin '
+      + '({ session_id, cwd, ... }) — refusing to fabricate a session id and '
+      + 'create a worktree without one. If you only meant to inspect this '
+      + 'module, require() it from a script file: `node -e "require(...)"` '
+      + 'runs the REAL hook flow.');
+  }
+
+  const rawId = input.session_id || process.env.CLAUDE_SESSION_ID || 'session';
+  const sessionId = String(rawId).replace(/[^A-Za-z0-9_-]/g, '_').slice(0, 64);
+  const cwd = input.cwd || process.env.CLAUDE_PROJECT_DIR || process.cwd();
+
+  // Branch 1: session cwd is a git repo (dev / same-repo) → faithful passthrough.
+  // Branch 2: cwd not git (production) → redirect into the active project's repo.
+  let repo = isGitRepo(cwd) ? gitTopLevel(cwd) : null;
+  let worktreePath;
+
+  if (repo) {
+    // TASK_1777: ALWAYS place the worktree in the sibling base dir OUTSIDE the
+    // repo tree — never at the harness-proposed in-repo path (which would make
+    // the isolation guard deny every Edit/Write the agent attempts). The
+    // proposed basename is discarded too: the short synthesized name enforces
+    // the wt-<sid8>-<pid> naming contract that GC and branch naming rely on.
+    worktreePath = path.join(siblingWorktreeBase(repo), makeWtName(sessionId, process.pid));
+  } else {
+    repo = resolveTargetRepo();
+    if (!repo) {
+      fail('session cwd is not a git repo and no git target project is resolvable from '
+        + '~/.kenaz/projects.json (currentProjectId) — cannot create an isolated worktree');
+    }
+    // Ignore the proposed path (it points under the non-git cwd); place in the
+    // target repo's sibling worktree base (TASK_1777 — see siblingWorktreeBase).
+    // pid suffix: concurrent subagents in one session share session_id; the pid
+    // makes each hook invocation's synthesized path unique without a TOCTOU race.
+    worktreePath = path.join(siblingWorktreeBase(repo), makeWtName(sessionId, process.pid));
+  }
+
+  // Uniquify the path: concurrent subagents in one session share session_id,
+  // so the synthesized path (and sometimes the proposed one) collides. NEVER
+  // claim an existing path — the old `worktree remove --force` "idempotency"
+  // here destroyed live sibling agents' worktrees mid-task (TASK_1639). Suffix
+  // until free instead.
+  {
+    const base = worktreePath;
+    let n = 1;
+    while (fs.existsSync(worktreePath)) {
+      n += 1;
+      worktreePath = `${base}-${n}`;
+      if (n > 50) { worktreePath = `${base}-${Date.now().toString(36)}`; break; }
+    }
+  }
+
+  // Branch derives from the (unique) worktree dir name — NOT the bare session
+  // id — keeping gcStaleWorktrees' dirname-based derivation aligned with what
+  // we create. If a husk from a destroyed worktree left the branch behind,
+  // suffix rather than delete: never touch refs a live sibling might own.
+  const wtName = path.basename(worktreePath)
+    .replace(/^wt-/, '')
+    .replace(/[^A-Za-z0-9_-]/g, '_')
+    .slice(0, 64);
+  let branch = `ansuz-wt-${wtName}`;
+  {
+    const taken = (b) => {
+      try {
+        execFileSync('git', ['-C', repo, 'rev-parse', '--verify', '--quiet', 'refs/heads/' + b],
+          { stdio: ['ignore', 'pipe', 'ignore'] });
+        return true;
+      } catch { return false; }
+    };
+    const base = branch;
+    let n = 1;
+    while (taken(branch)) {
+      n += 1;
+      branch = `${base}-${n}`;
+      if (n > 50) { branch = `${base}-${Date.now().toString(36)}`; break; }
+    }
+  }
+
+  // Best-effort GC of stale, clean, merged sibling worktrees (compensates for the
+  // harness not reliably firing WorktreeRemove on subagent completion).
+  gcStaleWorktrees(repo, worktreePath);
+
+  try {
+    fs.mkdirSync(path.dirname(worktreePath), { recursive: true });
+    // Path and branch are guaranteed fresh above — no destructive cleanup here.
+    // (The old remove --force/branch -D "idempotency" at this spot destroyed
+    // concurrent siblings' live worktrees.) Prune only drops registrations
+    // whose directories are already gone.
+    try { git(repo, ['worktree', 'prune']); } catch { /* none */ }
+    git(repo, ['worktree', 'add', '-b', branch, worktreePath, 'HEAD']);
+  } catch (e) {
+    const detail = e && e.stderr ? e.stderr.toString().trim() : (e && e.message) || 'unknown error';
+
+    // Rollback (a): remove via git
+    try { git(repo, ['worktree', 'remove', '--force', worktreePath]); } catch { /* best-effort */ }
+    // Rollback (b): filesystem rm with retries
+    try {
+      fs.rmSync(worktreePath, { recursive: true, force: true, maxRetries: 3 });
+    } catch { /* best-effort */ }
+    // Rollback (c): prune stale registrations
+    try { git(repo, ['worktree', 'prune']); } catch { /* best-effort */ }
+    // Rollback (d): delete only the branch we created this invocation
+    try { git(repo, ['branch', '-D', branch]); } catch { /* may not exist if add never started */ }
+
+    fail('git worktree add failed in ' + repo + ': ' + detail);
+  }
+
+  // TASK_1844: make the main checkout's node_modules available inside the
+  // worktree (junction on Windows / symlink on POSIX). Strictly best-effort:
+  // any failure is a stderr warning and the hook still emits the path — a bare
+  // worktree beats a failed dispatch. Millisecond-scale (links only, never any
+  // package-manager install on this critical path).
+  try { linkNodeModules(repo, worktreePath); } catch (e) {
+    process.stderr.write('[worktree-create] node_modules provisioning failed: '
+      + ((e && e.message) || 'unknown') + '\n');
+  }
+
+  emit(worktreePath);
+}
+
+// ── TASK_1827: CLI subcommands ──────────────────────────────────────────────
+
+function _cliParseFlags(args) {
+  const flags = {};
+  const positional = [];
+  for (let i = 0; i < args.length; i++) {
+    const a = args[i];
+    if (a === '--dry-run') flags.dryRun = true;
+    else if (a === '--repo') flags.repo = args[++i];
+    else if (a === '--task') flags.task = args[++i];
+    else if (a === '--by') flags.by = args[++i];
+    else if (a === '--tip') flags.tip = args[++i];
+    else if (a === '--review') flags.review = true;   // TASK_1876
+    else if (a === '--approve') flags.approve = true; // TASK_1876
+    else if (a === '--all') flags.all = true;         // TASK_1876
+    else positional.push(a);
+  }
+  return { flags, positional };
+}
+
+function _cliResolveRepo(flags) {
+  const start = flags.repo || process.cwd();
+  if (!isGitRepo(start)) fail('not a git repo: ' + start + ' (use --repo <path>)');
+  return gitTopLevel(start);
+}
+
+/**
+ * mark-landed <worktree-name|worktree-path|branch> [--task TASK_X] [--repo <path>] [--by <who>] [--tip <sha>]
+ *
+ * The MANUAL merge path (TASK_1827): after the main thread lands a worktree's
+ * work via file-scoped checkout (where ancestry and patch-id both lie — see
+ * file header), it records the fact here. GC then treats the worktree as
+ * reclaimable once the remaining safety conjuncts hold.
+ */
+function cliMarkLanded(args) {
+  const { flags, positional } = _cliParseFlags(args);
+  const target = positional[0];
+  if (!target) {
+    fail('usage: mark-landed <wt-name|wt-path|branch> [--task TASK_X] [--repo <path>] [--by <who>] [--tip <sha>]');
+  }
+  const repo = _cliResolveRepo(flags);
+  // Resolve target → { worktree name, branch }. Accepts a worktree directory
+  // path, a worktree dir name (wt-* / task_*), or a branch (ansuz-wt-* / task/*).
+  let name = target;
+  try {
+    if (fs.existsSync(target) && fs.statSync(target).isDirectory()) name = path.basename(target);
+  } catch { /* treat as name/branch */ }
+  let branch = null;
+  let worktree = null;
+  if (name.startsWith('ansuz-wt-')) { branch = name; worktree = 'wt-' + name.slice('ansuz-wt-'.length); }
+  else if (name.startsWith('task/')) { branch = name; worktree = 'task_' + name.slice('task/'.length); }
+  else {
+    branch = deriveBranchForName(name);
+    worktree = branch ? name : null;
+  }
+  if (!branch) {
+    fail('cannot derive a branch from "' + target + '" — expected wt-*/task_* worktree name, '
+      + 'ansuz-wt-*/task/* branch, or a worktree directory path');
+  }
+  let tip = flags.tip || null;
+  if (!tip) {
+    try { tip = git(repo, ['rev-parse', '--verify', '--quiet', 'refs/heads/' + branch]); }
+    catch { tip = null; } // branch already deleted — marker still valid
+  }
+  // TASK_2087: idempotent like post-complete's recordLanding (git-merge.js) —
+  // if the ledger already has this branch at the same tip (both non-null),
+  // every unconditional verify-and-land re-run of this CLI would otherwise
+  // append a redundant duplicate line for the same landing event.
+  const existing = readLandedIndex(repo).byBranch.get(branch);
+  if (existing && existing.tip && tip && existing.tip === tip) {
+    process.stdout.write('[worktree-create] mark-landed: already recorded (via '
+      + existing.via + ', by ' + existing.by + ') — skipped\n');
+    process.exit(0);
+  }
+  const entry = appendLandedMarker(repo, {
+    branch,
+    worktree,
+    task: flags.task || null,
+    tip,
+    via: 'manual-cli',
+    by: flags.by || (function () { try { return os.userInfo().username; } catch { return null; } })(),
+  });
+  process.stdout.write('[worktree-create] mark-landed: recorded ' + JSON.stringify(entry) + '\n');
+  process.stdout.write('[worktree-create] ledger: ' + landedLedgerPath(repo).replace(/\\/g, '/') + '\n');
+  process.exit(0);
+}
+
+// ── TASK_1876: gc --review / --approve — the marker-starved backlog path ────
+// Measured 2026-08-21: 30 of 31 accumulated worktrees had no landed marker, so
+// the safe path (gc) could reclaim nothing, and the only path that COULD
+// reclaim them (manual deletion) bypasses unlinkNodeModulesLinks and empties
+// the main checkout's node_modules (happened that same day: 189 .bin shims
+// wiped, npm rebuild required). This flow gives humans an evidence-based batch
+// decision, then reclaims through the ONE existing GC path.
+//
+// Design boundary (TASK_1827, respected): none of the evidence below feeds the
+// GC's reclaim conjunction — the HUMAN's approval writes the marker (exactly
+// like mark-landed), and evidence can only make batch approval MORE
+// conservative (unique content ⇒ refuse), never reclaim without a marker.
+
+/** Marker-starved candidates exactly as the GC sees them (single source). */
+function _collectStarvedCandidates(repo) {
+  const starved = [];
+  // dryRun guarantees read-only enumeration; collectStarved receives every
+  // worktree kept at the missing-marker conjunct.
+  gcStaleWorktrees(repo, path.join(repo, '.__gc_cli_no_keep__'), { dryRun: true, collectStarved: starved });
+  return starved;
+}
+
+/** Look up a task's status directory across both task-system layouts. */
+function _findTaskStatus(repo, taskId) {
+  for (const base of ['.kenaz/tasks', '.collaboration/tasks']) {
+    const baseDir = path.join(repo, base);
+    let dirs;
+    try { dirs = fs.readdirSync(baseDir, { withFileTypes: true }); } catch { continue; }
+    for (const d of dirs) {
+      if (!d.isDirectory()) continue;
+      for (const variant of [taskId + '.yaml', taskId.toLowerCase() + '.yaml']) {
+        if (fs.existsSync(path.join(baseDir, d.name, variant))) return d.name;
+      }
+    }
+  }
+  return null;
+}
+
+/**
+ * Evidence for one marker-starved candidate. All git access is read-only.
+ * `unique` states:
+ *   'none'    — tip fully reachable from the user branch (trivially landed)
+ *   'landed'  — branch-unique commits exist, but every file they touched is
+ *               byte-identical between the two tips (the file-scoped-merge
+ *               signature: patch-id/ancestry lie, content already on main)
+ *   'unique'  — branch-touched file(s) whose content the user branch does NOT
+ *               have (uniqueFiles names them)
+ *   'unknown' — no resolvable tip (branch deleted + husk) or git failure
+ */
+function _gatherStarvedEvidence(repo, cand, noisePaths, userBranch) {
+  const ev = {
+    name: cand.name, branch: cand.branch, dir: cand.dir,
+    tip: null, tipSource: null, tasks: [], taskStatuses: {},
+    unique: 'unknown', uniqueFiles: [], uniqueCommits: 0,
+    dirt: 'unknown', dirtReal: null, approvable: false, reason: '',
+  };
+  // task_<id> family: the task id is in the name itself.
+  if (cand.name.startsWith('task_')) ev.tasks.push(cand.name.slice(5).toUpperCase());
+  try { ev.tip = git(repo, ['rev-parse', '--verify', '--quiet', 'refs/heads/' + cand.branch]); ev.tipSource = 'branch'; }
+  catch { ev.tip = null; }
+  // Functioning standalone worktree? (same discrimination the GC uses)
+  let topLevel = null;
+  try { topLevel = git(cand.dir, ['rev-parse', '--show-toplevel']); } catch { topLevel = null; }
+  const isOwn = topLevel !== null
+    && path.resolve(topLevel).replace(/\\/g, '/').toLowerCase()
+       === path.resolve(cand.dir).replace(/\\/g, '/').toLowerCase();
+  if (!ev.tip && isOwn) {
+    // Branch already deleted but the worktree still functions: its own HEAD is
+    // the recorded state of the work.
+    try { ev.tip = git(cand.dir, ['rev-parse', 'HEAD']); ev.tipSource = 'worktree-HEAD'; } catch { ev.tip = null; }
+  }
+  if (isOwn) {
+    try {
+      const dirt = classifyWorktreeDirt(cand.dir, noisePaths, repo);
+      ev.dirtReal = dirt.real.length > 0;
+      ev.dirt = dirt.real.length > 0
+        ? 'REAL uncommitted: ' + dirt.real.slice(0, 5).join(', ') + (dirt.real.length > 5 ? ' …' : '')
+        : (dirt.noise.length > 0 ? 'daemon-noise only' : 'clean');
+    } catch { ev.dirt = 'unreadable'; ev.dirtReal = null; }
+  } else {
+    ev.dirt = 'husk (no functioning .git link — cannot host live work)';
+    ev.dirtReal = false;
+  }
+  if (ev.tip && userBranch) {
+    try {
+      const logRaw = git(repo, ['log', '--pretty=format:%H%x09%s', userBranch + '..' + ev.tip, '--']);
+      const lines = logRaw ? logRaw.split('\n').filter((l) => l.trim()) : [];
+      ev.uniqueCommits = lines.length;
+      for (const l of lines) {
+        const m = l.match(/TASK_\d+/i);
+        if (m && !ev.tasks.includes(m[0].toUpperCase())) ev.tasks.push(m[0].toUpperCase());
+      }
+      if (lines.length === 0) {
+        ev.unique = 'none';
+      } else {
+        // Files touched by branch-unique commits ∩ files whose content differs
+        // between the two TIPS (two-dot diff — deliberately NOT patch-id or
+        // ancestry, which both lie under file-scoped merges). Intersection in
+        // JS avoids command-line length limits on large branches.
+        const touchedRaw = git(repo, ['log', '--name-only', '--pretty=format:', userBranch + '..' + ev.tip, '--']);
+        const touched = new Set((touchedRaw || '').split('\n').map((s) => s.trim()).filter(Boolean));
+        const diffRaw = git(repo, ['diff', '--name-only', userBranch, ev.tip]);
+        const differing = (diffRaw || '').split('\n').map((s) => s.trim()).filter(Boolean);
+        ev.uniqueFiles = differing.filter((f) => touched.has(f));
+        ev.unique = ev.uniqueFiles.length === 0 ? 'landed' : 'unique';
+      }
+    } catch { ev.unique = 'unknown'; }
+  }
+  for (const t of ev.tasks) ev.taskStatuses[t] = _findTaskStatus(repo, t);
+  // Verdict — evidence can only REFUSE, never auto-reclaim (see block comment).
+  if ((ev.unique === 'landed' || ev.unique === 'none') && ev.dirtReal === false) {
+    ev.approvable = true;
+    ev.reason = ev.unique === 'landed'
+      ? 'branch-touched files byte-identical to ' + userBranch
+      : 'all commits reachable from ' + userBranch;
+  } else if (ev.unique === 'unique') {
+    ev.reason = 'UNIQUE content ' + userBranch + ' does not have: '
+      + ev.uniqueFiles.slice(0, 5).join(', ') + (ev.uniqueFiles.length > 5 ? ' …' : '');
+  } else if (ev.dirtReal) {
+    ev.reason = 'uncommitted non-daemon changes (' + ev.dirt + ')';
+  } else {
+    ev.reason = 'content unverifiable (no resolvable tip) — after manual verification use: '
+      + 'node .claude/hooks/worktree-create.js mark-landed ' + cand.name;
+  }
+  return ev;
+}
+
+function _cliGcReviewOrApprove(repo, flags, positional) {
+  const out = (m) => process.stdout.write(m + '\n');
+  let userBranch = null;
+  try { userBranch = git(repo, ['rev-parse', '--abbrev-ref', 'HEAD']); } catch { userBranch = null; }
+  const noisePaths = loadGcNoisePaths(repo);
+  const candidates = _collectStarvedCandidates(repo);
+  if (candidates.length === 0) {
+    out('[worktree-create] gc review: no marker-starved worktrees — nothing to review.');
+    process.exit(0);
+  }
+  const evidence = candidates.map((c) => _gatherStarvedEvidence(repo, c, noisePaths, userBranch));
+  if (flags.review) {
+    out('[worktree-create] gc review: ' + evidence.length
+      + ' worktree(s) kept ONLY because no landed marker was recorded (vs ' + (userBranch || '?') + '):');
+    for (const ev of evidence) {
+      out('');
+      out('  ' + ev.name + '  branch=' + ev.branch
+        + (ev.tip ? ' tip=' + ev.tip.slice(0, 8) + ' (' + ev.tipSource + ')' : ' (branch deleted, no tip)'));
+      out('    task:     ' + (ev.tasks.length
+        ? ev.tasks.map((t) => t + (ev.taskStatuses[t] ? ' [' + ev.taskStatuses[t] + ']' : ' [not found]')).join(', ')
+        : 'none identifiable'));
+      out('    content:  ' + (ev.unique === 'landed' ? 'landed — ' + ev.reason
+        : ev.unique === 'none' ? 'landed — ' + ev.reason
+        : ev.unique === 'unique' ? ev.reason
+        : 'unknown — ' + ev.reason)
+        + (ev.uniqueCommits ? ' (' + ev.uniqueCommits + ' branch-unique commit(s))' : ''));
+      out('    worktree: ' + ev.dirt);
+      out('    batch-approvable: ' + (ev.approvable ? 'yes' : 'NO — ' + ev.reason));
+    }
+    const ok = evidence.filter((e) => e.approvable).map((e) => e.name);
+    out('');
+    out(ok.length
+      ? 'batch approval: node .claude/hooks/worktree-create.js gc --approve ' + ok.join(' ')
+        + '   (or --approve --all for every batch-approvable candidate)'
+      : 'no candidate qualifies for batch approval — resolve each individually (mark-landed after manual verification).');
+    process.exit(0);
+  }
+  // --approve
+  const byName = new Map(evidence.map((e) => [e.name, e]));
+  const requested = flags.all
+    ? evidence.filter((e) => e.approvable).map((e) => e.name)
+    : positional;
+  if (requested.length === 0) {
+    fail('gc --approve needs worktree names (or --all for every batch-approvable candidate); '
+      + 'run gc --review first');
+  }
+  const by = (function () { try { return os.userInfo().username; } catch { return null; } })();
+  let approved = 0;
+  let refused = 0;
+  for (const nm of requested) {
+    const ev = byName.get(nm);
+    if (!ev) { out('SKIPPED ' + nm + ' — not a marker-starved candidate (already marked, too fresh, or unknown)'); refused += 1; continue; }
+    if (!ev.approvable) { out('REFUSED ' + nm + ' — ' + ev.reason); refused += 1; continue; }
+    appendLandedMarker(repo, {
+      branch: ev.branch, worktree: ev.name, task: ev.tasks[0] || null,
+      tip: ev.tip, via: 'gc-batch-review', by,
+    });
+    out('APPROVED ' + nm + ' — marker written (' + ev.reason + ')');
+    approved += 1;
+  }
+  if (approved > 0) {
+    // Reclaim through the ONE existing path. gcStaleWorktrees runs
+    // unlinkNodeModulesLinks before every removal (TASK_1844: git recurses
+    // through junctions and empties the MAIN checkout's node_modules —
+    // measured twice). Batch reclaim must never grow a second deletion
+    // implementation (TASK_1839 drift lesson) — approval only writes markers.
+    gcStaleWorktrees(repo, path.join(repo, '.__gc_cli_no_keep__'), { verbose: true });
+  }
+  out('[worktree-create] gc approve: ' + approved + ' approved, ' + refused + ' refused/skipped');
+  process.exit(refused > 0 ? 2 : 0);
+}
+
+/**
+ * gc [--dry-run] [--review] [--approve <wt-name...>|--approve --all] [--repo <path>]
+ * Runs the same GC as the WorktreeCreate hook. --dry-run is strictly read-only:
+ * no removal, no branch -D, no `worktree prune`.
+ * --review / --approve (TASK_1876): evidence-based batch handling of worktrees
+ * kept only for a missing landed marker — see _cliGcReviewOrApprove.
+ */
+function cliGc(args) {
+  const { flags, positional } = _cliParseFlags(args);
+  const repo = _cliResolveRepo(flags);
+  if (flags.review || flags.approve) {
+    _cliGcReviewOrApprove(repo, flags, positional);
+    return; // unreachable (process.exit inside) — defensive
+  }
+  process.stderr.write('[worktree-create] gc: repo=' + repo.replace(/\\/g, '/')
+    + (flags.dryRun ? ' (DRY-RUN — read-only)' : '') + '\n');
+  // keepPath: a token that can never collide with a real worktree dir.
+  // verbose: the CLI is where the per-worktree "why was this kept" report belongs
+  // (hook mode stays quiet — see the comment on gcStaleWorktrees).
+  gcStaleWorktrees(repo, path.join(repo, '.__gc_cli_no_keep__'), { dryRun: !!flags.dryRun, verbose: true });
+  process.exit(0);
+}
+
+// Exports are unconditional: post-complete/git-merge.js requires this file for
+// appendLandedMarker, and it must get them no matter how we were started.
+module.exports = {
+  runHook: main,
+  GC_MIN_AGE_MS,
+  landedLedgerPath,
+  appendLandedMarker,
+  readLandedIndex,
+  deriveBranchForName,
+  loadGcNoisePaths,
+  isNoisePath,
+  isLandedProgressNote,
+  classifyWorktreeDirt,
+  gcStaleWorktrees,
+  siblingWorktreeBase,
+  findNodeModulesParents,
+  linkNodeModules,
+  unlinkNodeModulesLinks,
+};
+
+// Entry dispatch. Three distinct ways this file is started, and they must NOT be
+// collapsed — conflating them is what broke every worktree dispatch once the CLI
+// subcommands were added:
+//
+//   require.main === module   `node worktree-create.js [gc|mark-landed]` — CLI
+//   require.main === undefined `node -e "require(...)"` — how settings.json wires
+//                              the WorktreeCreate hook. There is no main module
+//                              under `node -e`. The hook flow MUST run here; the
+//                              earlier `require.main === module` guard sent this
+//                              case to the exports-only branch, so the process
+//                              exited 0 having written nothing, and the harness
+//                              reported "hook succeeded but returned no worktree
+//                              path" on every single dispatch.
+//   require.main === <other>   required as a library (post-complete/git-merge.js
+//                              for appendLandedMarker, tests). Exports only —
+//                              running main() here would create a worktree in the
+//                              middle of a merge.
+if (require.main === module) {
+  // TASK_1866: explicit subcommand whitelist. Anything unrecognized (--help,
+  // typos, stray flags) used to fall through to main(), which built a real
+  // worktree and exited 0 — a query for usage silently mutated the repo.
+  // Whitelist: 'mark-landed' | 'gc' | <no args>. Everything else → usage, exit 1.
+  //
+  // <no args> intentionally still runs main() (manual hook invocation, e.g.
+  // `echo <json> | node worktree-create.js` for testing): verified 2026-08-13
+  // that NO caller depends on argument-less CLI invocation (grepped
+  // .claude/settings.json, .formation/, .specialist/, dev/scripts/ — the hook
+  // is wired via `node -e "require(...)"`, git-merge.js requires this file as
+  // a library, and all documented CLI usage is gc/mark-landed). It is safe
+  // regardless: main()'s stdin gate rejects it with exit 1 unless a valid
+  // WorktreeCreate JSON object is piped in.
+  const sub = process.argv[2];
+  if (sub === 'mark-landed') cliMarkLanded(process.argv.slice(3));
+  else if (sub === 'gc') cliGc(process.argv.slice(3));
+  else if (sub === undefined) main();
+  else {
+    process.stderr.write(
+      '[worktree-create] unknown subcommand: ' + sub + '\n'
+      + 'usage:\n'
+      + '  node .claude/hooks/worktree-create.js mark-landed <wt-name|wt-path|branch> [--task TASK_X] [--repo <path>] [--by <who>] [--tip <sha>]\n'
+      + '  node .claude/hooks/worktree-create.js gc [--dry-run] [--repo <path>]\n'
+      + '  node .claude/hooks/worktree-create.js gc --review [--repo <path>]\n'
+      + '  node .claude/hooks/worktree-create.js gc --approve <wt-name...> | --approve --all [--repo <path>]\n'
+      + '  (no args: WorktreeCreate hook flow — requires the hook JSON object on stdin)\n');
+    process.exit(1);
+  }
+} else if (require.main === undefined) {
+  main(); // WorktreeCreate hook mode (stdin JSON contract unchanged; stdin gate inside main)
+}