gitnexus 1.6.11-rc.34 → 1.6.11-rc.36

package/README.md

@@ -249,6 +249,7 @@ gitnexus analyze --verbose       # Log skipped files when parsers are unavailabl
 gitnexus analyze --max-file-size 1024  # Skip files larger than N KB (default: 512, cap: 32768)
 gitnexus analyze --worker-timeout 60  # Increase worker idle timeout for slow parses
 gitnexus analyze --wal-checkpoint-threshold 67108864  # 64 MiB. Control LadybugDB WAL auto-checkpoint threshold (default: 67108864 = 64 MiB; -1 keeps Ladybug stock ~16 MiB)
+gitnexus auto-sync [init|start|restart|stop|status|reset]  # Scheduled remote clone/pull + analyze from GITNEXUS_HOME/watch_config.yml
 gitnexus mcp                     # Start MCP server (stdio) — serves all indexed repos
 gitnexus serve                   # Start local HTTP server (multi-repo) for web UI
 gitnexus index                   # Register an existing .gitnexus/ folder into the global registry
@@ -309,6 +310,28 @@ and `serve` processes periodically check for a newly published index and reopen
 it without a restart. MCP checks are throttled to once every five seconds, so a
 tool call before the next check can briefly use the previous index.
 
+### `gitnexus auto-sync`
+
+`gitnexus auto-sync` is a different product from `gitnexus analyze --watch`. It is the explicit long-running auto-sync entrypoint that clones or pulls configured remotes. `gitnexus watch` is reserved and does not start either job: it prints this split. `GITNEXUS_HOME` defaults to `~/.gitnexus`; `gitnexus auto-sync init` creates its default `$GITNEXUS_HOME/watch_config.yml`. Bare `gitnexus auto-sync` is the same as `gitnexus auto-sync start`; `restart`, `stop`, `status`, and `reset` manage the same `GITNEXUS_HOME` instance. `reset` removes only the derived analysis state and commit snapshot; clones, indexes, and registry entries are untouched. `start` runs in the foreground, reads the configuration once at startup, runs once immediately, then repeats on `sync_interval_minutes`; restart it after changing the configuration. Watch runtime artifacts live under `$GITNEXUS_HOME/watch/`: `project_commit_info.txt` is the human-readable per-loop snapshot, `auto-sync-state.json` is the machine state used for commit skipping and analyze failure thresholds, `watch.mutex` prevents multiple auto-sync processes for one home, `watch.owner.json` records ownership metadata, `watch.pid` plus `watch.status.json` expose process state, `watch.stop.<ownerId>.json` is a temporary owner-fenced stop request, and `quarantine/` stores partial clone output before entries are removed after 14 days, keeping at most the five newest entries per repository regardless of age. Mutexes with verified dead owners are reclaimed automatically after an abnormal exit. Invalid or legacy mutexes fail closed; confirm no auto-sync process is running before manually removing `watch.mutex` and stale `watch.pid` / `watch.owner.json`.
+
+```yaml
+sync_interval_minutes: 10
+max_concurrency: 1
+repo_git_timeout: 10s
+analyze_timeout: 5m
+analyze_failure_threshold: 3
+projects:
+  - local_path: /abs/path/to/repos
+    branches: [master, main]
+    overwrite_local_changes: false
+    remote_urls:
+      - git@github.com:owner/repo.git
+      - git@gitlab.com:group/repo.git
+      - git@gitee.com:owner/repo.git
+```
+
+`sync_interval_minutes` must be an integer of at least `5`. `local_path` must be an absolute path without traversal; each remote is cloned below it as `host/namespace/repo`, preventing same-basename repositories from colliding. `remote_urls` must use SSH SCP form for github.com, gitlab.com, or gitee.com. `repo_git_timeout` applies to each repo clone/pull and defaults to `10s`; a bare number such as `10` is interpreted as seconds, while `10000ms`, `10s`, and `1m` keep their explicit units. It must not exceed one hour or `sync_interval_minutes`, whichever is smaller — so a bare `600000` is rejected, because it means 600000 seconds rather than milliseconds. `analyze_timeout` applies to each isolated analysis worker, defaults to half of `sync_interval_minutes`, and cannot exceed that value; this keeps it within Node's timer range. Timeout and `auto-sync stop` request safe cancellation; a worker already in native work exits after it returns to a JS-visible safe point. While waiting, auto-sync reports `cancelling` or `stopping` and keeps its ownership files so another auto-sync cannot take over. The parent waits up to 5 seconds for the worker to exit; after that it stops waiting, releases its ownership files, and leaves the worker to finish and exit on its own rather than killing it mid-write. `auto-sync stop` uses this same control path on macOS and Windows. `overwrite_local_changes` defaults to `false`; a dirty local clone is skipped with an error log, while `true` allows branch fallback to replace local changes and additionally discards untracked files and directories in the clone after checkout — ignored paths, including GitNexus's own `.gitnexus/` storage, are preserved. `max_concurrency` defaults to `1` and is capped at runtime by `floor(availableMemoryGB / 2)` with a minimum of `1`; the effective value is printed at the start of each loop. Each analysis worker's heap cap is the machine-wide cap divided by the number of repositories analyzed in parallel, so concurrent workers share one memory budget instead of each claiming the whole machine. `analyze_failure_threshold` defaults to `3`, must be at least `2`, and pauses repeated failures only for the same repo branch and commit; a new commit or `gitnexus auto-sync reset` clears the block and allows analysis again. Repositories are registered and added to groups by their full remote identity (`host/namespace/repo`), so repositories with the same basename remain distinct. Use `branches` to try branches in order; legacy `branch` remains supported, but the two fields cannot be set together. If all branches are unavailable or time out, watch logs an error, records the repo status, and skips that repo for the loop. Leave `group_name` empty or omit it to skip group add/sync for that project; otherwise create the group first with `gitnexus group create <name>`. `$GITNEXUS_HOME/watch/project_commit_info.txt` is for inspection only; GitNexus stores machine state separately in `$GITNEXUS_HOME/watch/auto-sync-state.json`.
+
 GraphQL contract matching is opt-in in the group's `group.yaml`:
 
 ```yaml

package/dist/cli/analyze-watch.d.ts

@@ -0,0 +1,20 @@
+import { type AnalyzeOptions as CoreAnalyzeOptions } from '../core/run-analyze.js';
+import type { AnalyzerRunnerIdentity } from '../storage/repo-manager.js';
+import type { AnalyzeOptions } from './analyze-options.js';
+import { type WatchRefreshError } from './watch-queue.js';
+export type WatchCliOptions = AnalyzeOptions;
+export declare function isRelevantWatchPath(filePath: string): boolean;
+export interface WatchEnvironmentBaseline {
+    readonly maxFileSize: string | undefined;
+    readonly workerTimeout: string | undefined;
+    readonly verbose: string | undefined;
+}
+export declare function resolveWatchOptions(repoPath: string, cli: WatchCliOptions, baseline: WatchEnvironmentBaseline, reportIgnoredConfig?: (names: readonly string[]) => void): Promise<CoreAnalyzeOptions>;
+export interface WatchFileLoop {
+    readonly waitForIdle: () => Promise<void>;
+    readonly close: () => Promise<void>;
+}
+export declare function shouldStopAfterWatchRefreshFailure(error: unknown, paths: readonly string[]): boolean;
+/** Start the real filesystem watcher with bounded, serialized refreshes. */
+export declare function startWatchFileLoop(repoPath: string, debounceMs: number, refresh: (paths: readonly string[]) => Promise<void>, onError: WatchRefreshError, onWatcherError?: (error: unknown) => void): Promise<WatchFileLoop>;
+export declare function watchCommandWithRunnerIdentity(runnerIdentityAtBootstrap: AnalyzerRunnerIdentity, inputPath?: string, cliOptions?: WatchCliOptions): Promise<void>;

package/dist/cli/analyze-watch.js

@@ -0,0 +1,375 @@
+/** Local incremental watch (`gitnexus analyze --watch`). Remote auto-sync lives in `auto-sync.ts`. */
+import path from 'node:path';
+import fs from 'node:fs/promises';
+import { watch } from 'chokidar';
+import { createWatchIgnorePredicate } from '../config/ignore-service.js';
+import { analyzeFailureMayHaveMutatedLiveIndex, runFullAnalysis, } from '../core/run-analyze.js';
+import { getGitRoot, hasGitDir } from '../storage/git.js';
+import { GITNEXUS_DIR } from '../storage/repo-meta.js';
+import { loadAnalyzeConfigStrict, mergeAnalyzeOptions, validateBranchName, } from './analyze-config.js';
+import { ensureHeap } from './analyze.js';
+import { cliError, cliInfo, cliWarn } from './cli-message.js';
+import { WATCH_FULL_REFRESH_PATH, WatchRefreshQueue, } from './watch-queue.js';
+const DEFAULT_DEBOUNCE_MS = 300;
+const MAX_TIMER_DELAY_MS = 2_147_483_647;
+const MAX_FILE_SIZE_KB = 32 * 1024;
+const TRANSIENT_WATCH_ERROR_CODES = new Set(['EACCES', 'ENOENT', 'ENOTDIR', 'EPERM']);
+function posixWatchPath(filePath) {
+    return filePath.replace(/\\/g, '/').replace(/^\.\/+/, '');
+}
+export function isRelevantWatchPath(filePath) {
+    const normalized = posixWatchPath(filePath);
+    return (normalized.length > 0 &&
+        normalized !== '.' &&
+        !normalized.startsWith('../') &&
+        !path.posix.isAbsolute(normalized) &&
+        !path.win32.isAbsolute(filePath));
+}
+function isIgnoreControlPath(filePath) {
+    const normalized = posixWatchPath(filePath);
+    return normalized === '.gitignore' || normalized === '.gitnexusignore';
+}
+function isConfigControlPath(filePath) {
+    return posixWatchPath(filePath) === '.gitnexusrc';
+}
+function isAnalyzerOwnedWatchPath(filePath) {
+    const normalized = posixWatchPath(filePath).replace(/\/+$/, '');
+    return normalized === GITNEXUS_DIR || normalized.startsWith(`${GITNEXUS_DIR}/`);
+}
+function repoRelativeWatchPath(repoPath, candidate) {
+    const relative = path.relative(repoPath, candidate).replace(/\\/g, '/');
+    if (!relative || relative.startsWith('../') || path.isAbsolute(relative))
+        return null;
+    return relative;
+}
+function setEnvironment(name, value) {
+    if (value === undefined)
+        delete process.env[name];
+    else
+        process.env[name] = value;
+}
+function positiveInteger(value, flag, maximum) {
+    if (value === undefined)
+        return undefined;
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1)
+        throw new Error(`${flag} must be a positive integer`);
+    if (maximum !== undefined && parsed > maximum) {
+        throw new Error(`${flag} must not exceed ${maximum}`);
+    }
+    return parsed;
+}
+export async function resolveWatchOptions(repoPath, cli, baseline, reportIgnoredConfig = () => { }) {
+    const config = (await loadAnalyzeConfigStrict(repoPath)) ?? {};
+    const merged = mergeAnalyzeOptions(cli, config);
+    const unsupported = [
+        ['--force', cli.force],
+        ['--repair-fts', cli.repairFts],
+        ['--embeddings', cli.embeddings],
+        ['--drop-embeddings', cli.dropEmbeddings],
+        ['--skills', cli.skills],
+        ['--default-branch', cli.defaultBranch],
+        ['--skip-agents-md', cli.skipAgentsMd],
+        ['--skip-skills', cli.skipSkills],
+        ['--no-stats', cli.stats === false],
+        ['--self-commit', cli.selfCommit],
+        ['--index-only', cli.indexOnly],
+        ['--skip-git', cli.skipGit],
+        ['--spring-actuator', cli.springActuator],
+        ['walCheckpointThreshold', cli.walCheckpointThreshold],
+        ['embeddingThreads', cli.embeddingThreads],
+        ['embeddingBatchSize', cli.embeddingBatchSize],
+        ['embeddingSubBatchSize', cli.embeddingSubBatchSize],
+        ['embeddingDevice', cli.embeddingDevice],
+        ['embeddingBaseUrl', cli.embeddingBaseUrl],
+        ['embeddingModel', cli.embeddingModel],
+        ['--embedding-auth-token', cli.embeddingAuthToken],
+        ['--embedding-dims', cli.embeddingDims],
+    ].filter(([, value]) => value !== undefined && value !== false);
+    if (unsupported.length > 0) {
+        throw new Error(`analyze --watch does not support ${unsupported.map(([name]) => name).join(', ')}`);
+    }
+    reportIgnoredConfig([
+        ['embeddings', config.embeddings],
+        ['dropEmbeddings', config.dropEmbeddings],
+        ['defaultBranch', config.defaultBranch],
+        ['skipAgentsMd', config.skipAgentsMd !== undefined],
+        ['skipSkills', config.skipSkills !== undefined],
+        ['stats', config.stats !== undefined],
+        ['springActuator', config.springActuator],
+        ['walCheckpointThreshold', config.walCheckpointThreshold],
+        ['embeddingThreads', config.embeddingThreads],
+        ['embeddingBatchSize', config.embeddingBatchSize],
+        ['embeddingSubBatchSize', config.embeddingSubBatchSize],
+        ['embeddingDevice', config.embeddingDevice],
+        ['embeddingBaseUrl', config.embeddingBaseUrl],
+        ['embeddingModel', config.embeddingModel],
+    ]
+        .filter(([, value]) => value !== undefined && value !== false)
+        .map(([name]) => String(name)));
+    const branch = merged.branch === undefined ? undefined : validateBranchName(merged.branch, '--branch');
+    const workerPoolSize = positiveInteger(merged.workers, '--workers');
+    const workerTimeoutSeconds = positiveInteger(merged.workerTimeout, 'workerTimeout');
+    const maxFileSize = positiveInteger(merged.maxFileSize, 'maxFileSize', MAX_FILE_SIZE_KB);
+    setEnvironment('GITNEXUS_MAX_FILE_SIZE', maxFileSize === undefined ? baseline.maxFileSize : String(maxFileSize));
+    if (workerTimeoutSeconds !== undefined) {
+        process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS = String(workerTimeoutSeconds * 1000);
+    }
+    else {
+        setEnvironment('GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS', baseline.workerTimeout);
+    }
+    setEnvironment('GITNEXUS_VERBOSE', merged.verbose ? '1' : baseline.verbose);
+    return {
+        pdg: merged.pdg,
+        branch,
+        registryName: merged.name,
+        allowDuplicateName: merged.allowDuplicateName,
+        workerPoolSize,
+        fetchWrappers: merged.fetchWrappers,
+        skipAgentsMd: true,
+        skipSkills: true,
+        noStats: true,
+        atomicIncremental: process.platform !== 'win32',
+    };
+}
+function refreshSummary(result, observedPaths, durationMs, lastSuccessfulRefreshAt) {
+    const measured = result.incrementalStats;
+    const changed = measured?.changedFiles ?? (result.alreadyUpToDate ? 0 : observedPaths.length);
+    const reparsed = measured?.reparsedFiles ??
+        (typeof result.pipelineResult?.reparsedFileCount === 'number'
+            ? result.pipelineResult.reparsedFileCount
+            : 0);
+    const dependents = measured?.affectedDependents ?? 0;
+    const mode = measured?.writeMode ?? (result.alreadyUpToDate ? 'no-op' : 'full');
+    return (`Refresh complete: ${changed} changed, ${reparsed} re-parsed, ` +
+        `${dependents} affected dependent(s), ${durationMs}ms, ${mode}; ` +
+        `last success ${lastSuccessfulRefreshAt}`);
+}
+async function waitUntilReady(watcher) {
+    await new Promise((resolve, reject) => {
+        const ready = () => {
+            watcher.off('error', failed);
+            resolve();
+        };
+        const failed = (error) => {
+            watcher.off('ready', ready);
+            reject(error);
+        };
+        watcher.once('ready', ready);
+        watcher.once('error', failed);
+    });
+}
+class WatchControlReloadError extends Error {
+    constructor(cause) {
+        super(cause instanceof Error ? cause.message : String(cause), { cause });
+        this.name = 'WatchControlReloadError';
+    }
+}
+export function shouldStopAfterWatchRefreshFailure(error, paths) {
+    return (paths.length > 0 &&
+        !(error instanceof WatchControlReloadError) &&
+        analyzeFailureMayHaveMutatedLiveIndex(error));
+}
+/** Start the real filesystem watcher with bounded, serialized refreshes. */
+export async function startWatchFileLoop(repoPath, debounceMs, refresh, onError, onWatcherError = (error) => onError(error, [])) {
+    let ignorePath = await createWatchIgnorePredicate(repoPath);
+    let ignoreControlValid = true;
+    const queue = new WatchRefreshQueue(async (paths) => {
+        if (paths.some(isIgnoreControlPath) || !ignoreControlValid) {
+            const retryingInvalidControls = !ignoreControlValid;
+            try {
+                ignorePath = await createWatchIgnorePredicate(repoPath);
+                ignoreControlValid = true;
+                watcher.add(repoPath);
+            }
+            catch (error) {
+                ignoreControlValid = false;
+                throw new WatchControlReloadError(retryingInvalidControls
+                    ? new Error('Ignore controls remain invalid; fix them before indexing more changes.', {
+                        cause: error,
+                    })
+                    : error);
+            }
+        }
+        await refresh(paths);
+    }, onError, debounceMs, {
+        maxWaitMs: Math.max(2_000, debounceMs * 10),
+        maxPendingPaths: 1_000,
+        holdEventsUntilInitialRefresh: true,
+        isPriorityPath: (filePath) => isIgnoreControlPath(filePath) || isConfigControlPath(filePath),
+    });
+    const watcher = watch(repoPath, {
+        ignoreInitial: true,
+        atomic: true,
+        followSymlinks: false,
+        awaitWriteFinish: { stabilityThreshold: 100, pollInterval: 20 },
+        ignored: (candidate, stats) => {
+            const relative = repoRelativeWatchPath(repoPath, candidate);
+            if (relative !== null && isAnalyzerOwnedWatchPath(relative))
+                return true;
+            if (relative !== null && (isIgnoreControlPath(relative) || isConfigControlPath(relative))) {
+                return false;
+            }
+            return ignorePath(candidate, stats?.isDirectory() ?? false);
+        },
+    });
+    watcher.on('all', (event, changedPath) => {
+        if (event !== 'add' && event !== 'change' && event !== 'unlink')
+            return;
+        const relative = repoRelativeWatchPath(repoPath, changedPath);
+        if (relative && isRelevantWatchPath(relative) && !isAnalyzerOwnedWatchPath(relative)) {
+            queue.enqueue(relative);
+        }
+    });
+    watcher.on('error', (error) => {
+        // Chokidar can surface a transient EPERM on Windows while an ignored
+        // analyzer-owned path is replaced. Re-arm the root and force one bounded
+        // catch-up refresh so a missed event cannot leave the graph stale. Other
+        // watcher errors may mean coverage was lost and remain fatal.
+        if (TRANSIENT_WATCH_ERROR_CODES.has(error.code ?? '')) {
+            watcher.add(repoPath);
+            queue.enqueue(WATCH_FULL_REFRESH_PATH);
+            return;
+        }
+        onWatcherError(error);
+    });
+    try {
+        await waitUntilReady(watcher);
+        await queue.runInitial();
+    }
+    catch (error) {
+        await watcher.close();
+        await queue.close();
+        throw error;
+    }
+    return {
+        waitForIdle: () => queue.waitForIdle(),
+        close: async () => {
+            await watcher.close();
+            await queue.close();
+        },
+    };
+}
+export async function watchCommandWithRunnerIdentity(runnerIdentityAtBootstrap, inputPath, cliOptions = {}) {
+    if (await ensureHeap({ cleanForwardedTermination: true }))
+        return;
+    const requestedRepoPath = inputPath ? path.resolve(inputPath) : getGitRoot(process.cwd());
+    if (requestedRepoPath === null || !hasGitDir(requestedRepoPath)) {
+        cliError('  gitnexus analyze --watch requires a Git repository.');
+        process.exitCode = 1;
+        return;
+    }
+    const repoPath = await fs.realpath(requestedRepoPath);
+    const baselineEnvironment = {
+        maxFileSize: process.env.GITNEXUS_MAX_FILE_SIZE,
+        workerTimeout: process.env.GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS,
+        verbose: process.env.GITNEXUS_VERBOSE,
+    };
+    try {
+        let ignoredConfigSignature;
+        const reportIgnoredConfig = (names) => {
+            const signature = [...names].sort().join(',');
+            if (signature === ignoredConfigSignature)
+                return;
+            ignoredConfigSignature = signature;
+            if (names.length > 0) {
+                cliWarn(`Watch mode ignores unsupported .gitnexusrc settings: ${names.join(', ')}.`);
+            }
+        };
+        let debounceMs;
+        let analyzeOptions;
+        try {
+            debounceMs =
+                positiveInteger(cliOptions.debounce ?? String(DEFAULT_DEBOUNCE_MS), '--debounce', MAX_TIMER_DELAY_MS) ?? DEFAULT_DEBOUNCE_MS;
+            analyzeOptions = await resolveWatchOptions(repoPath, cliOptions, baselineEnvironment, reportIgnoredConfig);
+        }
+        catch (error) {
+            cliError(`  ${error instanceof Error ? error.message : String(error)}`);
+            process.exitCode = 1;
+            return;
+        }
+        let stopWatching;
+        const stopped = new Promise((resolve) => {
+            stopWatching = resolve;
+        });
+        const stop = () => stopWatching();
+        process.once('SIGINT', stop);
+        process.once('SIGTERM', stop);
+        try {
+            let loop;
+            let fatalRefreshError;
+            let configControlValid = true;
+            let lastSuccessfulRefreshAt;
+            try {
+                loop = await startWatchFileLoop(repoPath, debounceMs, async (paths) => {
+                    if (paths.some(isConfigControlPath) || !configControlValid) {
+                        const retryingInvalidConfig = !configControlValid;
+                        try {
+                            analyzeOptions = await resolveWatchOptions(repoPath, cliOptions, baselineEnvironment, reportIgnoredConfig);
+                            configControlValid = true;
+                        }
+                        catch (error) {
+                            configControlValid = false;
+                            throw new WatchControlReloadError(retryingInvalidConfig
+                                ? new Error('Configuration remains invalid; fix it before indexing more changes.', {
+                                    cause: error,
+                                })
+                                : error);
+                        }
+                    }
+                    const startedAt = Date.now();
+                    const result = await runFullAnalysis(repoPath, analyzeOptions, {
+                        onProgress: () => { },
+                        onLog: process.env.GITNEXUS_VERBOSE === '1'
+                            ? (message) => cliInfo(`  ${message}`)
+                            : undefined,
+                    }, runnerIdentityAtBootstrap);
+                    lastSuccessfulRefreshAt = new Date().toISOString();
+                    if (paths.length === 0) {
+                        cliInfo(result.alreadyUpToDate
+                            ? `Watching ${repoPath}; index is up to date.`
+                            : `Watching ${repoPath}; initial index ready in ${Date.now() - startedAt}ms.`);
+                    }
+                    else {
+                        cliInfo(refreshSummary(result, paths, Date.now() - startedAt, lastSuccessfulRefreshAt));
+                    }
+                }, (error, paths) => {
+                    const detail = paths.length > 0 ? ` (${paths.length} queued path(s))` : '';
+                    if (shouldStopAfterWatchRefreshFailure(error, paths)) {
+                        fatalRefreshError = error;
+                        cliError(`Refresh failed${detail}: ${error instanceof Error ? error.message : String(error)}. ` +
+                            'Watch mode is stopping because the live index may have been updated in place.');
+                        stopWatching();
+                        return;
+                    }
+                    const lastSuccess = lastSuccessfulRefreshAt ?? 'none yet';
+                    cliWarn(`Refresh failed${detail}: ${error instanceof Error ? error.message : String(error)}. ` +
+                        `Retry scheduled; last success ${lastSuccess}.`);
+                }, (error) => {
+                    fatalRefreshError = error;
+                    cliError(`Watcher failed: ${error instanceof Error ? error.message : String(error)}. ` +
+                        'Watch mode is stopping.');
+                    stopWatching();
+                });
+            }
+            catch (error) {
+                cliError(`  Unable to start watcher: ${error instanceof Error ? error.message : String(error)}`);
+                process.exitCode = 1;
+                return;
+            }
+            await stopped;
+            await loop.close();
+            if (fatalRefreshError !== undefined)
+                process.exitCode = 1;
+        }
+        finally {
+            process.removeListener('SIGINT', stop);
+            process.removeListener('SIGTERM', stop);
+        }
+    }
+    finally {
+        setEnvironment('GITNEXUS_MAX_FILE_SIZE', baselineEnvironment.maxFileSize);
+        setEnvironment('GITNEXUS_WORKER_SUB_BATCH_TIMEOUT_MS', baselineEnvironment.workerTimeout);
+        setEnvironment('GITNEXUS_VERBOSE', baselineEnvironment.verbose);
+    }
+}

package/dist/cli/analyze.js

@@ -602,7 +602,7 @@ export const analyzeCommand = async (inputPath, options, runnerIdentityAtBootstr
 export const analyzeCommandWithRunnerIdentity = async (runnerIdentityAtBootstrap, inputPath, options) => analyzeCommand(inputPath, options, runnerIdentityAtBootstrap);
 export async function analyzeOrWatchCommandWithRunnerIdentity(runnerIdentityAtBootstrap, inputPath, options = {}) {
     if (options.watch) {
-        const { watchCommandWithRunnerIdentity } = await import('./watch.js');
+        const { watchCommandWithRunnerIdentity } = await import('./analyze-watch.js');
         await watchCommandWithRunnerIdentity(runnerIdentityAtBootstrap, inputPath, options);
         return;
     }

package/dist/cli/auto-sync.d.ts

@@ -0,0 +1 @@
+export declare function autoSyncCommand(action?: string): Promise<void>;

package/dist/cli/auto-sync.js

@@ -0,0 +1,107 @@
+/** Remote auto-sync CLI (`gitnexus auto-sync`). Local incremental watch lives in `analyze-watch.ts`. */
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import { getAutoSyncConfigPath, getAutoSyncMutexPath, readAutoSyncWatchStatus, resetAutoSyncState, startAutoSyncWatch, stopAutoSyncWatch, } from '../core/auto-sync/index.js';
+export async function autoSyncCommand(action = 'start') {
+    if (action === 'init') {
+        await initWatchConfig();
+        return;
+    }
+    if (action === 'reset') {
+        if (!(await resetAutoSyncState())) {
+            process.stderr.write(`[auto-sync] Cannot reset analysis state while the watch mutex is held. Confirm no watch process is running, then remove ${getAutoSyncMutexPath()}.\n`);
+            process.exitCode = 1;
+            return;
+        }
+        process.stdout.write('[auto-sync] Reset analysis state.\n');
+        return;
+    }
+    if (action === 'status') {
+        printStatus(await readAutoSyncWatchStatus());
+        return;
+    }
+    if (action === 'stop') {
+        if ((await stopAutoSyncWatch()) !== 'stopped')
+            process.exitCode = 1;
+        return;
+    }
+    if (action === 'restart') {
+        const result = await stopAutoSyncWatch();
+        if (result === 'refused' || result === 'timeout') {
+            process.exitCode = 1;
+            return;
+        }
+        await startWatchProcess();
+        return;
+    }
+    if (action !== 'start') {
+        process.stderr.write(`[auto-sync] Unknown auto-sync action: ${action}\n`);
+        process.exitCode = 1;
+        return;
+    }
+    await startWatchProcess();
+}
+async function startWatchProcess() {
+    const handle = await startAutoSyncWatch();
+    if (!handle) {
+        process.exitCode = 1;
+        return;
+    }
+    const stop = () => {
+        void handle.stop().then(() => {
+            process.stderr.write('[auto-sync] Watch stopped.\n');
+            process.exit(0);
+        }, (error) => {
+            const message = error instanceof Error ? error.message : String(error);
+            process.stderr.write(`[auto-sync] Failed to stop watch: ${message}\n`);
+            process.exit(1);
+        });
+    };
+    process.once('SIGINT', stop);
+    process.once('SIGTERM', stop);
+}
+function printStatus(status) {
+    const parts = [`state=${status.state}`];
+    if (status.pid)
+        parts.push(`pid=${status.pid}`);
+    if (status.configPath)
+        parts.push(`config=${status.configPath}`);
+    if (status.message)
+        parts.push(`message=${status.message}`);
+    parts.push(`updated_at=${status.updatedAt}`);
+    process.stdout.write(`${parts.join(' ')}\n`);
+}
+async function initWatchConfig() {
+    const configPath = getAutoSyncConfigPath();
+    try {
+        await fs.mkdir(path.dirname(configPath), { recursive: true });
+        await fs.writeFile(configPath, defaultSyncConfig(path.resolve(path.dirname(configPath), 'repos')), {
+            flag: 'wx',
+        });
+    }
+    catch (err) {
+        if (err.code === 'EEXIST') {
+            process.stderr.write(`[auto-sync] Config already exists: ${configPath}\n`);
+            process.exitCode = 1;
+            return;
+        }
+        throw err;
+    }
+    process.stdout.write(`[auto-sync] Created ${configPath}\n`);
+}
+function defaultSyncConfig(localPath) {
+    return [
+        'sync_interval_minutes: 10',
+        'max_concurrency: 1',
+        'repo_git_timeout: 10s',
+        'analyze_timeout: 5m',
+        'analyze_failure_threshold: 3',
+        'projects:',
+        `  - local_path: ${localPath}`,
+        '    branches: [master, main]',
+        '    overwrite_local_changes: false',
+        '    remote_urls:',
+        '      - git@github.com:owner/repo.git',
+        '',
+    ].join('\n');
+}

package/dist/cli/detect-changes-format.js

@@ -20,6 +20,27 @@ export function formatDetectChangesResult(result) {
     if (payload.truncated)
         notes.push(t(payload.partial ? 'tool.detectChanges.truncatedDegraded' : 'tool.detectChanges.truncated'));
     if ((summary.changed_count ?? 0) === 0) {
+        // Parse-fail payloads set `partial` and an honest `message` (#2915/#3131).
+        // Production *clean* trees also set English `message: 'No changes detected.'`
+        // — that must go through `t('tool.detectChanges.noChanges')` or zh-CN never
+        // fires. Only pass the backend string through on a degraded/parse-fail run.
+        if (payload.partial &&
+            typeof summary.message === 'string' &&
+            summary.message.trim().length > 0) {
+            return [...notes, summary.message.trim()].join('\n');
+        }
+        // Confirmed no-overlap: files parsed, mapping succeeded, zero symbols.
+        // `queryDegraded` is `partial: true` with the same counts and no message —
+        // do not call that a confirmed mapping (#3131 honesty).
+        if (!payload.partial && (summary.changed_files ?? 0) > 0) {
+            return [
+                ...notes,
+                t('tool.detectChanges.noOverlappingSymbols', { files: summary.changed_files }),
+            ].join('\n');
+        }
+        if (payload.partial) {
+            return notes.join('\n');
+        }
         return [...notes, t('tool.detectChanges.noChanges')].join('\n');
     }
     const lines = [];

package/dist/cli/help-i18n.js

@@ -10,6 +10,8 @@ const COMMAND_DESCRIPTION_KEYS = {
     '': 'help.description.root',
     setup: 'help.command.setup.description',
     uninstall: 'help.command.uninstall.description',
+    watch: 'help.command.watch.description',
+    'auto-sync': 'help.command.autoSync.description',
     analyze: 'help.command.analyze.description',
     index: 'help.command.index.description',
     serve: 'help.command.serve.description',

package/dist/cli/i18n/en.d.ts

@@ -66,6 +66,7 @@ export declare const en: {
     readonly 'tool.usage.cypher': "Usage: gitnexus cypher <cypher_query>";
     readonly 'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.";
     readonly 'tool.detectChanges.noChanges': "No changes detected.";
+    readonly 'tool.detectChanges.noOverlappingSymbols': "Diff touched {{files}} file(s) but no indexed symbols overlap those hunks — not a clean tree.";
     readonly 'tool.detectChanges.partial': "PARTIAL RESULT: a graph query failed, so changed symbols may be missing. Do not read this as a clean pre-commit check.";
     readonly 'tool.detectChanges.truncated': "LISTING CAPPED: the changed-symbol list was capped, so it does not name every changed symbol. The counts and risk level still cover all of them.";
     readonly 'tool.detectChanges.truncatedDegraded': "LISTING CAPPED: the changed-symbol list was capped. The run also degraded, so the counts are a lower bound, not a total.";
@@ -124,6 +125,11 @@ export declare const en: {
     readonly 'help.option.version': "output the version number";
     readonly 'help.command.setup.description': "One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex";
     readonly 'help.command.uninstall.description': "Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors";
+    readonly 'help.command.autoSync.description': "Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml";
+    readonly 'help.autoSync.details': "\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.";
+    readonly 'help.command.watch.description': "Ambiguous: use `analyze --watch` for local files, or `auto-sync` for scheduled remotes";
+    readonly 'help.watch.details': "\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
+    readonly 'error.watch.ambiguous': "`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n";
     readonly 'help.command.analyze.description': "Index a repository (full analysis)";
     readonly 'help.command.index.description': "Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)";
     readonly 'help.command.serve.description': "Start local HTTP server for web UI connection";

package/dist/cli/i18n/en.js

@@ -66,6 +66,7 @@ export const en = {
     'tool.usage.cypher': 'Usage: gitnexus cypher <cypher_query>',
     'tool.warn.unknownKind': "--kind '{{kind}}' is not a known symbol kind (e.g. Function, Class, Method); it will not narrow the result.",
     'tool.detectChanges.noChanges': 'No changes detected.',
+    'tool.detectChanges.noOverlappingSymbols': 'Diff touched {{files}} file(s) but no indexed symbols overlap those hunks — not a clean tree.',
     'tool.detectChanges.partial': 'PARTIAL RESULT: a graph query failed, so changed symbols may be missing. Do not read this as a clean pre-commit check.',
     'tool.detectChanges.truncated': 'LISTING CAPPED: the changed-symbol list was capped, so it does not name every changed symbol. The counts and risk level still cover all of them.',
     // The reassurance above is only true on its own. When the run also degraded,
@@ -126,6 +127,11 @@ export const en = {
     'help.option.version': 'output the version number',
     'help.command.setup.description': 'One-time setup: configure MCP for Cursor, Claude Code, Antigravity, OpenCode, CodeBuddy, Qoder, Codex',
     'help.command.uninstall.description': 'Reverse `setup`: remove GitNexus MCP entries, skills, and hooks from all detected editors',
+    'help.command.autoSync.description': 'Control scheduled repository clone/pull and analysis from GITNEXUS_HOME/watch_config.yml',
+    'help.autoSync.details': '\nActions: init, start (default), restart, stop, status, reset\nConfiguration: GITNEXUS_HOME/watch_config.yml\nRuntime files: GITNEXUS_HOME/watch/watch.pid, watch.mutex, watch.owner.json, watch.status.json, auto-sync-state.json\nRecovery: mutexes with verified dead owners are reclaimed automatically; invalid or legacy mutexes fail closed and require manual removal after confirming no watch process is running.\nWrites: GITNEXUS_HOME/watch/project_commit_info.txt\nRemote URLs: only SSH URLs on github.com, gitlab.com, and gitee.com are allowed.\nRuns once immediately, then repeats on sync_interval_minutes.',
+    'help.command.watch.description': 'Ambiguous: use `analyze --watch` for local files, or `auto-sync` for scheduled remotes',
+    'help.watch.details': '\n`gitnexus watch` does not start a watcher.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n',
+    'error.watch.ambiguous': '`gitnexus watch` is ambiguous.\n  Local working-tree incremental index:  gitnexus analyze --watch\n  Scheduled remote clone/pull + analyze: gitnexus auto-sync start\n',
     'help.command.analyze.description': 'Index a repository (full analysis)',
     'help.command.index.description': 'Register an existing .gitnexus/ folder into the global registry (no re-analysis needed)',
     'help.command.serve.description': 'Start local HTTP server for web UI connection',