@karmaniverous/jeeves-watcher 0.19.0-3 → 0.19.1

package/dist/cli/jeeves-watcher/index.js

@@ -265,7 +265,7 @@ async function startFromConfig(configPath, descriptor) {
     const config = await loadConfig(resolvedPath);
     // Dynamic import breaks the circular dependency between this module
     // and app/index.ts (which defines JeevesWatcher and re-exports startFromConfig).
-    const { JeevesWatcher } = await import('./index-CD0v-oGg.js');
+    const { JeevesWatcher } = await import('./index-C_bf9c9m.js');
     const app = new JeevesWatcher(config, resolvedPath, descriptor);
     installShutdownHandlers(() => app.stop());
     await app.start();
@@ -636,6 +636,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 {
@@ -644,7 +645,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 });
@@ -656,10 +657,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. */
@@ -681,49 +700,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'`).
+ *
+ * @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.
  *
- * 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.
+ * 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 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.
+ * @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.
@@ -736,6 +743,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.
@@ -1639,4 +1657,4 @@ const watcherDescriptor = {
 const program = createServiceCli(watcherDescriptor);
 program.parse();
 
-export { CONFIG_WATCH_VALID_SCOPES as C, GIT_TIMEOUT_STANDARD as G, VALID_REINDEX_SCOPES as V, normalizeError as a, GIT_TIMEOUT_CHERRY_PICK as b, GIT_TIMEOUT_PUSH as c, gitAddViaStdin as d, execFileAsync as e, normalizePathCase as f, getExecErrorFields as g, findRootForPath as h, GitignoreFilter as i, executeReindex as j, isPathWatched as k, getWatchRootBases as l, mergeInferenceRules as m, normalizeSlashes as n, loadConfig as o, startFromConfig as p, retry as r, sleep as s };
+export { CONFIG_WATCH_VALID_SCOPES as C, GIT_TIMEOUT_STANDARD as G, VALID_REINDEX_SCOPES as V, normalizeError as a, getErrorCode as b, GIT_TIMEOUT_CHERRY_PICK as c, GIT_TIMEOUT_PUSH as d, execFileAsync as e, normalizePathCase as f, gitArgs as g, findRootForPath as h, isIndexLockError as i, GitignoreFilter as j, executeReindex as k, isPathWatched as l, mergeInferenceRules as m, normalizeSlashes as n, getWatchRootBases as o, pathKey as p, loadConfig as q, retry as r, sleep as s, startFromConfig as t };

package/dist/index.d.ts

@@ -1227,6 +1227,25 @@ declare class EventQueue {
     private maybeResolveIdleWorkers;
 }
 
+/**
+ * @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.
+ */
+/** Serializable breaker state. */
+interface CircuitBreakerSnapshot {
+    /** Consecutive commit failures since the last success. */
+    consecutiveFailures: number;
+    /** Whether the breaker is tripped. */
+    tripped: boolean;
+    /** ISO timestamp of the current trip, or null. */
+    trippedAt: string | null;
+    /** Message of the most recent failure, or null. */
+    lastError: string | null;
+}
+
 /**
  * @module vcs/CommitMessageGenerator
  * Generates AI-powered commit messages via the Anthropic Messages API.
@@ -1272,6 +1291,11 @@ interface PushError {
  * Per-root VCS manager for git-backed content versioning.
  */
 
+/** Per-root circuit breaker state, exposed via /vcs/status. */
+interface VcsBreakerState extends CircuitBreakerSnapshot {
+    /** Files queued or in flight, not yet committed. */
+    pendingCount: number;
+}
 /**
  * Per-root VCS manager for git-backed content versioning.
  *
@@ -1280,7 +1304,9 @@ interface PushError {
  * (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).
  */
 declare class VcsManager {
     readonly config: VcsConfig;
@@ -1289,13 +1315,15 @@ declare class VcsManager {
     private readonly accessToken;
     private readonly logger;
     private readonly commitMessageBuilder;
+    private readonly breaker;
     private readonly pending;
     private readonly pendingReversions;
     private readonly _pushErrors;
     private readonly squashManager;
     private throttleTimer;
+    private breakerRetryTimer;
     private commitInFlight;
-    private consecutiveCommitFailures;
+    private inFlightFileCount;
     private started;
     private paused;
     private isBaseline;
@@ -1303,12 +1331,15 @@ declare class VcsManager {
     constructor(rootPath: string, config: VcsConfig, logger: pino.Logger, commitMessageGenerator?: CommitMessageGenerator, remoteUrl?: string, accessToken?: string);
     get lastPushTime(): string | null;
     get pushErrors(): readonly PushError[];
+    /** Current circuit breaker state and backlog, for /vcs/status. */
+    get breakerState(): VcsBreakerState;
     /**
      * 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.
@@ -1321,7 +1352,10 @@ declare class VcsManager {
     endBaseline(): void;
     /**
      * 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.
      */
@@ -1333,8 +1367,7 @@ declare class VcsManager {
      */
     addPendingReversion(reversion: PendingReversion): void;
     /**
-     * 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.
      */
@@ -1352,7 +1385,7 @@ declare class VcsManager {
      */
     resume(): void;
     /**
-     * Flush all pending files immediately.
+     * Commit all pending files now, in batches of at most maxBatchSize.
      */
     flush(): Promise<void>;
     /**
@@ -1360,32 +1393,46 @@ declare class VcsManager {
      */
     stop(): Promise<void>;
     /**
-     * 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).
      */
+    reconcileDeletions(isInScope: (absolutePath: string) => boolean): Promise<void>;
+    /** Take up to maxBatchSize files from the pending set. */
     private takeBatch;
-    /**
-     * Clear the throttle timer.
-     */
+    /** Chain a batch behind the in-flight commit, tracking it as backlog. */
+    private enqueueBatch;
+    /** Put files back in the pending set. Pending is a set, so this cannot grow it past the distinct paths seen. */
+    private retain;
     private clearThrottle;
     /**
      * Start the throttle timer to fire flush() after commitThrottleMs.
      * If a timer is already running, do not reset it — this is throttle, not debounce.
      */
     private resetThrottle;
+    private clearBreakerRetry;
     /**
-     * Check for and remove stale index.lock files before retrying.
+     * Ensure a timer will flush pending files when the breaker's cooldown
+     * elapses, without needing a new file-change event.
      */
-    private removeStaleLock;
+    private scheduleBreakerRetry;
     /**
-     * Check whether a git error represents a "nothing to commit" state.
-     * Git outputs this message to stdout (not stderr) on exit code 1.
+     * Commit a batch with index.lock retry, stale lock detection, pause
+     * support, and the circuit breaker. A failed batch is always retained.
      */
-    private isNothingToCommitError;
+    private commitBatch;
     /**
-     * Commit a batch of files to the git repo with index.lock retry,
-     * stale lock detection, circuit breaker, pause support, and re-queue cap.
+     * One commit attempt: stage, skip if nothing is staged, commit, push.
+     *
+     * @returns true if a commit was created; false for a no-op.
      */
-    private commitBatch;
+    private tryCommit;
+    private onCommitSuccess;
+    private onCommitFailure;
 }
 
 /**
@@ -1401,6 +1448,7 @@ declare class VcsCoordinator {
     private readonly managers;
     private readonly roots;
     private readonly logger;
+    private readonly isInWatchScope;
     constructor(config: JeevesWatcherConfig, logger: pino.Logger);
     /**
      * Start all VcsManager instances.
@@ -1952,15 +2000,6 @@ interface CommitInfo {
     hash: string;
     date: Date;
 }
-/**
- * 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).
- */
 /** Options for SquashManager construction beyond the required params. */
 interface SquashManagerOptions {
     /** Git branch name for squash operations. Default: "master". */
@@ -1974,6 +2013,15 @@ interface SquashManagerOptions {
     /** Access token for HTTPS push authentication. */
     accessToken?: string;
 }
+/**
+ * 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).
+ */
 declare class SquashManager {
     private readonly rootPath;
     private readonly retention;
@@ -2002,6 +2050,14 @@ declare class SquashManager {
      * to drain and suspend the commit pipeline during the squash.
      */
     runSquash(): Promise<SquashResult>;
+    /**
+     * 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.
+     */
+    private checkRepoPreconditions;
     /**
      * Get all commits in chronological order (oldest first).
      */
@@ -2022,6 +2078,12 @@ declare class SquashManager {
      * Uses the configured branch name instead of dynamic detection (Bug 1).
      */
     private performSquash;
+    /**
+     * 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.
+     */
+    private cleanupFailedSquash;
     /**
      * Force push to remote after squash (history rewrite requires force).
      */