@workweave/router 0.2.10 → 0.2.11

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@workweave/router",
-  "version": "0.2.10",
+  "version": "0.2.11",
   "description": "One-command installer that points Claude Code, Codex, opencode, or pi at the Weave Router. For pi it also ships the routing extension, loaded via pi.extensions.",
   "bin": {
     "weave-router": "bin.js",
@@ -9,6 +9,9 @@
   "pi": {
     "extensions": [
       "./pi-router/src/index.ts"
+    ],
+    "skills": [
+      "./pi-router/skills"
     ]
   },
   "files": [
@@ -16,6 +19,8 @@
     "install.sh",
     "uninstall.sh",
     "cc-statusline.sh",
+    "registry.sh",
+    "directives.tsv",
     "commands/",
     "codex-skills/",
     "pi-router/",

package/pi-router/README.md

@@ -11,6 +11,7 @@ Installed automatically by the Weave Router installer:
 ```bash
 WEAVE_ROUTER_KEY=rk_… npx --package @workweave/router -y -- weave-router --pi
 WEAVE_ROUTER_KEY=rk_… npx --package @workweave/router -y -- weave-router --pi --local  # local router
+WEAVE_ROUTER_KEY=rk_… npx --package @workweave/router -y -- weave-router --pi --lsp go,typescript  # + language servers for the lsp tool
 ```
 
 That writes `~/.pi/agent/models.json` (the `weave` provider), adds
@@ -32,17 +33,37 @@ from npm on next start and loads this extension via its `pi.extensions` field.
   router validates and canonicalizes the requested model.
 - **Per-process routing bias.** Static `x-weave-routing-*` knob headers bias the
   router: quality on the main loop and speed + cheap on subagents.
-- **Long tool-loop compaction.** Pi 0.74 can cross its context threshold inside
-  an uninterrupted tool loop before its normal post-run compaction check. The
-  extension preserves a usable output budget for the real continuation and
-  compacts once the loop settles, while leaving ordinary threshold compaction
-  to Pi.
+- **Long tool-loop compaction.** Pi can cross its context threshold inside an
+  uninterrupted tool loop before its normal post-run compaction check. The
+  extension preserves a usable output budget for the real continuation,
+  compacts once the loop settles, and resumes that extension-owned tool loop.
+  Ordinary Pi threshold compaction remains under Pi's control.
 - **Sticky sessions.** `metadata.user_id = "pi:<sessionId>"` pins the main loop
   to one model for the session; subagents get their own pins.
 - **`dispatch` tool — parallel, context-isolated subagents.** pi has none
   natively. `dispatch` spawns child `pi` processes (read-only by default), runs
   them concurrently, and returns only each subagent's final answer — intermediate
   tool output stays in the child, so the main context stays small.
+- **`lsp` tool — code intelligence through a language server.** definition,
+  references, hover, documentSymbol, and diagnostics for Go, TypeScript/
+  JavaScript, Python, and Rust (gopls, typescript-language-server, pyright,
+  rust-analyzer). Servers are spawned lazily per workspace root, shut down
+  after idling, and shared with dispatch subagents through a parent-side local
+  socket — a fan-out reuses the parent's warm servers instead of cold-starting
+  its own. A bundled `lsp-guide` skill (`/skill:lsp-guide`) carries the usage
+  recipes (per-operation cookbook, the locate-then-references flow, caveats).
+  Disable with `WEAVE_PI_NO_LSP=1`.
+- **Opt-in language-server install — nothing installs silently.** Two ways in:
+  pass `--lsp go,typescript` to the installer, or let the assistant offer.
+  When the workspace contains a language whose server is missing, the
+  assistant offers once in conversation ("I can enable go LSP support if
+  you'd like — just say the word!"); a yes runs the install through the
+  `lsp_enable` tool (main process only — subagents can't trigger installs), a
+  "don't ask again" is persisted per language in `<agentDir>/.weave_lsp.json`
+  and respected across sessions. Installs need that language's toolchain
+  (`go`, `npm`, or `rustup`) on PATH; when the toolchain itself is missing,
+  the bundled `install-lsps` skill (`/skill:install-lsps`) walks the agent
+  through installing it — again only with explicit consent.
 - **Persistent route + savings display.** Shows
   `WEAVE ROUTER — <routed> ← <selected> · saved $X.XX` below pi's native footer
   data. Savings compare the selected and routed catalog prices against the same
@@ -70,9 +91,17 @@ from npm on next start and loads this extension via its `pi.extensions` field.
 | `WEAVE_ROUTING_ALPHA` / `…_SPEED_WEIGHT` / `…_OUTPUT_COST_RATIO` / `…_EXPECTED_OUTPUT_TOKENS` | role preset | Override individual routing knobs (main process only — children always use their role preset) |
 | `WEAVE_NO_SAFETY` | unset | `1` disables the catastrophic-bash gate |
 | `WEAVE_PI_AUTO_COMPACTION` | unset | `0` disables the routed tool-loop compaction safeguard |
+| `WEAVE_PI_NO_LSP` | unset | `1` disables the `lsp` tool, the server pool, and the subagent broker |
+| `WEAVE_PI_LSP_IDLE_MS` | `300000` | Idle window before an unused language server is shut down |
+| `WEAVE_PI_LSP_REQUEST_TIMEOUT_MS` | `15000` | Per-request budget once a server is warm |
+| `WEAVE_PI_LSP_WARMUP_TIMEOUT_MS` | `60000` | Budget for initialize + the first query (indexing) |
+| `WEAVE_PI_LSP_DIAGNOSTICS_WAIT_MS` | `3000` | How long `diagnostics` waits for a fresh publish |
+| `WEAVE_PI_LSP_MAX_SERVERS` | `4` | LRU cap on concurrently live language servers |
+| `WEAVE_PI_LSP_MAX_REFERENCES` | `100` | Cap on reported reference sites |
 
-Internal: `WEAVE_PI_SUBAGENT=1` and `WEAVE_PI_SUBAGENT_ID` are set by `dispatch`
-on child processes; don't set them yourself.
+Internal: `WEAVE_PI_SUBAGENT=1`, `WEAVE_PI_SUBAGENT_ID`, `WEAVE_PI_LSP_BROKER`,
+and `WEAVE_PI_LSP_BROKER_TOKEN` are set by `dispatch` on child processes; don't
+set them yourself.
 
 ## Billing
 

package/pi-router/skills/install-lsps/SKILL.md

@@ -0,0 +1,75 @@
+---
+name: install-lsps
+description: Install language servers (gopls, typescript-language-server, pyright, rust-analyzer) and their prerequisite toolchains (Go, Node/npm, rustup) so the lsp tool works. Use when the user asks to enable or install LSP / language-server support, when lsp_enable reports a missing toolchain, or when the lsp tool reports no language server is installed.
+---
+
+# Install LSPs
+
+Enable the `lsp` tool for a language by installing its language server — and,
+when the server install needs it, the underlying toolchain.
+
+## Rules
+
+- Everything here is consent-gated: only act on the user's explicit go-ahead,
+  and confirm each toolchain install separately — those are system-level
+  changes, not part of whatever task prompted this.
+- If the user declines, stop. If they ask not to be offered again, call
+  `lsp_enable` with `{"language": "<language>", "action": "dismiss"}`.
+- Prefer the `lsp_enable` tool over bash whenever the toolchain already
+  exists; reach for bash only for the prerequisites `lsp_enable` refuses to
+  install itself.
+
+## Per language
+
+Work the ladder for each language the user wants:
+
+1. **Check what is missing.** Server binaries: `gopls`,
+   `typescript-language-server`, `pyright-langserver` (or
+   `basedpyright-langserver`), `rust-analyzer` — also look in `~/go/bin` and
+   `~/.cargo/bin`, which the lsp tool searches even when they are off PATH.
+   Toolchains: `go`, `npm`, `rustup`.
+2. **Toolchain present** → call `lsp_enable` with
+   `{"language": "<go|typescript|python|rust>"}` and you are done; it runs the
+   right server install and verifies the binary resolves.
+3. **Toolchain missing** → show the user the command you intend to run, get
+   their confirmation, run it in bash, then return to step 2.
+4. **Verify** with a real `lsp` query (`documentSymbol` on an actual source
+   file). The first query per workspace can take up to a minute while the
+   server indexes; that is normal.
+
+## Toolchain installs (step 3 reference)
+
+Go (for gopls):
+
+```bash
+brew install go            # macOS
+sudo apt-get install -y golang-go   # Debian/Ubuntu; or dnf install golang
+```
+
+Or the official downloads at https://go.dev/dl for anything else.
+
+Node/npm (for typescript-language-server and pyright):
+
+```bash
+brew install node          # macOS
+sudo apt-get install -y nodejs npm  # Debian/Ubuntu
+```
+
+Or nvm (https://github.com/nvm-sh/nvm) when the user prefers per-user installs.
+
+rustup (for rust-analyzer):
+
+```bash
+curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
+```
+
+This is the official rust installer; show the user the command before running
+it and follow its printed PATH instructions afterwards.
+
+## Notes
+
+- `go install` drops gopls in `~/go/bin` and rustup drops rust-analyzer in
+  `~/.cargo/bin`. The lsp tool finds both without PATH changes; other tools
+  may still want a PATH entry.
+- All of this can also happen at install time:
+  `npx @workweave/router --pi --lsp go,typescript,python,rust`.

package/pi-router/skills/lsp-guide/SKILL.md

@@ -0,0 +1,63 @@
+---
+name: lsp-guide
+description: Recipes for the lsp tool — resolving where a symbol is defined, every place it is used, type signatures and docs, file outlines, and compiler/type errors through a real language server (Go, TypeScript/JavaScript, Python, Rust). Use when navigating or explaining code by symbol, finding callers or usages, checking what broke after an edit, or deciding between lsp and text search.
+---
+
+# Using the lsp tool
+
+The `lsp` tool answers *semantic* questions through the language's own server:
+it resolves through imports, types, and aliases, where grep only matches text.
+Reach for it whenever the question is about a **symbol**; keep grep for plain
+strings, comments, and file types no server supports.
+
+## Operations
+
+| Operation | Answers | Needs |
+|---|---|---|
+| `definition` | where the symbol at a position is defined | `path`, `line`, `column` |
+| `references` | every place the symbol at a position is used | `path`, `line`, `column` |
+| `hover` | type signature + docs for the symbol at a position | `path`, `line`, `column` |
+| `documentSymbol` | the outline (types, functions, methods) of one file | `path` |
+| `diagnostics` | compiler/type errors and warnings for one file | `path` |
+
+Positions are 1-based, and `column` must point **at the identifier** (its first
+character works). All paths resolve against the working directory.
+
+## Recipes
+
+**"Where is X defined?"** — from any usage site of X:
+`{"operation": "definition", "path": "<file>", "line": <L>, "column": <C>}`.
+Don't know a usage site? Find one first (see next recipe's step 1).
+
+**"Everywhere X is used"** — two steps, always:
+
+1. Locate the declaration: `rg -n --column '\bX\b'` (the `--column` output is
+   exactly the coordinate the next call needs), or `documentSymbol` when you
+   already know the file.
+2. `{"operation": "references", "path": "<decl file>", "line": <L>, "column": <C>}`.
+
+A grep hit list is **not** a references answer: it includes comments and
+strings, misses aliased imports, and can't distinguish same-named symbols.
+Step 2 is what makes the answer authoritative.
+
+**"What is this / what's its signature?"** — `hover` at the symbol. Prefer it
+over reading the definition file when you only need the type or doc comment.
+
+**"What's in this file?"** — `documentSymbol` before reading a large file; jump
+straight to the line the outline gives you.
+
+**"Did my edit break anything here?"** — `diagnostics` on the file after
+editing. It reports the server's current analysis of the saved file.
+
+## Behavior worth knowing
+
+- **First query per workspace is slow** (the server indexes — up to a minute
+  in a big repo). Later queries on that workspace are fast; don't give up
+  after one timeout, retry once.
+- **References are capped** (default 100, header says how many exist).
+- **Unsupported file type or missing server** returns advice text, not an
+  error — fall back to grep for that file. A missing server can be installed
+  with the user's consent via `lsp_enable` (see the install-lsps skill for
+  toolchain prerequisites).
+- Works inside dispatch subagents too (they share the parent's warm servers),
+  so symbol lookups are safe to fan out.

package/pi-router/src/compaction.ts

@@ -21,11 +21,15 @@ import type {
 	TurnEndEvent,
 } from "@mariozechner/pi-coding-agent";
 import type { AssistantMessage } from "@mariozechner/pi-ai";
+import { ROUTED_CONTEXT_WINDOW_HEADER } from "./config.js";
+import { parseRoutedContextWindow } from "./context-window.js";
 
 const PROBE_MAX_TOKENS = 4;
 const CONTINUATION_MAX_TOKENS = 16_384;
 const COMPACTION_RESERVE_TOKENS = 16_384;
 const STATUS_KEY = "weave-compaction";
+/** Pi does not retry threshold compaction automatically, so resume our tool loop explicitly. */
+export const ROUTED_COMPACTION_CONTINUATION = "Continue from the compacted context. Pick up exactly where you left off.";
 
 interface ProviderPayload {
 	max_tokens?: unknown;
@@ -86,11 +90,20 @@ export function registerCompaction(pi: ExtensionAPI, schedule: Schedule = (callb
 	let lastTurnTokens = 0;
 	let repairedContinuation = false;
 	let compactionScheduled = false;
+	// Smallest served context window observed on a response this run. The router
+	// can reroute any request regardless of the requested model, so the served
+	// window is authoritative for the compaction budget. Tracking the minimum
+	// (not the latest or the max) is the conservative choice: if the router ever
+	// routed to a smaller window during the run, that window could clamp again,
+	// so the budget must respect it. Fall back to the registered model window
+	// until the first routed response.
+	let servedContextWindow: number | undefined;
 
 	const resetRun = () => {
 		highWaterTokens = 0;
 		lastTurnTokens = 0;
 		repairedContinuation = false;
+		servedContextWindow = undefined;
 	};
 
 	const finishCompaction = (ctx: ExtensionContext) => {
@@ -107,6 +120,15 @@ export function registerCompaction(pi: ExtensionAPI, schedule: Schedule = (callb
 		if (repairClampedToolContinuation(event.payload)) repairedContinuation = true;
 	});
 
+	pi.on("after_provider_response", (event, _ctx: ExtensionContext) => {
+		if (event.status < 200 || event.status >= 300) return;
+		const contextWindow = parseRoutedContextWindow(event.headers?.[ROUTED_CONTEXT_WINDOW_HEADER]);
+		if (contextWindow === undefined) return;
+		if (servedContextWindow === undefined || contextWindow < servedContextWindow) {
+			servedContextWindow = contextWindow;
+		}
+	});
+
 	pi.on("turn_end", (event: TurnEndEvent) => {
 		if (event.message.role !== "assistant") return;
 		lastTurnTokens = contextTokens(event.message as AssistantMessage);
@@ -115,14 +137,19 @@ export function registerCompaction(pi: ExtensionAPI, schedule: Schedule = (callb
 
 	pi.on("agent_end", (_event: AgentEndEvent, ctx: ExtensionContext) => {
 		if (process.env.WEAVE_PI_AUTO_COMPACTION === "0" || compactionScheduled) return;
-		const contextWindow = ctx.model?.contextWindow ?? ctx.getContextUsage()?.contextWindow ?? 0;
+		const registeredWindow = ctx.model?.contextWindow ?? ctx.getContextUsage()?.contextWindow ?? 0;
+		const contextWindow = servedContextWindow ?? registeredWindow;
 		if (contextWindow <= COMPACTION_RESERVE_TOKENS) return;
-		const threshold = contextWindow - COMPACTION_RESERVE_TOKENS;
-		// Pi's built-in check runs immediately after this event and owns the
-		// ordinary final-turn threshold case. Starting another compaction while
-		// that async summary is in flight would race it.
-		if (lastTurnTokens > threshold) return;
-		if (!repairedContinuation && highWaterTokens <= threshold) return;
+		const servedThreshold = contextWindow - COMPACTION_RESERVE_TOKENS;
+		const registeredThreshold = registeredWindow - COMPACTION_RESERVE_TOKENS;
+		// Pi's built-in check runs immediately after this event and budgets against
+		// the REGISTERED model window. If the final turn clears Pi's registered
+		// threshold, Pi will compact asynchronously — deferring is correct, and
+		// scheduling our own would race that async compaction. Otherwise Pi will not
+		// act, so we compact ourselves when the run crossed the SERVED threshold
+		// (which can be smaller than the registered window after a reroute).
+		if (lastTurnTokens > registeredThreshold) return;
+		if (!repairedContinuation && highWaterTokens <= servedThreshold) return;
 
 		compactionScheduled = true;
 		const previousCompactionId = latestCompactionId(ctx);
@@ -139,7 +166,18 @@ export function registerCompaction(pi: ExtensionAPI, schedule: Schedule = (callb
 			}
 			if (ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, "compacting routed context...");
 			ctx.compact({
-				onComplete: () => finishCompaction(ctx),
+				onComplete: () => {
+					finishCompaction(ctx);
+					// Pi only auto-retries an overflow compaction. This compaction is
+					// extension-owned and follows a routed tool loop, so queue the next
+					// turn after its summary is committed rather than leaving the agent idle.
+					// A user may have started another turn while the compaction ran; in
+					// that case Pi requires an explicit follow-up delivery mode.
+					pi.sendUserMessage(
+						ROUTED_COMPACTION_CONTINUATION,
+						ctx.isIdle() ? undefined : { deliverAs: "followUp" },
+					);
+				},
 				onError: (error) => {
 					compactionScheduled = false;
 					if (ctx.hasUI) ctx.ui.setStatus(STATUS_KEY, `compaction failed: ${error.message}`);

package/pi-router/src/config.ts

@@ -71,6 +71,11 @@ export function getKeyFilePath(): string {
 	return process.env.WEAVE_ROUTER_KEY_FILE?.trim() || path.join(getAgentDir(), ".weave_router_key");
 }
 
+/** Persisted LSP preferences (per-language "don't offer again" dismissals). */
+export function getLspPrefsPath(): string {
+	return path.join(getAgentDir(), ".weave_lsp.json");
+}
+
 interface WeaveProviderConfig {
 	baseUrl?: string;
 	apiKey?: string;
@@ -220,12 +225,17 @@ export function providerHeaders(role: Role, key: string): Record<string, string>
 // dispatched child (and a `pi -e` smoke test with no models.json) can still
 // resolve `weave/<model>`. The list mirrors the installer's headline models;
 // the router re-routes every request regardless, so this is a UX/label surface.
+// The context windows mirror the router's catalog for these models (see
+// internal/router/catalog) so the footer and auto-compaction budget reflect
+// what the router actually serves; per-request reroutes can still land on a
+// different window, which the served-window header reports on the response.
 export const WEAVE_MODELS: ProviderModelConfig[] = [
-	model("claude-opus-4-8", "Claude Opus 4.8 (via Weave Router)", 64000),
-	model("claude-opus-4-7", "Claude Opus 4.7 (via Weave Router)", 64000),
-	model("claude-sonnet-4-6", "Claude Sonnet 4.6 (via Weave Router)", 64000),
-	model("claude-haiku-4-5", "Claude Haiku 4.5 (via Weave Router)", 32000),
-	model("grok-4.6", "Grok 4.6 (via Weave Router)", 131072, 500000),
+	model("claude-opus-4-8", "Claude Opus 4.8 (via Weave Router)", 64000, 1_000_000),
+	model("claude-opus-4-7", "Claude Opus 4.7 (via Weave Router)", 64000, 1_000_000),
+	model("claude-sonnet-4-6", "Claude Sonnet 4.6 (via Weave Router)", 64000, 1_000_000),
+	model("claude-haiku-4-5", "Claude Haiku 4.5 (via Weave Router)", 32000, 200_000),
+	model("grok-4.6", "Grok 4.6 (via Weave Router)", 131072, 500_000),
+	model("qwen/qwen3.8-max", "Qwen 3.8 Max (via Weave Router)", 131072, 1_000_000),
 ];
 
 function model(id: string, name: string, maxTokens: number, contextWindow: number = 200000): ProviderModelConfig {
@@ -246,6 +256,8 @@ function model(id: string, name: string, maxTokens: number, contextWindow: numbe
 export const ROUTED_MODEL_HEADER = (process.env.WEAVE_ROUTED_MODEL_HEADER || "x-router-model").toLowerCase();
 export const ROUTED_PROVIDER_HEADER = "x-router-provider";
 export const ROUTER_DECISION_HEADER = "x-router-decision";
+/** Context window (tokens) of the model that actually served the routed response. */
+export const ROUTED_CONTEXT_WINDOW_HEADER = "x-router-context-window";
 /** Marker a headless child prints to stderr so the parent dispatch can read its routed model. */
 export const ROUTED_MODEL_STDERR_PREFIX = "weave-routed-model:";
 
@@ -255,6 +267,23 @@ export const MAX_SUBAGENTS = 8;
 export const SUBAGENT_TIMEOUT_MS = Math.max(1000, numEnv("WEAVE_PI_SUBAGENT_TIMEOUT_MS", 600000));
 export const DEFAULT_READONLY_TOOLS = ["read", "grep", "find", "ls"];
 
+// ---------- LSP tunables ----------
+
+/** Idle window before an unused language server is shut down. */
+export const LSP_IDLE_MS = Math.max(10_000, numEnv("WEAVE_PI_LSP_IDLE_MS", 300_000));
+export const LSP_REQUEST_TIMEOUT_MS = Math.max(1000, numEnv("WEAVE_PI_LSP_REQUEST_TIMEOUT_MS", 15_000));
+/** Budget for `initialize` and the first query, which race the server's initial indexing pass. */
+export const LSP_WARMUP_TIMEOUT_MS = Math.max(5000, numEnv("WEAVE_PI_LSP_WARMUP_TIMEOUT_MS", 60_000));
+export const LSP_DIAGNOSTICS_WAIT_MS = Math.max(500, numEnv("WEAVE_PI_LSP_DIAGNOSTICS_WAIT_MS", 3000));
+export const LSP_MAX_SERVERS = Math.max(1, numEnv("WEAVE_PI_LSP_MAX_SERVERS", 4));
+export const LSP_MAX_REFERENCES = Math.max(1, numEnv("WEAVE_PI_LSP_MAX_REFERENCES", 100));
+
+// Set by dispatch on children so a subagent reaches the parent's warm server
+// pool over a local socket instead of cold-starting its own gopls. Internal:
+// never set these yourself.
+export const LSP_BROKER_ENV = "WEAVE_PI_LSP_BROKER";
+export const LSP_BROKER_TOKEN_ENV = "WEAVE_PI_LSP_BROKER_TOKEN";
+
 // Tools that let a subagent mutate the filesystem or run arbitrary commands.
 // dispatch strips these from model-requested per-task `tools` (and downgrades
 // readOnly:false's "all tools") unless WEAVE_PI_ALLOW_SUBAGENT_TOOLS=1, so a

package/pi-router/src/context-window.ts

@@ -0,0 +1,12 @@
+/**
+ * Router-served context-window parsing shared by the model registry and
+ * compaction guard. The response header is the source of truth for the model
+ * that actually served a routed request.
+ */
+
+/** Parse a router context-window header without accepting fractional or unsafe values. */
+export function parseRoutedContextWindow(value: string | undefined): number | undefined {
+	if (!value || !/^[1-9]\d*$/.test(value)) return undefined;
+	const contextWindow = Number(value);
+	return Number.isSafeInteger(contextWindow) ? contextWindow : undefined;
+}

package/pi-router/src/dispatch.ts

@@ -25,6 +25,8 @@ import {
 	DEFAULT_READONLY_TOOLS,
 	DISPATCH_CONCURRENCY,
 	getRouterBaseUrl,
+	LSP_BROKER_ENV,
+	LSP_BROKER_TOKEN_ENV,
 	MAX_SUBAGENTS,
 	PROVIDER_NAME,
 	resolveIdentity,
@@ -34,6 +36,15 @@ import {
 	SUBAGENT_TIMEOUT_MS,
 } from "./config.js";
 
+/**
+ * The slice of the LSP subsystem dispatch depends on: hand me the env a child
+ * needs to reach a warm server pool. Declared here, by the consumer, so
+ * dispatch and lsp stay unaware of each other and index.ts does the wiring.
+ */
+export interface SubagentEnvProvider {
+	ensure(): Promise<Record<string, string>>;
+}
+
 const SIGKILL_GRACE_MS = 5000;
 
 const TaskItem = Type.Object({
@@ -123,6 +134,7 @@ function runChild(
 	key: string,
 	signal: AbortSignal | undefined,
 	index: number,
+	lspEnv: Record<string, string> | undefined,
 ): Promise<ChildResult> {
 	const args = ["--print", "--mode", "json", "--no-session", "-e", selfPath, "--model", `${PROVIDER_NAME}/${SUBAGENT_MODEL}`];
 
@@ -147,12 +159,17 @@ function runChild(
 		tools = tools.map((t) => t.trim()).filter((t) => t !== "" && !DANGEROUS_SUBAGENT_TOOLS.has(t.toLowerCase()));
 		if (tools.length === 0) tools = DEFAULT_READONLY_TOOLS;
 	}
+	// All five lsp operations are read-only, so granting it does not widen the
+	// capability gate above. Only offered when the parent actually has a broker
+	// listening; otherwise the child's tool list is exactly what it is today.
+	if (tools && lspEnv && !tools.includes("lsp")) tools = [...tools, "lsp"];
 	if (tools) args.push("--tools", tools.join(","));
 	args.push(task.prompt);
 
 	const identity = resolveIdentity();
 	const env: NodeJS.ProcessEnv = {
 		...process.env,
+		...lspEnv,
 		WEAVE_PI_SUBAGENT: "1",
 		WEAVE_PI_SUBAGENT_ID: randomUUID(),
 		WEAVE_ROUTER_KEY: key,
@@ -165,6 +182,12 @@ function runChild(
 	delete env.WEAVE_ROUTING_SPEED_WEIGHT;
 	delete env.WEAVE_ROUTING_OUTPUT_COST_RATIO;
 	delete env.WEAVE_ROUTING_EXPECTED_OUTPUT_TOKENS;
+	// With no broker there must be no broker env at all, so a child never tries
+	// to dial a socket that isn't there.
+	if (!lspEnv) {
+		delete env[LSP_BROKER_ENV];
+		delete env[LSP_BROKER_TOKEN_ENV];
+	}
 	if (identity.email) env.WEAVE_USER_EMAIL = identity.email;
 	if (identity.name) env.WEAVE_USER_NAME = identity.name;
 
@@ -282,7 +305,7 @@ function lastStderrLine(stderr: string): string {
 	return lines.length > 0 ? lines[lines.length - 1] : "";
 }
 
-export function registerDispatch(pi: ExtensionAPI, selfPath: string): void {
+export function registerDispatch(pi: ExtensionAPI, selfPath: string, lspBroker?: SubagentEnvProvider): void {
 	pi.registerTool({
 		name: "dispatch",
 		label: "Dispatch",
@@ -308,9 +331,19 @@ export function registerDispatch(pi: ExtensionAPI, selfPath: string): void {
 				};
 			}
 
+			// Start the broker before fan-out so N children share the parent's warm
+			// language servers instead of each cold-starting its own. A broker that
+			// will not start is not fatal: children just run without the lsp tool.
+			let lspEnv: Record<string, string> | undefined;
+			try {
+				lspEnv = await lspBroker?.ensure();
+			} catch {
+				lspEnv = undefined;
+			}
+
 			const readOnly = params.readOnly ?? true;
 			const results = await mapWithConcurrencyLimit(params.tasks, DISPATCH_CONCURRENCY, (task, index) =>
-				runChild(selfPath, task, readOnly, ctx.cwd, key, signal, index),
+				runChild(selfPath, task, readOnly, ctx.cwd, key, signal, index, lspEnv),
 			);
 
 			const succeeded = results.filter((r) => r.exitCode === 0 && !r.error).length;

package/pi-router/src/index.ts

@@ -12,6 +12,9 @@
  *   - compaction:   protect long tool loops, then compact routed context.
  *   - dispatch:     parallel, context-isolated subagents — top-level process
  *                   only (no grandchildren).
+ *   - lsp:          code intelligence (definition/references/hover/symbols/
+ *                   diagnostics) over lazily spawned language servers, shared
+ *                   with subagents through a parent-side broker socket.
  *
  * The same module loads in dispatched children via `-e <self>`; WEAVE_PI_SUBAGENT
  * flips the provider knobs and suppresses the dispatch tool so fan-out doesn't recurse.
@@ -23,6 +26,7 @@ import { isSubagent } from "./config.js";
 import { registerCompaction } from "./compaction.js";
 import { registerDispatch } from "./dispatch.js";
 import { registerForceModelCommands } from "./force-model.js";
+import { registerLsp } from "./lsp.js";
 import { registerMetadata } from "./metadata.js";
 import { registerRoutedModel } from "./routed-model.js";
 import { registerSafety } from "./safety.js";
@@ -44,8 +48,13 @@ export default function (pi: ExtensionAPI): void {
 
 	if (process.env.WEAVE_NO_SAFETY !== "1") registerSafety(pi);
 
+	// registerLsp picks its own role: the main process gets the pool-backed tool
+	// and returns the broker provider below; a child gets the broker-backed tool
+	// only when dispatch actually handed it a socket.
+	const lspBroker = process.env.WEAVE_PI_NO_LSP === "1" ? undefined : registerLsp(pi);
+
 	// Only the top-level process fans out. Children (WEAVE_PI_SUBAGENT=1) load
 	// this same extension but get no dispatch tool, so subagents can't spawn
 	// grandchildren.
-	if (!isSubagent()) registerDispatch(pi, SELF_PATH);
+	if (!isSubagent()) registerDispatch(pi, SELF_PATH, lspBroker);
 }