@octocodeai/octocode-engine 16.6.2 → 16.7.0

package/dist/lsp/config.js

@@ -137,7 +137,7 @@ function withBundledJsServer(config) {
     }
     // 2) Language-keyed: a different bundled server than the native default
     //    (e.g. pyright for Python); use the bundled server's own launch args.
-    const byLanguage = config.languageId
+    const byLanguage = path.basename(config.command) === config.command && config.languageId
         ? BUNDLED_BY_LANGUAGE[config.languageId]
         : undefined;
     if (byLanguage) {

package/dist/lsp/lspClientPool.d.ts

@@ -21,7 +21,9 @@ export declare class LspClientPool<T extends PooledClient> {
     clearAll(): Promise<void>;
     size(): number;
     keys(): PoolKey[];
+    has(key: PoolKey): boolean;
     private resetIdleTimer;
     private startIdleTimer;
 }
+export declare function serializeKey(key: PoolKey): string;
 export {};

package/dist/lsp/lspClientPool.js

@@ -53,6 +53,10 @@ export class LspClientPool {
     keys() {
         return [...this.entries.values()].map(entry => entry.key);
     }
+    has(key) {
+        const k = serializeKey(key);
+        return this.entries.has(k) || this.inflight.has(k);
+    }
     resetIdleTimer(k) {
         const entry = this.entries.get(k);
         if (!entry)
@@ -68,13 +72,14 @@ export class LspClientPool {
             this.entries.delete(k);
             void safeStop(entry.client);
         }, this.options.idleTimeoutMs);
-        if (typeof timer === 'object' && 'unref' in timer) {
-            timer.unref();
-        }
+        // This package is Node-only (napi-rs). The timer is always a NodeJS.Timeout
+        // with an unref() method; calling it keeps the idle timer from preventing
+        // a clean process exit when no real work is in flight.
+        timer.unref?.();
         return timer;
     }
 }
-function serializeKey(key) {
+export function serializeKey(key) {
     return `${key.serverId ?? key.languageId}\u0000${key.workspaceRoot}`;
 }
 async function safeStop(client) {

package/dist/lsp/manager.js

@@ -1,6 +1,6 @@
 import { LSPClient } from './client.js';
 import { getLanguageServerForFile, resolveServerForFile, } from './config.js';
-import { LspClientPool } from './lspClientPool.js';
+import { LspClientPool, serializeKey } from './lspClientPool.js';
 import { manifestInstallHint } from './serverManifest.js';
 import { resolveWorkspaceRootForFile } from './workspaceRoot.js';
 export async function isLanguageServerAvailable(filePath, workspaceRoot) {
@@ -66,10 +66,24 @@ const DEFAULT_READY_TIMEOUT_MS = 30_000;
 function readyTimeoutForLanguage(languageId) {
     return SERVER_READY_TIMEOUT_MS[languageId] ?? DEFAULT_READY_TIMEOUT_MS;
 }
+// Eliminates the double getLanguageServerForFile call that would otherwise
+// happen once in poolKeyForFile (to build the key) and again inside the factory
+// (to create the client). poolKeyForFile deposits the already-resolved config
+// here before calling sharedPool.acquire; the factory reads and clears it.
+//
+// The deposit is conditional: when sharedPool already has an entry or an
+// inflight promise for this key, acquire() returns the cached client or the
+// existing promise WITHOUT invoking the factory — so depositing again here
+// would never be read or cleared and would leak the entry forever. Key format
+// is the shared serializeKey from lspClientPool.ts.
+const _pendingConfigs = new Map();
 const sharedPool = new LspClientPool({
     idleTimeoutMs: POOL_IDLE_TIMEOUT_MS,
     factory: async (key) => {
-        const serverConfig = await getLanguageServerForFile(synthesizeFilePathForKey(key), key.workspaceRoot);
+        const cacheKey = serializeKey(key);
+        const serverConfig = _pendingConfigs.get(cacheKey) ??
+            (await getLanguageServerForFile(synthesizeFilePathForKey(key), key.workspaceRoot));
+        _pendingConfigs.delete(cacheKey);
         if (!serverConfig)
             return null;
         const client = new LSPClient(serverConfig);
@@ -147,10 +161,18 @@ async function poolKeyForFile(workspaceRoot, filePath) {
     const serverConfig = await getLanguageServerForFile(filePath, workspaceRoot);
     if (!serverConfig)
         return null;
-    return {
+    const key = {
         workspaceRoot,
         filePath,
         languageId: serverConfig.languageId ?? 'unknown',
         serverId: `${serverConfig.command} ${(serverConfig.args ?? []).join(' ')}`.trim(),
     };
+    const serialized = serializeKey(key);
+    // Only deposit when the pool will actually call the factory for this key.
+    // If there's already an entry or inflight, acquire() won't start a new factory
+    // run — so depositing here would permanently leak the entry.
+    if (!sharedPool.has(key)) {
+        _pendingConfigs.set(serialized, serverConfig);
+    }
+    return key;
 }

package/dist/lsp/native.d.ts

@@ -1,7 +1,8 @@
+import type { LspReadiness } from './types.js';
 export type NativeLspClientBinding = {
     start(): Promise<void>;
     stop(): Promise<void>;
-    waitForReady(timeoutMs?: number): Promise<void>;
+    waitForReady(timeoutMs?: number): Promise<LspReadiness | undefined>;
     hasCapability?(capability: string): boolean;
     getRecentStderr?(): string[];
     openDocument(filePath: string, content: string): Promise<void>;

package/dist/lsp/resolver.js

@@ -1,4 +1,4 @@
-import { readFile } from 'node:fs/promises';
+import { access, constants, readFile } from 'node:fs/promises';
 import path from 'node:path';
 import { nativeBinding } from './native.js';
 export class SymbolResolutionError extends Error {
@@ -7,7 +7,7 @@ export class SymbolResolutionError extends Error {
     reason;
     searchRadius;
     constructor(symbolName, lineHint, reason, searchRadius = 5) {
-        super(`Could not find symbol '${symbolName}' at or near line ${lineHint}. ${reason}`);
+        super(`Could not find symbol '${symbolName}' at or near line ${lineHint}.${reason ? ` ${reason}` : ''}`);
         this.symbolName = symbolName;
         this.lineHint = lineHint;
         this.reason = reason;
@@ -27,7 +27,13 @@ function normalizeResolvedSymbol(value) {
 function toSymbolResolutionError(error, fuzzy, searchRadius = 5) {
     if (error instanceof SymbolResolutionError)
         return error;
-    const reason = error instanceof Error ? error.message : String(error);
+    const raw = error instanceof Error ? error.message : String(error);
+    // The native resolver already emits the canonical "Could not find symbol …"
+    // sentence; strip it so the wrapper message doesn't repeat it.
+    const prefix = `Could not find symbol '${fuzzy.symbolName}' at or near line ${fuzzy.lineHint ?? 0}`;
+    const reason = raw.startsWith(prefix)
+        ? raw.slice(prefix.length).replace(/^[.\s]+/, '')
+        : raw;
     return new SymbolResolutionError(fuzzy.symbolName, fuzzy.lineHint ?? 0, reason, searchRadius);
 }
 export function resolveSymbolPosition(fileOrContent, fuzzyOrSymbolName, lineHint, orderHint) {
@@ -152,7 +158,7 @@ async function resolveLocalModulePath(importerPath, moduleSpecifier) {
     ];
     for (const candidate of candidates) {
         try {
-            await readFile(candidate, 'utf-8');
+            await access(candidate, constants.R_OK);
             return candidate;
         }
         catch {

package/dist/lsp/serverManifest.d.ts

@@ -7,7 +7,7 @@ import { type PlatformId } from './platform.js';
  * managed-cache locator.
  *
  * Provisioning policy (see docs/context/LSP_GUIDE.md):
- *   OCTOCODE_LSP_AUTO_INSTALL = off (default) | prompt | auto
+ *   OCTOCODE_LSP_AUTO_INSTALL = prompt (default) | off | auto
  * Live network download is gated and requires a pinned `sha256` per asset.
  * Until SHAs are pinned the manifest still drives (a) honest detect-and-instruct
  * guidance and (b) reuse of a server a user/CI has pre-populated into the
@@ -61,9 +61,10 @@ export declare function cachedServerBinPath(serverName: string, platformId?: Pla
 /**
  * If a managed binary is already present AND verified in the cache (downloaded
  * by a prior run, by CI, or pre-baked), return its absolute path. A binary is
- * only trusted when its sibling `<binName>.ok` completion marker exists — a
- * half-written binary from an interrupted install has no marker and is ignored,
- * so it never resolves as "installed". Read-only — always safe to call.
+ * only trusted when its sibling `<binName>.ok` completion marker contains the
+ * current binary's SHA-256 and size. A half-written or tampered binary from an
+ * interrupted install has no matching marker and is ignored, so it never
+ * resolves as "installed". Read-only — always safe to call.
  */
 export declare function resolveCachedServer(serverName: string, platformId?: PlatformId): string | null;
 /** Human-readable provisioning guidance for a server with no resolved binary. */

package/dist/lsp/serverManifest.js

@@ -1,4 +1,5 @@
-import { existsSync } from 'node:fs';
+import { createHash } from 'node:crypto';
+import { existsSync, readFileSync, statSync } from 'node:fs';
 import { homedir } from 'node:os';
 import path from 'node:path';
 import { detectPlatformId } from './platform.js';
@@ -6,6 +7,30 @@ import { MANIFEST } from './serverManifestData.js';
 function loadManifest() {
     return MANIFEST;
 }
+function sha256File(filePath) {
+    try {
+        return createHash('sha256').update(readFileSync(filePath)).digest('hex');
+    }
+    catch {
+        return null;
+    }
+}
+function readCacheMarker(markerPath) {
+    try {
+        const parsed = JSON.parse(readFileSync(markerPath, 'utf8'));
+        if (typeof parsed.binarySha256 !== 'string' ||
+            !/^[0-9a-f]{64}$/u.test(parsed.binarySha256) ||
+            typeof parsed.size !== 'number' ||
+            !Number.isSafeInteger(parsed.size) ||
+            parsed.size < 0) {
+            return null;
+        }
+        return { binarySha256: parsed.binarySha256, size: parsed.size };
+    }
+    catch {
+        return null;
+    }
+}
 /** The configured auto-install policy. Defaults to `prompt` when unset (asks before downloading). Set OCTOCODE_LSP_AUTO_INSTALL=off to disable all downloads, or =auto to skip the prompt. */
 export function provisionMode(env = process.env) {
     const raw = (env.OCTOCODE_LSP_AUTO_INSTALL ?? '').trim().toLowerCase();
@@ -51,15 +76,28 @@ export function cachedServerBinPath(serverName, platformId = detectPlatformId())
 /**
  * If a managed binary is already present AND verified in the cache (downloaded
  * by a prior run, by CI, or pre-baked), return its absolute path. A binary is
- * only trusted when its sibling `<binName>.ok` completion marker exists — a
- * half-written binary from an interrupted install has no marker and is ignored,
- * so it never resolves as "installed". Read-only — always safe to call.
+ * only trusted when its sibling `<binName>.ok` completion marker contains the
+ * current binary's SHA-256 and size. A half-written or tampered binary from an
+ * interrupted install has no matching marker and is ignored, so it never
+ * resolves as "installed". Read-only — always safe to call.
  */
 export function resolveCachedServer(serverName, platformId = detectPlatformId()) {
     const binPath = cachedServerBinPath(serverName, platformId);
-    if (!binPath)
+    if (!binPath || !existsSync(binPath))
+        return null;
+    const marker = readCacheMarker(`${binPath}.ok`);
+    if (!marker)
+        return null;
+    let size;
+    try {
+        size = statSync(binPath).size;
+    }
+    catch {
+        return null;
+    }
+    if (size !== marker.size)
         return null;
-    return existsSync(binPath) && existsSync(`${binPath}.ok`) ? binPath : null;
+    return sha256File(binPath) === marker.binarySha256 ? binPath : null;
 }
 /** Human-readable provisioning guidance for a server with no resolved binary. */
 export function manifestInstallHint(serverName) {

package/dist/lsp/serverManifestData.js

@@ -1,33 +1,96 @@
 export const MANIFEST = {
-    "$comment": "Auto-download manifest for portable, toolchain-free language servers. Verified 2026-06-28 against live GitHub Releases. SHA-256 pinned per asset — download is refused if the checksum mismatches. Scope: Rust (rust-analyzer, gz, auto-download ready), C/C++ (clangd, zip, auto-download ready). Toolchain-coupled servers (gopls/go, jdtls/jre) are detect-and-instruct; pure-JS servers (typescript-language-server, pyright, yaml/json/html/css) are bundled npm deps. Markdown/MDX handled by the MINIFIER, NOT LSP.",
+    "$comment": "Auto-download manifest for portable, toolchain-free language servers. Verified 2026-06-28 against live GitHub Releases. SHA-256 pinned per asset — download is refused if the checksum mismatches. Scope: Rust (rust-analyzer, gz, auto-download ready), C/C++ (clangd, zip, auto-download ready). Toolchain-coupled servers (gopls/go, jdtls/jre) are detect-and-instruct; pure-JS servers (typescript-language-server, pyright, yaml/json/html/css) are bundled npm deps. Markdown/MDX handled by the MINIFIER, NOT LSP. This JSON is the source of truth; src/lsp/serverManifestData.ts is generated from it by scripts/gen-server-manifest.mjs (run via `yarn manifest:gen` / the `verify:manifest` gate).",
     "version": 1,
     "servers": {
-        "rust-analyzer": {
-            "languageId": "rust",
-            "repo": "rust-lang/rust-analyzer",
-            "releaseTag": "2026-06-22",
-            "platforms": {
-                "darwin-arm64": { "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-aarch64-apple-darwin.gz", "archive": "gz", "binName": "rust-analyzer", "sha256": "c8cdf6d5e488752b907d5ee15e31768b59a78d992e9a54b9f9660e1bfdf39f27" },
-                "darwin-x64": { "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-x86_64-apple-darwin.gz", "archive": "gz", "binName": "rust-analyzer", "sha256": "feb7c170d2c1a2e4b8a88ac73f937eddb576828e3821b0a63ee0e64bd0bc9440" },
-                "linux-x64": { "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-x86_64-unknown-linux-gnu.gz", "archive": "gz", "binName": "rust-analyzer", "sha256": "9602ca5b24dcaa07a5a021274763bed367d8a32da9a226fe3e139de3306569cb" },
-                "linux-x64-musl": { "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-x86_64-unknown-linux-musl.gz", "archive": "gz", "binName": "rust-analyzer", "sha256": "fe1d7b0e9733f7a439e4b6f27b8c4cc7afd87ae28fc5b496eb8df31d674b78dd" },
-                "linux-arm64": { "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-aarch64-unknown-linux-gnu.gz", "archive": "gz", "binName": "rust-analyzer", "sha256": "bf65b0d4586f127ab11bf33476dd6aac82dad173946c5d3b1cede19d63ae85ed" },
-                "win32-x64": { "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-x86_64-pc-windows-msvc.zip", "archive": "zip", "binPath": "rust-analyzer.exe", "binName": "rust-analyzer.exe", "sha256": "6071dc5b28aa6d22c715f63c08d75b827c066be4ea866796587e52ed48b2922f" },
-                "win32-arm64": { "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-aarch64-pc-windows-msvc.zip", "archive": "zip", "binPath": "rust-analyzer.exe", "binName": "rust-analyzer.exe", "sha256": "30f873713ea3663db10999c23e95b74fe19968c893d5c0e9b8a896b31dbf8cf8" }
-            }
-        },
         "clangd": {
             "languageId": "cpp",
-            "repo": "clangd/clangd",
-            "releaseTag": "22.1.0",
             "launchArgs": [],
             "platforms": {
-                "darwin-arm64": { "url": "https://github.com/clangd/clangd/releases/download/22.1.0/clangd-mac-22.1.0.zip", "archive": "zip", "binPath": "clangd_22.1.0/bin/clangd", "binName": "clangd", "sha256": "e31e271fe11f6dcd7cf87ca74be4a12788ff8ce5a0b07762583e335c058e939a" },
-                "darwin-x64": { "url": "https://github.com/clangd/clangd/releases/download/22.1.0/clangd-mac-22.1.0.zip", "archive": "zip", "binPath": "clangd_22.1.0/bin/clangd", "binName": "clangd", "sha256": "e31e271fe11f6dcd7cf87ca74be4a12788ff8ce5a0b07762583e335c058e939a" },
-                "linux-x64": { "url": "https://github.com/clangd/clangd/releases/download/22.1.0/clangd-linux-22.1.0.zip", "archive": "zip", "binPath": "clangd_22.1.0/bin/clangd", "binName": "clangd", "sha256": "71eddc5303da9a5bc5e8b509488b5b2c5acf45f20e33b8394e71a12a56d67198" },
-                "win32-x64": { "url": "https://github.com/clangd/clangd/releases/download/22.1.0/clangd-windows-22.1.0.zip", "archive": "zip", "binPath": "clangd_22.1.0/bin/clangd.exe", "binName": "clangd.exe", "sha256": "c54e57dbff3ccc9e8352367ddb7030ad3f624073ec58c7477424e7919f578572" }
+                "darwin-arm64": {
+                    "url": "https://github.com/clangd/clangd/releases/download/22.1.0/clangd-mac-22.1.0.zip",
+                    "archive": "zip",
+                    "binPath": "clangd_22.1.0/bin/clangd",
+                    "binName": "clangd",
+                    "sha256": "e31e271fe11f6dcd7cf87ca74be4a12788ff8ce5a0b07762583e335c058e939a"
+                },
+                "darwin-x64": {
+                    "url": "https://github.com/clangd/clangd/releases/download/22.1.0/clangd-mac-22.1.0.zip",
+                    "archive": "zip",
+                    "binPath": "clangd_22.1.0/bin/clangd",
+                    "binName": "clangd",
+                    "sha256": "e31e271fe11f6dcd7cf87ca74be4a12788ff8ce5a0b07762583e335c058e939a"
+                },
+                "linux-x64": {
+                    "url": "https://github.com/clangd/clangd/releases/download/22.1.0/clangd-linux-22.1.0.zip",
+                    "archive": "zip",
+                    "binPath": "clangd_22.1.0/bin/clangd",
+                    "binName": "clangd",
+                    "sha256": "71eddc5303da9a5bc5e8b509488b5b2c5acf45f20e33b8394e71a12a56d67198"
+                },
+                "win32-x64": {
+                    "url": "https://github.com/clangd/clangd/releases/download/22.1.0/clangd-windows-22.1.0.zip",
+                    "archive": "zip",
+                    "binPath": "clangd_22.1.0/bin/clangd.exe",
+                    "binName": "clangd.exe",
+                    "sha256": "c54e57dbff3ccc9e8352367ddb7030ad3f624073ec58c7477424e7919f578572"
+                }
             },
-            "unsupportedPlatforms": { "linux-arm64": "clangd publishes no linux-arm64 release asset; install via the system package manager." }
+            "releaseTag": "22.1.0",
+            "repo": "clangd/clangd",
+            "unsupportedPlatforms": {
+                "linux-arm64": "clangd publishes no linux-arm64 release asset; install via the system package manager."
+            }
+        },
+        "rust-analyzer": {
+            "languageId": "rust",
+            "platforms": {
+                "darwin-arm64": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-aarch64-apple-darwin.gz",
+                    "archive": "gz",
+                    "binName": "rust-analyzer",
+                    "sha256": "c8cdf6d5e488752b907d5ee15e31768b59a78d992e9a54b9f9660e1bfdf39f27"
+                },
+                "darwin-x64": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-x86_64-apple-darwin.gz",
+                    "archive": "gz",
+                    "binName": "rust-analyzer",
+                    "sha256": "feb7c170d2c1a2e4b8a88ac73f937eddb576828e3821b0a63ee0e64bd0bc9440"
+                },
+                "linux-arm64": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-aarch64-unknown-linux-gnu.gz",
+                    "archive": "gz",
+                    "binName": "rust-analyzer",
+                    "sha256": "bf65b0d4586f127ab11bf33476dd6aac82dad173946c5d3b1cede19d63ae85ed"
+                },
+                "linux-x64": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-x86_64-unknown-linux-gnu.gz",
+                    "archive": "gz",
+                    "binName": "rust-analyzer",
+                    "sha256": "9602ca5b24dcaa07a5a021274763bed367d8a32da9a226fe3e139de3306569cb"
+                },
+                "linux-x64-musl": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-x86_64-unknown-linux-musl.gz",
+                    "archive": "gz",
+                    "binName": "rust-analyzer",
+                    "sha256": "fe1d7b0e9733f7a439e4b6f27b8c4cc7afd87ae28fc5b496eb8df31d674b78dd"
+                },
+                "win32-arm64": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-aarch64-pc-windows-msvc.zip",
+                    "archive": "zip",
+                    "binPath": "rust-analyzer.exe",
+                    "binName": "rust-analyzer.exe",
+                    "sha256": "30f873713ea3663db10999c23e95b74fe19968c893d5c0e9b8a896b31dbf8cf8"
+                },
+                "win32-x64": {
+                    "url": "https://github.com/rust-lang/rust-analyzer/releases/download/2026-06-22/rust-analyzer-x86_64-pc-windows-msvc.zip",
+                    "archive": "zip",
+                    "binPath": "rust-analyzer.exe",
+                    "binName": "rust-analyzer.exe",
+                    "sha256": "6071dc5b28aa6d22c715f63c08d75b827c066be4ea866796587e52ed48b2922f"
+                }
+            },
+            "releaseTag": "2026-06-22",
+            "repo": "rust-lang/rust-analyzer"
         }
     }
 };

package/dist/lsp/serverProvisioner.js

@@ -19,8 +19,8 @@ import { cachedServerBinPath, managedCacheRoot, manifestServer, provisionMode, r
  *   - atomic: download to a temp file in the dest dir, verify, chmod, rename
  *   - `.ok` completion marker written last, so a partial install never resolves
  *   - per-target lock so editor + CLI don't race the same download
- * v1 handles `gz` and `none` (raw) assets with zero new deps; archive formats
- * needing zip/tar/xz extraction return a clear "install manually" error.
+ * v1 handles `gz`, `zip`, and `none` (raw) assets with zero new deps; archive
+ * formats needing tar/xz extraction return a clear "install manually" error.
  */
 const ALLOWED_HOSTS = new Set([
     'github.com',
@@ -136,6 +136,10 @@ function extractFromZip(zipBuffer, targetPath) {
             .toString('utf8')
             .replace(/^\.?\//u, '');
         const dataOffset = offset + 30 + filenameLen + extraLen;
+        // Guard against a malformed or truncated ZIP with bogus size fields —
+        // compressedSize is UInt32 and could overflow past the buffer.
+        if (dataOffset + compressedSize > zipBuffer.length)
+            break;
         if (filename === normalizedTarget) {
             const compressed = zipBuffer.subarray(dataOffset, dataOffset + compressedSize);
             if (compressionMethod === 0)
@@ -227,8 +231,13 @@ export async function provisionServer(serverName, options = {}) {
         if (process.platform !== 'win32')
             chmodSync(tmpPath, 0o755);
         renameSync(tmpPath, binPath);
-        // Completion marker LAST — resolveCachedServer trusts the binary only now.
-        writeFileSync(`${binPath}.ok`, JSON.stringify({ sha256: asset.sha256, size: extracted.bytes.length }));
+        // Completion marker LAST — resolveCachedServer trusts only a marker that
+        // matches the final binary's hash and size.
+        writeFileSync(`${binPath}.ok`, JSON.stringify({
+            assetSha256: asset.sha256,
+            binarySha256: sha256(extracted.bytes),
+            size: extracted.bytes.length,
+        }));
         return { ok: true, path: binPath, source: 'downloaded' };
     }
     finally {

package/dist/lsp/types.d.ts

@@ -1,4 +1,15 @@
 export type InitializationOptions = Record<string, unknown>;
+/**
+ * Outcome of `waitForReady` — a readiness signal that lets a zero-results
+ * semantic query be interpreted honestly:
+ *   - `progressIdle`   — a `$/progress` indexing cycle was seen and drained to
+ *     idle; an empty answer reflects the fully-indexed project.
+ *   - `settledFallback`— no `$/progress` was ever seen, only the fixed settle
+ *     window elapsed; indexing completion is unconfirmed.
+ *   - `timeout`        — `$/progress` was still active when the deadline hit;
+ *     the server is (as far as we know) still indexing.
+ */
+export type LspReadiness = 'progressIdle' | 'settledFallback' | 'timeout';
 /**
  * Where a language-server executable was resolved from, for honest status
  * reporting. Ordered by the resolution ladder (see docs/context/LSP_GUIDE.md):

package/dist/security/commandValidator.js

@@ -201,6 +201,12 @@ function validateCommandArgs(command, args) {
             };
         }
     }
+    else {
+        const backendError = validateArchiveBackendArgs(command, args);
+        if (backendError) {
+            return { isValid: false, error: backendError };
+        }
+    }
     // grep: no per-flag allowlist — only the shared dangerous-pattern scan below
     // applies. grep flags are wide (e.g. -r, -Z, --include) and intentionally
     // left to the pattern scan rather than a strict allowlist.
@@ -277,6 +283,64 @@ function getGrepPatternPositions(args) {
     }
     return positions;
 }
+function isPathLikeArg(value) {
+    return value.length > 0 && !value.startsWith('-');
+}
+function exactArgs(args, expected) {
+    return args.length === expected.length && args.every((arg, i) => arg === expected[i]);
+}
+function validateArchiveBackendArgs(command, args) {
+    switch (command) {
+        case 'file':
+            return args.length === 3 && exactArgs(args.slice(0, 2), ['--mime-type', '-b']) && isPathLikeArg(args[2])
+                ? null
+                : 'file arguments are restricted to --mime-type -b <path>';
+        case 'zcat':
+        case 'bzcat':
+        case 'zstdcat':
+        case 'lz4cat':
+            return args.length === 1 && isPathLikeArg(args[0])
+                ? null
+                : `${command} arguments are restricted to <path>`;
+        case 'gunzip':
+            return args.length === 2 && args[0] === '-c' && isPathLikeArg(args[1])
+                ? null
+                : 'gunzip arguments are restricted to -c <path>';
+        case 'xzcat':
+            return (args.length === 1 && isPathLikeArg(args[0])) ||
+                (args.length === 2 && args[0] === '--format=lzma' && isPathLikeArg(args[1]))
+                ? null
+                : 'xzcat arguments are restricted to <path> or --format=lzma <path>';
+        case 'zstd':
+            return args.length === 2 && args[0] === '-dcq' && isPathLikeArg(args[1])
+                ? null
+                : 'zstd arguments are restricted to -dcq <path>';
+        case 'brotli':
+            return args.length === 2 && args[0] === '-dc' && isPathLikeArg(args[1])
+                ? null
+                : 'brotli arguments are restricted to -dc <path>';
+        case 'lzfse':
+            return args.length === 5 && exactArgs(args.slice(0, 2), ['-decode', '-i']) && isPathLikeArg(args[2]) && args[3] === '-o' && args[4] === '/dev/stdout'
+                ? null
+                : 'lzfse arguments are restricted to -decode -i <path> -o /dev/stdout';
+        case 'tar':
+        case 'bsdtar':
+            return args.length === 4 && args[0] === '-xOf' && isPathLikeArg(args[1]) && args[2] === '--' && args[3].length > 0
+                ? null
+                : `${command} arguments are restricted to -xOf <archive> -- <entry>`;
+        case 'unzip':
+            return args.length === 3 && args[0] === '-p' && isPathLikeArg(args[1]) && args[2].length > 0
+                ? null
+                : 'unzip arguments are restricted to -p <archive> <entry>';
+        case '7z':
+        case '7zz':
+            return args.length === 6 && exactArgs(args.slice(0, 4), ['e', '-so', '-bd', '--']) && isPathLikeArg(args[4]) && args[5].length > 0
+                ? null
+                : `${command} arguments are restricted to e -so -bd -- <archive> <entry>`;
+        default:
+            return null;
+    }
+}
 const FIND_PATTERN_ARGS = new Set([
     '-name',
     '-iname',

package/dist/security/contentSanitizer.js

@@ -163,9 +163,10 @@ function validateRecursive(params, depth, ancestorStack) {
                 hasValidationErrors = true;
                 r.warnings.forEach(w => warnings.add(`Invalid nested object in parameter ${key}: ${w}`));
             }
-            else {
-                sanitizedParams[key] = r.sanitizedParams;
-            }
+            // Always include sanitized data — tool handlers must not receive undefined
+            // for a key that was present in the input, even when the nested object had
+            // validation issues. The sanitized partial result is still safer than the raw.
+            sanitizedParams[key] = r.sanitizedParams;
         }
         else {
             sanitizedParams[key] = value;

package/dist/security/discoveryFilter.js

@@ -69,6 +69,9 @@ export const DISCOVERY_IGNORED_FOLDER_NAMES = [
     '.mvn',
     '.aws',
     '.gcp',
+    '.ssh',
+    '.kube',
+    '.docker',
     'fastlane',
     'DerivedData',
     'xcuserdata',

package/dist/security/ignoredPathFilter.js

@@ -22,7 +22,10 @@ function getCompiledPathRegex() {
         const all = extra.length > 0
             ? [...IGNORED_PATH_PATTERNS, ...extra]
             : IGNORED_PATH_PATTERNS;
-        _compiledPathRegex = new RegExp(all.map(r => stripNamedGroups(r.source)).join('|'));
+        // Wrap each source in a non-capturing group so alternation precedence is
+        // correct: `a|b` joined with `c|d` must be `(?:a|b)|(?:c|d)`, not
+        // `a|b|c|d` which re-associates differently once combined.
+        _compiledPathRegex = new RegExp(all.map(r => `(?:${stripNamedGroups(r.source)})`).join('|'));
     }
     return _compiledPathRegex;
 }
@@ -33,7 +36,7 @@ function getCompiledFileRegex() {
         const all = extra.length > 0
             ? [...IGNORED_FILE_PATTERNS, ...extra]
             : IGNORED_FILE_PATTERNS;
-        _compiledFileRegex = new RegExp(all.map(r => stripNamedGroups(r.source)).join('|'));
+        _compiledFileRegex = new RegExp(all.map(r => `(?:${stripNamedGroups(r.source)})`).join('|'));
     }
     return _compiledFileRegex;
 }

package/dist/security/pathValidator.js

@@ -12,7 +12,10 @@ export class PathValidator {
         if (opts.workspaceRoot) {
             this.addAllowedRoot(opts.workspaceRoot);
         }
-        if (opts.includeHomeDir !== false) {
+        // Home dir is opt-in. Local tools intentionally include it (users search
+        // ~/projects, ~/Documents, etc.) and rely on ignoredPathFilter as the
+        // second layer to block .ssh, .aws, .kube, etc. within it.
+        if (opts.includeHomeDir === true) {
             const homeDir = os.homedir();
             if (homeDir && !this.allowedRoots.includes(homeDir)) {
                 this.allowedRoots.push(homeDir);
@@ -59,22 +62,11 @@ export class PathValidator {
             // Non-existent roots are still useful for validating future output paths.
         }
     }
-    isResolvedPathAllowed(absolutePath, resolvedPath) {
-        return this.allowedRoots.some(root => {
-            if (resolvedPath === root || resolvedPath.startsWith(root + path.sep)) {
-                return true;
-            }
-            try {
-                const realRoot = fs.realpathSync(root);
-                if (absolutePath === root) {
-                    return resolvedPath === realRoot;
-                }
-                return resolvedPath.startsWith(realRoot + path.sep);
-            }
-            catch {
-                return false;
-            }
-        });
+    isResolvedPathAllowed(_absolutePath, resolvedPath) {
+        // addAllowedRoot already resolves both path.resolve() and realpathSync()
+        // and pushes both into allowedRoots, so a plain string comparison is
+        // sufficient here — no need for another realpathSync per validate() call.
+        return this.allowedRoots.some(root => resolvedPath === root || resolvedPath.startsWith(root + path.sep));
     }
     validate(inputPath) {
         if (!inputPath || inputPath.trim() === '') {
@@ -224,9 +216,15 @@ export class PathValidator {
         this.allowedRoots = [...roots];
     }
 }
-export const pathValidator = new PathValidator();
+// The production singleton explicitly opts in to the home dir because local
+// tools are expected to search ~/projects, ~/Documents, etc. Security within
+// the home directory is provided by ignoredPathFilter (.ssh, .aws, .kube, etc.).
+export const pathValidator = new PathValidator({ includeHomeDir: true });
 export function resetPathValidator(options) {
-    const newValidator = new PathValidator(options);
+    // When called with no arguments (e.g. in afterEach tear-down), restore the
+    // same includeHomeDir state the singleton starts with.
+    const effective = options ?? { includeHomeDir: true };
+    const newValidator = new PathValidator(effective);
     pathValidator.replaceAllowedRoots(newValidator.getAllowedRoots());
     return pathValidator;
 }