@karmaniverous/jeeves-watcher 0.18.9 → 0.18.11

package/dist/cli/jeeves-watcher/{index-xP2XrV4W.js → index-ZbXuE9a7.js}

@@ -1,7 +1,7 @@
 #!/usr/bin/env node
 import { createConfigQueryHandler as createConfigQueryHandler$1, createStatusHandler, createConfigApplyHandler, DEFAULT_PORTS, getBindAddress } from '@karmaniverous/jeeves';
-import { d as normalizeSlashes, n as normalizeError, e as execFileAsync, r as retry, b as gitAddViaStdin, c as normalizePathCase, f as findRootForPath, G as GitignoreFilter, a as executeReindex, V as VALID_REINDEX_SCOPES, m as mergeInferenceRules, i as isPathWatched, g as getWatchRootBases, C as CONFIG_WATCH_VALID_SCOPES, s as sleep, l as loadConfig } from './index.js';
-export { h as startFromConfig } from './index.js';
+import { p as normalizeSlashes, n as normalizeError, e as execFileAsync, b as GIT_TIMEOUT_STANDARD, G as GIT_TIMEOUT_CHERRY_PICK, d as buildAuthenticatedPushUrl, a as GIT_TIMEOUT_PUSH, h as getExecErrorFields, r as retry, j as gitAddViaStdin, o as normalizePathCase, g as findRootForPath, c as GitignoreFilter, f as executeReindex, V as VALID_REINDEX_SCOPES, m as mergeInferenceRules, k as isPathWatched, i as getWatchRootBases, C as CONFIG_WATCH_VALID_SCOPES, s as sleep, l as loadConfig } from './index.js';
+export { q as startFromConfig } from './index.js';
 import { mkdirSync, existsSync, readFileSync, writeFileSync, rmSync, renameSync, readdirSync, statSync } from 'node:fs';
 import { join, dirname, resolve, extname, basename, relative, sep, isAbsolute } from 'node:path';
 import Database from 'better-sqlite3';
@@ -10,9 +10,9 @@ import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import picomatch from 'picomatch';
 import { deserialize, serialize } from 'node:v8';
-import { normalizeWatchPaths, vcsRetentionConfigSchema, extractWatchPathStrings, vcsAuthorConfigSchema, inferenceRuleSchema, jeevesWatcherConfigSchema } from '@karmaniverous/jeeves-watcher-core';
+import { normalizeWatchPaths, vcsRetentionConfigSchema, extractWatchPathStrings, vcsAuthorConfigSchema, inferenceRuleSchema, jeevesWatcherConfigSchema, getEndpoint } from '@karmaniverous/jeeves-watcher-core';
 import { homedir } from 'node:os';
-import { access, rm, stat, readFile, writeFile, appendFile, mkdir } from 'node:fs/promises';
+import { access, rm, readFile, writeFile, appendFile, stat, mkdir } from 'node:fs/promises';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { packageDirectorySync } from 'package-directory';
 import { JsonMap } from '@karmaniverous/jsonmap';
@@ -803,17 +803,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 };
 }
 /**
@@ -1033,8 +1052,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 {
@@ -1102,29 +1121,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.
@@ -1154,6 +1170,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
@@ -1167,6 +1186,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) {
@@ -1191,13 +1220,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
@@ -1244,32 +1277,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)
@@ -1277,28 +1313,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 {
@@ -1322,12 +1363,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');
         }
@@ -1337,6 +1377,133 @@ class SquashManager {
     }
 }
 
+/**
+ * @module vcs/vcsBootstrap
+ * Static bootstrap utilities for VCS-managed watch roots.
+ */
+/** Always-on .gitignore entries for VCS-managed watch roots. */
+const ALWAYS_GITIGNORE_ENTRIES = [
+    '.git/',
+    'node_modules/',
+    '.jeeves-watcher/',
+    '.jeeves-metadata/',
+];
+/**
+ * Check whether git is available on the system PATH.
+ *
+ * @returns true if git is available, false otherwise.
+ */
+async function checkGitAvailable() {
+    try {
+        await execFileAsync('git', ['--version']);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+/**
+ * Initialize a git repository at the given path if none exists.
+ * Idempotent — does nothing if .git/ already exists.
+ *
+ * @param rootPath - Directory to initialize as a git repo.
+ */
+async function initRepo(rootPath) {
+    const gitDir = join(rootPath, '.git');
+    try {
+        await access(gitDir);
+        // .git exists, nothing to do
+    }
+    catch {
+        await execFileAsync('git', ['init'], { cwd: rootPath });
+    }
+}
+/**
+ * Configure local git identity for a repository.
+ * Sets repo-level (not global) user.name and user.email.
+ *
+ * @param rootPath - Directory of the git repository.
+ * @param name - Author name for commits.
+ * @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,
+    });
+}
+/**
+ * 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.
+ *
+ * @param rootPath - Directory containing the .gitignore.
+ * @param alwaysOnEntries - Additional always-on entries beyond the defaults.
+ */
+async function ensureGitignore(rootPath, alwaysOnEntries = []) {
+    const gitignorePath = join(rootPath, '.gitignore');
+    const requiredEntries = [...ALWAYS_GITIGNORE_ENTRIES, ...alwaysOnEntries];
+    let existingContent = '';
+    try {
+        existingContent = await readFile(gitignorePath, 'utf8');
+    }
+    catch {
+        // File doesn't exist yet
+    }
+    const existingLines = new Set(existingContent.split('\n').map((line) => line.trim()));
+    const missing = requiredEntries.filter((entry) => !existingLines.has(entry));
+    if (missing.length === 0)
+        return;
+    if (existingContent.length === 0) {
+        await writeFile(gitignorePath, missing.join('\n') + '\n', 'utf8');
+    }
+    else {
+        const prefix = existingContent.endsWith('\n') ? '' : '\n';
+        await appendFile(gitignorePath, prefix + missing.join('\n') + '\n', 'utf8');
+    }
+}
+
 /**
  * @module vcs/vcsPush
  * Push logic for VCS commits.
@@ -1358,13 +1525,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');
@@ -1389,7 +1554,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
@@ -1406,10 +1571,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) {
@@ -1420,7 +1586,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() {
@@ -1433,10 +1609,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');
@@ -1449,7 +1636,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.
@@ -1464,15 +1651,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.
@@ -1493,11 +1680,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();
@@ -1530,23 +1739,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.
@@ -1568,13 +1779,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({
@@ -1588,7 +1817,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
@@ -1597,8 +1826,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);
@@ -1616,6 +1846,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;
@@ -1629,6 +1864,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();
         }
     }
 }
@@ -1689,11 +1926,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');
     }
     /**
@@ -1717,8 +1957,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.
      */
@@ -3044,93 +3284,6 @@ function validateStateDirOverlap(stateDir, watchPaths) {
     }
 }
 
-/**
- * @module vcs/vcsBootstrap
- * Static bootstrap utilities for VCS-managed watch roots.
- */
-/** Always-on .gitignore entries for VCS-managed watch roots. */
-const ALWAYS_GITIGNORE_ENTRIES = [
-    '.git/',
-    'node_modules/',
-    '.jeeves-watcher/',
-    '.jeeves-metadata/',
-];
-/**
- * Check whether git is available on the system PATH.
- *
- * @returns true if git is available, false otherwise.
- */
-async function checkGitAvailable() {
-    try {
-        await execFileAsync('git', ['--version']);
-        return true;
-    }
-    catch {
-        return false;
-    }
-}
-/**
- * Initialize a git repository at the given path if none exists.
- * Idempotent — does nothing if .git/ already exists.
- *
- * @param rootPath - Directory to initialize as a git repo.
- */
-async function initRepo(rootPath) {
-    const gitDir = join(rootPath, '.git');
-    try {
-        await access(gitDir);
-        // .git exists, nothing to do
-    }
-    catch {
-        await execFileAsync('git', ['init'], { cwd: rootPath });
-    }
-}
-/**
- * Configure local git identity for a repository.
- * Sets repo-level (not global) user.name and user.email.
- *
- * @param rootPath - Directory of the git repository.
- * @param name - Author name for commits.
- * @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,
-    });
-}
-/**
- * Ensure a .gitignore file exists at rootPath with all always-on entries.
- * Creates the file if missing. Appends only entries not already present.
- *
- * @param rootPath - Directory containing the .gitignore.
- * @param alwaysOnEntries - Additional always-on entries beyond the defaults.
- */
-async function ensureGitignore(rootPath, alwaysOnEntries = []) {
-    const gitignorePath = join(rootPath, '.gitignore');
-    const requiredEntries = [...ALWAYS_GITIGNORE_ENTRIES, ...alwaysOnEntries];
-    let existingContent = '';
-    try {
-        existingContent = await readFile(gitignorePath, 'utf8');
-    }
-    catch {
-        // File doesn't exist yet
-    }
-    const existingLines = new Set(existingContent.split('\n').map((line) => line.trim()));
-    const missing = requiredEntries.filter((entry) => !existingLines.has(entry));
-    if (missing.length === 0)
-        return;
-    if (existingContent.length === 0) {
-        await writeFile(gitignorePath, missing.join('\n') + '\n', 'utf8');
-    }
-    else {
-        const prefix = existingContent.endsWith('\n') ? '' : '\n';
-        await appendFile(gitignorePath, prefix + missing.join('\n') + '\n', 'utf8');
-    }
-}
-
 /**
  * @module app/watcherFactory
  * Factory helpers for creating and rebuilding the filesystem watcher.
@@ -5412,36 +5565,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,
@@ -5452,12 +5605,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,
@@ -5468,10 +5621,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,
@@ -5481,7 +5634,7 @@ function createApiServer(options) {
             ? () => virtualRuleStore.getAll()
             : undefined,
     })));
-    app.post('/config/validate', createConfigValidateHandler({
+    app.post(getEndpoint('configValidate').path, createConfigValidateHandler({
         getConfig,
         logger,
         configDir: dirname(configPath),
@@ -5495,7 +5648,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);
@@ -5514,34 +5667,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;
 }
@@ -7855,7 +8008,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');