@opengsd/gsd-core 1.8.0 → 1.9.0

package/gsd-core/bin/lib/verify.cjs

@@ -63,14 +63,35 @@ const { MODEL_PROFILES } = modelProfilesMod;
 // Unused but imported for structural parity
 void stripShippedMilestones;
 void schema_detect_cjs_1.detectSchemaFiles;
-function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
-    if (!summaryPath) {
-        error('summary-path required');
-    }
+/**
+ * Pure core of `verify-summary` (#2572).
+ *
+ * Same artifact↔git checks the CLI verb has always run, lifted out of the
+ * `output()` wrapper so other verbs can consume the structured
+ * `{ passed, checks, errors }` contract directly instead of shelling out and
+ * re-parsing JSON. `cmdVerifySummary` is now a thin adapter over this.
+ *
+ * Never throws and never writes to stdout: a missing SUMMARY, a non-repo, or an
+ * unresolvable commit all come back as structured `false`/`missing` values.
+ *
+ * Caveat for callers surfacing `commits_exist`: the hash pattern is a loose
+ * `\b[0-9a-f]{7,40}\b`, so any hex-shaped token in the prose counts as a
+ * candidate. That is cheap as an advisory signal and unacceptable as a gate.
+ *
+ * @param checkFileCount How many extracted candidates to probe. Defaults to 2 —
+ *   the value the CLI verb has always used. Pass `Infinity` to probe every
+ *   candidate (see `cmdPhaseComplete`, which reports on all of them).
+ * @param opts.checkCommits When `false`, the `git cat-file` probes are skipped
+ *   entirely and `commits_exist` comes back `false` meaning *not checked*.
+ *   Callers that do not surface `commits_exist` should pass `false` so this
+ *   stays a pure-filesystem check with no subprocess cost.
+ */
+function verifySummaryCore(cwd, summaryPath, checkFileCount, opts) {
     const fullPath = node_path_1.default.join(cwd, summaryPath);
     const checkCount = checkFileCount || 2;
+    const checkCommits = opts?.checkCommits !== false;
     if (!node_fs_1.default.existsSync(fullPath)) {
-        const result = {
+        return {
             passed: false,
             checks: {
                 summary_exists: false,
@@ -80,21 +101,75 @@ function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
             },
             errors: ['SUMMARY.md not found'],
         };
-        output(result, raw, 'failed');
-        return;
     }
     const content = node_fs_1.default.readFileSync(fullPath, 'utf-8');
     const errors = [];
+    const projectRoot = node_path_1.default.resolve(cwd);
+    /**
+     * Is `candidate` plausibly a repo-relative file this check should probe?
+     *
+     * Deliberately narrowing. This is an ADVISORY, so the two error directions are
+     * not symmetric: a false positive tells a user their healthy project is
+     * missing a file that was never claimed, while a false negative just means one
+     * reference goes unprobed. Every rejection below is a noise class confirmed on
+     * #2685; when in doubt, skip rather than warn.
+     */
+    const isProbableProjectFile = (candidate) => {
+        // Only repo-relative paths — a bare filename is too ambiguous to locate.
+        if (!candidate.includes('/'))
+            return false;
+        // URLs, protocol-relative links, and any other scheme.
+        if (candidate.startsWith('http') || candidate.startsWith('//'))
+            return false;
+        if (/^[a-z][a-z0-9+.-]*:\/\//i.test(candidate))
+            return false;
+        // Globs name a set, not a file: `src/**/*.cts` is never "missing".
+        if (/[*?]/.test(candidate))
+            return false;
+        // Bare hostnames (`docs.example.com/guide.html`). A repo-relative path's
+        // first segment is a directory name, which in practice contains a dot only
+        // when it is a dotfile directory (`.github/`, `.changeset/`, `.planning/`)
+        // — i.e. the dot is at index 0. A dot anywhere later marks a hostname.
+        const firstSegment = candidate.split('/')[0] || '';
+        if (firstSegment.indexOf('.') > 0)
+            return false;
+        // Containment guard: a `../`-bearing reference must not turn this advisory
+        // into a filesystem existence probe outside the project.
+        const resolved = node_path_1.default.resolve(projectRoot, candidate);
+        if (resolved !== projectRoot && !resolved.startsWith(projectRoot + node_path_1.default.sep))
+            return false;
+        return true;
+    };
+    // Pattern 2 excludes `[` and `]` from its path class (#2685 Blocker 1). All
+    // three SUMMARY templates prescribe a YAML flow sequence for `key-files`:
+    //
+    //     key-files:
+    //       created: [src/auth/login.ts, src/auth/session.ts]
+    //
+    // and the label matches `(?:Created|Modified|…):` case-insensitively. Without
+    // the bracket exclusion the class captures the literal `[` as part of the
+    // first path, yielding `[src/auth/login.ts` — a candidate that can never exist
+    // on disk. That fired on healthy projects built from GSD's own shipped
+    // template. The exclusion also stops a markdown list in the body from
+    // reintroducing the same artifact.
+    //
+    // Stripping frontmatter first was the other remedy offered on #2685. It is a
+    // verified no-op on top of this exclusion — measured identical extraction
+    // across all three shipped templates — because the exclusion already makes a
+    // flow-sequence line contribute nothing. Consequence worth naming: the
+    // `key-files` block, the most authoritative statement of what a phase created,
+    // is still not read. Recovering it needs a real frontmatter parse, which is
+    // deliberately left as a follow-up rather than smuggled in here.
     const mentionedFiles = new Set();
     const patterns = [
         /`([^`]+\.[a-zA-Z]+)`/g,
-        /(?:Created|Modified|Added|Updated|Edited):\s*`?([^\s`]+\.[a-zA-Z]+)`?/gi,
+        /(?:Created|Modified|Added|Updated|Edited):\s*`?([^\s`[\]]+\.[a-zA-Z]+)`?/gi,
     ];
     for (const pattern of patterns) {
         let m;
         while ((m = pattern.exec(content)) !== null) {
             const filePath = m[1];
-            if (filePath && !filePath.startsWith('http') && filePath.includes('/')) {
+            if (filePath && isProbableProjectFile(filePath)) {
                 mentionedFiles.add(filePath);
             }
         }
@@ -102,12 +177,12 @@ function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
     const filesToCheck = Array.from(mentionedFiles).slice(0, checkCount);
     const missing = [];
     for (const file of filesToCheck) {
-        if (!node_fs_1.default.existsSync(node_path_1.default.join(cwd, file))) {
+        if (!node_fs_1.default.existsSync(node_path_1.default.resolve(projectRoot, file))) {
             missing.push(file);
         }
     }
     const commitHashPattern = /\b[0-9a-f]{7,40}\b/g;
-    const hashes = content.match(commitHashPattern) || [];
+    const hashes = checkCommits ? content.match(commitHashPattern) || [] : [];
     let commitsExist = false;
     if (hashes.length > 0) {
         for (const hash of hashes.slice(0, 3)) {
@@ -144,8 +219,15 @@ function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
         self_check: selfCheck,
     };
     const passed = missing.length === 0 && selfCheck !== 'failed';
-    const result = { passed, checks, errors };
-    output(result, raw, passed ? 'passed' : 'failed');
+    return { passed, checks, errors };
+}
+/** CLI adapter over verifySummaryCore — arg guard + output shaping only. */
+function cmdVerifySummary(cwd, summaryPath, checkFileCount, raw) {
+    if (!summaryPath) {
+        error('summary-path required');
+    }
+    const result = verifySummaryCore(cwd, summaryPath, checkFileCount);
+    output(result, raw, result.passed ? 'passed' : 'failed');
 }
 /**
  * Issue #429 — negative-grep comment-text echo gate.
@@ -649,13 +731,24 @@ function cmdVerifyPlanStructure(cwd, filePath, raw) {
     if (!filePath) {
         error('file path required');
     }
+    if (filePath.includes('\0')) {
+        error('file path contains null bytes');
+    }
     const fullPath = node_path_1.default.isAbsolute(filePath) ? filePath : node_path_1.default.join(cwd, filePath);
     const content = (0, shell_command_projection_cjs_1.platformReadSync)(fullPath);
     if (!content) {
         output({ error: 'File not found', path: filePath }, raw);
         return;
     }
-    const fm = extractFrontmatter(content);
+    // #2701: fail loud on NUL/binary corruption before structure checks. A
+    // structurally intact-but-NUL-corrupted plan otherwise passes as valid and is
+    // silently skipped by recursive/binary-skipping searchers downstream.
+    const encErr = (0, validate_cjs_2.textEncodingError)(content, filePath);
+    if (encErr) {
+        output({ valid: false, errors: [encErr] }, raw);
+        return;
+    }
+    const fm = extractFrontmatter(content, fullPath);
     const errors = [];
     const warnings = [];
     const required = ['phase', 'plan', 'type', 'wave', 'depends_on', 'files_modified', 'autonomous', 'must_haves'];
@@ -909,7 +1002,7 @@ function collectPromisedFilesAtOrAfterWave(phaseDir, minWave) {
         const planContent = (0, shell_command_projection_cjs_1.platformReadSync)(planFullPath);
         if (!planContent)
             continue;
-        const fm = extractFrontmatter(planContent);
+        const fm = extractFrontmatter(planContent, planFullPath);
         const waveRaw = fm['wave'];
         const wave = typeof waveRaw === 'string' ? parseInt(waveRaw, 10) : (typeof waveRaw === 'number' ? waveRaw : NaN);
         if (isNaN(wave) || wave < minWave)
@@ -944,7 +1037,7 @@ function cmdVerifyKeyLinks(cwd, planFilePath, raw) {
     }
     // Derive the current plan's wave number and phase directory for wave-aware
     // missing-file handling (fix #1202).
-    const currentFm = extractFrontmatter(content);
+    const currentFm = extractFrontmatter(content, fullPath);
     const currentWaveRaw = currentFm['wave'];
     const currentWave = typeof currentWaveRaw === 'string'
         ? parseInt(currentWaveRaw, 10)
@@ -1041,8 +1134,16 @@ function listMilestoneArchiveDirs(planBase) {
             .map((e) => node_path_1.default.join(milestonesDir, e.name))
             .sort((a, b) => node_path_1.default.basename(a).localeCompare(node_path_1.default.basename(b), undefined, { numeric: true }));
     }
-    catch {
-        return [];
+    catch (err) {
+        // #1883: distinguish genuine absence from a permission/I-O failure. ENOENT
+        // (no milestones/ dir yet) keeps the long-standing [] contract that
+        // collectPhaseRoots / forEachArchivedPhaseToken depend on for "no archives";
+        // every other error (EACCES, EIO, …) must propagate — otherwise an unreadable
+        // milestones/ dir is silently reported as "no archives" and active-milestone
+        // resolution / archived-phase filtering misbehaves.
+        if (err.code === 'ENOENT')
+            return [];
+        throw err;
     }
 }
 function forEachArchivedPhaseToken(planBase, onPhase) {
@@ -1215,8 +1316,9 @@ function cmdValidateConsistency(cwd, raw) {
                     }
                 }
                 for (const plan of plans) {
-                    const content = node_fs_1.default.readFileSync(node_path_1.default.join(phasePath, plan), 'utf-8');
-                    const fmData = extractFrontmatter(content);
+                    const planFilePath = node_path_1.default.join(phasePath, plan);
+                    const content = node_fs_1.default.readFileSync(planFilePath, 'utf-8');
+                    const fmData = extractFrontmatter(content, planFilePath);
                     if (!fmData['wave']) {
                         warnings.push(`${phaseLabel}/${plan}: missing 'wave' in frontmatter`);
                     }
@@ -2147,6 +2249,7 @@ module.exports = {
     scanNegativeGrepCommentEcho,
     scanFileWideNegativeGateConflict,
     cmdVerifySummary,
+    verifySummaryCore,
     cmdVerifyPlanStructure,
     cmdVerifyPhaseCompleteness,
     cmdVerifyReferences,
@@ -2158,4 +2261,9 @@ module.exports = {
     cmdValidateAgents,
     cmdVerifySchemaDrift,
     cmdVerifyCodebaseDrift,
+    // Test seam (#1883): listMilestoneArchiveDirs is private and exercised through
+    // the validate command, which runs in a subprocess — an fs monkeypatch in the
+    // test process cannot reach it. Exposed under a leading underscore so the
+    // permission-error path can be unit-tested directly (no chmod 0o000).
+    _listMilestoneArchiveDirs: listMilestoneArchiveDirs,
 };

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

@@ -19,6 +19,8 @@ const shell_command_projection_cjs_1 = require("./shell-command-projection.cjs")
 // providing a deterministic failure path when git stalls (locked index, hung
 // remote, stalled NFS mount, etc.).  Callers can override via deps.timeout.
 const DEFAULT_GIT_TIMEOUT_MS = 10000;
+const WORKTREE_AGENT_BRANCH_RE = /^(worktree-)?agent-[A-Za-z0-9._/-]+$/;
+const WORKTREE_AGENT_BRANCH_PATTERN = WORKTREE_AGENT_BRANCH_RE.source;
 /**
  * Execute a git command via the shell-projection seam, with a derived
  * `timedOut` field. Tests inject mocks via deps.execGit using the new
@@ -302,7 +304,7 @@ function normalizeCleanupManifestEntry(entry) {
     const expectedBase = typeof e.expected_base === 'string' ? e.expected_base : '';
     if (!worktreePath || !branch || !expectedBase)
         return null;
-    if (!/^worktree-agent-[A-Za-z0-9._/-]+$/.test(branch))
+    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) => typeof base === 'string' && base.length > 0)]));
@@ -449,20 +451,18 @@ function rescueSummaryArtifacts(worktreePath, repoRoot, deps) {
         // 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.
         //
-        // Fail-closed on timeout/fatal git errors: if we cannot determine whether
-        // the file is committed, do NOT rescue it (rescuing an actually-committed
-        // file would re-create the untracked collision; the merge will surface the
-        // issue).  The cleanup will be blocked by merge_failed in the worst case,
-        // which is the observable behaviour before this fix and is recoverable.
+        // #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 !== 1) {
-            // Rescue only when cat-file definitively reports the object is absent (exit 1).
-            //   exit 0  → object exists (committed on HEAD) — merge will carry it, skip.
-            //   exit 128 → fatal git error (corrupt store, unborn HEAD, etc.) — uncertain,
-            //              fail-closed: do NOT rescue to avoid recreating the #706 collision.
-            //   timedOut / null / other → unreliable result — same fail-closed policy.
-            // In all non-1 cases the merge will either succeed naturally (0) or surface
-            // the problem safely (128/timeout), which is the recoverable pre-fix behaviour.
+        if (catFileResult.exitCode === 0) {
+            // exit 0 → the SUMMARY is committed on HEAD; the merge will carry it, so skip rescue.
             continue;
         }
         const dest = node_path_1.default.join(repoRoot, relPath);
@@ -751,7 +751,7 @@ function planWorktreeRecordAgent(manifestRaw, fields) {
         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-[A-Za-z0-9._/-]+$ (got branch="${branch}"). Fix the field and re-run.`,
+            hint: `Entry failed cleanup-manifest validation: --path/--branch/--base must be non-empty and --branch must match ${WORKTREE_AGENT_BRANCH_PATTERN} (accepts both agent-<id> and worktree-agent-<id> namespaces; got branch="${branch}"). Fix the field and re-run.`,
             entry: null,
             manifest: null,
         };
@@ -893,6 +893,348 @@ function cmdWorktreeRecordAgent(cwd, args = [], deps = {}) {
     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 };
 }
+/**
+ * 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) {
+    const agentId = (fields.agentId || '').trim();
+    const worktreePath = (fields.worktreePath || '').trim();
+    const branch = (fields.branch || '').trim();
+    const base = (fields.base || '').trim();
+    const missing = [];
+    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 candidate = {
+        agent_id: agentId,
+        worktree_path: worktreePath,
+        branch,
+        expected_base: base,
+    };
+    const entry = normalizeCleanupManifestEntry(candidate);
+    if (!entry) {
+        return {
+            ok: false,
+            reason: 'invalid_entry',
+            hint: `Entry failed cleanup-manifest validation: --path/--branch/--base must be non-empty and --branch must match ${WORKTREE_AGENT_BRANCH_PATTERN} (accepts both agent-<id> and worktree-agent-<id> namespaces; got branch="${branch}"). Fix the field and re-run.`,
+            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 };
+}
+/**
+ * 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, worktreePath, repoRoot) {
+    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, repoRoot, deps = {}) {
+    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 = (0, shell_command_projection_cjs_1.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,
+    };
+}
+/**
+ * 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>
+ *
+ * #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, args = [], deps = {}) {
+    const flag = (name) => {
+        const i = args.indexOf(name);
+        return i >= 0 && i + 1 < args.length ? args[i + 1] : '';
+    };
+    const write = deps.write || ((s) => process.stdout.write(s));
+    const writeErr = deps.writeErr || ((s) => process.stderr.write(s));
+    const manifestPath = flag('--manifest');
+    if (!manifestPath) {
+        writeErr('Usage: worktree create --manifest <path> --agent-id <id> --path <worktree> --branch <branch> --base <sha> [--root <dir>]\n');
+        process.exitCode = 2;
+        return { ok: false, reason: 'usage' };
+    }
+    // 1. Read the manifest (no side effect yet).
+    const resolved = node_path_1.default.resolve(cwd, manifestPath);
+    const readFile = deps.readFile || ((p) => node_fs_1.default.readFileSync(p, 'utf8'));
+    let manifestRaw;
+    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.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;
+    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;
+    let writeBack;
+    if (Array.isArray(parsed)) {
+        worktrees = parsed;
+        writeBack = worktrees;
+    }
+    else if (parsed && typeof parsed === 'object') {
+        const container = parsed;
+        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'),
+    });
+    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. Optional root confinement (#2627, Phase 3 — the confinement Phase 2
+    //     deferred here from planWorktreeCreate's path-traversal guard).
+    //     planWorktreeCreate rejects a literal ".." SEGMENT, but a plain absolute
+    //     path outside the project contains no ".." and passes. Phase 3 makes the
+    //     orchestrator SPAWN executor processes into these paths, so an
+    //     unconfined --path is a write primitive aimed anywhere on the filesystem.
+    //
+    //     The root is DECLARED by the caller (`--root`) rather than inferred: agent
+    //     worktrees legitimately live outside the orchestrator's own root (a lane
+    //     orchestrator creates siblings under the repo's .claude/worktrees/), so
+    //     there is no layout this module could derive without guessing. Absent
+    //     `--root` the behavior is exactly as shipped in Phase 2 — the
+    //     orchestrator-worktree scheduler path always passes it.
+    //
+    //     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.
+    const rootFlag = flag('--root');
+    if (rootFlag) {
+        const absRoot = node_path_1.default.resolve(cwd, rootFlag);
+        const absWorktree = node_path_1.default.resolve(cwd, plan.entry.worktree_path);
+        const rel = node_path_1.default.relative(absRoot, absWorktree);
+        // 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(`..${node_path_1.default.sep}`) || node_path_1.default.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 = {
+        agent_id: plan.entry.agent_id,
+        worktree_path: plan.entry.worktree_path,
+        branch: plan.entry.branch,
+        expected_base: plan.entry.expected_base,
+    };
+    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, content) => node_fs_1.default.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.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.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
@@ -1180,6 +1522,9 @@ module.exports = {
     cmdWorktreeCleanupWave,
     planWorktreeRecordAgent,
     cmdWorktreeRecordAgent,
+    planWorktreeCreate,
+    executeWorktreeCreatePlan,
+    cmdWorktreeCreate,
     reapOrphanWorktrees,
     cmdWorktreeReapOrphans,
     resolveWorktreeRoot,