one-code-extension 0.3.0 → 0.4.0

package/extensions/lib/side-call.ts

@@ -0,0 +1,76 @@
+/**
+ * Shared pieces of a stateless side-model call — a one-off completion made over
+ * (a slice of) the current conversation, outside the main agent loop. Used by
+ * the recap extension (the "while you were away" summary) and the btw extension
+ * (Claude Code's `/btw` side question). Kept free of runtime pi imports (only a
+ * pi-ai type) so it stays unit-testable and importable from pure prompt modules.
+ */
+
+import type { Tool } from "@earendil-works/pi-ai";
+
+/**
+ * Name-only tool declarations: enough for a provider to accept the `tool_use`
+ * blocks already in a shared history, without the descriptions and schemas. A
+ * side call never invokes a tool (its prompt asks for text), and the empty
+ * schema keeps the model answering in text on strict providers that reject a
+ * history carrying `tool_use` blocks with no tools declared.
+ */
+export function toolStubs(names: readonly string[], reason = "Unavailable for this call; answer in text."): Tool[] {
+	return names.map(
+		(name) =>
+			({
+				name,
+				description: reason,
+				parameters: { type: "object", properties: {} },
+			}) as unknown as Tool,
+	);
+}
+
+/**
+ * Trim a message history forward to the first clean turn boundary — a `user`
+ * prompt or an `assistant` reply. A raw history can begin mid-exchange with a
+ * leading `tool_result` message whose matching `assistant` `tool_use` is absent,
+ * which strict providers (e.g. Anthropic) reject as an orphan `tool_result`. An
+ * assistant start is safe: its own tool results follow. When there is no
+ * user/assistant message at all, nothing is safe to send and this returns empty.
+ * Generic over `{ role }` so it is testable with plain objects.
+ */
+export function trimToTurnBoundary<T extends { role: string }>(messages: readonly T[]): T[] {
+	const start = messages.findIndex((message) => message.role === "user" || message.role === "assistant");
+	return start === -1 ? [] : messages.slice(start);
+}
+
+/** The placeholder left in a message whose only content was an image we removed. */
+export const IMAGE_OMITTED_TEXT = "[image omitted]";
+
+/**
+ * Drop image content blocks from a message history, so a side call can run on a
+ * text-only model without the images the conversation carried breaking the
+ * request. Used by the recap and btw side calls, which reuse the exact messages
+ * the session last sent — those can hold `image` blocks (pasted images, an image
+ * a Read returned), and neither call needs them: recap summarises "what
+ * happened" and btw answers a text question. The classifier renders the
+ * transcript to text (never blocks) and the web_fetch reader sends page text, so
+ * they need no stripping. A message left with no content becomes a single
+ * placeholder text block, so it stays a valid turn on strict providers. Purely
+ * structural (any `{ role, content }` message) to stay free of runtime pi
+ * imports; assistant messages carry no images and pass through untouched.
+ * See `docs/decisions/model-policy.md`.
+ */
+export function stripImageBlocks<M extends { role: string; content: unknown }>(messages: readonly M[]): M[] {
+	return messages.map((message) => {
+		const content = message.content;
+		if (!Array.isArray(content) || !content.some((block) => (block as { type?: string })?.type === "image")) return message;
+		const kept = content.filter((block) => (block as { type?: string })?.type !== "image");
+		return { ...message, content: kept.length > 0 ? kept : [{ type: "text", text: IMAGE_OMITTED_TEXT }] } as M;
+	});
+}
+
+/** Join the text blocks of a completion result into one trimmed string. */
+export function answerText(content: readonly { type: string; text?: string }[]): string {
+	return content
+		.filter((block): block is { type: "text"; text: string } => block.type === "text" && typeof block.text === "string")
+		.map((block) => block.text)
+		.join("\n")
+		.trim();
+}

package/extensions/lib/tui-render.ts

@@ -15,7 +15,7 @@
  * every line goes through `truncateLine` — never skip it.
  */
 
-import { notificationBody } from "./notifications.ts";
+import { framesToText, notificationBody, parseNotificationFrames } from "./notifications.ts";
 import { fitPainted, hardWrapColumns, sliceColumns, visibleWidth } from "./text-width.ts";
 export { notificationBody };
 export { visibleWidth } from "./text-width.ts";
@@ -729,21 +729,72 @@ export function customMessageText(content: unknown): string {
 	return String(content ?? "");
 }
 
+/** `Sep 11 12:03pm` — the time stamp on Claude Code's "Running scheduled task" line. */
+export function formatFireTime(ms: number): string {
+	const d = new Date(ms);
+	const month = ["Jan", "Feb", "Mar", "Apr", "May", "Jun", "Jul", "Aug", "Sep", "Oct", "Nov", "Dec"][d.getMonth()];
+	const hours = d.getHours();
+	const h12 = hours % 12 === 0 ? 12 : hours % 12;
+	const minutes = String(d.getMinutes()).padStart(2, "0");
+	return `${month} ${d.getDate()} ${h12}:${minutes}${hours < 12 ? "am" : "pm"}`;
+}
+
+/**
+ * A fired wakeup or loop tick in the transcript: Claude Code's dim
+ * `✻ Running scheduled task (Sep 11 12:03pm)` line, the prompt itself under it
+ * on ctrl+o (the prompt is the turn's input, verbatim — findings §21).
+ */
+export function scheduledTaskComponent(theme: ThemeLike, prompt: string, firedAt: number, expanded: boolean): TuiComponent {
+	const lines = prompt.trim().split("\n");
+	const headline = `Running scheduled task (${formatFireTime(firedAt)})`;
+	return linesComponent(() => {
+		if (!expanded) {
+			return [`${theme.fg("dim", "✻")} ${theme.fg("dim", headline)}${theme.fg("dim", ` (+${lines.length} lines, ${EXPAND_HINT})`)}`];
+		}
+		return [`${theme.fg("dim", "✻")} ${theme.fg("dim", headline)}`, ...lines.map((l) => `  ${theme.fg("muted", l)}`)];
+	});
+}
+
 /**
  * Compact transcript rendering for harness-injected messages (background
- * completions, subagent replies, monitor batches, wakeups): one dim headline
- * collapsed, the full body on ctrl+o.
+ * completions, subagent replies and reports, monitor batches): one dim headline
+ * per frame collapsed, each with its own "+N lines" hint, the bodies on ctrl+o.
+ * A coalesced message (several frames arriving together) therefore lists one
+ * line per event, the way the events would read had they arrived apart. The
+ * wire frames (`<task-notification>`, the agent-message envelope) are
+ * model-only; `parseNotificationFrames` takes them apart for display.
  */
 export function notificationComponent(theme: ThemeLike, text: string, expanded: boolean): TuiComponent {
-	const body = notificationBody(text);
-	const lines = body.split("\n");
-	const headline = oneLine(lines[0] ?? "");
+	// An agent's completion pointer says nothing the message above it does not;
+	// CC's transcript shows the message alone.
+	const parsed = parseNotificationFrames(text);
+	const frames = parsed.filter((frame) => !(frame.kind === "task" && frame.pointer));
+	if (frames.length === 0) frames.push({ kind: "text", text: framesToText(parsed) });
+	const dim = (s: string) => theme.fg("dim", s);
+	const muted = (s: string) => theme.fg("muted", s);
 	// pi's custom-message shell already prepends a spacer — emit content only.
-	return linesComponent(() => {
-		if (!expanded) {
-			const more = lines.length > 1 ? theme.fg("dim", ` (+${lines.length - 1} lines, ${EXPAND_HINT})`) : "";
-			return [`${theme.fg("dim", "✳")} ${theme.fg("muted", theme.italic(headline))}${more}`];
+	return linesComponent((width) => {
+		const out: string[] = [];
+		// Body lines wrap to the terminal (CC wraps its long preamble line) rather
+		// than being cut; continuation lines start at column 0, as CC's do.
+		const body = (lines: string[]) => lines.flatMap((l) => wrapPlainText(`  ${l}`, width).map((w) => muted(w)));
+		const hint = (lines: string[]) => (lines.length > 0 ? dim(` (+${lines.length} lines, ${EXPAND_HINT})`) : "");
+		for (const frame of frames) {
+			if (frame.kind === "agent-message") {
+				// Claude Code's look: `› Message from @ID (ctrl+o to expand)` collapsed;
+				// the header, then the body as delivered (preamble, indented report),
+				// indented under it, when expanded. The guard is never shown.
+				const bodyLines = frame.body.split("\n");
+				if (expanded) out.push(dim(`› Message from ${frame.from}`), ...body(bodyLines));
+				else out.push(dim(`› Message from @${frame.from}`) + hint(bodyLines));
+				continue;
+			}
+			const headline = frame.kind === "task" ? frame.summary : oneLine(frame.text.split("\n")[0] ?? "");
+			const bodyLines = frame.kind === "task" ? (frame.body ? frame.body.split("\n") : []) : frame.text.split("\n").slice(1);
+			const head = `${dim("✳")} ${muted(theme.italic(oneLine(headline)))}`;
+			if (expanded) out.push(head, ...body(bodyLines));
+			else out.push(head + hint(bodyLines));
 		}
-		return [`${theme.fg("dim", "✳")} ${theme.fg("muted", theme.italic(headline))}`, ...lines.slice(1).map((l) => `  ${theme.fg("muted", l)}`)];
+		return out;
 	});
 }

package/extensions/lib/update-check.mjs

@@ -0,0 +1,155 @@
+/**
+ * One Code's own update notice and the release facts behind it — shared by
+ * the bundled app (app/bin.mjs registers createUpdateCheck as an inline
+ * extension) and the doctor (doctor/update-lookup.ts reports the same
+ * "newest installable version"). Plain JS with no pi imports: the app loads
+ * it from the extension package it depends on, so it must run on bare Node.
+ *
+ * The notice replaces pi's (suppressed via PI_SKIP_VERSION_CHECK — its
+ * endpoint is hardcoded to pi's registry and cannot be pointed at one-code).
+ * It mirrors pi's behaviour: entirely non-blocking, and silent on any failure —
+ * an update hint must never cost startup time or surface a network error.
+ * Honours pi's offline switch (`--offline` sets PI_OFFLINE=1 before extensions
+ * load) and runs at most once a day per agent dir, stamped in
+ * `<agentDir>/last-update-check` (pi's own check is per session start; a
+ * daily cadence spares the registry on every TUI launch). pi's semver helpers
+ * are not exported from the package root, so the dotted-numeric compare lives
+ * here.
+ */
+
+import { readFileSync, writeFileSync } from "node:fs";
+
+export const APP_PACKAGE = "@one-ai/one-code";
+export const EXTENSION_PACKAGE = "one-code-extension";
+/** The Homebrew formula (IsuruMaduranga/homebrew-one-ai), renamed from one-code at 0.3.0. */
+export const HOMEBREW_FORMULA = "onecode";
+/** How each install method upgrades the app; the doctor and the update notice quote these. */
+export const UPGRADE_COMMANDS = {
+	npm: `npm install -g ${APP_PACKAGE}`,
+	brew: `brew upgrade ${HOMEBREW_FORMULA}`,
+	"pi-package": "pi update",
+};
+
+/**
+ * The registry packument for a package (scoped slash percent-encoded). The
+ * full document, not `/latest`: its `time` map dates every version, which
+ * the Homebrew rule needs (pickAvailableVersion). ~14 KB for this package.
+ */
+export function registryPackumentUrl(name) {
+	return `https://registry.npmjs.org/${name.replace("/", "%2F")}`;
+}
+
+const TIMEOUT_MS = 3000;
+const DAY_MS = 24 * 60 * 60 * 1000;
+export const CHECK_INTERVAL_MS = DAY_MS;
+/**
+ * Homebrew's `std_npm_args` passes npm `--min-release-age=1`, so a version
+ * becomes brew-installable only a day after its npm publish. A Homebrew user
+ * told about a fresher version would run `brew upgrade onecode` and get
+ * nothing, so every hint for that install method waits the same day.
+ */
+export const HOMEBREW_MIN_RELEASE_AGE_MS = DAY_MS;
+
+/**
+ * The minimum release age for an install method: a day for Homebrew, none
+ * otherwise. `ONECODE_INSTALL_METHOD` is set by the app launcher (app/bin.mjs)
+ * from where the binary lives; a plain pi package never sets it.
+ */
+export function minReleaseAgeFor(env = process.env) {
+	return env.ONECODE_INSTALL_METHOD === "brew" ? HOMEBREW_MIN_RELEASE_AGE_MS : 0;
+}
+
+/** pi's truthy-flag reading for PI_OFFLINE (1/true/yes). */
+export function isOffline(env = process.env) {
+	return /^(1|true|yes)$/i.test(String(env.PI_OFFLINE ?? "").trim());
+}
+
+/** True when the stamp file records a check within the interval; unreadable/missing stamps count as due. */
+export function checkedRecently(stampPath, now = Date.now()) {
+	if (!stampPath) return false;
+	try {
+		const last = Number(readFileSync(stampPath, "utf8").trim());
+		return Number.isFinite(last) && now - last >= 0 && now - last < CHECK_INTERVAL_MS;
+	} catch {
+		return false;
+	}
+}
+
+/** True when `candidate` is a strictly newer x.y.z than `current`. */
+export function isNewerVersion(candidate, current) {
+	const parse = (v) => {
+		const parts = String(v).trim().split(".");
+		if (parts.length === 0 || parts.length > 3) return undefined;
+		const nums = parts.map((p) => (/^\d+$/.test(p) ? Number(p) : Number.NaN));
+		return nums.some(Number.isNaN) ? undefined : nums;
+	};
+	const a = parse(candidate);
+	const b = parse(current);
+	if (!a || !b) return false;
+	for (let i = 0; i < 3; i++) {
+		const diff = (a[i] ?? 0) - (b[i] ?? 0);
+		if (diff !== 0) return diff > 0;
+	}
+	return false;
+}
+
+/**
+ * The newest version in a registry packument worth announcing, or undefined.
+ * With no minimum age this is `dist-tags.latest` (what `npm install -g`
+ * fetches). With one, it is the newest plain x.y.z version whose `time` entry
+ * is at least that old — the newest one a `--min-release-age` install can see.
+ * Prerelease tags never qualify.
+ */
+export function pickAvailableVersion(packument, { minReleaseAgeMs = 0, now = Date.now() } = {}) {
+	if (!packument || typeof packument !== "object") return undefined;
+	const latest = packument["dist-tags"]?.latest;
+	if (minReleaseAgeMs <= 0) return typeof latest === "string" ? latest : undefined;
+	const time = packument.time;
+	if (!time || typeof time !== "object") return undefined;
+	let best;
+	for (const [version, published] of Object.entries(time)) {
+		if (version === "created" || version === "modified") continue;
+		const publishedAt = Date.parse(published);
+		if (!Number.isFinite(publishedAt) || now - publishedAt < minReleaseAgeMs) continue;
+		if (!/^\d+\.\d+\.\d+$/.test(version)) continue; // prereleases never qualify
+		if (best === undefined || isNewerVersion(version, best)) best = version;
+	}
+	return best;
+}
+
+export function createUpdateCheck({ currentVersion, upgradeHint, stampPath, minReleaseAgeMs = 0 }) {
+	return function updateCheckExtension(pi) {
+		pi.on("session_start", (_event, ctx) => {
+			if (process.env.ONECODE_NO_UPDATE_CHECK === "1") return;
+			if (isOffline()) return;
+			if (!ctx.hasUI) return; // print/rpc runs stay clean for parsers
+			if (checkedRecently(stampPath)) return;
+			// Fire-and-forget: session_start handlers run serially before the
+			// prompt opens, so this must never be awaited.
+			void (async () => {
+				try {
+					// Stamp before the fetch: a hung registry must not re-fire on
+					// every /clear (session_start) within the day.
+					if (stampPath) {
+						try {
+							writeFileSync(stampPath, String(Date.now()));
+						} catch {
+							// Unwritable agent dir: check every start, as before.
+						}
+					}
+					const response = await fetch(registryPackumentUrl(APP_PACKAGE), { signal: AbortSignal.timeout(TIMEOUT_MS) });
+					if (!response.ok) return;
+					const latest = pickAvailableVersion(await response.json(), { minReleaseAgeMs });
+					if (typeof latest === "string" && isNewerVersion(latest, currentVersion)) {
+						ctx.ui.notify(
+							`One Code ${latest} is available (you have ${currentVersion}). Upgrade: ${upgradeHint}`,
+							"info",
+						);
+					}
+				} catch {
+					// Offline, slow registry, unexpected payload: stay silent.
+				}
+			})();
+		});
+	};
+}

package/extensions/lib/usage-bus.ts

@@ -22,7 +22,7 @@ export const USAGE_CHANNEL = "one-code:usage-recorded";
  */
 export const USAGE_ENTRY_TYPE = "one-code:usage";
 
-export type UsageSource = "subagent" | "classifier" | "reader" | "recap" | "setup";
+export type UsageSource = "subagent" | "classifier" | "reader" | "recap" | "session-title" | "setup" | "btw";
 
 export interface UsageRecord {
 	source: UsageSource;

package/extensions/lib/which.ts

@@ -0,0 +1,62 @@
+/**
+ * Minimal `which` (pure apart from the access check): the first PATH entry
+ * holding an executable of that name, with Windows `PATHEXT` honoured. Shared
+ * by the doctor's dependency checks and the shell resolvers
+ * (lib/shell-spawn.ts) so "is this on PATH" has one answer.
+ */
+
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+
+export function whichOnPath(command: string, env: NodeJS.ProcessEnv, platform: string = process.platform): string | undefined {
+	if (!command) return undefined;
+	// Windows resolves `foo` to `foo.exe`/`foo.cmd` whether or not a directory is
+	// spelled (`node_modules/.bin/tsserver` is `…\tsserver.cmd` on disk), so the
+	// extension list applies to both forms; elsewhere only the literal name counts.
+	// The bare name comes LAST on Windows, and only when it already carries a
+	// PATHEXT extension: npm puts three shims per global next to each other
+	// (`tsserver`, a POSIX sh script for Git Bash; `tsserver.cmd`; `tsserver.ps1`)
+	// and the extensionless one is not a Windows executable — CreateProcess
+	// refuses it with ENOENT, which is what every npm-installed language server
+	// did on a real Windows machine until 2026-09-19 (findings §22).
+	const pathext = platform === "win32" ? (envVar(env, "PATHEXT") ?? ".EXE;.CMD;.BAT").split(";").filter(Boolean) : [];
+	const hasPathext = pathext.some((ext) => command.toLowerCase().endsWith(ext.toLowerCase()));
+	const extensions = platform === "win32" ? (hasPathext ? ["", ...pathext] : [...pathext, ""]) : [""];
+	if (command.includes("/") || command.includes("\\")) {
+		return extensions.map((ext) => command + ext).find(isExecutable);
+	}
+	for (const dir of (envVar(env, "PATH") ?? "").split(delimiter)) {
+		if (!dir) continue;
+		for (const ext of extensions) {
+			const candidate = join(dir, command + ext);
+			if (isExecutable(candidate)) return candidate;
+		}
+	}
+	return undefined;
+}
+
+/**
+ * Read an environment variable by name regardless of the key's case. Windows
+ * spells it `Path`; `process.env` itself answers `env.PATH` there because it
+ * is a case-insensitive proxy, but a spread copy (`{ ...process.env, ...extra }`,
+ * the shape every spawn with its own variables builds) is a plain object and
+ * `copy.PATH` is undefined — so the lookup silently found nothing.
+ */
+export function envVar(env: NodeJS.ProcessEnv, name: string): string | undefined {
+	const direct = env[name];
+	if (direct !== undefined) return direct;
+	const upper = name.toUpperCase();
+	for (const key of Object.keys(env)) {
+		if (key.toUpperCase() === upper) return env[key];
+	}
+	return undefined;
+}
+
+export function isExecutable(path: string): boolean {
+	try {
+		accessSync(path, constants.X_OK);
+		return true;
+	} catch {
+		return false;
+	}
+}

package/extensions/lib/worktree-channel.ts

@@ -0,0 +1,18 @@
+/**
+ * The worktree session, announced over `pi.events` so other extensions can
+ * follow it without sharing module state (jiti isolation, findings §3). The
+ * worktree extension emits on every state change — enter, exit, and the
+ * session_start/session_tree restore; the footer shows the worktree's path
+ * and branch in place of the process cwd while one is active (Claude Code's
+ * footer does the same). The bus does not replay: a late subscriber sees the
+ * next change, which is fine here — the footer subscribes at load, and the
+ * first emit is the session_start restore.
+ */
+
+export const WORKTREE_CHANNEL = "one-code:worktree";
+
+/** Payload: the active worktree, or null when the session left it. */
+export interface WorktreeLocation {
+	path: string;
+	branch?: string;
+}

package/extensions/lib/worktree-isolation.ts

@@ -130,7 +130,8 @@ export function worktreeBashWriteGuardReason(input: { command: string; cwd: stri
 	const home = input.home ?? homedir();
 	const evidence = analyzeShellCommand({ command: input.command, cwd: input.cwd, home });
 	for (const write of evidence.writes) {
-		const mapped = sharedCheckoutWriteTarget(write.token, input.cwd, input.isolation, home);
+		// The target as the shell reaches it (Git Bash spellings converted), judged like a file-tool path.
+		const mapped = sharedCheckoutWriteTarget(write.absolute, input.cwd, input.isolation, home);
 		if (mapped) return refusal(input.isolation, `this command writes to ${write.token}, which`, mapped);
 	}
 	return undefined;

package/extensions/lsp/client.ts

@@ -19,6 +19,8 @@ import { type ChildProcess, spawn } from "node:child_process";
 import { readFileSync } from "node:fs";
 import { pathToFileURL } from "node:url";
 import type { LspDiagnostic } from "./format.ts";
+import { commandLaunch } from "../lib/command-launch.ts";
+import { killProcessTree } from "../lib/process-tree.ts";
 import { createReaderState, encodeMessage, type JsonRpcMessage, readMessages } from "./protocol.ts";
 
 const INITIALIZE_TIMEOUT_MS = 15_000;
@@ -99,10 +101,16 @@ export class LspClient {
 	async start(): Promise<void> {
 		if (this.child) return;
 
-		const child = spawn(this.config.command, this.config.args, {
+		const env = this.options.env ? { ...process.env, ...this.options.env } : process.env;
+		// On Windows an npm-installed server is a .cmd shim, which a bare spawn
+		// cannot start (lib/command-launch.ts); failure messages keep naming the command.
+		const launch = commandLaunch(this.config.command, this.config.args, env);
+		const child = spawn(launch.command, launch.args, {
 			cwd: this.root,
 			stdio: ["pipe", "pipe", "pipe"],
-			env: this.options.env ? { ...process.env, ...this.options.env } : process.env,
+			env,
+			windowsHide: true,
+			windowsVerbatimArguments: launch.windowsVerbatimArguments,
 		});
 		this.child = child;
 
@@ -322,7 +330,10 @@ export class LspClient {
 		this.child = undefined;
 		await new Promise<void>((resolve) => {
 			const timer = setTimeout(() => {
-				child.kill("SIGKILL");
+				// The tree, not the leader: on Windows a .cmd-shimmed server runs
+				// under the cmd.exe `commandLaunch` started, and killing cmd.exe
+				// alone would orphan the server on the inherited pipes.
+				killProcessTree(child, "SIGKILL");
 				resolve();
 			}, 1000);
 			timer.unref?.();

package/extensions/lsp/index.ts

@@ -29,6 +29,7 @@ import { StringEnum } from "@earendil-works/pi-ai";
 import { getAgentDir, type ExtensionAPI, type ExtensionContext } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
 import { DEFER_CHANNEL } from "../lib/deferred.ts";
+import { absoluteFrom } from "../lib/paths.ts";
 import { defaultDiscoverRoots, discoverPlugins, pluginResources } from "../lib/plugins.ts";
 import { REMINDER_CHANNEL, type ReminderPayload } from "../lib/reminders.ts";
 import { ccToolRenderers, cutPlainText } from "../lib/tui-render.ts";
@@ -45,6 +46,7 @@ import {
 } from "./plugin-servers.ts";
 import { findProjectRoot, serverForPath, typescriptPreflight } from "./servers.ts";
 import { computeDelta, DeliveredTracker, fingerprintDiagnostic, formatNewDiagnostics, markDelivered } from "./watcher.ts";
+import { registerLocalCommand } from "../lib/local-command.ts";
 
 /** Everything needed to spawn/reuse the server responsible for a path. */
 interface ResolvedTarget {
@@ -254,8 +256,13 @@ export default function lspExtension(pi: ExtensionAPI) {
 		// sync the file, await the server's next publish, and reset the file's
 		// delivered-set so a reintroduced issue resurfaces.
 		if (!event.isError && (event.toolName === "edit" || event.toolName === "write")) {
-			const path = (event.input as { path?: unknown }).path;
-			if (typeof path === "string") {
+			const raw = (event.input as { path?: unknown }).path;
+			if (typeof raw === "string") {
+				// One absolute spelling for everything below: the server key (root),
+				// the delivered-set URI and the diagnostics request. A relative path
+				// used to yield root `.` and a URI keyed on process.cwd(), so one file
+				// could end up on a second server instance (findings §23).
+				const path = absoluteFrom(ctx.cwd, raw);
 				const target = resolveTarget(path, ctx.cwd);
 				reportRoutingIssuesOnce(ctx);
 				if (target) {
@@ -309,7 +316,7 @@ export default function lspExtension(pi: ExtensionAPI) {
 			),
 		}),
 		async execute(_toolCallId, params, _signal, _onUpdate, ctx) {
-			const path = params.path.startsWith("/") ? params.path : `${ctx.cwd}/${params.path}`;
+			const path = absoluteFrom(ctx.cwd, params.path);
 			const target = resolveTarget(path, ctx.cwd);
 			// One keep-alive spans both awaits (same pattern as the tool_result hook).
 			const fetched = target
@@ -355,9 +362,9 @@ export default function lspExtension(pi: ExtensionAPI) {
 		},
 	});
 
-	pi.registerCommand("lsp", {
+	registerLocalCommand(pi, "lsp", {
 		description: "Show language server status",
-		handler: async (_args, ctx) => {
+		handler: async (args, ctx) => {
 			const lines = [...clients.entries()].map(
 				([key, client]) => `${client.isRunning ? "running" : "stopped"} ${key} (${client.diagnosticsCount} diagnostics)`,
 			);

package/extensions/lsp/install-hints.ts

@@ -11,13 +11,43 @@
  * one-time warning, /lsp, and the lsp_diagnostics tool all show the same text.
  */
 
+import { isAbsolute } from "node:path";
+import { TYPESCRIPT_PROJECT_INSTALL } from "./servers.ts";
+
+/**
+ * Tools that come from the OS package manager, by platform. Homebrew is a
+ * macOS answer; a Windows user needs winget (the doctor said `brew install
+ * ripgrep` on Windows until 2026-09-19), a Linux user their distro's manager.
+ */
+const PACKAGE_MANAGER_HINTS: Record<string, { darwin: string; win32: string; linux: string }> = {
+	ripgrep: { darwin: "brew install ripgrep", win32: "winget install BurntSushi.ripgrep.MSVC", linux: "apt install ripgrep (or your distribution's package manager)" },
+	jdtls: { darwin: "brew install jdtls", win32: "download from https://download.eclipse.org/jdtls/ and put its bin\\jdtls.bat on PATH", linux: "download from https://download.eclipse.org/jdtls/ and put its bin/jdtls on PATH" },
+};
+
+/** The install command for a package-manager tool on `platform` (defaults to this one). */
+export function installHint(tool: string, platform: string = process.platform): string {
+	const byPlatform = PACKAGE_MANAGER_HINTS[tool];
+	if (!byPlatform) return `install ${tool} and make sure it is on your PATH`;
+	return platform === "win32" ? byPlatform.win32 : platform === "darwin" ? byPlatform.darwin : byPlatform.linux;
+}
+
+/**
+ * The install command for a built-in server on `platform`: the package-manager
+ * ones (jdtls) per platform, the rest as in `INSTALL_HINTS`. The doctor
+ * renders a report for an injected platform, so it must not read the
+ * module-load default frozen into `INSTALL_HINTS`.
+ */
+export function serverInstallHint(command: string, platform: string = process.platform): string | undefined {
+	return PACKAGE_MANAGER_HINTS[command] ? installHint(command, platform) : INSTALL_HINTS[command];
+}
+
 /** Install commands for the built-in table's servers (and their npm siblings). */
 export const INSTALL_HINTS: Record<string, string> = {
-	"typescript-language-server": "npm install -g typescript-language-server typescript",
+	"typescript-language-server": `npm install -g typescript-language-server (and in the project: ${TYPESCRIPT_PROJECT_INSTALL} — the server never uses a global TypeScript)`,
 	"pyright-langserver": "npm install -g pyright",
 	gopls: "go install golang.org/x/tools/gopls@latest",
 	"rust-analyzer": "rustup component add rust-analyzer",
-	jdtls: "brew install jdtls",
+	jdtls: installHint("jdtls"),
 };
 
 /** True when the failure is a spawn ENOENT — the binary itself is absent. */
@@ -35,7 +65,7 @@ export function describeStartFailure(rawFailure: string, command: string, plugin
 	const from = pluginName ? ` (configured by the ${pluginName} plugin)` : "";
 	const hint = INSTALL_HINTS[command];
 	if (hint) return `${command} is not installed${from}. Install it with: ${hint}`;
-	if (command.startsWith("/")) {
+	if (isAbsolute(command)) {
 		return `${command} does not exist${from}. ${pluginName ? "Check the plugin's installation." : "Check the configured path."}`;
 	}
 	const docs = pluginName ? " (the plugin's documentation should say how)" : "";

package/extensions/lsp/plugin-servers.ts

@@ -23,7 +23,7 @@
  */
 
 import { readFileSync } from "node:fs";
-import { extname, join, resolve } from "node:path";
+import { extname, isAbsolute, join, resolve } from "node:path";
 import { pathWithinBase, sanitizePathSegment } from "../lib/plugin-root.ts";
 
 export interface ResolvedPluginServer {
@@ -198,7 +198,7 @@ export function resolveServerConfig(
 	if (typeof config.command !== "string" || config.command.length === 0) {
 		return reject('"command" must be a non-empty string');
 	}
-	if (config.command.includes(" ") && !config.command.startsWith("/")) {
+	if (config.command.includes(" ") && !isAbsolute(config.command)) {
 		return reject('"command" must not contain spaces — use the args array for arguments');
 	}
 

package/extensions/lsp/servers.ts

@@ -7,6 +7,7 @@
 
 import { existsSync } from "node:fs";
 import { dirname, extname, join } from "node:path";
+import { ancestorDirs } from "../lib/claude-context.ts";
 
 export interface ServerConfig {
 	command: string;
@@ -67,13 +68,34 @@ export function findProjectRoot(startPath: string, markers: string[], fallback:
 }
 
 /**
- * TypeScript 7's native compiler dropped `lib/tsserver.js`, which
- * typescript-language-server requires. Detect that up front so we can say so
- * instead of reporting a mystery server failure.
+ * The TypeScript install typescript-language-server will use for `root`: the
+ * nearest `node_modules/typescript` from the project root upward (the server
+ * resolves `typescript` the way Node does, so a monorepo's root install
+ * counts), or undefined when there is none. A global `npm i -g typescript`
+ * is never found — npm does not put global siblings on each other's
+ * resolution path (verified 2026-09-19 on macOS and Ubuntu, findings §23).
+ */
+export function findTypescript(root: string): string | undefined {
+	return ancestorDirs(root)
+		.reverse()
+		.map((dir) => join(dir, "node_modules", "typescript"))
+		.find((candidate) => existsSync(candidate));
+}
+
+/** The one way to give typescript-language-server a TypeScript it will use: 5.x in the project (findings §23). */
+export const TYPESCRIPT_PROJECT_INSTALL = "npm install -D typescript@5";
+
+/**
+ * Say up front why typescript-language-server cannot analyse `root`, instead
+ * of surfacing the server's own initialize failure: no TypeScript reachable
+ * from the project (the server does not use a global one), or a TypeScript 7
+ * whose native compiler dropped the `lib/tsserver.js` the server requires.
  */
 export function typescriptPreflight(root: string): string | undefined {
-	const localTypescript = join(root, "node_modules", "typescript");
-	if (!existsSync(localTypescript)) return undefined;
-	if (existsSync(join(localTypescript, "lib", "tsserver.js"))) return undefined;
-	return "The project's local TypeScript has no lib/tsserver.js (TypeScript 7's native compiler removed it), so typescript-language-server cannot analyse this project. Install typescript 5.x as a dev dependency for LSP diagnostics.";
+	const typescript = findTypescript(root);
+	if (!typescript) {
+		return `No TypeScript installation is reachable from this project (typescript-language-server resolves \`typescript\` from the project's node_modules upward and never uses a global install). Run \`${TYPESCRIPT_PROJECT_INSTALL}\` in the project for LSP diagnostics.`;
+	}
+	if (existsSync(join(typescript, "lib", "tsserver.js"))) return undefined;
+	return `The project's TypeScript has no lib/tsserver.js (TypeScript 7's native compiler removed it), so typescript-language-server cannot analyse this project. Run \`${TYPESCRIPT_PROJECT_INSTALL}\` for LSP diagnostics.`;
 }