msd-core/src/worktree-safety.cts

/**
 * Worktree Safety Policy Module
 *
 * Owns worktree-root resolution and non-destructive prune policy decisions.
 *
 * ADR-457 build-at-publish: the hand-written bin/lib/worktree-safety.cjs
 * collapsed to a TypeScript source of truth. Behaviour is preserved
 * byte-for-behaviour from the prior hand-written .cjs; only types are added.
 */

import fs from 'node:fs';
import path from 'node:path';
import { execGit as execGitSeam, posixNormalize, type SpawnResultOutput } from './shell-command-projection.cjs';

// Default timeout for worktree-related git subprocess calls.
// 10 s is generous enough for normal git operations on large repos while still
// providing a deterministic failure path when git stalls (locked index, hung
// remote, stalled NFS mount, etc.).  Callers can override via deps.timeout.
const DEFAULT_GIT_TIMEOUT_MS = 10000;

// #3021: accept the Workflow tool's worktree-wf_<runid>-<n> naming convention
// (claude-orchestration's isolation:"worktree" emission) alongside the
// existing agent-<id> / worktree-agent-<id> shapes.
const WORKTREE_AGENT_BRANCH_RE = /^((worktree-)?agent-|worktree-wf_)[A-Za-z0-9._/-]+$/;
const WORKTREE_AGENT_BRANCH_PATTERN = WORKTREE_AGENT_BRANCH_RE.source;

// GitResult now aliases the canonical SpawnResultOutput (shell-command-projection.cts),
// which already carries `timedOut` — kept as a local name since it is referenced
// below (gitResultOk).
type GitResult = SpawnResultOutput;

type ExecGitFn = typeof execGitSeam;

/**
 * Execute a git command via the shell-projection seam, applying the module's
 * default timeout. `timedOut` is now derived by the seam itself
 * (shell-command-projection.cts's `_spawnResult`), so this is a thin
 * passthrough. Tests inject mocks via deps.execGit using the same
 * (args, opts) shape — see worktree-safety-policy.test.cjs.
 */
function execGitDefault(args: string[], opts: { cwd?: string; env?: Record<string, string>; timeout?: number } = {}): GitResult {
  return execGitSeam(args, { ...opts, timeout: opts.timeout ?? DEFAULT_GIT_TIMEOUT_MS });
}

interface WorktreeBranchEntry {
  path: string;
  branch: string;
}

interface WorktreeEntry {
  path: string;
  branch: string | null;
}

function parseWorktreePorcelain(porcelain: string): WorktreeBranchEntry[] {
  return parseWorktreeEntries(porcelain).filter((entry) => entry.branch !== null).map((entry) => ({
    path: entry.path,
    branch: entry.branch!,
  }));
}

function parseWorktreeEntries(porcelain: string): WorktreeEntry[] {
  const entries: WorktreeEntry[] = [];
  const blocks = String(porcelain || '').split('\n\n').filter(Boolean);
  for (const block of blocks) {
    const lines = block.split('\n');
    const worktreeLine = lines.find((l) => l.startsWith('worktree '));
    if (!worktreeLine) continue;
    const worktreePath = worktreeLine.slice('worktree '.length).trim();
    if (!worktreePath) continue;
    const branchLine = lines.find((l) => l.startsWith('branch refs/heads/'));
    const branch = branchLine ? branchLine.slice('branch refs/heads/'.length).trim() : null;
    entries.push({ path: worktreePath, branch });
  }
  return entries;
}

function parseWorktreeListPaths(porcelain: string): string[] {
  return parseWorktreeEntries(porcelain).map((entry) => entry.path);
}

interface WorktreeListResult {
  ok: boolean;
  reason: string;
  porcelain: string;
  entries: WorktreeEntry[];
}

interface WorktreeDeps {
  execGit?: ExecGitFn;
  existsSync?: (p: string) => boolean;
  statSync?: (p: string) => fs.Stats;
  findSummaryFiles?: (worktreePath: string) => string[];
  readFileSync?: (p: string) => string;
  mkdirSync?: (d: string, o?: { recursive?: boolean }) => void;
  copyFileSync?: (src: string, dest: string) => void;
  isPidAlive?: (pid: number) => boolean;
  readDirSafe?: (dir: string) => string[] | null;
  readFileSafe?: (file: string) => string | null;
  mtimeSafe?: (file: string) => Date | null;
  reapMtimeGuardMs?: number;
  /** Injected current time in ms since epoch for deterministic tests (#1191). */
  nowMs?: number;
  parseWorktreePorcelain?: (porcelain: string) => WorktreeBranchEntry[];
}

function readWorktreeList(repoRoot: string, deps: WorktreeDeps = {}): WorktreeListResult {
  const execGit = deps.execGit || execGitDefault;
  const listResult = execGit(['worktree', 'list', '--porcelain'], { cwd: repoRoot });
  if (listResult.timedOut) {
    // AC2 / AC4: surface timeout as a distinct reason so callers can emit a
    // structured warning rather than silently treating the failure as a generic
    // list error (PRED.k302 — error-swallowing-empty-sentinel).
    return {
      ok: false,
      reason: 'git_timed_out',
      porcelain: '',
      entries: [],
    };
  }
  if (listResult.exitCode !== 0) {
    const stderr = String(listResult.stderr || '');
    return {
      ok: false,
      reason: /not a git repository|not a git repo/i.test(stderr)
        ? 'not_a_git_repo'
        : 'git_list_failed',
      porcelain: '',
      entries: [],
    };
  }

  return {
    ok: true,
    reason: 'ok',
    porcelain: listResult.stdout,
    entries: parseWorktreeEntries(listResult.stdout),
  };
}

interface WorktreeContextResult {
  effectiveRoot: string;
  mode: string;
  reason: string;
}

/**
 * Shortcut-free git-dir-vs-git-common-dir comparison: the actual primitive
 * that distinguishes a linked worktree from the main worktree.
 *
 * Deliberately factored out of `resolveWorktreeContext` (#3045). That
 * function's `has_local_planning` shortcut answers a DIFFERENT question ("is
 * there already a usable project root right here") and must NOT be consulted
 * for isolation detection: a git worktree created specifically to isolate an
 * executor is a full checkout, so it normally has its OWN checked-out
 * `.planning/` too. A caller that ran the shortcut first would read that
 * correctly-isolated worktree as `current_directory`/`has_local_planning` —
 * i.e. "not isolated" — a false positive that defeats the very isolation
 * guard that needs this check (see `hooks/gsd-cursor-subagent-start.js`,
 * #3045). `resolveWorktreeLinkage` always performs the real git-dir
 * comparison, independent of whether `.planning` exists locally.
 */
function resolveWorktreeLinkage(cwd: string, deps: WorktreeDeps = {}): WorktreeContextResult {
  const execGit = deps.execGit || execGitDefault;

  const gitDir = execGit(['rev-parse', '--git-dir'], { cwd });
  const commonDir = execGit(['rev-parse', '--git-common-dir'], { cwd });
  // A TIMEOUT means the command never completed — it is not evidence of "not a
  // git repository" (which completes fast, with a clean non-zero exit). Surface
  // it under a distinct reason so callers can tell "genuinely not a repo" apart
  // from "could not determine" (#3050). effectiveRoot still degrades to cwd
  // (there is no safer default without a resolved git-dir), but the reason is
  // no longer indistinguishable from the benign case.
  if (gitDir.timedOut || commonDir.timedOut) {
    return {
      effectiveRoot: cwd,
      mode: 'current_directory',
      reason: 'git_timed_out',
    };
  }
  if (gitDir.exitCode !== 0 || commonDir.exitCode !== 0) {
    return {
      effectiveRoot: cwd,
      mode: 'current_directory',
      reason: 'not_git_repo',
    };
  }

  const gitDirResolved = path.resolve(cwd, gitDir.stdout);
  const commonDirResolved = path.resolve(cwd, commonDir.stdout);
  if (gitDirResolved !== commonDirResolved) {
    return {
      effectiveRoot: path.dirname(commonDirResolved),
      mode: 'linked_worktree_root',
      reason: 'linked_worktree',
    };
  }

  return {
    effectiveRoot: cwd,
    mode: 'current_directory',
    reason: 'main_worktree',
  };
}

function resolveWorktreeContext(cwd: string, deps: WorktreeDeps = {}): WorktreeContextResult {
  const existsSync = deps.existsSync || fs.existsSync;

  // Local .planning takes precedence over linked-worktree remapping.
  if (existsSync(path.join(cwd, '.planning'))) {
    return {
      effectiveRoot: cwd,
      mode: 'current_directory',
      reason: 'has_local_planning',
    };
  }

  return resolveWorktreeLinkage(cwd, deps);
}

interface WorktreePrunePlan {
  repoRoot: string;
  action: string;
  reason: string;
  destructiveModeRequested: boolean;
}

function planWorktreePrune(repoRoot: string, options: { allowDestructive?: boolean } = {}, deps: WorktreeDeps = {}): WorktreePrunePlan {
  const parsePorcelain = deps.parseWorktreePorcelain || parseWorktreePorcelain;
  const destructiveModeRequested = Boolean(options.allowDestructive);
  const listed = readWorktreeList(repoRoot, deps);
  if (!listed.ok) {
    return {
      repoRoot,
      action: 'skip',
      reason: listed.reason,
      destructiveModeRequested,
    };
  }

  let worktrees: WorktreeBranchEntry[] = [];
  let parseFailed = false;
  try {
    worktrees = parsePorcelain(listed.porcelain);
  } catch {
    // Keep historical behavior: still run metadata prune when parsing fails.
    // #3050/#3057 (B6): but the reason must NOT collide with the
    // genuinely-empty-list case below — a parser that could not read the
    // porcelain output is not the same fact as "there are no worktrees", and
    // this plan drives a PRUNE, so conflating them means a prune decision made
    // on unread data would be indistinguishable from one made on real data.
    worktrees = [];
    parseFailed = true;
  }

  return {
    repoRoot,
    action: 'metadata_prune_only',
    reason: parseFailed
      ? 'parse_failed'
      : (worktrees.length === 0 ? 'no_worktrees' : 'worktrees_present'),
    destructiveModeRequested,
  };
}

interface PruneExecuteResult {
  ok: boolean;
  action: string;
  reason: string;
  timedOut?: boolean;
  pruned: unknown[];
}

function executeWorktreePrunePlan(plan: WorktreePrunePlan | null, deps: WorktreeDeps = {}): PruneExecuteResult {
  const execGit = deps.execGit || execGitDefault;
  if (!plan || plan.action === 'skip') {
    return {
      ok: false,
      action: plan ? plan.action : 'skip',
      reason: plan ? plan.reason : 'missing_plan',
      pruned: [],
    };
  }

  if (plan.action !== 'metadata_prune_only') {
    return {
      ok: false,
      action: plan.action,
      reason: 'unsupported_action',
      pruned: [],
    };
  }

  const result = execGit(['worktree', 'prune'], { cwd: plan.repoRoot });
  if (result.timedOut) {
    // AC4: surface timedOut as a first-class field so callers can log a structured WARNING rather
    // than silently ignoring it (PRED.k302 — error-swallowing-empty-sentinel).
    return {
      ok: false,
      action: plan.action,
      reason: 'git_timed_out',
      timedOut: true,
      pruned: [],
    };
  }
  return {
    ok: result.exitCode === 0,
    action: plan.action,
    reason: plan.reason,
    timedOut: false,
    pruned: [],
  };
}

interface LinkedWorktreePathsResult {
  ok: boolean;
  reason: string;
  paths: string[];
}

function listLinkedWorktreePaths(repoRoot: string, deps: WorktreeDeps = {}): LinkedWorktreePathsResult {
  const listed = readWorktreeList(repoRoot, deps);
  if (!listed.ok) {
    return {
      ok: false,
      reason: listed.reason,
      paths: [],
    };
  }

  const allPaths = listed.entries.map((entry) => entry.path);
  // git worktree list always includes the current/main worktree first.
  return {
    ok: true,
    reason: 'ok',
    paths: allPaths.slice(1),
  };
}

interface WorktreeFinding {
  kind: 'orphan' | 'stale' | 'unverified';
  path: string;
  ageMinutes?: number;
}

interface HealthResult {
  ok: boolean;
  reason: string;
  findings: WorktreeFinding[];
}

function inspectWorktreeHealth(repoRoot: string, options: { staleAfterMs?: number; nowMs?: number } = {}, deps: WorktreeDeps = {}): HealthResult {
  const inventory = snapshotWorktreeInventory(repoRoot, options, deps);
  if (!inventory.ok) {
    return {
      ok: false,
      reason: inventory.reason,
      findings: [],
    };
  }

  const findings: WorktreeFinding[] = [];
  for (const entry of inventory.entries) {
    if (entry.exists === 'absent') {
      findings.push({
        kind: 'orphan',
        path: entry.path,
      });
      continue;
    }
    if (entry.exists === 'unverified') {
      // #3050/#3057 (B5): existsSync confirmed the path is present but statSync
      // threw, so age/staleness could not be determined. This is neither
      // "orphan" (existsSync says it IS there) nor "healthy" (we never verified
      // it) — surface it as its own finding so a caller can't silently treat an
      // unverifiable worktree as confirmed present-and-not-stale.
      findings.push({
        kind: 'unverified',
        path: entry.path,
      });
      continue;
    }
    if (entry.isStale) {
      findings.push({
        kind: 'stale',
        path: entry.path,
        ageMinutes: entry.ageMinutes ?? undefined,
      });
    }
  }

  return {
    ok: true,
    reason: 'ok',
    findings,
  };
}

interface InventoryEntry {
  path: string;
  /**
   * Tri-state (#3050/#3057, B5): `'present'` = existsSync AND statSync both
   * succeeded (confirmed present, age known); `'absent'` = existsSync confirmed
   * the path is genuinely absent; `'unverified'` = existsSync confirmed presence
   * but statSync threw — presence could not be fully verified. `'unverified'`
   * MUST NOT be treated as `'present'`: a caller that could not check must not
   * report the worktree as confirmed present.
   */
  exists: 'present' | 'absent' | 'unverified';
  isStale: boolean;
  ageMinutes: number | null;
}

interface InventoryResult {
  ok: boolean;
  reason: string;
  entries: InventoryEntry[];
}

function snapshotWorktreeInventory(repoRoot: string, options: { staleAfterMs?: number; nowMs?: number } = {}, deps: WorktreeDeps = {}): InventoryResult {
  const existsSync = deps.existsSync || fs.existsSync;
  const statSync = deps.statSync || fs.statSync;
  const staleAfterMs = options.staleAfterMs ?? (60 * 60 * 1000);
  const nowMs = options.nowMs ?? Date.now();
  const listed = listLinkedWorktreePaths(repoRoot, { execGit: deps.execGit || execGitDefault });
  if (!listed.ok) {
    return {
      ok: false,
      reason: listed.reason,
      entries: [],
    };
  }

  const entries: InventoryEntry[] = [];
  for (const worktreePath of listed.paths) {
    let exists: 'present' | 'absent' | 'unverified' = 'absent';
    let isStale = false;
    let ageMinutes: number | null = null;

    if (!existsSync(worktreePath)) {
      entries.push({
        path: worktreePath,
        exists,
        isStale,
        ageMinutes,
      });
      continue;
    }

    try {
      const stat = statSync(worktreePath);
      exists = 'present';
      const ageMs = nowMs - stat.mtimeMs;
      ageMinutes = Math.round(ageMs / 60000);
      if (ageMs > staleAfterMs) {
        isStale = true;
      }
    } catch {
      // #3050/#3057 (B5): a statSync throw means presence could not be
      // verified — do NOT report exists:'present' (a guard that could not
      // check must not claim the worktree is confirmed present). Distinguish
      // from the genuinely-absent case above with a third state ('unverified')
      // rather than silently falling through to the pre-existing 'present' default.
      exists = 'unverified';
    }
    entries.push({
      path: worktreePath,
      exists,
      isStale,
      ageMinutes,
    });
  }

  return {
    ok: true,
    reason: 'ok',
    entries,
  };
}

interface CleanupManifestEntry {
  agent_id: string | null;
  worktree_path: string;
  branch: string;
  expected_base: string;
  allowed_bases?: string[];
  /** #2596: the plan's declared `files_modified`, when the recorder supplied it. Absent = unknown, never "declares nothing". */
  files_modified?: string[];
}

function normalizeCleanupManifestEntry(entry: unknown): CleanupManifestEntry | null {
  if (!entry || typeof entry !== 'object') return null;
  const e = entry as Record<string, unknown>;
  const worktreePath = typeof e.worktree_path === 'string'
    ? e.worktree_path
    : (typeof e.path === 'string' ? e.path : '');
  const branch = typeof e.branch === 'string' ? e.branch : '';
  const expectedBase = typeof e.expected_base === 'string' ? e.expected_base : '';
  if (!worktreePath || !branch || !expectedBase) return null;
  if (!WORKTREE_AGENT_BRANCH_RE.test(branch)) return null;
  const rawAllowedBases = Array.isArray(e.allowed_bases) ? e.allowed_bases : [];
  const allowedBases = Array.from(new Set(
    [expectedBase, ...rawAllowedBases.filter((base): base is string => typeof base === 'string' && base.length > 0)]
  ));
  // #2596: liberal in what we accept — non-array, or non-string / empty
  // elements, are dropped rather than coerced. An EMPTY result omits the field
  // entirely, so "declared nothing" is indistinguishable from "not recorded":
  // that ambiguity is already resolved as *unknown* by the per-plan submodule
  // gate's own `[ -z "$PLAN_FILES" ]` rule, and inventing a second rule here
  // would make an unrecorded plan look 100% out of scope.
  const filesModified = (Array.isArray(e.files_modified) ? e.files_modified : [])
    .filter((f): f is string => typeof f === 'string' && f.trim().length > 0);
  const normalized: CleanupManifestEntry = {
    agent_id: typeof e.agent_id === 'string' ? e.agent_id : null,
    worktree_path: worktreePath,
    branch,
    expected_base: expectedBase,
    allowed_bases: allowedBases,
  };
  if (filesModified.length > 0) normalized.files_modified = filesModified;
  return normalized;
}

interface NormalizedManifestResult {
  ok: boolean;
  reason: string;
  entries: CleanupManifestEntry[];
}

function normalizeCleanupManifest(manifest: unknown): NormalizedManifestResult {
  let parsed: unknown = manifest;
  if (typeof manifest === 'string') {
    try {
      parsed = JSON.parse(manifest);
    } catch {
      return { ok: false, reason: 'invalid_manifest_json', entries: [] };
    }
  }

  const p = parsed as Record<string, unknown> | unknown[] | null;
  const rawEntries = Array.isArray(p)
    ? p
    : (Array.isArray((p as Record<string, unknown>)?.worktrees) ? (p as Record<string, unknown>).worktrees as unknown[] : []);
  const seen = new Set<string>();
  const entries: CleanupManifestEntry[] = [];
  for (const raw of rawEntries) {
    const entry = normalizeCleanupManifestEntry(raw);
    if (!entry) continue;
    const key = `${entry.worktree_path}\0${entry.branch}`;
    if (seen.has(key)) continue;
    seen.add(key);
    entries.push(entry);
  }

  if (entries.length === 0) {
    return { ok: false, reason: 'empty_manifest', entries: [] };
  }

  return { ok: true, reason: 'ok', entries };
}

interface WaveCleanupPlan {
  ok: boolean;
  repoRoot: string;
  action: string;
  discovery: string;
  reason: string;
  entries: CleanupManifestEntry[];
}

function planWorktreeWaveCleanup(repoRoot: string, manifest: unknown): WaveCleanupPlan {
  const normalized = normalizeCleanupManifest(manifest);
  if (!normalized.ok) {
    return {
      ok: false,
      repoRoot,
      action: 'skip',
      discovery: 'manifest',
      reason: normalized.reason,
      entries: [],
    };
  }

  return {
    ok: true,
    repoRoot,
    action: 'cleanup_wave',
    discovery: 'manifest',
    reason: 'manifest_entries_present',
    entries: normalized.entries,
  };
}

function gitResultOk(result: GitResult | null | undefined): boolean {
  return !!(result && result.exitCode === 0 && !result.timedOut);
}

/**
 * #2852: after a failed `git merge` + a `git merge --abort` attempt, determine
 * whether `repoRoot` is STILL mid-merge — the only condition that genuinely
 * invalidates the rest of a cleanup wave.
 *
 * `git merge --abort`'s own exit code is NOT a reliable signal here: git refuses
 * many merges (e.g. "your local changes to the following files would be
 * overwritten by merge") WITHOUT ever creating a `MERGE_HEAD`, in which case
 * `repoRoot`'s tree was never touched and `git merge --abort` correctly fails
 * with "fatal: There is no merge to abort (MERGE_HEAD missing)?" — a SAFE
 * outcome, not a broken one. Trusting that exit code alone would misclassify an
 * ordinary per-entry merge failure as a repo-level one and strand the rest of
 * the wave (caught in review).
 *
 * Checked directly via `git rev-parse --verify -q MERGE_HEAD` against the git
 * ref itself rather than the filesystem: exit 0 means a merge is genuinely still
 * in progress (unrecoverable — halt); exit 1 (the ref simply doesn't exist) means
 * repoRoot is clean, whether because no merge state was ever entered or because
 * abort successfully cleared it (safe — isolate and continue). Anything else
 * (a timeout, or an unexpected git error) is treated conservatively as "still
 * mid-merge" — degrade to the safe/halting answer rather than throw or guess.
 */
function repoRootStillMidMerge(execGit: ExecGitFn, repoRoot: string): boolean {
  const check = execGit(['rev-parse', '--verify', '-q', 'MERGE_HEAD'], { cwd: repoRoot });
  if (check.timedOut) return true; // fail closed — cannot confirm safety
  if (check.exitCode === 0) return true; // MERGE_HEAD exists — genuinely still mid-merge
  if (check.exitCode === 1) return false; // ref not found — repoRoot is not mid-merge
  return true; // any other exit code (e.g. a fatal git error) — fail closed
}

// #2596: the single definition of "this file is an executor-written SUMMARY
// artifact". Shared by `defaultFindSummaryFiles` (which walks for them to
// rescue) and the scope advisory below (which must never flag them) — a plan's
// declared `files_modified` never lists a SUMMARY, because the executor writes
// it by orchestration contract, so a second copy of this rule would make the
// advisory fire on essentially every wave.
const SUMMARY_ARTIFACT_DIR = '.planning';
const SUMMARY_ARTIFACT_SUFFIX = 'SUMMARY.md';

/**
 * Normalize one path for scope comparison. Applied to BOTH sides so a declared
 * path and a git-reported path meet in the same shape: backslashes become
 * slashes unconditionally (a backslash path is not a Windows-only input),
 * a leading `./` and any trailing `/` are stripped. This is the single
 * normalizer shared by the SUMMARY-artifact predicate and the scope advisory,
 * so the two can never disagree about what `./a\b/` means.
 */
function normalizeScopePath(raw: string): string {
  return String(raw || '')
    .replace(/\\/g, '/')
    .trim()
    .replace(/^\.\//, '')
    .replace(/\/+$/, '');
}

/**
 * True when a worktree-relative path is a SUMMARY artifact. Input may use
 * either separator; normalization to POSIX is unconditional (backslash paths
 * reach Linux too).
 */
function isSummaryArtifactRelPath(relPath: string): boolean {
  const normalized = normalizeScopePath(relPath);
  return normalized.startsWith(`${SUMMARY_ARTIFACT_DIR}/`)
    && normalized.endsWith(SUMMARY_ARTIFACT_SUFFIX);
}

/**
 * Walk <worktreePath>/.planning/ recursively and collect absolute paths of
 * all files whose names match *SUMMARY.md.  Returns [] when the directory
 * does not exist or cannot be read.
 *
 * Mirrors the shell fallback in quick.md (#2296, #2070, #2838):
 *   find "$WT/.planning" -name "*SUMMARY.md"
 */
function defaultFindSummaryFiles(worktreePath: string): string[] {
  const planningDir = path.join(worktreePath, SUMMARY_ARTIFACT_DIR);
  const results: string[] = [];
  function walk(dir: string): void {
    let entries: fs.Dirent[];
    try { entries = fs.readdirSync(dir, { withFileTypes: true }); } catch { return; }
    for (const entry of entries) {
      const full = path.join(dir, entry.name);
      if (entry.isDirectory()) {
        walk(full);
      } else if (entry.isFile() && entry.name.endsWith(SUMMARY_ARTIFACT_SUFFIX)) {
        results.push(full);
      }
    }
  }
  walk(planningDir);
  return results;
}

/**
 * Rescue uncommitted SUMMARY.md artifacts from a worktree into the main repo
 * tree before the dirty-state check.  Mirrors the shell-fallback rescue block
 * in quick.md (lines 878–891, #2296/#2070/#2838).
 *
 * For each *SUMMARY.md found under <worktreePath>/.planning/:
 *   - compute relative path from worktree root  → .planning/<id>-SUMMARY.md
 *   - if the file is ALREADY COMMITTED on the worktree branch
 *     (`git cat-file -e HEAD:<relPath>` returns exit 0), skip the copy entirely:
 *     the merge will carry it naturally and copying it as an untracked file would
 *     cause a "untracked working tree files would be overwritten by merge" collision.
 *     On timeout or fatal exit (128) the rescue is also skipped (fail-closed).
 *     (#706 — execute-phase committed-SUMMARY contract)
 *   - destination = <repoRoot>/<relPath>
 *   - copy when dest is absent or content differs
 *
 * Returns `{ rescuedRelPaths, failures }`:
 *   - `rescuedRelPaths`: Set of worktree-relative paths that were successfully rescued
 *     (copy not needed because dest already matches, or copy succeeded).  Only paths
 *     where the rescue genuinely succeeded are included so the dirty-block filter does
 *     not suppress paths that were silently lost.
 *   - `failures`: array of `{ relPath, error }` for any path where mkdirSync or
 *     copyFileSync threw.  A read failure during content comparison is NOT a rescue
 *     failure — it sets needsCopy=true and the copy is attempted normally.
 */
function rescueSummaryArtifacts(
  worktreePath: string,
  repoRoot: string,
  deps: WorktreeDeps,
): { rescuedRelPaths: Set<string>; failures: Array<{ relPath: string; error: string }> } {
  const execGit = deps.execGit || execGitDefault;
  const findSummaryFiles = deps.findSummaryFiles || defaultFindSummaryFiles;
  const existsSync = deps.existsSync || fs.existsSync;
  const readFileSync = deps.readFileSync || ((p: string) => fs.readFileSync(p, 'utf8'));
  const mkdirSync = deps.mkdirSync || ((d: string, o?: { recursive?: boolean }) => fs.mkdirSync(d, o));
  const copyFileSync = deps.copyFileSync || fs.copyFileSync;

  const summaryPaths = findSummaryFiles(worktreePath);
  const rescuedRelPaths = new Set<string>();
  const failures: Array<{ relPath: string; error: string }> = [];

  for (const absPath of summaryPaths) {
    // relPath is the path relative to the worktree root (e.g. ".planning/q1-SUMMARY.md")
    // Normalize to forward slashes so the Set comparison against `git status --porcelain`
    // output works on Windows too (git always emits forward slashes in porcelain output).
    const relPath = posixNormalize(absPath.slice(worktreePath.length).replace(/^[/\\]/, ''));

    // #706: skip rescue when the SUMMARY is already committed on the branch.
    // Use `git cat-file -e HEAD:<relPath>` (not `ls-files --error-unmatch`) so
    // the check is against the committed tree, not the index.  ls-files also
    // matches staged-but-uncommitted files, which would skip rescue when the
    // file is staged but not yet committed — the merge wouldn't carry it, and
    // the executor's content could be lost.  cat-file -e HEAD:<path> returns
    // exit 0 only when the object exists in the committed HEAD tree.
    //
    // #2556: rescue whenever the object is NOT confirmed committed (any non-zero
    // exit). `git cat-file -e` returns 128 — NOT 1 — for an absent path (the
    // normal uncommitted-SUMMARY state), so the previous `!== 1` check never
    // rescued and the untracked file was silently discarded by `worktree remove
    // --force`. Data safety wins: an un-rescued untracked SUMMARY is lost, while
    // a spurious rescue is usually a no-op — the destination check below skips the
    // copy when the main tree already holds identical content (which is also what
    // guards the #706 merge collision). A divergent dest is overwritten, but only
    // uncommitted main-tree content could be lost (committed content is git-recoverable).
    const catFileResult = execGit(['-C', worktreePath, 'cat-file', '-e', `HEAD:${relPath}`], { cwd: repoRoot });
    if (catFileResult.exitCode === 0) {
      // exit 0 → the SUMMARY is committed on HEAD; the merge will carry it, so skip rescue.
      continue;
    }

    const dest = path.join(repoRoot, relPath);
    let needsCopy = !existsSync(dest);
    if (!needsCopy) {
      try {
        const srcContent = readFileSync(absPath);
        const destContent = readFileSync(dest);
        needsCopy = srcContent !== destContent;
      } catch {
        // Read failure during comparison is not a rescue failure — force a copy attempt.
        needsCopy = true;
      }
    }
    if (needsCopy) {
      try {
        mkdirSync(path.dirname(dest), { recursive: true });
        copyFileSync(absPath, dest);
        // Copy succeeded — the SUMMARY is now safe in the main tree.
        rescuedRelPaths.add(relPath);
      } catch (err) {
        // Write failure: the SUMMARY was NOT rescued.  Record it so the caller can
        // block cleanup instead of silently losing data.
        failures.push({ relPath, error: (err as Error).message });
      }
    } else {
      // dest already exists with identical content — SUMMARY is already safe.
      rescuedRelPaths.add(relPath);
    }
  }

  return { rescuedRelPaths, failures };
}

/**
 * #2596: advisory codes emitted by the wave-cleanup gauntlet. Frozen and
 * exported so tests assert on a code rather than on rendered prose (this repo
 * forbids raw-text matching on test output).
 */
const WAVE_CLEANUP_WARNING = Object.freeze({
  /** A committed path fell outside the plan's declared `files_modified`. */
  SCOPE_OUT_OF_DECLARED: 'scope_out_of_declared',
  /** The scope diff could not be computed, so conformance is unknown. */
  SCOPE_CHECK_UNAVAILABLE: 'scope_check_unavailable',
});

interface WaveCleanupWarning {
  code: string;
  branch: string;
  /** The offending path; null when the check itself could not run. */
  path: string | null;
}

/**
 * The literal directory prefix a declared path covers, or `null` when the
 * pattern begins with a glob metacharacter and therefore has no usable prefix.
 *
 * Deliberately literal-prefix only — NOT a glob engine. A hand-rolled
 * `**`/`*`/`?` matcher inside a worktree-lifecycle module is an informal,
 * undocumented pattern language living where no language belongs, and this
 * repo forbids external deps in core. The submodule-intersection gate
 * (`workflows/execute-phase/steps/per-plan-worktree-gate.md`) already ships
 * exactly this glob-prefix rule; reusing it beats inventing a second one.
 *
 * `null` (no literal prefix, e.g. `*.md`) means "matches everything": for an
 * ADVISORY, a false alarm costs more than a miss, so the ambiguous case
 * suppresses rather than shouts.
 */
function declaredScopePrefix(declared: string): string | null {
  const globAt = declared.search(/[*?[]/);
  if (globAt < 0) return declared;
  const literal = declared.slice(0, globAt).replace(/\/+$/, '');
  return literal.length > 0 ? literal : null;
}

/**
 * #2596: compare a branch's actual committed paths against the plan's declared
 * scope. Pure — no git, no IO. Returns one warning per out-of-scope path, in
 * the order the paths were given. Returns [] when nothing usable was declared:
 * absence of data is not evidence of over-reach.
 */
function planWaveScopeConformance(
  changedPaths: unknown,
  declaredFiles: unknown,
  branch: string,
): WaveCleanupWarning[] {
  if (!Array.isArray(declaredFiles)) return [];
  const prefixes: Array<string | null> = [];
  for (const declared of declaredFiles) {
    if (typeof declared !== 'string') continue;
    const normalized = normalizeScopePath(declared);
    if (!normalized) continue;
    prefixes.push(declaredScopePrefix(normalized));
  }
  if (prefixes.length === 0) return [];

  const warnings: WaveCleanupWarning[] = [];
  const seen = new Set<string>();
  for (const raw of Array.isArray(changedPaths) ? changedPaths : []) {
    if (typeof raw !== 'string') continue;
    const changed = normalizeScopePath(raw);
    if (!changed || seen.has(changed)) continue;
    seen.add(changed);
    if (isSummaryArtifactRelPath(changed)) continue;
    const covered = prefixes.some((prefix) => (
      prefix === null || changed === prefix || changed.startsWith(`${prefix}/`)
    ));
    if (covered) continue;
    warnings.push({ code: WAVE_CLEANUP_WARNING.SCOPE_OUT_OF_DECLARED, branch, path: changed });
  }
  return warnings;
}

interface WaveCleanupEntryResult extends CleanupManifestEntry {
  status: string;
  reason: string | null;
  stderr: string;
  warnings: WaveCleanupWarning[];
}

interface WaveCleanupResult {
  ok: boolean;
  action: string;
  reason: string;
  entries: WaveCleanupEntryResult[];
  pending: CleanupManifestEntry[];
  warnings: WaveCleanupWarning[];
}

function executeWorktreeWaveCleanupPlan(plan: WaveCleanupPlan | null, deps: WorktreeDeps = {}): WaveCleanupResult {
  const execGit = deps.execGit || execGitDefault;
  const entries = Array.isArray(plan?.entries) ? plan.entries : [];
  if (!plan || plan.action !== 'cleanup_wave' || entries.length === 0) {
    return {
      ok: false,
      action: plan ? plan.action : 'skip',
      reason: plan ? (plan.reason || 'missing_entries') : 'missing_plan',
      entries: [],
      pending: entries,
      warnings: [],
    };
  }

  const results: WaveCleanupEntryResult[] = [];
  const pending: CleanupManifestEntry[] = [];
  const allWarnings: WaveCleanupWarning[] = [];
  let ok = true;

  // #2852: every per-entry failure site marks the SAME shape — status='blocked',
  // a reason code, the captured stderr, push to results, flip the overall `ok`
  // flag — and then either `continue` (isolate, the default) or, for the one
  // repo-level-failure carve-out, `break`. Factored out so the 8 call sites below
  // don't repeat the assembly; each site still owns its own control-flow decision.
  function blockEntry(result: WaveCleanupEntryResult, reason: string, stderr: string): void {
    result.status = 'blocked';
    result.reason = reason;
    result.stderr = stderr;
    results.push(result);
    ok = false;
  }

  for (let i = 0; i < entries.length; i += 1) {
    const entry = entries[i];
    const result: WaveCleanupEntryResult = {
      ...entry,
      status: 'pending',
      reason: null,
      stderr: '',
      warnings: [],
    };

    const branchCheck = execGit(['-C', entry.worktree_path, 'rev-parse', '--abbrev-ref', 'HEAD'], { cwd: plan.repoRoot });
    if (!gitResultOk(branchCheck) || branchCheck.stdout.trim() !== entry.branch) {
      blockEntry(result, 'branch_mismatch', branchCheck?.stderr || '');
      // #2852: isolate — this entry's problem does not touch repoRoot's git state,
      // so every remaining entry is still independently evaluated.
      continue;
    }

    const mergeBase = execGit(['merge-base', 'HEAD', entry.branch], { cwd: plan.repoRoot });
    const allowedBases = Array.isArray(entry.allowed_bases) && entry.allowed_bases.length > 0
      ? entry.allowed_bases
      : [entry.expected_base];
    if (!gitResultOk(mergeBase) || !allowedBases.includes(mergeBase.stdout.trim())) {
      blockEntry(result, 'base_mismatch', mergeBase?.stderr || '');
      continue; // #2852: isolate
    }

    const deletions = execGit(['diff', '--diff-filter=D', '--name-only', `HEAD...${entry.branch}`], { cwd: plan.repoRoot });
    if (!gitResultOk(deletions)) {
      blockEntry(result, 'deletion_check_failed', deletions?.stderr || '');
      continue; // #2852: isolate
    }
    if (deletions.stdout) {
      // Unconditional: any deletion in this entry's branch blocks THIS entry. Whether
      // that guard should have an opt-in for intentional deletions is a deferred
      // product decision (issue #2852's own triage scoped it out — tracked in #3003);
      // this fix only isolates the block to this one entry (#2852) instead of aborting
      // the rest of the wave, same as every other block reason below.
      blockEntry(result, 'branch_contains_deletions', deletions.stdout);
      continue; // #2852: isolate
    }

    // #2596: advisory scope conformance — does the branch's ACTUAL committed
    // diff stay inside the scope the plan declared? Gated on a declared scope
    // being present: with nothing declared there is nothing to compare, so no
    // git subprocess is spent at all (and every pre-#2596 fixture, none of
    // which declares one, issues exactly the git calls it always did).
    //
    // ADVISORY ONLY. Unlike the deletions check above, a finding here does NOT
    // call blockEntry and does NOT touch `ok` — the merge proceeds. Promotion
    // to a hard gate is a separate, disclosed change.
    if (Array.isArray(entry.files_modified) && entry.files_modified.length > 0) {
      const scopeDiff = execGit(['diff', '--name-only', `HEAD...${entry.branch}`], { cwd: plan.repoRoot });
      const scopeWarnings: WaveCleanupWarning[] = !gitResultOk(scopeDiff)
        // A broken advisory must never become a gate: record that conformance
        // is unknown rather than blocking (or, worse, silently passing).
        ? [{ code: WAVE_CLEANUP_WARNING.SCOPE_CHECK_UNAVAILABLE, branch: entry.branch, path: null }]
        : planWaveScopeConformance((scopeDiff.stdout || '').split('\n'), entry.files_modified, entry.branch);
      result.warnings.push(...scopeWarnings);
      allWarnings.push(...scopeWarnings);
    }

    // Safety net: rescue uncommitted SUMMARY.md artifacts before the dirty check.
    // The executor leaves <quick_id>-SUMMARY.md uncommitted by contract — the
    // orchestrator commits it.  Mirrors quick.md shell fallback (#2296, #2070, #2838, #3804).
    const { rescuedRelPaths, failures: rescueFailures } = rescueSummaryArtifacts(entry.worktree_path, plan.repoRoot, deps);
    if (rescueFailures.length > 0) {
      blockEntry(result, 'summary_rescue_failed', rescueFailures.map((f) => `${f.relPath}: ${f.error}`).join('; '));
      continue; // #2852: isolate
    }

    const worktreeStatus = execGit(['-C', entry.worktree_path, 'status', '--porcelain', '--untracked-files=all'], { cwd: plan.repoRoot });
    if (!gitResultOk(worktreeStatus)) {
      blockEntry(result, 'worktree_dirty', worktreeStatus?.stderr || '');
      continue; // #2852: isolate
    }
    // Filter rescued SUMMARY paths out of the porcelain output before deciding dirty.
    // A line like "?? .planning/q1-SUMMARY.md" should not block when the SUMMARY
    // has already been rescued into the main tree.
    const dirtyLines = (worktreeStatus.stdout || '')
      .split('\n')
      .filter((line) => {
        if (!line.trim()) return false;
        // porcelain v1 format: "XY path" (3-char prefix + space + path)
        const filePath = line.slice(3).trim();
        return !rescuedRelPaths.has(filePath);
      });
    if (dirtyLines.length > 0) {
      blockEntry(result, 'worktree_dirty', dirtyLines.join('\n'));
      continue; // #2852: isolate
    }

    const merge = execGit(['merge', entry.branch, '--no-ff', '--no-edit', '-m', `chore: merge executor worktree (${entry.branch})`], { cwd: plan.repoRoot });
    if (!gitResultOk(merge)) {
      blockEntry(result, 'merge_failed', merge?.stderr || merge?.stdout || '');
      // #2852: a failed --no-ff merge MIGHT leave repoRoot itself mid-merge
      // (MERGE_HEAD set, conflict markers in the tree) — unlike every other block
      // reason above, that specific state is NOT scoped to this one entry: a second
      // `git merge` cannot even start while one is in progress, so every remaining
      // entry would be corrupted by it. But git also refuses many merges WITHOUT ever
      // entering a merge state (e.g. "your local changes would be overwritten by
      // merge") — in that case repoRoot's tree was never touched and this failure is
      // scoped to this entry, same as everything else. Attempt the abort as a
      // best-effort cleanup, then check repoRoot's ACTUAL state directly — not
      // `git merge --abort`'s own exit code, which fails "There is no merge to abort"
      // in the safe case too and would misclassify it as unrecoverable (caught in
      // review). Only a repo genuinely still mid-merge afterward legitimately halts
      // the rest of the wave (the brief's "infrastructure-level failure" carve-out).
      execGit(['merge', '--abort'], { cwd: plan.repoRoot });
      if (repoRootStillMidMerge(execGit, plan.repoRoot)) {
        pending.push(...entries.slice(i + 1));
        break;
      }
      continue; // #2852: isolate — repoRoot is not (or no longer) mid-merge
    }

    let remove = execGit(['worktree', 'remove', entry.worktree_path, '--force'], { cwd: plan.repoRoot });
    if (!gitResultOk(remove)) {
      // Locked worktrees require unlock before remove (or --force --force).
      // Attempt: git worktree unlock <path> (ignore failure — already unlocked is ok)
      // then retry git worktree remove --force.  (#3707)
      execGit(['worktree', 'unlock', entry.worktree_path], { cwd: plan.repoRoot });
      remove = execGit(['worktree', 'remove', entry.worktree_path, '--force'], { cwd: plan.repoRoot });
    }
    if (!gitResultOk(remove)) {
      blockEntry(result, 'worktree_remove_failed', remove?.stderr || '');
      // #2852: isolate — the merge already landed on repoRoot; only this entry's
      // worktree/branch teardown is affected.
      continue;
    }

    const branchDelete = execGit(['branch', '-D', entry.branch], { cwd: plan.repoRoot });
    if (!gitResultOk(branchDelete)) {
      result.status = 'warning';
      result.reason = 'branch_delete_failed';
      result.stderr = branchDelete?.stderr || '';
      ok = false;
    } else {
      result.status = 'merged_removed';
      result.reason = 'ok';
    }
    results.push(result);
  }

  return {
    ok,
    action: plan.action,
    reason: ok ? 'ok' : 'cleanup_blocked',
    entries: results,
    pending,
    warnings: allWarnings,
  };
}

function cmdWorktreeCleanupWave(cwd: string, args: string[] = []): void {
  const manifestFlagIndex = args.indexOf('--manifest');
  const manifestPath = manifestFlagIndex >= 0 ? args[manifestFlagIndex + 1] : '';
  if (!manifestPath) {
    process.stderr.write('Usage: worktree cleanup-wave --manifest <path>\n');
    process.exitCode = 2;
    return;
  }

  let manifest: string;
  try {
    manifest = fs.readFileSync(path.resolve(cwd, manifestPath), 'utf8');
  } catch (err) {
    process.stdout.write(`${JSON.stringify({
      ok: false,
      reason: 'manifest_read_failed',
      error: (err as Error).message,
    }, null, 2)}\n`);
    process.exitCode = 1;
    return;
  }

  const plan = planWorktreeWaveCleanup(cwd, manifest);
  const result = executeWorktreeWaveCleanupPlan(plan);
  const response = {
    ok: result.ok,
    plan: {
      action: plan.action,
      discovery: plan.discovery,
      reason: plan.reason,
      entries: plan.entries.length,
    },
    result,
  };
  process.stdout.write(`${JSON.stringify(response, null, 2)}\n`);
  if (!result.ok) {
    process.exitCode = 1;
  }
}

interface RecordAgentFields {
  agentId: string;
  worktreePath: string;
  branch: string;
  base: string;
  files?: string;
}

/**
 * #2596: split a `--files` value into declared paths. Whitespace-separated,
 * matching the `PLAN_FILES` shape the per-plan worktree gate already builds
 * with `jq -r '.files_modified // [] | join(" ")'`. Values are DATA compared
 * against a diff — never opened, never passed to a shell.
 */
function parseDeclaredScopeFlag(raw?: string): string[] {
  return String(raw || '').split(/\s+/).filter((token) => token.length > 0);
}

interface RecordAgentPlan {
  ok: boolean;
  reason: string;
  hint?: string;
  entry: CleanupManifestEntry | null;
  /** Serialized manifest to write back (with trailing newline); null when ok === false. */
  manifest: string | null;
}

/**
 * Pure planner for the per-agent wave-manifest append.
 *
 * Validates the candidate entry at write time using the SAME rules the
 * cleanup-wave reader enforces (via `normalizeCleanupManifestEntry`), so an
 * entry that `record-agent` accepts is guaranteed to survive
 * `normalizeCleanupManifest` on read — a field that would be silently dropped
 * at cleanup time fails loudly here instead.
 *
 * `agent_id` is treated write-strict (required) even though the reader is
 * lenient (nullable): the whole point of this verb is to catch an
 * under-populated entry at write time, and an entry whose author cannot be
 * identified defeats that. A duplicate `(worktree_path, branch)` is also
 * rejected loudly — the reader dedups on that key, so a re-record would be
 * silently dropped (the failure mode this verb exists to eliminate). The
 * on-disk shape stays the existing 4-field entry (`agent_id`, `worktree_path`,
 * `branch`, `expected_base`) unless `--files` declares a scope, in which case
 * an optional `files_modified` is appended (#2596); the reader still
 * re-derives `allowed_bases`.
 */
function planWorktreeRecordAgent(manifestRaw: string, fields: RecordAgentFields): RecordAgentPlan {
  // 1. Write-strict required-field check (loud, with which flag is missing).
  //    Trim first so a whitespace-only value ("   ") is rejected here rather
  //    than deferred to a guaranteed `git worktree remove` failure at cleanup.
  const agentId = (fields.agentId || '').trim();
  const worktreePath = (fields.worktreePath || '').trim();
  const branch = (fields.branch || '').trim();
  const base = (fields.base || '').trim();
  const missing: string[] = [];
  if (!agentId) missing.push('--agent-id');
  if (!worktreePath) missing.push('--path');
  if (!branch) missing.push('--branch');
  if (!base) missing.push('--base');
  if (missing.length > 0) {
    return {
      ok: false,
      reason: 'missing_field',
      hint: `record-agent requires ${missing.join(', ')}. Re-run with all of --agent-id, --path, --branch, --base set to non-empty (non-whitespace) values.`,
      entry: null,
      manifest: null,
    };
  }

  // 2. Shared validation: run the candidate through the reader's normalizer.
  //    If it returns null the reader would drop this entry on read — reject now.
  const declaredScope = parseDeclaredScopeFlag(fields.files);
  const candidate = {
    agent_id: agentId,
    worktree_path: worktreePath,
    branch,
    expected_base: base,
    ...(declaredScope.length > 0 ? { files_modified: declaredScope } : {}),
  };
  const entry = normalizeCleanupManifestEntry(candidate);
  if (!entry) {
    return {
      ok: false,
      reason: 'invalid_entry',
      hint: `Entry failed cleanup-manifest validation: --path/--branch/--base must be non-empty and --branch must match ${WORKTREE_AGENT_BRANCH_PATTERN} (accepts agent-<id>, worktree-agent-<id>, and worktree-wf_<runid> namespaces; got branch="${branch}"). Fix the field and re-run.`,
      entry: null,
      manifest: null,
    };
  }

  // 3. Parse the existing manifest. The init shell ({orchestrator_root, worktrees: []})
  //    is written inline by the orchestrator before any agent spawns; a missing or
  //    malformed manifest is a loud failure here, not a silent under-populated write.
  let parsed: unknown;
  try {
    parsed = JSON.parse(manifestRaw);
  } catch {
    return {
      ok: false,
      reason: 'invalid_manifest_json',
      hint: 'Manifest is not valid JSON. The orchestrator must initialize it as {"orchestrator_root": "...", "worktrees": []} before recording agents.',
      entry: null,
      manifest: null,
    };
  }

  // Accept the canonical {worktrees: []} shell or a bare top-level array (both
  // are read by normalizeCleanupManifest); preserve any other top-level keys.
  let worktrees: unknown[];
  let writeBack: unknown;
  if (Array.isArray(parsed)) {
    worktrees = parsed;
    writeBack = worktrees;
  } else if (parsed && typeof parsed === 'object') {
    const container = parsed as Record<string, unknown>;
    if (container.worktrees === undefined) container.worktrees = [];
    if (!Array.isArray(container.worktrees)) {
      return {
        ok: false,
        reason: 'manifest_shape_invalid',
        hint: 'Manifest "worktrees" must be an array. Re-initialize as {"orchestrator_root": "...", "worktrees": []}.',
        entry: null,
        manifest: null,
      };
    }
    worktrees = container.worktrees;
    writeBack = container;
  } else {
    return {
      ok: false,
      reason: 'manifest_shape_invalid',
      hint: 'Manifest must be a JSON object {"worktrees": []} or a top-level array.',
      entry: null,
      manifest: null,
    };
  }

  // 4. Reject a duplicate (worktree_path, branch). The reader dedups on this
  //    exact key, but only over entries that NORMALIZE successfully — so an
  //    existing malformed same-key entry (which the reader would drop) must NOT
  //    block recording a valid one. Run each existing entry through the reader's
  //    own normalizer and compare only the entries the reader would keep; this
  //    matches its dedup behavior exactly. A real duplicate signals an upstream
  //    double-spawn — surface it loudly instead of silently dropping it.
  const dupKey = `${entry.worktree_path}\0${entry.branch}`;
  const isDuplicate = worktrees.some((existing) => {
    const normalized = normalizeCleanupManifestEntry(existing);
    return normalized !== null && `${normalized.worktree_path}\0${normalized.branch}` === dupKey;
  });
  if (isDuplicate) {
    return {
      ok: false,
      reason: 'duplicate_entry',
      hint: `The manifest already records worktree_path="${entry.worktree_path}" branch="${entry.branch}". The cleanup reader dedups on (worktree_path, branch), so re-recording would be silently dropped — this usually signals an upstream double-spawn. Investigate rather than re-record.`,
      entry: null,
      manifest: null,
    };
  }

  // 5. Append the minimal 4-field entry, matching the existing on-disk format.
  const recorded: CleanupManifestEntry = {
    agent_id: entry.agent_id,
    worktree_path: entry.worktree_path,
    branch: entry.branch,
    expected_base: entry.expected_base,
  };
  // #2596: only written when a scope was actually declared — conservative in
  // what we send, so a blank --files leaves the 4-field shape untouched.
  if (entry.files_modified && entry.files_modified.length > 0) {
    recorded.files_modified = entry.files_modified;
  }
  worktrees.push(recorded);

  return {
    ok: true,
    reason: 'ok',
    entry: recorded,
    manifest: `${JSON.stringify(writeBack, null, 2)}\n`,
  };
}

interface RecordAgentCmdDeps {
  readFile?: (p: string) => string;
  writeFile?: (p: string, content: string) => void;
  write?: (s: string) => void;
  writeErr?: (s: string) => void;
}

interface RecordAgentCmdResult {
  ok: boolean;
  reason: string;
  hint?: string;
  entry: CleanupManifestEntry | null;
  manifest_path?: string;
}

/**
 * CLI command: append a validated per-agent entry to a wave cleanup manifest.
 *
 * Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> [--files "<space-separated paths>"]
 *
 * Fails loudly (non-zero exit + recovery hint on stderr) when a field is
 * missing/garbled or the manifest is absent/malformed, rather than appending an
 * under-populated entry that the cleanup reader would silently drop.
 */
function cmdWorktreeRecordAgent(cwd: string, args: string[] = [], deps: RecordAgentCmdDeps = {}): RecordAgentCmdResult {
  const flag = (name: string): string => {
    const i = args.indexOf(name);
    return i >= 0 && i + 1 < args.length ? args[i + 1] : '';
  };
  const write = deps.write || ((s: string) => process.stdout.write(s));
  const writeErr = deps.writeErr || ((s: string) => process.stderr.write(s));

  const manifestPath = flag('--manifest');
  if (!manifestPath) {
    writeErr('Usage: worktree record-agent --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> [--files "<space-separated paths>"]\n');
    process.exitCode = 2;
    return { ok: false, reason: 'usage', entry: null };
  }

  const resolved = path.resolve(cwd, manifestPath);
  const readFile = deps.readFile || ((p: string) => fs.readFileSync(p, 'utf8'));
  let manifestRaw: string;
  try {
    manifestRaw = readFile(resolved);
  } catch (err) {
    const hint = `Manifest not found or unreadable at ${manifestPath}. The orchestrator must initialize it ({"orchestrator_root": "...", "worktrees": []}) before recording agents.`;
    writeErr(`[gsd] worktree.record-agent: manifest_read_failed — ${hint}\n`);
    write(`${JSON.stringify({ ok: false, reason: 'manifest_read_failed', hint, error: (err as Error).message }, null, 2)}\n`);
    process.exitCode = 1;
    return { ok: false, reason: 'manifest_read_failed', hint, entry: null };
  }

  const plan = planWorktreeRecordAgent(manifestRaw, {
    agentId: flag('--agent-id'),
    worktreePath: flag('--path'),
    branch: flag('--branch'),
    base: flag('--base'),
    files: flag('--files'),
  });

  if (!plan.ok || plan.manifest === null) {
    writeErr(`[gsd] worktree.record-agent: ${plan.reason} — ${plan.hint || ''}\n`);
    write(`${JSON.stringify({ ok: false, reason: plan.reason, hint: plan.hint }, null, 2)}\n`);
    process.exitCode = 1;
    return { ok: false, reason: plan.reason, hint: plan.hint, entry: null };
  }

  const writeFile = deps.writeFile || ((p: string, content: string) => fs.writeFileSync(p, content, 'utf8'));
  writeFile(resolved, plan.manifest);
  write(`${JSON.stringify({ ok: true, reason: 'ok', entry: plan.entry, manifest_path: resolved }, null, 2)}\n`);
  return { ok: true, reason: 'ok', entry: plan.entry, manifest_path: resolved };
}

// ─── worktree create (#2584 ADR-1239 Codex-binding amendment — Phase 2) ───────
//
// The `orchestrator-worktree` isolation ladder value (ADR-1239) requires GSD
// itself to create + bind the git worktree an executor runs in — this is that
// git-worktree-creation primitive. UNCONSUMED in Phase 2: no scheduler calls
// this yet (Phase 3 wires it). Mirrors the plan/execute/cmd split used by
// cleanup-wave and record-agent above so a created worktree is immediately
// manageable by cleanup-wave / reap-orphans without a second code path.

interface WorktreeCreateFields {
  agentId: string;
  worktreePath: string;
  branch: string;
  base: string;
  files?: string;
}

interface WorktreeCreatePlan {
  ok: boolean;
  reason: string;
  hint?: string;
  entry: CleanupManifestEntry | null;
}

/**
 * Pure planner for `worktree create`. Validates the four required fields
 * (write-strict, same missing-field-hint style as `planWorktreeRecordAgent`),
 * then runs the candidate entry through the SAME `normalizeCleanupManifestEntry`
 * validation the cleanup-wave reader and record-agent use — so a worktree this
 * verb creates is guaranteed manageable by cleanup-wave/reap-orphans, and an
 * entry that would fail the reader's branch-namespace guard is rejected here,
 * fail-closed, before any git command runs.
 */
function planWorktreeCreate(fields: WorktreeCreateFields): WorktreeCreatePlan {
  const agentId = (fields.agentId || '').trim();
  const worktreePath = (fields.worktreePath || '').trim();
  const branch = (fields.branch || '').trim();
  const base = (fields.base || '').trim();
  const missing: string[] = [];
  if (!agentId) missing.push('--agent-id');
  if (!worktreePath) missing.push('--path');
  if (!branch) missing.push('--branch');
  if (!base) missing.push('--base');
  if (missing.length > 0) {
    return {
      ok: false,
      reason: 'missing_field',
      hint: `worktree create requires ${missing.join(', ')}. Re-run with all of --agent-id, --path, --branch, --base set to non-empty (non-whitespace) values.`,
      entry: null,
    };
  }

  const declaredScope = parseDeclaredScopeFlag(fields.files);
  const candidate = {
    agent_id: agentId,
    worktree_path: worktreePath,
    branch,
    expected_base: base,
    ...(declaredScope.length > 0 ? { files_modified: declaredScope } : {}),
  };
  const entry = normalizeCleanupManifestEntry(candidate);
  if (!entry) {
    return {
      ok: false,
      reason: 'invalid_entry',
      hint: `Entry failed cleanup-manifest validation: --path/--branch/--base must be non-empty and --branch must match ${WORKTREE_AGENT_BRANCH_PATTERN} (accepts agent-<id>, worktree-agent-<id>, and worktree-wf_<runid> namespaces; got branch="${branch}"). Fix the field and re-run.`,
      entry: null,
    };
  }

  // #2584 FIX 4 — git argument-injection guard: a value starting with '-'
  // could be parsed by git as a FLAG rather than a positional argument (e.g.
  // base="--upload-pack=x", path="-f"). `git worktree add` / `git rev-parse`
  // support for a `--` end-of-options separator is inconsistent across git
  // versions, so rejecting a leading dash outright — not relying on `--` — is
  // the portable fix.
  if (branch.startsWith('-') || base.startsWith('-') || worktreePath.startsWith('-')) {
    return {
      ok: false,
      reason: 'unsafe_leading_dash',
      hint: `--branch/--base/--path must not start with "-" (a leading dash would be parsed by git as a flag, not a value). Got branch="${branch}" base="${base}" path="${worktreePath}".`,
      entry: null,
    };
  }

  // #2584 FIX 4 — path-traversal guard: reject a ".." path segment in --path.
  // Absolute paths ARE allowed (the orchestrator legitimately uses them —
  // Phase-3 root confinement is out of Phase-2 scope); only a literal ".."
  // component is rejected. Split on BOTH separators so the guard is effective
  // on a Windows-style path too.
  if (worktreePath.split(/[/\\]/).includes('..')) {
    return {
      ok: false,
      reason: 'unsafe_path_traversal',
      hint: `--path must not contain a ".." path segment (got: "${worktreePath}").`,
      entry: null,
    };
  }

  return { ok: true, reason: 'ok', entry };
}

interface WorktreeCreateResult {
  ok: boolean;
  reason: string;
  worktree_path?: string;
  branch?: string;
  base?: string;
  cwd?: string;
  stderr?: string;
}

/**
 * Best-effort bounded rollback of a partial/orphaned worktree (#2584 FIX 3,
 * scope narrowed by FIX 5). Invoked ONLY when a `git worktree add` TIMED OUT
 * mid-operation — a SIGTERM'd `add` can leave a `.git/worktrees/<name>` admin
 * entry / directory on disk that got past validation into the file checkout,
 * so the partial is genuinely THIS call's own creation and is safe to
 * best-effort remove immediately. It is deliberately NOT invoked on a clean
 * non-zero `add` exit (see FIX 5) — the most common such failure is a
 * COLLISION (the path/branch is already a registered worktree), git fails
 * FAST there having created nothing, and the branch namespace this verb
 * writes into (`worktree-agent-*`/`agent-*`) is exactly the concurrent-
 * executor namespace, so a colliding path is very plausibly a LIVE PEER
 * executor whose uncommitted work `--force` would destroy. Also invoked from
 * `cmdWorktreeCreate` when a successful `add` is followed by a manifest-write
 * failure (#2584 FIX 1) — that path proves THIS call created the worktree, so
 * removing it is safe. This is immediate best-effort hygiene, not the only
 * safety net: `reapOrphanWorktrees` scans the `.git/worktrees/` admin
 * directory directly (a genuine directory-scan backstop, not manifest-only),
 * so any partial this call cannot reach is still eventually discovered and
 * reaped there. The result is intentionally ignored and a throw is
 * swallowed: this is best-effort cleanup, never a new source of truth, and
 * must never mask or block the caller's own degraded-but-honest return.
 */
function rollbackPartialWorktree(execGit: ExecGitFn, worktreePath: string, repoRoot: string): void {
  try {
    execGit(['worktree', 'remove', '--force', worktreePath], { cwd: repoRoot });
  } catch {
    // best-effort only — a throwing rollback must never mask the original failure.
  }
}

/**
 * Execute a `planWorktreeCreate` plan via bounded git. Fail-closed at every
 * step — a timeout or a non-zero exit degrades to a structured result rather
 * than throwing, and the base must resolve BEFORE any worktree is created (no
 * partial/orphaned worktree on a bad base). Returns `cwd` — the working
 * directory Phase 3's executor spawn will pass through.
 */
function executeWorktreeCreatePlan(plan: WorktreeCreatePlan, repoRoot: string, deps: WorktreeDeps = {}): WorktreeCreateResult {
  const execGit = deps.execGit || execGitDefault;
  if (!plan || !plan.ok || !plan.entry) {
    return {
      ok: false,
      reason: plan ? plan.reason : 'missing_plan',
    };
  }

  const { worktree_path: worktreePath, branch, expected_base: base } = plan.entry;
  const normalizedPath = posixNormalize(worktreePath);

  // 1. Verify the base resolves BEFORE creating anything (fail-closed). Nothing
  //    has been created on this path yet, so there is nothing to roll back.
  const baseCheck = execGit(['rev-parse', '--verify', '--quiet', `${base}^{commit}`], { cwd: repoRoot });
  if (baseCheck.timedOut) {
    return { ok: false, reason: 'git_timeout', worktree_path: normalizedPath, branch, base };
  }
  if (!gitResultOk(baseCheck)) {
    return { ok: false, reason: 'base_unresolved', worktree_path: normalizedPath, branch, base, stderr: baseCheck.stderr || '' };
  }

  // 2. Create the worktree + branch together.
  const addResult = execGit(['worktree', 'add', '-b', branch, worktreePath, base], { cwd: repoRoot });
  if (addResult.timedOut) {
    // #2584 FIX 3: a SIGTERM'd `add` can leave a partial worktree on disk.
    rollbackPartialWorktree(execGit, worktreePath, repoRoot);
    return { ok: false, reason: 'git_timeout', worktree_path: normalizedPath, branch, base };
  }
  if (addResult.exitCode !== 0) {
    // #2584 FIX 5: deliberately NO rollback here. A clean non-zero exit is
    // most commonly a COLLISION (path/branch already a registered worktree),
    // and git fails FAST on that — it creates nothing. A colliding path in
    // this branch namespace is very plausibly a LIVE PEER executor;
    // `git worktree remove --force` on it would destroy real, uncommitted
    // work. The safe response to a clean failure is to fail loudly and leave
    // whatever is already on disk untouched.
    return { ok: false, reason: 'worktree_add_failed', worktree_path: normalizedPath, branch, base, stderr: addResult.stderr || '' };
  }

  return {
    ok: true,
    reason: 'created',
    worktree_path: normalizedPath,
    branch,
    base,
    cwd: normalizedPath,
  };
}

interface WorktreeCreateCmdResult {
  ok: boolean;
  reason: string;
  hint?: string;
  entry?: CleanupManifestEntry | null;
  cwd?: string;
  manifest_path?: string;
  stderr?: string;
}

/**
 * CLI command: create a git worktree + branch off `--base`, then append the
 * validated manifest entry so the worktree is immediately manageable by
 * `worktree cleanup-wave` / `worktree reap-orphans`.
 *
 * Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> --root <dir> [--files "<space-separated paths>"]
 *
 * #2584 FIX 1 — ORDERING CONTRACT: every manifest read/parse/shape-validate/
 * plan step runs BEFORE the git side effect (step 5). The ONLY manifest
 * operation that can run AFTER `git worktree add` has succeeded is the final
 * guarded write (step 6), and a failure there triggers a best-effort rollback
 * of the just-created worktree — so a malformed/mis-shaped manifest, or a
 * `writeFile` IO error, can never leave a REAL worktree on disk with no
 * manifest entry (cleanup-wave/reap-orphans only discover worktrees via the
 * manifest, never a directory scan) or an uncaught throw.
 */
function cmdWorktreeCreate(cwd: string, args: string[] = [], deps: RecordAgentCmdDeps & WorktreeDeps = {}): WorktreeCreateCmdResult {
  const flag = (name: string): string => {
    const i = args.indexOf(name);
    return i >= 0 && i + 1 < args.length ? args[i + 1] : '';
  };
  const write = deps.write || ((s: string) => process.stdout.write(s));
  const writeErr = deps.writeErr || ((s: string) => process.stderr.write(s));

  const manifestPath = flag('--manifest');
  if (!manifestPath) {
    writeErr('Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> --root <dir> [--files "<space-separated paths>"]\n');
    process.exitCode = 2;
    return { ok: false, reason: 'usage' };
  }

  // 1. Read the manifest (no side effect yet).
  const resolved = path.resolve(cwd, manifestPath);
  const readFile = deps.readFile || ((p: string) => fs.readFileSync(p, 'utf8'));
  let manifestRaw: string;
  try {
    manifestRaw = readFile(resolved);
  } catch (err) {
    const hint = `Manifest not found or unreadable at ${manifestPath}. The orchestrator must initialize it ({"orchestrator_root": "...", "worktrees": []}) before creating agent worktrees.`;
    writeErr(`[gsd] worktree.create: manifest_read_failed — ${hint}\n`);
    write(`${JSON.stringify({ ok: false, reason: 'manifest_read_failed', hint, error: (err as Error).message }, null, 2)}\n`);
    process.exitCode = 1;
    return { ok: false, reason: 'manifest_read_failed', hint };
  }

  // 2. Parse + shape-validate the manifest BEFORE any git command runs.
  //    Mirrors planWorktreeRecordAgent's shell-acceptance rules (canonical
  //    {worktrees:[]} object OR a bare top-level array).
  let parsed: unknown;
  try {
    parsed = JSON.parse(manifestRaw);
  } catch {
    const hint = 'Manifest is not valid JSON. The orchestrator must initialize it as {"orchestrator_root": "...", "worktrees": []} before creating agent worktrees.';
    writeErr(`[gsd] worktree.create: invalid_manifest_json — ${hint}\n`);
    write(`${JSON.stringify({ ok: false, reason: 'invalid_manifest_json', hint }, null, 2)}\n`);
    process.exitCode = 1;
    return { ok: false, reason: 'invalid_manifest_json', hint };
  }

  let worktrees: unknown[];
  let writeBack: unknown;
  if (Array.isArray(parsed)) {
    worktrees = parsed;
    writeBack = worktrees;
  } else if (parsed && typeof parsed === 'object') {
    const container = parsed as Record<string, unknown>;
    if (container.worktrees === undefined) container.worktrees = [];
    if (!Array.isArray(container.worktrees)) {
      const hint = 'Manifest "worktrees" must be an array. Re-initialize as {"orchestrator_root": "...", "worktrees": []}.';
      writeErr(`[gsd] worktree.create: manifest_shape_invalid — ${hint}\n`);
      write(`${JSON.stringify({ ok: false, reason: 'manifest_shape_invalid', hint }, null, 2)}\n`);
      process.exitCode = 1;
      return { ok: false, reason: 'manifest_shape_invalid', hint };
    }
    worktrees = container.worktrees;
    writeBack = container;
  } else {
    const hint = 'Manifest must be a JSON object {"worktrees": []} or a top-level array.';
    writeErr(`[gsd] worktree.create: manifest_shape_invalid — ${hint}\n`);
    write(`${JSON.stringify({ ok: false, reason: 'manifest_shape_invalid', hint }, null, 2)}\n`);
    process.exitCode = 1;
    return { ok: false, reason: 'manifest_shape_invalid', hint };
  }

  // 3. Plan (pure, no I/O) — still before any git command.
  const plan = planWorktreeCreate({
    agentId: flag('--agent-id'),
    worktreePath: flag('--path'),
    branch: flag('--branch'),
    base: flag('--base'),
    files: flag('--files'),
  });

  if (!plan.ok || !plan.entry) {
    writeErr(`[gsd] worktree.create: ${plan.reason} — ${plan.hint || ''}\n`);
    write(`${JSON.stringify({ ok: false, reason: plan.reason, hint: plan.hint }, null, 2)}\n`);
    process.exitCode = 1;
    return { ok: false, reason: plan.reason, hint: plan.hint };
  }

  // 3b. Mandatory root confinement (#2627 Phase 3 introduced it; #3050 made it
  //     mandatory — the confinement Phase 2 deferred here from
  //     planWorktreeCreate's path-traversal guard). planWorktreeCreate rejects a
  //     literal ".." SEGMENT, but a plain absolute path outside the project
  //     contains no ".." and passes. The orchestrator SPAWNS executor processes
  //     into these paths, so an unconfined --path is a write primitive aimed
  //     anywhere on the filesystem.
  //
  //     The root is DECLARED by the caller (`--root`) rather than inferred: agent
  //     worktrees legitimately live outside the orchestrator's own root (a lane
  //     orchestrator creates siblings under the repo's .claude/worktrees/), so
  //     there is no layout this module could derive without guessing.
  //
  //     Lexical by design: the worktree does not exist yet, so there is nothing
  //     to realpath, and resolving only the root would not close a symlinked-leaf
  //     hole. Pairs with the leading-dash and ".."-segment guards above.
  //
  //     #3050: confinement does not depend on the caller remembering to pass
  //     `--root` — it used to be silently skippable, so a caller that forgot the
  //     flag got an unconfined `--path` with no warning. Fail closed instead:
  //     absent `--root`, this verb refuses to create anything. The one current
  //     caller (execute-phase's orchestrator-worktree dispatch) always passes
  //     `--root`, so this closes the gap without breaking it.
  const rootFlag = flag('--root');
  if (!rootFlag) {
    const hint = '--root is required (fail-closed root confinement, #3050). Pass --root <orchestrator-root-dir> so worktree.create can verify --path resolves inside it before creating anything.';
    writeErr(`[gsd] worktree.create: root_required — ${hint}\n`);
    write(`${JSON.stringify({ ok: false, reason: 'root_required', hint }, null, 2)}\n`);
    process.exitCode = 1;
    return { ok: false, reason: 'root_required', hint };
  }
  {
    const absRoot = path.resolve(cwd, rootFlag);
    const absWorktree = path.resolve(cwd, plan.entry.worktree_path);
    const rel = path.relative(absRoot, absWorktree);
    // rel === ''           → the worktree IS the root (would clobber the checkout)
    // rel === '..' / '../…' → escapes the root
    // path.isAbsolute(rel) → a different Windows drive or UNC root
    if (rel === '' || rel === '..' || rel.startsWith(`..${path.sep}`) || path.isAbsolute(rel)) {
      const hint = `--path must resolve INSIDE --root (root="${absRoot}", path="${absWorktree}"). A worktree outside the declared root is unreachable by manifest-scoped cleanup and would let a spawned executor write outside the project.`;
      writeErr(`[gsd] worktree.create: path_outside_root — ${hint}\n`);
      write(`${JSON.stringify({ ok: false, reason: 'path_outside_root', hint }, null, 2)}\n`);
      process.exitCode = 1;
      return { ok: false, reason: 'path_outside_root', hint };
    }
  }

  // 4. Compute the deduped final manifest STRING in memory now — the ONLY
  //    manifest work left is the guarded write in step 6, after git succeeds.
  //    #2584 FIX 2: the on-disk entry is the SAME minimal 4-field shape
  //    `cmdWorktreeRecordAgent` writes — never the full normalized entry with
  //    the derived `allowed_bases` — so the two verbs never write divergent
  //    shapes into the same manifest (the reader re-derives `allowed_bases`
  //    from `expected_base` on load, exactly as it does for record-agent).
  const recorded: CleanupManifestEntry = {
    agent_id: plan.entry.agent_id,
    worktree_path: plan.entry.worktree_path,
    branch: plan.entry.branch,
    expected_base: plan.entry.expected_base,
  };
  // #2596: only written when a scope was actually declared — conservative in
  // what we send, so a blank --files leaves the 4-field shape untouched.
  if (Array.isArray(plan.entry.files_modified) && plan.entry.files_modified.length > 0) {
    recorded.files_modified = plan.entry.files_modified;
  }
  const dedupeKey = `${recorded.worktree_path}\0${recorded.branch}`;
  const alreadyPresent = worktrees.some((existing) => {
    const normalized = normalizeCleanupManifestEntry(existing);
    return normalized !== null && `${normalized.worktree_path}\0${normalized.branch}` === dedupeKey;
  });
  if (!alreadyPresent) {
    worktrees.push(recorded);
  }
  const manifestToWrite = `${JSON.stringify(writeBack, null, 2)}\n`;

  // 5. NOW run the git side effect. Every manifest problem above is caught
  //    before this point, so a malformed/mis-shaped manifest can never leave
  //    an unmanifested worktree on disk. `executeWorktreeCreatePlan` itself
  //    best-effort rolls back a partial worktree on its own add-timeout /
  //    add-failed paths (#2584 FIX 3).
  const result = executeWorktreeCreatePlan(plan, cwd, deps);
  if (!result.ok) {
    writeErr(`[gsd] worktree.create: ${result.reason} — ${result.stderr || ''}\n`);
    write(`${JSON.stringify({ ok: false, reason: result.reason, stderr: result.stderr }, null, 2)}\n`);
    process.exitCode = 1;
    return { ok: false, reason: result.reason, stderr: result.stderr };
  }

  // 6. Write the pre-computed manifest string, guarded. A write failure here
  //    means a REAL worktree now exists with NO manifest entry — roll it back
  //    (best-effort) rather than leaving an orphan cleanup-wave/reap-orphans
  //    can never reach (#2584 FIX 1). Never throws past this function.
  const writeFile = deps.writeFile || ((p: string, content: string) => fs.writeFileSync(p, content, 'utf8'));
  try {
    writeFile(resolved, manifestToWrite);
  } catch (err) {
    const execGit = deps.execGit || execGitDefault;
    rollbackPartialWorktree(execGit, plan.entry.worktree_path, cwd);
    const hint = `The worktree was created but the manifest write failed (${(err as Error).message}); rolled back the worktree via a best-effort 'git worktree remove --force'.`;
    writeErr(`[gsd] worktree.create: manifest_write_failed — ${hint}\n`);
    write(`${JSON.stringify({ ok: false, reason: 'manifest_write_failed', hint, error: (err as Error).message }, null, 2)}\n`);
    process.exitCode = 1;
    return { ok: false, reason: 'manifest_write_failed', hint };
  }

  write(`${JSON.stringify({ ok: true, reason: 'created', entry: recorded, cwd: result.cwd, manifest_path: resolved }, null, 2)}\n`);
  return { ok: true, reason: 'created', entry: recorded, cwd: result.cwd, manifest_path: resolved };
}

/**
 * Reap orphaned linked worktrees whose lock owner process is dead, whose
 * branch tip is fully merged into the default branch, and whose lock file
 * mtime is older than REAP_MTIME_GUARD_MS (race guard).
 */
const REAP_MTIME_GUARD_MS = 5 * 60 * 1000; // 5 minutes

interface ReapResult {
  path: string;
  status: 'reaped' | 'skipped';
  reason: string;
}

function reapOrphanWorktrees(repoRoot: string, deps: WorktreeDeps = {}): ReapResult[] {
  const execGit = deps.execGit || execGitDefault;
  const isPidAliveCheck = deps.isPidAlive || defaultIsPidAlive;
  const readDirSafe = deps.readDirSafe || defaultReadDirSafe;
  const readFileSafe = deps.readFileSafe || defaultReadFileSafe;
  const mtimeSafe = deps.mtimeSafe || defaultMtimeSafe;
  const reapMtimeGuardMs = deps.reapMtimeGuardMs !== undefined ? deps.reapMtimeGuardMs : REAP_MTIME_GUARD_MS;
  const nowMs = deps.nowMs ?? Date.now();

  const results: ReapResult[] = [];

  // 1. Discover the .git/worktrees/ admin directory.
  const gitDir = execGit(['rev-parse', '--git-dir'], { cwd: repoRoot });
  if (!gitResultOk(gitDir)) return results;
  const gitDirPath = path.resolve(repoRoot, gitDir.stdout.trim());

  const worktreesAdminDir = path.join(gitDirPath, 'worktrees');
  const entries = readDirSafe(worktreesAdminDir);
  if (!entries) return results;

  // 2. Discover the default branch (main/master/etc) tip.
  const defaultBranchResult = execGit(
    ['symbolic-ref', '--quiet', '--short', 'refs/remotes/origin/HEAD'],
    { cwd: repoRoot }
  );

  let mainTip: string | undefined;
  if (gitResultOk(defaultBranchResult)) {
    // Remote default branch is known — use it exclusively.
    const branchName = defaultBranchResult.stdout.trim().replace(/^origin\//, '');
    const r = execGit(['rev-parse', `refs/remotes/origin/${branchName}`], { cwd: repoRoot });
    if (!gitResultOk(r)) return results; // remote ref unresolvable — fail closed
    mainTip = r.stdout.trim();
  } else {
    // No remote configured (local-only repo, e.g. test fixtures).
    const hasRemote = execGit(['remote'], { cwd: repoRoot });
    if (gitResultOk(hasRemote) && hasRemote.stdout.trim()) {
      // Remote exists but origin/HEAD not set — ambiguous; fail closed.
      return results;
    }
    // Build candidate list: init.defaultBranch config, HEAD symref, then main, master.
    const candidateBranches: string[] = [];
    const configResult = execGit(['config', '--get', 'init.defaultBranch'], { cwd: repoRoot });
    if (gitResultOk(configResult) && configResult.stdout.trim()) {
      candidateBranches.push(configResult.stdout.trim());
    }
    const headSymref = execGit(['symbolic-ref', '--quiet', '--short', 'HEAD'], { cwd: repoRoot });
    if (gitResultOk(headSymref) && headSymref.stdout.trim()) {
      const headBranch = headSymref.stdout.trim();
      if (!candidateBranches.includes(headBranch)) {
        candidateBranches.push(headBranch);
      }
    }
    for (const b of ['main', 'master']) {
      if (!candidateBranches.includes(b)) candidateBranches.push(b);
    }
    for (const candidate of candidateBranches) {
      const r = execGit(['rev-parse', candidate], { cwd: repoRoot });
      if (gitResultOk(r)) {
        mainTip = r.stdout.trim();
        break;
      }
    }
    if (!mainTip) return results;
  }

  // 3. Build a canonical-path → listed-path index from git worktree list.
  const listedResult = execGit(['worktree', 'list', '--porcelain'], { cwd: repoRoot });
  const canonicalToListed = new Map<string, string>();
  if (gitResultOk(listedResult)) {
    const normalizedListed = listedResult.stdout.replace(/\r\n/g, '\n');
    for (const block of normalizedListed.split('\n\n').filter(Boolean)) {
      const wtLine = block.split('\n').find((l) => l.startsWith('worktree '));
      if (!wtLine) continue;
      const listed = wtLine.slice('worktree '.length).trim();
      try {
        const canonical = fs.realpathSync.native(listed);
        canonicalToListed.set(canonical, listed);
      } catch {
        // If the path doesn't exist (already removed), skip silently.
      }
    }
  }

  // 4. Process each worktree admin entry that has a 'locked' file.
  for (const entryName of entries) {
    const adminDir = path.join(worktreesAdminDir, entryName);
    const lockedFile = path.join(adminDir, 'locked');
    const lockedContent = readFileSafe(lockedFile);
    if (lockedContent === null) continue; // no lock file — not our concern

    // Resolve the actual worktree path from the gitdir pointer.
    const gitdirFile = path.join(adminDir, 'gitdir');
    const gitdirContent = readFileSafe(gitdirFile);
    if (!gitdirContent) continue;
    const resolvedGitFile = path.resolve(adminDir, gitdirContent.trim());
    const worktreePath = path.basename(resolvedGitFile) === '.git'
      ? path.dirname(resolvedGitFile)
      : resolvedGitFile;

    // Look up the git-list path (the path git knows about) for use in
    // git worktree unlock/remove commands.
    let gitKnownPath = worktreePath;
    try {
      const canonical = fs.realpathSync.native(worktreePath);
      gitKnownPath = canonicalToListed.get(canonical) || worktreePath;
    } catch {
      // worktreePath may not exist yet (already removed); use as-is.
    }

    // 4a. Stale-lock guard: skip if lock is too fresh (PID recycling / race).
    //
    // The two causes are reported SEPARATELY (#3057). A lock whose mtime could
    // not be read is not "fresh" in any sense: `lock_too_fresh` tells an
    // operator that waiting will resolve the skip, and waiting never resolves a
    // stat failure — the lock could be seconds or months old and the sweep has
    // no way to tell. Conflating them is the same defect this module already
    // fixed for `parse_failed` vs `no_worktrees` in planWorktreePrune: a
    // decision made on unread data must not be indistinguishable from one made
    // on real data.
    const lockMtime = mtimeSafe(lockedFile);
    if (!lockMtime) {
      results.push({ path: worktreePath, status: 'skipped', reason: 'lock_age_unknown' });
      continue;
    }
    if (nowMs - lockMtime.getTime() < reapMtimeGuardMs) {
      results.push({ path: worktreePath, status: 'skipped', reason: 'lock_too_fresh' });
      continue;
    }

    // 4b. PID liveness check.
    const pidStr = lockedContent.trim().match(/^\d+/)?.[0];
    if (!pidStr) {
      results.push({ path: worktreePath, status: 'skipped', reason: 'lock_owner_unknown' });
      continue;
    }
    const pid = parseInt(pidStr, 10);
    // Number.isFinite, not Number.isNaN: pidStr is captured by /^\d+/ above, so
    // pid can never be NaN. A 309-or-more-digit string parses to Infinity.
    //
    // NOT LOAD-BEARING FOR SAFETY — do not delete it as redundant. Fail-closed
    // liveness now lives in defaultIsPidAlive, which treats every non-ESRCH
    // outcome (including the TypeError process.kill throws for Infinity) as
    // ALIVE. This guard survives because it produces a more ACCURATE verdict
    // for garbage input: `lock_owner_unknown` says "the lock names a PID this
    // parse could not represent", whereas falling through would report
    // `pid_alive` — an assertion about an owner that was never probed.
    // Note this is an EARLIER, DIFFERENT gate than the process.kill range
    // limit: process.kill accepts up to 2147483647 and rejects 2147483648
    // (measured), far below the parse cliff this guard catches.
    if (!Number.isFinite(pid)) {
      results.push({ path: worktreePath, status: 'skipped', reason: 'lock_owner_unknown' });
      continue;
    }
    let pidIsAlive: boolean;
    try {
      pidIsAlive = isPidAliveCheck(pid);
    } catch {
      pidIsAlive = true; // Cannot determine liveness — treat as alive, do not reap.
    }
    if (pidIsAlive) {
      results.push({ path: worktreePath, status: 'skipped', reason: 'pid_alive' });
      continue;
    }

    // 4c. Ancestry guard: branch-tip must be reachable from main (fail closed).
    let branchTip: string | undefined;
    {
      const headContent = readFileSafe(path.join(adminDir, 'HEAD'));
      if (!headContent) {
        results.push({ path: worktreePath, status: 'skipped', reason: 'cannot_resolve_branch_tip' });
        continue;
      }
      const trimmed = headContent.trim();
      if (trimmed.startsWith('ref: refs/heads/')) {
        // Symbolic ref — resolve to commit SHA via git
        const branchName = trimmed.slice('ref: refs/heads/'.length);
        const resolveResult = execGit(['rev-parse', `refs/heads/${branchName}`], { cwd: repoRoot });
        if (!gitResultOk(resolveResult)) {
          results.push({ path: worktreePath, status: 'skipped', reason: 'cannot_resolve_branch_tip' });
          continue;
        }
        branchTip = resolveResult.stdout.trim();
      } else if (/^[0-9a-f]{40}$/i.test(trimmed)) {
        // Detached HEAD — bare SHA
        branchTip = trimmed;
      } else {
        results.push({ path: worktreePath, status: 'skipped', reason: 'cannot_resolve_branch_tip' });
        continue;
      }
    }

    const ancestorCheck = execGit(
      ['merge-base', '--is-ancestor', branchTip, mainTip],
      { cwd: repoRoot }
    );
    if (!gitResultOk(ancestorCheck)) {
      results.push({ path: worktreePath, status: 'skipped', reason: 'branch_not_merged' });
      continue;
    }

    // 4d. Reap: unlock → remove --force.
    execGit(['worktree', 'unlock', gitKnownPath], { cwd: repoRoot }); // ignore failure (already unlocked)
    const removeResult = execGit(['worktree', 'remove', gitKnownPath, '--force'], { cwd: repoRoot });
    if (!gitResultOk(removeResult)) {
      results.push({ path: worktreePath, status: 'skipped', reason: 'remove_failed' });
      continue;
    }

    results.push({ path: gitKnownPath, status: 'reaped', reason: 'pid_dead_and_merged' });
  }

  // 5. Always prune stale metadata (handles missing-on-disk entries).
  execGit(['worktree', 'prune'], { cwd: repoRoot });

  return results;
}

// ─── reapOrphanWorktrees deps helpers ─────────────────────────────────────────

/**
 * Liveness probe for a lock-owner PID — FAILS CLOSED (#3057).
 *
 * `ESRCH` ("no such process") is the ONLY outcome that proves the owner is
 * gone. Every other failure means the probe could not determine liveness:
 *   - `EPERM` — the process exists, we just may not signal it;
 *   - `TypeError` / `ERR_INVALID_ARG_TYPE` — `process.kill` accepts a pid up
 *     to 2147483647 and REJECTS 2147483648 and above (measured), so a finite
 *     but out-of-range pid never reaches the OS at all;
 *   - anything else — an outcome this helper does not recognise.
 *
 * The return value feeds a DESTRUCTIVE decision (`git worktree remove
 * --force`), so an unrecognised failure must never read as "dead". Hence the
 * inversion: only ESRCH returns false; everything else returns true (alive,
 * do not reap).
 */
function defaultIsPidAlive(pid: number): boolean {
  try {
    process.kill(pid, 0);
    return true;
  } catch (err) {
    return (err as NodeJS.ErrnoException | null | undefined)?.code !== 'ESRCH';
  }
}

function defaultReadDirSafe(dir: string): string[] | null {
  try { return fs.readdirSync(dir); } catch { return null; }
}

function defaultReadFileSafe(file: string): string | null {
  try { return fs.readFileSync(file, 'utf8'); } catch { return null; }
}

function defaultMtimeSafe(file: string): Date | null {
  try { return fs.statSync(file).mtime; } catch { return null; }
}

function cmdWorktreeReapOrphans(cwd: string, deps: RecordAgentCmdDeps & WorktreeDeps = {}): void {
  const write = deps.write || ((s: string) => process.stdout.write(s));
  const writeErr = deps.writeErr || ((s: string) => process.stderr.write(s));
  let result: ReapResult[];
  try {
    result = reapOrphanWorktrees(cwd, deps);
  } catch (err) {
    // Surface failure as a one-line warning; keep exit-zero so workflows don't break.
    writeErr(`[gsd] worktree.reap-orphans failed: ${err && (err as Error).message ? (err as Error).message : String(err)}\n`);
    result = [];
  }
  const skippedCount = result.filter((r) => r.status === 'skipped').length;
  if (skippedCount > 0) {
    // Surface skipped entries so operators are aware of unresolved orphans.
    writeErr(`[gsd] worktree.reap-orphans: ${skippedCount} orphan(s) skipped (run with DEBUG=1 for details)\n`);
  }
  write(`${JSON.stringify({ ok: true, reaped: result.filter((r) => r.status === 'reaped').length, entries: result }, null, 2)}\n`);
}

// Unused exports kept for API compatibility
void parseWorktreeListPaths;

// ─── Moved from core.cjs (ADR-857 T0 #1268 rehome-core-squatters) ─────────────

/**
 * Resolve the main worktree root when running inside a git worktree, along
 * with the `reason` that produced it (#3050). Callers MUST inspect `reason`
 * before trusting `root` unconditionally — a `reason` of `git_timed_out`
 * means the git subprocess used to distinguish "linked worktree" from
 * "not a repo" never completed, so `root` is a best-effort fallback (cwd),
 * not a confirmed worktree root. Degrading to cwd rather than throwing is
 * intentional (return degraded result on timeout; do not throw) — but the
 * reason must still reach the caller so it can surface the risk instead of
 * silently trusting the wrong root.
 */
function resolveWorktreeRoot(cwd: string, deps: WorktreeDeps = {}): { root: string; reason: string } {
  const context = resolveWorktreeContext(cwd, {
    existsSync: deps.existsSync || fs.existsSync,
    execGit: deps.execGit,
  });
  return { root: context.effectiveRoot, reason: context.reason };
}

/**
 * Clear stale worktree metadata references via `git worktree prune`.
 *
 * Destructive linked-worktree removal is disabled by default for safety.
 *
 * @param repoRoot - absolute path to the main (or any) worktree of
 *   the repository; used as `cwd` for git commands.
 * @returns list of worktree paths that were removed (always empty)
 */
function pruneOrphanedWorktrees(repoRoot: string, deps: WorktreeDeps & { writeErr?: (s: string) => void } = {}): string[] {
  const writeErr = deps.writeErr || ((s: string) => process.stderr.write(s));
  try {
    // `...deps` comes LAST deliberately: `parseWorktreePorcelain` is a declared
    // member of WorktreeDeps and planWorktreePrune already reads
    // `deps.parseWorktreePorcelain` before falling back to the module function,
    // so a caller-supplied parser is an intended override, not an accident.
    // The hard-coded key is only a restatement of that same default. Do not
    // reorder the two — `tests/worktree-safety-reap.test.cjs` pins the override.
    const plan = planWorktreePrune(
      repoRoot,
      { allowDestructive: false },
      { parseWorktreePorcelain, ...deps }
    );
    const pruneResult = executeWorktreePrunePlan(plan, deps) as { timedOut?: boolean } | null;
    if (pruneResult && pruneResult.timedOut) {
      writeErr(
        '[gsd-tools] WARNING: worktree health check degraded' +
        ' — git worktree prune timed out after 10s.' +
        ' Orphaned worktree metadata may remain until the next successful run.\n'
      );
    }
  } catch { /* never crash the caller */ }
  return [];
}

export = {
  resolveWorktreeContext,
  resolveWorktreeLinkage,
  parseWorktreePorcelain,
  planWorktreePrune,
  executeWorktreePrunePlan,
  listLinkedWorktreePaths,
  inspectWorktreeHealth,
  snapshotWorktreeInventory,
  normalizeCleanupManifest,
  planWorktreeWaveCleanup,
  executeWorktreeWaveCleanupPlan,
  WAVE_CLEANUP_WARNING,
  planWaveScopeConformance,
  isSummaryArtifactRelPath,
  cmdWorktreeCleanupWave,
  planWorktreeRecordAgent,
  cmdWorktreeRecordAgent,
  planWorktreeCreate,
  executeWorktreeCreatePlan,
  cmdWorktreeCreate,
  reapOrphanWorktrees,
  cmdWorktreeReapOrphans,
  resolveWorktreeRoot,
  pruneOrphanedWorktrees,
};