@karmaniverous/jeeves-watcher 0.19.0 → 0.19.1

package/dist/index.js

@@ -403,6 +403,7 @@ function computeDelayMs(attempt, baseDelayMs, maxDelayMs, jitter = 0) {
  */
 async function retry(fn, options) {
     const attempts = Math.max(1, options.attempts);
+    const shouldRetry = options.shouldRetry ?? (() => true);
     let lastError;
     for (let attempt = 1; attempt <= attempts; attempt++) {
         try {
@@ -411,7 +412,7 @@ async function retry(fn, options) {
         catch (error) {
             lastError = error;
             const isLast = attempt >= attempts;
-            if (isLast)
+            if (isLast || !shouldRetry(error))
                 break;
             const delayMs = computeDelayMs(attempt, options.baseDelayMs, options.maxDelayMs, options.jitter);
             options.onRetry?.({ attempt, attempts, delayMs, error });
@@ -423,10 +424,28 @@ async function retry(fn, options) {
 
 /**
  * @module vcs/gitExec
- * Shared git execution utilities.
+ * Shared git execution utilities: the pinned argv prefix, timeouts, error
+ * field extraction and classification, and path comparison helpers.
  */
 /** Promisified execFile for git commands. */
 const execFileAsync = promisify(execFile);
+/**
+ * Leading git arguments applied to every VCS-owned git invocation.
+ *
+ * `-c core.longpaths=true` lets Windows checkouts handle paths beyond the
+ * legacy MAX_PATH limit (260 chars) without requiring a machine-wide
+ * `core.longpaths` git config or registry change. See #249.
+ */
+const GIT_BASE_ARGS = ['-c', 'core.longpaths=true'];
+/**
+ * Build a git argv array with {@link GIT_BASE_ARGS} prefixed.
+ *
+ * @param args - The subcommand and its arguments (e.g. `'commit', '-m', msg`).
+ * @returns The full argv array, base args first.
+ */
+function gitArgs(...args) {
+    return [...GIT_BASE_ARGS, ...args];
+}
 /** Standard timeout (ms) for most git operations. */
 const GIT_TIMEOUT_STANDARD = 30_000;
 /** Extended timeout (ms) for cherry-pick operations. */
@@ -448,49 +467,37 @@ function getExecErrorFields(error) {
     return { message: error.message || '', stderr, stdout };
 }
 /**
- * Stage files via stdin to avoid ENAMETOOLONG on Windows.
+ * Read the `code` property of an unknown rejection value, if present.
+ * execFile rejects with the child's numeric exit status in `code`; fs calls
+ * reject with a string errno code (e.g. `'ENOENT'`).
  *
- * Uses `git add --pathspec-from-file=- --pathspec-file-nul` so the file list is piped
- * through stdin (NUL-delimited) instead of passed as command-line
- * arguments.  This sidesteps the Windows CreateProcessW 32 767-char
- * limit that triggers ENAMETOOLONG when batches contain many files
- * with long absolute paths.
+ * @param error - The caught value.
+ * @returns The code, or undefined if the value has none.
+ */
+function getErrorCode(error) {
+    if (typeof error !== 'object' || error === null || !('code' in error)) {
+        return undefined;
+    }
+    const { code } = error;
+    return typeof code === 'string' || typeof code === 'number'
+        ? code
+        : undefined;
+}
+/**
+ * Check whether an error is caused by `index.lock` contention.
  *
- * @param files - Absolute paths of files to stage.
- * @param cwd   - Repository root (working directory for git).
- * @param timeoutMs - Kill the child process after this many milliseconds. Default: 30000.
+ * Requires the literal `index.lock` in the message or stderr: a bare
+ * `EEXIST` (any file that already exists) is not lock contention and must
+ * not be retried as if it were. Only Error instances qualify.
+ *
+ * @param error - The caught value.
+ * @returns true if the error names `index.lock`.
  */
-function gitAddViaStdin(files, cwd, timeoutMs = 30_000) {
-    return new Promise((resolve, reject) => {
-        let timedOut = false;
-        const child = execFile('git', ['add', '--pathspec-from-file=-', '--pathspec-file-nul'], { cwd }, (error) => {
-            clearTimeout(timer);
-            if (timedOut)
-                return;
-            if (error)
-                reject(error);
-            else
-                resolve();
-        });
-        const timer = setTimeout(() => {
-            timedOut = true;
-            child.kill();
-            reject(new Error(`git add timed out after ${String(timeoutMs)}ms`));
-        }, timeoutMs);
-        if (!child.stdin) {
-            clearTimeout(timer);
-            reject(new Error('Failed to open stdin for git add'));
-            return;
-        }
-        // Suppress EPIPE — expected if git exits before we finish writing
-        child.stdin.on('error', (err) => {
-            if (err.code !== 'EPIPE') {
-                clearTimeout(timer);
-                reject(err);
-            }
-        });
-        child.stdin.end(files.join('\0'));
-    });
+function isIndexLockError(error) {
+    if (!(error instanceof Error))
+        return false;
+    const { message, stderr } = getExecErrorFields(error);
+    return message.includes('index.lock') || stderr.includes('index.lock');
 }
 /**
  * Normalize a path for case-insensitive comparison on Windows.
@@ -503,6 +510,17 @@ function gitAddViaStdin(files, cwd, timeoutMs = 30_000) {
 function normalizePathCase(p, platform = process.platform) {
     return platform === 'win32' ? p.toLowerCase() : p;
 }
+/**
+ * Build a comparison key for an absolute path: resolved, forward slashes,
+ * and lowercased on Windows.
+ *
+ * @param p - The path.
+ * @param platform - The platform to check against (default: `process.platform`).
+ * @returns The comparison key.
+ */
+function pathKey(p, platform = process.platform) {
+    return normalizePathCase(normalizeSlashes(resolve(p)), platform);
+}
 /**
  * Find the longest-prefix-match root for a normalized path.
  * Roots must be sorted longest-first for correct nested matching.
@@ -3661,6 +3679,28 @@ function resolveWatchRootsForGlob(coordinator, glob) {
     return results;
 }
 
+/**
+ * @module vcs/runGit
+ * Run a git subcommand in a repository with the pinned argv prefix and a
+ * timeout. Lives in its own module (rather than gitExec) so callers resolve
+ * `execFileAsync` through the gitExec module binding.
+ */
+/**
+ * Run `git <args>` in `cwd` with {@link gitArgs} applied.
+ *
+ * @param cwd - Repository root (working directory for git).
+ * @param args - Subcommand and arguments.
+ * @param options - Timeout and buffer limits.
+ * @returns The child's stdout and stderr.
+ */
+function runGit(cwd, args, { timeoutMs = GIT_TIMEOUT_STANDARD, maxBuffer } = {}) {
+    return execFileAsync('git', gitArgs(...args), {
+        cwd,
+        timeout: timeoutMs,
+        ...(maxBuffer === undefined ? {} : { maxBuffer }),
+    });
+}
+
 /**
  * @module api/handlers/vcs/vcsCheckExclusion
  * Fastify route handler for GET /vcs/check-exclusion. Checks gitignore status of a path.
@@ -3685,7 +3725,11 @@ function createVcsCheckExclusionHandler(deps) {
             return;
         }
         try {
-            const { stdout } = await execFileAsync('git', ['check-ignore', '-v', resolved.relativePath], { cwd: resolved.root });
+            const { stdout } = await runGit(resolved.root, [
+                'check-ignore',
+                '-v',
+                resolved.relativePath,
+            ]);
             // Output format: <source>:<linenum>:<pattern>\t<pathname>
             const trimmed = stdout.trim();
             const match = /^(.+):(\d+):(.+)\t/.exec(trimmed);
@@ -3733,7 +3777,7 @@ function createVcsDiffHandler(deps) {
             const range = commitEnd ? `${commit}..${commitEnd}` : `${commit}..HEAD`;
             const args = ['diff', range, '--', relativePath || '.'];
             try {
-                const { stdout } = await execFileAsync('git', args, { cwd: root });
+                const { stdout } = await runGit(root, args);
                 if (stdout.trim())
                     diffs.push(stdout);
             }
@@ -3947,7 +3991,7 @@ function createVcsHistoryHandler(deps) {
                 args.push(`--until=${until}`);
             args.push('--', relativePath || '.');
             try {
-                const { stdout } = await execFileAsync('git', args, { cwd: root });
+                const { stdout } = await runGit(root, args);
                 allEntries.push(...parseGitLog(stdout));
             }
             catch {
@@ -3994,7 +4038,7 @@ function createVcsRevertHandler(deps) {
                 const args = relativePath === '' || relativePath === '.'
                     ? ['ls-tree', '-r', '--name-only', commit]
                     : ['ls-tree', '-r', '--name-only', commit, '--', relativePath];
-                const { stdout } = await execFileAsync('git', args, { cwd: root });
+                const { stdout } = await runGit(root, args);
                 fileList = stdout
                     .trim()
                     .split('\n')
@@ -4018,7 +4062,10 @@ function createVcsRevertHandler(deps) {
                 // Get file content at the target commit
                 let content;
                 try {
-                    const { stdout } = await execFileAsync('git', ['show', `${commit}:${relFile}`], { cwd: root });
+                    const { stdout } = await runGit(root, [
+                        'show',
+                        `${commit}:${relFile}`,
+                    ]);
                     content = stdout;
                 }
                 catch {
@@ -4083,7 +4130,10 @@ function createVcsShowHandler(deps) {
             return;
         }
         try {
-            const { stdout } = await execFileAsync('git', ['show', `${commit}:${resolved.relativePath}`], { cwd: resolved.root });
+            const { stdout } = await runGit(resolved.root, [
+                'show',
+                `${commit}:${resolved.relativePath}`,
+            ]);
             const ext = extname(path).toLowerCase();
             const contentType = CONTENT_TYPES[ext] ?? 'application/octet-stream';
             void reply.header('content-type', contentType).send(stdout);
@@ -4100,37 +4150,34 @@ function createVcsShowHandler(deps) {
  * @module api/handlers/vcs/vcsStatus
  * Fastify route handler for GET /vcs/status. Returns VCS state for all roots.
  */
-async function getLastCommit(cwd) {
+/**
+ * Run a read-only git query; a failure (no commits, no remote, not a repo)
+ * or empty output yields null.
+ */
+async function queryGit(cwd, args) {
     try {
-        const { stdout } = await execFileAsync('git', ['log', '-1', '--format=%H|%s|%aI'], { cwd });
-        const trimmed = stdout.trim();
-        if (!trimmed)
-            return null;
-        const [hash, message, timestamp] = trimmed.split('|');
-        return { hash, message, timestamp };
+        const out = (await runGit(cwd, args)).stdout.trim();
+        return out || null;
     }
     catch {
         return null;
     }
 }
-async function getTrackedCount(cwd) {
-    try {
-        const { stdout } = await execFileAsync('git', ['rev-list', '--count', 'HEAD'], { cwd });
-        return parseInt(stdout.trim(), 10);
-    }
-    catch {
-        return 0;
-    }
-}
-async function getRemoteUrl(cwd) {
-    try {
-        const { stdout } = await execFileAsync('git', ['remote', 'get-url', 'origin'], { cwd });
-        const url = stdout.trim();
-        return url || null;
-    }
-    catch {
+async function getLastCommit(cwd) {
+    const out = await queryGit(cwd, ['log', '-1', '--format=%H|%s|%aI']);
+    if (out === null)
         return null;
-    }
+    // Hash and timestamp never contain '|'; the subject may.
+    const parts = out.split('|');
+    return {
+        hash: parts[0],
+        message: parts.slice(1, -1).join('|'),
+        timestamp: parts[parts.length - 1],
+    };
+}
+async function getCommitCount(cwd) {
+    const out = await queryGit(cwd, ['rev-list', '--count', 'HEAD']);
+    return out === null ? 0 : parseInt(out, 10);
 }
 /**
  * Create handler for GET /vcs/status.
@@ -4142,9 +4189,9 @@ function createVcsStatusHandler(deps) {
         const rootStatuses = await Promise.all(roots.map(async (root) => {
             const manager = deps.coordinator.getManager(root);
             const [tracked, lastCommit, remoteUrl] = await Promise.all([
-                getTrackedCount(root),
+                getCommitCount(root),
                 getLastCommit(root),
-                getRemoteUrl(root),
+                queryGit(root, ['remote', 'get-url', 'origin']),
             ]);
             return {
                 path: root,
@@ -4153,6 +4200,7 @@ function createVcsStatusHandler(deps) {
                 remoteUrl: manager?.remoteUrl ?? remoteUrl,
                 lastPush: manager?.lastPushTime ?? null,
                 pushErrors: manager?.pushErrors ?? [],
+                breaker: manager?.breakerState ?? null,
             };
         }));
         return { enabled, roots: rootStatuses };
@@ -4442,6 +4490,57 @@ class CommitMessageGenerator {
     }
 }
 
+/**
+ * @module vcs/cronMatch
+ * Minimal 5-field cron matcher used by the squash retention scheduler.
+ */
+function partMatches(part, value, min, max) {
+    // Handle step: */N or range/N
+    const [rangePart, stepStr] = part.split('/');
+    const step = stepStr ? parseInt(stepStr, 10) : 1;
+    if (rangePart === '*') {
+        return (value - min) % step === 0;
+    }
+    // Handle range: N-M
+    if (rangePart.includes('-')) {
+        const [startStr, endStr] = rangePart.split('-');
+        const start = parseInt(startStr, 10);
+        const end = parseInt(endStr, 10);
+        if (value < start || value > end)
+            return false;
+        return (value - start) % step === 0;
+    }
+    // Plain number. For day-of-week, 7 also means Sunday (0).
+    const num = parseInt(rangePart, 10);
+    if (step === 1 && max === 7 && num === 7)
+        return value === 0;
+    return value === num;
+}
+function fieldMatches(field, value, min, max) {
+    return field
+        .split(',')
+        .some((part) => partMatches(part.trim(), value, min, max));
+}
+/**
+ * Check whether a standard 5-field cron expression matches a time.
+ * Fields: minute hour day-of-month month day-of-week.
+ * Supports numbers, wildcards, lists (1,3,5), ranges (1-5) and steps.
+ *
+ * @param cronExpr - The cron expression.
+ * @param now - The time to test (default: now).
+ * @returns true if every field matches.
+ */
+function cronMatchesNow(cronExpr, now = new Date()) {
+    const fields = cronExpr.trim().split(/\s+/);
+    if (fields.length !== 5)
+        return false;
+    return (fieldMatches(fields[0], now.getMinutes(), 0, 59) &&
+        fieldMatches(fields[1], now.getHours(), 0, 23) &&
+        fieldMatches(fields[2], now.getDate(), 1, 31) &&
+        fieldMatches(fields[3], now.getMonth() + 1, 1, 12) &&
+        fieldMatches(fields[4], now.getDay(), 0, 7));
+}
+
 /**
  * @module vcs/gitNetwork
  * Non-interactive, credential-safe execution of git commands that touch the
@@ -4606,7 +4705,7 @@ function sanitizeGitError(error, secret) {
  */
 async function execGitNetwork(args, options) {
     try {
-        return await execFileAsync('git', [...buildGitNetworkArgs(options.clearCredentialHelpers), ...args], {
+        return await execFileAsync('git', gitArgs(...buildGitNetworkArgs(options.clearCredentialHelpers), ...args), {
             cwd: options.cwd,
             env: buildGitNetworkEnv(process.env, options.config),
             timeout: options.timeout,
@@ -4643,64 +4742,122 @@ async function gitPushNonInteractive(options) {
 }
 
 /**
- * @module vcs/SquashManager
- * Handles scheduled squash retention for git-backed VCS roots.
+ * @module vcs/gitRepoState
+ * Read-mostly checks of a repository's state that gate VCS operations:
+ * abandoned sequencer/rebase/merge state, uncommitted tracked changes, and
+ * `index.lock` presence and staleness. See #249.
  */
 /**
- * Parse a standard 5-field cron expression and check if the current time matches.
- * Fields: minute hour dom month dow
- * Supports: numbers, wildcards, lists (1,3,5), ranges (1-5), steps (star/5)
+ * Paths under `.git/` that indicate an in-progress rebase, cherry-pick, or
+ * merge. Rewriting history (or committing) on top of one is unsafe.
  */
-function cronMatchesNow(cronExpr, now = new Date()) {
-    const fields = cronExpr.trim().split(/\s+/);
-    if (fields.length !== 5)
-        return false;
-    const minute = now.getMinutes();
-    const hour = now.getHours();
-    const dom = now.getDate();
-    const month = now.getMonth() + 1; // 1-based
-    const dow = now.getDay(); // 0=Sunday
-    return (fieldMatches(fields[0], minute, 0, 59) &&
-        fieldMatches(fields[1], hour, 0, 23) &&
-        fieldMatches(fields[2], dom, 1, 31) &&
-        fieldMatches(fields[3], month, 1, 12) &&
-        fieldMatches(fields[4], dow, 0, 7) // 7 also means Sunday
-    );
+const STALE_OPERATION_MARKERS = [
+    'sequencer',
+    'rebase-merge',
+    'rebase-apply',
+    'CHERRY_PICK_HEAD',
+    'MERGE_HEAD',
+];
+/** Manual resolution hint logged alongside stale-operation reports. */
+const STALE_OPERATION_HINT = 'resolve it manually (e.g. git cherry-pick --quit / git rebase --abort / git merge --abort)';
+function indexLockPath(rootPath) {
+    return join(rootPath, '.git', 'index.lock');
 }
-function fieldMatches(field, value, min, max) {
-    for (const part of field.split(',')) {
-        if (partMatches(part.trim(), value, min, max))
-            return true;
+/**
+ * Detect an abandoned cherry-pick, rebase, or merge left in `.git/`.
+ * Report-only: never clears the state.
+ *
+ * @param rootPath - Repository root.
+ * @returns The first marker found, or undefined if none.
+ */
+async function detectStaleGitOperation(rootPath) {
+    for (const marker of STALE_OPERATION_MARKERS) {
+        try {
+            await access(join(rootPath, '.git', marker));
+            return marker;
+        }
+        catch {
+            // Not present: check the next marker.
+        }
     }
-    return false;
+    return undefined;
 }
-function partMatches(part, value, min, max) {
-    // Handle step: */N or range/N
-    const [rangePart, stepStr] = part.split('/');
-    const step = stepStr ? parseInt(stepStr, 10) : 1;
-    if (rangePart === '*') {
-        return (value - min) % step === 0;
+/**
+ * Check for uncommitted changes to tracked files (staged or unstaged).
+ * Untracked files are ignored.
+ *
+ * @param rootPath - Repository root.
+ * @returns true if any tracked file differs from HEAD.
+ */
+async function hasDirtyTrackedFiles(rootPath) {
+    const { stdout } = await runGit(rootPath, [
+        'status',
+        '--porcelain',
+        '-z',
+        '--untracked-files=no',
+    ]);
+    return stdout.length > 0;
+}
+/**
+ * Check whether `.git/index.lock` exists.
+ *
+ * @param rootPath - Repository root.
+ * @returns true if the lock file is present.
+ */
+async function indexLockExists(rootPath) {
+    try {
+        await access(indexLockPath(rootPath));
+        return true;
     }
-    // Handle range: N-M
-    if (rangePart.includes('-')) {
-        const [startStr, endStr] = rangePart.split('-');
-        const start = parseInt(startStr, 10);
-        const end = parseInt(endStr, 10);
-        if (value < start || value > end)
-            return false;
-        return (value - start) % step === 0;
+    catch {
+        return false;
     }
-    // Plain number
-    const num = parseInt(rangePart, 10);
-    if (step === 1) {
-        // For dow, treat 7 as 0 (Sunday)
-        if (max === 7 && num === 7)
-            return value === 0;
-        return value === num;
+}
+/**
+ * Remove `.git/index.lock` unconditionally (missing is fine).
+ *
+ * @param rootPath - Repository root.
+ */
+async function removeIndexLock(rootPath) {
+    await rm(indexLockPath(rootPath), { force: true });
+}
+/**
+ * Remove `.git/index.lock` if it is older than `thresholdMs`. A fresh lock
+ * (held by a live git process) is left alone.
+ *
+ * @param rootPath - Repository root.
+ * @param thresholdMs - Minimum age for a lock to count as stale.
+ * @param logger - Logger for removal and failure reports.
+ */
+async function removeStaleIndexLock(rootPath, thresholdMs, logger) {
+    try {
+        const ageMs = Date.now() - (await stat(indexLockPath(rootPath))).mtimeMs;
+        if (ageMs > thresholdMs) {
+            await removeIndexLock(rootPath);
+            logger.warn({ root: rootPath, ageMs }, 'Removed stale index.lock');
+        }
+    }
+    catch (error) {
+        if (getErrorCode(error) !== 'ENOENT') {
+            logger.warn({ root: rootPath, err: normalizeError(error) }, 'Unable to remove stale index.lock');
+        }
     }
-    // Number with step doesn't make sense for single values, treat as exact
-    return value === num;
 }
+
+/**
+ * @module vcs/SquashManager
+ * Handles scheduled squash retention for git-backed VCS roots.
+ */
+const DAY_MS = 24 * 60 * 60 * 1000;
+/**
+ * Manages scheduled squash retention for a single VCS root.
+ *
+ * Runs on a cron schedule (checked every 60s). When triggered, squashes
+ * commits older than the retention boundary (the tighter of maxAgeDays
+ * and maxVersions) into a single "historical baseline" orphan commit,
+ * then cherry-picks retained commits on top. Force-pushes to remote
+ * if configured (D13).
+ */
 class SquashManager {
     rootPath;
     retention;
@@ -4755,17 +4912,9 @@ class SquashManager {
      * to drain and suspend the commit pipeline during the squash.
      */
     async runSquash() {
-        // Check for index.lock before starting multi-step operation
-        const lockPath = join(this.rootPath, '.git', 'index.lock');
-        try {
-            await access(lockPath);
-            // Lock exists — abort and retry next cycle
-            this.logger.warn({ root: this.rootPath }, 'Squash aborted: index.lock exists, will retry next cycle');
-            return { squashed: false, error: 'index.lock exists' };
-        }
-        catch {
-            // No lock — proceed
-        }
+        const blocked = await this.checkRepoPreconditions();
+        if (blocked !== undefined)
+            return { squashed: false, error: blocked };
         // Bug 3: Pause the commit pipeline before squash
         try {
             await this.pauseCommits?.();
@@ -4777,40 +4926,65 @@ class SquashManager {
             return { squashed: false, error: normalizeError(error).message };
         }
         try {
-            const commits = await this.getCommitLog();
-            if (commits.length <= 1) {
-                return { squashed: false };
+            // #249 guard: the squash uses `reset --hard` / `checkout -f`, which
+            // would destroy uncommitted changes to tracked files. After draining
+            // the commit pipeline the tracked tree should be clean; if it isn't,
+            // refuse rather than lose content. Untracked files don't block.
+            if (await hasDirtyTrackedFiles(this.rootPath)) {
+                const error = 'Squash refused: working tree has uncommitted changes to tracked files';
+                this.logger.warn({ root: this.rootPath }, error);
+                return { squashed: false, error };
             }
-            const boundaryIndex = this.calculateRetentionBoundary(commits);
-            if (boundaryIndex <= 0) {
-                // All commits are within retention or only one commit before boundary
+            const commits = await this.getCommitLog();
+            const boundaryIndex = commits.length <= 1 ? 0 : this.calculateRetentionBoundary(commits);
+            if (boundaryIndex <= 0)
                 return { squashed: false };
-            }
-            // Perform the squash
             await this.performSquash(commits, boundaryIndex);
             const commitsRemoved = boundaryIndex;
             const commitsRetained = commits.length - boundaryIndex;
             this.logger.info({ root: this.rootPath, commitsRemoved, commitsRetained }, 'Squash retention completed');
-            // Force push if remote configured
             await this.forcePushIfConfigured();
             return { squashed: true, commitsRemoved, commitsRetained };
         }
         catch (error) {
-            const message = normalizeError(error).message;
             this.logger.error({ root: this.rootPath, err: normalizeError(error) }, 'Squash operation failed');
-            return { squashed: false, error: message };
+            return { squashed: false, error: normalizeError(error).message };
         }
         finally {
             // Bug 3: Always resume the commit pipeline
             this.resumeCommits?.();
         }
     }
+    /**
+     * Refuse to start a multi-step history rewrite while another git
+     * operation holds the index or an abandoned cherry-pick, rebase, or merge
+     * is present (#249: report only, never auto-clear).
+     *
+     * @returns The refusal reason, or undefined if the squash may proceed.
+     */
+    async checkRepoPreconditions() {
+        if (await indexLockExists(this.rootPath)) {
+            this.logger.warn({ root: this.rootPath }, 'Squash aborted: index.lock exists, will retry next cycle');
+            return 'index.lock exists';
+        }
+        const marker = await detectStaleGitOperation(this.rootPath);
+        if (marker !== undefined) {
+            const error = `Squash refused: in-progress git operation detected (.git/${marker})`;
+            this.logger.error({ root: this.rootPath, marker }, `${error} — ${STALE_OPERATION_HINT}`);
+            return error;
+        }
+        return undefined;
+    }
     /**
      * Get all commits in chronological order (oldest first).
      */
     async getCommitLog() {
         try {
-            const { stdout } = await execFileAsync('git', ['log', '--format=%H %aI', '--reverse'], { cwd: this.rootPath, timeout: GIT_TIMEOUT_STANDARD });
+            const { stdout } = await runGit(this.rootPath, [
+                'log',
+                '--format=%H %aI',
+                '--reverse',
+            ]);
             if (!stdout.trim())
                 return [];
             return stdout
@@ -4839,17 +5013,10 @@ class SquashManager {
      * The boundary is the one that retains FEWER old commits (tighter).
      */
     calculateRetentionBoundary(commits) {
-        const now = new Date();
-        const maxAgeMs = this.retention.maxAgeDays * 24 * 60 * 60 * 1000;
-        const cutoffDate = new Date(now.getTime() - maxAgeMs);
-        // Find the first commit that is within the age window (to keep)
-        let ageBoundary = commits.length; // Default: all too old
-        for (let i = 0; i < commits.length; i++) {
-            if (commits[i].date >= cutoffDate) {
-                ageBoundary = i;
-                break;
-            }
-        }
+        const cutoffDate = new Date(Date.now() - this.retention.maxAgeDays * DAY_MS);
+        // First commit within the age window (to keep); default: all too old.
+        const firstKept = commits.findIndex((c) => c.date >= cutoffDate);
+        const ageBoundary = firstKept === -1 ? commits.length : firstKept;
         // Count boundary: keep the last maxVersions commits
         const countBoundary = Math.max(0, commits.length - this.retention.maxVersions);
         // The tighter constraint wins (keeps fewer old commits = higher boundary index)
@@ -4860,80 +5027,59 @@ class SquashManager {
      * Uses the configured branch name instead of dynamic detection (Bug 1).
      */
     async performSquash(commits, boundaryIndex) {
+        const git = (...args) => runGit(this.rootPath, args);
         // The commit just before boundary is the last one to squash
         const baselineHash = commits[boundaryIndex - 1].hash;
-        // Bug 1: Use configured branch name, not dynamic detection
         const targetBranch = this.branch;
         const orphanBranch = `__squash_orphan_${String(Date.now())}`;
         try {
-            // 1. Create orphan branch with the tree state at the baseline commit
-            await execFileAsync('git', ['checkout', '--orphan', orphanBranch], {
-                cwd: this.rootPath,
-                timeout: GIT_TIMEOUT_STANDARD,
-            });
-            // 2. Reset index to the baseline tree (the last squashed commit's tree)
-            await execFileAsync('git', ['reset', '--hard', baselineHash], {
-                cwd: this.rootPath,
-                timeout: GIT_TIMEOUT_STANDARD,
-            });
-            // 3. Create the baseline commit with the same tree
-            // Use commit-tree for a clean orphan commit
-            const { stdout: treeOut } = await execFileAsync('git', ['rev-parse', `${baselineHash}^{tree}`], { cwd: this.rootPath, timeout: GIT_TIMEOUT_STANDARD });
-            const treeHash = treeOut.trim();
-            const { stdout: commitOut } = await execFileAsync('git', ['commit-tree', treeHash, '-m', 'historical baseline'], { cwd: this.rootPath, timeout: GIT_TIMEOUT_STANDARD });
-            const baselineCommitHash = commitOut.trim();
-            // 4. Reset orphan branch to this new baseline commit
-            await execFileAsync('git', ['reset', '--hard', baselineCommitHash], {
-                cwd: this.rootPath,
-                timeout: GIT_TIMEOUT_STANDARD,
-            });
-            // 5. Cherry-pick boundary..HEAD (the retained commits)
-            // Get the list of commits to cherry-pick (from boundary to the end)
+            // 1-2. Orphan branch at the baseline commit's tree
+            await git('checkout', '--orphan', orphanBranch);
+            await git('reset', '--hard', baselineHash);
+            // 3-4. Single parentless baseline commit with that tree
+            const { stdout: treeOut } = await git('rev-parse', `${baselineHash}^{tree}`);
+            const { stdout: commitOut } = await git('commit-tree', treeOut.trim(), '-m', 'historical baseline');
+            await git('reset', '--hard', commitOut.trim());
+            // 5. Cherry-pick the retained commits on top
             const commitsToCherry = commits.slice(boundaryIndex).map((c) => c.hash);
             if (commitsToCherry.length > 0) {
-                await execFileAsync('git', ['cherry-pick', ...commitsToCherry], {
-                    cwd: this.rootPath,
-                    timeout: GIT_TIMEOUT_CHERRY_PICK,
+                await runGit(this.rootPath, ['cherry-pick', ...commitsToCherry], {
+                    timeoutMs: GIT_TIMEOUT_CHERRY_PICK,
                 });
             }
-            // 6. Force-update the configured branch to the orphan
-            const { stdout: newHead } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: this.rootPath, timeout: GIT_TIMEOUT_STANDARD });
-            await execFileAsync('git', ['branch', '-f', targetBranch, newHead.trim()], { cwd: this.rootPath, timeout: GIT_TIMEOUT_STANDARD });
-            // 7. Switch back to configured branch
-            await execFileAsync('git', ['checkout', targetBranch], {
-                cwd: this.rootPath,
-                timeout: GIT_TIMEOUT_STANDARD,
-            });
-            // 8. Delete orphan branch
-            await execFileAsync('git', ['branch', '-D', orphanBranch], {
-                cwd: this.rootPath,
-                timeout: GIT_TIMEOUT_STANDARD,
-            });
+            // 6-8. Move the configured branch to the new history and clean up
+            const { stdout: newHead } = await git('rev-parse', 'HEAD');
+            await git('branch', '-f', targetBranch, newHead.trim());
+            await git('checkout', targetBranch);
+            await git('branch', '-D', orphanBranch);
         }
         catch (error) {
-            // Attempt cleanup: try to get back to configured branch
-            try {
-                await execFileAsync('git', ['checkout', '-f', targetBranch], {
-                    cwd: this.rootPath,
-                    timeout: GIT_TIMEOUT_STANDARD,
-                });
-                await execFileAsync('git', ['branch', '-D', orphanBranch], {
-                    cwd: this.rootPath,
-                    timeout: GIT_TIMEOUT_STANDARD,
-                });
-            }
-            catch {
-                // Cleanup failed — log but re-throw original error
-            }
-            // Remove index.lock if left behind
+            await this.cleanupFailedSquash(targetBranch, orphanBranch);
+            throw error;
+        }
+    }
+    /**
+     * Best-effort cleanup after a failed squash. Aborts any half-finished
+     * cherry-pick first, so a failure never leaves a sequencer behind (#249),
+     * then returns to the configured branch and removes a leftover lock.
+     */
+    async cleanupFailedSquash(targetBranch, orphanBranch) {
+        const attempt = async (...args) => {
             try {
-                const lockFile = join(this.rootPath, '.git', 'index.lock');
-                await rm(lockFile, { force: true });
+                await runGit(this.rootPath, args);
             }
             catch {
-                // ignore
+                // Best effort: the state may not need this step.
             }
-            throw error;
+        };
+        await attempt('cherry-pick', '--abort');
+        await attempt('checkout', '-f', targetBranch);
+        await attempt('branch', '-D', orphanBranch);
+        try {
+            await removeIndexLock(this.rootPath);
+        }
+        catch {
+            // Best effort: the original squash error is what gets reported.
         }
     }
     /**
@@ -5010,7 +5156,7 @@ const ALWAYS_GITIGNORE_ENTRIES = [
  */
 async function checkGitAvailable() {
     try {
-        await execFileAsync('git', ['--version']);
+        await execFileAsync('git', gitArgs('--version'));
         return true;
     }
     catch {
@@ -5030,7 +5176,7 @@ async function initRepo(rootPath) {
         // .git exists, nothing to do
     }
     catch {
-        await execFileAsync('git', ['init'], { cwd: rootPath });
+        await runGit(rootPath, ['init']);
     }
 }
 /**
@@ -5042,12 +5188,8 @@ async function initRepo(rootPath) {
  * @param email - Author email for commits.
  */
 async function configureRepoIdentity(rootPath, name, email) {
-    await execFileAsync('git', ['config', '--local', 'user.name', name], {
-        cwd: rootPath,
-    });
-    await execFileAsync('git', ['config', '--local', 'user.email', email], {
-        cwd: rootPath,
-    });
+    await runGit(rootPath, ['config', '--local', 'user.name', name]);
+    await runGit(rootPath, ['config', '--local', 'user.email', email]);
 }
 /**
  * Detect and recover from orphan branch state on startup.
@@ -5069,24 +5211,22 @@ async function detectAndRecoverOrphanBranch(rootPath, expectedBranch, logger) {
         // Not a git repo — nothing to detect
         return;
     }
-    const { stdout: branchOut } = await execFileAsync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: rootPath, timeout: GIT_TIMEOUT_STANDARD });
+    const { stdout: branchOut } = await runGit(rootPath, [
+        'rev-parse',
+        '--abbrev-ref',
+        'HEAD',
+    ]);
     const currentBranch = branchOut.trim();
     if (currentBranch === expectedBranch)
         return;
     logger.warn({ root: rootPath, currentBranch, expectedBranch }, 'Repo is on unexpected branch — recovering to configured branch');
     // Get current HEAD
-    const { stdout: headOut } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: rootPath, timeout: GIT_TIMEOUT_STANDARD });
+    const { stdout: headOut } = await runGit(rootPath, ['rev-parse', 'HEAD']);
     const headHash = headOut.trim();
     // Force-update the expected branch to current HEAD
-    await execFileAsync('git', ['branch', '-f', expectedBranch, headHash], {
-        cwd: rootPath,
-        timeout: GIT_TIMEOUT_STANDARD,
-    });
+    await runGit(rootPath, ['branch', '-f', expectedBranch, headHash]);
     // Checkout the expected branch
-    await execFileAsync('git', ['checkout', expectedBranch], {
-        cwd: rootPath,
-        timeout: GIT_TIMEOUT_STANDARD,
-    });
+    await runGit(rootPath, ['checkout', expectedBranch]);
     logger.info({ root: rootPath, recoveredFrom: currentBranch, expectedBranch, headHash }, 'Orphan branch recovery complete — now on configured branch');
 }
 /**
@@ -5266,6 +5406,295 @@ function resolveCommitMessageApiKey(provider, configApiKey, logger) {
     return undefined;
 }
 
+/**
+ * @module vcs/gitIndex
+ * Git index operations used by the commit pipeline: staging additions and
+ * removals through stdin, listing tracked-but-deleted paths, detecting a
+ * staged diff, and creating a commit. Every call carries
+ * {@link GIT_BASE_ARGS} via {@link gitArgs}.
+ */
+/** Max stdout buffered from `git ls-files` (large corpora can list many paths). */
+const LS_FILES_MAX_BUFFER = 256 * 1024 * 1024;
+/**
+ * Run a git subcommand with a NUL-delimited file list piped through stdin.
+ *
+ * This sidesteps the Windows CreateProcessW 32 767-char limit that
+ * triggers ENAMETOOLONG when batches contain many files with long
+ * absolute paths.
+ *
+ * @param argv - Full git argv (base args, subcommand, and flags).
+ * @param files - Absolute paths to pipe through stdin (NUL-delimited).
+ * @param cwd - Repository root (working directory for git).
+ * @param timeoutMs - Kill the child process after this many milliseconds.
+ */
+function execGitStdin(argv, files, cwd, timeoutMs) {
+    return new Promise((resolvePromise, reject) => {
+        let timedOut = false;
+        const child = execFile('git', argv, { cwd }, (error) => {
+            clearTimeout(timer);
+            if (timedOut)
+                return;
+            if (error)
+                reject(error);
+            else
+                resolvePromise();
+        });
+        const timer = setTimeout(() => {
+            timedOut = true;
+            child.kill();
+            reject(new Error(`git ${argv.join(' ')} timed out after ${String(timeoutMs)}ms`));
+        }, timeoutMs);
+        if (!child.stdin) {
+            clearTimeout(timer);
+            reject(new Error('Failed to open stdin for git command'));
+            return;
+        }
+        // Suppress EPIPE: expected if git exits before we finish writing.
+        child.stdin.on('error', (err) => {
+            if (err.code !== 'EPIPE') {
+                clearTimeout(timer);
+                reject(err);
+            }
+        });
+        child.stdin.end(files.join('\0'));
+    });
+}
+/**
+ * Stage files with `git add --pathspec-from-file=- --pathspec-file-nul`.
+ *
+ * @param files - Absolute paths of files to stage.
+ * @param cwd - Repository root (working directory for git).
+ * @param timeoutMs - Kill the child process after this many milliseconds.
+ */
+async function gitAddViaStdin(files, cwd, timeoutMs = GIT_TIMEOUT_STANDARD) {
+    if (files.length === 0)
+        return;
+    await execGitStdin(gitArgs('add', '--pathspec-from-file=-', '--pathspec-file-nul'), files, cwd, timeoutMs);
+}
+/**
+ * Stage the removal (index only) of tracked files that are missing from
+ * disk. `--ignore-unmatch` means a path that isn't actually tracked is
+ * skipped instead of failing the whole command. See #249.
+ *
+ * @param files - Absolute paths of tracked files to remove from the index.
+ * @param cwd - Repository root (working directory for git).
+ * @param timeoutMs - Kill the child process after this many milliseconds.
+ */
+async function gitRmCachedViaStdin(files, cwd, timeoutMs = GIT_TIMEOUT_STANDARD) {
+    if (files.length === 0)
+        return;
+    await execGitStdin(gitArgs('rm', '--cached', '--ignore-unmatch', '--quiet', '--pathspec-from-file=-', '--pathspec-file-nul'), files, cwd, timeoutMs);
+}
+/**
+ * List tracked paths that are missing from the working tree, via a single
+ * `git ls-files --deleted -z` call (never one process per file).
+ *
+ * `git ls-files` has no `--pathspec-from-file`, so rather than passing the
+ * candidate paths (which could exceed the Windows command-line limit) this
+ * asks for every tracked-but-deleted path; callers intersect with their own
+ * candidates. Output is bounded by the number of deleted tracked files.
+ *
+ * @param cwd - Repository root (working directory for git).
+ * @param timeoutMs - Kill the child process after this many milliseconds.
+ * @returns Absolute paths (forward slashes) of tracked files missing on disk.
+ */
+async function listDeletedTrackedPaths(cwd, timeoutMs = GIT_TIMEOUT_STANDARD) {
+    const { stdout } = await runGit(cwd, ['ls-files', '--deleted', '-z'], {
+        timeoutMs,
+        maxBuffer: LS_FILES_MAX_BUFFER,
+    });
+    return stdout
+        .split('\0')
+        .filter((rel) => rel.length > 0)
+        .map((rel) => normalizeSlashes(resolve(cwd, rel)));
+}
+/**
+ * Check whether anything is staged (`git diff --cached --quiet`).
+ * Exit code 0 means the index matches HEAD; exit code 1 means there is a
+ * staged diff. Any other outcome is a real error and is rethrown. See #249.
+ *
+ * @param cwd - Repository root (working directory for git).
+ * @param timeoutMs - Kill the child process after this many milliseconds.
+ * @returns true if there is a staged diff to commit.
+ */
+async function hasStagedChanges(cwd, timeoutMs = GIT_TIMEOUT_STANDARD) {
+    try {
+        await runGit(cwd, ['diff', '--cached', '--quiet'], { timeoutMs });
+        return false;
+    }
+    catch (error) {
+        if (getErrorCode(error) === 1)
+            return true;
+        throw error;
+    }
+}
+/**
+ * Commit the staged index and return the new commit's short hash.
+ *
+ * @param cwd - Repository root (working directory for git).
+ * @param message - Commit message.
+ * @param timeoutMs - Kill each child process after this many milliseconds.
+ * @returns The short hash of the new HEAD.
+ */
+async function gitCommit(cwd, message, timeoutMs = GIT_TIMEOUT_STANDARD) {
+    await runGit(cwd, ['commit', '-m', message], { timeoutMs });
+    const { stdout } = await runGit(cwd, ['rev-parse', '--short', 'HEAD'], {
+        timeoutMs,
+    });
+    return stdout.trim();
+}
+
+/**
+ * @module vcs/batchStaging
+ * Stage a commit batch so that a missing path never fails it: existing
+ * files are added, tracked files that vanished have their deletion staged,
+ * and never-tracked files that vanished are dropped. See #249.
+ */
+/** Errno codes that mean "this path does not exist". */
+const MISSING_CODES = new Set([
+    'ENOENT',
+    'ENOTDIR',
+]);
+/**
+ * Check whether a path exists. Only "does not exist" errors count as
+ * missing; any other failure (permissions, I/O) propagates so the batch is
+ * retained and retried rather than silently dropping a real change.
+ *
+ * @param path - Absolute path to check.
+ * @param statFn - Stat implementation (injectable for tests).
+ * @returns true if the path exists.
+ */
+async function pathExists(path, statFn) {
+    try {
+        await statFn(path);
+        return true;
+    }
+    catch (error) {
+        if (MISSING_CODES.has(getErrorCode(error) ?? ''))
+            return false;
+        throw error;
+    }
+}
+/**
+ * Split a batch into existing, missing-tracked, and missing-untracked
+ * paths. Uses one `git ls-files --deleted` call, and only when something is
+ * missing.
+ *
+ * @param files - Absolute paths in the batch.
+ * @param rootPath - Repository root.
+ * @param statFn - Stat implementation (injectable for tests).
+ * @returns The classified batch.
+ */
+async function classifyBatchPaths(files, rootPath, statFn = stat) {
+    const exists = await Promise.all(files.map((f) => pathExists(f, statFn)));
+    const existing = files.filter((_, i) => exists[i]);
+    const missing = files.filter((_, i) => !exists[i]);
+    if (missing.length === 0) {
+        return { existing, missingTracked: [], missingUntracked: [] };
+    }
+    const deletedTracked = new Set((await listDeletedTrackedPaths(rootPath)).map((p) => pathKey(p)));
+    const isTracked = (f) => deletedTracked.has(pathKey(f));
+    return {
+        existing,
+        missingTracked: missing.filter(isTracked),
+        missingUntracked: missing.filter((f) => !isTracked(f)),
+    };
+}
+/**
+ * Stage a batch: add existing files, stage removal of tracked files that
+ * are gone, and drop never-tracked files that are gone.
+ *
+ * @param files - Absolute paths in the batch.
+ * @param rootPath - Repository root.
+ * @param logger - Logger (dropped paths are reported at debug).
+ * @param timeoutMs - Timeout for each git call.
+ */
+async function stageBatch(files, rootPath, logger, timeoutMs = GIT_TIMEOUT_STANDARD) {
+    const { existing, missingTracked, missingUntracked } = await classifyBatchPaths(files, rootPath);
+    if (missingUntracked.length > 0) {
+        logger.debug({ root: rootPath, count: missingUntracked.length }, 'Dropping missing, untracked paths from batch');
+    }
+    await gitAddViaStdin(existing, rootPath, timeoutMs);
+    await gitRmCachedViaStdin(missingTracked, rootPath, timeoutMs);
+}
+
+/**
+ * @module vcs/CommitCircuitBreaker
+ * Per-root circuit breaker for the VCS commit pipeline. Counts consecutive
+ * failures, trips at a threshold, and allows one half-open attempt per
+ * cooldown. It holds no files: callers retain pending work while it is
+ * tripped. See #249.
+ */
+/** Circuit breaker with a time-based half-open recovery. */
+class CommitCircuitBreaker {
+    maxConsecutiveFailures;
+    cooldownMs;
+    now;
+    failures = 0;
+    trippedAtMs;
+    lastError;
+    /**
+     * @param maxConsecutiveFailures - Failures that trip the breaker.
+     * @param cooldownMs - Time after a trip before one attempt is allowed.
+     * @param now - Clock (injectable for tests).
+     */
+    constructor(maxConsecutiveFailures, cooldownMs, now = Date.now) {
+        this.maxConsecutiveFailures = maxConsecutiveFailures;
+        this.cooldownMs = cooldownMs;
+        this.now = now;
+    }
+    /** Whether the breaker is tripped. */
+    get isTripped() {
+        return this.trippedAtMs !== undefined;
+    }
+    /**
+     * Milliseconds until an attempt is allowed. 0 when not tripped or when
+     * the cooldown has elapsed (half-open).
+     */
+    remainingCooldownMs() {
+        if (this.trippedAtMs === undefined)
+            return 0;
+        return Math.max(0, this.cooldownMs - (this.now() - this.trippedAtMs));
+    }
+    /**
+     * Record a failed attempt.
+     *
+     * @param message - The failure message.
+     * @returns true if this failure tripped (or re-armed) the breaker.
+     */
+    recordFailure(message) {
+        this.failures++;
+        this.lastError = message;
+        if (this.failures < this.maxConsecutiveFailures)
+            return false;
+        this.trippedAtMs = this.now();
+        return true;
+    }
+    /**
+     * Record a successful attempt (a commit or a no-op) and reset.
+     *
+     * @returns true if the breaker was tripped before this success.
+     */
+    recordSuccess() {
+        const wasTripped = this.isTripped;
+        this.failures = 0;
+        this.trippedAtMs = undefined;
+        this.lastError = undefined;
+        return wasTripped;
+    }
+    /** Current state for status reporting. */
+    snapshot() {
+        return {
+            consecutiveFailures: this.failures,
+            tripped: this.isTripped,
+            trippedAt: this.trippedAtMs === undefined
+                ? null
+                : new Date(this.trippedAtMs).toISOString(),
+            lastError: this.lastError ?? null,
+        };
+    }
+}
+
 /**
  * @module vcs/CommitMessageBuilder
  * Builds commit messages — both template-based and AI-generated.
@@ -5341,8 +5770,15 @@ class CommitMessageBuilder {
      */
     async getStagedDiff() {
         try {
-            const { stdout: stat } = await execFileAsync('git', ['diff', '--cached', '--stat'], { cwd: this.rootPath, timeout: GIT_TIMEOUT_STANDARD });
-            const { stdout: patch } = await execFileAsync('git', ['diff', '--cached'], { cwd: this.rootPath, timeout: GIT_TIMEOUT_STANDARD });
+            const { stdout: stat } = await runGit(this.rootPath, [
+                'diff',
+                '--cached',
+                '--stat',
+            ]);
+            const { stdout: patch } = await runGit(this.rootPath, [
+                'diff',
+                '--cached',
+            ]);
             return `${stat}\n${patch}`;
         }
         catch {
@@ -5405,7 +5841,9 @@ async function pushToRemote(rootPath, remoteUrl, accessToken, pushErrors, logger
  * (with optional AI-generated messages), and optionally pushed to a remote.
  *
  * Concurrency: only one commit is in-flight at a time per root. Index.lock
- * contention is handled with exponential backoff retries (D10).
+ * contention is handled with exponential backoff retries (D10). Failed
+ * batches are always retained; a circuit breaker spaces out retries of a
+ * persistently failing root (#249).
  */
 class VcsManager {
     config;
@@ -5414,13 +5852,15 @@ class VcsManager {
     accessToken;
     logger;
     commitMessageBuilder;
+    breaker;
     pending = new Set();
     pendingReversions = [];
     _pushErrors = [];
     squashManager;
     throttleTimer;
+    breakerRetryTimer;
     commitInFlight = Promise.resolve();
-    consecutiveCommitFailures = 0;
+    inFlightFileCount = 0;
     started = false;
     paused = false;
     isBaseline = true;
@@ -5432,12 +5872,11 @@ class VcsManager {
         this.remoteUrl = remoteUrl;
         this.accessToken = accessToken;
         this.commitMessageBuilder = new CommitMessageBuilder(rootPath, logger, commitMessageGenerator);
+        this.breaker = new CommitCircuitBreaker(config.maxConsecutiveFailures, config.circuitBreakerCooldownMs);
         if (config.retention) {
             this.squashManager = new SquashManager(rootPath, config.retention, logger, {
                 branch: config.branch,
-                pauseCommits: () => {
-                    return this.pause();
-                },
+                pauseCommits: () => this.pause(),
                 resumeCommits: () => {
                     this.resume();
                 },
@@ -5452,25 +5891,36 @@ class VcsManager {
     get pushErrors() {
         return this._pushErrors;
     }
+    /** Current circuit breaker state and backlog, for /vcs/status. */
+    get breakerState() {
+        return {
+            ...this.breaker.snapshot(),
+            pendingCount: this.pending.size + this.inFlightFileCount,
+        };
+    }
     /**
      * Begin accepting file changes. Sets the manager to started state and
      * starts the squash manager if configured.
      *
      * Performs startup orphan detection/recovery before starting the squash
-     * manager, ensuring the repo is on the configured branch.
+     * manager, ensuring the repo is on the configured branch, and reports
+     * (never clears) an abandoned cherry-pick, rebase, or merge.
      *
      * Baseline mode (commit prefix `"baseline:"`) remains active until
      * {@link endBaseline} is called by the coordinator after the initial scan.
      */
     async start() {
         // Bug 6: Detect and recover from orphan branches before normal operations
-        const branch = this.config.branch;
         try {
-            await detectAndRecoverOrphanBranch(this.rootPath, branch, this.logger);
+            await detectAndRecoverOrphanBranch(this.rootPath, this.config.branch, this.logger);
         }
         catch (error) {
             this.logger.error({ root: this.rootPath, err: normalizeError(error) }, 'Orphan branch recovery failed — continuing with current state');
         }
+        const marker = await detectStaleGitOperation(this.rootPath);
+        if (marker !== undefined) {
+            this.logger.error({ root: this.rootPath, marker }, `Stale in-progress git operation detected (.git/${marker}) — squash retention will refuse to run until you ${STALE_OPERATION_HINT}`);
+        }
         this.started = true;
         this.squashManager?.start();
         this.logger.info({ root: this.rootPath }, 'VcsManager started');
@@ -5484,26 +5934,22 @@ class VcsManager {
     }
     /**
      * Add a file to the pending set and start the throttle timer.
-     * If the pending set exceeds maxBatchSize, flush immediately.
+     * If the pending set reaches maxBatchSize, commit a batch immediately.
+     *
+     * The circuit breaker is intentionally not reset here: recovery is
+     * time-based, so a busy root cannot hammer a deterministic failure.
      *
      * @param filePath - Absolute path of the changed file.
      */
     fileChanged(filePath) {
         if (!this.started)
             return;
-        // Reset circuit breaker on new file change so the system can recover
-        if (this.consecutiveCommitFailures >= this.config.maxConsecutiveFailures) {
-            this.logger.info({ root: this.rootPath }, 'VCS circuit breaker reset — new file change received, retrying commits');
-            this.consecutiveCommitFailures = 0;
-        }
         this.pending.add(filePath);
         if (this.pending.size >= this.config.maxBatchSize) {
             this.clearThrottle();
-            const batch = this.takeBatch(this.config.maxBatchSize);
-            this.commitInFlight = this.commitInFlight.then(() => this.commitBatch(batch));
-            if (this.pending.size > 0) {
+            this.enqueueBatch(this.takeBatch());
+            if (this.pending.size > 0)
                 this.resetThrottle();
-            }
             return;
         }
         this.resetThrottle();
@@ -5517,14 +5963,11 @@ class VcsManager {
         this.pendingReversions.push(reversion);
     }
     /**
-     * Stage a file deletion and add to pending set.
-     * git add handles deleted files when the file is gone from disk.
+     * Queue a deleted file. Staging records the deletion if git tracks it.
      *
      * @param filePath - Absolute path of the deleted file.
      */
     handleUnlink(filePath) {
-        if (!this.started)
-            return;
         this.fileChanged(filePath);
     }
     /**
@@ -5545,19 +5988,16 @@ class VcsManager {
     resume() {
         this.paused = false;
         this.logger.debug({ root: this.rootPath }, 'VcsManager resumed');
-        if (this.pending.size > 0) {
+        if (this.pending.size > 0)
             this.resetThrottle();
-        }
     }
     /**
-     * Flush all pending files immediately.
+     * Commit all pending files now, in batches of at most maxBatchSize.
      */
     async flush() {
         this.clearThrottle();
-        if (this.pending.size > 0) {
-            const batch = [...this.pending];
-            this.pending.clear();
-            this.commitInFlight = this.commitInFlight.then(() => this.commitBatch(batch));
+        while (this.pending.size > 0) {
+            this.enqueueBatch(this.takeBatch());
         }
         await this.commitInFlight;
     }
@@ -5567,32 +6007,61 @@ class VcsManager {
     async stop() {
         this.started = false;
         this.squashManager?.stop();
+        this.clearBreakerRetry();
         await this.flush();
         this.logger.info({ root: this.rootPath }, 'VcsManager stopped');
     }
     /**
-     * Take up to N items from the pending set.
+     * Add tracked-but-deleted paths (`git ls-files --deleted`) in this
+     * manager's watch scope to pending, so the next commit (typically the
+     * baseline) records deletions that happened while nothing was watching.
+     * Called by the coordinator before flush/endBaseline on startup. See #249.
+     *
+     * @param isInScope - Returns true if the absolute path routes to this
+     *   manager (the coordinator's routing and watch-scope logic).
      */
-    takeBatch(n) {
-        const batch = [];
-        for (const item of this.pending) {
-            if (batch.length >= n)
-                break;
-            batch.push(item);
+    async reconcileDeletions(isInScope) {
+        try {
+            const deleted = (await listDeletedTrackedPaths(this.rootPath)).filter(isInScope);
+            for (const path of deleted)
+                this.pending.add(path);
+            if (deleted.length > 0) {
+                this.logger.info({ root: this.rootPath, count: deleted.length }, 'VCS startup reconciliation — queued tracked deletions');
+            }
         }
-        for (const item of batch) {
-            this.pending.delete(item);
+        catch (error) {
+            this.logger.warn({ root: this.rootPath, err: normalizeError(error) }, 'VCS startup deletion reconciliation failed');
         }
+    }
+    /** Take up to maxBatchSize files from the pending set. */
+    takeBatch() {
+        const batch = [...this.pending].slice(0, this.config.maxBatchSize);
+        for (const item of batch)
+            this.pending.delete(item);
         return batch;
     }
-    /**
-     * Clear the throttle timer.
-     */
+    /** Chain a batch behind the in-flight commit, tracking it as backlog. */
+    enqueueBatch(batch) {
+        this.inFlightFileCount += batch.length;
+        this.commitInFlight = this.commitInFlight.then(async () => {
+            try {
+                await this.commitBatch(batch);
+            }
+            finally {
+                this.inFlightFileCount -= batch.length;
+            }
+        });
+    }
+    /** Put files back in the pending set. Pending is a set, so this cannot grow it past the distinct paths seen. */
+    retain(files) {
+        for (const f of files)
+            this.pending.add(f);
+    }
     clearThrottle() {
-        if (this.throttleTimer !== undefined) {
-            clearTimeout(this.throttleTimer);
-            this.throttleTimer = undefined;
-        }
+        if (this.throttleTimer === undefined)
+            return;
+        clearTimeout(this.throttleTimer);
+        this.throttleTimer = undefined;
     }
     /**
      * Start the throttle timer to fire flush() after commitThrottleMs.
@@ -5606,117 +6075,148 @@ class VcsManager {
             void this.flush();
         }, this.config.commitThrottleMs);
     }
-    /**
-     * Check for and remove stale index.lock files before retrying.
-     */
-    async removeStaleLock() {
-        const lockPath = join(this.rootPath, '.git', 'index.lock');
-        try {
-            const lockStat = await stat(lockPath);
-            const ageMs = Date.now() - lockStat.mtimeMs;
-            if (ageMs > this.config.staleLockThresholdMs) {
-                await rm(lockPath, { force: true });
-                this.logger.warn({ root: this.rootPath, ageMs }, 'Removed stale index.lock');
-            }
-        }
-        catch (error) {
-            const code = error.code;
-            if (code !== 'ENOENT') {
-                this.logger.warn({ root: this.rootPath, err: normalizeError(error) }, 'Unable to remove stale index.lock');
-            }
-        }
+    clearBreakerRetry() {
+        if (this.breakerRetryTimer === undefined)
+            return;
+        clearTimeout(this.breakerRetryTimer);
+        this.breakerRetryTimer = undefined;
     }
     /**
-     * Check whether a git error represents a "nothing to commit" state.
-     * Git outputs this message to stdout (not stderr) on exit code 1.
+     * Ensure a timer will flush pending files when the breaker's cooldown
+     * elapses, without needing a new file-change event.
      */
-    isNothingToCommitError(error) {
-        const { message, stderr, stdout } = getExecErrorFields(error);
-        return (message.includes('nothing to commit') ||
-            stderr.includes('nothing to commit') ||
-            stdout.includes('nothing to commit'));
+    scheduleBreakerRetry() {
+        if (!this.started || this.breakerRetryTimer !== undefined)
+            return;
+        this.breakerRetryTimer = setTimeout(() => {
+            this.breakerRetryTimer = undefined;
+            void this.flush();
+        }, this.breaker.remainingCooldownMs());
     }
     /**
-     * Commit a batch of files to the git repo with index.lock retry,
-     * stale lock detection, circuit breaker, pause support, and re-queue cap.
+     * Commit a batch with index.lock retry, stale lock detection, pause
+     * support, and the circuit breaker. A failed batch is always retained.
      */
     async commitBatch(files) {
         if (files.length === 0)
             return;
-        // Pause support: re-queue files without counting as failure
         if (this.paused) {
-            for (const f of files) {
-                this.pending.add(f);
-            }
+            this.retain(files);
             this.logger.debug({ root: this.rootPath, fileCount: files.length }, 'VcsManager paused — files re-queued');
             return;
         }
-        // Circuit breaker: skip if too many consecutive failures
-        if (this.consecutiveCommitFailures >= this.config.maxConsecutiveFailures) {
-            this.logger.error({
-                root: this.rootPath,
-                consecutiveFailures: this.consecutiveCommitFailures,
-                discardedFiles: files.length,
-            }, 'VCS circuit breaker tripped — pending files discarded until next successful commit');
-            return;
+        if (this.breaker.isTripped) {
+            if (this.breaker.remainingCooldownMs() > 0) {
+                this.retain(files);
+                this.scheduleBreakerRetry();
+                return;
+            }
+            this.logger.info({ root: this.rootPath }, 'VCS circuit breaker half-open — attempting recovery commit');
         }
         try {
-            // Check for stale lock before first attempt
-            await this.removeStaleLock();
-            await retry(async (attempt) => {
-                await gitAddViaStdin(files, this.rootPath, GIT_TIMEOUT_STANDARD);
-                // Build message after staging so getStagedDiff can see the changes.
-                // Skip AI for baselines and retries — use template directly.
-                const message = this.isBaseline || attempt > 1
-                    ? this.commitMessageBuilder.buildTemplateMessage(files.length, this.isBaseline, this.pendingReversions)
-                    : await this.commitMessageBuilder.buildCommitMessage(files, this.isBaseline, this.pendingReversions);
-                this.pendingReversions.length = 0;
-                await execFileAsync('git', ['commit', '-m', message], {
-                    cwd: this.rootPath,
-                    timeout: GIT_TIMEOUT_STANDARD,
-                });
-                const { stdout: hashOut } = await execFileAsync('git', ['rev-parse', '--short', 'HEAD'], { cwd: this.rootPath, timeout: GIT_TIMEOUT_STANDARD });
-                const hash = hashOut.trim();
-                this.logger.info({ root: this.rootPath, hash, fileCount: files.length }, 'VCS commit created');
-                const pushTime = await pushToRemote(this.rootPath, this.remoteUrl, this.accessToken, this._pushErrors, this.logger);
-                if (pushTime)
-                    this._lastPushTime = pushTime;
-            }, {
+            await removeStaleIndexLock(this.rootPath, this.config.staleLockThresholdMs, this.logger);
+            const committed = await retry((attempt) => this.tryCommit(files, attempt), {
                 attempts: 4,
                 baseDelayMs: 500,
                 maxDelayMs: 2000,
+                // Only index.lock contention is transient. Anything else fails on
+                // the first attempt with its real message. See #249.
+                shouldRetry: isIndexLockError,
                 onRetry: ({ attempt, delayMs }) => {
                     this.logger.warn({ root: this.rootPath, attempt, delay: delayMs }, 'index.lock contention, retrying');
                 },
             });
-            // Success — reset circuit breaker
-            this.consecutiveCommitFailures = 0;
+            if (!committed) {
+                this.logger.info({ root: this.rootPath, fileCount: files.length }, 'VCS commit skipped — nothing staged');
+            }
+            this.onCommitSuccess();
         }
         catch (error) {
-            // Bug 5: "nothing to commit" is a no-op, not a failure
-            if (this.isNothingToCommitError(error)) {
-                this.logger.info({ root: this.rootPath, fileCount: files.length }, 'VCS commit skipped — nothing to commit');
-                return;
-            }
-            this.consecutiveCommitFailures++;
-            // Re-queue cap: only re-queue up to maxBatchSize files
-            const cap = this.config.maxBatchSize;
-            const toRequeue = files.slice(0, cap);
-            const overflow = files.length - toRequeue.length;
-            for (const f of toRequeue) {
-                this.pending.add(f);
-            }
-            if (overflow > 0) {
-                this.logger.warn({ root: this.rootPath, overflow, cap }, 'Re-queue cap exceeded — discarded overflow files');
-            }
-            this.logger.warn({ root: this.rootPath, fileCount: toRequeue.length }, 'Re-queued files after commit failure');
-            this.logger.error({ root: this.rootPath, err: normalizeError(error) }, 'VCS commit failed');
+            this.onCommitFailure(files, error);
+        }
+    }
+    /**
+     * One commit attempt: stage, skip if nothing is staged, commit, push.
+     *
+     * @returns true if a commit was created; false for a no-op.
+     */
+    async tryCommit(files, attempt) {
+        await stageBatch(files, this.rootPath, this.logger);
+        // "Nothing staged" is a no-op, detected without parsing git's text.
+        if (!(await hasStagedChanges(this.rootPath)))
+            return false;
+        // Build message after staging so getStagedDiff can see the changes.
+        // Skip AI for baselines and retries — use template directly.
+        const message = this.isBaseline || attempt > 1
+            ? this.commitMessageBuilder.buildTemplateMessage(files.length, this.isBaseline, this.pendingReversions)
+            : await this.commitMessageBuilder.buildCommitMessage(files, this.isBaseline, this.pendingReversions);
+        this.pendingReversions.length = 0;
+        const hash = await gitCommit(this.rootPath, message);
+        this.logger.info({ root: this.rootPath, hash, fileCount: files.length }, 'VCS commit created');
+        const pushTime = await pushToRemote(this.rootPath, this.remoteUrl, this.accessToken, this._pushErrors, this.logger);
+        if (pushTime)
+            this._lastPushTime = pushTime;
+        return true;
+    }
+    onCommitSuccess() {
+        if (!this.breaker.recordSuccess())
+            return;
+        this.clearBreakerRetry();
+        this.logger.info({ root: this.rootPath }, 'VCS circuit breaker recovered — resuming normal operation');
+    }
+    onCommitFailure(files, error) {
+        const err = normalizeError(error);
+        this.retain(files);
+        this.logger.warn({ root: this.rootPath, fileCount: files.length }, 'Re-queued files after commit failure');
+        this.logger.error({ root: this.rootPath, err }, 'VCS commit failed');
+        if (!this.breaker.recordFailure(err.message)) {
             // Bug 2: Restart throttle timer so re-queued files get retried
             this.resetThrottle();
+            return;
         }
+        this.logger.error({
+            root: this.rootPath,
+            consecutiveFailures: this.breaker.snapshot().consecutiveFailures,
+            pendingCount: this.pending.size,
+            cooldownMs: this.config.circuitBreakerCooldownMs,
+        }, 'VCS circuit breaker tripped — pending files retained, will retry after cooldown');
+        this.scheduleBreakerRetry();
     }
 }
 
+/**
+ * @module vcs/watchScope
+ * Build a predicate for "would the filesystem watcher observe this path?"
+ * from `watch.paths` and `watch.ignored`, using the watcher's own glob
+ * resolution. Used to scope VCS startup deletion reconciliation. See #249.
+ */
+/**
+ * Create a watch-scope predicate. A path is in scope if it matches a watch
+ * glob and neither it nor any ancestor directory matches a `watch.ignored`
+ * pattern (chokidar applies `ignored` to directories as well as files).
+ *
+ * @param watch - The `watch` section of the config.
+ * @returns The scope predicate.
+ */
+function createWatchScope(watch) {
+    const matchesGlobs = resolveWatchPaths(extractWatchPathStrings(watch.paths)).matches;
+    // Config `ignored` entries are strings, which resolveIgnored always turns
+    // into picomatch functions; the filter only narrows the union type.
+    const ignored = resolveIgnored(watch.ignored).filter((entry) => typeof entry === 'function');
+    return (normalizedPath) => {
+        if (!matchesGlobs(normalizedPath))
+            return false;
+        for (let current = normalizedPath;;) {
+            if (ignored.some((isIgnored) => isIgnored(current)))
+                return false;
+            const parent = normalizeSlashes(dirname(current));
+            if (parent === current)
+                return true;
+            current = parent;
+        }
+    };
+}
+
 /**
  * @module vcs/VcsCoordinator
  * Orchestrates VCS across all watch roots. Routes file events to the correct
@@ -5729,10 +6229,14 @@ class VcsCoordinator {
     managers = new Map();
     roots = [];
     logger;
+    isInWatchScope = () => false;
     constructor(config, logger) {
         this.logger = logger;
         if (!config.vcs?.enabled)
             return;
+        // Same watch-scope logic as the filesystem watcher (globs + ignored),
+        // used to filter startup deletion reconciliation. See #249.
+        this.isInWatchScope = createWatchScope(config.watch);
         const normalized = normalizeWatchPaths(config.watch.paths);
         for (const entry of normalized) {
             const rootVcs = entry.vcs?.enabled ?? config.vcs.enabled;
@@ -5811,6 +6315,11 @@ class VcsCoordinator {
      */
     async onInitialScanComplete() {
         for (const manager of this.managers.values()) {
+            // Reconcile tracked-but-deleted paths within this manager's watch
+            // scope before flushing, so the baseline commit records deletions
+            // that happened while the process wasn't watching. See #249.
+            await manager.reconcileDeletions((absPath) => this.findManagerForPath(absPath) === manager &&
+                this.isInWatchScope(absPath));
             await manager.flush();
             manager.endBaseline();
         }