@spikedpunch/mast 0.1.0 → 0.3.0

package/dist/indexer/watcher.js

@@ -136,6 +136,14 @@ export function startWatchMode(options) {
         scheduler.notify(path); });
     watcher.on('unlink', (path) => { if (shouldWatchPath(filter, resolve(path)))
         scheduler.notify(path); });
+    // Fires after the initial scan completes; from here on, a created file
+    // produces an `add`. A construction failure (EMFILE, permissions) throws out
+    // of `chokidarWatch` above and never reaches this line, so `onReady` cannot
+    // announce a watcher that failed to start — the caller's catch handles that
+    // case. Handler registration order is NOT what provides that guarantee, and a
+    // runtime `error` after a successful scan does not un-fire `ready`: this
+    // signal means "the initial scan finished", not "the watcher is healthy".
+    watcher.on('ready', () => { options.onReady?.(); });
     watcher.on('error', (err) => {
         // Watcher errors (EMFILE, EPERM, …) degrade to no-watch; JIT staleness
         // handling keeps reads correct, so serving continues.

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/server.d.ts

@@ -1,4 +1,5 @@
 import type { ResolvedConfig } from '../store/config.js';
+import { type FreshnessProbe } from './freshness-probe.js';
 /**
  * Thrown by {@link assertServableIndex} when `mast serve --no-startup-reindex`
  * targets a state directory that has never completed an index run. Extends
@@ -33,14 +34,56 @@ export declare class NeverIndexedError extends Error {
 export declare function assertServableIndex(config: ResolvedConfig, options: {
     readonly noStartupReindex?: boolean;
 }): void;
+/**
+ * Run an incremental/full index pass and then correct the cached freshness
+ * count, which that pass has just made wrong.
+ *
+ * Extracted from `serve` because the ordering here is the whole contract and it
+ * was previously expressed three times in three closures, one of which got it
+ * wrong (D060): the invalidate must be in a `finally`. A reindex that FAILS is
+ * the case where the cached count is most likely to be stale and most costly to
+ * keep — the watcher only fired because files on disk changed, and `runIndex`
+ * losing `structure.lock` to a concurrent writer is an ordinary outcome, not an
+ * exceptional one. Invalidating only on success leaves `mast_search` reporting
+ * a pre-change count as authoritative for a full TTL, and after
+ * `maxConsecutiveFailures` the watcher drops the batch, so nothing retries.
+ *
+ * Errors propagate deliberately. `WatchScheduler` needs the rejection to
+ * requeue the batch, and the startup path wants to warn on its own terms; a
+ * function that both corrects the cache and swallows the failure would give
+ * neither caller what it needs.
+ *
+ * @param prime `true` measures immediately (startup, so the first search of the
+ *   session has a real answer instead of `null`); `false` leaves the next
+ *   `peekUnindexed` to schedule it, which is right for a watch batch that may
+ *   be one of many in a burst.
+ */
+export declare function reindexAndRemeasure(config: ResolvedConfig, freshness: FreshnessProbe, options: {
+    readonly incremental: boolean;
+    readonly prime?: boolean;
+    /** §4.4 DI seam: tests drive the failure path without standing up a writer. */
+    readonly runIndexFn?: (config: ResolvedConfig, opts: {
+        incremental: boolean;
+    }) => Promise<unknown>;
+}): Promise<void>;
 export interface ServeOptions {
     readonly config: ResolvedConfig;
     /** Skip the startup incremental reindex (not recommended). */
     readonly noStartupReindex?: boolean;
     /**
-     * Watch source files and incrementally reindex on change (§11.4). Opt-in,
-     * for interactive (non-container) use — the SDD container relies on the
-     * startup ladder instead.
+     * Watch source files and incrementally reindex on change (§11.4).
+     *
+     * **Defaults to on** (`undefined` means watch). It was opt-in until
+     * 2026-09-03, on the theory that the startup ladder plus JIT staleness kept
+     * reads correct. Measurement said otherwise: JIT only re-parses files the
+     * index already knows, so a file CREATED during a session is invisible to
+     * every read tool until something reindexes — and nothing does. A watcher is
+     * the only mechanism here that closes that window without a per-query cost.
+     * Watcher construction failures degrade to serving without it, so the
+     * default cannot make the server fail to start.
+     *
+     * Set `false` (CLI `--no-watch`) for container or batch use, where the tree
+     * does not change under the server and the fd cost is not worth paying.
      */
     readonly watch?: boolean;
 }

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

@@ -1 +1 @@
-{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAczD;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAiC/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE;IAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/C,IAAI,CASN;AAMD,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC;;;;OAIG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CA2FhE"}
+{"version":3,"file":"server.d.ts","sourceRoot":"","sources":["../../src/mcp/server.ts"],"names":[],"mappings":"AAKA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,oBAAoB,CAAC;AAOzD,OAAO,EAAwB,KAAK,cAAc,EAAE,MAAM,sBAAsB,CAAC;AAQjF;;;;;;GAMG;AACH,qBAAa,iBAAkB,SAAQ,KAAK;CAAG;AAiC/C;;;;;;;;;;;;;;;;;;;;;GAqBG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,cAAc,EACtB,OAAO,EAAE;IAAE,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAA;CAAE,GAC/C,IAAI,CASN;AAMD;;;;;;;;;;;;;;;;;;;;;;;GAuBG;AACH,wBAAsB,mBAAmB,CACvC,MAAM,EAAE,cAAc,EACtB,SAAS,EAAE,cAAc,EACzB,OAAO,EAAE;IACP,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;IACzB,+EAA+E;IAC/E,QAAQ,CAAC,UAAU,CAAC,EAAE,CAAC,MAAM,EAAE,cAAc,EAAE,IAAI,EAAE;QAAE,WAAW,EAAE,OAAO,CAAA;KAAE,KAAK,OAAO,CAAC,OAAO,CAAC,CAAC;CACpG,GACA,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,cAAc,CAAC;IAChC,8DAA8D;IAC9D,QAAQ,CAAC,gBAAgB,CAAC,EAAE,OAAO,CAAC;IACpC;;;;;;;;;;;;;;OAcG;IACH,QAAQ,CAAC,KAAK,CAAC,EAAE,OAAO,CAAC;CAC1B;AAED;;;;;;;;;GASG;AACH,wBAAsB,KAAK,CAAC,OAAO,EAAE,YAAY,GAAG,OAAO,CAAC,IAAI,CAAC,CAmHhE"}

package/dist/mcp/server.js

@@ -8,6 +8,7 @@ import { SqliteChunkStore } from '../store/sqliteChunkStore.js';
 import { runIndex, loadIndexMeta } from '../indexer/index.js';
 import { startWatchMode } from '../indexer/watcher.js';
 import { bootstrapState } from './startup.js';
+import { createFreshnessProbe } from './freshness-probe.js';
 import { registerAllTools } from './register-tools.js';
 // ---------------------------------------------------------------------------
 // M6 Part A (eval/GITNEXUS_COMPARISON.md §13.8 item 4): refuse to serve only
@@ -85,6 +86,44 @@ export function assertServableIndex(config, options) {
         'query would return {"results":[]} forever, indistinguishable from "symbol doesn\'t exist". ' +
         'Run `mast init` or `mast index` against this state directory first, or drop --no-startup-reindex.');
 }
+// ---------------------------------------------------------------------------
+// Startup ladder (§7.4)
+// ---------------------------------------------------------------------------
+/**
+ * Run an incremental/full index pass and then correct the cached freshness
+ * count, which that pass has just made wrong.
+ *
+ * Extracted from `serve` because the ordering here is the whole contract and it
+ * was previously expressed three times in three closures, one of which got it
+ * wrong (D060): the invalidate must be in a `finally`. A reindex that FAILS is
+ * the case where the cached count is most likely to be stale and most costly to
+ * keep — the watcher only fired because files on disk changed, and `runIndex`
+ * losing `structure.lock` to a concurrent writer is an ordinary outcome, not an
+ * exceptional one. Invalidating only on success leaves `mast_search` reporting
+ * a pre-change count as authoritative for a full TTL, and after
+ * `maxConsecutiveFailures` the watcher drops the batch, so nothing retries.
+ *
+ * Errors propagate deliberately. `WatchScheduler` needs the rejection to
+ * requeue the batch, and the startup path wants to warn on its own terms; a
+ * function that both corrects the cache and swallows the failure would give
+ * neither caller what it needs.
+ *
+ * @param prime `true` measures immediately (startup, so the first search of the
+ *   session has a real answer instead of `null`); `false` leaves the next
+ *   `peekUnindexed` to schedule it, which is right for a watch batch that may
+ *   be one of many in a burst.
+ */
+export async function reindexAndRemeasure(config, freshness, options) {
+    const run = options.runIndexFn ?? runIndex;
+    try {
+        await run(config, { incremental: options.incremental });
+    }
+    finally {
+        freshness.invalidate();
+        if (options.prime === true)
+            freshness.refresh();
+    }
+}
 /**
  * Run the MAST MCP server.
  *
@@ -112,11 +151,17 @@ export async function serve(options) {
     // tool below already uses.
     const chunkStore = new SqliteChunkStore(db);
     // ── Step 3: open MCP transport and register tools ─────────────────────────
+    // Freshness signal for `mast_search`'s `unindexed_files` warning. Created
+    // before the tools are registered because handlers capture `ctx` at
+    // registration; primed below so the first search of a session already has a
+    // real answer rather than `null`.
+    const freshness = createFreshnessProbe(config, db);
     const ctx = {
         db,
         chunkStore,
         config,
         sessionId: randomUUID(),
+        freshness,
     };
     const server = new McpServer({ name: 'mast', version: '0.1.0' });
     registerAllTools(server, ctx);
@@ -128,7 +173,7 @@ export async function serve(options) {
     // mast_reindex). JIT staleness handling (§9.0) already guarantees read
     // correctness; watch mode only keeps the FTS/graph index fresh between reads.
     const startWatchIfRequested = () => {
-        if (options.watch !== true)
+        if (options.watch === false)
             return;
         let watchHandle = null;
         try {
@@ -136,9 +181,19 @@ export async function serve(options) {
                 config,
                 runBatch: async (paths) => {
                     process.stderr.write(`[mast] watch: reindexing after ${paths.length} change(s)\n`);
-                    await runIndex(config, { incremental: true });
+                    // Not primed: a burst of saves produces a burst of batches, and the
+                    // next `peekUnindexed` will schedule one measurement for all of them.
+                    await reindexAndRemeasure(config, freshness, { incremental: true });
                 },
                 onWarn: (message) => process.stderr.write(`${message}\n`),
+                // The success path now announces itself, because the failure path
+                // always did: `startWatchMode`'s EMFILE degradation writes a warning,
+                // so before this line silence meant "watching", "not watching yet" and
+                // "watcher failed to start" alike, and an operator could not tell which
+                // (D061). Emitted once, after chokidar's initial scan — files created
+                // before it are treated as pre-existing and fire no event, so this is
+                // the point from which a change is guaranteed to be seen.
+                onReady: () => process.stderr.write('[mast] watch: watching for changes\n'),
             });
         }
         catch (err) {
@@ -161,12 +216,19 @@ export async function serve(options) {
     };
     // ── Step 4: background reindex ────────────────────────────────────────────
     if (options.noStartupReindex) {
+        // No reindex is coming, so measure the drift the user has chosen to keep.
+        freshness.refresh();
         startWatchIfRequested();
         return;
     }
     void (async () => {
         try {
-            await runIndex(config, { incremental: !needsFullReindex });
+            // Measured AFTER the reindex, in the same background task: a probe run
+            // before it would race the indexer and cache a count that the very next
+            // moment invalidates. On the failure path the correction is the more
+            // important half — the index is behind and nothing else will say so —
+            // which is why it lives in `reindexAndRemeasure`'s `finally`.
+            await reindexAndRemeasure(config, freshness, { incremental: !needsFullReindex, prime: true });
         }
         catch (err) {
             process.stderr.write(`[mast] startup indexing failed: ${String(err)}\n`);

package/dist/mcp/server.js.map

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

package/dist/mcp/tools/_helpers.d.ts

@@ -2,6 +2,8 @@ import type { Db } from '../../graph/db.js';
 import type { ResolvedConfig } from '../../store/config.js';
 import type { AppContext } from '../context.js';
 import { type StalenessCheckResult } from '../staleness.js';
+/** @see {@link DEFAULT_RESULT_LIMIT} — re-exported so every capped tool reads one constant (D043). */
+export { DEFAULT_RESULT_LIMIT } from '../../search/potential-matches.js';
 export { collectPotentialMatches, collectPotentialMatchCandidates, type ChunkByIdSource, type PotentialMatchCandidate, type PotentialMatchCandidatesResult, type PotentialMatchesResult, } from '../../search/potential-matches.js';
 /**
  * True when the `chunks` table has zero rows — i.e. nothing is indexed yet,
@@ -14,6 +16,46 @@ export { collectPotentialMatches, collectPotentialMatchCandidates, type ChunkByI
  * pays nothing extra per call.
  */
 export declare function isIndexEmpty(ctx: AppContext): Promise<boolean>;
+/**
+ * How exhaustive a tool's answer claims to be. This is what decides whether a
+ * partial index is worth mentioning alongside a *non-empty* result, and the two
+ * cases are genuinely different claims rather than a style choice.
+ *
+ * - `exhaustive-set` — the answer is "these are the ones there are"
+ *   (`mast_callers`, `mast_rename_impact`, `mast_implementors`, `mast_search`,
+ *   `mast_project_skeleton`). A **non-empty** answer is the dangerous one here:
+ *   "3 verified callers" computed over a corpus missing forty files is what
+ *   drives a delete, and it reads exactly like a complete answer.
+ * - `named-lookup` — the answer is about one thing the caller named
+ *   (`mast_signature`, `mast_exports`, `mast_dependencies`). If it was found,
+ *   the answer is correct however much else is unindexed; only *not finding* it
+ *   is ambiguous between "absent" and "never indexed".
+ */
+export type CompletenessClaim = 'exhaustive-set' | 'named-lookup';
+/**
+ * The partial-index warning (D054), for every tool that returns a primary
+ * result set — not just `mast_search`, which had it first only because that is
+ * where it was written.
+ *
+ * The severity zero: a caller reads an empty or thin answer, concludes "it
+ * isn't there", and edits or deletes code that is in fact referenced from a
+ * file the index never saw. `index_empty` covers the all-or-nothing case; this
+ * covers the far commoner partial one, where the index is populated and merely
+ * behind.
+ *
+ * Free to call. `peekUnindexed` reads a TTL-cached count synchronously and
+ * never awaits a walk (see `mcp/freshness-probe.ts`), so unlike `isIndexEmpty`
+ * this costs nothing on a populated response and needs no empty-path guard for
+ * performance — only for meaning.
+ *
+ * `null` from the probe means *no measurement has landed yet*, which is
+ * unknown, not zero. Both render as an omitted field, but they are kept
+ * distinct here because the next reader to add a branch would otherwise inherit
+ * "unknown means clean" — the exact conflation this signal exists to prevent.
+ */
+export declare function unindexedFilesField(ctx: AppContext, claim: CompletenessClaim, isEmpty: boolean): {
+    readonly unindexed_files?: number;
+};
 /** Extract the first JSDoc comment block from chunk content, if present. */
 export declare function extractDoc(content: string): string | null;
 export { globToRegex } from '../../indexer/walker.js';

package/dist/mcp/tools/_helpers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"_helpers.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAA0B,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AASpF,OAAO,EACL,uBAAuB,EACvB,+BAA+B,EAC/B,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,GAC5B,MAAM,mCAAmC,CAAC;AAM3C;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAEpE;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGzD;AAID,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,EAAE,EACN,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,oBAAoB,CAAC,CAQ/B"}
+{"version":3,"file":"_helpers.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/_helpers.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,EAAE,EAAE,MAAM,mBAAmB,CAAC;AAC5C,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,uBAAuB,CAAC;AAC5D,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAChD,OAAO,EAA0B,KAAK,oBAAoB,EAAE,MAAM,iBAAiB,CAAC;AAEpF,sGAAsG;AACtG,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AASzE,OAAO,EACL,uBAAuB,EACvB,+BAA+B,EAC/B,KAAK,eAAe,EACpB,KAAK,uBAAuB,EAC5B,KAAK,8BAA8B,EACnC,KAAK,sBAAsB,GAC5B,MAAM,mCAAmC,CAAC;AAM3C;;;;;;;;;GASG;AACH,wBAAsB,YAAY,CAAC,GAAG,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAEpE;AAED;;;;;;;;;;;;;;GAcG;AACH,MAAM,MAAM,iBAAiB,GAAG,gBAAgB,GAAG,cAAc,CAAC;AAElE;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,wBAAgB,mBAAmB,CACjC,GAAG,EAAE,UAAU,EACf,KAAK,EAAE,iBAAiB,EACxB,OAAO,EAAE,OAAO,GACf;IAAE,QAAQ,CAAC,eAAe,CAAC,EAAE,MAAM,CAAA;CAAE,CAIvC;AAED,4EAA4E;AAC5E,wBAAgB,UAAU,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAGzD;AAID,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;GAIG;AACH,wBAAsB,cAAc,CAClC,EAAE,EAAE,EAAE,EACN,MAAM,EAAE,cAAc,EACtB,QAAQ,EAAE,MAAM,GACf,OAAO,CAAC,oBAAoB,CAAC,CAQ/B"}

package/dist/mcp/tools/_helpers.js

@@ -1,4 +1,6 @@
 import { checkAndRefreshIfStale } from '../staleness.js';
+/** @see {@link DEFAULT_RESULT_LIMIT} — re-exported so every capped tool reads one constant (D043). */
+export { DEFAULT_RESULT_LIMIT } from '../../search/potential-matches.js';
 // collectPotentialMatches/collectPotentialMatchCandidates moved to
 // search/potential-matches.ts (Stage 1.2) so the `mast index --checker` pass
 // (graph/checker-resolver.ts) can share the exact same "what counts as a
@@ -23,6 +25,33 @@ export { collectPotentialMatches, collectPotentialMatchCandidates, } from '../..
 export async function isIndexEmpty(ctx) {
     return (await ctx.chunkStore.chunkCount()) === 0;
 }
+/**
+ * The partial-index warning (D054), for every tool that returns a primary
+ * result set — not just `mast_search`, which had it first only because that is
+ * where it was written.
+ *
+ * The severity zero: a caller reads an empty or thin answer, concludes "it
+ * isn't there", and edits or deletes code that is in fact referenced from a
+ * file the index never saw. `index_empty` covers the all-or-nothing case; this
+ * covers the far commoner partial one, where the index is populated and merely
+ * behind.
+ *
+ * Free to call. `peekUnindexed` reads a TTL-cached count synchronously and
+ * never awaits a walk (see `mcp/freshness-probe.ts`), so unlike `isIndexEmpty`
+ * this costs nothing on a populated response and needs no empty-path guard for
+ * performance — only for meaning.
+ *
+ * `null` from the probe means *no measurement has landed yet*, which is
+ * unknown, not zero. Both render as an omitted field, but they are kept
+ * distinct here because the next reader to add a branch would otherwise inherit
+ * "unknown means clean" — the exact conflation this signal exists to prevent.
+ */
+export function unindexedFilesField(ctx, claim, isEmpty) {
+    if (claim === 'named-lookup' && !isEmpty)
+        return {};
+    const unindexed = ctx.freshness?.peekUnindexed() ?? null;
+    return unindexed !== null && unindexed > 0 ? { unindexed_files: unindexed } : {};
+}
 /** Extract the first JSDoc comment block from chunk content, if present. */
 export function extractDoc(content) {
     const match = /\/\*\*([\s\S]*?)\*\//.exec(content);

package/dist/mcp/tools/_helpers.js.map

@@ -1 +1 @@
-{"version":3,"file":"_helpers.js","sourceRoot":"","sources":["../../../src/mcp/tools/_helpers.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,sBAAsB,EAA6B,MAAM,iBAAiB,CAAC;AAEpF,mEAAmE;AACnE,6EAA6E;AAC7E,yEAAyE;AACzE,oEAAoE;AACpE,sEAAsE;AACtE,4EAA4E;AAC5E,yDAAyD;AACzD,OAAO,EACL,uBAAuB,EACvB,+BAA+B,GAKhC,MAAM,mCAAmC,CAAC;AAE3C,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAe;IAChD,OAAO,CAAC,MAAM,GAAG,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC;AACnD,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,KAAK,GAAG,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnD,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC;AAED,+EAA+E;AAC/E,kFAAkF;AAClF,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAM,EACN,MAAsB,EACtB,QAAgB;IAEhB,MAAM,GAAG,GAAG,MAAM,EAAE;SACjB,UAAU,CAAC,OAAO,CAAC;SACnB,MAAM,CAAC,OAAO,CAAC;SACf,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC;SAC5B,gBAAgB,EAAE,CAAC;IACtB,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAChE,OAAO,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;AACjE,CAAC;AAED,8EAA8E;AAC9E,uEAAuE;AACvE,6EAA6E;AAC7E,yEAAyE;AACzE,uDAAuD"}
+{"version":3,"file":"_helpers.js","sourceRoot":"","sources":["../../../src/mcp/tools/_helpers.ts"],"names":[],"mappings":"AAGA,OAAO,EAAE,sBAAsB,EAA6B,MAAM,iBAAiB,CAAC;AAEpF,sGAAsG;AACtG,OAAO,EAAE,oBAAoB,EAAE,MAAM,mCAAmC,CAAC;AAEzE,mEAAmE;AACnE,6EAA6E;AAC7E,yEAAyE;AACzE,oEAAoE;AACpE,sEAAsE;AACtE,4EAA4E;AAC5E,yDAAyD;AACzD,OAAO,EACL,uBAAuB,EACvB,+BAA+B,GAKhC,MAAM,mCAAmC,CAAC;AAE3C,8EAA8E;AAC9E,4EAA4E;AAC5E,8EAA8E;AAE9E;;;;;;;;;GASG;AACH,MAAM,CAAC,KAAK,UAAU,YAAY,CAAC,GAAe;IAChD,OAAO,CAAC,MAAM,GAAG,CAAC,UAAU,CAAC,UAAU,EAAE,CAAC,KAAK,CAAC,CAAC;AACnD,CAAC;AAmBD;;;;;;;;;;;;;;;;;;;;GAoBG;AACH,MAAM,UAAU,mBAAmB,CACjC,GAAe,EACf,KAAwB,EACxB,OAAgB;IAEhB,IAAI,KAAK,KAAK,cAAc,IAAI,CAAC,OAAO;QAAE,OAAO,EAAE,CAAC;IACpD,MAAM,SAAS,GAAG,GAAG,CAAC,SAAS,EAAE,aAAa,EAAE,IAAI,IAAI,CAAC;IACzD,OAAO,SAAS,KAAK,IAAI,IAAI,SAAS,GAAG,CAAC,CAAC,CAAC,CAAC,EAAE,eAAe,EAAE,SAAS,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;AACnF,CAAC;AAED,4EAA4E;AAC5E,MAAM,UAAU,UAAU,CAAC,OAAe;IACxC,MAAM,KAAK,GAAG,sBAAsB,CAAC,IAAI,CAAC,OAAO,CAAC,CAAC;IACnD,OAAO,KAAK,IAAI,IAAI,CAAC,CAAC,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,CAAC,IAAI,CAAC;AAChD,CAAC;AAED,+EAA+E;AAC/E,kFAAkF;AAClF,OAAO,EAAE,WAAW,EAAE,MAAM,yBAAyB,CAAC;AAEtD;;;;GAIG;AACH,MAAM,CAAC,KAAK,UAAU,cAAc,CAClC,EAAM,EACN,MAAsB,EACtB,QAAgB;IAEhB,MAAM,GAAG,GAAG,MAAM,EAAE;SACjB,UAAU,CAAC,OAAO,CAAC;SACnB,MAAM,CAAC,OAAO,CAAC;SACf,KAAK,CAAC,MAAM,EAAE,GAAG,EAAE,QAAQ,CAAC;SAC5B,gBAAgB,EAAE,CAAC;IACtB,IAAI,GAAG,KAAK,SAAS;QAAE,OAAO,EAAE,IAAI,EAAE,KAAK,EAAE,SAAS,EAAE,KAAK,EAAE,CAAC;IAChE,OAAO,sBAAsB,CAAC,EAAE,EAAE,MAAM,EAAE,QAAQ,EAAE,GAAG,CAAC,KAAK,CAAC,CAAC;AACjE,CAAC;AAED,8EAA8E;AAC9E,uEAAuE;AACvE,6EAA6E;AAC7E,yEAAyE;AACzE,uDAAuD"}

package/dist/mcp/tools/callers.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"callers.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/callers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAYhD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,CA2H5E"}
+{"version":3,"file":"callers.d.ts","sourceRoot":"","sources":["../../../src/mcp/tools/callers.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,yCAAyC,CAAC;AACzE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,eAAe,CAAC;AAYhD,wBAAgB,mBAAmB,CAAC,MAAM,EAAE,SAAS,EAAE,GAAG,EAAE,UAAU,GAAG,IAAI,CAgI5E"}