gitnexus 1.6.11-rc.8 → 1.6.11

package/dist/core/search/fts-indexes.d.ts

@@ -59,6 +59,12 @@ export declare const SUPPORTED_FTS_STEMMERS: ReadonlySet<string>;
 export interface CreateSearchFTSIndexesOptions {
     onIndexStart?: (table: string, indexName: string) => void;
     onIndexReady?: (table: string, indexName: string) => void;
+    /**
+     * When set, only these node-table names are dropped/rebuilt (#3016).
+     * Omit to rebuild every configured FTS index (full analyze / deleted-file
+     * incremental / `--repair-fts`).
+     */
+    tables?: ReadonlySet<string>;
 }
 /**
  * Resolve + validate `GITNEXUS_FTS_STEMMER` once, up front at analyze startup,
@@ -98,7 +104,19 @@ export declare function getSearchFTSStemmer(): string;
  * contract, and the same one-shared-`SHOW_INDEXES`-read purpose, as the gates in
  * `lbug-adapter.ts`. Omit it to have the sweep read the catalog itself.
  */
-export declare function dropSearchFTSIndexes(indexRows?: IndexCatalogSnapshot): Promise<void>;
+export declare function dropSearchFTSIndexes(indexRows?: IndexCatalogSnapshot, tables?: ReadonlySet<string>): Promise<void>;
+/**
+ * The configured FTS tables whose index the catalog proves is ABSENT right now.
+ *
+ * `undefined` means the catalog could not be read, which proves nothing — the
+ * same fail-closed reading the sweep above applies. Callers narrowing a rebuild
+ * to a subset of tables (#3016) must union this in, or must not narrow at all
+ * when it is `undefined`: a run that rebuilds only the tables it wrote leaves
+ * keyword search permanently degraded on every table whose index went missing
+ * earlier (a prior escalation drops all of them, and only the next full rebuild
+ * would ever put them back).
+ */
+export declare function missingSearchFTSIndexTables(indexRows?: IndexCatalogSnapshot): Promise<Set<string> | undefined>;
 /** One configured index that could not be (re)built, and why. */
 export interface FtsIndexBuildFailure {
     table: string;

package/dist/core/search/fts-indexes.js

@@ -172,7 +172,7 @@ export function getSearchFTSStemmer() {
  * contract, and the same one-shared-`SHOW_INDEXES`-read purpose, as the gates in
  * `lbug-adapter.ts`. Omit it to have the sweep read the catalog itself.
  */
-export async function dropSearchFTSIndexes(indexRows) {
+export async function dropSearchFTSIndexes(indexRows, tables) {
     // One catalog read for the whole sweep, decided PER CONFIGURED INDEX on
     // IDENTITY (#2841 cleanup review). `undefined` = the catalog could not be
     // read, which proves nothing — attempt every drop rather than skip a real one,
@@ -193,6 +193,8 @@ export async function dropSearchFTSIndexes(indexRows) {
     // whether the sweep ran or not.
     const rows = await resolveGateRows(indexRows);
     for (const { table, indexName } of FTS_INDEXES) {
+        if (tables && !tables.has(table))
+            continue;
         // Skip only what the catalog POSITIVELY proves absent. Without this, a
         // machine whose FTS extension cannot load, analyzing a DB that never carried
         // an FTS index, pays one failed `CALL DROP_FTS_INDEX` per configured table on
@@ -209,6 +211,29 @@ export async function dropSearchFTSIndexes(indexRows) {
         await dropFTSIndex(table, indexName);
     }
 }
+/**
+ * The configured FTS tables whose index the catalog proves is ABSENT right now.
+ *
+ * `undefined` means the catalog could not be read, which proves nothing — the
+ * same fail-closed reading the sweep above applies. Callers narrowing a rebuild
+ * to a subset of tables (#3016) must union this in, or must not narrow at all
+ * when it is `undefined`: a run that rebuilds only the tables it wrote leaves
+ * keyword search permanently degraded on every table whose index went missing
+ * earlier (a prior escalation drops all of them, and only the next full rebuild
+ * would ever put them back).
+ */
+export async function missingSearchFTSIndexTables(indexRows) {
+    const rows = await resolveGateRows(indexRows);
+    if (rows === undefined)
+        return undefined;
+    const missing = new Set();
+    for (const { table, indexName } of FTS_INDEXES) {
+        const present = rows.some((row) => indexRowTable(row) === table && indexRowName(row) === indexName);
+        if (!present)
+            missing.add(table);
+    }
+    return missing;
+}
 /**
  * Build every configured FTS index, and keep going when one of them fails
  * (#2889).
@@ -232,6 +257,8 @@ export async function createSearchFTSIndexes(options) {
     const stemmer = getSearchFTSStemmer();
     const failures = [];
     for (const { table, indexName, properties } of FTS_INDEXES) {
+        if (options?.tables && !options.tables.has(table))
+            continue;
         options?.onIndexStart?.(table, indexName);
         // Drop first so the live `properties` always win. `createFTSIndex` is
         // idempotent-by-name (skips when the index already exists), so without the

package/dist/core/tree-sitter/parser-loader.js

@@ -112,6 +112,22 @@ const SOURCES = {
             'Likely cause: no prebuilt `.node` for this platform/architecture. ' +
             `See ${ISSUES_URL}/2107.`,
     },
+    // Zig grammar declares peerOptional `tree-sitter@^0.22.1` but its native
+    // binding is ABI-compatible with the bundled `tree-sitter@0.21.x` runtime
+    // (verified by load-time smoke test). The peer-dep mismatch is suppressed
+    // via the `overrides` block in package.json. Listed as `optional: true`
+    // because the package is in `optionalDependencies` — users on platforms
+    // without a prebuild may not have it — and `userSkippable` because it is
+    // a genuinely-optional grammar: `GITNEXUS_SKIP_OPTIONAL_GRAMMARS` must be
+    // able to disable it at analyze time like swift/dart/kotlin.
+    [SupportedLanguages.Zig]: {
+        load: () => _require('@tree-sitter-grammars/tree-sitter-zig'),
+        optional: true,
+        userSkippable: true,
+        unavailableNote: 'Zig parsing disabled: `@tree-sitter-grammars/tree-sitter-zig` is an ' +
+            'optionalDependency and is not installed (or its native binding failed ' +
+            'to load on this platform).',
+    },
 };
 export const listGrammarSources = () => Object.entries(SOURCES).map(([key, source]) => ({
     key,

package/dist/core/update-cache.d.ts

@@ -0,0 +1,39 @@
+export declare const UPDATE_CACHE_TTL_MS: number;
+export declare const STRICT_UPDATE_VERSION: RegExp;
+export declare const DEFAULT_UPDATE_REGISTRY = "https://registry.npmjs.org";
+export interface UpdateCacheEntry {
+    lastCheckAt: string;
+    registry: string;
+    latestVersion?: string;
+}
+export interface ValidatedUpdateCache {
+    lastCheckAt: number;
+    latestVersion?: string;
+    stale: boolean;
+}
+/** Broad truthy parsing shared by the update-notifier guards. */
+export declare function isTruthyEnv(value: string | undefined): boolean;
+/** The update notifier is disabled by either opt-out env or a CI environment. */
+export declare function updateNotifierOptedOut(env: NodeJS.ProcessEnv): boolean;
+/** Freshness gate for the 24h TTL; future-dated timestamps are stale. */
+export declare function isUpdateCacheFresh(lastCheckAt: string, now: number): boolean;
+/** Strict x.y.z numeric comparison. Invalid or prerelease versions are silent. */
+export declare function isNewerVersion(installedVersion: string, latestVersion: string): boolean;
+export declare function normalizedUpdateRegistry(env?: NodeJS.ProcessEnv): {
+    identity: string;
+    packageUrl: string;
+};
+export declare function updateCheckCachePath(env?: NodeJS.ProcessEnv): string;
+export declare function updateCheckLockPath(env?: NodeJS.ProcessEnv): string;
+/**
+ * Best-effort synchronous probe: is a refresh plausibly in flight? Used to
+ * coalesce detached refresh spawns. A dead same-host owner returns false so
+ * the spawned child can reclaim the stale lock; a foreign-host owner returns
+ * false and lets the child's full lock logic decide.
+ */
+export declare function updateRefreshInProgress(env?: NodeJS.ProcessEnv): boolean;
+export declare function parseUpdateCache(raw: string, registry: string): UpdateCacheEntry | null;
+export declare function readValidatedUpdateCacheSync(options?: {
+    env?: NodeJS.ProcessEnv;
+    now?: number;
+}): ValidatedUpdateCache | null;

package/dist/core/update-cache.js

@@ -0,0 +1,141 @@
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { getGlobalDir } from '../storage/global-dir.js';
+import { isProcessAlive, readProcessStartTime } from '../utils/process-identity.js';
+export const UPDATE_CACHE_TTL_MS = 24 * 60 * 60 * 1_000;
+export const STRICT_UPDATE_VERSION = /^\d+\.\d+\.\d+$/;
+export const DEFAULT_UPDATE_REGISTRY = 'https://registry.npmjs.org';
+/** Broad truthy parsing shared by the update-notifier guards. */
+export function isTruthyEnv(value) {
+    if (!value)
+        return false;
+    return !['', '0', 'false', 'no', 'off'].includes(value.toLowerCase());
+}
+/** The update notifier is disabled by either opt-out env or a CI environment. */
+export function updateNotifierOptedOut(env) {
+    return (isTruthyEnv(env.GITNEXUS_NO_UPDATE_NOTIFIER) ||
+        isTruthyEnv(env.NO_UPDATE_NOTIFIER) ||
+        isTruthyEnv(env.CI));
+}
+/** Freshness gate for the 24h TTL; future-dated timestamps are stale. */
+export function isUpdateCacheFresh(lastCheckAt, now) {
+    const checkedAt = Date.parse(lastCheckAt);
+    return checkedAt <= now && now - checkedAt < UPDATE_CACHE_TTL_MS;
+}
+/** Strict x.y.z numeric comparison. Invalid or prerelease versions are silent. */
+export function isNewerVersion(installedVersion, latestVersion) {
+    if (!STRICT_UPDATE_VERSION.test(installedVersion) || !STRICT_UPDATE_VERSION.test(latestVersion)) {
+        return false;
+    }
+    const installed = installedVersion.split('.').map(BigInt);
+    const latest = latestVersion.split('.').map(BigInt);
+    for (let index = 0; index < 3; index += 1) {
+        if (latest[index] !== installed[index])
+            return latest[index] > installed[index];
+    }
+    return false;
+}
+let registryMemo;
+export function normalizedUpdateRegistry(env = process.env) {
+    const key = env.npm_config_registry ?? '';
+    if (registryMemo?.key === key)
+        return registryMemo.value;
+    const value = buildUpdateRegistry(key);
+    registryMemo = { key, value };
+    return value;
+}
+function buildUpdateRegistry(rawRegistry) {
+    const parsed = new URL(rawRegistry || DEFAULT_UPDATE_REGISTRY);
+    if (parsed.protocol !== 'https:' && parsed.protocol !== 'http:') {
+        throw new Error('Unsupported npm registry protocol');
+    }
+    if (parsed.search || parsed.hash) {
+        throw new Error('Registry URL cannot contain query or fragment');
+    }
+    parsed.username = '';
+    parsed.password = '';
+    parsed.pathname = parsed.pathname.replace(/\/+$/, '') || '/';
+    const pathname = parsed.pathname === '/' ? '' : parsed.pathname;
+    const identity = `${parsed.protocol}//${parsed.host}${pathname}`;
+    // `/<pkg>/latest` is the small dist-tag document. The full packument at
+    // `/<pkg>` is multi-megabyte on this package and cannot fit the fetch cap.
+    const packagePath = `${pathname}/gitnexus/latest`.replace(/\/{2,}/g, '/');
+    return { identity, packageUrl: `${parsed.protocol}//${parsed.host}${packagePath}` };
+}
+export function updateCheckCachePath(env = process.env) {
+    return path.join(env.GITNEXUS_HOME || getGlobalDir(), 'update-check.json');
+}
+export function updateCheckLockPath(env = process.env) {
+    return path.join(env.GITNEXUS_HOME || getGlobalDir(), 'update-check.lock');
+}
+/**
+ * Best-effort synchronous probe: is a refresh plausibly in flight? Used to
+ * coalesce detached refresh spawns. A dead same-host owner returns false so
+ * the spawned child can reclaim the stale lock; a foreign-host owner returns
+ * false and lets the child's full lock logic decide.
+ */
+export function updateRefreshInProgress(env = process.env) {
+    try {
+        const owner = JSON.parse(fs.readFileSync(updateCheckLockPath(env), 'utf8'));
+        if (typeof owner.pid !== 'number' || owner.pid <= 0)
+            return false;
+        if (owner.hostname !== os.hostname())
+            return false;
+        if (!isProcessAlive(owner.pid))
+            return false;
+        // Same rule as acquireFileLock: a live PID with a different start time is
+        // reuse, not the lock owner. Unreadable start time stays conservative
+        // (treat as in progress) so we don't spawn a racing child.
+        if (typeof owner.processStartTime === 'string' && owner.processStartTime) {
+            const currentStartTime = readProcessStartTime(owner.pid);
+            if (currentStartTime && currentStartTime !== owner.processStartTime)
+                return false;
+        }
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+export function parseUpdateCache(raw, registry) {
+    try {
+        const parsed = JSON.parse(raw);
+        if (typeof parsed.lastCheckAt !== 'string' ||
+            !Number.isFinite(Date.parse(parsed.lastCheckAt)) ||
+            parsed.registry !== registry ||
+            (parsed.latestVersion !== undefined &&
+                (typeof parsed.latestVersion !== 'string' ||
+                    !STRICT_UPDATE_VERSION.test(parsed.latestVersion)))) {
+            return null;
+        }
+        return {
+            lastCheckAt: parsed.lastCheckAt,
+            registry: parsed.registry,
+            ...(parsed.latestVersion === undefined ? {} : { latestVersion: parsed.latestVersion }),
+        };
+    }
+    catch {
+        return null;
+    }
+}
+export function readValidatedUpdateCacheSync(options = {}) {
+    try {
+        const env = options.env ?? process.env;
+        const registry = normalizedUpdateRegistry(env);
+        const raw = fs.readFileSync(updateCheckCachePath(env), 'utf8');
+        const entry = parseUpdateCache(raw, registry.identity);
+        if (!entry)
+            return null;
+        const lastCheckAt = Date.parse(entry.lastCheckAt);
+        const now = options.now ?? Date.now();
+        return {
+            lastCheckAt,
+            ...(entry.latestVersion === undefined ? {} : { latestVersion: entry.latestVersion }),
+            stale: !isUpdateCacheFresh(entry.lastCheckAt, now),
+        };
+    }
+    catch {
+        return null;
+    }
+}

package/dist/core/update-check.d.ts

@@ -0,0 +1,31 @@
+export interface UpdateState {
+    updateAvailable: boolean;
+    latestVersion?: string;
+}
+export interface UpdateCheckOptions {
+    /** Test/adapter override; omitted means classify process.argv[1]. */
+    eligible?: boolean;
+    /** Test override; omitted means this package's installed version. */
+    installedVersion?: string;
+    /** Test override in epoch milliseconds. */
+    now?: number;
+    /** Cache-only consumers can suppress stale-while-revalidate. */
+    refreshIfStale?: boolean;
+    /** Explicit `gitnexus update`: check even when CI/opt-out env is set. */
+    ignoreOptOut?: boolean;
+}
+export interface UpdateRefreshSchedulerOptions extends Omit<UpdateCheckOptions, 'now' | 'refreshIfStale'> {
+    now?: () => number;
+}
+/**
+ * Read update state cache-first. Every invalid/missing/stale cache starts one
+ * catch-isolated refresh unless the caller explicitly requests cache-only.
+ */
+export declare function evaluate(options?: UpdateCheckOptions): Promise<UpdateState | null>;
+/** Run one locked, fail-open registry refresh. */
+export declare function refresh(options?: UpdateCheckOptions): Promise<UpdateState | null>;
+/**
+ * Start an immediate evaluation and repeat on the cache TTL cadence. Timers
+ * never keep the process alive; refresh() supplies process-wide single-flight.
+ */
+export declare function armUpdateRefreshScheduler(onState: (state: UpdateState | null) => void, options?: UpdateRefreshSchedulerOptions): () => void;

package/dist/core/update-check.js

@@ -0,0 +1,274 @@
+import fs from 'node:fs/promises';
+import { getGlobalDir } from '../storage/global-dir.js';
+import { writeFileAtomic } from '../storage/fs-atomic.js';
+import { acquireFileLock, FileLockBusyError } from '../storage/file-lock.js';
+import { validateGitUrl } from './net/url-guard.js';
+import { updateEligibleInstall } from './install-context.js';
+import { createLogger } from './logger.js';
+import { packageVersion } from './package-version.js';
+import { isNewerVersion, isUpdateCacheFresh, normalizedUpdateRegistry, parseUpdateCache, STRICT_UPDATE_VERSION, UPDATE_CACHE_TTL_MS, updateCheckCachePath, updateCheckLockPath, updateNotifierOptedOut, } from './update-cache.js';
+const FETCH_TIMEOUT_MS = 3_000;
+const MAX_RESPONSE_BYTES = 64 * 1024;
+const MAX_REDIRECTS = 5;
+/** Backoff when refresh cannot publish (lock-busy or still-stale cache). */
+const LOCK_BUSY_RETRY_MIN_MS = 30_000;
+const LOCK_BUSY_RETRY_JITTER_MS = 30_000;
+const updateLogger = createLogger('update-check');
+function defaultInstalledVersion() {
+    return packageVersion();
+}
+function nextSchedulerDelay(entry, now) {
+    if (entry && isUpdateCacheFresh(entry.lastCheckAt, now)) {
+        return Math.max(1, Date.parse(entry.lastCheckAt) + UPDATE_CACHE_TTL_MS - now);
+    }
+    // Missing, future-dated, or still stale after a lock-busy skip: back off
+    // from now instead of deriving 1ms from a past-due timestamp.
+    return LOCK_BUSY_RETRY_MIN_MS + Math.floor(Math.random() * LOCK_BUSY_RETRY_JITTER_MS);
+}
+function isOptedOut() {
+    return updateNotifierOptedOut(process.env);
+}
+async function isEligible(override) {
+    return override ?? (await updateEligibleInstall());
+}
+function cacheFile() {
+    return updateCheckCachePath();
+}
+function lockFile() {
+    return updateCheckLockPath();
+}
+function normalizedRegistry() {
+    const registry = normalizedUpdateRegistry();
+    validateGitUrl(registry.packageUrl);
+    return registry;
+}
+async function readCache(registry) {
+    try {
+        return parseUpdateCache(await fs.readFile(cacheFile(), 'utf8'), registry);
+    }
+    catch {
+        return null;
+    }
+}
+function stateFrom(entry, installedVersion) {
+    return {
+        updateAvailable: entry.latestVersion !== undefined && isNewerVersion(installedVersion, entry.latestVersion),
+        ...(entry.latestVersion === undefined ? {} : { latestVersion: entry.latestVersion }),
+    };
+}
+function installedVersionOf(options) {
+    return options.installedVersion ?? defaultInstalledVersion();
+}
+async function isNotifierActive(options = {}) {
+    return (options.ignoreOptOut === true || !isOptedOut()) && (await isEligible(options.eligible));
+}
+/**
+ * Read update state cache-first. Every invalid/missing/stale cache starts one
+ * catch-isolated refresh unless the caller explicitly requests cache-only.
+ */
+export async function evaluate(options = {}) {
+    try {
+        if (!(await isNotifierActive(options)))
+            return null;
+        const registry = normalizedRegistry();
+        const now = options.now ?? Date.now();
+        const entry = await readCache(registry.identity);
+        if ((!entry || !isUpdateCacheFresh(entry.lastCheckAt, now)) &&
+            options.refreshIfStale !== false) {
+            void refresh(options).catch(() => { });
+        }
+        if (!entry)
+            return null;
+        return stateFrom(entry, installedVersionOf(options));
+    }
+    catch {
+        return null;
+    }
+}
+async function readResponseBody(response) {
+    const advertised = Number(response.headers.get('content-length'));
+    if (Number.isFinite(advertised) && advertised > MAX_RESPONSE_BYTES) {
+        await response.body?.cancel().catch(() => { });
+        throw new Error('Registry response too large');
+    }
+    if (!response.body)
+        return '';
+    const reader = response.body.getReader();
+    const chunks = [];
+    let bytes = 0;
+    try {
+        for (;;) {
+            const { done, value } = await reader.read();
+            if (done)
+                break;
+            bytes += value.byteLength;
+            if (bytes > MAX_RESPONSE_BYTES)
+                throw new Error('Registry response too large');
+            chunks.push(value);
+        }
+    }
+    finally {
+        if (bytes > MAX_RESPONSE_BYTES)
+            await reader.cancel().catch(() => { });
+        reader.releaseLock();
+    }
+    return Buffer.concat(chunks).toString('utf8');
+}
+function sanitizedHttpUrl(input, base) {
+    const parsed = new URL(input, base);
+    parsed.username = '';
+    parsed.password = '';
+    validateGitUrl(parsed.toString());
+    return parsed;
+}
+async function fetchLatest(packageUrl) {
+    let url = sanitizedHttpUrl(packageUrl);
+    for (let redirects = 0;; redirects += 1) {
+        const response = await fetch(url.toString(), {
+            method: 'GET',
+            redirect: 'manual',
+            headers: { accept: 'application/json' },
+            signal: AbortSignal.timeout(FETCH_TIMEOUT_MS),
+        });
+        if (response.status >= 300 && response.status < 400) {
+            if (redirects >= MAX_REDIRECTS)
+                throw new Error('Too many registry redirects');
+            const location = response.headers.get('location');
+            await response.body?.cancel().catch(() => { });
+            if (!location)
+                throw new Error('Registry redirect missing location');
+            url = sanitizedHttpUrl(location, url.toString());
+            continue;
+        }
+        if (!response.ok) {
+            await response.body?.cancel().catch(() => { });
+            throw new Error(`Registry returned ${response.status}`);
+        }
+        const parsed = JSON.parse(await readResponseBody(response));
+        const latest = (typeof parsed.version === 'string' ? parsed.version : undefined) ??
+            (typeof parsed['dist-tags']?.latest === 'string' ? parsed['dist-tags'].latest : undefined);
+        if (typeof latest !== 'string' || !STRICT_UPDATE_VERSION.test(latest)) {
+            throw new Error('Registry latest version is invalid');
+        }
+        return latest;
+    }
+}
+async function publishMonotonically(entry, attemptStartedAt) {
+    const current = await readCache(entry.registry);
+    const currentAt = current ? Date.parse(current.lastCheckAt) : Number.NaN;
+    // A later in-the-past write wins. Future-dated entries (wall-clock) are
+    // clock-skew poison and must stay replaceable so a later holder can repair them.
+    if (Number.isFinite(currentAt) && currentAt <= Date.now() && currentAt > attemptStartedAt) {
+        return;
+    }
+    await fs.mkdir(getGlobalDir(), { recursive: true });
+    await writeFileAtomic(cacheFile(), `${JSON.stringify(entry)}\n`, 1);
+}
+let refreshInFlight = null;
+/** Run one locked, fail-open registry refresh. */
+export function refresh(options = {}) {
+    if (refreshInFlight)
+        return refreshInFlight;
+    const run = async () => {
+        let release;
+        try {
+            if (!(await isNotifierActive(options)))
+                return null;
+            const registry = normalizedRegistry();
+            const attemptStartedAt = options.now ?? Date.now();
+            try {
+                release = await acquireFileLock(lockFile(), { retries: 0 });
+            }
+            catch (error) {
+                if (error instanceof FileLockBusyError)
+                    return null;
+                throw error;
+            }
+            let fetched;
+            try {
+                fetched = await fetchLatest(registry.packageUrl);
+            }
+            catch {
+                // Negative entries enforce the same TTL on offline/authenticated-only
+                // registries as successful checks. A known same-identity latestVersion
+                // must survive a later failed refresh so notices do not go silent
+                // for a day; only a first-ever miss stays version-less.
+            }
+            const latestVersion = fetched ?? (await readCache(registry.identity))?.latestVersion;
+            const entry = {
+                lastCheckAt: new Date(attemptStartedAt).toISOString(),
+                registry: registry.identity,
+                ...(latestVersion === undefined ? {} : { latestVersion }),
+            };
+            await publishMonotonically(entry, attemptStartedAt);
+            // Live fetch failed: keep the on-disk pin for notices, but do not
+            // return it as a confirmed refresh so `gitnexus update` cannot install
+            // from an unconfirmed cache.
+            if (fetched === undefined)
+                return null;
+            return stateFrom(entry, installedVersionOf(options));
+        }
+        catch (error) {
+            updateLogger.debug({ code: error.code }, 'Update check failed open');
+            return null;
+        }
+        finally {
+            if (release)
+                await release().catch(() => { });
+        }
+    };
+    refreshInFlight = run().finally(() => {
+        refreshInFlight = null;
+    });
+    return refreshInFlight;
+}
+/**
+ * Start an immediate evaluation and repeat on the cache TTL cadence. Timers
+ * never keep the process alive; refresh() supplies process-wide single-flight.
+ */
+export function armUpdateRefreshScheduler(onState, options = {}) {
+    let stopped = false;
+    let timer;
+    const cycle = async () => {
+        if (stopped)
+            return;
+        const now = options.now?.() ?? Date.now();
+        let entry = null;
+        try {
+            const registry = normalizedRegistry();
+            entry = await readCache(registry.identity);
+            if (!entry || !isUpdateCacheFresh(entry.lastCheckAt, now)) {
+                await refresh({ ...options, now });
+                entry = await readCache(registry.identity);
+            }
+        }
+        catch {
+            // The public scheduler shares the service's fail-open contract.
+        }
+        // Derive state from the entry already read above; a full evaluate() here
+        // would re-run guards and re-read the cache on every tick.
+        let state = null;
+        try {
+            state =
+                !entry || !(await isNotifierActive(options))
+                    ? null
+                    : stateFrom(entry, installedVersionOf(options));
+        }
+        catch {
+            state = null;
+        }
+        if (!stopped)
+            onState(state);
+        if (!stopped) {
+            timer = setTimeout(() => void cycle(), nextSchedulerDelay(entry, now));
+            timer.unref();
+        }
+    };
+    timer = setTimeout(() => void cycle(), 0);
+    timer.unref();
+    return () => {
+        stopped = true;
+        if (timer)
+            clearTimeout(timer);
+    };
+}

package/dist/mcp/local/local-backend.d.ts

@@ -5,14 +5,12 @@
  * Supports multiple indexed repositories via a global registry.
  * LadybugDB connections are opened lazily per repo on first query.
  */
+import { isTestFilePath } from '../../core/ingestion/utils/test-file-path.js';
 import { type RegistryEntry, type BranchSummary } from '../../storage/repo-manager.js';
 import { GroupService } from '../../core/group/service.js';
 import { type StalenessInfo } from '../../core/git-staleness.js';
-/**
- * Quick test-file detection for filtering impact results.
- * Matches common test file patterns across all supported languages.
- */
-export declare function isTestFilePath(filePath: string | null | undefined): boolean;
+/** Shared predicate; re-exported so MCP importers keep the old public name. */
+export { isTestFilePath };
 /** Valid LadybugDB node labels for safe Cypher query construction */
 export declare const VALID_NODE_LABELS: Set<string>;
 /** Valid relation types for impact analysis filtering */
@@ -371,10 +369,26 @@ export declare class LocalBackend {
      * - If only 1 repo, use it
      * - If 0 or multiple without param, throw with helpful message
      *
-     * On a miss, re-reads the registry once in case a new repo was indexed
-     * while the MCP server was running.
+     * Re-reads the registry before an omitted implicit target or after an
+     * explicit miss, so long-running servers see newly indexed repositories.
      */
     resolveRepo(repoParam?: string, branch?: string): Promise<RepoHandle>;
+    /**
+     * Internal resolver variant for CLI/MCP tool routing and discovery.
+     * - If repoParam is given, match by name or path
+     * - If only 1 repo, use it
+     * - If multiple repos exist and repoParam is omitted, callers may opt in to
+     *   the registered repo containing process.cwd()
+     * - If 0 repos exist, or cwd cannot disambiguate multiple repos, throw
+     *
+     * Omitted-repo resolution re-reads the registry before accepting any
+     * implicit target, including a cached singleton. A caller that just obtained
+     * a fresh registry snapshot may disable that refresh explicitly.
+     */
+    selectToolRepository(repoParam?: string, branch?: string, options?: {
+        allowCwdDefault?: boolean;
+        refreshRegistry?: boolean;
+    }): Promise<RepoHandle>;
     /**
      * Re-point a resolved repo handle at a specific branch index (#2106).
      *
@@ -409,12 +423,13 @@ export declare class LocalBackend {
      */
     private resolveRepoFromCache;
     /**
-     * Prefer the indexed repo whose path matches the git root of process.cwd().
+     * Match process.cwd() against indexed repositories.
      *
-     * In MCP stdio server mode, `process.cwd()` is the server's launch directory,
-     * not the agent client's cwd. If the server was started from an unrelated
-     * directory, `getGitRoot` returns null and duplicate-name resolution throws
-     * {@link RegistryAmbiguousTargetError} — callers should pass an absolute path.
+     * Explicit duplicate aliases use exact Git-root matching only. Omitted
+     * read-only calls opt into deepest containing-path selection. In that mode a
+     * candidate must not sit above cwd's Git root, so an unindexed nested checkout
+     * cannot fall through to an indexed ancestor. The `.git` ancestor fallback
+     * preserves that boundary when the git executable is unavailable.
      */
     private pickRepoHandleForCwd;
     private handleToRegistryEntry;
@@ -842,4 +857,3 @@ export declare class LocalBackend {
     queryProcessDetail(name: string, repoName?: string): Promise<any>;
     disconnect(): Promise<void>;
 }
-export {};