@karmaniverous/jeeves-watcher 0.18.9 → 0.18.11

package/dist/index.js

@@ -1,6 +1,6 @@
 import { join, dirname, resolve, relative, extname, basename, isAbsolute, sep } from 'node:path';
 import { createConfigQueryHandler as createConfigQueryHandler$1, createStatusHandler, createConfigApplyHandler, substituteEnvVars, DEFAULT_PORTS, getBindAddress, postJson, fetchJson, getPackageVersion } from '@karmaniverous/jeeves';
-import { extractWatchPathStrings, inferenceRuleSchema, jeevesWatcherConfigSchema, normalizeWatchPaths, vcsRetentionConfigSchema, vcsAuthorConfigSchema, LOGGING_DEFAULTS, API_DEFAULTS, EMBEDDING_DEFAULTS, CONFIG_WATCH_DEFAULTS, WATCH_DEFAULTS, ROOT_DEFAULTS, INIT_CONFIG_TEMPLATE, DEFAULT_PORT as DEFAULT_PORT$1, PLUGIN_PACKAGE, SERVICE_PACKAGE, COMPONENT_NAME } from '@karmaniverous/jeeves-watcher-core';
+import { extractWatchPathStrings, inferenceRuleSchema, jeevesWatcherConfigSchema, normalizeWatchPaths, vcsRetentionConfigSchema, vcsAuthorConfigSchema, getEndpoint, LOGGING_DEFAULTS, API_DEFAULTS, EMBEDDING_DEFAULTS, CONFIG_WATCH_DEFAULTS, WATCH_DEFAULTS, ROOT_DEFAULTS, INIT_CONFIG_TEMPLATE, DEFAULT_PORT as DEFAULT_PORT$1, PLUGIN_PACKAGE, SERVICE_PACKAGE, COMPONENT_NAME } from '@karmaniverous/jeeves-watcher-core';
 export { apiConfigSchema, configWatchConfigSchema, embeddingConfigSchema, inferenceRuleSchema, jeevesWatcherConfigSchema, loggingConfigSchema, vectorStoreConfigSchema, watchConfigSchema } from '@karmaniverous/jeeves-watcher-core';
 import Fastify from 'fastify';
 import { readdir, stat, access, readFile, writeFile, mkdir, appendFile, rm } from 'node:fs/promises';
@@ -427,6 +427,39 @@ async function retry(fn, options) {
  */
 /** Promisified execFile for git commands. */
 const execFileAsync = promisify(execFile);
+/** Standard timeout (ms) for most git operations. */
+const GIT_TIMEOUT_STANDARD = 30_000;
+/** Extended timeout (ms) for cherry-pick operations. */
+const GIT_TIMEOUT_CHERRY_PICK = 120_000;
+/** Timeout (ms) for push operations. */
+const GIT_TIMEOUT_PUSH = 60_000;
+/**
+ * Extract string fields from a child-process error.
+ * Node's execFile wraps failures in an Error with `stderr`, `stdout`, and
+ * `code` properties that aren't part of the Error type.
+ */
+function getExecErrorFields(error) {
+    if (!(error instanceof Error)) {
+        return { message: String(error), stderr: '', stdout: '' };
+    }
+    const rec = error;
+    const stderr = typeof rec['stderr'] === 'string' ? rec['stderr'] : '';
+    const stdout = typeof rec['stdout'] === 'string' ? rec['stdout'] : '';
+    return { message: error.message || '', stderr, stdout };
+}
+/**
+ * Build an authenticated push URL by injecting a token into an HTTPS remote.
+ * Non-HTTPS URLs are returned as-is.
+ *
+ * @param remoteUrl - The remote repository URL.
+ * @param accessToken - Optional access token to inject.
+ * @returns The URL with the token injected if applicable.
+ */
+function buildAuthenticatedPushUrl(remoteUrl, accessToken) {
+    if (!accessToken)
+        return remoteUrl;
+    return remoteUrl.replace(/^https:\/\//, `https://${encodeURIComponent(accessToken)}@`);
+}
 /**
  * Stage files via stdin to avoid ENAMETOOLONG on Windows.
  *
@@ -438,22 +471,34 @@ const execFileAsync = promisify(execFile);
  *
  * @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.
  */
-function gitAddViaStdin(files, cwd) {
+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);
             }
         });
@@ -4320,8 +4365,8 @@ class CommitMessageBuilder {
      */
     async getStagedDiff() {
         try {
-            const { stdout: stat } = await execFileAsync('git', ['diff', '--cached', '--stat'], { cwd: this.rootPath });
-            const { stdout: patch } = await execFileAsync('git', ['diff', '--cached'], { cwd: this.rootPath });
+            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 });
             return `${stat}\n${patch}`;
         }
         catch {
@@ -4502,29 +4547,26 @@ function partMatches(part, value, min, max) {
     // Number with step doesn't make sense for single values, treat as exact
     return value === num;
 }
-/**
- * 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;
+    branch;
+    pauseCommits;
+    resumeCommits;
     remoteUrl;
     accessToken;
     logger;
     intervalTimer;
     running = false;
-    constructor(rootPath, retention, logger, remoteUrl, accessToken) {
+    constructor(rootPath, retention, logger, options = {}) {
         this.rootPath = rootPath;
         this.retention = retention;
         this.logger = logger;
-        this.remoteUrl = remoteUrl;
-        this.accessToken = accessToken;
+        this.branch = options.branch ?? 'master';
+        this.pauseCommits = options.pauseCommits;
+        this.resumeCommits = options.resumeCommits;
+        this.remoteUrl = options.remoteUrl;
+        this.accessToken = options.accessToken;
     }
     /**
      * Start the cron-based squash scheduler.
@@ -4554,6 +4596,9 @@ class SquashManager {
     }
     /**
      * Run the squash operation. Exposed publicly for testing.
+     *
+     * Coordinates with VcsManager by calling pause/resume callbacks
+     * to drain and suspend the commit pipeline during the squash.
      */
     async runSquash() {
         // Check for index.lock before starting multi-step operation
@@ -4567,6 +4612,16 @@ class SquashManager {
         catch {
             // No lock — proceed
         }
+        // Bug 3: Pause the commit pipeline before squash
+        try {
+            await this.pauseCommits?.();
+        }
+        catch (error) {
+            this.logger.error({ root: this.rootPath, err: normalizeError(error) }, 'Failed to pause commit pipeline before squash');
+            // Resume in case pause partially executed (flush succeeded but flag not set)
+            this.resumeCommits?.();
+            return { squashed: false, error: normalizeError(error).message };
+        }
         try {
             const commits = await this.getCommitLog();
             if (commits.length <= 1) {
@@ -4591,13 +4646,17 @@ class SquashManager {
             this.logger.error({ root: this.rootPath, err: normalizeError(error) }, 'Squash operation failed');
             return { squashed: false, error: message };
         }
+        finally {
+            // Bug 3: Always resume the commit pipeline
+            this.resumeCommits?.();
+        }
     }
     /**
      * Get all commits in chronological order (oldest first).
      */
     async getCommitLog() {
         try {
-            const { stdout } = await execFileAsync('git', ['log', '--format=%H %aI', '--reverse'], { cwd: this.rootPath });
+            const { stdout } = await execFileAsync('git', ['log', '--format=%H %aI', '--reverse'], { cwd: this.rootPath, timeout: GIT_TIMEOUT_STANDARD });
             if (!stdout.trim())
                 return [];
             return stdout
@@ -4644,32 +4703,35 @@ class SquashManager {
     }
     /**
      * Perform the squash: create orphan with baseline + cherry-pick retained commits.
+     * Uses the configured branch name instead of dynamic detection (Bug 1).
      */
     async performSquash(commits, boundaryIndex) {
         // The commit just before boundary is the last one to squash
         const baselineHash = commits[boundaryIndex - 1].hash;
-        // Get the current branch name
-        const { stdout: branchOut } = await execFileAsync('git', ['rev-parse', '--abbrev-ref', 'HEAD'], { cwd: this.rootPath });
-        const currentBranch = branchOut.trim();
+        // 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 });
+            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 });
+            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)
@@ -4677,28 +4739,33 @@ class SquashManager {
             if (commitsToCherry.length > 0) {
                 await execFileAsync('git', ['cherry-pick', ...commitsToCherry], {
                     cwd: this.rootPath,
+                    timeout: GIT_TIMEOUT_CHERRY_PICK,
                 });
             }
-            // 6. Force-update the original branch to the orphan
-            const { stdout: newHead } = await execFileAsync('git', ['rev-parse', 'HEAD'], { cwd: this.rootPath });
-            await execFileAsync('git', ['branch', '-f', currentBranch, newHead.trim()], { cwd: this.rootPath });
-            // 7. Switch back to original branch
-            await execFileAsync('git', ['checkout', currentBranch], {
+            // 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,
             });
         }
         catch (error) {
-            // Attempt cleanup: try to get back to original branch
+            // Attempt cleanup: try to get back to configured branch
             try {
-                await execFileAsync('git', ['checkout', '-f', currentBranch], {
+                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 {
@@ -4722,12 +4789,11 @@ class SquashManager {
         if (!this.remoteUrl)
             return;
         try {
-            const pushUrl = this.accessToken
-                ? this.remoteUrl.replace(/^https:\/\//, `https://${encodeURIComponent(this.accessToken)}@`)
-                : this.remoteUrl;
+            const pushUrl = buildAuthenticatedPushUrl(this.remoteUrl, this.accessToken);
             await execFileAsync('git', ['push', '--force', pushUrl, 'HEAD'], {
                 cwd: this.rootPath,
                 env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+                timeout: GIT_TIMEOUT_PUSH,
             });
             this.logger.info({ root: this.rootPath, remote: this.remoteUrl }, 'Squash force push succeeded');
         }
@@ -4828,6 +4894,46 @@ async function configureRepoIdentity(rootPath, name, email) {
         cwd: rootPath,
     });
 }
+/**
+ * Detect and recover from orphan branch state on startup.
+ *
+ * If the repo is on an unexpected branch (e.g. a leftover squash orphan),
+ * force-updates the expected branch to the current HEAD and checks it out.
+ * Orphan branches are NOT deleted — they serve as a recovery safety net.
+ *
+ * @param rootPath - Directory of the git repository.
+ * @param expectedBranch - The configured branch name (e.g. "master").
+ * @param logger - Logger instance for warnings and info.
+ */
+async function detectAndRecoverOrphanBranch(rootPath, expectedBranch, logger) {
+    const gitDir = join(rootPath, '.git');
+    try {
+        await access(gitDir);
+    }
+    catch {
+        // 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 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 headHash = headOut.trim();
+    // Force-update the expected branch to current HEAD
+    await execFileAsync('git', ['branch', '-f', expectedBranch, headHash], {
+        cwd: rootPath,
+        timeout: GIT_TIMEOUT_STANDARD,
+    });
+    // Checkout the expected branch
+    await execFileAsync('git', ['checkout', expectedBranch], {
+        cwd: rootPath,
+        timeout: GIT_TIMEOUT_STANDARD,
+    });
+    logger.info({ root: rootPath, recoveredFrom: currentBranch, expectedBranch, headHash }, 'Orphan branch recovery complete — now on configured branch');
+}
 /**
  * Ensure a .gitignore file exists at rootPath with all always-on entries.
  * Creates the file if missing. Appends only entries not already present.
@@ -4914,17 +5020,36 @@ function buildGlobMatcher(globs) {
         return isMatch(normalized);
     };
 }
+/**
+ * Expand a bare directory path (no glob characters) to a recursive glob.
+ * A path like `/opt/jeeves/content` becomes `/opt/jeeves/content/**`.
+ * Paths that already contain glob characters are returned unchanged.
+ *
+ * @param glob - A glob pattern or bare directory path.
+ * @returns The original glob, or the path suffixed with `/**` if bare.
+ */
+function expandBareDirectoryGlob(glob) {
+    const normalized = normalizeSlashes(glob);
+    if (/[*?{[\]]/.test(normalized))
+        return glob;
+    return glob.replace(/\/+$/, '') + '/**';
+}
 /**
  * Convert an array of glob patterns into chokidar-compatible directory roots
  * and a filter function for post-hoc event filtering.
  *
+ * Bare directory paths (no glob characters, e.g. `/opt/jeeves/content`) are
+ * automatically expanded to recursive globs (`/opt/jeeves/content/**`) so that
+ * picomatch matches all files underneath them.
+ *
  * @param globs - Glob patterns from the watch config.
  * @returns Object with `roots` (directories for chokidar) and `matches` (filter function).
  */
 function resolveWatchPaths(globs) {
-    const rawRoots = globs.map(globRoot);
+    const expandedGlobs = globs.map(expandBareDirectoryGlob);
+    const rawRoots = expandedGlobs.map(globRoot);
     const roots = deduplicateRoots(rawRoots);
-    const matches = buildGlobMatcher(globs);
+    const matches = buildGlobMatcher(expandedGlobs);
     return { roots, matches };
 }
 /**
@@ -4977,13 +5102,11 @@ async function pushToRemote(rootPath, remoteUrl, accessToken, pushErrors, logger
     if (!remoteUrl)
         return undefined;
     try {
-        // Build the authenticated URL if a token is available
-        const pushUrl = accessToken
-            ? remoteUrl.replace(/^https:\/\//, `https://${encodeURIComponent(accessToken)}@`)
-            : remoteUrl;
+        const pushUrl = buildAuthenticatedPushUrl(remoteUrl, accessToken);
         await execFileAsync('git', ['push', pushUrl, 'HEAD'], {
             cwd: rootPath,
             env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            timeout: GIT_TIMEOUT_PUSH,
         });
         const timestamp = new Date().toISOString();
         logger.info({ root: rootPath, remote: remoteUrl }, 'VCS push succeeded');
@@ -5008,7 +5131,7 @@ async function pushToRemote(rootPath, remoteUrl, accessToken, pushErrors, logger
  * Per-root VCS manager for git-backed content versioning.
  *
  * Each VCS-enabled watch root gets its own VcsManager instance, which owns
- * a debounced commit pipeline: file changes are batched, staged, committed
+ * a throttled commit pipeline: file changes are batched, staged, committed
  * (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
@@ -5025,10 +5148,11 @@ class VcsManager {
     pendingReversions = [];
     _pushErrors = [];
     squashManager;
-    debounceTimer;
+    throttleTimer;
     commitInFlight = Promise.resolve();
     consecutiveCommitFailures = 0;
     started = false;
+    paused = false;
     isBaseline = true;
     _lastPushTime = null;
     constructor(rootPath, config, logger, commitMessageGenerator, remoteUrl, accessToken) {
@@ -5039,7 +5163,17 @@ class VcsManager {
         this.accessToken = accessToken;
         this.commitMessageBuilder = new CommitMessageBuilder(rootPath, logger, commitMessageGenerator);
         if (config.retention) {
-            this.squashManager = new SquashManager(rootPath, config.retention, logger, remoteUrl, accessToken);
+            this.squashManager = new SquashManager(rootPath, config.retention, logger, {
+                branch: config.branch,
+                pauseCommits: () => {
+                    return this.pause();
+                },
+                resumeCommits: () => {
+                    this.resume();
+                },
+                remoteUrl,
+                accessToken,
+            });
         }
     }
     get lastPushTime() {
@@ -5052,10 +5186,21 @@ class VcsManager {
      * 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.
+     *
      * Baseline mode (commit prefix `"baseline:"`) remains active until
      * {@link endBaseline} is called by the coordinator after the initial scan.
      */
-    start() {
+    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);
+        }
+        catch (error) {
+            this.logger.error({ root: this.rootPath, err: normalizeError(error) }, 'Orphan branch recovery failed — continuing with current state');
+        }
         this.started = true;
         this.squashManager?.start();
         this.logger.info({ root: this.rootPath }, 'VcsManager started');
@@ -5068,7 +5213,7 @@ class VcsManager {
         this.isBaseline = false;
     }
     /**
-     * Add a file to the pending set and reset the debounce timer.
+     * Add a file to the pending set and start the throttle timer.
      * If the pending set exceeds maxBatchSize, flush immediately.
      *
      * @param filePath - Absolute path of the changed file.
@@ -5083,15 +5228,15 @@ class VcsManager {
         }
         this.pending.add(filePath);
         if (this.pending.size >= this.config.maxBatchSize) {
-            this.clearDebounce();
+            this.clearThrottle();
             const batch = this.takeBatch(this.config.maxBatchSize);
             this.commitInFlight = this.commitInFlight.then(() => this.commitBatch(batch));
             if (this.pending.size > 0) {
-                this.resetDebounce();
+                this.resetThrottle();
             }
             return;
         }
-        this.resetDebounce();
+        this.resetThrottle();
     }
     /**
      * Record reversion metadata so the next commit uses a revert-prefixed message.
@@ -5112,11 +5257,33 @@ class VcsManager {
             return;
         this.fileChanged(filePath);
     }
+    /**
+     * Pause the commit pipeline. Drains pending commits via flush(), then
+     * sets a flag that makes commitBatch queue instead of execute.
+     * Used by SquashManager to coordinate squash operations.
+     */
+    async pause() {
+        await this.flush();
+        this.paused = true;
+        this.logger.debug({ root: this.rootPath }, 'VcsManager paused');
+    }
+    /**
+     * Resume the commit pipeline after a pause.
+     * Re-enables normal commit operations and starts a throttle timer
+     * if there are pending files that accumulated during the pause.
+     */
+    resume() {
+        this.paused = false;
+        this.logger.debug({ root: this.rootPath }, 'VcsManager resumed');
+        if (this.pending.size > 0) {
+            this.resetThrottle();
+        }
+    }
     /**
      * Flush all pending files immediately.
      */
     async flush() {
-        this.clearDebounce();
+        this.clearThrottle();
         if (this.pending.size > 0) {
             const batch = [...this.pending];
             this.pending.clear();
@@ -5149,23 +5316,25 @@ class VcsManager {
         return batch;
     }
     /**
-     * Clear the debounce timer.
+     * Clear the throttle timer.
      */
-    clearDebounce() {
-        if (this.debounceTimer !== undefined) {
-            clearTimeout(this.debounceTimer);
-            this.debounceTimer = undefined;
+    clearThrottle() {
+        if (this.throttleTimer !== undefined) {
+            clearTimeout(this.throttleTimer);
+            this.throttleTimer = undefined;
         }
     }
     /**
-     * Reset the debounce timer to fire flush() after commitDebounceMs.
+     * Start the throttle timer to fire flush() after commitThrottleMs.
+     * If a timer is already running, do not reset it — this is throttle, not debounce.
      */
-    resetDebounce() {
-        this.clearDebounce();
-        this.debounceTimer = setTimeout(() => {
-            this.debounceTimer = undefined;
+    resetThrottle() {
+        if (this.throttleTimer !== undefined)
+            return;
+        this.throttleTimer = setTimeout(() => {
+            this.throttleTimer = undefined;
             void this.flush();
-        }, this.config.commitDebounceMs);
+        }, this.config.commitThrottleMs);
     }
     /**
      * Check for and remove stale index.lock files before retrying.
@@ -5187,13 +5356,31 @@ class VcsManager {
             }
         }
     }
+    /**
+     * Check whether a git error represents a "nothing to commit" state.
+     * Git outputs this message to stdout (not stderr) on exit code 1.
+     */
+    isNothingToCommitError(error) {
+        const { message, stderr, stdout } = getExecErrorFields(error);
+        return (message.includes('nothing to commit') ||
+            stderr.includes('nothing to commit') ||
+            stdout.includes('nothing to commit'));
+    }
     /**
      * Commit a batch of files to the git repo with index.lock retry,
-     * stale lock detection, circuit breaker, and re-queue cap.
+     * stale lock detection, circuit breaker, pause support, and re-queue cap.
      */
     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.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({
@@ -5207,7 +5394,7 @@ class VcsManager {
             // Check for stale lock before first attempt
             await this.removeStaleLock();
             await retry(async (attempt) => {
-                await gitAddViaStdin(files, this.rootPath);
+                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
@@ -5216,8 +5403,9 @@ class VcsManager {
                 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 });
+                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);
@@ -5235,6 +5423,11 @@ class VcsManager {
             this.consecutiveCommitFailures = 0;
         }
         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;
@@ -5248,6 +5441,8 @@ class VcsManager {
             }
             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');
+            // Bug 2: Restart throttle timer so re-queued files get retried
+            this.resetThrottle();
         }
     }
 }
@@ -5308,11 +5503,14 @@ class VcsCoordinator {
     }
     /**
      * Start all VcsManager instances.
+     * Runs startup orphan detection/recovery for each root.
      */
-    start() {
+    async start() {
+        const startPromises = [];
         this.managers.forEach((manager) => {
-            manager.start();
+            startPromises.push(manager.start());
         });
+        await Promise.all(startPromises);
         this.logger.info({ rootCount: this.managers.size }, 'VcsCoordinator started');
     }
     /**
@@ -5336,8 +5534,8 @@ class VcsCoordinator {
     /**
      * Signal that the initial filesystem scan is complete.
      *
-     * Flushes each manager's debounce buffer before ending baseline mode, ensuring
-     * any files still pending in the VCS debounce are committed with a
+     * Flushes each manager's throttle buffer before ending baseline mode, ensuring
+     * any files still pending in the VCS throttle are committed with a
      * `"baseline:"` prefix rather than `"watcher:"`. AI generation is not enabled
      * until all managers have completed their flush.
      */
@@ -5901,36 +6099,36 @@ function createApiServer(options) {
             };
         },
     });
-    app.get('/status', withCache(cacheTtlMs, async () => {
+    app.get(getEndpoint('status').path, withCache(cacheTtlMs, async () => {
         const result = await coreStatusHandler();
         return result.body;
     }));
-    app.post('/metadata', createMetadataHandler({
+    app.post(getEndpoint('metadata').path, createMetadataHandler({
         processor,
         getConfig,
         logger,
         configDir: dirname(configPath),
     }));
-    app.post('/render', withCache(cacheTtlMs, createRenderHandler({
+    app.post(getEndpoint('render').path, withCache(cacheTtlMs, createRenderHandler({
         processor,
         getWatch: () => getConfig().watch,
         logger,
     })));
-    app.get('/search/facets', createFacetsHandler({
+    app.get(getEndpoint('searchFacets').path, createFacetsHandler({
         getConfig,
         valuesManager,
         configDir: dirname(configPath),
     }));
-    app.post('/scan', createScanHandler({
+    app.post(getEndpoint('scan').path, createScanHandler({
         vectorStore,
         logger,
     }));
-    app.post('/walk', createWalkHandler({
+    app.post(getEndpoint('walk').path, createWalkHandler({
         getWatchPaths: () => extractWatchPathStrings(getConfig().watch.paths),
         getFileSystemWatcher,
         logger,
     }));
-    app.post('/search', createSearchHandler({
+    app.post(getEndpoint('search').path, createSearchHandler({
         embeddingProvider,
         vectorStore,
         logger,
@@ -5941,12 +6139,12 @@ function createApiServer(options) {
                 : undefined;
         },
     }));
-    app.post('/rebuild-metadata', createRebuildMetadataHandler({
+    app.post(getEndpoint('rebuildMetadata').path, createRebuildMetadataHandler({
         enrichmentStore: options.enrichmentStore,
         vectorStore,
         logger,
     }));
-    app.post('/reindex', createConfigReindexHandler({
+    app.post(getEndpoint('reindex').path, createConfigReindexHandler({
         getConfig,
         processor,
         logger,
@@ -5957,10 +6155,10 @@ function createApiServer(options) {
         vectorStore,
         queue,
     }));
-    app.get('/issues', withCache(cacheTtlMs, createIssuesHandler({ issuesManager })));
-    app.get('/config/schema', withCache(cacheTtlMs, createConfigSchemaHandler()));
-    app.post('/config/match', createConfigMatchHandler({ getConfig, logger }));
-    app.get('/config', withCache(cacheTtlMs, createConfigQueryHandler({
+    app.get(getEndpoint('issues').path, withCache(cacheTtlMs, createIssuesHandler({ issuesManager })));
+    app.get(getEndpoint('configSchema').path, withCache(cacheTtlMs, createConfigSchemaHandler()));
+    app.post(getEndpoint('configMatch').path, createConfigMatchHandler({ getConfig, logger }));
+    app.get(getEndpoint('config').path, withCache(cacheTtlMs, createConfigQueryHandler({
         getConfig,
         valuesManager,
         issuesManager,
@@ -5970,7 +6168,7 @@ function createApiServer(options) {
             ? () => virtualRuleStore.getAll()
             : undefined,
     })));
-    app.post('/config/validate', createConfigValidateHandler({
+    app.post(getEndpoint('configValidate').path, createConfigValidateHandler({
         getConfig,
         logger,
         configDir: dirname(configPath),
@@ -5984,7 +6182,7 @@ function createApiServer(options) {
             return Promise.resolve();
         },
     });
-    app.post('/config/apply', async (request, reply) => {
+    app.post(getEndpoint('configApply').path, async (request, reply) => {
         const { patch, replace } = request.body;
         const result = await coreConfigApplyHandler({ patch, replace });
         return reply.status(result.status).send(result.body);
@@ -6003,34 +6201,34 @@ function createApiServer(options) {
             gitignoreFilter,
             vectorStore,
         });
-        app.post('/rules/register', createRulesRegisterHandler({
+        app.post(getEndpoint('rulesRegister').path, createRulesRegisterHandler({
             virtualRuleStore,
             logger,
             onRulesChanged,
         }));
-        app.delete('/rules/unregister', createRulesUnregisterHandler({
+        app.delete(getEndpoint('rulesUnregister').path, createRulesUnregisterHandler({
             virtualRuleStore,
             logger,
             onRulesChanged,
         }));
-        app.delete('/rules/unregister/:source', createRulesUnregisterParamHandler({
+        app.delete(getEndpoint('rulesUnregisterBySource').path, createRulesUnregisterParamHandler({
             virtualRuleStore,
             logger,
             onRulesChanged,
         }));
-        app.post('/points/delete', createPointsDeleteHandler({ vectorStore, logger }));
-        app.post('/rules/reapply', createRulesReapplyHandler({ processor, vectorStore, logger }));
+        app.post(getEndpoint('pointsDelete').path, createPointsDeleteHandler({ vectorStore, logger }));
+        app.post(getEndpoint('rulesReapply').path, createRulesReapplyHandler({ processor, vectorStore, logger }));
     }
     // VCS routes — only registered when a VcsCoordinator is provided
     if (options.vcsCoordinator) {
         const coordinator = options.vcsCoordinator;
-        app.get('/vcs/status', createVcsStatusHandler({ coordinator, logger }));
-        app.get('/vcs/history', createVcsHistoryHandler({ coordinator, logger }));
-        app.get('/vcs/show', createVcsShowHandler({ coordinator, logger }));
-        app.get('/vcs/diff', createVcsDiffHandler({ coordinator, logger }));
-        app.get('/vcs/check-exclusion', createVcsCheckExclusionHandler({ coordinator, logger }));
-        app.post('/vcs/revert', createVcsRevertHandler({ coordinator, logger }));
-        app.post('/vcs/exclude', createVcsExcludeHandler({ coordinator, logger }));
+        app.get(getEndpoint('vcsStatus').path, createVcsStatusHandler({ coordinator, logger }));
+        app.get(getEndpoint('vcsHistory').path, createVcsHistoryHandler({ coordinator, logger }));
+        app.get(getEndpoint('vcsShow').path, createVcsShowHandler({ coordinator, logger }));
+        app.get(getEndpoint('vcsDiff').path, createVcsDiffHandler({ coordinator, logger }));
+        app.get(getEndpoint('vcsCheckExclusion').path, createVcsCheckExclusionHandler({ coordinator, logger }));
+        app.post(getEndpoint('vcsRevert').path, createVcsRevertHandler({ coordinator, logger }));
+        app.post(getEndpoint('vcsExclude').path, createVcsExcludeHandler({ coordinator, logger }));
     }
     return app;
 }
@@ -9129,7 +9327,7 @@ class JeevesWatcher {
         this.watcher = watcher;
         this.gitignoreFilter = gitignoreFilter;
         this.server = await this.startApiServer();
-        vcsCoordinator.start();
+        await vcsCoordinator.start();
         this.watcher.start();
         this.startConfigWatch();
         logger.info('jeeves-watcher started');