@pugi/cli 0.1.0-beta.11 → 0.1.0-beta.13

package/dist/core/consensus/diff-capture.js

@@ -6,6 +6,10 @@
  *
  *   1. `--pr <number>`    — uses `gh pr diff <num>` (gh CLI required).
  *   2. `--commit <sha>`   — diff of that commit vs its first parent.
+ *                           When `--base <ref>` is ALSO provided, the
+ *                           diff is the range `<base>..<commit>` instead
+ *                           (mirrors `git diff base..commit` — covers the
+ *                           full PR-style payload, not just the tip).
  *   3. `--branch <name>`  — diff of HEAD vs `origin/<name>` merge-base.
  *   4. (default)          — diff of HEAD vs `origin/main` merge-base
  *                           covering BOTH committed-since-base AND
@@ -95,6 +99,16 @@ export function captureDiff(spec) {
         return captureFromPr(cwd, spec.pr);
     }
     if (typeof spec.commit === 'string' && spec.commit.length > 0) {
+        // When `--base` is supplied alongside `--commit`, callers want the
+        // full PR-style range diff (`base..commit`), not just the tip
+        // commit's parent diff. This matches the convention used by
+        // `git diff <base>..<commit>` everywhere else in the toolchain and
+        // is the verified-correct mode for reviewing a PR head ref. Without
+        // this branch, `--base` was silently ignored when `--commit` was
+        // present — see feedback_pugi_review_use_range_diff_not_worktree.
+        if (typeof spec.baseRef === 'string' && spec.baseRef.length > 0) {
+            return captureFromRange(cwd, spec.baseRef, spec.commit);
+        }
         return captureFromCommit(cwd, spec.commit);
     }
     if (typeof spec.branch === 'string' && spec.branch.length > 0) {
@@ -192,6 +206,65 @@ function captureFromCommit(cwd, commit) {
         },
     };
 }
+/**
+ * Range capture for `--commit <X> --base <Y>` — diff equivalent to
+ * `git diff <base>..<commit>`. Used when the operator names BOTH endpoints
+ * (typical PR review against a remote head SHA).
+ *
+ * Critical: this MUST be a pure read-only range diff against named refs.
+ * The previous behavior fell through to `captureFromCommit` which only
+ * showed the tip commit (`commit~1..commit`) — fine for single-commit
+ * review, wrong for multi-commit PRs. Worse, a stale fallback path was
+ * sending the working tree diff (`git diff` with no args), which caused
+ * every review on 2026-05-27 to surface identical noise from uncommitted
+ * `.gitignore` edits instead of the actual PR contents.
+ *
+ * Working tree integrity: only `git diff <ref>..<ref>` and metadata
+ * `log` / `rev-parse` / `name-rev` are used — none of these touch the
+ * index, working tree, or HEAD.
+ */
+function captureFromRange(cwd, baseRef, commit) {
+    // Resolve both endpoints up front so an unknown ref errors with a
+    // clear message before the diff invocation. `rev-parse` is read-only.
+    const fullCommit = safeExec(cwd, 'git', ['rev-parse', commit]).trim();
+    if (!fullCommit)
+        throw new Error(`Unknown commit ref: ${commit}`);
+    // Resolve the base: accept already-qualified refs (`origin/main`,
+    // `refs/heads/foo`) and bare branch names. If the bare name isn't
+    // locally resolvable, retry against `origin/<name>` — the common
+    // CI shape where local main is absent but the remote tracking ref is.
+    let resolvedBase = safeExecOptional(cwd, 'git', ['rev-parse', baseRef]).trim();
+    let effectiveBase = baseRef;
+    if (!resolvedBase && !baseRef.includes('/')) {
+        const remoteBase = `origin/${baseRef}`;
+        resolvedBase = safeExecOptional(cwd, 'git', ['rev-parse', remoteBase]).trim();
+        if (resolvedBase)
+            effectiveBase = remoteBase;
+    }
+    if (!resolvedBase)
+        throw new Error(`Unknown base ref: ${baseRef}`);
+    const diff = safeExec(cwd, 'git', [
+        'diff',
+        `${resolvedBase}..${fullCommit}`,
+        '--',
+        '.',
+        ...PROTECTED_PATHSPEC_EXCLUDES,
+    ]);
+    const cappedDiff = capDiff(diff);
+    const subject = safeExec(cwd, 'git', ['log', '-1', '--pretty=%s', fullCommit]).trim();
+    const branch = safeExec(cwd, 'git', ['name-rev', '--name-only', fullCommit]).trim() || 'detached';
+    const stats = computeStats(cappedDiff);
+    return {
+        diff: cappedDiff,
+        context: {
+            branch,
+            commit: shortSha(fullCommit),
+            title: subject || `commit ${shortSha(fullCommit)}`,
+            ref: `range:${effectiveBase}..${shortSha(fullCommit)}`,
+            stats,
+        },
+    };
+}
 function captureFromBranch(cwd, branch, baseRef) {
     const remoteRef = branch.includes('/') ? branch : `origin/${branch}`;
     const mergeBase = safeExec(cwd, 'git', ['merge-base', baseRef, remoteRef]).trim();

package/dist/core/context/index.js

@@ -18,4 +18,11 @@ export { BASELINE_IGNORE_PATTERNS, SECRET_IGNORE_PATTERNS, globalPugiIgnorePath,
 export { COLLAPSE_DIR_ENTRIES, MAX_README_LINES, MAX_SKELETON_BYTES, MAX_TREE_DEPTH, MAX_WALK_NODES, TOP_LANGUAGES, buildRepoSkeleton, detectPackageManager, languageForExtension, readGitBranch, readPackageJson, readReadme, renderSkeleton, topLanguages, } from './repo-skeleton.js';
 export { DEFAULT_WORKING_SET_CAPACITY, WorkingSet, } from './working-set.js';
 export { MAX_WATCHED_PATHS, PugiWatcher, THROTTLE_WINDOW_MS, } from './watcher.js';
+/**
+ * β5a R4+P5 — per-directory PUGI.md / AGENTS.md / CLAUDE.md / GEMINI.md
+ * traverse-up. Loads agent-context markdown at every directory between
+ * `cwd` and `workspaceRoot` (workspace root file is owned by
+ * `loadMarkdownContext` in `markdown-loader.ts` — no double-load).
+ */
+export { MAX_TRAVERSE_BYTES, MAX_TRAVERSE_PER_FILE_BYTES, MAX_TRAVERSE_DEPTH, TRAVERSE_SOURCES, loadTraversedMarkdown, } from './markdown-traverse.js';
 //# sourceMappingURL=index.js.map

package/dist/core/context/markdown-traverse.js

@@ -0,0 +1,255 @@
+/**
+ * Per-directory PUGI.md / AGENTS.md / CLAUDE.md / GEMINI.md traverse-up
+ * loader — β5a R4+P5.
+ *
+ * Claude Code, Codex CLI, and Gemini CLI all support a "walk up from
+ * cwd to the workspace root, pick up agent-context markdown at every
+ * level" pattern. Without this, a `pugi explain` invoked from
+ * `apps/admin-api/` cannot see project-local conventions encoded in
+ * `apps/admin-api/PUGI.md` (or the cross-CLI shim files) — the
+ * existing `loadMarkdownContext` only reads files at `workspaceRoot`.
+ *
+ * The β5a quality gate (≥80% win-rate vs Claude Code per CEO 2026-05-26)
+ * surfaces this gap repeatedly: monorepo-local conventions (NestJS
+ * controller style, Prisma migration name format, cabinet brand voice
+ * gates) live in per-app context files, and Pugi was blind to them
+ * pre-β5a.
+ *
+ * Contract:
+ *
+ *   - Walk from `cwd` upward until we reach `workspaceRoot` OR cross
+ *     the filesystem boundary. The workspace root file itself is
+ *     loaded by the legacy `loadMarkdownContext` so we do NOT include
+ *     it here (no double-load, no double-budget-charge).
+ *
+ *   - At each intermediate directory, look for the four canonical
+ *     filenames: `PUGI.md` (native), `AGENTS.md` (cross-CLI shim),
+ *     `CLAUDE.md` (Claude Code compat), `GEMINI.md` (Gemini CLI compat).
+ *
+ *   - HTML comments stripped, identical to the legacy loader.
+ *
+ *   - `@import` expansion is intentionally NOT performed here — the
+ *     per-dir surface is "drop a small file with the local
+ *     conventions"; deep @import chains belong at workspace root.
+ *     Keeping this surface flat means the per-dir budget cannot be
+ *     blown out by a runaway @import in an unrelated subtree.
+ *
+ *   - Aggregate budget: `MAX_TRAVERSE_BYTES` across ALL files found
+ *     in the walk. When exhausted, remaining files are skipped with
+ *     a `budget_exhausted` warning. Default 32 KB — half the
+ *     workspace-root budget, because per-dir files are meant to be
+ *     terse delta conventions, not full project briefs.
+ *
+ *   - The walk is bounded: `MAX_TRAVERSE_DEPTH` levels above
+ *     workspaceRoot are NEVER traversed (defense against being
+ *     invoked from a malicious cwd outside the workspace; in
+ *     practice cwd is always inside workspaceRoot but the symlink
+ *     case demands belt + suspenders).
+ *
+ *   - Order returned: shallowest-first (workspace root would be
+ *     first if included, then each level closer to cwd). Closest-
+ *     to-cwd files are the most specific and the context builder
+ *     emits them LAST so the model treats them as the highest-
+ *     priority conventions.
+ *
+ * This module is pure: no logging, no network, no fs writes. Filesystem
+ * reads only.
+ */
+import { existsSync, readFileSync, realpathSync, statSync } from 'node:fs';
+import { dirname, isAbsolute, relative, resolve, sep } from 'node:path';
+import { stripHtmlComments } from './markdown-loader.js';
+/**
+ * Per-traverse total byte cap. Half the workspace-root budget — these
+ * files are meant to be terse "in this subdir, do X". 32 KB still fits
+ * ~8000 words of guidance.
+ */
+export const MAX_TRAVERSE_BYTES = 32 * 1024;
+/**
+ * Per-file byte cap. A single per-dir file should never dominate; the
+ * 8 KB cap keeps any one level honest. Files larger than this are
+ * loaded up to the cap and flagged truncated.
+ */
+export const MAX_TRAVERSE_PER_FILE_BYTES = 8 * 1024;
+/**
+ * Maximum number of parent directories above workspaceRoot we will
+ * traverse. Zero in normal operation — cwd is always inside the
+ * workspace; the cap exists so a misconfigured invocation never
+ * walks the whole filesystem looking for AGENTS.md.
+ */
+export const MAX_TRAVERSE_DEPTH = 0;
+/**
+ * Filenames we look for at every level of the walk. The order here
+ * also defines the per-directory load order: PUGI.md first (highest
+ * trust), then cross-CLI compat shims. When the same directory has
+ * multiple files (e.g. both PUGI.md AND CLAUDE.md), all are loaded
+ * — operators sometimes keep both during a tool migration.
+ */
+export const TRAVERSE_SOURCES = ['PUGI.md', 'AGENTS.md', 'CLAUDE.md', 'GEMINI.md'];
+/**
+ * Walk from `opts.cwd` upward toward `opts.workspaceRoot`, loading
+ * every PUGI.md / AGENTS.md / CLAUDE.md / GEMINI.md we encounter at
+ * intermediate levels. The workspace root itself is NOT loaded here
+ * — `loadMarkdownContext(workspaceRoot)` owns that file.
+ *
+ * Returned `loaded` is sorted shallowest-first (closest-to-root) so
+ * the caller can emit per-dir context in increasing specificity.
+ *
+ * Safety properties (proven by spec):
+ *
+ *   - Never reads outside the workspace tree (symlinks resolved via
+ *     realpathSync; off-tree symlinks rejected as
+ *     `import_escapes_workspace`).
+ *   - Never reads more than `MAX_TRAVERSE_BYTES` total or more than
+ *     `MAX_TRAVERSE_PER_FILE_BYTES` per file.
+ *   - Never walks above the workspace root.
+ *   - Never visits the workspace root itself (single source of truth
+ *     for workspace-level docs stays with `loadMarkdownContext`).
+ */
+export async function loadTraversedMarkdown(opts) {
+    const warnings = [];
+    const loaded = [];
+    let budgetRemaining = MAX_TRAVERSE_BYTES;
+    let absRoot;
+    let absCwd;
+    try {
+        absRoot = realpathSync(resolve(opts.workspaceRoot));
+        absCwd = realpathSync(resolve(opts.cwd));
+    }
+    catch (error) {
+        warnings.push({
+            kind: 'read_error',
+            message: `realpath failed for traverse anchor: ${error.message}`,
+        });
+        return { loaded, warnings, totalBytes: 0 };
+    }
+    // Containment guard: if cwd is not inside workspaceRoot, refuse
+    // to walk. Returning a clean empty result keeps the engine happy
+    // and surfaces nothing about the off-tree cwd to the model.
+    const relCwd = relative(absRoot, absCwd);
+    if (relCwd.startsWith('..') || isAbsolute(relCwd)) {
+        warnings.push({
+            kind: 'import_escapes_workspace',
+            message: `cwd is outside workspaceRoot; per-dir traverse skipped (cwd=${absCwd}, root=${absRoot})`,
+            path: absCwd,
+        });
+        return { loaded, warnings, totalBytes: 0 };
+    }
+    // Collect the walk: every directory from cwd UP TO (but not
+    // including) workspaceRoot.
+    const dirsToVisit = [];
+    let current = absCwd;
+    while (current !== absRoot) {
+        dirsToVisit.push(current);
+        const parent = dirname(current);
+        if (parent === current)
+            break; // hit filesystem root before workspaceRoot — defensive
+        current = parent;
+        if (dirsToVisit.length > 64)
+            break; // pathological depth, refuse
+    }
+    // Walk shallowest-first so we charge the budget in the order
+    // that matches what we return.
+    dirsToVisit.reverse();
+    for (const dir of dirsToVisit) {
+        if (budgetRemaining <= 0) {
+            warnings.push({
+                kind: 'budget_exhausted',
+                message: `per-dir traverse budget exhausted before reaching ${dir}`,
+                path: dir,
+            });
+            break;
+        }
+        for (const source of TRAVERSE_SOURCES) {
+            const candidate = resolve(dir, source);
+            if (!existsSync(candidate))
+                continue;
+            // Symlink guard: same realpath check as the workspace-root
+            // loader. A symlink inside the workspace that points outside
+            // the workspace must NOT be inlined.
+            let realCandidate;
+            try {
+                realCandidate = realpathSync(candidate);
+            }
+            catch (error) {
+                warnings.push({
+                    kind: 'read_error',
+                    message: `realpath failed for ${candidate}: ${error.message}`,
+                    path: candidate,
+                });
+                continue;
+            }
+            const realRel = relative(absRoot, realCandidate);
+            if (realRel.startsWith('..') || isAbsolute(realRel)) {
+                warnings.push({
+                    kind: 'import_escapes_workspace',
+                    message: `traverse file escapes workspace via symlink: ${candidate} -> ${realCandidate}`,
+                    path: candidate,
+                });
+                continue;
+            }
+            let raw;
+            let rawBytes;
+            try {
+                rawBytes = statSync(candidate).size;
+                raw = readFileSync(candidate, 'utf8');
+            }
+            catch (error) {
+                warnings.push({
+                    kind: 'read_error',
+                    message: `could not read ${candidate}: ${error.message}`,
+                    path: candidate,
+                });
+                continue;
+            }
+            const stripped = stripHtmlComments(raw);
+            // Per-file cap first, then global budget.
+            const perFileCap = Math.min(MAX_TRAVERSE_PER_FILE_BYTES, budgetRemaining);
+            let content = stripped;
+            let truncated = false;
+            let contentBytes = Buffer.byteLength(content, 'utf8');
+            if (contentBytes > perFileCap) {
+                // Codepoint-safe slice: convert byte cap to char cap by
+                // taking min(byte cap, char-length-up-to-cap). We accept
+                // mild over-trim for safety.
+                content = content.slice(0, perFileCap);
+                truncated = true;
+                contentBytes = Buffer.byteLength(content, 'utf8');
+            }
+            const distance = distanceSegments(absCwd, dir);
+            loaded.push({
+                source,
+                resolvedPath: candidate,
+                dir,
+                distanceFromCwd: distance,
+                rawBytes,
+                loadedBytes: contentBytes,
+                truncated,
+                content,
+            });
+            budgetRemaining -= contentBytes;
+            if (budgetRemaining <= 0)
+                break;
+        }
+    }
+    return {
+        loaded,
+        warnings,
+        totalBytes: MAX_TRAVERSE_BYTES - budgetRemaining,
+    };
+}
+/**
+ * How many path segments separate `from` and `to`. Both must be
+ * absolute. `to` is assumed to be an ancestor of (or equal to)
+ * `from`; if not, returns -1 so callers can ignore the file.
+ */
+function distanceSegments(from, to) {
+    if (from === to)
+        return 0;
+    const rel = relative(to, from);
+    if (rel.startsWith('..') || isAbsolute(rel))
+        return -1;
+    if (rel.length === 0)
+        return 0;
+    return rel.split(sep).length;
+}
+//# sourceMappingURL=markdown-traverse.js.map

package/dist/core/edits/dispatch.js

@@ -1,5 +1,6 @@
 /**
- * Diff dispatch — α6.6 escalation Phase 1.
+ * Diff dispatch — α6.6 escalation Phase 1, β1b Pl8 transactional layer
+ * (2026-05-26).
  *
  * Reads a raw model response containing one or more SEARCH/REPLACE
  * envelopes, normalises them through `marker-parser`, and routes each
@@ -21,16 +22,36 @@
  * the writeFile. A crash between the two leaves a recoverable trail —
  * the operator (or `pugi resume`) sees the intent and can re-attempt.
  *
+ * β1b Pl8 — transactional rollback: when the caller supplies
+ * `transactional: { sessionId, taskId, workspaceRoot }`, the dispatcher
+ * wraps the multi-file edits in a session journal (see
+ * `core/edits/journal.ts`). On non-zero exit / budget kill / partial
+ * fail it runs `rollbackDispatch()`:
+ *
+ *   - tracked files that EXISTED before → `git restore -- <file>`
+ *   - newly created files (existed=false) → `fs.unlink`
+ *   - untracked files that EXISTED before → restore from in-memory
+ *     pre-content snapshot (sha256_before validated)
+ *
+ * Pattern mirrors `tools/apply-patch.ts::rollbackFiles` (PR #413). The
+ * journal is the durability layer that lets a process crash recover
+ * across PIDs; the in-memory snapshot covers the single-process case
+ * where the journal write itself failed.
+ *
  * The dispatcher is intentionally side-effect-light: no logging, no
  * stdout writes, no exit-code mutation. The CLI integration layer in
  * `cli.ts` owns operator-facing rendering; the dispatcher returns
  * structured data and lets the caller decide UX.
  */
+import { spawnSync } from 'node:child_process';
+import { readFileSync, rmSync, writeFileSync } from 'node:fs';
+import { resolve, sep } from 'node:path';
 import { LayerDDeferredError, applyLayerD } from './layer-d-ast.js';
 import { applyLayerA } from './layer-a-apply.js';
 import { applyLayerB } from './layer-b-apply.js';
 import { applyLayerC } from './layer-c-apply.js';
 import { MarkerParseError, parseMarkers, } from './marker-parser.js';
+import { appendEntry, snapshotForDispatch, } from './journal.js';
 /**
  * Parse `raw` into edits and apply each in order. Aggregate results,
  * preserving order. Never throws — parse failures surface as a single
@@ -65,13 +86,208 @@ export async function dispatchEdit(raw, opts) {
         // render "no edits proposed".
         return [];
     }
+    // β1b Pl8 — transactional path. When enabled, snapshot every target
+    // file BEFORE the first applicator runs so we can roll back if a
+    // later edit fails. Snapshot also drives the journal entry so a
+    // post-crash recovery can replay rollback in a fresh process.
+    //
+    // The journal write itself is best-effort: a disk-full / EACCES
+    // failure must NOT block the dispatch. The in-memory snapshot
+    // still carries every pre-existing file's content, so single-
+    // process rollback degrades cleanly. The operator sees the
+    // journal-failed warning via the session events mirror (caller's
+    // responsibility to emit).
+    let snapshot = null;
+    let preContent = null;
+    if (opts.transactional && !opts.dryRun) {
+        const targets = Array.from(new Set(parsed.map((e) => editFile(e))));
+        snapshot = snapshotForDispatch(opts.transactional.workspaceRoot, targets);
+        preContent = new Map();
+        for (const e of snapshot) {
+            if (!e.existed)
+                continue;
+            const abs = resolve(opts.transactional.workspaceRoot, e.path);
+            try {
+                preContent.set(e.path, readFileSync(abs));
+            }
+            catch {
+                /* file vanished between snapshot + read — treat as not-snapshotted */
+            }
+        }
+        appendEntry(opts.transactional.workspaceRoot, opts.transactional.sessionId, {
+            ts: Date.now(),
+            taskId: opts.transactional.taskId,
+            files: snapshot,
+        });
+    }
     const out = [];
+    let crashError = null;
     for (const edit of parsed) {
         const intent = makeIntent(edit);
         opts.onIntent?.(intent);
-        const result = await applyOne(edit, opts);
+        let result;
+        try {
+            result = await applyOne(edit, opts);
+        }
+        catch (error) {
+            // applyOne does not throw today (errors are returned as
+            // `ok: false`), but a future applicator that does throw —
+            // or a budget-kill that arrives mid-write — needs deterministic
+            // rollback. Catch + record + break so the rollback below runs.
+            crashError = error;
+            const msg = error instanceof Error ? error.message : String(error);
+            result = {
+                layer: 'layer-a',
+                file: editFile(edit),
+                ok: false,
+                bytesWritten: 0,
+                reason: 'apply_error',
+                detail: `dispatch threw: ${msg}`,
+            };
+        }
         out.push(result);
         opts.onResult?.(result);
+        if (!result.ok && opts.transactional && snapshot && preContent) {
+            // Rollback every snapshotted file then break out — partial
+            // success is unacceptable in transactional mode.
+            const rollback = rollbackDispatch(opts.transactional.workspaceRoot, snapshot, preContent);
+            if (!rollback.ok) {
+                // Surface the rollback failure as an additional synthetic
+                // result so the caller can render the operator-facing
+                // message without losing the original failure context.
+                const failure = {
+                    layer: 'layer-a',
+                    file: '',
+                    ok: false,
+                    bytesWritten: 0,
+                    reason: 'rollback_failed',
+                    detail: rollback.detail,
+                };
+                out.push(failure);
+                opts.onResult?.(failure);
+            }
+            if (crashError) {
+                // Re-throw post-rollback so the caller learns the dispatch
+                // crashed (vs returned ok: false). Rollback already completed
+                // so the workspace is consistent.
+                throw crashError;
+            }
+            break;
+        }
+    }
+    return out;
+}
+/**
+ * Workspace-relative path for a parsed edit, regardless of layer.
+ * Hoisted because the snapshot + intent both need the same answer.
+ */
+function editFile(edit) {
+    switch (edit.kind) {
+        case 'layer-a':
+        case 'layer-b':
+        case 'layer-c':
+        case 'layer-d':
+            return edit.edit.file;
+    }
+}
+/**
+ * Roll the workspace back to the pre-dispatch state captured in
+ * `snapshot`. Mirrors `tools/apply-patch.ts::rollbackFiles`:
+ *
+ *   - existed-before + git-tracked → `git restore -- <file>` (cheap
+ *     + atomic against the index).
+ *   - existed-before + untracked   → restore from the in-memory
+ *     preContent buffer (sha256_before validates the snapshot still
+ *     matches what we hold; if not we punt with `partial_rollback`).
+ *   - newly created                → fs.unlink (force).
+ *
+ * Best-effort: every per-file failure is collected into the detail
+ * string so the operator can manually fix the residual state. The
+ * dispatcher does not abort on the first error so an unrelated
+ * permission glitch on one file doesn't strand the others.
+ *
+ * Exported for the spec suite + a future operator command
+ * (`pugi resume --rollback <taskId>` ships in β2).
+ */
+export function rollbackDispatch(workspaceRoot, snapshot, preContent) {
+    if (snapshot.length === 0)
+        return { ok: true };
+    // Filter to workspace-internal paths only. A snapshot entry that
+    // escaped the workspace would already have aborted upstream; the
+    // filter is belt + braces against a future bug.
+    const safe = snapshot.filter((e) => {
+        const abs = resolve(workspaceRoot, e.path);
+        return abs === workspaceRoot || abs.startsWith(workspaceRoot + sep);
+    });
+    const failures = [];
+    const tracked = listTrackedFiles(workspaceRoot, safe.map((e) => e.path));
+    for (const entry of safe) {
+        const abs = resolve(workspaceRoot, entry.path);
+        if (!entry.existed) {
+            try {
+                // β1b r1: `recursive: true` so rollback handles the case where
+                // the dispatcher created an intermediate directory (e.g. a new
+                // `src/feature/` tree). Without it the unlink fails on a dir
+                // and the journal-replay leaves an orphan workspace path.
+                rmSync(abs, { force: true, recursive: true });
+            }
+            catch (error) {
+                failures.push(`${entry.path}: unlink failed: ${error instanceof Error ? error.message : String(error)}`);
+            }
+            continue;
+        }
+        if (tracked.has(entry.path)) {
+            const result = spawnSync('git', ['restore', '--', entry.path], {
+                cwd: workspaceRoot,
+                encoding: 'utf8',
+            });
+            if (result.status !== 0) {
+                failures.push(`${entry.path}: git restore failed: ${(result.stderr ?? '').trim() || 'non-zero exit'}`);
+            }
+            continue;
+        }
+        // Untracked-but-existed: write back from memory.
+        const buf = preContent.get(entry.path);
+        if (!buf) {
+            failures.push(`${entry.path}: pre-content snapshot missing (partial rollback)`);
+            continue;
+        }
+        try {
+            writeFileSync(abs, buf);
+        }
+        catch (error) {
+            failures.push(`${entry.path}: rewrite failed: ${error instanceof Error ? error.message : String(error)}`);
+        }
+    }
+    if (failures.length === 0)
+        return { ok: true };
+    return { ok: false, detail: failures.join('; ') };
+}
+/**
+ * Ask git which of `paths` are tracked. A single `git ls-files
+ * --error-unmatch` call would fail-fast on the first untracked path,
+ * so we use `git ls-files -- <paths...>` which lists only tracked
+ * matches. Returns a Set of workspace-relative paths.
+ *
+ * Pure-stdlib fallback when git is unavailable: returns an empty
+ * Set — every "existed" entry then routes to the untracked-restore
+ * path via the in-memory preContent map. Slower per file but still
+ * correct.
+ */
+function listTrackedFiles(cwd, paths) {
+    if (paths.length === 0)
+        return new Set();
+    const result = spawnSync('git', ['ls-files', '--', ...paths], {
+        cwd,
+        encoding: 'utf8',
+    });
+    if (result.status !== 0)
+        return new Set();
+    const out = new Set();
+    for (const line of (result.stdout ?? '').split('\n')) {
+        const trimmed = line.trim();
+        if (trimmed.length > 0)
+            out.add(trimmed);
     }
     return out;
 }