@karmaniverous/jeeves-watcher 0.17.11 → 0.18.1

package/dist/cli/jeeves-watcher/{index-DXiOIyDK.js → index-1dpUCttm.js}

@@ -1,15 +1,20 @@
 #!/usr/bin/env node
 import { createConfigQueryHandler as createConfigQueryHandler$1, createStatusHandler, createConfigApplyHandler, DEFAULT_PORTS, getBindAddress } from '@karmaniverous/jeeves';
-import { a as normalizeSlashes, n as normalizeError, G as GitignoreFilter, e as executeReindex, V as VALID_REINDEX_SCOPES, m as mergeInferenceRules, i as isPathWatched, g as getWatchRootBases, C as CONFIG_WATCH_VALID_SCOPES, r as retry, s as sleep, l as loadConfig } from './index.js';
+import { a as normalizeSlashes, n as normalizeError, r as retry, G as GitignoreFilter, e 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 { b as startFromConfig } from './index.js';
 import { mkdirSync, existsSync, readFileSync, writeFileSync, rmSync, renameSync, readdirSync, statSync } from 'node:fs';
-import { join, dirname, resolve, extname, basename, isAbsolute } from 'node:path';
+import { join, dirname, resolve, extname, basename, relative, sep, isAbsolute } from 'node:path';
 import Database from 'better-sqlite3';
 import { z } from 'zod';
 import Ajv from 'ajv';
 import addFormats from 'ajv-formats';
 import picomatch from 'picomatch';
 import { deserialize, serialize } from 'node:v8';
+import { normalizeWatchPaths, extractWatchPathStrings, inferenceRuleSchema, jeevesWatcherConfigSchema } from '@karmaniverous/jeeves-watcher-core';
+import { execFile } from 'node:child_process';
+import { promisify } from 'node:util';
+import { homedir } from 'node:os';
+import { access, rm, readFile, writeFile, appendFile, mkdir, stat } from 'node:fs/promises';
 import { pathToFileURL, fileURLToPath } from 'node:url';
 import { packageDirectorySync } from 'package-directory';
 import { JsonMap } from '@karmaniverous/jsonmap';
@@ -24,12 +29,10 @@ import { unified } from 'unified';
 import yaml from 'js-yaml';
 import chokidar from 'chokidar';
 import Fastify from 'fastify';
-import { inferenceRuleSchema, jeevesWatcherConfigSchema } from '@karmaniverous/jeeves-watcher-core';
 import crypto from 'crypto';
 import https from 'node:https';
 import { createHash } from 'node:crypto';
 import pino from 'pino';
-import { readFile, stat } from 'node:fs/promises';
 import { v5 } from 'uuid';
 import * as cheerio from 'cheerio';
 import mammoth from 'mammoth';
@@ -744,6 +747,837 @@ class ValuesManager extends BinaryFileStore {
     }
 }
 
+/**
+ * @module vcs/CommitMessageGenerator
+ * Generates AI-powered commit messages via the Anthropic Messages API.
+ */
+/** Maximum characters of diff to send to the AI. */
+const MAX_DIFF_CHARS = 4000;
+/** Maximum length of the generated commit message. */
+const MAX_MESSAGE_LENGTH = 100;
+/** Request timeout in milliseconds. */
+const REQUEST_TIMEOUT_MS = 15000;
+/** System prompt for the commit message generator. */
+const SYSTEM_PROMPT = 'You are a commit message generator. Given file changes, produce a single concise one-line commit message. No prefix. No punctuation at end';
+/**
+ * Generates AI commit messages using the Anthropic Messages API.
+ */
+class CommitMessageGenerator {
+    provider;
+    model;
+    apiKey;
+    logger;
+    constructor(provider, model, apiKey, logger) {
+        this.provider = provider;
+        this.model = model;
+        this.apiKey = apiKey;
+        this.logger = logger;
+    }
+    /**
+     * Generate a commit message from file changes.
+     *
+     * @param files - List of changed file paths.
+     * @param diffSummary - Combined diff output (stat + patch).
+     * @returns A one-line commit message, or null on failure.
+     */
+    async generate(files, diffSummary) {
+        if (!this.apiKey) {
+            this.logger.warn('No API key configured for commit message generation');
+            return null;
+        }
+        if (this.provider !== 'anthropic') {
+            this.logger.warn({ provider: this.provider }, 'Unsupported commit message provider; only "anthropic" is supported');
+            return null;
+        }
+        const truncatedDiff = diffSummary.slice(0, MAX_DIFF_CHARS);
+        const userPrompt = `Files changed:\n${files.join('\n')}\n\nDiff:\n${truncatedDiff}`;
+        try {
+            const body = JSON.stringify({
+                model: this.model,
+                max_tokens: 256,
+                system: SYSTEM_PROMPT,
+                messages: [{ role: 'user', content: userPrompt }],
+            });
+            const response = await fetch('https://api.anthropic.com/v1/messages', {
+                method: 'POST',
+                headers: {
+                    'Content-Type': 'application/json',
+                    'x-api-key': this.apiKey,
+                    'anthropic-version': '2023-06-01',
+                },
+                body,
+                signal: AbortSignal.timeout(REQUEST_TIMEOUT_MS),
+            });
+            if (!response.ok) {
+                const text = await response.text();
+                this.logger.warn({ status: response.status, body: text }, 'Anthropic API returned non-OK status');
+                return null;
+            }
+            const data = (await response.json());
+            const textBlock = data.content?.find((b) => b.type === 'text');
+            if (!textBlock?.text) {
+                this.logger.warn('Anthropic API returned no text content');
+                return null;
+            }
+            const message = textBlock.text.trim().slice(0, MAX_MESSAGE_LENGTH);
+            this.logger.debug({ message }, 'AI commit message generated');
+            return message;
+        }
+        catch (error) {
+            this.logger.warn({ err: normalizeError(error) }, 'Failed to generate AI commit message');
+            return null;
+        }
+    }
+}
+
+/**
+ * @module vcs/gitExec
+ * Shared git execution utilities.
+ */
+/** Promisified execFile for git commands. */
+const execFileAsync = promisify(execFile);
+/**
+ * Find the longest-prefix-match root for a normalized path.
+ * Roots must be sorted longest-first for correct nested matching.
+ *
+ * @param roots - Root paths sorted longest-first.
+ * @param normalizedPath - Normalized absolute path (forward slashes).
+ * @returns The matching root, or undefined.
+ */
+function findRootForPath(roots, normalizedPath) {
+    for (const root of roots) {
+        if (normalizedPath === root || normalizedPath.startsWith(root + '/')) {
+            return root;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * @module vcs/resolveCommitMessageApiKey
+ * Resolves the API key for AI commit message generation.
+ */
+/**
+ * Resolve the API key for commit message generation.
+ * Checks config first, then falls back to OpenClaw gateway credentials.
+ */
+function resolveCommitMessageApiKey(provider, configApiKey, logger) {
+    if (configApiKey) {
+        logger.debug('Using commit message API key from config');
+        return configApiKey;
+    }
+    try {
+        const openclawPath = join(homedir(), '.openclaw', 'openclaw.json');
+        const raw = readFileSync(openclawPath, 'utf8');
+        const parsed = JSON.parse(raw);
+        const gatewayKey = parsed.models?.providers?.[provider]?.apiKey;
+        if (gatewayKey) {
+            logger.debug({ provider }, 'Using commit message API key from OpenClaw gateway config');
+            return gatewayKey;
+        }
+        logger.warn({ provider }, 'OpenClaw gateway config found but no API key for provider');
+    }
+    catch {
+        logger.warn('No commit message API key in config or OpenClaw gateway');
+    }
+    return undefined;
+}
+
+/**
+ * @module vcs/SquashManager
+ * Handles scheduled squash retention for git-backed VCS roots.
+ */
+/**
+ * Parse a standard 5-field cron expression and check if the current time matches.
+ * Fields: minute hour dom month dow
+ * Supports: numbers, wildcards, lists (1,3,5), ranges (1-5), steps (star/5)
+ */
+function cronMatchesNow(cronExpr, now = new Date()) {
+    const fields = cronExpr.trim().split(/\s+/);
+    if (fields.length !== 5)
+        return false;
+    const minute = now.getMinutes();
+    const hour = now.getHours();
+    const dom = now.getDate();
+    const month = now.getMonth() + 1; // 1-based
+    const dow = now.getDay(); // 0=Sunday
+    return (fieldMatches(fields[0], minute, 0, 59) &&
+        fieldMatches(fields[1], hour, 0, 23) &&
+        fieldMatches(fields[2], dom, 1, 31) &&
+        fieldMatches(fields[3], month, 1, 12) &&
+        fieldMatches(fields[4], dow, 0, 7) // 7 also means Sunday
+    );
+}
+function fieldMatches(field, value, min, max) {
+    for (const part of field.split(',')) {
+        if (partMatches(part.trim(), value, min, max))
+            return true;
+    }
+    return false;
+}
+function partMatches(part, value, min, max) {
+    // Handle step: */N or range/N
+    const [rangePart, stepStr] = part.split('/');
+    const step = stepStr ? parseInt(stepStr, 10) : 1;
+    if (rangePart === '*') {
+        return (value - min) % step === 0;
+    }
+    // Handle range: N-M
+    if (rangePart.includes('-')) {
+        const [startStr, endStr] = rangePart.split('-');
+        const start = parseInt(startStr, 10);
+        const end = parseInt(endStr, 10);
+        if (value < start || value > end)
+            return false;
+        return (value - start) % step === 0;
+    }
+    // Plain number
+    const num = parseInt(rangePart, 10);
+    if (step === 1) {
+        // For dow, treat 7 as 0 (Sunday)
+        if (max === 7 && num === 7)
+            return value === 0;
+        return value === num;
+    }
+    // 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;
+    remoteUrl;
+    accessToken;
+    logger;
+    intervalTimer;
+    running = false;
+    constructor(rootPath, retention, logger, remoteUrl, accessToken) {
+        this.rootPath = rootPath;
+        this.retention = retention;
+        this.logger = logger;
+        this.remoteUrl = remoteUrl;
+        this.accessToken = accessToken;
+    }
+    /**
+     * Start the cron-based squash scheduler.
+     * Checks every 60 seconds if the cron expression matches.
+     */
+    start() {
+        if (this.running)
+            return;
+        this.running = true;
+        this.intervalTimer = setInterval(() => {
+            if (cronMatchesNow(this.retention.squashCron)) {
+                void this.runSquash();
+            }
+        }, 60_000);
+        this.logger.info({ root: this.rootPath, cron: this.retention.squashCron }, 'SquashManager started');
+    }
+    /**
+     * Stop the cron scheduler.
+     */
+    stop() {
+        this.running = false;
+        if (this.intervalTimer !== undefined) {
+            clearInterval(this.intervalTimer);
+            this.intervalTimer = undefined;
+        }
+        this.logger.info({ root: this.rootPath }, 'SquashManager stopped');
+    }
+    /**
+     * Run the squash operation. Exposed publicly for testing.
+     */
+    async runSquash() {
+        // Check for index.lock before starting multi-step operation
+        const lockPath = join(this.rootPath, '.git', 'index.lock');
+        try {
+            await access(lockPath);
+            // Lock exists — abort and retry next cycle
+            this.logger.warn({ root: this.rootPath }, 'Squash aborted: index.lock exists, will retry next cycle');
+            return { squashed: false, error: 'index.lock exists' };
+        }
+        catch {
+            // No lock — proceed
+        }
+        try {
+            const commits = await this.getCommitLog();
+            if (commits.length <= 1) {
+                return { squashed: false };
+            }
+            const boundaryIndex = this.calculateRetentionBoundary(commits);
+            if (boundaryIndex <= 0) {
+                // All commits are within retention or only one commit before boundary
+                return { squashed: false };
+            }
+            // Perform the squash
+            await this.performSquash(commits, boundaryIndex);
+            const commitsRemoved = boundaryIndex;
+            const commitsRetained = commits.length - boundaryIndex;
+            this.logger.info({ root: this.rootPath, commitsRemoved, commitsRetained }, 'Squash retention completed');
+            // Force push if remote configured
+            await this.forcePushIfConfigured();
+            return { squashed: true, commitsRemoved, commitsRetained };
+        }
+        catch (error) {
+            const message = normalizeError(error).message;
+            this.logger.error({ root: this.rootPath, err: normalizeError(error) }, 'Squash operation failed');
+            return { squashed: false, error: message };
+        }
+    }
+    /**
+     * Get all commits in chronological order (oldest first).
+     */
+    async getCommitLog() {
+        try {
+            const { stdout } = await execFileAsync('git', ['log', '--format=%H %aI', '--reverse'], { cwd: this.rootPath });
+            if (!stdout.trim())
+                return [];
+            return stdout
+                .trim()
+                .split('\n')
+                .map((line) => {
+                const spaceIdx = line.indexOf(' ');
+                return {
+                    hash: line.slice(0, spaceIdx),
+                    date: new Date(line.slice(spaceIdx + 1)),
+                };
+            });
+        }
+        catch {
+            return [];
+        }
+    }
+    /**
+     * Calculate the retention boundary index.
+     * Returns the index of the oldest commit to KEEP.
+     * All commits before this index will be squashed into a baseline.
+     *
+     * Strategy: find the tighter constraint between age and count.
+     * - Age: keep commits newer than maxAgeDays
+     * - Count: keep the last maxVersions commits
+     * The boundary is the one that retains FEWER old commits (tighter).
+     */
+    calculateRetentionBoundary(commits) {
+        const now = new Date();
+        const maxAgeMs = this.retention.maxAgeDays * 24 * 60 * 60 * 1000;
+        const cutoffDate = new Date(now.getTime() - maxAgeMs);
+        // Find the first commit that is within the age window (to keep)
+        let ageBoundary = commits.length; // Default: all too old
+        for (let i = 0; i < commits.length; i++) {
+            if (commits[i].date >= cutoffDate) {
+                ageBoundary = i;
+                break;
+            }
+        }
+        // Count boundary: keep the last maxVersions commits
+        const countBoundary = Math.max(0, commits.length - this.retention.maxVersions);
+        // The tighter constraint wins (keeps fewer old commits = higher boundary index)
+        return Math.max(ageBoundary, countBoundary);
+    }
+    /**
+     * Perform the squash: create orphan with baseline + cherry-pick retained commits.
+     */
+    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();
+        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,
+            });
+            // 2. Reset index to the baseline tree (the last squashed commit's tree)
+            await execFileAsync('git', ['reset', '--hard', baselineHash], {
+                cwd: this.rootPath,
+            });
+            // 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 treeHash = treeOut.trim();
+            const { stdout: commitOut } = await execFileAsync('git', ['commit-tree', treeHash, '-m', 'historical baseline'], { cwd: this.rootPath });
+            const baselineCommitHash = commitOut.trim();
+            // 4. Reset orphan branch to this new baseline commit
+            await execFileAsync('git', ['reset', '--hard', baselineCommitHash], {
+                cwd: this.rootPath,
+            });
+            // 5. Cherry-pick boundary..HEAD (the retained commits)
+            // Get the list of commits to cherry-pick (from boundary to the end)
+            const commitsToCherry = commits.slice(boundaryIndex).map((c) => c.hash);
+            if (commitsToCherry.length > 0) {
+                await execFileAsync('git', ['cherry-pick', ...commitsToCherry], {
+                    cwd: this.rootPath,
+                });
+            }
+            // 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], {
+                cwd: this.rootPath,
+            });
+            // 8. Delete orphan branch
+            await execFileAsync('git', ['branch', '-D', orphanBranch], {
+                cwd: this.rootPath,
+            });
+        }
+        catch (error) {
+            // Attempt cleanup: try to get back to original branch
+            try {
+                await execFileAsync('git', ['checkout', '-f', currentBranch], {
+                    cwd: this.rootPath,
+                });
+                await execFileAsync('git', ['branch', '-D', orphanBranch], {
+                    cwd: this.rootPath,
+                });
+            }
+            catch {
+                // Cleanup failed — log but re-throw original error
+            }
+            // Remove index.lock if left behind
+            try {
+                const lockFile = join(this.rootPath, '.git', 'index.lock');
+                await rm(lockFile, { force: true });
+            }
+            catch {
+                // ignore
+            }
+            throw error;
+        }
+    }
+    /**
+     * Force push to remote after squash (history rewrite requires force).
+     */
+    async forcePushIfConfigured() {
+        if (!this.remoteUrl)
+            return;
+        try {
+            const pushUrl = this.accessToken
+                ? this.remoteUrl.replace(/^https:\/\//, `https://${encodeURIComponent(this.accessToken)}@`)
+                : this.remoteUrl;
+            await execFileAsync('git', ['push', '--force', pushUrl, 'HEAD'], {
+                cwd: this.rootPath,
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            });
+            this.logger.info({ root: this.rootPath, remote: this.remoteUrl }, 'Squash force push succeeded');
+        }
+        catch (error) {
+            this.logger.error({ root: this.rootPath, err: normalizeError(error) }, 'Squash force push failed');
+        }
+    }
+}
+
+/**
+ * @module vcs/VcsManager
+ * Per-root VCS manager for git-backed content versioning.
+ */
+/**
+ * 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
+ * (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).
+ */
+class VcsManager {
+    config;
+    rootPath;
+    remoteUrl;
+    accessToken;
+    logger;
+    commitMessageGenerator;
+    pending = new Set();
+    pendingReversions = [];
+    _pushErrors = [];
+    squashManager;
+    debounceTimer;
+    commitInFlight = Promise.resolve();
+    started = false;
+    _lastPushTime = null;
+    constructor(rootPath, config, logger, commitMessageGenerator, remoteUrl, accessToken) {
+        this.rootPath = rootPath;
+        this.config = config;
+        this.logger = logger;
+        this.commitMessageGenerator = commitMessageGenerator;
+        this.remoteUrl = remoteUrl;
+        this.accessToken = accessToken;
+        if (config.retention) {
+            this.squashManager = new SquashManager(rootPath, config.retention, logger, remoteUrl, accessToken);
+        }
+    }
+    get lastPushTime() {
+        return this._lastPushTime;
+    }
+    get pushErrors() {
+        return this._pushErrors;
+    }
+    /**
+     * Begin accepting file changes. Sets up the debounce mechanism.
+     */
+    start() {
+        this.started = true;
+        this.squashManager?.start();
+        this.logger.info({ root: this.rootPath }, 'VcsManager started');
+    }
+    /**
+     * Add a file to the pending set and reset the debounce timer.
+     * If the pending set exceeds maxBatchSize, flush immediately.
+     *
+     * @param filePath - Absolute path of the changed file.
+     */
+    fileChanged(filePath) {
+        if (!this.started)
+            return;
+        this.pending.add(filePath);
+        if (this.pending.size >= this.config.maxBatchSize) {
+            this.clearDebounce();
+            const batch = this.takeBatch(this.config.maxBatchSize);
+            this.commitInFlight = this.commitInFlight.then(() => this.commitBatch(batch));
+            if (this.pending.size > 0) {
+                this.resetDebounce();
+            }
+            return;
+        }
+        this.resetDebounce();
+    }
+    /**
+     * Record reversion metadata so the next commit uses a revert-prefixed message.
+     *
+     * @param reversion - The reversion metadata to record.
+     */
+    addPendingReversion(reversion) {
+        this.pendingReversions.push(reversion);
+    }
+    /**
+     * Stage a file deletion and add to pending set.
+     * git add handles deleted files when the file is gone from disk.
+     *
+     * @param filePath - Absolute path of the deleted file.
+     */
+    handleUnlink(filePath) {
+        if (!this.started)
+            return;
+        this.fileChanged(filePath);
+    }
+    /**
+     * Flush all pending files immediately.
+     */
+    async flush() {
+        this.clearDebounce();
+        if (this.pending.size > 0) {
+            const batch = [...this.pending];
+            this.pending.clear();
+            this.commitInFlight = this.commitInFlight.then(() => this.commitBatch(batch));
+        }
+        await this.commitInFlight;
+    }
+    /**
+     * Stop accepting file changes, flush pending, and clean up timers.
+     */
+    async stop() {
+        this.started = false;
+        this.squashManager?.stop();
+        await this.flush();
+        this.logger.info({ root: this.rootPath }, 'VcsManager stopped');
+    }
+    /**
+     * Take up to N items from the pending set.
+     */
+    takeBatch(n) {
+        const batch = [];
+        for (const item of this.pending) {
+            if (batch.length >= n)
+                break;
+            batch.push(item);
+        }
+        for (const item of batch) {
+            this.pending.delete(item);
+        }
+        return batch;
+    }
+    /**
+     * Clear the debounce timer.
+     */
+    clearDebounce() {
+        if (this.debounceTimer !== undefined) {
+            clearTimeout(this.debounceTimer);
+            this.debounceTimer = undefined;
+        }
+    }
+    /**
+     * Reset the debounce timer to fire flush() after commitDebounceMs.
+     */
+    resetDebounce() {
+        this.clearDebounce();
+        this.debounceTimer = setTimeout(() => {
+            this.debounceTimer = undefined;
+            void this.flush();
+        }, this.config.commitDebounceMs);
+    }
+    /**
+     * Get the cached diff for staged files, for AI context.
+     */
+    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 });
+            return `${stat}\n${patch}`;
+        }
+        catch {
+            return '';
+        }
+    }
+    /**
+     * Build the template commit message (no AI).
+     */
+    buildTemplateMessage(fileCount) {
+        if (this.pendingReversions.length === 0) {
+            const timestamp = new Date().toISOString();
+            return `watcher: batch ${timestamp} (${String(fileCount)} files)`;
+        }
+        // Count total reverted files across all pending reversions
+        const revertedPaths = new Set(this.pendingReversions.flatMap((r) => r.paths));
+        const revertedCount = revertedPaths.size;
+        const otherCount = fileCount - revertedCount;
+        // Use the first reversion's glob and commit for the message
+        const { glob, commit } = this.pendingReversions[0];
+        const shortCommit = commit.slice(0, 7);
+        let message = `revert: ${glob} to ${shortCommit} — restored ${String(revertedCount)} files`;
+        if (otherCount > 0) {
+            message += ` (+ ${String(otherCount)} other changes)`;
+        }
+        return message;
+    }
+    /**
+     * Build the commit message, using AI when available with template fallback.
+     */
+    async buildCommitMessage(files) {
+        const fileCount = files.length;
+        const templateMessage = this.buildTemplateMessage(fileCount);
+        if (!this.commitMessageGenerator) {
+            return templateMessage;
+        }
+        try {
+            const diffSummary = await this.getStagedDiff();
+            const aiMessage = await this.commitMessageGenerator.generate(files, diffSummary);
+            if (!aiMessage) {
+                this.logger.warn('AI commit message generation returned null; using template');
+                return templateMessage;
+            }
+            // For reversions: prefix with revert info + AI description
+            if (this.pendingReversions.length > 0) {
+                const { glob, commit } = this.pendingReversions[0];
+                const shortCommit = commit.slice(0, 7);
+                return `revert: ${glob} to ${shortCommit} — ${aiMessage}`;
+            }
+            return aiMessage;
+        }
+        catch (error) {
+            this.logger.warn({ err: normalizeError(error) }, 'AI commit message generation failed; using template');
+            return templateMessage;
+        }
+    }
+    /**
+     * Commit a batch of files to the git repo with index.lock retry.
+     */
+    async commitBatch(files) {
+        if (files.length === 0)
+            return;
+        try {
+            await retry(async (attempt) => {
+                await execFileAsync('git', ['add', '--', ...files], {
+                    cwd: this.rootPath,
+                });
+                // Build message after staging so getStagedDiff can see the changes
+                const message = attempt === 1
+                    ? await this.buildCommitMessage(files)
+                    : this.buildTemplateMessage(files.length);
+                this.pendingReversions.length = 0;
+                await execFileAsync('git', ['commit', '-m', message], {
+                    cwd: this.rootPath,
+                });
+                const { stdout: hashOut } = await execFileAsync('git', ['rev-parse', '--short', 'HEAD'], { cwd: this.rootPath });
+                const hash = hashOut.trim();
+                this.logger.info({ root: this.rootPath, hash, fileCount: files.length }, 'VCS commit created');
+                await this.pushIfConfigured();
+            }, {
+                attempts: 4,
+                baseDelayMs: 500,
+                maxDelayMs: 2000,
+                onRetry: ({ attempt, delayMs }) => {
+                    this.logger.warn({ root: this.rootPath, attempt, delay: delayMs }, 'index.lock contention, retrying');
+                },
+            });
+        }
+        catch (error) {
+            for (const f of files) {
+                this.pending.add(f);
+            }
+            this.logger.warn({ root: this.rootPath, fileCount: files.length }, 'Re-queued files after commit failure');
+            this.logger.error({ root: this.rootPath, err: normalizeError(error) }, 'VCS commit failed');
+        }
+    }
+    /**
+     * Push to the configured remote if remoteUrl is set.
+     * On failure: logs the error and records it in pushErrors; never throws.
+     */
+    async pushIfConfigured() {
+        if (!this.remoteUrl)
+            return;
+        try {
+            // Build the authenticated URL if a token is available
+            const pushUrl = this.accessToken
+                ? this.remoteUrl.replace(/^https:\/\//, `https://${encodeURIComponent(this.accessToken)}@`)
+                : this.remoteUrl;
+            await execFileAsync('git', ['push', pushUrl, 'HEAD'], {
+                cwd: this.rootPath,
+                env: { ...process.env, GIT_TERMINAL_PROMPT: '0' },
+            });
+            this._lastPushTime = new Date().toISOString();
+            this.logger.info({ root: this.rootPath, remote: this.remoteUrl }, 'VCS push succeeded');
+        }
+        catch (error) {
+            const pushError = {
+                timestamp: new Date().toISOString(),
+                message: normalizeError(error).message,
+            };
+            this._pushErrors.push(pushError);
+            this.logger.error({ root: this.rootPath, err: normalizeError(error) }, 'VCS push failed');
+        }
+    }
+}
+
+/**
+ * @module vcs/VcsCoordinator
+ * Orchestrates VCS across all watch roots. Routes file events to the correct
+ * root's VcsManager instance.
+ */
+/**
+ * Orchestrates VCS across all VCS-enabled watch roots.
+ */
+class VcsCoordinator {
+    managers = new Map();
+    roots = [];
+    logger;
+    constructor(config, logger) {
+        this.logger = logger;
+        if (!config.vcs?.enabled)
+            return;
+        const normalized = normalizeWatchPaths(config.watch.paths);
+        for (const entry of normalized) {
+            const rootVcs = entry.vcs?.enabled ?? config.vcs.enabled;
+            if (!rootVcs)
+                continue;
+            if (/[*?{[]/.test(entry.path)) {
+                logger.warn({ path: entry.path }, 'Skipping VCS for watch path containing glob characters');
+                continue;
+            }
+            const resolvedRoot = normalizeSlashes(resolve(entry.path));
+            const mergedConfig = {
+                ...config.vcs,
+                ...entry.vcs,
+                enabled: true,
+            };
+            // Create CommitMessageGenerator if AI commit messages are configured
+            const cmConfig = mergedConfig.commitMessage;
+            const rootLogger = logger.child({ vcsRoot: resolvedRoot });
+            const resolvedApiKey = cmConfig?.enabled !== false
+                ? resolveCommitMessageApiKey(cmConfig?.provider ?? 'anthropic', cmConfig?.apiKey, rootLogger)
+                : undefined;
+            const generator = cmConfig?.enabled !== false && resolvedApiKey
+                ? new CommitMessageGenerator(cmConfig?.provider ?? 'anthropic', cmConfig?.model ?? 'claude-haiku-4-0', resolvedApiKey, rootLogger)
+                : undefined;
+            // Resolve remote config: per-root overrides fall back to root-level defaults
+            const remoteUrl = entry.vcs?.remote;
+            const accessToken = entry.vcs?.accessToken ?? config.vcs.defaultAccessToken;
+            const manager = new VcsManager(resolvedRoot, mergedConfig, logger.child({ vcsRoot: resolvedRoot }), generator, remoteUrl, accessToken);
+            this.managers.set(resolvedRoot, manager);
+            this.roots.push(resolvedRoot);
+        }
+        // Sort roots longest-first so nested paths match before parents.
+        this.roots.sort((a, b) => b.length - a.length);
+    }
+    /**
+     * Start all VcsManager instances.
+     */
+    start() {
+        this.managers.forEach((manager) => {
+            manager.start();
+        });
+        this.logger.info({ rootCount: this.managers.size }, 'VcsCoordinator started');
+    }
+    /**
+     * Route a file event to the correct root's VcsManager.
+     *
+     * @param filePath - Absolute path of the changed file.
+     * @param event - The event type: add, change, or unlink.
+     */
+    onFileChange(filePath, event) {
+        const normalizedPath = normalizeSlashes(resolve(filePath));
+        const manager = this.findManagerForPath(normalizedPath);
+        if (!manager)
+            return;
+        if (event === 'unlink') {
+            manager.handleUnlink(normalizedPath);
+        }
+        else {
+            manager.fileChanged(normalizedPath);
+        }
+    }
+    /**
+     * Flush all managers and clean up.
+     */
+    async stop() {
+        const stopPromises = [];
+        this.managers.forEach((manager) => {
+            stopPromises.push(manager.stop());
+        });
+        await Promise.all(stopPromises);
+        this.logger.info('VcsCoordinator stopped');
+    }
+    /**
+     * Get the sorted root paths (longest-first).
+     */
+    getRoots() {
+        return this.roots;
+    }
+    /**
+     * Get the VcsManager for a specific root path.
+     */
+    getManager(root) {
+        return this.managers.get(root);
+    }
+    /**
+     * Get all managers as [root, manager] pairs.
+     */
+    getAllManagers() {
+        return this.managers;
+    }
+    /**
+     * Find the VcsManager that owns the given normalized file path.
+     * Uses longest-prefix-match against resolved watch roots.
+     *
+     * @param normalizedPath - Normalized absolute path (forward slashes).
+     * @returns The matching VcsManager, or undefined.
+     */
+    findManagerForPath(normalizedPath) {
+        const root = findRootForPath(this.roots, normalizedPath);
+        return root ? this.managers.get(root) : undefined;
+    }
+}
+
 /**
  * @module helpers/loadModule
  * Shared utility for loading and namespace-prefixing exports from helper modules.
@@ -1925,7 +2759,164 @@ async function applyRules(compiledRules, attributes, options = {}) {
             }
         }
     }
-    return { metadata: merged, renderedContent, matchedRules, renderAs };
+    return { metadata: merged, renderedContent, matchedRules, renderAs };
+}
+
+/**
+ * @module vcs/resolveWatchRoot
+ * Resolves which VCS-enabled watch root(s) own a given absolute path or glob.
+ */
+/**
+ * Resolve which VCS-enabled watch root owns an absolute path.
+ *
+ * @param coordinator - The VcsCoordinator with root information.
+ * @param absolutePath - An absolute filesystem path.
+ * @returns The matching root and relative path, or undefined if no root matches.
+ */
+function resolveWatchRoot(coordinator, absolutePath) {
+    const normalized = normalizeSlashes(resolve(absolutePath));
+    const root = findRootForPath(coordinator.getRoots(), normalized);
+    if (!root)
+        return undefined;
+    return {
+        root,
+        relativePath: normalizeSlashes(relative(root, normalized)),
+    };
+}
+/**
+ * Resolve which VCS-enabled watch roots match a glob pattern.
+ * For globs that could span multiple roots, returns all matching roots.
+ *
+ * @param coordinator - The VcsCoordinator with root information.
+ * @param glob - An absolute glob pattern.
+ * @returns Array of matching roots with relative glob patterns.
+ */
+function resolveWatchRootsForGlob(coordinator, glob) {
+    const normalizedGlob = normalizeSlashes(glob);
+    const roots = coordinator.getRoots();
+    const results = [];
+    for (const root of roots) {
+        if (normalizedGlob.startsWith(root + '/') || normalizedGlob === root) {
+            // Glob is under this root
+            results.push({
+                root,
+                relativePath: normalizeSlashes(relative(root, normalizedGlob)),
+            });
+        }
+        else if (root.startsWith(normalizedGlob.replace(/[*?[\]{}]/g, ''))) {
+            // Root is under the glob's base path — include with root-relative glob
+            results.push({
+                root,
+                relativePath: '.',
+            });
+        }
+    }
+    return results;
+}
+
+/**
+ * @module vcs/validateStateDirOverlap
+ * Validates that stateDir does not overlap with any watch path.
+ */
+/**
+ * Validate that stateDir does not overlap with any watch path.
+ * Overlap means stateDir is a parent, child, or equal to a watch path.
+ *
+ * @param stateDir - The state directory path.
+ * @param watchPaths - Array of watch path strings.
+ * @throws Error if stateDir overlaps with any watch path.
+ */
+function validateStateDirOverlap(stateDir, watchPaths) {
+    const resolvedStateDir = resolve(stateDir);
+    for (const watchPath of watchPaths) {
+        const resolvedWatch = resolve(watchPath);
+        if (resolvedStateDir === resolvedWatch) {
+            throw new Error(`stateDir "${stateDir}" is the same as watch path "${watchPath}". They must not overlap.`);
+        }
+        const stateDirWithSep = resolvedStateDir.endsWith(sep)
+            ? resolvedStateDir
+            : resolvedStateDir + sep;
+        const watchWithSep = resolvedWatch.endsWith(sep)
+            ? resolvedWatch
+            : resolvedWatch + sep;
+        if (resolvedWatch.startsWith(stateDirWithSep)) {
+            throw new Error(`Watch path "${watchPath}" is inside stateDir "${stateDir}". They must not overlap.`);
+        }
+        if (resolvedStateDir.startsWith(watchWithSep)) {
+            throw new Error(`stateDir "${stateDir}" is inside watch path "${watchPath}". They must not overlap.`);
+        }
+    }
+}
+
+/**
+ * @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 });
+    }
+}
+/**
+ * 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');
+    }
 }
 
 /**
@@ -1995,10 +2986,10 @@ function createProcessorConfig(config, configDir, customMapLib) {
 /**
  * Create file system watcher with gitignore filtering.
  */
-function createWatcher(config, factories, queue, processor, logger, runtimeOptions, initialScanTracker, contentHashCache) {
+function createWatcher(config, factories, queue, processor, logger, runtimeOptions, initialScanTracker, contentHashCache, onVcsFileChange) {
     const respectGitignore = config.watch.respectGitignore ?? true;
     const gitignoreFilter = respectGitignore
-        ? new GitignoreFilter(config.watch.paths)
+        ? new GitignoreFilter(extractWatchPathStrings(config.watch.paths))
         : undefined;
     const watcher = factories.createFileSystemWatcher(config.watch, queue, processor, logger, {
         maxRetries: config.maxRetries ?? runtimeOptions.maxRetries,
@@ -2007,6 +2998,7 @@ function createWatcher(config, factories, queue, processor, logger, runtimeOptio
         gitignoreFilter,
         initialScanTracker,
         contentHashCache,
+        onVcsFileChange,
     });
     return { watcher, gitignoreFilter };
 }
@@ -2078,6 +3070,41 @@ function resolveVersion(referenceUrl) {
         return 'unknown';
     }
 }
+/**
+ * Initialize VCS for all watch roots where VCS is enabled.
+ * Checks git availability, validates stateDir overlap, and initializes repos.
+ *
+ * @param config - The resolved configuration (mutated in place if git unavailable).
+ * @param logger - Logger instance.
+ * @returns The effective VCS enabled state (false if git unavailable).
+ */
+async function initVcs(config, logger) {
+    if (!config.vcs?.enabled)
+        return false;
+    const gitAvailable = await checkGitAvailable();
+    if (!gitAvailable) {
+        logger.warn('git not found on PATH — VCS disabled for this session');
+        return false;
+    }
+    const stateDir = config.stateDir ?? '.jeeves-metadata';
+    const pathStrings = extractWatchPathStrings(config.watch.paths);
+    const staticPaths = pathStrings.filter((p) => !/[*?{[]/.test(p));
+    validateStateDirOverlap(stateDir, staticPaths);
+    const normalized = normalizeWatchPaths(config.watch.paths);
+    for (const entry of normalized) {
+        const rootVcs = entry.vcs?.enabled ?? config.vcs.enabled;
+        if (!rootVcs)
+            continue;
+        if (/[*?{[]/.test(entry.path)) {
+            logger.warn({ path: entry.path }, 'Skipping VCS init for watch path containing glob characters');
+            continue;
+        }
+        await initRepo(entry.path);
+        await ensureGitignore(entry.path);
+        logger.info({ root: entry.path }, 'VCS initialized for watch root');
+    }
+    return true;
+}
 
 /**
  * @module app/configReload
@@ -2283,7 +3310,9 @@ function createConfigMatchHandler(options) {
         const config = getConfig();
         if (config !== cachedConfig) {
             compiledRules = compileRules(config.inferenceRules ?? []);
-            watchMatcher = picomatch(config.watch.paths, { dot: true });
+            watchMatcher = picomatch(extractWatchPathStrings(config.watch.paths), {
+                dot: true,
+            });
             ignoreMatcher = config.watch.ignored.length
                 ? picomatch(config.watch.ignored, { dot: true })
                 : undefined;
@@ -3180,7 +4209,7 @@ function createRenderHandler(deps) {
         }
         // Validate path is within watched scope (live config)
         const watch = getWatch();
-        if (!isPathWatched(filePath, watch.paths, watch.ignored)) {
+        if (!isPathWatched(filePath, extractWatchPathStrings(watch.paths), watch.ignored)) {
             return reply.status(403).send({ error: 'Path is outside watched scope' });
         }
         try {
@@ -3373,6 +4402,504 @@ function createSearchHandler(deps) {
     }, deps.logger, 'Search');
 }
 
+/**
+ * @module api/handlers/vcs/vcsCheckExclusion
+ * Fastify route handler for GET /vcs/check-exclusion. Checks gitignore status of a path.
+ */
+/**
+ * Create handler for GET /vcs/check-exclusion.
+ */
+function createVcsCheckExclusionHandler(deps) {
+    return wrapHandler(async (request, reply) => {
+        const { path } = request.query;
+        if (!path) {
+            void reply
+                .status(400)
+                .send({ error: 'Missing required query parameter: path' });
+            return;
+        }
+        const resolved = resolveWatchRoot(deps.coordinator, path);
+        if (!resolved) {
+            void reply
+                .status(404)
+                .send({ error: 'Path does not match any VCS-enabled watch root' });
+            return;
+        }
+        try {
+            const { stdout } = await execFileAsync('git', ['check-ignore', '-v', resolved.relativePath], { cwd: resolved.root });
+            // Output format: <source>:<linenum>:<pattern>\t<pathname>
+            const trimmed = stdout.trim();
+            const match = /^(.+):(\d+):(.+)\t/.exec(trimmed);
+            if (match) {
+                return {
+                    excluded: true,
+                    rule: match[3].trim(),
+                    source: match[1],
+                };
+            }
+            return { excluded: true };
+        }
+        catch {
+            // Exit code 1 means the path is NOT ignored
+            return { excluded: false };
+        }
+    }, deps.logger, 'VcsCheckExclusion');
+}
+
+/**
+ * @module api/handlers/vcs/vcsDiff
+ * Fastify route handler for GET /vcs/diff. Returns diff text for a glob between commits.
+ */
+/**
+ * Create handler for GET /vcs/diff.
+ */
+function createVcsDiffHandler(deps) {
+    return wrapHandler(async (request, reply) => {
+        const { glob, commit, commitEnd } = request.query;
+        if (!glob || !commit) {
+            void reply
+                .status(400)
+                .send({ error: 'Missing required query parameters: glob, commit' });
+            return;
+        }
+        const resolved = resolveWatchRootsForGlob(deps.coordinator, glob);
+        if (resolved.length === 0) {
+            void reply
+                .status(404)
+                .send({ error: 'No VCS-enabled watch root matches the given glob' });
+            return;
+        }
+        const diffs = [];
+        for (const { root, relativePath } of resolved) {
+            const range = commitEnd ? `${commit}..${commitEnd}` : `${commit}..HEAD`;
+            const args = ['diff', range, '--', relativePath || '.'];
+            try {
+                const { stdout } = await execFileAsync('git', args, { cwd: root });
+                if (stdout.trim())
+                    diffs.push(stdout);
+            }
+            catch {
+                // Invalid commit or path — skip
+            }
+        }
+        void reply.header('content-type', 'text/plain').send(diffs.join('\n'));
+    }, deps.logger, 'VcsDiff');
+}
+
+/**
+ * @module api/handlers/vcs/vcsExclude
+ * Fastify route handler for POST /vcs/exclude. Manages .gitignore exclusions
+ * with locality-based placement.
+ */
+/**
+ * Determine the deepest directory for .gitignore placement and the pattern
+ * to add. Splits the glob at the first wildcard character.
+ *
+ * @param relativeGlob - Glob relative to the watch root.
+ * @returns The directory (relative to root) and the pattern for .gitignore.
+ */
+function splitGlobForLocality(relativeGlob) {
+    // Find the first path segment containing a wildcard
+    const segments = relativeGlob.split('/');
+    const dirSegments = [];
+    for (const segment of segments) {
+        if (/[*?[\]{}]/.test(segment))
+            break;
+        dirSegments.push(segment);
+    }
+    // Last non-wildcard segment might be a filename, not a directory.
+    // If no wildcards at all, the directory is the parent of the file.
+    if (dirSegments.length === segments.length) {
+        // No wildcards — the glob is a literal path, directory is parent
+        const dir = dirSegments.slice(0, -1).join('/') || '.';
+        const pattern = dirSegments[dirSegments.length - 1];
+        return { dir, pattern };
+    }
+    const dir = dirSegments.join('/') || '.';
+    const patternSegments = segments.slice(dirSegments.length);
+    const pattern = patternSegments.join('/');
+    return { dir, pattern };
+}
+/**
+ * Create handler for POST /vcs/exclude.
+ */
+function createVcsExcludeHandler(deps) {
+    return wrapHandler(async (request, reply) => {
+        const { glob, root: requestedRoot, remove } = request.body;
+        if (!glob) {
+            void reply
+                .status(400)
+                .send({ error: 'Missing required body parameter: glob' });
+            return;
+        }
+        // Resolve the root
+        let root;
+        if (requestedRoot) {
+            const normalizedRoot = normalizeSlashes(requestedRoot);
+            const manager = deps.coordinator.getManager(normalizedRoot);
+            if (!manager) {
+                void reply
+                    .status(404)
+                    .send({ error: 'Root is not a VCS-enabled watch root' });
+                return;
+            }
+            root = normalizedRoot;
+        }
+        else {
+            // Resolve root from the glob path
+            const normalizedGlob = normalizeSlashes(glob);
+            const basePath = normalizedGlob.replace(/[*?[\]{}].*/g, '');
+            const matchedRoot = findRootForPath(deps.coordinator.getRoots(), basePath);
+            if (!matchedRoot) {
+                void reply
+                    .status(404)
+                    .send({ error: 'Glob does not match any VCS-enabled watch root' });
+                return;
+            }
+            root = matchedRoot;
+        }
+        // Compute relative glob from root
+        const normalizedGlob = normalizeSlashes(glob);
+        let relativeGlob;
+        if (normalizedGlob.startsWith(root + '/')) {
+            relativeGlob = normalizedGlob.slice(root.length + 1);
+        }
+        else {
+            // Glob is the root itself or doesn't start with root — use as-is
+            relativeGlob = normalizedGlob;
+        }
+        // Determine .gitignore directory and pattern using locality principle
+        const { dir, pattern } = splitGlobForLocality(relativeGlob);
+        const gitignoreDir = dir === '.' ? root : normalizeSlashes(join(root, dir));
+        const gitignorePath = normalizeSlashes(join(gitignoreDir, '.gitignore'));
+        if (remove) {
+            // Remove the pattern from .gitignore
+            let content;
+            try {
+                content = await readFile(gitignorePath, 'utf8');
+            }
+            catch {
+                void reply
+                    .status(404)
+                    .send({ error: 'No .gitignore found at the expected location' });
+                return;
+            }
+            const lines = content.split('\n');
+            const filtered = lines.filter((line) => line.trim() !== pattern);
+            if (filtered.length === lines.length) {
+                void reply
+                    .status(404)
+                    .send({ error: 'Pattern not found in .gitignore' });
+                return;
+            }
+            await writeFile(gitignorePath, filtered.join('\n'), 'utf8');
+            return { ok: true, gitignorePath, action: 'removed' };
+        }
+        // Add the pattern to .gitignore
+        await mkdir(gitignoreDir, { recursive: true });
+        let existingContent = '';
+        try {
+            existingContent = await readFile(gitignorePath, 'utf8');
+        }
+        catch {
+            // File doesn't exist yet
+        }
+        // Check if pattern already exists
+        const existingLines = new Set(existingContent.split('\n').map((line) => line.trim()));
+        if (existingLines.has(pattern)) {
+            return { ok: true, gitignorePath, action: 'added' };
+        }
+        if (existingContent.length === 0) {
+            await writeFile(gitignorePath, pattern + '\n', 'utf8');
+        }
+        else {
+            const prefix = existingContent.endsWith('\n') ? '' : '\n';
+            await appendFile(gitignorePath, prefix + pattern + '\n', 'utf8');
+        }
+        return { ok: true, gitignorePath, action: 'added' };
+    }, deps.logger, 'VcsExclude');
+}
+
+/**
+ * @module api/handlers/vcs/vcsHistory
+ * Fastify route handler for GET /vcs/history. Returns commit history for a glob.
+ */
+/** Matches a commit header line: 40-hex-char hash, pipe, message, pipe, ISO timestamp. */
+const HEADER_RE = /^([0-9a-f]{40})\|(.+)\|(\d{4}-\d{2}-\d{2}T.+)$/;
+/**
+ * Parse git log --format='%H|%s|%aI' --name-only output into structured entries.
+ *
+ * Output format per commit:
+ *   hash|subject|ISO-date
+ *   (empty line)
+ *   file1
+ *   file2
+ *   (empty line)
+ */
+function parseGitLog(stdout) {
+    const entries = [];
+    const lines = stdout.split('\n');
+    let current;
+    for (const line of lines) {
+        const trimmed = line.trim();
+        const headerMatch = HEADER_RE.exec(trimmed);
+        if (headerMatch) {
+            // Start of a new commit
+            current = {
+                commit: headerMatch[1],
+                message: headerMatch[2],
+                timestamp: headerMatch[3],
+                files: [],
+            };
+            entries.push(current);
+        }
+        else if (trimmed.length > 0 && current) {
+            current.files.push(trimmed);
+        }
+    }
+    return entries;
+}
+/**
+ * Create handler for GET /vcs/history.
+ */
+function createVcsHistoryHandler(deps) {
+    return wrapHandler(async (request, reply) => {
+        const { glob, since, until, limit: limitStr } = request.query;
+        if (!glob) {
+            void reply
+                .status(400)
+                .send({ error: 'Missing required query parameter: glob' });
+            return;
+        }
+        const limit = limitStr ? parseInt(limitStr, 10) : 20;
+        const resolved = resolveWatchRootsForGlob(deps.coordinator, glob);
+        if (resolved.length === 0) {
+            void reply
+                .status(404)
+                .send({ error: 'No VCS-enabled watch root matches the given glob' });
+            return;
+        }
+        const allEntries = [];
+        for (const { root, relativePath } of resolved) {
+            const args = ['log', '--format=%H|%s|%aI', '--name-only'];
+            if (since)
+                args.push(`--since=${since}`);
+            if (until)
+                args.push(`--until=${until}`);
+            args.push('--', relativePath || '.');
+            try {
+                const { stdout } = await execFileAsync('git', args, { cwd: root });
+                allEntries.push(...parseGitLog(stdout));
+            }
+            catch {
+                // No commits or invalid path — skip
+            }
+        }
+        // Sort by timestamp descending
+        allEntries.sort((a, b) => new Date(b.timestamp).getTime() - new Date(a.timestamp).getTime());
+        return allEntries.slice(0, limit);
+    }, deps.logger, 'VcsHistory');
+}
+
+/**
+ * @module api/handlers/vcs/vcsRevert
+ * Fastify route handler for POST /vcs/revert. Restores files from a past commit.
+ */
+/**
+ * Create handler for POST /vcs/revert.
+ */
+function createVcsRevertHandler(deps) {
+    return wrapHandler(async (request, reply) => {
+        const { glob, commit, existingOnly } = request.body;
+        if (!glob || !commit) {
+            void reply
+                .status(400)
+                .send({ error: 'Missing required body parameters: glob, commit' });
+            return;
+        }
+        const resolved = resolveWatchRootsForGlob(deps.coordinator, glob);
+        if (resolved.length === 0) {
+            void reply
+                .status(404)
+                .send({ error: 'Glob does not match any VCS-enabled watch root' });
+            return;
+        }
+        const allFiles = [];
+        for (const { root, relativePath } of resolved) {
+            const manager = deps.coordinator.getManager(root);
+            if (!manager)
+                continue;
+            // List files matching the glob at the target commit
+            let fileList;
+            try {
+                const args = relativePath === '' || relativePath === '.'
+                    ? ['ls-tree', '-r', '--name-only', commit]
+                    : ['ls-tree', '-r', '--name-only', commit, '--', relativePath];
+                const { stdout } = await execFileAsync('git', args, { cwd: root });
+                fileList = stdout
+                    .trim()
+                    .split('\n')
+                    .filter((line) => line.length > 0);
+            }
+            catch {
+                continue;
+            }
+            const restoredPaths = [];
+            for (const relFile of fileList) {
+                const absPath = normalizeSlashes(join(root, relFile));
+                // If existingOnly, skip files that don't exist on disk
+                if (existingOnly) {
+                    try {
+                        await access(absPath);
+                    }
+                    catch {
+                        continue;
+                    }
+                }
+                // Get file content at the target commit
+                let content;
+                try {
+                    const { stdout } = await execFileAsync('git', ['show', `${commit}:${relFile}`], { cwd: root });
+                    content = stdout;
+                }
+                catch {
+                    continue;
+                }
+                // Ensure parent directory exists
+                const dir = dirname(absPath);
+                await mkdir(dir, { recursive: true });
+                // Write the file
+                await writeFile(absPath, content, 'utf8');
+                restoredPaths.push(absPath);
+                // Notify VcsManager of the change (enters debounce cycle)
+                manager.fileChanged(absPath);
+            }
+            if (restoredPaths.length > 0) {
+                manager.addPendingReversion({
+                    glob,
+                    commit,
+                    paths: restoredPaths,
+                });
+                allFiles.push(...restoredPaths);
+            }
+        }
+        return { restored: allFiles.length, files: allFiles };
+    }, deps.logger, 'VcsRevert');
+}
+
+/**
+ * @module api/handlers/vcs/vcsShow
+ * Fastify route handler for GET /vcs/show. Returns file content at a specific commit.
+ */
+const CONTENT_TYPES = {
+    '.txt': 'text/plain',
+    '.md': 'text/markdown',
+    '.json': 'application/json',
+    '.xml': 'application/xml',
+    '.html': 'text/html',
+    '.css': 'text/css',
+    '.js': 'application/javascript',
+    '.ts': 'text/plain',
+    '.yaml': 'text/yaml',
+    '.yml': 'text/yaml',
+    '.csv': 'text/csv',
+};
+/**
+ * Create handler for GET /vcs/show.
+ */
+function createVcsShowHandler(deps) {
+    return wrapHandler(async (request, reply) => {
+        const { path, commit } = request.query;
+        if (!path || !commit) {
+            void reply
+                .status(400)
+                .send({ error: 'Missing required query parameters: path, commit' });
+            return;
+        }
+        const resolved = resolveWatchRoot(deps.coordinator, path);
+        if (!resolved) {
+            void reply
+                .status(404)
+                .send({ error: 'Path does not match any VCS-enabled watch root' });
+            return;
+        }
+        try {
+            const { stdout } = await execFileAsync('git', ['show', `${commit}:${resolved.relativePath}`], { cwd: resolved.root });
+            const ext = extname(path).toLowerCase();
+            const contentType = CONTENT_TYPES[ext] ?? 'application/octet-stream';
+            void reply.header('content-type', contentType).send(stdout);
+        }
+        catch {
+            void reply
+                .status(404)
+                .send({ error: 'File not found at the specified commit' });
+        }
+    }, deps.logger, 'VcsShow');
+}
+
+/**
+ * @module api/handlers/vcs/vcsStatus
+ * Fastify route handler for GET /vcs/status. Returns VCS state for all roots.
+ */
+async function getLastCommit(cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', ['log', '-1', '--format=%H|%s|%aI'], { cwd });
+        const trimmed = stdout.trim();
+        if (!trimmed)
+            return null;
+        const [hash, message, timestamp] = trimmed.split('|');
+        return { hash, message, timestamp };
+    }
+    catch {
+        return null;
+    }
+}
+async function getTrackedCount(cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', ['rev-list', '--count', 'HEAD'], { cwd });
+        return parseInt(stdout.trim(), 10);
+    }
+    catch {
+        return 0;
+    }
+}
+async function getRemoteUrl(cwd) {
+    try {
+        const { stdout } = await execFileAsync('git', ['remote', 'get-url', 'origin'], { cwd });
+        const url = stdout.trim();
+        return url || null;
+    }
+    catch {
+        return null;
+    }
+}
+/**
+ * Create handler for GET /vcs/status.
+ */
+function createVcsStatusHandler(deps) {
+    return wrapHandler(async () => {
+        const roots = deps.coordinator.getRoots();
+        const enabled = roots.length > 0;
+        const rootStatuses = await Promise.all(roots.map(async (root) => {
+            const manager = deps.coordinator.getManager(root);
+            const [tracked, lastCommit, remoteUrl] = await Promise.all([
+                getTrackedCount(root),
+                getLastCommit(root),
+                getRemoteUrl(root),
+            ]);
+            return {
+                path: root,
+                tracked,
+                lastCommit,
+                remoteUrl: manager?.remoteUrl ?? remoteUrl,
+                lastPush: manager?.lastPushTime ?? null,
+                pushErrors: manager?.pushErrors ?? [],
+            };
+        }));
+        return { enabled, roots: rootStatuses };
+    }, deps.logger, 'VcsStatus');
+}
+
 /**
  * @module api/handlers/walk
  * Fastify route handler for POST /walk. Enumerates watched files matching caller-provided globs
@@ -3681,7 +5208,7 @@ function createApiServer(options) {
         logger,
     }));
     app.post('/walk', createWalkHandler({
-        getWatchPaths: () => getConfig().watch.paths,
+        getWatchPaths: () => extractWatchPathStrings(getConfig().watch.paths),
         getFileSystemWatcher,
         logger,
     }));
@@ -3776,6 +5303,17 @@ function createApiServer(options) {
         app.post('/points/delete', createPointsDeleteHandler({ vectorStore, logger }));
         app.post('/rules/reapply', 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 }));
+    }
     return app;
 }
 
@@ -5787,6 +7325,7 @@ class FileSystemWatcher {
     gitignoreFilter;
     initialScanTracker;
     contentHashCache;
+    onVcsFileChange;
     moveCorrelator;
     globMatches;
     watcher;
@@ -5807,6 +7346,7 @@ class FileSystemWatcher {
         this.gitignoreFilter = options.gitignoreFilter;
         this.initialScanTracker = options.initialScanTracker;
         this.contentHashCache = options.contentHashCache;
+        this.onVcsFileChange = options.onVcsFileChange;
         this.globMatches = () => true;
         const healthOptions = {
             maxRetries: options.maxRetries,
@@ -5824,7 +7364,7 @@ class FileSystemWatcher {
         // Glob patterns are silently treated as literal strings, producing zero
         // events. We extract static directory roots for chokidar to watch, then
         // filter emitted events against the original globs via picomatch.
-        const { roots, matches } = resolveWatchPaths(this.config.paths);
+        const { roots, matches } = resolveWatchPaths(extractWatchPathStrings(this.config.paths));
         this.globMatches = matches;
         this.logger.info({ roots }, 'Resolved watch roots from globs');
         // Chokidar v5's inline anymatch does exact string equality for string
@@ -5905,6 +7445,8 @@ class FileSystemWatcher {
                 this.initialScanTracker?.incrementEnqueued();
             }
             this.logger.debug({ path }, 'File added');
+            if (initialScanComplete)
+                this.onVcsFileChange?.(path, 'add');
             if (correlator && initialScanComplete) {
                 void correlator.handleAdd(path);
             }
@@ -5921,6 +7463,7 @@ class FileSystemWatcher {
             if (this.isGitignored(path))
                 return;
             this.logger.debug({ path }, 'File changed');
+            this.onVcsFileChange?.(path, 'change');
             this.queue.enqueue({ type: 'modify', path, priority: 'normal' }, () => this.wrapProcessing(() => this.processor.processFile(path)));
         });
         this.watcher.on('unlink', (path) => {
@@ -5930,6 +7473,7 @@ class FileSystemWatcher {
             if (this.isGitignored(path))
                 return;
             this.logger.debug({ path }, 'File removed');
+            this.onVcsFileChange?.(path, 'unlink');
             if (correlator) {
                 correlator.handleUnlink(path);
             }
@@ -6081,6 +7625,7 @@ class JeevesWatcher {
     gitignoreFilter;
     enrichmentStore;
     contentHashCache;
+    vcsCoordinator;
     initialScanTracker;
     version;
     /** Create a new JeevesWatcher instance. */
@@ -6103,6 +7648,7 @@ class JeevesWatcher {
     async start() {
         const logger = this.factories.createLogger(this.config.logging);
         this.logger = logger;
+        await initVcs(this.config, logger);
         const { embeddingProvider, vectorStore } = await initEmbeddingAndStore(this.config, this.factories, logger);
         this.embeddingProvider = embeddingProvider;
         this.vectorStore = vectorStore;
@@ -6139,10 +7685,15 @@ class JeevesWatcher {
             concurrency: this.config.embedding.concurrency ?? 5,
             rateLimitPerMinute: this.config.embedding.rateLimitPerMinute,
         });
-        const { watcher, gitignoreFilter } = createWatcher(this.config, this.factories, this.queue, processor, logger, this.runtimeOptions, this.initialScanTracker, contentHashCache);
+        const vcsCoordinator = new VcsCoordinator(this.config, logger);
+        this.vcsCoordinator = vcsCoordinator;
+        const { watcher, gitignoreFilter } = createWatcher(this.config, this.factories, this.queue, processor, logger, this.runtimeOptions, this.initialScanTracker, contentHashCache, (filePath, event) => {
+            vcsCoordinator.onFileChange(filePath, event);
+        });
         this.watcher = watcher;
         this.gitignoreFilter = gitignoreFilter;
         this.server = await this.startApiServer();
+        vcsCoordinator.start();
         this.watcher.start();
         this.startConfigWatch();
         logger.info('jeeves-watcher started');
@@ -6152,6 +7703,9 @@ class JeevesWatcher {
      */
     async stop() {
         await this.stopConfigWatch();
+        if (this.vcsCoordinator) {
+            await this.vcsCoordinator.stop();
+        }
         if (this.watcher) {
             await this.watcher.stop();
         }
@@ -6199,6 +7753,7 @@ class JeevesWatcher {
             fileSystemWatcher: this.watcher,
             getFileSystemWatcher: () => this.watcher,
             enrichmentStore: this.enrichmentStore,
+            vcsCoordinator: this.vcsCoordinator,
         });
         await server.listen({
             host: this.config.api?.host ?? getBindAddress('watcher'),