oh-my-opencode 5.0.0-beta.3 → 5.0.0-beta.30

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "oh-my-opencode",
-  "version": "5.0.0-beta.3",
+  "version": "5.0.0-beta.30",
   "description": "The Best AI Agent Harness - Batteries-Included OpenCode Plugin with Multi-Model Orchestration, Parallel Background Agents, and Crafted LSP/AST Tools",
   "main": "./dist/index.js",
   "types": "dist/index.d.ts",
@@ -85,7 +85,7 @@
     "packages/omo-codex/plugin/components/lazycodex-executor-verify/dist/cli.js",
     "packages/omo-codex/plugin/components/lsp/dist/cli.js",
     "packages/omo-codex/plugin/components/rules/dist/cli.js",
-    "packages/omo-codex/plugin/components/start-work-continuation/dist/cli.js",
+    "packages/omo-codex/plugin/components/ulw-execute-continuation/dist/cli.js",
     "packages/omo-codex/plugin/components/teammode/dist/cli.js",
     "packages/omo-codex/plugin/components/telemetry/dist/cli.js",
     "packages/omo-codex/plugin/components/ultrawork/dist/cli.js",
@@ -136,7 +136,8 @@
     "typecheck:script": "tsgo --noEmit -p script/tsconfig.json",
     "test": "bun test",
     "test:codex": "bun run build:codex-install && bun run build:git-bash-mcp && bun run build:lsp-tools-mcp && bun run build:lsp-daemon && npm --prefix packages/lsp-tools-mcp test && npm --prefix packages/omo-codex/plugin ci && npm --prefix packages/omo-codex/plugin/components/ulw-loop test && bun run --cwd packages/omo-codex/plugin build && npm --prefix packages/omo-codex/plugin/components/codegraph run typecheck && npm --prefix packages/omo-codex/plugin/components/codegraph test && node scripts/check-third-party-notices.mjs --ship && bun test packages/omo-opencode/src/cli/cli-installer.platform.test.ts packages/omo-codex/src/install/codex-cache.test.ts packages/omo-codex/src/install/codex-cleanup.test.ts packages/omo-codex/src/install/codex-config-agent-cleanup.test.ts packages/omo-codex/src/install/codex-config-autonomous-features.test.ts packages/omo-codex/src/install/codex-config-reasoning.test.ts packages/omo-codex/src/install/codex-config-toml.test.ts packages/omo-codex/src/install/codex-project-local-cleanup.test.ts packages/omo-codex/src/install/install-codex-project-local-cleanup.test.ts packages/omo-codex/src/install/install-codex.test.ts packages/omo-codex/src/install/install-codex-packaged.test.ts packages/omo-codex/src/install/link-cached-plugin-agents.test.ts packages/omo-codex/src/**/*.test.ts packages/utils/src/jsonc-parser.test.ts packages/utils/src/frontmatter.test.ts packages/hashline-core/src/hash-computation.test.ts packages/hashline-core/src/smoke-untested-modules.test.ts packages/rules-engine/src/index.test.ts packages/rules-engine/src/security-boundary.test.ts packages/agents-md-core/src/injector.test.ts packages/omo-codex/plugin/components/lsp/test/package-smoke.test.ts && node --test packages/omo-codex/plugin/test/*.test.mjs packages/omo-codex/scripts/install-cache-copy.test.mjs packages/omo-codex/scripts/install-cli-args.test.mjs packages/omo-codex/scripts/install-delegated-command.test.mjs packages/omo-codex/scripts/install-config-autonomous-features.test.mjs packages/omo-codex/scripts/install-config-autonomous.test.mjs packages/omo-codex/scripts/install-config-reasoning.test.mjs packages/omo-codex/scripts/install-config.test.mjs packages/omo-codex/scripts/install-hook-targets.test.mjs packages/omo-codex/scripts/install-project-local-cleanup.test.mjs packages/omo-codex/scripts/install-lazycodex-version-stamp.test.mjs packages/omo-codex/scripts/install-local-entrypoint.test.mjs packages/omo-codex/scripts/install-local-git-bash-preflight.test.mjs packages/omo-codex/scripts/install-local.test.mjs packages/omo-codex/scripts/install-marketplace-cache.test.mjs packages/omo-codex/scripts/install-mcp-context7-runtime.test.mjs packages/omo-codex/scripts/install-mcp-runtime.test.mjs packages/omo-codex/scripts/install-packaged-local.test.mjs packages/omo-codex/scripts/install-generated-bundle.test.mjs packages/omo-codex/scripts/install-agent-links.test.mjs packages/omo-codex/scripts/install-bin-links.test.mjs",
-    "test:senpi": "bun run build:senpi-plugin && tsgo --noEmit -p packages/omo-senpi/tsconfig.json && bun test packages/omo-senpi",
+    "test:fast": "bun run script/test-fast.ts",
+    "test:senpi": "bun run build:senpi-plugin && tsgo --noEmit -p packages/omo-senpi/tsconfig.json && bun test packages/omo-senpi && bun test ./.agents/skills/senpi-qa/scripts/resolve-evidence-dir.test.mjs",
     "test:windows-codex": "bun run test:codex",
     "build:git-bash-mcp": "bun run --cwd packages/git-bash-mcp build",
     "build:ast-grep-mcp": "bun run --cwd packages/ast-grep-mcp build"
@@ -161,26 +162,26 @@
   },
   "homepage": "https://github.com/code-yeongyu/oh-my-openagent#readme",
   "dependencies": {
-    "@clack/prompts": "^1.4.0",
+    "@clack/prompts": "^1.7.0",
     "@code-yeongyu/comment-checker": "^0.8.0",
-    "@modelcontextprotocol/sdk": "^1.29.0",
-    "@opencode-ai/plugin": "1.15.13",
-    "@opencode-ai/sdk": "1.15.13",
-    "@opentui/core": "^0.2.16",
-    "@opentui/keymap": "^0.2.16",
-    "@opentui/solid": "^0.2.16",
-    "commander": "^14.0.3",
+    "@modelcontextprotocol/sdk": "^1.30.0",
+    "@opencode-ai/plugin": "1.18.22",
+    "@opencode-ai/sdk": "1.18.22",
+    "@opentui/core": "^0.5.8",
+    "@opentui/keymap": "^0.5.8",
+    "@opentui/solid": "^0.5.8",
+    "commander": "^15.0.0",
     "detect-libc": "^2.1.2",
     "diff": "^9.0.0",
-    "js-yaml": "^4.1.1",
+    "js-yaml": "^5.0.0",
     "jsonc-parser": "^3.3.1",
     "picocolors": "^1.1.1",
-    "picomatch": "^4.0.4",
-    "posthog-node": "^5.34.3",
+    "picomatch": "^4.0.7",
+    "posthog-node": "^5.51.1",
     "zod": "^4.4.3"
   },
   "devDependencies": {
-    "@code-yeongyu/senpi": "2026.8.9-2",
+    "@code-yeongyu/senpi": "2026.8.30-3",
     "@oh-my-opencode/agents-md-core": "workspace:*",
     "@oh-my-opencode/ast-grep-mcp": "workspace:*",
     "@oh-my-opencode/boulder-state": "workspace:*",
@@ -196,6 +197,7 @@
     "@oh-my-opencode/model-core": "workspace:*",
     "@oh-my-opencode/omo-codex": "workspace:*",
     "@oh-my-opencode/omo-config-core": "workspace:*",
+    "@oh-my-opencode/omo-opencode": "workspace:*",
     "@oh-my-opencode/omo-senpi": "workspace:*",
     "@oh-my-opencode/openclaw-core": "workspace:*",
     "@oh-my-opencode/pi-goal": "workspace:*",
@@ -211,40 +213,44 @@
     "@oh-my-opencode/utils": "workspace:*",
     "@types/js-yaml": "^4.0.9",
     "@types/picomatch": "^4.0.3",
-    "@typescript/native-preview": "7.0.0-dev.20260518.1",
+    "@typescript/native-preview": "7.0.0-dev.20260707.2",
     "@xterm/addon-unicode11": "^0.9.0",
     "@xterm/xterm": "^6.0.0",
-    "bun-types": "1.3.14",
+    "bun-types": "1.4.0",
     "node-pty": "^1.1.0",
-    "puppeteer-core": "^25.3.0",
+    "puppeteer-core": "^25.8.0",
     "typescript": "^7.0.2"
   },
   "optionalDependencies": {
-    "oh-my-opencode-darwin-arm64": "5.0.0-beta.3",
-    "oh-my-opencode-darwin-x64": "5.0.0-beta.3",
-    "oh-my-opencode-darwin-x64-baseline": "5.0.0-beta.3",
-    "oh-my-opencode-linux-arm64": "5.0.0-beta.3",
-    "oh-my-opencode-linux-arm64-musl": "5.0.0-beta.3",
-    "oh-my-opencode-linux-x64": "5.0.0-beta.3",
-    "oh-my-opencode-linux-x64-baseline": "5.0.0-beta.3",
-    "oh-my-opencode-linux-x64-musl": "5.0.0-beta.3",
-    "oh-my-opencode-linux-x64-musl-baseline": "5.0.0-beta.3",
-    "oh-my-opencode-windows-arm64": "5.0.0-beta.3",
-    "oh-my-opencode-windows-x64": "5.0.0-beta.3",
-    "oh-my-opencode-windows-x64-baseline": "5.0.0-beta.3"
+    "oh-my-opencode-darwin-arm64": "5.0.0-beta.30",
+    "oh-my-opencode-darwin-x64": "5.0.0-beta.30",
+    "oh-my-opencode-darwin-x64-baseline": "5.0.0-beta.30",
+    "oh-my-opencode-linux-arm64": "5.0.0-beta.30",
+    "oh-my-opencode-linux-arm64-musl": "5.0.0-beta.30",
+    "oh-my-opencode-linux-x64": "5.0.0-beta.30",
+    "oh-my-opencode-linux-x64-baseline": "5.0.0-beta.30",
+    "oh-my-opencode-linux-x64-musl": "5.0.0-beta.30",
+    "oh-my-opencode-linux-x64-musl-baseline": "5.0.0-beta.30",
+    "oh-my-opencode-windows-arm64": "5.0.0-beta.30",
+    "oh-my-opencode-windows-x64": "5.0.0-beta.30",
+    "oh-my-opencode-windows-x64-baseline": "5.0.0-beta.30"
   },
   "overrides": {
-    "@earendil-works/pi-agent-core": "0.80.3",
-    "@earendil-works/pi-ai": "0.80.3",
-    "@earendil-works/pi-coding-agent": "0.80.3",
-    "@earendil-works/pi-tui": "0.80.3",
+    "@earendil-works/pi-agent-core": "0.84.2",
+    "@earendil-works/pi-ai": "0.84.2",
+    "@earendil-works/pi-coding-agent": "0.84.2",
+    "@earendil-works/pi-tui": "0.84.2",
     "hono": "^4.12.18",
     "@hono/node-server": "^1.19.13",
     "express-rate-limit": "^8.5.1",
     "fast-uri": "^3.1.2",
-    "path-to-regexp": "^8.4.2"
+    "path-to-regexp": "^8.4.2",
+    "@types/node": "26.2.0"
   },
   "trustedDependencies": [
     "@code-yeongyu/comment-checker"
-  ]
+  ],
+  "patchedDependencies": {
+    "@code-yeongyu/senpi@2026.8.30-3": "patches/@code-yeongyu%2Fsenpi@2026.8.30-3.patch"
+  }
 }

package/packages/git-bash-mcp/dist/cli.js

@@ -276,7 +276,11 @@ function createParentWatchdog(config, onDeadParent) {
   const probeAlive = config.probeAlive ?? isProcessAlive;
   let fired = false;
   const timer = setInterval(() => {
-    if (fired || probeAlive(parentPid))
+    if (fired)
+      return;
+    const alive = probeAlive(parentPid);
+    config.onPoll?.(alive);
+    if (alive)
       return;
     fired = true;
     onDeadParent(parentPid, pollIntervalMs);

package/packages/git-bash-mcp/package.json

@@ -22,6 +22,6 @@
     "@oh-my-opencode/utils": "workspace:*"
   },
   "devDependencies": {
-    "bun-types": "1.3.12"
+    "bun-types": "1.4.0"
   }
 }

package/packages/lsp-core/src/index.ts

@@ -7,6 +7,7 @@ export * from "./lsp/constants.js";
 export * from "./lsp/directory-diagnostics.js";
 export * from "./lsp/effective-extension.js";
 export * from "./lsp/errors.js";
+export * from "./lsp/format-document.js";
 export * from "./lsp/formatters.js";
 export * from "./lsp/infer-extension.js";
 export * from "./lsp/json-rpc-connection.js";

package/packages/lsp-core/src/lsp/client-diagnostics-concurrency.integration.test.ts

@@ -0,0 +1,44 @@
+import { afterEach, describe, expect, it } from "bun:test";
+
+import {
+	createWorkspaceEditTestHarness,
+	diagnostic,
+	readEvents,
+} from "./workspace-apply-edit-test-support.js";
+
+const harness = createWorkspaceEditTestHarness();
+
+afterEach(async () => {
+	await harness.cleanup();
+});
+
+describe("LspClient diagnostics concurrency", () => {
+	it("#given concurrent diagnostics on a cold file and an exact didOpen publish #when pull is not advertised #then one didOpen opens the file and both requests receive the current diagnostics", async () => {
+		const context = await harness.makeClient(
+			{
+				publishDiagnostics: [
+					{
+						trigger: "didOpen",
+						version: 1,
+						diagnostics: [diagnostic("exact-current")],
+						awaitClientDelivery: true,
+					},
+				],
+			},
+			{ diagnosticsFreshnessTimeoutMs: 500, versionlessPublishQuiescenceMs: 5 },
+		);
+
+		const [first, second] = await Promise.all([
+			context.client.diagnostics(context.source),
+			context.client.diagnostics(context.source),
+		]);
+
+		expect(first.items).toEqual([diagnostic("exact-current")]);
+		expect(second.items).toEqual([diagnostic("exact-current")]);
+		expect(
+			readEvents(context.events).filter(
+				(event) => event.type === "clientNotification" && event.method === "textDocument/didOpen",
+			),
+		).toHaveLength(1);
+	});
+});

package/packages/lsp-core/src/lsp/client-diagnostics-freshness.integration.test.ts

@@ -16,34 +16,6 @@ afterEach(async () => {
 });
 
 describe("LspClient diagnostics freshness", () => {
-	it("#given concurrent diagnostics on a cold file and an exact didOpen publish #when pull is not advertised #then one didOpen opens the file and both requests receive the current diagnostics", async () => {
-		const context = await harness.makeClient(
-			{
-				publishDiagnostics: [
-					{
-						trigger: "didOpen",
-						version: 1,
-						diagnostics: [diagnostic("exact-current")],
-					},
-				],
-			},
-			{ diagnosticsFreshnessTimeoutMs: 50, versionlessPublishQuiescenceMs: 5 },
-		);
-
-		const [first, second] = await Promise.all([
-			context.client.diagnostics(context.source),
-			context.client.diagnostics(context.source),
-		]);
-
-		expect(first.items).toEqual([diagnostic("exact-current")]);
-		expect(second.items).toEqual([diagnostic("exact-current")]);
-		expect(
-			readEvents(context.events).filter(
-				(event) => event.type === "clientNotification" && event.method === "textDocument/didOpen",
-			),
-		).toHaveLength(1);
-	});
-
 	it("#given a versionless publish that arrives after the current change #when no newer eligible publish arrives before quiescence #then diagnostics wait for that quiescence window and return the versionless payload", async () => {
 		const context = await harness.makeClient(
 			{

package/packages/lsp-core/src/lsp/client-wrapper-outside-cwd.test.ts

@@ -0,0 +1,78 @@
+import { mkdirSync, mkdtempSync, realpathSync, rmSync, writeFileSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { afterEach, describe, expect, it } from "bun:test";
+
+import { createStandaloneMcpRequestContext, runWithRequestContext } from "../request-context.js";
+import { findWorkspaceRoot, resolveReadablePathInsideContext, resolvePathInsideContext } from "./client-wrapper.js";
+import { LspInvalidPathError } from "./errors.js";
+
+const tempDirectories: string[] = [];
+
+afterEach(() => {
+	for (const directory of tempDirectories.splice(0)) {
+		rmSync(directory, { recursive: true, force: true });
+	}
+});
+
+function tempRoot(prefix: string): string {
+	const root = mkdtempSync(join(tmpdir(), prefix));
+	tempDirectories.push(root);
+	return root;
+}
+
+describe("LSP read-only access outside request cwd", () => {
+	it("#given an absolute file outside cwd #when resolving a read path #then returns the canonical path", () => {
+		const root = tempRoot("lsp-outcwd-root-");
+		const outside = tempRoot("lsp-outcwd-outside-");
+		const outsideFile = join(outside, "probe.ts");
+		writeFileSync(outsideFile, "export const value = 1;\n");
+
+		const resolved = runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+			resolveReadablePathInsideContext(outsideFile),
+		);
+
+		expect(resolved).toBe(realpathSync(outsideFile));
+	});
+
+	it("#given an outside file inside its own marked project #when inferring workspace #then uses that project root", () => {
+		const root = tempRoot("lsp-outcwd-marker-root-");
+		const outside = tempRoot("lsp-outcwd-marker-outside-");
+		mkdirSync(join(outside, ".git"), { recursive: true });
+		mkdirSync(join(outside, "src"), { recursive: true });
+		const outsideFile = join(outside, "src", "probe.ts");
+		writeFileSync(outsideFile, "export const value = 1;\n");
+
+		const workspace = runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+			findWorkspaceRoot(outsideFile),
+		);
+
+		expect(workspace).toBe(realpathSync(outside));
+	});
+
+	it("#given an outside file without any marker #when inferring workspace #then falls back to its own directory", () => {
+		const root = tempRoot("lsp-outcwd-nomarker-root-");
+		const outside = tempRoot("lsp-outcwd-nomarker-outside-");
+		const outsideFile = join(outside, "probe.ts");
+		writeFileSync(outsideFile, "export const value = 1;\n");
+
+		const workspace = runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+			findWorkspaceRoot(outsideFile),
+		);
+
+		expect(workspace).toBe(realpathSync(outside));
+	});
+
+	it("#given an outside file #when resolving a mutating path #then still rejects to keep writes confined", () => {
+		const root = tempRoot("lsp-outcwd-write-root-");
+		const outside = tempRoot("lsp-outcwd-write-outside-");
+		const outsideFile = join(outside, "probe.ts");
+		writeFileSync(outsideFile, "export const value = 1;\n");
+
+		expect(() =>
+			runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+				resolvePathInsideContext(outsideFile),
+			),
+		).toThrow(LspInvalidPathError);
+	});
+});

package/packages/lsp-core/src/lsp/client-wrapper.test.ts

@@ -4,8 +4,9 @@ import { join } from "node:path";
 import { afterEach, describe, expect, it } from "bun:test";
 
 import { createStandaloneMcpRequestContext, runWithRequestContext } from "../request-context.js";
-import { findWorkspaceRoot, resolvePathInsideContext } from "./client-wrapper.js";
+import { findWorkspaceRoot, resolveReadablePathInsideContext, withLspClient } from "./client-wrapper.js";
 import { LspInvalidPathError } from "./errors.js";
+import { LspManager } from "./manager.js";
 
 const tempDirectories: string[] = [];
 
@@ -35,29 +36,81 @@ describe("LSP client path confinement", () => {
 		expect(workspace).toBe(realpathSync(root));
 	});
 
-	it("#given an absolute file outside context cwd #when resolving #then rejects before workspace inference", () => {
+	it("#given an absolute file outside context cwd #when resolving #then infers the file's own project root", () => {
 		const root = tempRoot("lsp-client-wrapper-cwd-");
 		const outside = tempRoot("lsp-client-wrapper-outside-");
 		mkdirSync(join(outside, ".git"), { recursive: true });
 		writeFileSync(join(outside, "file.ts"), "export const outside = true;\n");
 
-		expect(() =>
-			runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
-				findWorkspaceRoot(join(outside, "file.ts")),
-			),
-		).toThrow(LspInvalidPathError);
+		const workspace = runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+			findWorkspaceRoot(join(outside, "file.ts")),
+		);
+
+		expect(workspace).toBe(realpathSync(outside));
 	});
 
-	it("#given a symlink inside cwd that points outside #when resolving #then rejects the escape", () => {
+	it("#given a symlink inside cwd that points outside #when resolving read path #then keeps lexical path and cwd root", () => {
 		const root = tempRoot("lsp-client-wrapper-symlink-root-");
 		const outside = tempRoot("lsp-client-wrapper-symlink-outside-");
+		mkdirSync(join(root, ".git"), { recursive: true });
+		mkdirSync(join(outside, ".git"), { recursive: true });
+		writeFileSync(join(outside, "file.ts"), "export const outside = true;\n");
+		symlinkSync(outside, join(root, "linked"));
+
+		const result = runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () => ({
+			filePath: resolveReadablePathInsideContext("linked/file.ts"),
+			workspaceRoot: findWorkspaceRoot("linked/file.ts"),
+		}));
+
+		expect(result.filePath).toBe(join(realpathSync(root), "linked", "file.ts"));
+		expect(result.workspaceRoot).toBe(realpathSync(root));
+	});
+
+	it("#given an absolute macOS alias path through an outside symlink #when resolving read path #then preserves the lexical suffix", () => {
+		const root = tempRoot("lsp-client-wrapper-alias-root-");
+		const outside = tempRoot("lsp-client-wrapper-alias-outside-");
+		mkdirSync(join(root, ".git"), { recursive: true });
+		writeFileSync(join(outside, "file.ts"), "export const outside = true;\n");
+		symlinkSync(outside, join(root, "linked"));
+
+		const result = runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+			resolveReadablePathInsideContext(join(root, "linked", "file.ts")),
+		);
+
+		expect(result).toBe(join(realpathSync(root), "linked", "file.ts"));
+	});
+
+	it("#given missing parent directories without markers #when resolving workspace #then uses an existing directory", () => {
+		const root = tempRoot("lsp-client-wrapper-missing-root-");
+		const workspace = runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+			findWorkspaceRoot("missing/deep/file.ts"),
+		);
+
+		expect(workspace).toBe(realpathSync(root));
+	});
+
+	it("#given a symlink inside cwd that points outside #when starting rename #then rejects before client acquisition", async () => {
+		const root = tempRoot("lsp-client-wrapper-rename-root-");
+		const outside = tempRoot("lsp-client-wrapper-rename-outside-");
 		writeFileSync(join(outside, "file.ts"), "export const outside = true;\n");
 		symlinkSync(outside, join(root, "linked"));
+		let clientFactoryCalls = 0;
+		const manager = new LspManager({
+			clientFactory: () => {
+				clientFactoryCalls += 1;
+				throw new Error("client acquisition must not start");
+			},
+		});
 
-		expect(() =>
-			runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
-				resolvePathInsideContext("linked/file.ts"),
-			),
-		).toThrow(LspInvalidPathError);
+		try {
+			await expect(
+				runWithRequestContext(createStandaloneMcpRequestContext({ cwd: root }), () =>
+					withLspClient("linked/file.ts", async () => undefined, "rename", { manager }),
+				),
+			).rejects.toThrow(LspInvalidPathError);
+			expect(clientFactoryCalls).toBe(0);
+		} finally {
+			await manager.stopAll();
+		}
 	});
 });

package/packages/lsp-core/src/lsp/client-wrapper.ts

@@ -1,5 +1,5 @@
-import { existsSync, statSync } from "node:fs";
-import { dirname, join, resolve } from "node:path";
+import { existsSync, realpathSync, statSync } from "node:fs";
+import { basename, dirname, join, resolve } from "node:path";
 import {
 	canonicalizeExistingOrNearestAncestor,
 	contextCwd,
@@ -16,11 +16,12 @@ import {
 	LspServerLookupError,
 } from "./errors.js";
 import { getLspManager, type LspManager } from "./manager.js";
+import { findWorkspaceRootOutsideContext } from "./outside-context-workspace.js";
+import { LSP_LOCAL_INSTALL_HINTS } from "./server-definitions.js";
 import { loadInstallDecision } from "./server-install-state.js";
 import { findServerForExtension } from "./server-resolution.js";
 import type { ServerLookupResult } from "./types.js";
-
-const WORKSPACE_MARKERS = [".git", "package.json", "pyproject.toml", "Cargo.toml", "go.mod", "pom.xml", "build.gradle"];
+import { WORKSPACE_MARKERS } from "./workspace-markers.js";
 
 export function isDirectoryPath(filePath: string): boolean {
 	try {
@@ -31,30 +32,47 @@ export function isDirectoryPath(filePath: string): boolean {
 }
 
 export function findWorkspaceRoot(filePath: string): string {
-	const abs = resolvePathInsideContext(filePath);
+	const cwd = contextCwd();
+	const abs = resolveReadablePathInsideContext(filePath);
 	let dir = abs;
 
 	if (!isDirectoryPath(dir)) {
 		dir = dirname(dir);
 	}
 
-	let prevDir = "";
-	while (dir !== prevDir) {
-		for (const marker of WORKSPACE_MARKERS) {
-			if (existsSync(join(dir, marker))) {
-				return dir;
+	if (!isPathInside(cwd, abs)) return findWorkspaceRootOutsideContext(dir);
+
+	const fallbackRoot = nearestExistingDirectoryInsideContext(dir, cwd) ?? cwd;
+	while (isPathInside(cwd, dir)) {
+		const canonicalDir = existingDirectoryInsideContext(dir, cwd);
+		if (canonicalDir !== undefined) {
+			for (const marker of WORKSPACE_MARKERS) {
+				if (existsSync(join(dir, marker))) {
+					return canonicalDir;
+				}
 			}
 		}
-		prevDir = dir;
+		if (dir === cwd) break;
 		dir = dirname(dir);
 	}
 
-	return dirname(abs);
+	return fallbackRoot;
 }
 
-export function resolvePathInsideContext(filePath: string): string {
+export function resolveReadablePathInsideContext(filePath: string): string {
 	const cwd = contextCwd();
 	const abs = resolve(cwd, filePath);
+	if (isPathInside(cwd, abs)) return abs;
+
+	const rebased = rebaseThroughCanonicalAncestor(abs, cwd);
+	if (rebased !== undefined) return rebased;
+
+	return canonicalizeExistingOrNearestAncestor(abs);
+}
+
+export function resolvePathInsideContext(filePath: string): string {
+	const cwd = contextCwd();
+	const abs = resolveReadablePathInsideContext(filePath);
 	const canonical = canonicalizeExistingOrNearestAncestor(abs);
 	if (!isPathInside(cwd, canonical)) {
 		throw new LspInvalidPathError(`LSP file path must be inside request cwd: ${filePath}`);
@@ -62,6 +80,39 @@ export function resolvePathInsideContext(filePath: string): string {
 	return canonical;
 }
 
+function rebaseThroughCanonicalAncestor(path: string, cwd: string): string | undefined {
+	let current = path;
+	const suffix: string[] = [];
+	while (true) {
+		if (existsSync(current)) {
+			const canonical = realpathSync(current);
+			if (isPathInside(cwd, canonical)) return suffix.length === 0 ? canonical : join(canonical, ...suffix);
+		}
+		const parent = dirname(current);
+		if (parent === current) return undefined;
+		suffix.unshift(basename(current));
+		current = parent;
+	}
+}
+
+function existingDirectoryInsideContext(directory: string, cwd: string): string | undefined {
+	if (!existsSync(directory)) return undefined;
+	const canonical = realpathSync(directory);
+	if (!statSync(canonical).isDirectory()) return undefined;
+	return isPathInside(cwd, canonical) ? canonical : undefined;
+}
+
+function nearestExistingDirectoryInsideContext(directory: string, cwd: string): string | undefined {
+	let current = directory;
+	while (isPathInside(cwd, current)) {
+		const canonical = existingDirectoryInsideContext(current, cwd);
+		if (canonical !== undefined) return canonical;
+		if (current === cwd) return undefined;
+		current = dirname(current);
+	}
+	return undefined;
+}
+
 export function formatServerLookupError(result: Exclude<ServerLookupResult, { status: "found" }>): string {
 	if (result.status === "not_installed") {
 		return formatNotInstalled(result);
@@ -88,6 +139,26 @@ export function formatServerLookupError(result: Exclude<ServerLookupResult, { st
 	].join("\n");
 }
 
+/**
+ * Builds the install guidance, offering the repo-local install first.
+ *
+ * A repo-local install is resolvable without touching the global environment, so it is the
+ * recommended route whenever the server ships as a project dependency.
+ */
+function formatInstallOptions(serverId: string, installHint: string): string[] {
+	const localHint = LSP_LOCAL_INSTALL_HINTS[serverId];
+	if (localHint === undefined) {
+		return ["To install, run:", `  ${installHint}`];
+	}
+	return [
+		"To install in THIS repository (preferred — no global install needed):",
+		`  ${localHint}`,
+		"",
+		"Or install it globally:",
+		`  ${installHint}`,
+	];
+}
+
 function formatNotInstalled(result: Extract<ServerLookupResult, { status: "not_installed" }>): string {
 	const { server, installHint } = result;
 	const extensions = server.extensions.join(", ");
@@ -104,20 +175,20 @@ function formatNotInstalled(result: Extract<ServerLookupResult, { status: "not_i
 		`Command not found: ${server.command[0]}`,
 		"",
 	];
+	const installOptions = formatInstallOptions(server.id, installHint);
 
 	if (decision === "allowed") {
 		return [
 			...header,
 			"The user has pre-authorized LSP installation. Run the install command, then retry this tool:",
-			`  ${installHint}`,
+			...installOptions.slice(1),
 		].join("\n");
 	}
 
 	if (!context.capabilities.installDecisionTool) {
 		return [
 			...header,
-			"To install, run:",
-			`  ${installHint}`,
+			...installOptions,
 			"",
 			"ACTION REQUIRED — ASK THE USER whether to install this LSP server.",
 			"Install-decision recording is unavailable in this harness; proceed without LSP if the user declines.",
@@ -126,8 +197,7 @@ function formatNotInstalled(result: Extract<ServerLookupResult, { status: "not_i
 
 	return [
 		...header,
-		"To install, run:",
-		`  ${installHint}`,
+		...installOptions,
 		"",
 		"ACTION REQUIRED — ASK THE USER whether to install this LSP server.",
 		"- If the user agrees: run the install command above, then retry this tool.",
@@ -143,7 +213,7 @@ export interface WithLspClientOptions {
 	manager?: LspManager;
 }
 
-const READ_ONLY_RETRY_TOOLS = new Set([
+const READ_ONLY_TOOLS = new Set([
 	"diagnostics",
 	"definition",
 	"references",
@@ -154,11 +224,13 @@ const READ_ONLY_RETRY_TOOLS = new Set([
 
 export async function withLspClient<T>(
 	filePath: string,
-	fn: (client: LspClient, workspaceRoot: string) => Promise<T>,
+	fn: (client: LspClient, workspaceRoot: string, resolvedFilePath: string) => Promise<T>,
 	toolName: string,
 	options: WithLspClientOptions = {},
 ): Promise<T> {
-	const absPath = resolvePathInsideContext(filePath);
+	const absPath = READ_ONLY_TOOLS.has(toolName)
+		? resolveReadablePathInsideContext(filePath)
+		: resolvePathInsideContext(filePath);
 
 	if (isDirectoryPath(absPath)) {
 		throw new LspInvalidPathError(
@@ -181,9 +253,9 @@ export async function withLspClient<T>(
 		const client = await manager.getClient(root, server, options.signal);
 
 		try {
-			return await fn(client, root);
+			return await fn(client, root, absPath);
 		} catch (err) {
-			if (allowRetry && READ_ONLY_RETRY_TOOLS.has(toolName) && isLspDeadConnectionError(err)) {
+			if (allowRetry && READ_ONLY_TOOLS.has(toolName) && isLspDeadConnectionError(err)) {
 				manager.invalidateClient(root, server.id, client);
 				return acquireAndCall(false);
 			}