@opengsd/gsd-core 1.9.1 → 1.11.0

package/gsd-core/bin/lib/worktree-safety.cjs

@@ -19,20 +19,20 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 // 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;
-const WORKTREE_AGENT_BRANCH_RE = /^(worktree-)?agent-[A-Za-z0-9._/-]+$/;
+// #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;
 /**
- * Execute a git command via the shell-projection seam, with a derived
- * `timedOut` field. Tests inject mocks via deps.execGit using the new
+ * 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.
- *
- * Return shape: { exitCode, stdout, stderr, timedOut, error, signal }
- *   - timedOut: true when spawnSync reports SIGTERM + ETIMEDOUT
  */
 function execGitDefault(args, opts = {}) {
-    const result = (0, shell_command_projection_cjs_1.execGit)(args, { ...opts, timeout: opts.timeout ?? DEFAULT_GIT_TIMEOUT_MS });
-    const timedOut = result.signal === 'SIGTERM' && result.error?.code === 'ETIMEDOUT';
-    return { ...result, timedOut };
+    return (0, shell_command_projection_cjs_1.execGit)(args, { ...opts, timeout: opts.timeout ?? DEFAULT_GIT_TIMEOUT_MS });
 }
 function parseWorktreePorcelain(porcelain) {
     return parseWorktreeEntries(porcelain).filter((entry) => entry.branch !== null).map((entry) => ({
@@ -92,19 +92,39 @@ function readWorktreeList(repoRoot, deps = {}) {
         entries: parseWorktreeEntries(listResult.stdout),
     };
 }
-function resolveWorktreeContext(cwd, deps = {}) {
+/**
+ * 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, deps = {}) {
     const execGit = deps.execGit || execGitDefault;
-    const existsSync = deps.existsSync || node_fs_1.default.existsSync;
-    // Local .planning takes precedence over linked-worktree remapping.
-    if (existsSync(node_path_1.default.join(cwd, '.planning'))) {
+    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: 'has_local_planning',
+            reason: 'git_timed_out',
         };
     }
-    const gitDir = execGit(['rev-parse', '--git-dir'], { cwd });
-    const commonDir = execGit(['rev-parse', '--git-common-dir'], { cwd });
     if (gitDir.exitCode !== 0 || commonDir.exitCode !== 0) {
         return {
             effectiveRoot: cwd,
@@ -127,6 +147,18 @@ function resolveWorktreeContext(cwd, deps = {}) {
         reason: 'main_worktree',
     };
 }
+function resolveWorktreeContext(cwd, deps = {}) {
+    const existsSync = deps.existsSync || node_fs_1.default.existsSync;
+    // Local .planning takes precedence over linked-worktree remapping.
+    if (existsSync(node_path_1.default.join(cwd, '.planning'))) {
+        return {
+            effectiveRoot: cwd,
+            mode: 'current_directory',
+            reason: 'has_local_planning',
+        };
+    }
+    return resolveWorktreeLinkage(cwd, deps);
+}
 function planWorktreePrune(repoRoot, options = {}, deps = {}) {
     const parsePorcelain = deps.parseWorktreePorcelain || parseWorktreePorcelain;
     const destructiveModeRequested = Boolean(options.allowDestructive);
@@ -140,17 +172,26 @@ function planWorktreePrune(repoRoot, options = {}, deps = {}) {
         };
     }
     let worktrees = [];
+    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: worktrees.length === 0 ? 'no_worktrees' : 'worktrees_present',
+        reason: parseFailed
+            ? 'parse_failed'
+            : (worktrees.length === 0 ? 'no_worktrees' : 'worktrees_present'),
         destructiveModeRequested,
     };
 }
@@ -220,13 +261,25 @@ function inspectWorktreeHealth(repoRoot, options = {}, deps = {}) {
     }
     const findings = [];
     for (const entry of inventory.entries) {
-        if (!entry.exists) {
+        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',
@@ -256,7 +309,7 @@ function snapshotWorktreeInventory(repoRoot, options = {}, deps = {}) {
     }
     const entries = [];
     for (const worktreePath of listed.paths) {
-        let exists = false;
+        let exists = 'absent';
         let isStale = false;
         let ageMinutes = null;
         if (!existsSync(worktreePath)) {
@@ -268,9 +321,9 @@ function snapshotWorktreeInventory(repoRoot, options = {}, deps = {}) {
             });
             continue;
         }
-        exists = true;
         try {
             const stat = statSync(worktreePath);
+            exists = 'present';
             const ageMs = nowMs - stat.mtimeMs;
             ageMinutes = Math.round(ageMs / 60000);
             if (ageMs > staleAfterMs) {
@@ -278,7 +331,12 @@ function snapshotWorktreeInventory(repoRoot, options = {}, deps = {}) {
             }
         }
         catch {
-            // Keep historical behavior: stat failures are ignored.
+            // #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,
@@ -308,13 +366,24 @@ function normalizeCleanupManifestEntry(entry) {
         return null;
     const rawAllowedBases = Array.isArray(e.allowed_bases) ? e.allowed_bases : [];
     const allowedBases = Array.from(new Set([expectedBase, ...rawAllowedBases.filter((base) => typeof base === 'string' && base.length > 0)]));
-    return {
+    // #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) => typeof f === 'string' && f.trim().length > 0);
+    const normalized = {
         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;
 }
 function normalizeCleanupManifest(manifest) {
     let parsed = manifest;
@@ -371,6 +440,71 @@ function planWorktreeWaveCleanup(repoRoot, manifest) {
 function gitResultOk(result) {
     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, repoRoot) {
+    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) {
+    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) {
+    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
@@ -380,7 +514,7 @@ function gitResultOk(result) {
  *   find "$WT/.planning" -name "*SUMMARY.md"
  */
 function defaultFindSummaryFiles(worktreePath) {
-    const planningDir = node_path_1.default.join(worktreePath, '.planning');
+    const planningDir = node_path_1.default.join(worktreePath, SUMMARY_ARTIFACT_DIR);
     const results = [];
     function walk(dir) {
         let entries;
@@ -395,7 +529,7 @@ function defaultFindSummaryFiles(worktreePath) {
             if (entry.isDirectory()) {
                 walk(full);
             }
-            else if (entry.isFile() && entry.name.endsWith('SUMMARY.md')) {
+            else if (entry.isFile() && entry.name.endsWith(SUMMARY_ARTIFACT_SUFFIX)) {
                 results.push(full);
             }
         }
@@ -498,6 +632,77 @@ function rescueSummaryArtifacts(worktreePath, repoRoot, deps) {
     }
     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',
+});
+/**
+ * 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) {
+    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, declaredFiles, branch) {
+    if (!Array.isArray(declaredFiles))
+        return [];
+    const prefixes = [];
+    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 = [];
+    const seen = new Set();
+    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;
+}
 function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
     const execGit = deps.execGit || execGitDefault;
     const entries = Array.isArray(plan?.entries) ? plan.entries : [];
@@ -508,11 +713,25 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
             reason: plan ? (plan.reason || 'missing_entries') : 'missing_plan',
             entries: [],
             pending: entries,
+            warnings: [],
         };
     }
     const results = [];
     const pending = [];
+    const allWarnings = [];
     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, reason, stderr) {
+        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 = {
@@ -520,71 +739,68 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
             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) {
-            result.status = 'blocked';
-            result.reason = 'branch_mismatch';
-            result.stderr = branchCheck?.stderr || '';
-            results.push(result);
-            pending.push(...entries.slice(i + 1));
-            ok = false;
-            break;
+            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())) {
-            result.status = 'blocked';
-            result.reason = 'base_mismatch';
-            result.stderr = mergeBase?.stderr || '';
-            results.push(result);
-            pending.push(...entries.slice(i + 1));
-            ok = false;
-            break;
+            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)) {
-            result.status = 'blocked';
-            result.reason = 'deletion_check_failed';
-            result.stderr = deletions?.stderr || '';
-            results.push(result);
-            pending.push(...entries.slice(i + 1));
-            ok = false;
-            break;
+            blockEntry(result, 'deletion_check_failed', deletions?.stderr || '');
+            continue; // #2852: isolate
         }
         if (deletions.stdout) {
-            result.status = 'blocked';
-            result.reason = 'branch_contains_deletions';
-            result.stderr = deletions.stdout;
-            results.push(result);
-            pending.push(...entries.slice(i + 1));
-            ok = false;
-            break;
+            // 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 = !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) {
-            result.status = 'blocked';
-            result.reason = 'summary_rescue_failed';
-            result.stderr = rescueFailures.map((f) => `${f.relPath}: ${f.error}`).join('; ');
-            results.push(result);
-            pending.push(...entries.slice(i + 1));
-            ok = false;
-            break;
+            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)) {
-            result.status = 'blocked';
-            result.reason = 'worktree_dirty';
-            result.stderr = worktreeStatus?.stderr || '';
-            results.push(result);
-            pending.push(...entries.slice(i + 1));
-            ok = false;
-            break;
+            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
@@ -599,23 +815,31 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
             return !rescuedRelPaths.has(filePath);
         });
         if (dirtyLines.length > 0) {
-            result.status = 'blocked';
-            result.reason = 'worktree_dirty';
-            result.stderr = dirtyLines.join('\n');
-            results.push(result);
-            pending.push(...entries.slice(i + 1));
-            ok = false;
-            break;
+            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)) {
-            result.status = 'blocked';
-            result.reason = 'merge_failed';
-            result.stderr = merge?.stderr || merge?.stdout || '';
-            results.push(result);
-            pending.push(...entries.slice(i + 1));
-            ok = false;
-            break;
+            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)) {
@@ -626,13 +850,10 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
             remove = execGit(['worktree', 'remove', entry.worktree_path, '--force'], { cwd: plan.repoRoot });
         }
         if (!gitResultOk(remove)) {
-            result.status = 'blocked';
-            result.reason = 'worktree_remove_failed';
-            result.stderr = remove?.stderr || '';
-            results.push(result);
-            pending.push(...entries.slice(i + 1));
-            ok = false;
-            break;
+            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)) {
@@ -653,6 +874,7 @@ function executeWorktreeWaveCleanupPlan(plan, deps = {}) {
         reason: ok ? 'ok' : 'cleanup_blocked',
         entries: results,
         pending,
+        warnings: allWarnings,
     };
 }
 function cmdWorktreeCleanupWave(cwd, args = []) {
@@ -693,6 +915,15 @@ function cmdWorktreeCleanupWave(cwd, args = []) {
         process.exitCode = 1;
     }
 }
+/**
+ * #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) {
+    return String(raw || '').split(/\s+/).filter((token) => token.length > 0);
+}
 /**
  * Pure planner for the per-agent wave-manifest append.
  *
@@ -709,8 +940,9 @@ function cmdWorktreeCleanupWave(cwd, args = []) {
  * 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`) — no schema change; the reader re-derives
- * `allowed_bases`.
+ * `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, fields) {
     // 1. Write-strict required-field check (loud, with which flag is missing).
@@ -740,18 +972,20 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
     }
     // 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 both agent-<id> and worktree-agent-<id> namespaces; got branch="${branch}"). Fix the field and re-run.`,
+            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,
         };
@@ -833,6 +1067,11 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
         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,
@@ -844,7 +1083,7 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
 /**
  * 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>
+ * 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
@@ -859,7 +1098,7 @@ function cmdWorktreeRecordAgent(cwd, args = [], deps = {}) {
     const writeErr = deps.writeErr || ((s) => 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>\n');
+        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 };
     }
@@ -881,6 +1120,7 @@ function cmdWorktreeRecordAgent(cwd, args = [], deps = {}) {
         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`);
@@ -924,18 +1164,20 @@ function planWorktreeCreate(fields) {
             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 both agent-<id> and worktree-agent-<id> namespaces; got branch="${branch}"). Fix the field and re-run.`,
+            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,
         };
     }
@@ -1056,7 +1298,7 @@ function executeWorktreeCreatePlan(plan, repoRoot, deps = {}) {
  * 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>
+ * 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
@@ -1076,7 +1318,7 @@ function cmdWorktreeCreate(cwd, args = [], deps = {}) {
     const writeErr = deps.writeErr || ((s) => 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>]\n');
+        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' };
     }
@@ -1141,6 +1383,7 @@ function cmdWorktreeCreate(cwd, args = [], deps = {}) {
         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`);
@@ -1148,25 +1391,38 @@ function cmdWorktreeCreate(cwd, args = [], deps = {}) {
         process.exitCode = 1;
         return { ok: false, reason: plan.reason, hint: plan.hint };
     }
-    // 3b. Optional root confinement (#2627, Phase 3 — 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. Phase 3 makes the
-    //     orchestrator SPAWN executor processes into these paths, so an
-    //     unconfined --path is a write primitive aimed anywhere on the filesystem.
+    // 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. Absent
-    //     `--root` the behavior is exactly as shipped in Phase 2 — the
-    //     orchestrator-worktree scheduler path always passes it.
+    //     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) {
+    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 = node_path_1.default.resolve(cwd, rootFlag);
         const absWorktree = node_path_1.default.resolve(cwd, plan.entry.worktree_path);
         const rel = node_path_1.default.relative(absRoot, absWorktree);
@@ -1194,6 +1450,11 @@ function cmdWorktreeCreate(cwd, args = [], deps = {}) {
         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);
@@ -1350,8 +1611,21 @@ function reapOrphanWorktrees(repoRoot, deps = {}) {
             // 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 || nowMs - lockMtime.getTime() < reapMtimeGuardMs) {
+        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;
         }
@@ -1362,9 +1636,26 @@ function reapOrphanWorktrees(repoRoot, deps = {}) {
             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;
         try {
-            pidIsAlive = Number.isNaN(pid) || isPidAliveCheck(pid);
+            pidIsAlive = isPidAliveCheck(pid);
         }
         catch {
             pidIsAlive = true; // Cannot determine liveness — treat as alive, do not reap.
@@ -1420,15 +1711,29 @@ function reapOrphanWorktrees(repoRoot, deps = {}) {
     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) {
     try {
         process.kill(pid, 0);
         return true;
     }
     catch (err) {
-        if (err && err.code === 'EPERM')
-            return true;
-        return false;
+        return err?.code !== 'ESRCH';
     }
 }
 function defaultReadDirSafe(dir) {
@@ -1455,36 +1760,45 @@ function defaultMtimeSafe(file) {
         return null;
     }
 }
-function cmdWorktreeReapOrphans(cwd) {
+function cmdWorktreeReapOrphans(cwd, deps = {}) {
+    const write = deps.write || ((s) => process.stdout.write(s));
+    const writeErr = deps.writeErr || ((s) => process.stderr.write(s));
     let result;
     try {
-        result = reapOrphanWorktrees(cwd);
+        result = reapOrphanWorktrees(cwd, deps);
     }
     catch (err) {
         // Surface failure as a one-line warning; keep exit-zero so workflows don't break.
-        process.stderr.write(`[gsd] worktree.reap-orphans failed: ${err && err.message ? err.message : String(err)}\n`);
+        writeErr(`[gsd] worktree.reap-orphans failed: ${err && err.message ? err.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.
-        process.stderr.write(`[gsd] worktree.reap-orphans: ${skippedCount} orphan(s) skipped (run with DEBUG=1 for details)\n`);
+        writeErr(`[gsd] worktree.reap-orphans: ${skippedCount} orphan(s) skipped (run with DEBUG=1 for details)\n`);
     }
-    process.stdout.write(`${JSON.stringify({ ok: true, reaped: result.filter((r) => r.status === 'reaped').length, entries: result }, null, 2)}\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.
- * In a linked worktree, .planning/ lives in the main worktree, not in the linked one.
- * Returns the main worktree path, or cwd if not in a worktree.
+ * 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) {
+function resolveWorktreeRoot(cwd, deps = {}) {
     const context = resolveWorktreeContext(cwd, {
-        existsSync: node_fs_1.default.existsSync,
+        existsSync: deps.existsSync || node_fs_1.default.existsSync,
+        execGit: deps.execGit,
     });
-    return context.effectiveRoot;
+    return { root: context.effectiveRoot, reason: context.reason };
 }
 /**
  * Clear stale worktree metadata references via `git worktree prune`.
@@ -1495,12 +1809,19 @@ function resolveWorktreeRoot(cwd) {
  *   the repository; used as `cwd` for git commands.
  * @returns list of worktree paths that were removed (always empty)
  */
-function pruneOrphanedWorktrees(repoRoot) {
+function pruneOrphanedWorktrees(repoRoot, deps = {}) {
+    const writeErr = deps.writeErr || ((s) => process.stderr.write(s));
     try {
-        const plan = planWorktreePrune(repoRoot, { allowDestructive: false }, { parseWorktreePorcelain });
-        const pruneResult = executeWorktreePrunePlan(plan);
+        // `...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);
         if (pruneResult && pruneResult.timedOut) {
-            process.stderr.write('[gsd-tools] WARNING: worktree health check degraded' +
+            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');
         }
@@ -1510,6 +1831,7 @@ function pruneOrphanedWorktrees(repoRoot) {
 }
 module.exports = {
     resolveWorktreeContext,
+    resolveWorktreeLinkage,
     parseWorktreePorcelain,
     planWorktreePrune,
     executeWorktreePrunePlan,
@@ -1519,6 +1841,9 @@ module.exports = {
     normalizeCleanupManifest,
     planWorktreeWaveCleanup,
     executeWorktreeWaveCleanupPlan,
+    WAVE_CLEANUP_WARNING,
+    planWaveScopeConformance,
+    isSummaryArtifactRelPath,
     cmdWorktreeCleanupWave,
     planWorktreeRecordAgent,
     cmdWorktreeRecordAgent,