fix(server): bound startup file discovery

AGENTS.md

@@ -141,6 +141,7 @@ claude --plugin-dir ./apps/hook
 | `PLANNOTATOR_ANNOTATE_HISTORY` | Set to `0` / `false` to disable per-file version history in annotate mode (no copies of annotated files are written to the data dir; the annotate version diff is unavailable). Default: enabled. Can also be set via `~/.plannotator/config.json` (`{ "annotateHistory": false }`); the env var takes precedence. |
 | `JINA_API_KEY` | Optional Jina Reader API key for higher rate limits (500 RPM vs 20 RPM unauthenticated). Free keys include 10M tokens. |
 | `PLANNOTATOR_DATA_DIR` | Override the base data directory. Supports `~` expansion. Default: `~/.plannotator`. All data (plans, history, drafts, config, hooks, sessions, debug logs, IPC registry) is stored under this directory. |
+| `PLANNOTATOR_FILE_BROWSER_MAX_FILES` | File-discovery limit: regular files inspected by CLI markdown/folder resolution and startup code-file warming, and supported files returned by the file browser. Must be a positive integer; invalid, zero, or negative values use the default of `5000`. |
 | `PLANNOTATOR_GLIMPSE` | Set to `0` / `false` to disable the Glimpse native window even when `glimpseui` is installed. Default: enabled. Can also be set via `~/.plannotator/config.json` (`{ "glimpse": false }`). |
 | `PLANNOTATOR_GLIMPSE_WIDTH` | Width in pixels for the Glimpse native window. Default: `1280`. |
 | `PLANNOTATOR_GLIMPSE_HEIGHT` | Height in pixels for the Glimpse native window. Default: `900`. |

apps/pi-extension/server.test.ts

@@ -13,11 +13,13 @@ import {
   runGitDiff,
   runVcsDiff,
   stageFile,
+  startAnnotateServer,
   startPlanReviewServer,
   startReviewServer,
   unstageFile,
 } from "./server";
 import { WorkspaceReviewSession } from "./generated/review-workspace.js";
+import { warmFileListCache } from "./generated/resolve-file.js";
 
 const tempDirs: string[] = [];
 const originalCwd = process.cwd();
@@ -26,6 +28,7 @@ const originalXdgConfigHome = process.env.XDG_CONFIG_HOME;
 const originalPort = process.env.PLANNOTATOR_PORT;
 const originalSemPath = process.env.PLANNOTATOR_SEM_PATH;
 const originalDataDir = process.env.PLANNOTATOR_DATA_DIR;
+const originalFileBrowserLimit = process.env.PLANNOTATOR_FILE_BROWSER_MAX_FILES;
 
 function makeTempDir(prefix: string): string {
   const dir = mkdtempSync(join(tmpdir(), prefix));
@@ -207,12 +210,70 @@ afterEach(() => {
   } else {
     process.env.PLANNOTATOR_DATA_DIR = originalDataDir;
   }
+  if (originalFileBrowserLimit === undefined) {
+    delete process.env.PLANNOTATOR_FILE_BROWSER_MAX_FILES;
+  } else {
+    process.env.PLANNOTATOR_FILE_BROWSER_MAX_FILES = originalFileBrowserLimit;
+  }
 
   for (const dir of tempDirs.splice(0)) {
     rmSync(dir, { recursive: true, force: true });
   }
 });
 
+function observePiWarmState(projectRoot: string): Promise<"ready" | "warm"> {
+  const warm = warmFileListCache(projectRoot, "code").then(() => "warm" as const);
+  const ready = new Promise<"ready">((resolve) => {
+    queueMicrotask(() => resolve("ready"));
+  });
+  return Promise.race([warm, ready]);
+}
+
+async function expectPiReadyBeforeWarm(
+  start: () => Promise<{ url: string; stop(): void }>,
+): Promise<void> {
+  const projectRoot = makeTempDir("plannotator-pi-startup-warm-");
+  const dataRoot = makeTempDir("plannotator-pi-startup-data-");
+  writeTempFile(projectRoot, "document.md", "# Test\n");
+  writeTempFile(projectRoot, "source.ts", "export {};\n");
+  process.chdir(projectRoot);
+  process.env.PLANNOTATOR_DATA_DIR = dataRoot;
+  process.env.PLANNOTATOR_FILE_BROWSER_MAX_FILES = "1";
+  process.env.PLANNOTATOR_PORT = String(await reservePort());
+
+  const server = await start();
+  try {
+    expect(await observePiWarmState(process.cwd())).toBe("ready");
+    const response = await fetch(`${server.url}/api/plan`);
+    expect(response.status).toBe(200);
+  } finally {
+    server.stop();
+  }
+}
+
+describe("pi startup file-cache warm", () => {
+  test("plan server binds before its cache warm can settle", async () => {
+    await expectPiReadyBeforeWarm(() =>
+      startPlanReviewServer({
+        plan: "# Test plan",
+        origin: "pi",
+        htmlContent: "<!doctype html><html><body>plan</body></html>",
+      }),
+    );
+  });
+
+  test("annotate server binds before its cache warm can settle", async () => {
+    await expectPiReadyBeforeWarm(() =>
+      startAnnotateServer({
+        markdown: "# Test document",
+        filePath: join(process.cwd(), "document.md"),
+        htmlContent: "<!doctype html><html><body>annotate</body></html>",
+        origin: "pi",
+      }),
+    );
+  });
+});
+
 describe("pi review server", () => {
   const testIfJj = hasJj() ? test : test.skip;
   const semanticRawPatch = [

apps/pi-extension/server/serverAnnotate.ts

@@ -180,8 +180,6 @@ export async function startAnnotateServer(options: {
 	/** Project name for keying per-file version history (powers the annotate version diff). */
 	project?: string;
 }): Promise<AnnotateServerResult> {
-	// Side-channel pre-warm so /api/doc/exists POSTs land on warm cache.
-	void warmFileListCache(process.cwd(), "code");
 	const gitUser = detectGitUser();
 	const sharingEnabled =
 		options.sharingEnabled ?? resolveSharingEnabled(loadConfig());
@@ -651,6 +649,9 @@ export async function startAnnotateServer(options: {
 
 	const { port, portSource } = await listenOnPort(server);
 
+	// Mirror the Bun server: bind first, then warm through the async shared walk.
+	void warmFileListCache(process.cwd(), "code");
+
 	return {
 		port,
 		portSource,

apps/pi-extension/server/serverPlan.ts

@@ -84,8 +84,6 @@ export async function startPlanReviewServer(options: {
 	mode?: "archive";
 	customPlanPath?: string | null;
 }): Promise<PlanServerResult> {
-	// Side-channel pre-warm so /api/doc/exists POSTs land on warm cache.
-	void warmFileListCache(process.cwd(), "code");
 	const gitUser = detectGitUser();
 	const sharingEnabled =
 		options.sharingEnabled ?? resolveSharingEnabled(loadConfig());
@@ -453,6 +451,9 @@ export async function startPlanReviewServer(options: {
 
 	const { port, portSource } = await listenOnPort(server);
 
+	// Mirror the Bun server: bind first, then warm through the async shared walk.
+	void warmFileListCache(process.cwd(), "code");
+
 	return {
 		reviewId,
 		port,

packages/server/annotate.ts

@@ -135,9 +135,6 @@ const RETRY_DELAY_MS = 500;
 export async function startAnnotateServer(
   options: AnnotateServerOptions
 ): Promise<AnnotateServerResult> {
-  // Side-channel pre-warm so /api/doc/exists POSTs land on warm cache.
-  void warmFileListCache(process.cwd(), "code");
-
   const {
     markdown,
     filePath,
@@ -747,6 +744,10 @@ export async function startAnnotateServer(
   const port = server.port!;
   const serverUrl = `http://localhost:${port}`;
 
+  // The cache warm must never gate the listening socket. Its async filesystem
+  // walk yields between directories while requests remain serviceable.
+  void warmFileListCache(process.cwd(), "code");
+
   // Notify caller that server is ready
   if (onReady) {
     onReady(serverUrl, isRemote, port);

packages/server/index.ts

@@ -135,10 +135,6 @@ export async function startPlannotatorServer(
   const wslFlag = await isWSL();
   const gitUser = detectGitUser();
 
-  // Side-channel pre-warm: kick off the code-file walk now so the
-  // renderer's POST /api/doc/exists lands on warm cache.
-  void warmFileListCache(process.cwd(), "code");
-
   // --- Archive mode setup ---
   let archivePlans: ArchivedPlan[] = [];
   let initialArchivePlan = "";
@@ -614,6 +610,10 @@ export async function startPlannotatorServer(
   const port = server.port!;
   const serverUrl = `http://localhost:${port}`;
 
+  // The cache warm must never gate the listening socket. Its async filesystem
+  // walk yields between directories while requests remain serviceable.
+  void warmFileListCache(process.cwd(), "code");
+
   // Notify caller that server is ready
   if (onReady) {
     onReady(serverUrl, isRemote, port);

packages/server/reference-handlers.ts

@@ -24,6 +24,7 @@ import {
 	resolveMarkdownFile,
 	resolveUserPath,
 	isWithinProjectRoot,
+	getFileBrowserMaxFiles,
 	warmFileListCache,
 } from "@plannotator/shared/resolve-file";
 import { htmlToMarkdown } from "@plannotator/shared/html-to-markdown";
@@ -543,17 +544,11 @@ export async function handleObsidianDoc(req: Request): Promise<Response> {
 // --- File Browser ---
 
 const FILE_BROWSER_EXTENSIONS = /\.(mdx?|txt|html?)$/i;
-const DEFAULT_FILE_BROWSER_MAX_FILES = 5_000;
 
 function includeWorkspaceFile(relativePath: string, _change: WorkspaceFileChange): boolean {
 	return FILE_BROWSER_EXTENSIONS.test(relativePath) && !isFileBrowserExcludedPath(relativePath);
 }
 
-function getFileBrowserMaxFiles(): number {
-	const value = Number.parseInt(process.env.PLANNOTATOR_FILE_BROWSER_MAX_FILES ?? "", 10);
-	return Number.isFinite(value) && value > 0 ? value : DEFAULT_FILE_BROWSER_MAX_FILES;
-}
-
 type FileBrowserWalkState = {
 	files: Set<string>;
 	limit: number;

packages/server/startup-warm.test.ts

@@ -0,0 +1,105 @@
+import { describe, expect, test } from "bun:test";
+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { warmFileListCache } from "@plannotator/shared/resolve-file";
+import { startAnnotateServer } from "./annotate";
+import { startPlannotatorServer } from "./index";
+
+const MINIMAL_HTML = "<html><body>Plannotator</body></html>";
+
+type StartedServer = {
+	readonly url: string;
+	stop(): void;
+};
+
+type ReadyCallback = (url: string, isRemote: boolean, port: number) => void;
+
+function observeWarmState(projectRoot: string): Promise<"ready" | "warm"> {
+	const warm = warmFileListCache(projectRoot, "code").then(() => "warm" as const);
+	const ready = new Promise<"ready">((resolve) => {
+		queueMicrotask(() => resolve("ready"));
+	});
+	return Promise.race([warm, ready]);
+}
+
+async function expectReadyBeforeWarm(
+	start: (onReady: ReadyCallback) => Promise<StartedServer>,
+): Promise<void> {
+	const projectRoot = mkdtempSync(join(tmpdir(), "plannotator-startup-warm-"));
+	const dataRoot = mkdtempSync(join(tmpdir(), "plannotator-startup-data-"));
+	const previousCwd = process.cwd();
+	const previousPort = process.env.PLANNOTATOR_PORT;
+	const previousRemote = process.env.PLANNOTATOR_REMOTE;
+	const previousDataDir = process.env.PLANNOTATOR_DATA_DIR;
+	const previousLimit = process.env.PLANNOTATOR_FILE_BROWSER_MAX_FILES;
+	let server: StartedServer | null = null;
+	let ordering: Promise<"ready" | "warm"> | null = null;
+
+	try {
+		writeFileSync(join(projectRoot, "document.md"), "# Test\n");
+		writeFileSync(join(projectRoot, "source.ts"), "export {};\n");
+		process.chdir(projectRoot);
+		delete process.env.PLANNOTATOR_PORT;
+		process.env.PLANNOTATOR_REMOTE = "0";
+		process.env.PLANNOTATOR_DATA_DIR = dataRoot;
+		process.env.PLANNOTATOR_FILE_BROWSER_MAX_FILES = "1";
+
+		server = await start(() => {
+			// Observe with the server's OWN cache key: process.cwd() inside onReady
+			// is the realpath (on macOS mkdtemp returns /var/... but cwd resolves to
+			// /private/var/...), and a key mismatch would race a FRESH warm instead
+			// of the server's, making the test pass on any code.
+			ordering = observeWarmState(process.cwd());
+		});
+
+		const observedOrdering = ordering;
+		if (!observedOrdering) {
+			throw new Error("Server did not invoke its ready callback");
+		}
+		expect(await observedOrdering).toBe("ready");
+
+		const response = await fetch(`${server.url}/api/plan`);
+		expect(response.status).toBe(200);
+	} finally {
+		server?.stop();
+		process.chdir(previousCwd);
+		if (previousPort === undefined) delete process.env.PLANNOTATOR_PORT;
+		else process.env.PLANNOTATOR_PORT = previousPort;
+		if (previousRemote === undefined) delete process.env.PLANNOTATOR_REMOTE;
+		else process.env.PLANNOTATOR_REMOTE = previousRemote;
+		if (previousDataDir === undefined) delete process.env.PLANNOTATOR_DATA_DIR;
+		else process.env.PLANNOTATOR_DATA_DIR = previousDataDir;
+		if (previousLimit === undefined) {
+			delete process.env.PLANNOTATOR_FILE_BROWSER_MAX_FILES;
+		} else {
+			process.env.PLANNOTATOR_FILE_BROWSER_MAX_FILES = previousLimit;
+		}
+		rmSync(projectRoot, { recursive: true, force: true });
+		rmSync(dataRoot, { recursive: true, force: true });
+	}
+}
+
+describe("startup file-cache warm", () => {
+	test("Bun plan server binds before its cache warm can settle", async () => {
+		await expectReadyBeforeWarm((onReady) =>
+			startPlannotatorServer({
+				plan: "# Test plan",
+				origin: "codex",
+				htmlContent: MINIMAL_HTML,
+				onReady,
+			}),
+		);
+	});
+
+	test("Bun annotate server binds before its cache warm can settle", async () => {
+		await expectReadyBeforeWarm((onReady) =>
+			startAnnotateServer({
+				markdown: "# Test document",
+				filePath: join(process.cwd(), "document.md"),
+				htmlContent: MINIMAL_HTML,
+				onReady,
+			}),
+		);
+	});
+});