2f86278b5e
* test(#3003): failing-first suite for declared deletions in cleanup-wave Binds the guard's opt-in before it exists, so the suite is RED against next. The rows that carry the weight are the over-authorization set: a directory declaration must not authorize its children, a glob declaration must authorize nothing, and a declaration must not act as a string prefix of another path. Each of those BLOCKS, and each would PASS under a prefix, glob, or startsWith matcher — which is how a path list quietly degrades into the boolean opt-in #3003 explicitly rejected. The glob row matters most: declaredScopePrefix already returns null ("matches everything") for a glob-leading pattern, correct for the advisory it serves and catastrophic for a gate. Also pinned: a failed deletion check blocks on its own reason rather than being filtered into a pass; the block detail names only the undeclared residue so the operator is not misdirected by paths that were fine; an entry with no declaration blocks exactly as before; junk and non-array declarations do not authorize; and a blocked entry still isolates rather than aborting the wave (#2852, which must stay fixed). Two advisory rows cover an interaction found while designing: git diff --name-only includes deleted paths, so without unioning the declaration into the #2596 scope check, authorizing a deletion would raise SCOPE_OUT_OF_DECLARED against the very path just authorized. A seeded property states the whole invariant the three over-authorization rows sample: a deletion merges iff its normalized path is in the declared set. * feat(#3003): declared deletions opt-in for the cleanup-wave guard The deletions guard blocked the merge-back of any executor branch whose diff removed a file, with no way to say a removal was intended. A plan that folded one test file into a sibling could not be merged by the tool meant to merge it, forcing a manual --no-ff outside the tool -- strictly less safe than what the guard protects against. A plan now declares removals in its own frontmatter (files_deleted), and that list rides the same path files_modified already travels: plan-document parse -> phase plan JSON -> the per-plan worktree gate -> record-agent/create --deletions -> declared_deletions on the manifest entry -> the guard. The guard blocks only the deletions NOT in that list. A path list rather than a boolean, per the pinned decision: a boolean disarms the guard for the whole entry, so an unexpected deletion riding along with a declared one would pass unnoticed. Matching is exact after the module's shared normalizer -- never a prefix, never a glob. Both would let one declaration authorize a whole set, which is the mass-deletion accident the guard exists to catch. That also means declaredScopePrefix is deliberately NOT reused here: it returns null ("matches everything") for a glob-leading pattern, which is right for the advisory it serves and would silently disarm a gate. The block detail now carries only the undeclared residue, so an operator is not sent looking at paths that were fine. A failed deletion check still blocks on its own reason and is never filtered into a pass. A blocked entry still isolates rather than aborting the wave (#2852). The #2596 scope advisory unions the declaration into its declared set -- git diff --name-only includes deleted paths, so without that, authorizing a deletion would immediately warn that the same path was out of declared scope. Optional and additive throughout: files_deleted is absent from PLAN_REQUIRED_FIELDS, a manifest entry without declared_deletions keeps the original unconditional block, and omitting --deletions leaves the on-disk entry shape untouched. Supersedes the spent #2856 emitted-drift ack entry for execute-phase.md, the same supersede that entry performed on #3370 and #3370 on #3324. * fix(#3003): wire --deletions on every dispatch surface, not just one Review found the feature inert on two of three dispatch paths. execute-phase.md (harness inline) passed --deletions, but the orchestrator-worktree path (executor-isolation-dispatch.md, worktree.create) and the Fleet-parallel batch path (capabilities/claude-orchestration/fragments/execute-wave-pre.md, worktree.record-agent) still passed only --files. A plan declaring files_deleted would have merged on one path and been blocked on the other two -- the exact bug #3003 exists to fix, left unfixed where most of the isolation actually runs. Worse, per-plan-worktree-gate.md already claimed --deletions was passed 'on the same worktree.record-agent / worktree.create calls', which was false for both untouched sites. A doc asserting coverage that does not exist is how a gap survives review. All four surfaces now pass the flag, verified by sweeping every .md under gsd-core/, capabilities/, commands/, skills/ and agents/ that invokes worktree.record-agent or worktree.create: each one that passes --files now also passes --deletions. The isolation-dispatch note explains why this flag, unlike --files, is not advisory -- omitting it does not skip a check, it blocks a merge the plan declared. Regenerates capability-registry.cjs, which the fragment edit made stale. Neither newly-grown file needs an emitted-drift ack: executor-isolation-dispatch.md sits under workflows/execute-phase/steps/ and execute-wave-pre.md under capabilities/, both outside currentSizes()'s non-recursive scan of gsd-core/workflows/ and agents/. * docs(#3003): document files_deleted where a plan author will actually find it The feature's entire user surface is one plan-frontmatter field, and the canonical reference for that frontmatter -- docs/reference/plan-md.md, the table that documents every other key -- never mentioned it. A field nobody can discover ships as a field nobody uses. Adds the files_deleted row and an example entry in all five locales (en, ja-JP, zh-CN, ko-KR, pt-BR), stating the property that makes the opt-in safe: matching is exact per path after separator normalization, with no globs and no directory prefixes, so a declaration can never authorize more than it literally lists, and omitting the field keeps the guard's original unconditional block. Also corrects two claims in the scope-conformance how-to that this change made false. Its opening paragraph described the recorded declared scope as files_modified alone; declared_deletions is now unioned into that comparison. Its "Renames are not detected specially" bullet asserted the deletions guard blocks any entry whose diff contains a deletion, full stop -- which was the whole point of #3003 and is no longer true. Reworked to say what now decides a rename's fate: declare the old path in files_deleted and both halves become ordinary paths for the advisory check, which is also why the old path needs no separate files_modified entry. Documentation that describes the pre-change behavior of the thing being changed is worse than no documentation, because a reader trusts it. * fix(#3003): close every review finding on the declared-deletions opt-in Two independent isolated reviewers, correctness and security. Neither found a blocker; both found real defects, and the directive treats a finding at any severity as blocking. All of them are fixed here. MAJOR -- the submodule worktree gate could not see a deletion-only plan. per-plan-worktree-gate.md intersected $SUBMODULE_PATHS against $PLAN_FILES alone, while $PLAN_DELETIONS was extracted and then never used. Before files_deleted existed, a path had to appear in files_modified to be planned at all, so the gate saw it; the new field plus the new docs telling authors a deleted path needs no files_modified entry opened a hole where a plan whose only submodule touch is a removal kept worktree isolation on -- the exact case #2772 disabled it for. Both channels now feed the intersection. Note the posture is deliberately the OPPOSITE of the cleanup-wave guard: there the channels stay apart because a deletion AUTHORIZATION must never be inferred; here they merge because a safety fallback must never MISS a touch. MAJOR -- same-wave conflict detection could not see a deletion. The planner's implicit-dependency rule compared files_modified only, so plan A editing src/x.ts and plan B declaring files_deleted: [src/x.ts] scored as conflict-free and ran in parallel: one branch removing what the other is writing, which is the sharpest conflict there is. Overlap is now computed across both channels. MINOR (both reviewers, one root cause) -- the advisory union gave one field two matching rules. declared_deletions was unioned into the scope list handed to planWaveScopeConformance, which reads it with prefix-and-glob semantics. So a field that is exact-match-only at the gate silently became wider at the advisory: ["*.md"], inert at the gate, yielded a null prefix meaning "matches everything" and muted the advisory completely, and ["src"] muted all of src/. The union also activated the advisory on plans that declared no modification scope at all, warning on every modified path. Replaced with subtraction from the findings, gated on files_modified alone. One field, one rule, everywhere. MINOR -- core.quotepath made the feature silently inert for non-ASCII paths. git emits "tests/\303\251.ts" C-escaped and quoted, which never equals the declared plain path, so a correctly declared deletion of tests/é.ts would block forever with nothing pointing at the encoding. Both diffs now pass -c core.quotepath=false. NIT -- flag() consumed a following flag as a value, so --deletions --files x swallowed --files and dropped both. Now treated as a missing declaration, which fails closed. Fixed at both call sites; the helper is duplicated verbatim in cmdWorktreeRecordAgent and cmdWorktreeCreate and leaving one would reintroduce it. TEST -- one test passed for the wrong reason. "a declared deletion is in scope for the advisory" asserted only that warnings omit the deleted path; under a full revert the entry blocks first, warnings come back empty, and the negative assertion passes anyway. It now asserts the entry actually merged, which is the load-bearing half. Four regressions added, one per fix above. Docs corrected rather than extended. The rename bullet in the scope-conformance how-to claimed a rename whose delete side is undeclared never reaches the advisory. Verified false: git's rename detection is on by default, so a pure rename is a single R entry that appears in no --diff-filter=D output and was never gated, before or after #3003. Only a rename that edits enough to fall below the similarity threshold decomposes into add+delete. The pre-existing sentence made the same wrong claim; this restates it correctly instead of sharpening the error. The localized plan-md.md reference edits are reverted: the PR template requires docs content added here to be English, and the translations already lag by three fields, so English-only is the repo's standing posture, not an oversight. Agent-file size caps respected: gsd-planner.md is XL-tier by bytes but carries a separate 49152-LF-CHAR cap asserted by four suites, so its edit is deliberately terse and lands at 49141 with 11 chars of headroom, with the rationale moved to docs/reference/plan-md.md, which has no cap. gsd-plan-checker.md lands at 49107 bytes, 45 under the LARGE cap. Both acks merged into the existing fragments that already name those paths, since two ack sources may never name the same path. * fix(#3003): decode git's path quoting instead of changing the git argv The previous commit's non-ASCII fix turned the remote suite red: 44 failures, 42 of them "unexpected git call: -c core.quotepath=false diff --diff-filter=D --name-only ...". The suite's git mocks match on exact argv, so adding two flags to the deletions diff and the advisory diff invalidated every existing fixture in tests/worktree-safety.test.cjs. Rewriting dozens of fixtures to accommodate one flag would be paying a large Hyrum's-law bill to fix a small defect. Both execGit calls are reverted to their original argv. The C-quoting is now decoded in normalizeScopePath instead, via a new decodeGitQuotedPath helper. That is the better fix on its own merits, not merely the cheaper one: the git argv is untouched so no fixture moves, the decode lands on the ONE normalizer already applied to both sides of the comparison so the declared and reported paths cannot disagree, and it holds regardless of the user's own core.quotepath setting rather than only when we remember to override it. A value not wrapped in a leading AND trailing quote is returned completely untouched, so the plain-ASCII path -- the overwhelmingly common case -- is byte-identical to before. Escapes decode to BYTES collected into a Buffer and UTF-8 decoded only at the end, because \303\251 is two bytes forming one character and decoding them separately yields mojibake. Malformed input never throws: a trailing lone backslash or a short octal escape degrades to the literal character, since one bad path must not take down a cleanup wave. Caught while reviewing the helper: the non-escape branch pushed a UTF-16 code unit rather than UTF-8 bytes. Git always escapes non-ASCII so its own output was fine, but this normalizer runs on the DECLARED side too, and an author may write a quoted path holding a literal é -- pushing 0xE9 alone is invalid UTF-8, so the declaration would decode to a replacement character and silently stop matching. That is precisely the failure this change removes, reintroduced on the other side of the comparison. Now converts whole code points, surrogate pairs intact. The other 2 failures: tests/parallel-dependent-plans.test.cjs pins the exact unbackticked substring "files_modified overlap" in gsd-planner.md, and rewording that comment to "declared-scope overlap" deleted it. The comment is restored verbatim and the files_deleted change rides in the pseudocode and the Rule sentence instead. Recorded in the ack fragment so the next contributor does not rediscover it the same way. Four regression tests cover the decode through the public cleanup-wave seam (the helper is module-private): a declared non-ASCII deletion merges against a C-quoted git report, the symmetric case where the DECLARATION is the quoted form, an undeclared non-ASCII deletion still blocks with the residue naming the decoded path an operator can act on, and a path merely containing a quote is left alone. Plain ASCII was already covered and is not duplicated. * fix(#3003): revert the leading-dash flag guard, the review nit was wrong The remote suite came back with 2 failures, down from 44, and both point at the same thing: tests/worktree-safety.test.cjs:7045 already pins the opposite contract, deliberately. test('a flag-shaped --files value is not re-parsed as a flag', ...) recordAgent(['--files', '--branch']) -> files_modified === ['--branch'] -> branch === 'worktree-agent-a1' ("the real --branch value must be untouched") So consuming the next argv element positionally, whatever its shape, is the tested intent of this parser, not an oversight. The security reviewer's nit claimed --deletions --files x would "swallow --files and drop both". It does not: each flag runs its own indexOf, so --deletions records the literal '--files' while --files independently still resolves to x. And that literal is a path git never reports as deleted, so it authorizes nothing -- already fail-closed with no guard at all. The guard bought no safety and silently changed --files behavior along the way, outside this issue's scope. Reverted at both call sites, which are byte-identical again, along with the test asserting the reverted behavior and the docs sentence describing it. The nit is recorded as REJECTED in the review artifact with the reasoning above, rather than as fixed -- a finding that turns out to be wrong should leave a trace of why, or the next reviewer files it again. docs/CLI-TOOLS.md now states the positional-read behavior plainly instead, so the next person meets it as documented intent rather than rediscovering it through a red suite. * chore(#3003): backfill changeset pr number to 3757 * test(#3003): cover parsePlanDocument's filesDeleted branch to clear the mutation gate CI's Stryker shard for plan-document failed at 73.28 against a break threshold of 75: 170 killed, 62 survived, 232 total. Eight of those survivors are the filesDeleted block this issue added to parsePlanDocument, which shipped with no direct coverage at all -- the field was exercised end to end through the cleanup-wave tests, but the parser itself was never called with a plan that declares it, so every mutant in the block lived. Four tests, each pinned to specific mutants rather than written for coverage percentage: - absent key yields exactly [] -- kills the array-literal seed (["Stryker was here"]) and the `fmDeleted = true` conditional, which would otherwise produce ["true"] - a scalar underscore `files_deleted:` wraps into a one-element array -- kills `fmDeleted = false`, the `&&` logical-operator swap, the `fm[""]` string mutation on the first operand, the emptied if-block, and the ternary's non-array branch - an array-valued hyphenated `files-deleted:` maps element-wise -- kills the `fm[""]` mutation on the SECOND operand (only reachable when the legacy hyphen alias is the one carrying the value) and the ternary's array branch - an empty list yields [] -- boundary case, and a genuinely distinct one from the absent key: [] is truthy in JS so it ENTERS the if, and only Array.isArray's true branch mapping over nothing produces the same [] Threshold arithmetic: 174 of 232 are needed for 75%, and these take it to about 178, so the shard clears with margin rather than landing on the line. Every expected value was confirmed by executing the built parser before being asserted, not inferred from reading the source. --------- Co-authored-by: sim <sim@local>
2331 lines
97 KiB
TypeScript
2331 lines
97 KiB
TypeScript
/**
|
||
* 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[];
|
||
/**
|
||
* #3003: paths the PLAN declared it would delete. The deletions guard blocks only
|
||
* deletions NOT in this list. Absent = declares nothing, which keeps the guard's
|
||
* original unconditional block — never "authorizes everything".
|
||
*
|
||
* A path LIST, not a boolean, deliberately: a boolean would disarm the guard for the
|
||
* whole entry, so an unexpected deletion riding along with a declared one would pass
|
||
* unnoticed. Matching is EXACT after `normalizeScopePath`, never a prefix and never a
|
||
* glob — a directory prefix authorizes a mass deletion, which is the precise accident
|
||
* this guard exists to catch.
|
||
*/
|
||
declared_deletions?: 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);
|
||
// #3003: same liberal-in-what-we-accept rule as `files_modified` above — non-array,
|
||
// or non-string / empty elements, are dropped rather than coerced, and an EMPTY
|
||
// result omits the field entirely so "declares nothing" stays indistinguishable
|
||
// from "not recorded" (the guard's own absence-check already treats both as unknown).
|
||
const declaredDeletions = (Array.isArray(e.declared_deletions) ? e.declared_deletions : [])
|
||
.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;
|
||
if (declaredDeletions.length > 0) normalized.declared_deletions = declaredDeletions;
|
||
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';
|
||
|
||
/**
|
||
* Decode a git-quoted path. With `core.quotepath` left at its default (`true`)
|
||
* git wraps any path containing non-ASCII or special bytes in double quotes
|
||
* and C-escapes it — e.g. `tests/é.ts` is emitted as the literal
|
||
* `"tests/\303\251.ts"`. Both sides of the deletion/scope comparison
|
||
* (a declared path and a git-reported path) must agree on the same decoded
|
||
* shape, and decoding it here — rather than passing `-c core.quotepath=false`
|
||
* on the `execGit` call — keeps the git argv, and therefore every existing
|
||
* test fixture that asserts on exact argv, unchanged. It also works
|
||
* regardless of the user's own `core.quotepath` config.
|
||
*
|
||
* A value that is not wrapped in a leading and trailing `"` is returned
|
||
* completely untouched — this is the overwhelmingly common (plain ASCII)
|
||
* case and must not be altered in any way.
|
||
*
|
||
* Escapes decode to BYTES, collected into a Buffer and decoded as UTF-8 only
|
||
* at the end: `\303\251` is two bytes that together form one character (é),
|
||
* so decoding them one at a time would produce mojibake. Malformed input
|
||
* (a trailing lone backslash, or an octal escape with fewer than three
|
||
* digits) never throws — it degrades to treating the character literally, so
|
||
* a single bad path can never take down the whole cleanup wave.
|
||
*/
|
||
function decodeGitQuotedPath(raw: string): string {
|
||
if (raw.length < 2 || !raw.startsWith('"') || !raw.endsWith('"')) return raw;
|
||
const body = raw.slice(1, -1);
|
||
const bytes: number[] = [];
|
||
for (let i = 0; i < body.length; i++) {
|
||
const ch = body[i];
|
||
if (ch !== '\\' || i === body.length - 1) {
|
||
// UTF-8 bytes, not the code unit: a DECLARED path may be quoted while
|
||
// still holding a literal `é`, and pushing 0xE9 alone is invalid UTF-8.
|
||
// codePointAt keeps a surrogate pair together.
|
||
const codePoint = body.codePointAt(i);
|
||
const char = codePoint === undefined ? ch : String.fromCodePoint(codePoint);
|
||
bytes.push(...Buffer.from(char, 'utf8'));
|
||
i += char.length - 1;
|
||
continue;
|
||
}
|
||
const rest = body.slice(i + 1);
|
||
const octalMatch = /^([0-3][0-7][0-7])/.exec(rest);
|
||
if (octalMatch) {
|
||
bytes.push(parseInt(octalMatch[1], 8));
|
||
i += 3;
|
||
continue;
|
||
}
|
||
const next = body[i + 1];
|
||
const CONTROL_ESCAPES: Record<string, number> = {
|
||
a: 0x07, b: 0x08, f: 0x0c, n: 0x0a, r: 0x0d, t: 0x09, v: 0x0b,
|
||
'\\': 0x5c, '"': 0x22,
|
||
};
|
||
if (Object.prototype.hasOwnProperty.call(CONTROL_ESCAPES, next)) {
|
||
bytes.push(CONTROL_ESCAPES[next]);
|
||
} else {
|
||
bytes.push(next.charCodeAt(0));
|
||
}
|
||
i += 1;
|
||
}
|
||
return Buffer.from(bytes).toString('utf8');
|
||
}
|
||
|
||
/**
|
||
* Normalize one path for scope comparison. Applied to BOTH sides so a declared
|
||
* path and a git-reported path meet in the same shape: any git C-quoting is
|
||
* decoded first (order matters — the backslash-to-slash conversion below
|
||
* would destroy the escape sequences if it ran first), then backslashes
|
||
* become slashes unconditionally (a backslash path is not a Windows-only
|
||
* input), and 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 decodeGitQuotedPath(String(raw || '').trim())
|
||
.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;
|
||
}
|
||
|
||
/**
|
||
* #3003: split git's reported deletions into declared and undeclared.
|
||
*
|
||
* EXACT match after `normalizeScopePath` — the same normalizer both other path
|
||
* comparisons in this file use, so a declared path and a git-reported path meet in the
|
||
* same shape (`a\b` and `./a/b/` both become `a/b`).
|
||
*
|
||
* Deliberately NOT `declaredScopePrefix`. That helper returns `null` for a glob-leading
|
||
* pattern meaning "matches everything", which is right for the ADVISORY it serves — a
|
||
* false alarm there costs more than a miss — and exactly wrong for a GATE, where it would
|
||
* let `["*.ts"]` disarm the guard. A glob here is simply a literal path that matches
|
||
* nothing. Prefix matching is likewise refused: `["tests"]` must not authorize deleting
|
||
* everything under tests/.
|
||
*
|
||
* Pure — no git, no IO. Returns the undeclared residue in the order git reported it.
|
||
*/
|
||
function partitionDeclaredDeletions(deletedPaths: unknown, declared: unknown): string[] {
|
||
const allowed = new Set(
|
||
(Array.isArray(declared) ? declared : [])
|
||
.filter((p): p is string => typeof p === 'string')
|
||
.map((p) => normalizeScopePath(p))
|
||
.filter((p) => p.length > 0),
|
||
);
|
||
const undeclared: string[] = [];
|
||
const seen = new Set<string>();
|
||
for (const raw of Array.isArray(deletedPaths) ? deletedPaths : []) {
|
||
if (typeof raw !== 'string') continue;
|
||
const normalized = normalizeScopePath(raw);
|
||
if (!normalized || seen.has(normalized)) continue;
|
||
seen.add(normalized);
|
||
if (allowed.has(normalized)) continue;
|
||
undeclared.push(normalized);
|
||
}
|
||
return undeclared;
|
||
}
|
||
|
||
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) {
|
||
// #3003: a deletion the PLAN declared is authorized; anything else still blocks.
|
||
// Only a SUCCESSFUL check reaches here — a failed one blocked above on its own
|
||
// reason, so a broken check can never be filtered into a pass.
|
||
//
|
||
// The block detail carries ONLY the undeclared residue. Listing declared paths
|
||
// there would misdirect the operator toward paths that were fine.
|
||
const undeclaredDeletions = partitionDeclaredDeletions(
|
||
deletions.stdout.split('\n'),
|
||
entry.declared_deletions,
|
||
);
|
||
if (undeclaredDeletions.length > 0) {
|
||
blockEntry(result, 'branch_contains_deletions', undeclaredDeletions.join('\n'));
|
||
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.
|
||
// #3003: a declared deletion is in scope by construction — `git diff --name-only`
|
||
// includes deleted paths, so without accounting for the declaration, authorizing a
|
||
// deletion would immediately warn that the same path is out of declared scope.
|
||
//
|
||
// It is SUBTRACTED from the findings rather than UNIONED into the declared scope,
|
||
// and the difference is not cosmetic. `planWaveScopeConformance` reads its scope
|
||
// list with prefix-and-glob semantics, so unioning would silently hand
|
||
// `declared_deletions` a second, WIDER matching rule than the gate gives it:
|
||
// `["*.md"]` (inert at the gate) would yield a null prefix meaning "matches
|
||
// everything" and mute the advisory entirely, and `["src"]` would mute all of
|
||
// `src/`. One field with two matching rules is a trap. Subtracting keeps the
|
||
// field exact-match-only on every surface it touches.
|
||
//
|
||
// Gating stays on `files_modified` alone for the same reason: a plan that declares
|
||
// only deletions has still declared no modification scope, so the advisory stays
|
||
// exactly as silent as it was before this change instead of warning on every
|
||
// modified path.
|
||
const declaredFiles = Array.isArray(entry.files_modified) ? entry.files_modified : [];
|
||
if (declaredFiles.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'), declaredFiles, entry.branch)
|
||
// A path-less warning (SCOPE_CHECK_UNAVAILABLE) is never subtracted.
|
||
.filter((w) => w.path === null
|
||
|| partitionDeclaredDeletions([w.path], entry.declared_deletions).length > 0);
|
||
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;
|
||
deletions?: 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);
|
||
// #3003: reuse parseDeclaredScopeFlag — a blank/absent --deletions leaves the
|
||
// entry shape untouched, mirroring the --files rule directly above.
|
||
const declaredDeletions = parseDeclaredScopeFlag(fields.deletions);
|
||
const candidate = {
|
||
agent_id: agentId,
|
||
worktree_path: worktreePath,
|
||
branch,
|
||
expected_base: base,
|
||
...(declaredScope.length > 0 ? { files_modified: declaredScope } : {}),
|
||
...(declaredDeletions.length > 0 ? { declared_deletions: declaredDeletions } : {}),
|
||
};
|
||
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;
|
||
}
|
||
// #3003: same conservative rule as --files above — a blank --deletions
|
||
// leaves the entry shape untouched.
|
||
if (entry.declared_deletions && entry.declared_deletions.length > 0) {
|
||
recorded.declared_deletions = entry.declared_deletions;
|
||
}
|
||
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>"] [--deletions "<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);
|
||
if (i < 0 || i + 1 >= args.length) return '';
|
||
return 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>"] [--deletions "<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'),
|
||
deletions: flag('--deletions'),
|
||
});
|
||
|
||
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;
|
||
deletions?: 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);
|
||
// #3003: reuse parseDeclaredScopeFlag — a blank/absent --deletions leaves the
|
||
// entry shape untouched, mirroring the --files rule directly above.
|
||
const declaredDeletions = parseDeclaredScopeFlag(fields.deletions);
|
||
const candidate = {
|
||
agent_id: agentId,
|
||
worktree_path: worktreePath,
|
||
branch,
|
||
expected_base: base,
|
||
...(declaredScope.length > 0 ? { files_modified: declaredScope } : {}),
|
||
...(declaredDeletions.length > 0 ? { declared_deletions: declaredDeletions } : {}),
|
||
};
|
||
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>"] [--deletions "<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);
|
||
if (i < 0 || i + 1 >= args.length) return '';
|
||
return 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>"] [--deletions "<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'),
|
||
deletions: flag('--deletions'),
|
||
});
|
||
|
||
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;
|
||
}
|
||
// #3003: same conservative rule as --files above — a blank --deletions
|
||
// leaves the entry shape untouched.
|
||
if (Array.isArray(plan.entry.declared_deletions) && plan.entry.declared_deletions.length > 0) {
|
||
recorded.declared_deletions = plan.entry.declared_deletions;
|
||
}
|
||
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,
|
||
};
|