@aroman22/codegraph-vba 1.3.3

package/dist/sync/git-hooks.d.ts

@@ -0,0 +1,45 @@
+/**
+ * Git Sync Hooks
+ *
+ * When the live file watcher is disabled (e.g. on WSL2 `/mnt/*` drives,
+ * see watch-policy.ts), the CodeGraph index would otherwise go stale until
+ * the user runs `codegraph sync` by hand. As an opt-in alternative, we can
+ * install git hooks that refresh the index after the operations that change
+ * files on disk: commit, merge (covers `git pull`), and checkout.
+ *
+ * The hooks run `codegraph sync` in the background so they never block git,
+ * and are guarded by `command -v codegraph` so they no-op cleanly when the
+ * CLI isn't on PATH. Our snippet is delimited by marker comments so install
+ * is idempotent and removal preserves any user-authored hook content.
+ */
+export type GitHookName = 'post-commit' | 'post-merge' | 'post-checkout';
+/** Hooks installed by default: commit, merge (git pull), and checkout. */
+export declare const DEFAULT_SYNC_HOOKS: GitHookName[];
+export interface GitHookResult {
+    /** Hook names that were created or updated. */
+    installed: GitHookName[];
+    /** Resolved hooks directory, or null when not a git repo. */
+    hooksDir: string | null;
+    /** Reason nothing happened (e.g. not a git repository). */
+    skipped?: string;
+}
+/**
+ * Whether `projectRoot` is inside a git working tree. Returns false if git
+ * isn't installed or the path isn't a repo.
+ */
+export declare function isGitRepo(projectRoot: string): boolean;
+/**
+ * Install (or update) the CodeGraph sync hooks in a git repository.
+ * Idempotent: re-running replaces our marker block rather than duplicating
+ * it, and any user-authored hook content is preserved.
+ */
+export declare function installGitSyncHook(projectRoot: string, hooks?: GitHookName[]): GitHookResult;
+/**
+ * Remove the CodeGraph sync hooks. Strips only our marker block; deletes the
+ * hook file entirely when nothing but a shebang remains, otherwise rewrites
+ * the user's content untouched.
+ */
+export declare function removeGitSyncHook(projectRoot: string, hooks?: GitHookName[]): GitHookResult;
+/** Whether any CodeGraph sync hook is currently installed. */
+export declare function isSyncHookInstalled(projectRoot: string, hooks?: GitHookName[]): boolean;
+//# sourceMappingURL=git-hooks.d.ts.map

package/dist/sync/index.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Sync Module
+ *
+ * Provides synchronization functionality for keeping the code graph
+ * up-to-date with file system changes.
+ *
+ * Components:
+ * - FileWatcher: Debounced fs.watch that auto-triggers sync on file changes
+ * - Watch policy: decides when the watcher must be disabled (e.g. WSL2 /mnt)
+ * - Git sync hooks: opt-in commit/merge/checkout hooks when watching is off
+ * - Git worktree awareness: detect when a query borrows another tree's index
+ * - Content hashing for change detection (in extraction module)
+ * - Incremental reindexing (in extraction module)
+ */
+export { FileWatcher, WatchOptions, PendingFile, LockUnavailableError } from './watcher';
+export { watchDisabledReason, detectWsl } from './watch-policy';
+export { installGitSyncHook, removeGitSyncHook, isSyncHookInstalled, isGitRepo, DEFAULT_SYNC_HOOKS, type GitHookName, type GitHookResult, } from './git-hooks';
+export { gitWorktreeRoot, detectWorktreeIndexMismatch, worktreeMismatchWarning, worktreeMismatchNotice, type WorktreeIndexMismatch, } from './worktree';
+//# sourceMappingURL=index.d.ts.map

package/dist/sync/watch-policy.d.ts

@@ -0,0 +1,48 @@
+/**
+ * Watch Policy
+ *
+ * Decides whether the live file watcher should run for a given project.
+ *
+ * Native recursive `fs.watch` is pathologically slow on WSL2 `/mnt/*`
+ * drives (NTFS exposed over the 9p/drvfs bridge): setting up the recursive
+ * watch walks the directory tree, and every readdir/stat crosses the
+ * Windows boundary. Inside an MCP server this stalls the event loop during
+ * startup long enough to blow past host handshake timeouts (opencode's 30s),
+ * so the tools never appear. See issue #199.
+ *
+ * This module centralizes the on/off decision so the watcher, the MCP
+ * server (for diagnostics), and the installer all agree.
+ */
+/**
+ * Detect whether the current process is running under WSL (Windows
+ * Subsystem for Linux). Result is cached after the first call.
+ *
+ * Checks the WSL-specific env vars first (no I/O), then falls back to
+ * `/proc/version`, which contains "microsoft" on WSL kernels.
+ */
+export declare function detectWsl(): boolean;
+/**
+ * Inputs that can be overridden in tests so the decision is deterministic
+ * without touching real env vars or `/proc/version`.
+ */
+export interface WatchProbe {
+    /** Defaults to `process.env`. */
+    env?: NodeJS.ProcessEnv;
+    /** Defaults to `detectWsl()`. */
+    isWsl?: boolean;
+}
+/**
+ * Decide whether the file watcher should be disabled for a project, and why.
+ *
+ * Returns a short human-readable reason when watching should be skipped, or
+ * `null` when it should run normally.
+ *
+ * Precedence (first match wins):
+ *  1. `CODEGRAPH_NO_WATCH=1`    → off  (explicit opt-out always wins)
+ *  2. `CODEGRAPH_FORCE_WATCH=1` → on   (overrides auto-detection)
+ *  3. WSL2 + `/mnt/*` drive     → off  (recursive fs.watch is too slow; #199)
+ */
+export declare function watchDisabledReason(projectRoot: string, probe?: WatchProbe): string | null;
+/** Test-only: reset the cached WSL detection. */
+export declare function __resetWslCacheForTests(): void;
+//# sourceMappingURL=watch-policy.d.ts.map

package/dist/sync/watcher.d.ts

@@ -0,0 +1,358 @@
+/**
+ * File Watcher
+ *
+ * Watches the project directory for file changes and triggers debounced sync
+ * operations to keep the code graph up-to-date.
+ *
+ * Uses Node's built-in `fs.watch` directly (no third-party watcher, no native
+ * addon) with a per-platform strategy chosen to keep the open-descriptor /
+ * kernel-watch cost BOUNDED rather than growing with the number of files:
+ *
+ *   - macOS / Windows: a SINGLE recursive `fs.watch(root, {recursive:true})`.
+ *     libuv maps this to one FSEvents stream (macOS) / one
+ *     ReadDirectoryChangesW handle (Windows), so it costs O(1) descriptors no
+ *     matter how large the tree. This is the fix for the macOS file-table
+ *     exhaustion (#644 / #496 / #555 / #628): the previous watcher held one
+ *     open fd PER WATCHED FILE on macOS (tens of thousands of REG fds), which
+ *     exhausted `kern.maxfiles` and crashed unrelated processes system-wide.
+ *
+ *   - Linux: recursive `fs.watch` is unsupported, so we watch each (non-ignored)
+ *     DIRECTORY with one inotify watch — O(directories), NOT O(files). New
+ *     directories are picked up dynamically and an overall watch cap bounds
+ *     inotify usage on pathological monorepos (#579). A single inotify watch on
+ *     a directory already reports create/modify/delete for its children, so
+ *     per-file watches are never needed.
+ *
+ * Excluded trees (node_modules/, dist/, .git/, …) are filtered via the
+ * indexer's `buildScopeIgnore` (built-in default-ignore dirs + the project's
+ * .gitignore) — on Linux they're never descended into (so they cost no watch),
+ * and on macOS/Windows the single recursive stream still covers them but their
+ * events are dropped before any sync is scheduled. Either way the watcher's
+ * scope matches the indexer's (#276 / #407).
+ */
+import * as fs from 'fs';
+/**
+ * Indirection over `fs.watch` so tests can inject a fake that throws or emits
+ * `EMFILE`/`ENFILE` deterministically (real watch-resource exhaustion can't be
+ * provoked reliably, and `fs.watch` is a non-configurable property so it can't
+ * be spied). Production always uses the real `fs.watch`.
+ */
+type WatchFn = typeof fs.watch;
+/** @internal Test-only seam to inject a fake fs.watch implementation. */
+export declare function __setFsWatchForTests(fn: WatchFn | null): void;
+/**
+ * Options for the file watcher
+ */
+export interface WatchOptions {
+    /**
+     * Debounce delay in milliseconds.
+     * After the last file change, wait this long before triggering sync.
+     * Default: 2000ms
+     */
+    debounceMs?: number;
+    /**
+     * Callback when a sync completes (for logging/diagnostics).
+     */
+    onSyncComplete?: (result: {
+        filesChanged: number;
+        durationMs: number;
+    }) => void;
+    /**
+     * Callback when a sync errors (for logging/diagnostics).
+     */
+    onSyncError?: (error: Error) => void;
+    /**
+     * Callback fired ONCE when live watching degrades permanently and auto-sync
+     * is disabled — OS watch-resource exhaustion (EMFILE/ENFILE), or a write lock
+     * held past the retry budget. The string is an actionable, human-readable
+     * reason. Lets a host (MCP server, daemon, CLI) tell the user that the index
+     * will no longer auto-update instead of silently serving stale results.
+     */
+    onDegraded?: (reason: string) => void;
+    /**
+     * Test-only. When true, `start()` installs NO OS-level fs.watch — the
+     * watcher is "inert" and only the {@link __emitWatchEventForTests} /
+     * {@link FileWatcher.ingestEventForTests} seam drives its pipeline. This
+     * restores the deterministic, OS-free behavior the unit tests need (real
+     * FSEvents/inotify delivery races under parallel vitest). Production never
+     * sets it.
+     */
+    inertForTests?: boolean;
+}
+/**
+ * Thrown by a `syncFn` to signal that the underlying sync couldn't acquire
+ * the cross-process write lock (#449). The watcher treats this as "no
+ * progress" — preserves `pendingFiles`, skips `onSyncComplete`, and the
+ * `finally` block reschedules. Quiet (debug-only) because a long-running
+ * external indexer can hit this every debounce cycle.
+ */
+export declare class LockUnavailableError extends Error {
+    constructor(message?: string);
+}
+/**
+ * Per-file pending entry — tracks a source file the watcher saw an event for
+ * but hasn't yet synced into the index. Exposed via {@link FileWatcher.getPendingFiles}
+ * so MCP tool responses can mark stale results without forcing a wait.
+ */
+export interface PendingFile {
+    /** Project-relative POSIX path (e.g. "src/foo.ts"). */
+    path: string;
+    /** Wall-clock ms at the first event we saw for this path since the last sync. */
+    firstSeenMs: number;
+    /** Wall-clock ms at the most recent event we saw for this path. */
+    lastSeenMs: number;
+    /**
+     * True when a sync is currently in flight that began AFTER this file's most
+     * recent event — i.e. the next successful sync will pick it up. False when
+     * the file is still in the debounce window (no sync running yet).
+     */
+    indexing: boolean;
+}
+/**
+ * FileWatcher monitors a project directory for changes and triggers
+ * debounced sync operations via a provided callback.
+ *
+ * Design goals:
+ * - Bounded resource usage: O(1) descriptors on macOS/Windows (one recursive
+ *   watch), O(directories) inotify watches on Linux — never O(files), which
+ *   was the system-crashing fd leak on macOS (#644/#496/#555/#628).
+ * - Debounced to avoid thrashing on rapid saves
+ * - Filters to supported source files by extension
+ * - Ignores .codegraph/ and .git/ regardless of .gitignore
+ * - Tracks per-file pending state so MCP tools can flag stale results
+ *   without blocking on a sync (issue #403)
+ */
+export declare class FileWatcher {
+    /** macOS/Windows: the single recursive watcher. Null on Linux. */
+    private recursiveWatcher;
+    /** Linux: one watcher per watched directory (keyed by absolute path). */
+    private dirWatchers;
+    /** Set once the per-directory watch cap is hit, so we log only once. */
+    private dirCapWarned;
+    /**
+     * Set once the Linux inotify watch limit (ENOSPC) is hit. Double duty: we
+     * warn only once, AND we stop attempting new directory watches for the rest
+     * of the session — once the kernel budget is exhausted every further
+     * `inotify_add_watch` fails too, so trying the rest of the tree is pure
+     * waste. NON-fatal (does not degrade): installed watches keep working.
+     */
+    private inotifyLimitWarned;
+    /**
+     * One-way latch: the reason live watching was permanently disabled at runtime
+     * (watch-resource exhaustion, or lock contention past the retry budget), or
+     * null while healthy. Set by {@link degrade}; cleared only by a fresh start().
+     */
+    private degradedReason;
+    /** Consecutive lock-contention retries for watcher-triggered syncs. */
+    private lockRetryCount;
+    /** Test-only inert mode: started, but with no OS watcher installed. */
+    private inert;
+    private debounceTimer;
+    /**
+     * Files seen by the watcher since the last successful sync — populated on
+     * every change event, cleared at the start of a sync, and re-populated by
+     * events that arrive mid-sync (or restored on sync failure). Keyed by the
+     * same project-relative POSIX path the rest of the codebase uses, so a
+     * caller can intersect tool-response file paths against this map cheaply.
+     */
+    private pendingFiles;
+    /**
+     * Wall-clock ms at which the in-flight sync began. Combined with
+     * {@link pendingFiles}'s `lastSeenMs`, this distinguishes "still in the
+     * debounce window" (lastSeen > syncStarted, sync hasn't started yet for
+     * this edit) from "currently being indexed" (lastSeen <= syncStarted).
+     */
+    private syncStartedMs;
+    private syncing;
+    private stopped;
+    /**
+     * True once the initial watch set is established. Unlike the previous
+     * chokidar implementation there is no asynchronous initial "crawl" emitting
+     * an `add` per existing file — `fs.watch` only reports changes from the
+     * moment it's installed — so this flips to true synchronously at the end of
+     * `start()`. The startup reconcile against on-disk state is handled
+     * separately by the engine's catch-up sync, not by the watcher.
+     */
+    private ready;
+    /**
+     * Callbacks that resolve when the watch set is established. Used by tests
+     * (and any production caller that cares about a clean baseline) to
+     * deterministically gate on watcher readiness.
+     */
+    private readyWaiters;
+    private ignoreMatcher;
+    private readonly projectRoot;
+    private readonly debounceMs;
+    private readonly syncFn;
+    private readonly onSyncComplete?;
+    private readonly onSyncError?;
+    private readonly onDegraded?;
+    private readonly inertForTests;
+    constructor(projectRoot: string, syncFn: () => Promise<{
+        filesChanged: number;
+        durationMs: number;
+    }>, options?: WatchOptions);
+    /**
+     * Start watching for file changes.
+     * Returns true if watching started successfully, false otherwise.
+     */
+    start(): boolean;
+    /**
+     * macOS/Windows: one recursive watcher for the whole tree. O(1) descriptors.
+     * `filename` arrives relative to the project root (with subdirectories), so
+     * it maps straight to a project-relative path.
+     */
+    private startRecursive;
+    /**
+     * Linux: walk the (non-ignored) tree and watch each directory. One inotify
+     * watch per directory reports create/modify/delete for that directory's
+     * direct children, so we never watch individual files.
+     */
+    private startPerDirectory;
+    /**
+     * Add an inotify watch for `dir` and recurse into its non-ignored
+     * subdirectories. When `markExisting` is true (a directory that appeared
+     * AFTER startup), the source files already inside it are recorded as pending
+     * — this closes the `mkdir + write` race where files created before the new
+     * directory's watch is installed would otherwise be missed until the next
+     * full sync. The initial startup walk passes false (the engine's catch-up
+     * sync owns the baseline).
+     */
+    private watchTree;
+    /**
+     * Linux per-directory event handler. `filename` is relative to `dir`. A new
+     * sub-directory is picked up by extending the watch tree; everything else is
+     * routed through the shared change handler.
+     */
+    private handleDirEvent;
+    /**
+     * True when `rel` is a Dysflow saved-query `.sql` file — i.e. a `.sql` whose
+     * directory also contains a `queries.json` manifest. This mirrors the
+     * directory-discovery gate so incremental edits to a query file are picked
+     * up, while ordinary `.sql` files (no sibling manifest) are ignored exactly
+     * as they are during a full index.
+     */
+    private isDysflowQuerySql;
+    /**
+     * Shared change handler for both watch strategies. `rel` is a
+     * project-relative POSIX path. Applies the ignore + source-file filters and,
+     * for a real source change, records it as pending (#403) and schedules a
+     * debounced sync.
+     *
+     * The recursive (macOS/Windows) watcher reports events for ignored trees too
+     * (one stream covers the whole repo), so the ignore check here is load-bearing
+     * — it drops node_modules/dist/.git churn before any sync is scheduled.
+     */
+    private handleChange;
+    /** Close and forget the watch for a directory that errored/was removed. */
+    private unwatchDir;
+    /** Our own dirs are always ignored, regardless of .gitignore. */
+    private isAlwaysIgnored;
+    /**
+     * True for any directory that should NOT be watched (used while building the
+     * Linux per-directory watch tree). Tests the directory form of the path so a
+     * dir-only ignore rule like `build/` matches.
+     */
+    private shouldIgnoreDir;
+    /**
+     * Permanently disable live watching after a terminal runtime failure
+     * (watch-resource exhaustion, or lock contention past the retry budget).
+     * Idempotent: logs one actionable warning, fires {@link WatchOptions.onDegraded}
+     * once, and stops the watcher. A subsequent start() clears the latch.
+     */
+    private degrade;
+    /**
+     * Warn ONCE that the Linux inotify watch budget is exhausted (ENOSPC), and
+     * stop adding new watches for the rest of this session — every further
+     * `inotify_add_watch` would fail too, so walking the rest of the tree is
+     * waste. Unlike {@link degrade} this is NON-fatal: the watches already
+     * installed keep firing, and `codegraph sync` covers the unwatched remainder.
+     * The message names the kernel knob to raise (`fs.inotify.max_user_watches`).
+     */
+    private warnInotifyLimit;
+    /**
+     * Whether live watching has degraded permanently (until the next start()).
+     * Distinct from {@link isActive}: a degraded watcher is inactive, but an
+     * inactive watcher is not necessarily degraded (it may simply be stopped or
+     * never started). Hosts use this to tell the user auto-sync is off.
+     */
+    isDegraded(): boolean;
+    /** The reason live watching degraded, or null if it is healthy. */
+    getDegradedReason(): string | null;
+    /**
+     * Stop watching for file changes.
+     */
+    stop(): void;
+    /**
+     * @internal Test-only: feed a synthetic project-relative change through the
+     * same filter → pendingFiles → debounced-sync path a real fs.watch event
+     * takes. Lets the watcher / staleness-banner suites stay deterministic
+     * instead of racing on OS watch-delivery latency. See
+     * {@link __emitWatchEventForTests}.
+     */
+    ingestEventForTests(relPath: string): void;
+    /**
+     * Whether the watcher is currently active.
+     */
+    isActive(): boolean;
+    /**
+     * Resolves once the watch set has been installed (or immediately if it
+     * already has). Useful for tests that need a deterministic boundary before
+     * asserting on `pendingFiles`.
+     *
+     * Production callers don't need this: `pendingFiles` is read continuously,
+     * the staleness banner is always correct (empty or populated), and there is
+     * no asynchronous initial-scan window with `fs.watch`.
+     */
+    waitUntilReady(timeoutMs?: number): Promise<void>;
+    /**
+     * Schedule a normal debounced sync after a source edit.
+     */
+    private scheduleSync;
+    /**
+     * Schedule a retry after a recoverable sync failure (lock contention). Kept
+     * separate from {@link scheduleSync} so prolonged contention backs off
+     * exponentially instead of hammering the lock every debounce cycle.
+     */
+    private scheduleRetrySync;
+    /**
+     * Flush pending changes by running sync.
+     *
+     * pendingFiles is NOT cleared at the start of sync — entries are removed
+     * only after sync commits successfully, and only for entries whose
+     * lastSeenMs <= syncStartedMs. That way, a query that arrives mid-sync
+     * still sees the affected files marked stale (the DB hasn't been updated
+     * yet), and an event that lands mid-sync persists into the follow-up.
+     *
+     * On sync failure pendingFiles is left untouched — every edit is still
+     * unindexed, and the rescheduled sync will absorb the same set next time.
+     */
+    private flush;
+    /**
+     * Snapshot of files seen by the watcher since the last successful sync.
+     *
+     * Used by MCP tool responses to mark stale results without blocking on a
+     * sync: a tool that returns a hit in `src/foo.ts` while `src/foo.ts` is in
+     * this list tells the agent "Read this file directly, the index lags."
+     *
+     * `indexing` is true when a sync is currently in flight whose start time is
+     * AFTER this file's most recent event — i.e. that sync will absorb the
+     * edit. False means the file is still inside the debounce window and no
+     * sync has started yet (a follow-up call a few hundred ms later may show
+     * `indexing: true` or the file may have left the list entirely).
+     *
+     * Cheap: O(pendingFiles.size), no I/O, no locks.
+     */
+    getPendingFiles(): PendingFile[];
+}
+/**
+ * Test-only: synthesize a source-file change for the live watcher running at
+ * `projectRoot`, exercising the real filter → pendingFiles → debounced-sync
+ * logic without depending on fs.watch delivery timing (which races under
+ * parallel vitest). `relPath` is project-relative POSIX (e.g. "src/foo.ts").
+ * Returns false if no live watcher is registered for that root (e.g. outside a
+ * test runtime, where the registry is intentionally not populated).
+ */
+export declare function __emitWatchEventForTests(projectRoot: string, relPath: string): boolean;
+export {};
+//# sourceMappingURL=watcher.d.ts.map

package/dist/sync/worktree.d.ts

@@ -0,0 +1,54 @@
+/**
+ * Git Worktree Awareness
+ *
+ * A CodeGraph index lives in a `.codegraph/` directory and is resolved by
+ * walking up parent directories to the nearest one (see
+ * `findNearestCodeGraphRoot`). That walk is unaware of git worktrees: when a
+ * worktree is created *inside* the main checkout (e.g. some tools place them
+ * under `.gitignore`d paths like `.claude/worktrees/<name>/`), a command run
+ * from the worktree walks up and silently resolves the MAIN checkout's index.
+ *
+ * Every query then returns results from the main tree's code — usually a
+ * different branch — rather than the worktree the user is actually editing.
+ * Symbols added or changed only in the worktree are invisible. This module
+ * detects that "borrowed index" situation so callers can warn about it.
+ *
+ * Detection is best-effort: when git is unavailable or the path isn't a repo,
+ * it reports "no mismatch" and callers carry on unchanged.
+ */
+/**
+ * Absolute, symlink-resolved toplevel of the git working tree that `dir`
+ * belongs to, or null when `dir` isn't inside a git repo (or git is missing).
+ *
+ * `git rev-parse --show-toplevel` returns the per-worktree root: the main
+ * checkout and each linked worktree report their own distinct directory, which
+ * is exactly the distinction this module relies on.
+ */
+export declare function gitWorktreeRoot(dir: string): string | null;
+export interface WorktreeIndexMismatch {
+    /** The git working tree the command was run from. */
+    worktreeRoot: string;
+    /** The (different) working tree whose `.codegraph` index is being used. */
+    indexRoot: string;
+}
+/**
+ * Detect when `startPath` lives in one git working tree but the resolved
+ * CodeGraph index (`indexRoot`) belongs to a *different* working tree.
+ *
+ * Returns null — meaning "nothing to warn about" — when:
+ *   - `startPath` isn't in a git repo (or git is unavailable),
+ *   - the index already lives in `startPath`'s own working tree, or
+ *   - `indexRoot` isn't itself a working-tree root (an unrelated parent dir
+ *     that merely happens to contain a `.codegraph/`), which keeps non-git
+ *     and monorepo-subdir layouts from producing false warnings.
+ */
+export declare function detectWorktreeIndexMismatch(startPath: string, indexRoot: string): WorktreeIndexMismatch | null;
+/** One-line-per-fact warning describing a detected mismatch. */
+export declare function worktreeMismatchWarning(m: WorktreeIndexMismatch): string;
+/**
+ * Compact, single-line variant for prefixing a tool's result. Read tools
+ * return their answer inline, so the heads-up has to ride on the same payload
+ * the agent is already reading — a multi-line block would bury the result.
+ */
+export declare function worktreeMismatchNotice(m: WorktreeIndexMismatch): string;
+//# sourceMappingURL=worktree.d.ts.map

package/dist/telemetry/index.d.ts

@@ -0,0 +1,143 @@
+/**
+ * Anonymous usage telemetry — client side.
+ *
+ * The contract for what may be collected lives in docs/design/telemetry.md
+ * (and user-facing TELEMETRY.md); the ingest endpoint that enforces it is
+ * public at telemetry-worker/. This module honors four invariants:
+ *
+ * 1. Zero hot-path cost: recording is an in-memory increment. Disk writes are
+ *    a tiny synchronous append at process exit (works under `process.exit()`,
+ *    where `beforeExit` never fires); network sends happen opportunistically
+ *    (startup of long-running commands, daemon interval, bounded await at the
+ *    end of install/init) and are fire-and-forget everywhere else.
+ * 2. Zero stdout: stdio is the MCP protocol channel. Notices and debug output
+ *    go to stderr only.
+ * 3. Off is off: when disabled, nothing is recorded, nothing is sent, and no
+ *    socket is opened — there is no "opted out" ping. Turning telemetry off
+ *    also deletes any buffered, unsent data.
+ * 4. Fail silent: offline, endpoint down, disk full — every failure mode is
+ *    silence, never a retry loop, never an error surfaced to the user/agent.
+ *
+ * Usage counts aggregate locally into per-day rollups; only *completed* (UTC)
+ * days are sent, so volume scales with active machines, not with tool calls.
+ */
+export declare const TELEMETRY_ENDPOINT = "https://telemetry.getcodegraph.com/v1/events";
+export declare const TELEMETRY_DOCS = "https://github.com/colbymchenry/codegraph/blob/main/TELEMETRY.md";
+export type UsageKind = 'mcp_tool' | 'cli_command';
+export type LifecycleEvent = 'install' | 'index' | 'uninstall';
+/** Coarse buckets — exact counts are deliberately not collected. */
+export declare function bucketFileCount(n: number): '<100' | '100-1k' | '1k-10k' | '10k+';
+export declare function bucketDuration(ms: number): '<10s' | '10-60s' | '1-5m' | '5m+';
+/**
+ * Shared "a full index completed" event (CLI init/index + installer local
+ * init): language names and coarse buckets only — never paths, file names,
+ * or exact counts. Structurally typed so callers don't need engine imports.
+ */
+export declare function recordIndexEvent(cg: {
+    getStats(): {
+        filesByLanguage: Record<string, number>;
+    };
+}, result: {
+    filesIndexed: number;
+    durationMs: number;
+}): void;
+export interface ClientInfo {
+    name?: string;
+    version?: string;
+}
+export interface TelemetryStatus {
+    enabled: boolean;
+    /** What decided the current state — mirrors the precedence order. */
+    decidedBy: 'DO_NOT_TRACK' | 'CODEGRAPH_TELEMETRY' | 'config' | 'default';
+    machineId: string | null;
+    configPath: string;
+}
+export interface TelemetryOptions {
+    /** Global state dir; defaults to ~/.codegraph. Tests inject a temp dir. */
+    dir?: string;
+    fetchImpl?: typeof globalThis.fetch;
+    now?: () => Date;
+    env?: NodeJS.ProcessEnv;
+    stderr?: (line: string) => void;
+    /** Tests opt out so short-lived instances don't pile onto process 'exit'. */
+    installExitHook?: boolean;
+}
+export declare class Telemetry {
+    private readonly dir;
+    private readonly fetchImpl;
+    private readonly now;
+    private readonly env;
+    private readonly writeStderr;
+    private counts;
+    private events;
+    private readonly installExitHook;
+    private exitHookInstalled;
+    private configCache;
+    private intervalHandle;
+    constructor(opts?: TelemetryOptions);
+    get configPath(): string;
+    get queuePath(): string;
+    /**
+     * Resolution order (first match wins) — keep in sync with TELEMETRY.md:
+     * DO_NOT_TRACK=1 > CODEGRAPH_TELEMETRY=0|1 > stored config > default on.
+     */
+    getStatus(): TelemetryStatus;
+    isEnabled(): boolean;
+    /**
+     * Persist an explicit user choice (installer toggle or `codegraph
+     * telemetry on|off`). Turning telemetry off also deletes any buffered,
+     * unsent data — off means off.
+     */
+    setEnabled(enabled: boolean, source: 'installer' | 'cli'): void;
+    /** True once any consent decision (or the first-run notice) is on disk. */
+    hasStoredChoice(): boolean;
+    /** In-memory increment — safe on the MCP tool-call hot path. */
+    recordUsage(kind: UsageKind, name: string, ok: boolean, client?: ClientInfo): void;
+    /** install / index / uninstall — buffered like everything else. */
+    recordLifecycle(event: LifecycleEvent, props: Record<string, unknown>): void;
+    /**
+     * Fire-and-forget send of everything sendable. Never throws, never logs
+     * above debug. Safe to call at startup of long-running commands.
+     */
+    maybeFlush(): void;
+    /**
+     * Drain in-memory state to the buffer, then send completed-day rollups and
+     * lifecycle events. Bounded by `timeoutMs`; leftovers stay buffered for the
+     * next process. Awaited only where latency is invisible (install/init).
+     */
+    flushNow(timeoutMs?: number): Promise<void>;
+    /**
+     * Periodic flush for long-lived processes (MCP daemon / serve). Unref'd so
+     * it never keeps the process alive.
+     */
+    startInterval(everyMs?: number): void;
+    stopInterval(): void;
+    private utcDay;
+    private readConfig;
+    private writeConfig;
+    /**
+     * Default-on consent is gated by a one-time stderr notice (interactive
+     * installs record their choice explicitly and never reach this).
+     */
+    private firstRunNotice;
+    /**
+     * Synchronous, tiny, exit-safe: drain in-memory deltas to the JSONL queue.
+     * Runs on `process.on('exit')`, so it must never be async or slow.
+     */
+    persistSync(): void;
+    private appendLines;
+    /**
+     * Atomically claim the queue for sending (rename). Concurrent processes
+     * can't double-send; a crash mid-send leaves a claim file that
+     * `recoverStaleClaims` merges back after an hour.
+     */
+    private claimQueue;
+    private recoverStaleClaims;
+    /** Returns the lines that did NOT make it out (to be re-queued). */
+    private send;
+    private packageVersion;
+    private ensureExitHook;
+    private debug;
+}
+export declare function getTelemetry(): Telemetry;
+//# sourceMappingURL=index.d.ts.map