@quolu/lattice 0.69.5 → 0.71.0

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

@@ -5,8 +5,11 @@
  */
 import type LatticeSensor from '../index';
 import type { QueryPool } from './query-pool';
+import { WslSharedIndexError } from '../db/wsl-shared-index';
 export declare function __setLoadLatticeSensorForTests(cls: typeof import('../index').default | null): void;
 import type { PendingFile } from '../sync';
+import { type AnswerFile } from './answer-freshness';
+import { ExploreSessionState, type ExploreEmission, type ExploreLineRange } from './explore-session-state';
 /**
  * An expected, recoverable "lattice sensor can't serve this" condition — most
  * importantly a project with no index. The dispatch catch converts these to
@@ -23,9 +26,12 @@ export declare class NotIndexedError extends Error {
 /**
  * A security refusal (sensitive system path). Stays `isError: true` WITHOUT
  * retry guidance — abandoning this path is the desired agent reaction.
+ *
+ * Defined in `../errors` so non-MCP read sinks (the `lattice sensor ui` server) can
+ * enforce the same refusal without importing this module; re-exported here
+ * because this is where every existing caller imports it from.
  */
-export declare class PathRefusalError extends Error {
-}
+export { PathRefusalError } from '../errors';
 /**
  * ADR 0049 Decision 5②: a genuine malfunction opening the default project's
  * index — DB open failure, schema mismatch, integrity error, or lock
@@ -105,19 +111,368 @@ export interface ExploreOutputBudget {
     includeAdditionalFiles: boolean;
     /** Include the "Complete source code is included above…" reminder. */
     includeCompletenessSignal: boolean;
-    /** Include the explore-budget reminder at the end. */
-    includeBudgetNote: boolean;
     /**
-     * Hard-drop test/spec/icon/i18n files from the relevant-file set unless
-     * the query itself mentions tests. Today they're only deprioritized in
-     * the sort, which on tiny repos still lets one slip into the top N (e.g.
-     * cobra's `command_test.go` displaced `args.go` and contributed ~10KB of
-     * pure noise to "How does cobra parse commands?"). Off by default; on
-     * for the very-tiny tier where one slip dominates the budget.
+     * Include the advisory exploration-guidance note at the end. Purely
+     * advisory — the server NEVER rejects or rate-limits extra explore calls.
      */
-    excludeLowValueFiles: boolean;
+    includeBudgetNote: boolean;
 }
 export declare function getExploreOutputBudget(fileCount: number): ExploreOutputBudget;
+/**
+ * How strongly a match on a symbol of this kind corroborates that its FILE is
+ * what the query is about.
+ *
+ *   1.0   a callable or a type — the unit an architecture question is about
+ *   ~0.5  a member of a type, or the file node itself (a path match, not a
+ *         symbol match)
+ *   ~0.3  a variable / constant — as often a name collision as a definition
+ *   0.15  a parameter — essentially never the subject of a question
+ *
+ * Unlisted kinds fall back to `DEFAULT_RELEVANCE_KIND_WEIGHT`, so a NodeKind
+ * added later is neither free nor fatal.
+ */
+export declare const RELEVANCE_KIND_WEIGHT: Readonly<Record<string, number>>;
+export declare const EXPLORE_ALLOCATION: {
+    /**
+     * A file whose weight is under this fraction of the top file's gets no source.
+     *
+     * Calibrated between the two shapes the fixtures pin: the #1500 generated CRUD
+     * lands at 10–11% of the top weight (penalised twice — once into the score by
+     * `rankPenalty`, once again here) and must cliff; a genuinely peripheral but
+     * hand-written flow file — `payslip_builder.go`, the direct callee of the
+     * workflow entry — lands at 25% and must NOT. Everything in between is a
+     * judgement call the agent can undo for ~0 cost, because a cliffed file is
+     * still NAMED in the response and one follow-up explore fetches it.
+     */
+    readonly CLIFF_FRACTION: 0.15;
+    /**
+     * Ceiling on the cliff, in the same units as `SCORE_FLOOR_MAX` — and for the
+     * same reason. A file whose weight clears a full-strength direct match is never
+     * incidental, so no amount of concentration elsewhere may zero it: one
+     * overwhelming top file (a 99-scoring god-file among score-10 peers) otherwise
+     * puts the cliff at 14.9 and silences every peer the score floor had just
+     * deliberately admitted. The cliff is a RELATIVE prune of weak evidence, not a
+     * second admission gate — the score floor already owns admission.
+     */
+    readonly CLIFF_MAX: 10;
+    /**
+     * Floor on a useful reservation — every admitted file gets this much before
+     * the proportional split divides the rest. Under it a slice can't hold one
+     * complete method, and a fragment is strictly worse than a pointer: it forces
+     * the Read this tool exists to prevent.
+     *
+     * It is a FLOOR, not a second cliff. Cliffing the starved file instead
+     * cascades: removing the smallest raises everyone else's share by so little
+     * that the next-smallest starves too, and a query with two dominant files ate
+     * six legitimately-ranked peers one at a time. Concentration is the relative
+     * cliff's job; this only keeps a served file's slice usable.
+     */
+    readonly MIN_CHARS: 700;
+    /**
+     * Safety valve, as a fraction of the envelope. Not the primary guard any more —
+     * the proportional split is — so this only has to stop a pathological
+     * single-file response.
+     *
+     * It does not apply to a file the query NAMED — one that defines a symbol the
+     * query spelled, or that the query named by path. The valve hedges against a
+     * mis-ranked dominant file, and a file the agent asked for by name is not
+     * one. It also never redistributed: a clamped file's excess was simply left
+     * unreserved, and the carry-forward only moves reservations, so nobody could
+     * spend it. On express, "response.js res.send res.json res.render …" admits
+     * one file, clamps it at 9,100 with 3,700 of the pool unreserved, and cuts
+     * the named `send` body at 55 of 97 lines in a 10.9K response to a 13K budget.
+     */
+    readonly MAX_SHARE: 0.7;
+    /**
+     * Markdown overhead charged per rendered file (header + fences + blank lines),
+     * matching the render loop's own `+ 200` accounting. Held out of the pool
+     * before the split so the reservations plus their overhead fit the envelope —
+     * without this the last file's reservation is always the one that doesn't fit.
+     */
+    readonly FILE_OVERHEAD: 200;
+    /**
+     * Flow-spine files are weighted up and are exempt from the cliff. Clipping the
+     * spine causes the Read fallback (it IS the answer to a flow question);
+     * clipping a peripheral file does not. This makes the existing advisory spine
+     * handling — `hasSpine`, `SPINE_CEILING` — strict at the allocation layer.
+     */
+    readonly SPINE_WEIGHT_BOOST: 2;
+    /**
+     * Slack allowed on the whole-file rule: a file a little over its reservation
+     * still ships WHOLE rather than as clusters, because slicing off that last
+     * sliver saves ~1% of the envelope and costs a Read — the trade the whole-file
+     * rule exists to refuse. Proportional (with an absolute ceiling) because a
+     * "sliver" is relative: a flat 800 is 15% of a 5K reservation but 31% of a 2.5K
+     * one, and at the small end that overshoot is exactly what the file below then
+     * loses.
+     */
+    readonly WHOLE_FILE_GRACE_FRACTION: 0.15;
+    readonly WHOLE_FILE_GRACE_MAX: 800;
+    /**
+     * A reservation that already covers this fraction of a file BUYS THE WHOLE
+     * FILE (CG-21), even though the file is bigger than the reservation.
+     *
+     * The grace above is calibrated as a *sliver* — it only rescues a file that
+     * essentially fits. Below it there is a hole the render loop cannot fill:
+     * express's `lib/utils.js` (5,293 B) was the TOP-ranked file, reserved 3,870,
+     * declined the whole-file render at a 4,450 grace bound, and then spent 583 on
+     * a three-symbol cluster render. The other 3,287 chars of its reservation were
+     * neither redistributed nor delivered — the envelope shrank by a third against
+     * an unchanged budget and the agent Read the file back four times.
+     *
+     * So the rule is not "does the file fit the reservation" but "has the
+     * reservation already bought most of the file": at 0.6 the loop pays at most
+     * two-thirds of a reservation extra to avoid losing the whole thing, and it
+     * spends bytes it was going to spend anyway on a file that already earned
+     * them. Below the fraction the shortfall is real — the file is several times
+     * its reservation, clustering is the right answer, and the carry-forward
+     * (`reservedSoFar`/`sourceSpent` in the render loop) hands whatever it cannot
+     * spend to the next file down.
+     */
+    readonly WHOLE_FILE_BUY_FRACTION: 0.6;
+    /**
+     * The buy rule's overshoot is funded from ONE pool for the whole response,
+     * sized as this fraction of the envelope — deliberately the same 15% as
+     * `WHOLE_FILE_GRACE_FRACTION`, one level up: the grace is a sliver of a
+     * FILE's reservation, this is a sliver of the RESPONSE's envelope.
+     *
+     * Per-file funding is the version that fails, and it fails the same way the
+     * bug being fixed does. The merit test is a RATIO, so wherever several files
+     * sit near it they all qualify, and N independent overshoots inflate the
+     * response until the render ceiling drops whatever is last. Measured on the
+     * #1500 payroll fixture: three files bought whole and `payslip_builder.go` —
+     * the file that computes the payslip the question asks about, rank #6 — was
+     * dropped entirely so three higher-ranked files could each ship their final
+     * sliver. A dropped section is strictly worse than a clustered one, so one
+     * shared pool, spent in rank order, is the bound that matters.
+     */
+    readonly WHOLE_FILE_BUY_OVERSHOOT_FRACTION: 0.15;
+};
+/** One candidate file's allocation inputs, in final rank order. */
+export interface ExploreAllocationCandidate {
+    path: string;
+    /** Post-`rankPenalty` relevance score from the ranking pass. */
+    score: number;
+    /**
+     * How much this file's BYTES are worth, independent of how well it matched.
+     * Ranking answers "is this file about the query"; allocation answers "will
+     * these bytes teach the agent anything". Generated CRUD can legitimately rank
+     * (it name-collides on every domain word) while its bytes stay mechanical
+     * boilerplate the agent gains nothing from reading — so `rankPenalty` is
+     * applied a SECOND time here. That is what finally sinks the #1500 generated
+     * layer below the cliff: it survived CG-10's single penalty because the sort's
+     * leading keys (entry-point, graph mass) are structural, and a big densely
+     * self-referential generated file scores well on both.
+     */
+    worth: number;
+    /**
+     * Carries a symbol on the rendered flow spine — or an exact target (a
+     * qualified name, a line anchor), which is the answer by the same argument.
+     */
+    spine: boolean;
+    /**
+     * The query named this file by PATH (see query-paths.ts). Pinned files are
+     * never cliffed or trimmed, and weigh at least as much as the strongest
+     * candidate — the agent asked for the file itself, so starving it on text/
+     * graph scores (which a pure-path query doesn't produce) defeats the ask.
+     */
+    pinned?: boolean;
+    /**
+     * The query named a symbol this file defines (the named-first sort tier). Like
+     * a pinned file, it is exempt from the `MAX_SHARE` valve: its proportional
+     * share stands, bounded only by the pool.
+     */
+    named?: boolean;
+}
+export interface ExploreAllocation {
+    /** path → chars of source it may render. Only holds admitted files. */
+    allowances: Map<string, number>;
+    /** Files the cliff zeroed, in rank order — pointers, not bytes. */
+    cliffed: string[];
+    /** The weight threshold the cliff fired at (0 when nothing was cliffed). */
+    cliffAt: number;
+    /** Chars actually split among the admitted files. */
+    pool: number;
+}
+/**
+ * Split `budget.maxOutputChars` across ranked candidates in proportion to
+ * relevance, with a hard relative cliff.
+ *
+ * `candidates` must arrive in FINAL RANK ORDER — `maxFiles` is applied to the
+ * survivors of the cliff, in that order, so cliffing genuinely hands a slot to
+ * the next file down rather than leaving it unused.
+ *
+ * Tier invariant (`getExploreOutputBudget`): a larger tier must never allow less
+ * per file than a smaller one. It holds here by construction — every bound is a
+ * fraction of `maxOutputChars` or of `maxCharsPerFile`, both monotonic across
+ * tiers — except `MIN_CHARS`, which is an absolute floor and so identical at
+ * every tier.
+ */
+export declare function allocateExploreBudget(candidates: readonly ExploreAllocationCandidate[], budget: ExploreOutputBudget, maxFiles: number): ExploreAllocation;
+type ElidedSymbolRef = {
+    name: string;
+    kind: string;
+    startLine: number;
+};
+/**
+ * Indexed symbols whose definition starts strictly between two rendered
+ * spans. The hole is what a trim dropped; naming them is what lets the agent
+ * follow up by name instead of guessing (#1711).
+ */
+export declare function symbolsBetweenRanges(nodes: ReadonlyArray<{
+    name: string;
+    kind: string;
+    startLine: number;
+    endLine: number;
+}>, fromEnd: number, toStart: number): ElidedSymbolRef[];
+/**
+ * Symbols in `candidates` whose start line is not covered by any emitted range.
+ * Used to bias the per-file header toward what the trim dropped (#1711).
+ */
+export declare function symbolsNotInRanges(candidates: ReadonlyArray<ElidedSymbolRef>, ranges: ReadonlyArray<ExploreLineRange>): ElidedSymbolRef[];
+/**
+ * Gap marker between two non-contiguous slices of one file.
+ *
+ * Bare `... (gap) ...` told the agent something was missing but not WHAT —
+ * and the footer then asked it to re-explore "with its exact name", which is
+ * circular when the missing names *are* the question (#1711). When the hole
+ * holds indexed symbols, list them as `name (file:line)` (same shape the
+ * flow / blast-radius lines already use).
+ */
+export declare function formatGapMarker(filePath: string, elided: ReadonlyArray<ElidedSymbolRef>): string;
+/**
+ * Join rendered parts with gap markers that name whatever the trim skipped.
+ *
+ * `spareChars` is what naming may cost beyond bare markers. Cluster selection
+ * prices every join between clusters as a bare marker, and on a long path each
+ * named gap runs to several hundred chars, so unbounded naming overran the
+ * file's reservation and the ceiling trim then dropped SOURCE to pay for the
+ * names: vscode's `rpcProtocol.ts` went from ~5,200 chars of the RPCProtocol
+ * body to a 222-char stub. A gap the spare can't cover stays bare; the file
+ * header still lists the symbols the trim dropped.
+ */
+export declare function joinPartsWithNamedGaps(filePath: string, parts: ReadonlyArray<{
+    range: ExploreLineRange;
+    text: string;
+}>, nodes: ReadonlyArray<{
+    name: string;
+    kind: string;
+    startLine: number;
+    endLine: number;
+}>, spareChars?: number): string;
+/**
+ * Prefer symbols the trim dropped when filling the per-file header's named
+ * slots, so `+N more` is less likely to hide the answer (#1711). Frequency
+ * still breaks ties among the preferred / remaining groups.
+ */
+export declare function biasHeaderSymbols(symbols: readonly string[], elided: ReadonlyArray<ElidedSymbolRef>, cap: number): {
+    shown: string[];
+    omitted: number;
+};
+/**
+ * The notes that stand in for the epilogue, or close a truncated response, in
+ * two wordings each. `complete` says the source above is complete; `trimmed` is
+ * used when a section it vouches for was trimmed (see `elidedWantedSpans`) and
+ * drops that claim, keeping the guarantee that is still true. Each trimmed
+ * wording is no longer than its complete one: the epilogue floor (`lost`) and
+ * the cut note's fit test (`cut`) are sized before the render knows which of the
+ * two it will need.
+ */
+export declare const EXPLORE_FALLBACK_NOTES: {
+    readonly lost: {
+        readonly complete: "> (Trailing pointer list omitted for size. The source above is complete and verbatim — treat it as already Read. For anything this call did not cover, run another lattice_sensor_explore with the specific names rather than reading those files.)";
+        readonly trimmed: "> (Trailing pointer list omitted for size. The source above is verbatim — treat it as already Read. For symbols its gap markers name, and anything else not covered, run another lattice_sensor_explore with those names rather than reading.)";
+    };
+    readonly cut: {
+        readonly complete: "\n\n> (Trailing notes omitted for size. The source above is complete and verbatim — treat it as already Read. For anything this call did not cover, run another lattice_sensor_explore with the specific names rather than reading those files.)";
+        readonly trimmed: "\n\n> (Trailing notes omitted for size. The source above is verbatim — treat it as already Read. For symbols its gap markers name, and anything else not covered, run another lattice_sensor_explore with those names rather than reading.)";
+    };
+    readonly truncated: {
+        readonly complete: "\n\n... (output truncated to budget; the source above is complete and verbatim — treat it as already Read. For any area not covered, run another lattice_sensor_explore with the specific names — do NOT Read these files.)";
+        readonly trimmed: "\n\n... (output truncated to budget; the source above is verbatim — treat it as already Read. For names its gap markers list, or any area not covered, run another lattice_sensor_explore — do NOT Read these files.)";
+    };
+};
+/**
+ * One symbol a file section set out to deliver: a cluster member, or a symbol
+ * of the per-symbol (focused/skeleton) view. Completeness is judged against
+ * these, not against the file — explore never promises whole files, only the
+ * symbols it selected for each one.
+ */
+export type ExploreWantedSpan = {
+    name: string;
+    kind: string;
+    start: number;
+    end: number;
+    importance: number;
+    spine: boolean;
+    /** The indexed qualified name (`SQLCompiler::as_sql`), when the span is a node. */
+    qualifiedName?: string;
+};
+/**
+ * The wanted spans a section did NOT deliver in full: some line of the span is
+ * in neither what this call sent nor what an earlier call already sent (a
+ * back-referenced span counts — the agent holds that copy).
+ *
+ * Derived from the emitted ranges rather than from a flag each trim site has to
+ * remember to set. The oversize-spine window set none until #2068, which is how
+ * a 62-line slice of vscode's 968-line `rpcProtocol.ts` went out under "Complete
+ * source … do NOT re-read them". Whatever elides source — a member shrink, a
+ * ceiling window, a dropped cluster, the per-symbol view, a path added later —
+ * shows up here.
+ *
+ * Most relevant first (spine, then importance), then source order.
+ */
+export declare function elidedWantedSpans(wanted: ReadonlyArray<ExploreWantedSpan>, delivered: ReadonlyArray<ExploreLineRange>): ExploreWantedSpan[];
+/** A rendered file whose section is missing some of what it set out to deliver. */
+export type ExplorePartialFile = {
+    filePath: string;
+    elided: ReadonlyArray<ExploreWantedSpan>;
+};
+/**
+ * The shortest trailing slice of each path that no other path in `paths`
+ * ends with: `extHostExtensionService.ts` alone when it is the only one,
+ * `node/extHostExtensionService.ts` beside `common/extHostExtensionService.ts`.
+ */
+export declare function shortestUniqueSuffixes(paths: ReadonlyArray<string>): Map<string, string>;
+/**
+ * The large tiers' completeness note (`includeCompletenessSignal`), as
+ * candidates from most to least specific. The epilogue fit keeps the first
+ * one that fits the room left (CG-26).
+ *
+ * "Complete" is claimed only when no section elided anything it set out to
+ * deliver. Otherwise the note keeps the guarantee that is still true (every
+ * block shown is verbatim; treat it as already Read), names the trimmed files
+ * and the most relevant elided symbols as room allows, and sends the agent to
+ * another lattice_sensor_explore for them. It never offers Read: explore output must
+ * not tell the agent to Read (AGENTS.md).
+ */
+export declare function exploreCompletenessNotes(filesIncluded: number, trimmed: ReadonlyArray<ExplorePartialFile>, 
+/** Every path the response can name (sections and pointer list); labels are unique among them. */
+knownPaths: ReadonlyArray<string>): string[];
+/**
+ * Fit the completeness note and the pointer list into the room the response has
+ * left (CG-26). Returns the note (a candidate block, or none), the pointer
+ * block, and the room that remains.
+ *
+ * The note is one of `noteCandidates`, most specific first. A complete-source
+ * note keeps the precedence it always had and goes first. A note that YIELDS (a
+ * trimmed one) gives way to the pointer list, which names files the response
+ * does not show at all, while what a trimmed section elided is already named in
+ * its own gap markers and header. It leaves the list's header and first entry
+ * when that much could fit, and its optional detail never costs an entry the
+ * least specific candidate would have left.
+ */
+export declare function fitExploreEpilogue(opts: {
+    room: number;
+    noteCandidates: ReadonlyArray<readonly string[]>;
+    noteYields: boolean;
+    pointerEntries: readonly string[];
+    pointerOmitted: number;
+}): {
+    note: string[];
+    pointers: string[];
+    room: number;
+};
 /**
  * Per-file staleness banner emitted at the top of a tool response when the
  * file watcher has pending events for files referenced by the response.
@@ -140,6 +495,8 @@ export declare function formatStaleFooter(stale: PendingFile[]): string;
  * already names the operator remedy (`lattice sensor sync . --json` / git hooks).
  */
 export declare function formatDegradedBanner(reason: string | null): string;
+/** Re-armed watches are not proof of freshness until their full scan commits. */
+export declare function formatRecoveringBanner(): string;
 /**
  * MCP Tool definition
  */
@@ -153,6 +510,12 @@ export interface ToolDefinition {
     };
     /** Behavioral hints for clients (see {@link ToolAnnotations}). */
     annotations?: ToolAnnotations;
+    /**
+     * MCP `_meta` on the tool definition. `anthropic/alwaysLoad: true` makes
+     * Claude Code load the tool at session start instead of deferring it behind
+     * its tool search (https://code.claude.com/docs/en/mcp#exempt-a-server-from-deferral).
+     */
+    _meta?: Record<string, unknown>;
 }
 /**
  * MCP ToolAnnotations — behavioral hints a client MAY use to decide how, or
@@ -194,6 +557,18 @@ export interface ToolResult {
         text: string;
     }>;
     isError?: boolean;
+    /**
+     * INTERNAL side-channel (CG-17): what a `lattice_sensor_explore` call actually put
+     * on the wire — files, line ranges, bytes. It rides the result because the
+     * call may have run on a query-pool worker, while the session state it feeds
+     * lives on the main thread. {@link ToolHandler.execute} records it and DELETES
+     * it, so nothing here ever reaches the client. Keyed by
+     * {@link EXPLORE_EMISSION_KEY}; the two must stay in sync.
+     */
+    _cgExploreEmission?: ExploreEmission;
+    /** Internal structured provenance, preserved by query workers and stripped by execute. */
+    _cgAnswerFiles?: AnswerFile[];
+    structuredContent?: Record<string, unknown>;
 }
 /**
  * All LatticeSensor MCP tools
@@ -212,6 +587,27 @@ export declare const tools: ToolDefinition[];
  * note in a description only adds once `cg` is loaded; the schemas are static).
  */
 export declare function getStaticTools(): ToolDefinition[];
+/**
+ * How many explicit-`projectPath` projects a handler keeps open at once
+ * (#1835). Each cached project may hold a file watcher, a writer lock and a
+ * SQLite connection, so the cache is bounded LRU: opening one more than this
+ * closes the least recently used. Small on purpose — a session that queries
+ * many repositories still leaks nothing; it only pays a reopen + catch-up.
+ */
+export declare const MAX_CACHED_PROJECTS = 8;
+/**
+ * Engine-side lifecycle for a project the ToolHandler opened for an explicit
+ * `projectPath` (#1835). `activate` gives it the same treatment the default
+ * project gets — a file watcher while it stays open and a catch-up sync — and
+ * returns the catch-up promise, which the handler awaits (time-boxed) before
+ * calls against that project. `release` runs after active calls drain, so the
+ * engine can release shared ownership safely on LRU eviction or shutdown.
+ */
+export interface ProjectLifecycle {
+    open(root: string, open: () => LatticeSensor): LatticeSensor;
+    activate(cg: LatticeSensor): Promise<void>;
+    release(cg: LatticeSensor): void | Promise<void>;
+}
 /**
  * Tool handler that executes tools against a LatticeSensor instance
  *
@@ -221,25 +617,46 @@ export declare function getStaticTools(): ToolDefinition[];
 export declare class ToolHandler {
     private cg;
     private projectCache;
+    private projectLifecycle;
+    private projectGates;
+    private activeCalls;
+    private closing;
+    private pendingCloses;
+    private closeWaiters;
     private defaultProjectHint;
+    private knownSubprojects;
+    private knownSubprojectsBase;
+    private defaultOpenFailure;
     private worktreeMismatchCache;
     private catchUpGate;
+    private onDatabaseReopened;
     private queryPool;
     private openFailure;
     private executionMode;
     constructor(cg: LatticeSensor | null);
     /**
      * Engine-only: attach (or detach with null) the worker-thread query pool. The
-     * shared daemon sets this once its default project is open; the workers each
+     * engine sets this after resolving its default project; the workers each
      * hold their own WAL read connection and run {@link executeReadTool}. A
      * worker's own ToolHandler never has a pool, so there is no nested off-loading.
      */
     setQueryPool(pool: QueryPool | null): void;
+    /**
+     * Engine-only: own the lifecycle (watcher, catch-up, writer lock) of every
+     * project this handler opens for an explicit `projectPath` (#1835).
+     */
+    setProjectLifecycle(lifecycle: ProjectLifecycle | null): void;
     /**
      * Update the default LatticeSensor instance (e.g. after lazy initialization).
      * A successful open supersedes any previously recorded open failure.
      */
     setDefaultLatticeSensor(cg: LatticeSensor): void;
+    /**
+     * Engine-only: record why the default project failed to open (#995), so a
+     * call that needs it answers with that fix rather than "no project loaded".
+     * `null` clears it.
+     */
+    setDefaultOpenFailure(err: WslSharedIndexError | null): void;
     /**
      * ADR 0049 Decision 5②: record that the DEFAULT project's index failed to
      * open for a reason OTHER than "no .lattice/sensor/ found" — the engine calls
@@ -269,6 +686,12 @@ export declare class ToolHandler {
      * stale data, which is what would have happened without the gate.
      */
     setCatchUpGate(p: Promise<void> | null): void;
+    /**
+     * Engine-only: called after a tool call's {@link freshen} reopened a database
+     * that was replaced on disk (#1902). The engine decides whether a catch-up
+     * sync is its to run (only for the instance it watches and writes).
+     */
+    setOnDatabaseReopened(fn: ((cg: LatticeSensor) => void) | null): void;
     /**
      * Await the catch-up gate, but no longer than the configured timeout (#905).
      * If the reconcile settles first, we got the fully-reconciled answer. If the
@@ -284,6 +707,14 @@ export declare class ToolHandler {
      * Used only to make the "no default project" error actionable.
      */
     setDefaultProjectHint(searchedPath: string): void;
+    /**
+     * Engine-only: record the indexed sub-projects the workspace down-scan saw
+     * when it could not adopt a default project (#1606/#1607). An empty list
+     * clears any previous note.
+     */
+    setKnownSubprojects(roots: string[], base: string): void;
+    /** One message line naming the indexed sub-projects, or '' when none known. */
+    private formatKnownSubprojects;
     /**
      * Whether a default LatticeSensor instance is available
      */
@@ -316,6 +747,9 @@ export declare class ToolHandler {
      * similar to how git finds .git/ directories.
      */
     private getLatticeSensor;
+    private awaitProjectGate;
+    /** Never evict a graph while a tool call or its timed-out reconcile uses it. */
+    private trimProjects;
     /**
      * Heal a long-lived connection whose `.lattice/sensor/` was removed and recreated
      * at the same path (a worktree recreated, or `rm -rf .lattice/sensor` + re-init)
@@ -330,7 +764,7 @@ export declare class ToolHandler {
     /**
      * Close all cached project connections
      */
-    closeAll(): void;
+    closeAll(): Promise<void>;
     /**
      * Validate that a value is a non-empty string within length bounds.
      *
@@ -404,11 +838,40 @@ export declare class ToolHandler {
      * would needlessly push the agent back to Read.
      */
     private isFileStaleOnDisk;
+    private answerResult;
     private withStalenessNotice;
     /**
-     * Execute a tool by name
+     * Execute a tool by name.
+     *
+     * `sessionState` is the CALLER's per-session explore history (CG-17). The
+     * daemon shares one ToolHandler across every connected session, so this state
+     * cannot live on the handler — each session owns one and hands it in, which is
+     * what keeps two sessions on one daemon from ever seeing each other's calls.
+     * Omit it (the CLI does) and explore behaves exactly as before, untracked.
+     */
+    execute(toolName: string, args: Record<string, unknown>, sessionState?: ExploreSessionState): Promise<ToolResult>;
+    /**
+     * Attach the caller's session view to an explore call's args (CG-17), on a
+     * COPY so the caller's object is never mutated. Nothing else sees it: a
+     * non-explore tool, or a caller with no session state, gets the args
+     * unchanged and pays nothing.
+     *
+     * A client that spells the internal key itself is stripped rather than
+     * trusted — the view decides what source a later call may withhold, so it has
+     * to come from the server's own record, never from the wire.
+     */
+    private withSessionView;
+    /**
+     * Record an explore call's emission into the caller's session state and strip
+     * it from the result (CG-17).
+     *
+     * Unconditional strip: the property is internal, so it comes off even when
+     * there is no session state to record it into (the CLI path) — that is what
+     * keeps the agent-facing response byte-identical. Recording is wrapped
+     * because a bookkeeping bug must never fail a tool call that already
+     * succeeded.
      */
-    execute(toolName: string, args: Record<string, unknown>): Promise<ToolResult>;
+    private takeExploreEmission;
     /**
      * Run a single read tool to completion and return its raw {@link ToolResult},
      * classifying expected failures the same way {@link execute}'s catch does so
@@ -462,6 +925,12 @@ export declare class ToolHandler {
      * for ordinary static edges. Used by trace + the node trail so a synthesized
      * hop reads as "registered via onUpdate at App.tsx:3148", not a bare arrow.
      */
+    /**
+     * The branch conditions a flow hop's call site runs under, read from the
+     * caller's source now (`graph/branch-guards.ts`); '' when unconditional,
+     * unreadable, or the grammar for that language is not loaded.
+     */
+    private whenLabel;
     private synthEdgeNote;
     /**
      * Flow-from-named-symbols: an agent's lattice_sensor_explore query is a bag of
@@ -511,12 +980,13 @@ export declare class ToolHandler {
      */
     private buildPolymorphicBoundaries;
     /**
-     * Shortlist candidate runtime targets for a dispatch key surfaced by
-     * {@link buildDynamicBoundaries}. Exact conventional names first (`save` →
-     * `onSave`/`handleSave`; `CreateCmd` → `CreateCmdHandler`), then FTS, with a
-     * normalized-containment post-filter (FTS camel-splitting is fuzzier than a
-     * candidate list should be). Symbols the agent already named sort first and
-     * are marked — that's the "you were right, here's the wiring" case.
+     * Render the candidate shortlist for a dispatch site as one line.
+     *
+     * The shortlist itself is `shortlistBoundaryCandidates` in
+     * `../graph/dynamic-boundary-report` — shared with the viewer's end cap, so
+     * "candidates for key `save`" names the same symbols in both places. Symbols
+     * the agent already named are marked: that is the "you were right, here's the
+     * wiring" case.
      */
     private boundaryCandidates;
     /**
@@ -637,22 +1107,8 @@ export declare class ToolHandler {
      * Returns the best match and a note about alternatives if any.
      */
     /**
-     * Check if a node matches a symbol query.
-     *
-     * Accepts simple names (`run`) and three flavors of qualifier:
-     *   - dotted     `Session.request`         (TS/JS/Python)
-     *   - colon-pair `stage_apply::run`        (Rust, C++, Ruby)
-     *   - slash      `configurator/stage_apply` (path-ish)
-     *
-     * Multi-level qualifiers compose: `crate::configurator::stage_apply::run`
-     * works. Rust path prefixes (`crate`, `super`, `self`) are stripped so
-     * the canonical `crate::module::symbol` form resolves.
-     *
-     * Resolution order, last part must always equal `node.name`:
-     *   1. Suffix-match against `qualifiedName` (handles class-scoped methods
-     *      where the extractor builds the qualified name from the AST stack)
-     *   2. File-path containment (handles file-derived modules in Rust/
-     *      Python — `stage_apply::run` matches a `run` in `stage_apply.rs`)
+     * Check if a node matches a symbol query — see `matchesSymbol` in
+     * `../graph/symbol-lookup`, which owns the rules.
      */
     private matchesSymbol;
     /**
@@ -667,6 +1123,9 @@ export declare class ToolHandler {
     /**
      * Find ALL symbols matching a name. Used by callers/callees/impact to aggregate
      * results across all matching symbols (e.g., multiple classes with an `execute` method).
+     *
+     * The resolution itself lives in `../graph/named-symbol-flow`, so the Flow
+     * strip and `lattice_sensor_explore` resolve a written name to the same nodes.
      */
     private findAllSymbols;
     /**
@@ -695,5 +1154,4 @@ export declare class ToolHandler {
     private textResult;
     private errorResult;
 }
-export {};
 //# sourceMappingURL=tools.d.ts.map