pi-context-engine 0.3.1 → 0.5.0

package/README.md

@@ -37,7 +37,7 @@ runs fixed queries. Run it yourself; nothing is cherry-picked.
 
 ## What you get
 
-Ten tools the agent can call, plus three slash commands.
+Ten tools the agent can call, plus four slash commands.
 
 **Search**
 - **`context_search`**: hybrid vector + BM25 retrieval with confidence scores.
@@ -56,7 +56,8 @@ Ten tools the agent can call, plus three slash commands.
 - **`index_status`**: chunk count and measured savings.
 - **`reindex`**: refresh a path or the whole project.
 
-Commands: `/context-index [--full]`, `/context-status`, `/context-savings`.
+Commands: `/context-index [--full]`, `/context-status`, `/context-savings`,
+`/context-warmup`.
 
 **Shipped guidance.** The package also injects a ~900-token guidance section
 into the system prompt while `context_search` is active: how to formulate
@@ -95,12 +96,30 @@ unchanged repo took 237 ms.
   it. You get a notification only when something changed.
 - **Lazy fallback**: if a search still lands on an empty index, indexing kicks
   off on the spot and the tool asks you to retry in a few seconds.
-- **One switch for both**: `indexer.auto_index: false` disables both behaviors;
-  build the index manually with `/context-index` instead.
+- **Live reindex while you work**: a recursive file watcher re-indexes on
+  edits, saves and branch switches (debounced, so a `git checkout` collapses
+  into one run). The agent's own edits are searchable right away instead of
+  after the next session.
+- **Switches**: `indexer.auto_index: false` disables the session-start and
+  lazy kicks; `indexer.watch: false` disables the file watcher. Use
+  `/context-index` for manual builds.
 - **Why it matters**: incremental runs are cheap (a few hundred ms on an
   unchanged repo), so this removes the classic cold-start failure of searching
   an empty index, without ever blocking the UI.
 
+### Model warmup
+
+- **`/context-warmup`** downloads the embedding model up front, no project or
+  index needed. With `retrieval.rerank: local` it also fetches the reranker
+  model; with Ollama as the backend it forces the model pull through the same
+  command.
+- **Why it matters**: the embedder initializes lazily, only when a run has
+  chunks to embed. An empty repo or an already up-to-date index never touches
+  the network, so on a fresh machine or an ephemeral container the download
+  lands inside the first search. Warming turns it into an explicit
+  provisioning step (a devcontainer `postCreateCommand`, a CI cache setup),
+  keeping first searches fast.
+
 ## Requirements
 
 - **Node 22+** on macOS, Linux or Windows.
@@ -167,6 +186,7 @@ indexer:
   chunking: legacy        # legacy (default) | ast-density — cAST-style budgeted split-merge (experimental)
   chunk_budget_chars: 1200 # non-whitespace budget per ast-density chunk
   auto_index: true        # incremental background reindex shortly after session start
+  watch: true             # reindex on file changes while the session runs (debounced, incremental)
 memory:
   redact_pii: true
 pricing:
@@ -247,7 +267,7 @@ bootstrapping for non-pi editors.
 
 ```bash
 npm install
-npm run check          # typecheck + 97 unit tests
+npm run check          # typecheck + 251 unit tests
 npm run smoke:env      # tree-sitter + sqlite-vec capability check
 npm run smoke:loader   # load the extension through pi's jiti loader
 npm run smoke:real-world  # index this repo with the local embedder

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pi-context-engine",
-  "version": "0.3.1",
+  "version": "0.5.0",
   "description": "Semantic code context for pi: tree-sitter index + hybrid vector/BM25 retrieval + cross-session memory, all local. Port of code-context-engine (MIT, elara-labs) as a native pi extension.",
   "keywords": [
     "pi-package",

package/src/config.ts

@@ -95,6 +95,12 @@ export interface Config {
 	indexerContextHeaders: boolean;
 	/** Run an incremental reindex in the background shortly after session start. */
 	indexerAutoIndex: boolean;
+	/**
+	 * Watch the project tree while a session runs and reindex on changes
+	 * (debounced, incremental). Independent of `indexerAutoIndex`, which only
+	 * gates the session-start kick.
+	 */
+	indexerWatch: boolean;
 	indexerRedactSecrets: boolean;
 	memoryRedactPii: boolean;
 	pricingModel: string;
@@ -128,6 +134,7 @@ export function defaultConfig(): Config {
 		indexerIgnore: [...DEFAULT_IGNORE],
 		indexerContextHeaders: true,
 		indexerAutoIndex: true,
+		indexerWatch: true,
 		indexerRedactSecrets: true,
 		memoryRedactPii: true,
 		pricingModel: "opus",
@@ -162,6 +169,7 @@ const MAPPING: Record<string, keyof Config> = {
 	"indexer.ignore": "indexerIgnore",
 	"indexer.context_headers": "indexerContextHeaders",
 	"indexer.auto_index": "indexerAutoIndex",
+	"indexer.watch": "indexerWatch",
 	"indexer.redact_secrets": "indexerRedactSecrets",
 	"memory.redact_pii": "memoryRedactPii",
 	"storage.path": "storagePath",

package/src/engine.ts

@@ -125,8 +125,19 @@ export interface SessionStats {
 export interface EngineOptions {
 	projectDir: string;
 	config?: Config;
-	/** Test seam: reuse an existing backend/embedder instead of auto-detecting. */
-	runtime?: { backend: LocalBackend; embedder: Embedder };
+	/** Test seam: reuse an existing backend/embedder/reranker instead of auto-detecting. */
+	runtime?: { backend: LocalBackend; embedder: Embedder; reranker?: LocalReranker };
+}
+
+/** Issue #11 (upstream warmup): what /context-warmup resolved + cached. */
+export interface WarmupReport {
+	backend: string;
+	model: string;
+	dimension: number;
+	/** Present only when retrieval.rerank is "local". */
+	reranker?: string;
+	rerankerReady?: boolean;
+	rerankerError?: string;
 }
 
 /** R13: cheap keyword extraction for decision tags (no LLM): distinctive
@@ -150,10 +161,13 @@ export class ContextEngine {
 	readonly projectName: string;
 	readonly storageBase: string;
 	config: Config;
-	private readonly injectedRuntime: { backend: LocalBackend; embedder: Embedder } | undefined;
+	private readonly injectedRuntime:
+		| { backend: LocalBackend; embedder: Embedder; reranker?: LocalReranker }
+		| undefined;
 	private backendInstance: LocalBackend | null = null;
 	private embedderInstance: Embedder | null = null;
 	private retrieverInstance: HybridRetriever | null = null;
+	private rerankerInstance: LocalReranker | null = null;
 	private compressorInstance: Compressor | null = null;
 	private memoryInstance: MemoryDb | null = null;
 	private memoryFailed = false;
@@ -210,15 +224,48 @@ export class ContextEngine {
 			this.retrieverInstance = new HybridRetriever(this.backend, await this.getEmbedder(), {
 				expandContext: this.config.retrievalExpandContext,
 				autoElaborate: this.config.retrievalAutoElaborate,
-				reranker:
-					this.config.retrievalRerank === "local"
-						? new LocalReranker(this.config.retrievalRerankModel)
-						: null,
+				reranker: this.getReranker(),
 			});
 		}
 		return this.retrieverInstance;
 	}
 
+	/**
+	 * The opt-in local reranker, or null when reranking is off. Memoized so
+	 * /context-warmup loads the SAME instance the retriever later searches
+	 * with — the model stays warm across the command boundary.
+	 */
+	private getReranker(): LocalReranker | null {
+		if (this.config.retrievalRerank !== "local") return null;
+		this.rerankerInstance ??= this.injectedRuntime?.reranker ?? new LocalReranker(this.config.retrievalRerankModel);
+		return this.rerankerInstance;
+	}
+
+	/**
+	 * Warm the model caches (issue #11, upstream elara-labs#168): resolve +
+	 * download + dimension-probe the embedding backend, and — when the opt-in
+	 * local reranker is configured — its cross-encoder too. Unlike a reindex
+	 * on an empty or fully up-to-date repo (which never initializes the
+	 * embedder and therefore never touches the network), this guarantees the
+	 * models are cached, so the first search or index doesn't pay the fetch
+	 * inline. Ollama pulls ride the existing ensureModel() path.
+	 */
+	async warmup(): Promise<WarmupReport> {
+		const embedder = await this.getEmbedder();
+		const report: WarmupReport = {
+			backend: embedder.backendName,
+			model: embedder.modelName,
+			dimension: embedder.dimension,
+		};
+		const reranker = this.getReranker();
+		if (reranker) {
+			report.reranker = reranker.model;
+			report.rerankerReady = await reranker.warm();
+			if (!report.rerankerReady) report.rerankerError = reranker.loadError ?? "unknown error";
+		}
+		return report;
+	}
+
 	async getCompressor(): Promise<Compressor> {
 		if (!this.compressorInstance) {
 			this.compressorInstance = new Compressor(

package/src/extension.ts

@@ -12,6 +12,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { ContextEngine, isPceConfig } from "./engine.js";
 import { applyContextSearchGuidance } from "./guidance.js";
+import { ProjectWatcher } from "./indexer/watcher.js";
 
 /** Tools whose payloads are worth capturing for session timelines. */
 const CAPTURED_TOOLS = new Set(["bash", "read", "edit", "write", "grep", "find", "ls"]);
@@ -32,6 +33,100 @@ export default function contextEngineExtension(pi: ExtensionAPI) {
 	let autoIndexTimer: NodeJS.Timeout | null = null;
 	let indexInFlight = false;
 
+	/**
+	 * File watcher (config `indexer.watch`, default true): a debounced change
+	 * signal over the project tree. Unlike the session-start auto-index this
+	 * is re-kickable — one kick per settled change burst, for the whole
+	 * session. Owned by this closure, like `autoIndexTimer`: engine instances
+	 * are replaced per `session_start` without a shutdown event.
+	 */
+	let watcher: ProjectWatcher | null = null;
+	let watcherKickPending = false;
+	let watcherNotify: ((msg: string, level: "info" | "warning") => void) | undefined;
+
+	/**
+	 * Watcher-triggered incremental reindex. Unlike `kickBackgroundIndex` this
+	 * calls `reindex()` directly — the watcher must re-fire all session, not
+	 * consume a one-shot. Shares `indexInFlight` with the other kicks so runs
+	 * never stack; a change that arrives mid-run coalesces into exactly one
+	 * trailing kick, so edits made *while indexing* still land. Successful
+	 * runs stay silent (the user's own edit caused them); failures — both
+	 * rejections AND per-file errors resolved in `result.errors` — notify.
+	 */
+	const kickWatcherIndex = (eng: ContextEngine, notify?: (msg: string, level: "info" | "warning") => void) => {
+		if (engine !== eng) return; // session moved on
+		if (indexInFlight) {
+			watcherKickPending = true;
+			return;
+		}
+		indexInFlight = true;
+		void eng
+			.reindex({})
+			.then((result) => {
+				// Per-file chunking/read failures RESOLVE in result.errors — mirroring
+				// kickBackgroundIndex, surface them or affected files go stale silently.
+				if (engine !== eng || !notify) return; // session moved on
+				if (result.errors.length > 0) {
+					notify(`Context index: watcher reindex hit ${result.errors.length} error(s)`, "warning");
+				}
+			})
+			.catch((err: unknown) => {
+				if (engine === eng && notify) {
+					const detail = (err instanceof Error ? err.message : String(err)).slice(0, 120);
+					notify(`Context index: watcher reindex failed (${detail})`, "warning");
+				}
+			})
+			.finally(() => {
+				indexInFlight = false;
+				drainWatcherKick();
+			});
+	};
+
+	/** Deliver a watcher change that arrived while a background run was in flight. */
+	const drainWatcherKick = () => {
+		if (!watcherKickPending) return;
+		watcherKickPending = false;
+		if (engine && watcher) kickWatcherIndex(engine, watcherNotify);
+	};
+
+	const stopWatcher = () => {
+		watcher?.stop();
+		watcher = null;
+		watcherKickPending = false;
+	};
+
+	/**
+	 * (Re)point the file watcher at the live engine's project dir. Idempotent
+	 * per dir (called from every `getEngine`), so a mid-session project switch
+	 * re-arms the watcher exactly like the auto-index timer re-points its kick.
+	 */
+	const attachWatcher = (eng: ContextEngine) => {
+		if (watcher && watcher.dir === eng.projectDir) return;
+		stopWatcher();
+		if (!eng.config.indexerWatch) return;
+		// An in-project storage dir (storage.path inside the checkout) is written
+		// on EVERY reindex run (manifest.save()), so its events must not be
+		// accepted — otherwise each kick schedules the next one forever.
+		const storageRel = path.relative(eng.projectDir, eng.storageBase);
+		const storageInsideProject = storageRel !== "" && !storageRel.startsWith("..") && !path.isAbsolute(storageRel);
+		const w = new ProjectWatcher(eng.projectDir, {
+			// Same sets the walker enforces: any-depth + root-only semantics,
+			// user additions to indexer.ignore included, case-sensitive.
+			ignoreSegments: eng.config.indexerIgnore,
+			ignorePaths: storageInsideProject ? [eng.storageBase] : [],
+			onChange: () => {
+				if (engine) kickWatcherIndex(engine, watcherNotify);
+			},
+			onError: (err) => {
+				// E.g. Linux inotify exhaustion: degrade to session-start/lazy
+				// indexing and say so once. Never crash the session.
+				stopWatcher();
+				watcherNotify?.(`Context index: file watcher disabled (${err.message.slice(0, 100)}) — back to session-start indexing only`, "warning");
+			},
+		});
+		if (w.start()) watcher = w;
+	};
+
 	/**
 	 * Kick the one-shot background index (session-start auto-index and the
 	 * first-search lazy path share this). Never stacks: `lazyIndexStarted`
@@ -69,6 +164,7 @@ export default function contextEngineExtension(pi: ExtensionAPI) {
 			})
 			.finally(() => {
 				indexInFlight = false;
+				drainWatcherKick(); // a watcher change may have landed mid-run
 			});
 	};
 
@@ -82,6 +178,7 @@ export default function contextEngineExtension(pi: ExtensionAPI) {
 		// Always track the live engine so `session_shutdown` closes it even when
 		// a tool ran before `session_start` (tests, mid-reload edge cases).
 		engine = new ContextEngine({ projectDir: dir });
+		attachWatcher(engine);
 		return engine;
 	};
 
@@ -364,6 +461,22 @@ export default function contextEngineExtension(pi: ExtensionAPI) {
 		},
 	});
 
+	pi.registerCommand("context-warmup", {
+		description: "Pre-download the embedding (and opt-in reranker) model so the first search doesn't fetch inline",
+		handler: async (_args, ctx) => {
+			ctx.ui.notify("Warming up embedding model…", "info");
+			const report = await getEngine(ctx.cwd).warmup();
+			const parts = [`${report.backend} ${report.model} (${report.dimension} dims)`];
+			if (report.reranker) {
+				parts.push(report.rerankerReady ? `reranker ${report.reranker} ready` : `reranker ${report.reranker} FAILED: ${report.rerankerError}`);
+			}
+			ctx.ui.notify(
+				`✓ Warmup complete: ${parts.join(" · ")}`,
+				report.reranker && !report.rerankerReady ? "warning" : "info",
+			);
+		},
+	});
+
 	/* ── Lifecycle hooks (replace upstream's curl-based hooks) ───────────── */
 
 	pi.on("session_start", async (_event, ctx) => {
@@ -372,6 +485,12 @@ export default function contextEngineExtension(pi: ExtensionAPI) {
 		engine.startBackgroundWork();
 		lazyIndexStarted = false;
 		bootstrapSent = false;
+		watcherNotify = ctx.hasUI ? (msg, level) => ctx.ui.notify(msg, level) : undefined;
+		// (Re)arm the file watcher for this session: fresh notify channel, and
+		// config may have changed since the last session. No-op when
+		// `indexer.watch` is off.
+		stopWatcher();
+		attachWatcher(engine);
 		if (autoIndexTimer) {
 			clearTimeout(autoIndexTimer);
 			autoIndexTimer = null;
@@ -455,6 +574,8 @@ export default function contextEngineExtension(pi: ExtensionAPI) {
 			clearTimeout(autoIndexTimer);
 			autoIndexTimer = null;
 		}
+		stopWatcher();
+		watcherNotify = undefined;
 		await engine?.shutdown().catch(() => undefined);
 		engine = null;
 	});

package/src/indexer/pipeline.ts

@@ -368,8 +368,7 @@ export async function indexCommits(
 
 /**
  * Per-storage-dir indexing lock so concurrent reindex runs (auto-index kick,
- * lazy search kick, manual /context-index; plus a future file watcher, #12)
- * can't interleave.
+ * lazy search kick, file watcher, manual /context-index) can't interleave.
  */
 const pipelineLocks = new Map<string, Promise<unknown>>();
 

package/src/indexer/watcher.ts

@@ -0,0 +1,195 @@
+/**
+ * Real-time reindex trigger — issue #12. A thin debounced wrapper around
+ * Node's built-in `fs.watch(dir, { recursive: true })` (one OS handle on
+ * Windows/macOS, inotify tree on Linux since Node 19.1).
+ *
+ * The watcher only produces a *change signal*: the incremental pipeline
+ * re-walks and re-hashes anyway, so false positives cost one cheap walk and
+ * only missed events matter. That is why the built-in suffices and neither
+ * chokidar (per-file stat-confirmed events, Node >= 22.22) nor
+ * @parcel/watcher (native addon, snapshot diffs) are needed.
+ *
+ * Filter semantics deliberately MIRROR the pipeline's inclusion policy
+ * (`targetExcluded` / `iterProjectFiles` in pipeline.ts), because a dropped
+ * event is the only unrecoverable failure mode: a wrongly accepted event just
+ * costs one cheap incremental run.
+ */
+import fs from "node:fs";
+import path from "node:path";
+import { DEFAULT_IGNORE, ROOT_ONLY_IGNORE } from "../config.js";
+
+/**
+ * Trailing-edge debounce for watcher events: long enough that a burst
+ * (editor save, `git checkout` rewriting many files) collapses into one
+ * kick, short enough that retrieval catches up quickly after an edit.
+ */
+export const WATCH_DEBOUNCE_MS = 1500;
+
+const ROOT_ONLY_SET = new Set(ROOT_ONLY_IGNORE);
+
+export interface ProjectWatcherOptions {
+	/** Called once per debounced change burst. Keep it cheap and sync. */
+	onChange: () => void;
+	/** Fatal watcher problem (e.g. Linux ENOSPC inotify exhaustion). The watcher closes itself; the caller falls back to session-start/lazy indexing. */
+	onError?: (err: Error) => void;
+	/** Defaults to {@link WATCH_DEBOUNCE_MS}. */
+	debounceMs?: number;
+	/**
+	 * Segment names ignored at ANY depth — defaults to `DEFAULT_IGNORE`; the
+	 * extension passes `config.indexerIgnore` so user additions apply too
+	 * (same set the walker checks via `ignoreSet.has(seg)`).
+	 */
+	ignoreSegments?: readonly string[];
+	/**
+	 * Absolute directories whose events are dropped entirely. The extension
+	 * passes the engine's storage dir when it points INSIDE the checkout:
+	 * every reindex rewrites `manifest.json` there unconditionally, so
+	 * without this exclusion a watcher kick would re-trigger itself forever
+	 * after source edits stop (PR #15 review, #12).
+	 */
+	ignorePaths?: readonly string[];
+}
+
+export class ProjectWatcher {
+	private watcher: fs.FSWatcher | null = null;
+	private debounceTimer: NodeJS.Timeout | null = null;
+	private stopped = false;
+	private watchRoot: string | null = null;
+	private readonly ignoreSet: Set<string>;
+	private ignorePaths: string[] = [];
+
+	constructor(
+		readonly dir: string,
+		private readonly options: ProjectWatcherOptions,
+	) {
+		this.ignoreSet = new Set(options.ignoreSegments ?? DEFAULT_IGNORE);
+	}
+
+	/** True while an OS watch handle is held. */
+	get watching(): boolean {
+		return this.watcher !== null;
+	}
+
+	/** Start watching. Returns false (after reporting via `onError`) when the watch could not be established — never throws. */
+	start(): boolean {
+		if (this.watcher) return true;
+		let watcher: fs.FSWatcher;
+		try {
+			// Canonicalize 8.3 short names first: on Windows,
+			// fs.watch({recursive}) hits an uncatchable libuv assertion
+			// (fs-event.c: `filename` vs watched dir prefix mismatch) that ABORTS
+			// the whole host process when the watched path has short-name
+			// components (common for os.tmpdir() and some tool-set cwds) and an
+			// event then reports the long name. realpathSync.native returns the
+			// canonical long path and avoids the mismatch entirely.
+			const dir = fs.realpathSync.native(this.dir);
+			this.watchRoot = dir;
+			this.ignorePaths = (this.options.ignorePaths ?? []).map((p) => {
+				try {
+					return fs.realpathSync.native(p);
+				} catch {
+					return path.resolve(p);
+				}
+			});
+			watcher = fs.watch(dir, { recursive: true }, (_event, filename) => this.onEvent(filename));
+		} catch (err) {
+			this.options.onError?.(err as Error);
+			return false;
+		}
+		this.watcher = watcher;
+		watcher.on("error", (err) => {
+			// E.g. inotify watch exhaustion on huge Linux trees. Close and let
+			// the caller degrade to session-start/lazy indexing — a watcher
+			// problem must never crash or stall the session.
+			this.closeWatcher();
+			if (!this.stopped) this.options.onError?.(err);
+		});
+		// Never keep the host process alive just for indexing.
+		watcher.unref?.();
+		return true;
+	}
+
+	private onEvent(filename: string | Buffer | null): void {
+		if (this.stopped || !this.watcher) return;
+		// No filename (happens, e.g. Linux inotify): cannot filter — a missed
+		// event is the unrecoverable failure mode, so accept and debounce it.
+		if (filename === null) {
+			this.scheduleKick();
+			return;
+		}
+		const name = Buffer.isBuffer(filename) ? filename.toString("utf-8") : filename;
+		if (name !== "" && this.isNoise(name)) return;
+		this.scheduleKick();
+	}
+
+	/**
+	 * Mirrors the walker's inclusion policy (see header): case-sensitive
+	 * segment match at any depth, root-only names only for the FIRST segment,
+	 * and explicit storage-dir path exclusion. Returns "noise" = drop event.
+	 */
+	private isNoise(filename: string): boolean {
+		const rel = this.relativeToRoot(filename);
+		if (rel === null) return false; // absolute path outside the watch root: be conservative, kick
+		const segments = rel.split(/[\\/]/).filter((s) => s !== "");
+		if (segments.length === 0) return false;
+		// Root-only names (`storage`, `logs`, `tmp`, ...) count only at the
+		// project root — nested `src/storage/` is real source the pipeline
+		// indexes, so its events must kick (PR #15 review).
+		if (ROOT_ONLY_SET.has(segments[0]!)) return true;
+		// Case-SENSITIVE like `ignoreSet.has(seg)`: the pipeline indexes
+		// `src/Build/`, so its events must not be dropped (PR #15 review).
+		if (segments.some((s) => this.ignoreSet.has(s))) return true;
+		return this.isUnderIgnoredPath(rel);
+	}
+
+	/** Relative path from the watch root, or null when outside/unknown. */
+	private relativeToRoot(filename: string): string | null {
+		if (!path.isAbsolute(filename)) return filename;
+		const rel = path.relative(this.watchRoot ?? this.dir, filename);
+		if (rel === "" || rel.startsWith("..") || path.isAbsolute(rel)) return null;
+		return rel;
+	}
+
+	/** True when the event's resolved path lives under an ignored dir (e.g. an in-project storage dir). */
+	private isUnderIgnoredPath(rel: string): boolean {
+		if (this.ignorePaths.length === 0 || this.watchRoot === null) return false;
+		const abs = path.resolve(this.watchRoot, rel);
+		const fold = (p: string) => (process.platform === "win32" ? p.toLowerCase() : p);
+		const absFolded = fold(abs);
+		return this.ignorePaths.some((p) => {
+			const ignored = fold(p);
+			return absFolded === ignored || absFolded.startsWith(ignored + path.sep);
+		});
+	}
+
+	private scheduleKick(): void {
+		if (this.debounceTimer) clearTimeout(this.debounceTimer);
+		this.debounceTimer = setTimeout(() => {
+			this.debounceTimer = null;
+			// `stopped` mid-debounce, or the watcher died (error path) while
+			// the timer was pending: no kick.
+			if (this.stopped || !this.watcher) return;
+			this.options.onChange();
+		}, this.options.debounceMs ?? WATCH_DEBOUNCE_MS);
+		this.debounceTimer.unref?.();
+	}
+
+	/** Stop watching and cancel any pending debounced kick. Idempotent. */
+	stop(): void {
+		this.stopped = true;
+		if (this.debounceTimer) {
+			clearTimeout(this.debounceTimer);
+			this.debounceTimer = null;
+		}
+		this.closeWatcher();
+	}
+
+	private closeWatcher(): void {
+		try {
+			this.watcher?.close();
+		} catch {
+			// already closed by the runtime
+		}
+		this.watcher = null;
+	}
+}

package/src/retrieval/reranker.ts

@@ -56,6 +56,8 @@ export class LocalReranker implements RerankerLike {
 	private loading: Promise<LoadedReranker | null> | null = null;
 	/** Set after a load failure; every later call short-circuits to no-op. */
 	failed = false;
+	/** Why the load failed (null before any attempt). Surfaced by /context-warmup. */
+	loadError: string | null = null;
 
 	constructor(
 		readonly model: string,
@@ -88,6 +90,17 @@ export class LocalReranker implements RerankerLike {
 		}
 	}
 
+	/**
+	 * Force the model load now (issue #11, upstream warmup): downloads and
+	 * initializes the cross-encoder without needing a query. Returns false
+	 * when the load failed — the reranker then stays a silent no-op, per its
+	 * degrade-never-break design; `loadError` carries the reason.
+	 */
+	async warm(): Promise<boolean> {
+		if (this.failed) return false;
+		return (await this.ensureLoaded()) !== null;
+	}
+
 	private ensureLoaded(): Promise<LoadedReranker | null> {
 		if (this.loaded) return Promise.resolve(this.loaded);
 		if (!this.loading) {
@@ -102,8 +115,9 @@ export class LocalReranker implements RerankerLike {
 				});
 				this.loaded = { tokenizer, model };
 				return this.loaded;
-			})().catch(() => {
+			})().catch((err: unknown) => {
 				this.failed = true;
+				this.loadError = err instanceof Error ? err.message : String(err);
 				return null;
 			});
 		}