@spikedpunch/mast 0.2.0 → 0.4.0

package/dist/indexer/watcher.d.ts

@@ -60,6 +60,62 @@ export interface WatchPathFilter {
  * set of files a manual `mast index` run would.
  */
 export declare function shouldWatchPath(filter: WatchPathFilter, absPath: string): boolean;
+/** One directory entry, reduced to what reconciliation needs. */
+export interface ListedEntry {
+    readonly name: string;
+    readonly isDirectory: boolean;
+}
+export interface UnwatchedEntries {
+    /** Every unknown file, including those inside unknown directories. */
+    readonly files: readonly string[];
+    /** Every unknown directory, at any depth. */
+    readonly directories: readonly string[];
+    /**
+     * The unknown entries whose parent the watcher already knows: handing these to
+     * the watcher is enough, because it descends into a directory by itself.
+     */
+    readonly roots: readonly string[];
+    /** Directories that could not be listed (vanished, EACCES); the rest was still scanned. */
+    readonly failures: ReadonlyArray<{
+        readonly directory: string;
+        readonly error: unknown;
+    }>;
+}
+export interface FindUnwatchedInput {
+    /** chokidar's `getWatched()`: absolute directory -> names of its children, files and directories alike. */
+    readonly watched: Readonly<Record<string, readonly string[]>>;
+    readonly projectRoot: string;
+    readonly listDirectory: (directory: string) => Promise<readonly ListedEntry[]>;
+    /** The same predicate the watcher was constructed with, applied to files and directories. */
+    readonly isIgnored: (absPath: string) => boolean;
+    /** Checked between directories, so a closed watcher stops walking a large tree. */
+    readonly signal?: AbortSignal;
+}
+/**
+ * Finds what is on disk but unknown to the watcher (D067). Pure over its inputs:
+ * `watched` is a snapshot and `listDirectory` is the only I/O.
+ *
+ * Only directories at or under `projectRoot` are listed: chokidar records the root
+ * itself as a child of the root's parent, and that parent is not ours to scan.
+ * A file the watcher learns about between the snapshot and the listing is reported
+ * too; that is a redundant notification, which the incremental reindex absorbs.
+ * Symbolic links are listed as files and never followed, so a link cycle cannot loop.
+ */
+export declare function findUnwatchedEntries(input: FindUnwatchedInput): Promise<UnwatchedEntries>;
+/** The members of chokidar's `FSWatcher` that `startWatchMode` uses. */
+export interface FsWatcher {
+    onFileEvent(event: 'add' | 'change' | 'unlink', listener: (path: string) => void): void;
+    onReady(listener: () => void): void;
+    onError(listener: (err: unknown) => void): void;
+    getWatched(): Record<string, string[]>;
+    add(paths: readonly string[]): unknown;
+    close(): Promise<void>;
+}
+export interface FsWatcherOptions {
+    readonly ignoreInitial: true;
+    readonly ignored: (path: string) => boolean;
+}
+export type FsWatcherFactory = (root: string, options: FsWatcherOptions) => FsWatcher;
 export interface WatchHandle {
     close(): Promise<void>;
 }
@@ -68,8 +124,46 @@ export interface StartWatchModeOptions {
     /** One incremental Phase 1 + embed run; supplied by the serve lifecycle. */
     readonly runBatch: (paths: readonly string[]) => Promise<void>;
     readonly onWarn: (message: string) => void;
+    /**
+     * Called once, after chokidar's initial scan, a settle period of `settleMs`, and
+     * one reconciliation pass over the directories chokidar is watching (D067).
+     * It means: every file that existed when the pass ran has been accounted for
+     * (queued for reindex if chokidar had not seen it), and the OS watch has had
+     * `settleMs` to go live. It is never called after `close()`.
+     *
+     * What it does not mean: chokidar's own `ready` fires before the OS watch is
+     * delivering, and a file created in that gap produces no event at all. The
+     * reconciliation pass recovers files created up to the moment it ran; a watch
+     * that goes live later than `settleMs` after `ready` is still a gap, and nothing
+     * here proves liveness. Each directory has its own OS watch, so a sentinel file
+     * would prove one directory only.
+     *
+     * Before D067 this fired straight from chokidar's `ready`, and under CPU load 12
+     * of 550 files written immediately after it were lost, against 0 of 400 written
+     * 300 ms after it.
+     *
+     * The watcher starts AFTER `serve` accepts MCP connections, and it is
+     * constructed with `ignoreInitial: true` — correct, since the startup ladder
+     * has already indexed the tree, but it means a file created before the scan
+     * finishes is treated as pre-existing and fires no event at all. Without this
+     * callback nothing outside the process could tell that window apart from
+     * "watching, nothing has changed" or from "the watcher failed to start": the
+     * EMFILE path warns, and the success path was silent, so silence meant three
+     * different things (D061).
+     *
+     * Optional. A caller that does not want the signal still gets a watcher.
+     */
+    readonly onReady?: () => void;
     /** Override for tests; production default 500ms. */
     readonly debounceMs?: number;
+    /**
+     * Wait between chokidar's `ready` and the reconciliation pass; production
+     * default 1000 ms. Measured under load (D067): 0 of 400 files lost when written
+     * 300 ms after `ready`; 1000 ms is a margin over that, not a measured bound.
+     */
+    readonly settleMs?: number;
+    /** Test seam; production uses chokidar. */
+    readonly watcherFactory?: FsWatcherFactory;
 }
 /**
  * Start `--watch` mode: a chokidar watcher over the project feeding the

package/dist/indexer/watcher.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../src/indexer/watcher.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAOzD,MAAM,WAAW,qBAAqB;IACpC,8EAA8E;IAC9E,QAAQ,CAAC,UAAU,EAAE,MAAM,CAAC;IAC5B;;;;OAIG;IACH,QAAQ,CAAC,OAAO,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC9D,uEAAuE;IACvE,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C;;;;OAIG;IACH,QAAQ,CAAC,sBAAsB,CAAC,EAAE,MAAM,CAAC;CAC1C;AAED;;;;;;;;;;GAUG;AACH,qBAAa,cAAc;IAQb,OAAO,CAAC,QAAQ,CAAC,OAAO;IAPpC,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAqB;IAC7C,OAAO,CAAC,KAAK,CAA+B;IAC5C,OAAO,CAAC,OAAO,CAAS;IACxB,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,mBAAmB,CAAK;IAChC,OAAO,CAAC,QAAQ,CAAC,sBAAsB,CAAS;gBAEnB,OAAO,EAAE,qBAAqB;IAI3D,4DAA4D;IAC5D,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAM1B,8EAA8E;IAC9E,KAAK,IAAI,IAAI;IAQb,OAAO,CAAC,QAAQ;YAQF,GAAG;CA4BlB;AAMD,MAAM,WAAW,eAAe;IAC9B,6BAA6B;IAC7B,QAAQ,CAAC,WAAW,EAAE,MAAM,CAAC;IAC7B,8EAA8E;IAC9E,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,qDAAqD;IACrD,QAAQ,CAAC,UAAU,EAAE,SAAS,MAAM,EAAE,CAAC;IACvC,yEAAyE;IACzE,QAAQ,CAAC,cAAc,EAAE,SAAS,MAAM,EAAE,CAAC;CAC5C;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,MAAM,EAAE,eAAe,EAAE,OAAO,EAAE,MAAM,GAAG,OAAO,CAMjF;AAMD,MAAM,WAAW,WAAW;IAC1B,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CACxB;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,CAAC,KAAK,EAAE,SAAS,MAAM,EAAE,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;IAC/D,QAAQ,CAAC,MAAM,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;IAC3C,oDAAoD;IACpD,QAAQ,CAAC,UAAU,CAAC,EAAE,MAAM,CAAC;CAC9B;AAED;;;;GAIG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,qBAAqB,GAAG,WAAW,CAgD1E"}
+{"version":3,"file":"watcher.d.ts","sourceRoot":"","sources":["../../src/indexer/watcher.ts"],"names":[],"mappings":"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"}

package/dist/indexer/watcher.js

@@ -1,4 +1,5 @@
-import { extname, relative, resolve } from 'node:path';
+import { readdir } from 'node:fs/promises';
+import { extname, join, relative, resolve } from 'node:path';
 import { watch as chokidarWatch } from 'chokidar';
 import { globToRegex } from './walker.js';
 /**
@@ -93,6 +94,102 @@ export function shouldWatchPath(filter, absPath) {
         return false;
     return !filter.excludeRegexes.some((rx) => rx.test(rel));
 }
+function isInsideRoot(projectRoot, directory) {
+    const rel = relative(projectRoot, directory);
+    return rel === '' || (!rel.startsWith('..') && !rel.startsWith('/'));
+}
+/**
+ * Finds what is on disk but unknown to the watcher (D067). Pure over its inputs:
+ * `watched` is a snapshot and `listDirectory` is the only I/O.
+ *
+ * Only directories at or under `projectRoot` are listed: chokidar records the root
+ * itself as a child of the root's parent, and that parent is not ours to scan.
+ * A file the watcher learns about between the snapshot and the listing is reported
+ * too; that is a redundant notification, which the incremental reindex absorbs.
+ * Symbolic links are listed as files and never followed, so a link cycle cannot loop.
+ */
+export async function findUnwatchedEntries(input) {
+    const files = [];
+    const directories = [];
+    const roots = [];
+    const failures = [];
+    const list = async (directory) => {
+        try {
+            return await input.listDirectory(directory);
+        }
+        catch (error) {
+            failures.push({ directory, error });
+            return [];
+        }
+    };
+    // Everything below an unknown directory is unknown too, so it is walked in full.
+    const walkUnknown = async (directory) => {
+        if (input.signal?.aborted === true)
+            return;
+        for (const entry of await list(directory)) {
+            const abs = join(directory, entry.name);
+            if (input.isIgnored(abs))
+                continue;
+            if (entry.isDirectory) {
+                directories.push(abs);
+                await walkUnknown(abs);
+            }
+            else {
+                files.push(abs);
+            }
+        }
+    };
+    for (const [directory, children] of Object.entries(input.watched)) {
+        if (input.signal?.aborted === true)
+            break;
+        if (!isInsideRoot(input.projectRoot, directory))
+            continue;
+        const known = new Set(children);
+        for (const entry of await list(directory)) {
+            if (known.has(entry.name))
+                continue;
+            const abs = join(directory, entry.name);
+            if (input.isIgnored(abs))
+                continue;
+            roots.push(abs);
+            if (entry.isDirectory) {
+                directories.push(abs);
+                await walkUnknown(abs);
+            }
+            else {
+                files.push(abs);
+            }
+        }
+    }
+    return { files, directories, roots, failures };
+}
+async function listDirectoryOnDisk(directory) {
+    const entries = await readdir(directory, { withFileTypes: true });
+    return entries.map((e) => ({ name: e.name, isDirectory: e.isDirectory() }));
+}
+/** Resolves true after `ms`, or false at once if `signal` aborts first. */
+function delay(ms, signal) {
+    return new Promise((resolve) => {
+        if (signal.aborted) {
+            resolve(false);
+            return;
+        }
+        const timer = setTimeout(() => { signal.removeEventListener('abort', onAbort); resolve(true); }, ms);
+        const onAbort = () => { clearTimeout(timer); resolve(false); };
+        signal.addEventListener('abort', onAbort, { once: true });
+    });
+}
+const defaultWatcherFactory = (root, opts) => {
+    const fsw = chokidarWatch(root, opts);
+    return {
+        onFileEvent: (event, listener) => { fsw.on(event, listener); },
+        onReady: (listener) => { fsw.on('ready', listener); },
+        onError: (listener) => { fsw.on('error', listener); },
+        getWatched: () => fsw.getWatched(),
+        add: (paths) => fsw.add([...paths]),
+        close: () => fsw.close(),
+    };
+};
 /**
  * Start `--watch` mode: a chokidar watcher over the project feeding the
  * debounced scheduler. May throw on construction (e.g. EMFILE) — callers must
@@ -111,38 +208,94 @@ export function startWatchMode(options) {
         onBatch: options.runBatch,
         onWarn: options.onWarn,
     });
-    const watcher = chokidarWatch(config.resolved_project_root, {
+    // Prune ignored subtrees at the directory level so chokidar never descends
+    // into node_modules/ or the state dir. Files are re-checked (with the
+    // extension allowlist) in shouldWatchPath; `rel + '/'` lets patterns like
+    // `**/node_modules/**` match the directory itself, not just its contents.
+    // Shared with reconciliation so both agree on what is out of scope.
+    const isIgnored = (path) => {
+        const abs = resolve(path);
+        if (abs === filter.stateDir || abs.startsWith(`${filter.stateDir}/`))
+            return true;
+        const rel = relative(filter.projectRoot, abs);
+        if (rel === '' || rel.startsWith('..'))
+            return false;
+        return filter.excludeRegexes.some((rx) => rx.test(rel) || rx.test(`${rel}/`));
+    };
+    const watcher = (options.watcherFactory ?? defaultWatcherFactory)(config.resolved_project_root, {
         // The startup ladder already reindexed — only future changes matter.
         ignoreInitial: true,
-        // Prune ignored subtrees at the directory level so chokidar never descends
-        // into node_modules/ or the state dir. Files are re-checked (with the
-        // extension allowlist) in shouldWatchPath; `rel + '/'` lets patterns like
-        // `**/node_modules/**` match the directory itself, not just its contents.
-        ignored: (path) => {
-            const abs = resolve(path);
-            if (abs === filter.stateDir || abs.startsWith(`${filter.stateDir}/`))
-                return true;
-            const rel = relative(filter.projectRoot, abs);
-            if (rel === '' || rel.startsWith('..'))
-                return false;
-            return filter.excludeRegexes.some((rx) => rx.test(rel) || rx.test(`${rel}/`));
-        },
+        ignored: isIgnored,
     });
+    // Aborted by `close()`; cancels the settle wait and the reconciliation walk.
+    const closing = new AbortController();
+    const reconcile = async () => {
+        let found;
+        try {
+            found = await findUnwatchedEntries({
+                watched: watcher.getWatched(),
+                projectRoot: filter.projectRoot,
+                listDirectory: listDirectoryOnDisk,
+                isIgnored,
+                signal: closing.signal,
+            });
+        }
+        catch (err) {
+            options.onWarn(`[mast] watch: reconciliation failed (continuing): ${String(err)}`);
+            return;
+        }
+        if (closing.signal.aborted)
+            return;
+        for (const failure of found.failures) {
+            options.onWarn(`[mast] watch: reconciliation could not list ${failure.directory} (continuing): ${String(failure.error)}`);
+        }
+        for (const file of found.files) {
+            if (shouldWatchPath(filter, file))
+                scheduler.notify(file);
+        }
+        // `add` under `ignoreInitial: true` emits no `add` events (chokidar handler.js:
+        // `_addToNodeFs(path, !_internal, ...)` makes this an initial add), so the files
+        // notified above are not delivered twice. It is what makes later changes inside
+        // a missed directory visible.
+        if (found.roots.length > 0)
+            watcher.add(found.roots);
+    };
+    const announceReadiness = async () => {
+        if (!(await delay(options.settleMs ?? 1000, closing.signal)))
+            return;
+        await reconcile();
+        if (closing.signal.aborted)
+            return;
+        options.onReady?.();
+    };
     // `unlink` feeds the same incremental run: deleted files are cleaned up by
     // the index run's manifest diff (removeDeletedFiles), not reimplemented here.
-    watcher.on('add', (path) => { if (shouldWatchPath(filter, resolve(path)))
+    watcher.onFileEvent('add', (path) => { if (shouldWatchPath(filter, resolve(path)))
         scheduler.notify(path); });
-    watcher.on('change', (path) => { if (shouldWatchPath(filter, resolve(path)))
+    watcher.onFileEvent('change', (path) => { if (shouldWatchPath(filter, resolve(path)))
         scheduler.notify(path); });
-    watcher.on('unlink', (path) => { if (shouldWatchPath(filter, resolve(path)))
+    watcher.onFileEvent('unlink', (path) => { if (shouldWatchPath(filter, resolve(path)))
         scheduler.notify(path); });
-    watcher.on('error', (err) => {
+    // chokidar's `ready` only says its initial scan finished; the OS watch may not be
+    // delivering yet, and a file created in that gap fires no event (D067). So
+    // readiness is announced after a settle period and a reconciliation pass, see
+    // `onReady`. A construction failure (EMFILE, permissions) throws out of the
+    // factory above and never reaches this line, so `onReady` cannot announce a
+    // watcher that failed to start. A runtime `error` after a successful scan does
+    // not un-fire it: the signal is not "the watcher is healthy".
+    watcher.onReady(() => {
+        announceReadiness().catch((err) => {
+            options.onWarn(`[mast] watch: readiness announcement failed: ${String(err)}`);
+        });
+    });
+    watcher.onError((err) => {
         // Watcher errors (EMFILE, EPERM, …) degrade to no-watch; JIT staleness
         // handling keeps reads correct, so serving continues.
         options.onWarn(`[mast] watch: watcher error (continuing without event): ${String(err)}`);
     });
     return {
         close: async () => {
+            closing.abort();
             scheduler.close();
             await watcher.close();
         },

package/dist/indexer/watcher.js.map

@@ -1 +1 @@
-{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../src/indexer/watcher.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"watcher.js","sourceRoot":"","sources":["../../src/indexer/watcher.ts"],"names":[],"mappings":"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"}

package/dist/mcp/context.d.ts

@@ -1,6 +1,7 @@
 import type { Db } from '../graph/db.js';
 import type { ChunkStore } from '../store/sqliteChunkStore.js';
 import type { ResolvedConfig } from '../store/config.js';
+import type { FreshnessProbe } from './freshness-probe.js';
 /**
  * Shared state injected into every MCP tool handler at registration time.
  *
@@ -19,5 +20,20 @@ export interface AppContext {
     readonly config: ResolvedConfig;
     /** Stable identifier for this MCP server session (used in metrics). */
     readonly sessionId: string;
+    /**
+     * Cached "is the index missing files?" signal, read by `mast_search` to warn
+     * that a result set may be incomplete.
+     *
+     * Optional, and absent is a real configuration rather than an oversight: the
+     * probe amortises one project walk across a TTL, which only pays off in a
+     * long-lived process. `mast serve` wires one (mcp/server.ts); the one-shot
+     * CLI query path (cli/query.ts) deliberately does not, because a single
+     * search there would pay the whole walk to answer a question it can answer
+     * outright with `mast search --reindex`.
+     *
+     * Absent, or reporting `null`, means *unknown* — surfaces render that as
+     * silence, never as zero.
+     */
+    readonly freshness?: FreshnessProbe;
 }
 //# sourceMappingURL=context.d.ts.map

package/dist/mcp/context.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/mcp/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAMzD;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;CAC5B"}
+{"version":3,"file":"context.d.ts","sourceRoot":"","sources":["../../src/mcp/context.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,8BAA8B,CAAC;AAC/D,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAM3D;;;;;;GAMG;AACH,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,EAAE,EAAE,EAAE,CAAC;IAChB;;;;OAIG;IACH,QAAQ,CAAC,UAAU,EAAE,UAAU,CAAC;IAChC,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,uEAAuE;IACvE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B;;;;;;;;;;;;;OAaG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,cAAc,CAAC;CACrC"}

package/dist/mcp/freshness-probe.d.ts

@@ -0,0 +1,82 @@
+/**
+ * A cached, non-blocking answer to "is the index missing files?".
+ *
+ * `mast_search` needs this to warn a caller that a zero-hit result may mean
+ * "not indexed" rather than "not present" — the severity-zero failure this
+ * package is built around. What it cannot do is pay for it *at scale*, and the
+ * cost is worth stating with its corpus attached, because it inverts:
+ *
+ *   - This repository, 213 files walked (medians, measured 2026-09-03):
+ *     `fusedSearch` 15.3 ms, `measureFreshness` 7.6 ms. The walk is CHEAPER
+ *     than the search. On a tree this size the probe buys nothing.
+ *   - A 14k-file monorepo: `measureFreshness` ~183 ms (measured 2026-09-02).
+ *
+ * That is the whole argument, and it is about scaling, not about a ratio.
+ * `measureFreshness` is O(files in the tree) and a search is O(matches), so the
+ * walk overtakes the query as the tree grows and then keeps going. The probe
+ * exists for the trees where that has already happened.
+ *
+ * So the probe inverts it. `peekUnindexed` returns the last-known count
+ * synchronously and schedules a refresh behind the caller when the value has
+ * aged past the TTL. The first search of a session gets `null` — unknown, no
+ * warning — and every later one gets an answer that is at most `ttlMs` old.
+ * `server.ts` primes it at startup so that window is usually already closed.
+ *
+ * The cost is amortised, NOT eliminated, and it is worth being exact about
+ * which: `measureFreshness` -> `walkProject` globs asynchronously but then
+ * `statSync`s every hit in a synchronous loop, so a refresh occupies the event
+ * loop for part of its duration. A search that lands mid-refresh can be
+ * delayed by that much. One such window per `ttlMs`, rather than one walk per
+ * search, is the whole of the improvement — do not read "background" as
+ * "free".
+ *
+ * Deliberately NOT a reindex: no `structure.lock` is taken and nothing is
+ * written, so the probe cannot contend with a concurrent `runIndex` or with
+ * another reader (E7 measured 35-88.5% JIT failure under reader-vs-reader
+ * contention). It reads, it counts, it reports.
+ */
+import type { Db } from '../graph/db.js';
+import type { ResolvedConfig } from '../store/config.js';
+import { type IndexFreshness } from '../indexer/freshness.js';
+/** How long a measurement stays authoritative before the next peek refreshes it. */
+export declare const DEFAULT_FRESHNESS_TTL_MS = 30000;
+export interface FreshnessProbe {
+    /**
+     * Files on disk that the index has never seen, as of the last completed
+     * measurement — or `null` when none has completed yet.
+     *
+     * Never blocks, never throws, never awaits. May schedule a background
+     * refresh as a side effect. `null` means *unknown*, which callers must
+     * render as silence rather than as zero.
+     */
+    peekUnindexed(): number | null;
+    /**
+     * Discard the cached value and re-measure on the next peek.
+     *
+     * Called after this process reindexes: the previous count is not merely old,
+     * it is wrong in the direction that produces a false warning about files
+     * that were just indexed. A measurement already in flight is *superseded* —
+     * it is allowed to finish, and its result is discarded rather than cached,
+     * because it was reading the pre-reindex tree.
+     */
+    invalidate(): void;
+    /** Start a measurement now if none is in flight. Used to prime at startup. */
+    refresh(): void;
+    /**
+     * Resolves when the in-flight measurement settles — success or failure.
+     *
+     * Settling is not the same as caching a value: a measurement superseded by
+     * `invalidate()` settles with its result discarded, leaving `peekUnindexed`
+     * at `null` until the next peek starts a clean one.
+     */
+    settled(): Promise<void>;
+}
+export interface FreshnessProbeOptions {
+    readonly ttlMs?: number;
+    /** Injected for tests (§4.4); production reads the real clock. */
+    readonly now?: () => number;
+    /** Injected for tests (§4.4); production walks the project. */
+    readonly measure?: (config: ResolvedConfig, db: Db) => Promise<IndexFreshness>;
+}
+export declare function createFreshnessProbe(config: ResolvedConfig, db: Db, options?: FreshnessProbeOptions): FreshnessProbe;
+//# sourceMappingURL=freshness-probe.d.ts.map

package/dist/mcp/freshness-probe.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness-probe.d.ts","sourceRoot":"","sources":["../../src/mcp/freshness-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAEH,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,gBAAgB,CAAC;AACzC,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AACzD,OAAO,EAAoB,KAAK,cAAc,EAAE,MAAM,yBAAyB,CAAC;AAEhF,oFAAoF;AACpF,eAAO,MAAM,wBAAwB,QAAS,CAAC;AAE/C,MAAM,WAAW,cAAc;IAC7B;;;;;;;OAOG;IACH,aAAa,IAAI,MAAM,GAAG,IAAI,CAAC;IAE/B;;;;;;;;OAQG;IACH,UAAU,IAAI,IAAI,CAAC;IAEnB,8EAA8E;IAC9E,OAAO,IAAI,IAAI,CAAC;IAEhB;;;;;;OAMG;IACH,OAAO,IAAI,OAAO,CAAC,IAAI,CAAC,CAAC;CAC1B;AAED,MAAM,WAAW,qBAAqB;IACpC,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,kEAAkE;IAClE,QAAQ,CAAC,GAAG,CAAC,EAAE,MAAM,MAAM,CAAC;IAC5B,+DAA+D;IAC/D,QAAQ,CAAC,OAAO,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,EAAE,EAAE,EAAE,KAAK,OAAO,CAAC,cAAc,CAAC,CAAC;CAChF;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,cAAc,EACtB,EAAE,EAAE,EAAE,EACN,OAAO,GAAE,qBAA0B,GAClC,cAAc,CAuEhB"}

package/dist/mcp/freshness-probe.js

@@ -0,0 +1,111 @@
+/**
+ * A cached, non-blocking answer to "is the index missing files?".
+ *
+ * `mast_search` needs this to warn a caller that a zero-hit result may mean
+ * "not indexed" rather than "not present" — the severity-zero failure this
+ * package is built around. What it cannot do is pay for it *at scale*, and the
+ * cost is worth stating with its corpus attached, because it inverts:
+ *
+ *   - This repository, 213 files walked (medians, measured 2026-09-03):
+ *     `fusedSearch` 15.3 ms, `measureFreshness` 7.6 ms. The walk is CHEAPER
+ *     than the search. On a tree this size the probe buys nothing.
+ *   - A 14k-file monorepo: `measureFreshness` ~183 ms (measured 2026-09-02).
+ *
+ * That is the whole argument, and it is about scaling, not about a ratio.
+ * `measureFreshness` is O(files in the tree) and a search is O(matches), so the
+ * walk overtakes the query as the tree grows and then keeps going. The probe
+ * exists for the trees where that has already happened.
+ *
+ * So the probe inverts it. `peekUnindexed` returns the last-known count
+ * synchronously and schedules a refresh behind the caller when the value has
+ * aged past the TTL. The first search of a session gets `null` — unknown, no
+ * warning — and every later one gets an answer that is at most `ttlMs` old.
+ * `server.ts` primes it at startup so that window is usually already closed.
+ *
+ * The cost is amortised, NOT eliminated, and it is worth being exact about
+ * which: `measureFreshness` -> `walkProject` globs asynchronously but then
+ * `statSync`s every hit in a synchronous loop, so a refresh occupies the event
+ * loop for part of its duration. A search that lands mid-refresh can be
+ * delayed by that much. One such window per `ttlMs`, rather than one walk per
+ * search, is the whole of the improvement — do not read "background" as
+ * "free".
+ *
+ * Deliberately NOT a reindex: no `structure.lock` is taken and nothing is
+ * written, so the probe cannot contend with a concurrent `runIndex` or with
+ * another reader (E7 measured 35-88.5% JIT failure under reader-vs-reader
+ * contention). It reads, it counts, it reports.
+ */
+import { measureFreshness } from '../indexer/freshness.js';
+/** How long a measurement stays authoritative before the next peek refreshes it. */
+export const DEFAULT_FRESHNESS_TTL_MS = 30_000;
+export function createFreshnessProbe(config, db, options = {}) {
+    const ttlMs = options.ttlMs ?? DEFAULT_FRESHNESS_TTL_MS;
+    const now = options.now ?? Date.now;
+    const measure = options.measure ?? measureFreshness;
+    let unindexed = null;
+    /** `null` = never measured or invalidated; otherwise the clock at settlement. */
+    let settledAt = null;
+    let inFlight = null;
+    /**
+     * Bumped by `invalidate()`. A measurement that started under an older
+     * generation was reading a tree this process has since reindexed, so its
+     * count is not merely old — it is wrong in the exact direction that warns
+     * about files that now ARE indexed. Gating on the generation is what makes
+     * `invalidate()` mean "discard", rather than "discard unless a walk happens
+     * to be in flight, in which case adopt its stale answer and stamp it fresh
+     * for a full TTL".
+     */
+    let generation = 0;
+    function refresh() {
+        // Still coalesced across generations: a superseded walk is left to finish
+        // and its result dropped, rather than disowned and replaced immediately.
+        // Disowning would let one walk per `invalidate()` run concurrently, and
+        // `measureFreshness` holds the event loop in a synchronous `statSync` loop
+        // (see the header) — under a watch-driven edit loop that is worse than the
+        // laziness. The cache is left `null` (unknown -> silence, never a wrong
+        // warning) and the next peek starts a clean measurement.
+        if (inFlight !== null)
+            return;
+        const startedAt = generation;
+        inFlight = measure(config, db)
+            .then((result) => {
+            if (startedAt !== generation)
+                return;
+            unindexed = result.unindexed;
+        })
+            .catch(() => {
+            // Swallowed by contract: a failed walk (a directory removed mid-walk, a
+            // permission error) must not reject into a search handler or replace a
+            // good answer with a wrong one. The last value stands and the stamp
+            // below backs the retry off by a full TTL rather than re-walking on
+            // every peek.
+        })
+            .finally(() => {
+            inFlight = null;
+            // A superseded walk must NOT stamp the cache fresh. Leaving `settledAt`
+            // null keeps the value expired, so the next peek re-measures instead of
+            // serving `null` for a full TTL.
+            if (startedAt !== generation)
+                return;
+            settledAt = now();
+        });
+    }
+    return {
+        peekUnindexed() {
+            const isExpired = settledAt === null || now() - settledAt >= ttlMs;
+            if (isExpired)
+                refresh();
+            return unindexed;
+        },
+        invalidate() {
+            unindexed = null;
+            settledAt = null;
+            generation += 1;
+        },
+        refresh,
+        async settled() {
+            await inFlight;
+        },
+    };
+}
+//# sourceMappingURL=freshness-probe.js.map

package/dist/mcp/freshness-probe.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"freshness-probe.js","sourceRoot":"","sources":["../../src/mcp/freshness-probe.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;GAoCG;AAIH,OAAO,EAAE,gBAAgB,EAAuB,MAAM,yBAAyB,CAAC;AAEhF,oFAAoF;AACpF,MAAM,CAAC,MAAM,wBAAwB,GAAG,MAAM,CAAC;AA6C/C,MAAM,UAAU,oBAAoB,CAClC,MAAsB,EACtB,EAAM,EACN,UAAiC,EAAE;IAEnC,MAAM,KAAK,GAAG,OAAO,CAAC,KAAK,IAAI,wBAAwB,CAAC;IACxD,MAAM,GAAG,GAAG,OAAO,CAAC,GAAG,IAAI,IAAI,CAAC,GAAG,CAAC;IACpC,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,IAAI,gBAAgB,CAAC;IAEpD,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,iFAAiF;IACjF,IAAI,SAAS,GAAkB,IAAI,CAAC;IACpC,IAAI,QAAQ,GAAyB,IAAI,CAAC;IAC1C;;;;;;;;OAQG;IACH,IAAI,UAAU,GAAG,CAAC,CAAC;IAEnB,SAAS,OAAO;QACd,0EAA0E;QAC1E,yEAAyE;QACzE,wEAAwE;QACxE,2EAA2E;QAC3E,2EAA2E;QAC3E,wEAAwE;QACxE,yDAAyD;QACzD,IAAI,QAAQ,KAAK,IAAI;YAAE,OAAO;QAC9B,MAAM,SAAS,GAAG,UAAU,CAAC;QAC7B,QAAQ,GAAG,OAAO,CAAC,MAAM,EAAE,EAAE,CAAC;aAC3B,IAAI,CAAC,CAAC,MAAM,EAAE,EAAE;YACf,IAAI,SAAS,KAAK,UAAU;gBAAE,OAAO;YACrC,SAAS,GAAG,MAAM,CAAC,SAAS,CAAC;QAC/B,CAAC,CAAC;aACD,KAAK,CAAC,GAAG,EAAE;YACV,wEAAwE;YACxE,uEAAuE;YACvE,oEAAoE;YACpE,oEAAoE;YACpE,cAAc;QAChB,CAAC,CAAC;aACD,OAAO,CAAC,GAAG,EAAE;YACZ,QAAQ,GAAG,IAAI,CAAC;YAChB,wEAAwE;YACxE,wEAAwE;YACxE,iCAAiC;YACjC,IAAI,SAAS,KAAK,UAAU;gBAAE,OAAO;YACrC,SAAS,GAAG,GAAG,EAAE,CAAC;QACpB,CAAC,CAAC,CAAC;IACP,CAAC;IAED,OAAO;QACL,aAAa;YACX,MAAM,SAAS,GAAG,SAAS,KAAK,IAAI,IAAI,GAAG,EAAE,GAAG,SAAS,IAAI,KAAK,CAAC;YACnE,IAAI,SAAS;gBAAE,OAAO,EAAE,CAAC;YACzB,OAAO,SAAS,CAAC;QACnB,CAAC;QAED,UAAU;YACR,SAAS,GAAG,IAAI,CAAC;YACjB,SAAS,GAAG,IAAI,CAAC;YACjB,UAAU,IAAI,CAAC,CAAC;QAClB,CAAC;QAED,OAAO;QAEP,KAAK,CAAC,OAAO;YACX,MAAM,QAAQ,CAAC;QACjB,CAAC;KACF,CAAC;AACJ,CAAC"}

package/dist/mcp/instructions.d.ts

@@ -0,0 +1,7 @@
+/**
+ * The MCP `instructions` string sent in the `initialize` result (ADR 017 §6).
+ * One paragraph: a client may place it in the model's context verbatim, so every
+ * sentence has to earn its tokens.
+ */
+export declare const SERVER_INSTRUCTIONS: string;
+//# sourceMappingURL=instructions.d.ts.map

package/dist/mcp/instructions.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.d.ts","sourceRoot":"","sources":["../../src/mcp/instructions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,eAAO,MAAM,mBAAmB,QAI2H,CAAC"}

package/dist/mcp/instructions.js

@@ -0,0 +1,10 @@
+/**
+ * The MCP `instructions` string sent in the `initialize` result (ADR 017 §6).
+ * One paragraph: a client may place it in the model's context verbatim, so every
+ * sentence has to earn its tokens.
+ */
+export const SERVER_INSTRUCTIONS = 'mast is an AST-level index of this repository\'s TypeScript, JavaScript and Markdown. ' +
+    'To find code — a symbol, its callers, a module\'s exports — call mast_search (or mast_signature, mast_callers, mast_exports) before using grep, glob or reading whole files: it returns ranked declarations, not line matches. ' +
+    'Use grep for other languages, non-code files, or an exact regex over text. ' +
+    'An empty result is not proof of absence: check index_empty and unindexed_files on the response, and call mast_reindex after creating or renaming files.';
+//# sourceMappingURL=instructions.js.map

package/dist/mcp/instructions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"instructions.js","sourceRoot":"","sources":["../../src/mcp/instructions.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AACH,MAAM,CAAC,MAAM,mBAAmB,GAC9B,wFAAwF;IACxF,iOAAiO;IACjO,6EAA6E;IAC7E,yJAAyJ,CAAC"}