@sema-agent/core 2.13.0 → 4.0.0

package/dist/core/hooks.d.ts

@@ -7,7 +7,9 @@ export interface Hooks {
     userPromptSubmit?(prompt: string): UserPromptSubmitResult | undefined | Promise<UserPromptSubmitResult | undefined>;
     stop?(ctx: StopHookContext): StopHookResult | undefined | Promise<StopHookResult | undefined>;
     postToolUseFailure?(toolName: string, input: unknown, failure: HookToolFailure, ctx: HookToolContext): PostToolUseFailureResult | undefined | Promise<PostToolUseFailureResult | undefined>;
-    postToolBatch?(batch: PostToolBatchCall[]): PostToolBatchResult | undefined | Promise<PostToolBatchResult | undefined>;
+    postToolBatch?(batch: PostToolBatchCall[], meta?: {
+        injectedThisTurn: "final_verification" | "finalize";
+    }): PostToolBatchResult | undefined | Promise<PostToolBatchResult | undefined>;
     preCompact?(ctx: PreCompactContext): PreCompactResult | undefined | Promise<PreCompactResult | undefined>;
     postCompact?(ctx: PostCompactContext): void | Promise<void>;
     stopFailure?(ctx: StopFailureContext): void | Promise<void>;
@@ -121,6 +123,7 @@ export interface ToolGateInput {
     approvalTimeoutMs?: number;
     abortSignal?: AbortSignal;
     permissionDenied?: (payload: PermissionDeniedPayload) => void | Promise<void>;
+    onHookError?: (err: unknown) => void;
     shellGated?: boolean;
     autoMode?: {
         decider: import("./auto-mode.js").AutoModeDecider;

package/dist/core/hooks.js

@@ -1,6 +1,7 @@
 import { decisionText } from "./tool-policy.js";
 import { inlineUntrusted } from "./untrusted-text.js";
 import { ASK_USER_QUESTION_TOOL_NAME } from "./ask-question.js";
+import { createSafeNotifier } from "./safe-notify.js";
 export function cloneObserverInput(input) {
     try {
         return structuredClone(input);
@@ -16,6 +17,16 @@ export function cloneObserverInput(input) {
 export function formatHookFeedback(text) {
     return `<system-reminder>\n${text}\n</system-reminder>`;
 }
+function preToolUseCrashReason(subject, err) {
+    const raw = err instanceof Error ? err.message.trim() || err.name : String(err);
+    const cause = inlineUntrusted(raw, 200);
+    return (`a PreToolUse hook crashed while screening ${subject}; the call was NOT executed (fail-closed). ` +
+        `This is a failure of the deployment's hook, NOT of the tool itself — an identical retry reaches the ` +
+        `same hook and fails the same way. Hook error: ${cause || "(no message)"}`);
+}
+function traceHookCrash(input, err, notifier) {
+    notifier.notify(() => input.onHookError?.(err), "toolGate.onHookError");
+}
 function withProbeTimeout(p, ms, signal) {
     if (ms === undefined && signal === undefined)
         return p;
@@ -48,8 +59,20 @@ export async function runToolGate(input) {
     let currentInput = event.input;
     const preToolContext = [];
     let hookAsk;
+    const notifier = createSafeNotifier();
     if (preToolUse) {
-        const r = await preToolUse(toolName, currentInput, { toolCallId, toolName });
+        let r;
+        try {
+            r = await preToolUse(toolName, currentInput, { toolCallId, toolName });
+        }
+        catch (err) {
+            const reason = preToolUseCrashReason(`this call to "${toolName}"`, err);
+            traceHookCrash(input, err, notifier);
+            if (input.permissionDenied) {
+                await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason, source: "hook" }), "toolGate.permissionDenied");
+            }
+            return { block: true, reason: formatHookFeedback(reason), preToolContext };
+        }
         if (r) {
             if (r.additionalContext) {
                 preToolContext.push(r.additionalContext);
@@ -182,7 +205,16 @@ export async function runToolGate(input) {
                         break;
                     }
                     if (preToolUse) {
-                        const hr = await preToolUse(toolName, editArgs, { toolCallId, toolName });
+                        let hr;
+                        try {
+                            hr = await preToolUse(toolName, editArgs, { toolCallId, toolName });
+                        }
+                        catch (err) {
+                            traceHookCrash(input, err, notifier);
+                            editDenied = { action: "deny", reason: preToolUseCrashReason(`the approved edit for "${toolName}"`, err) };
+                            denySource = "hook";
+                            break;
+                        }
                         if (hr) {
                             if (hr.additionalContext)
                                 preToolContext.push(hr.additionalContext);
@@ -250,11 +282,7 @@ export async function runToolGate(input) {
             currentInput = decision.updatedInput;
         }
         if (input.permissionDenied) {
-            try {
-                await input.permissionDenied({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource });
-            }
-            catch {
-            }
+            await notifier.notifyAsync(() => input.permissionDenied?.({ toolName, input: cloneObserverInput(currentInput), toolCallId, reason: denyReason, source: denySource }), "toolGate.permissionDenied");
         }
         return {
             block: true,

package/dist/core/lsp-diagnostics.js

@@ -35,22 +35,28 @@ export class LspDiagnosticsRegistry {
     }
     drain() {
         const out = [];
+        const requeued = new Map();
         let total = 0;
         for (const [uri, all] of this.pending) {
-            if (total >= MAX_TOTAL)
-                break;
             const fresh = all
                 .filter((d) => !this.delivered.has(diagnosticKey(uri, d)))
-                .sort((a, b) => (a.severity ?? 99) - (b.severity ?? 99))
-                .slice(0, Math.min(MAX_PER_FILE, MAX_TOTAL - total));
+                .sort((a, b) => (a.severity ?? 99) - (b.severity ?? 99));
             if (fresh.length === 0)
                 continue;
-            for (const d of fresh)
+            const room = Math.max(0, Math.min(MAX_PER_FILE, MAX_TOTAL - total));
+            const take = fresh.slice(0, room);
+            if (fresh.length > take.length)
+                requeued.set(uri, fresh.slice(take.length));
+            if (take.length === 0)
+                continue;
+            for (const d of take)
                 this.delivered.add(diagnosticKey(uri, d));
-            total += fresh.length;
-            out.push({ uri, diagnostics: fresh });
+            total += take.length;
+            out.push({ uri, diagnostics: take });
         }
         this.pending.clear();
+        for (const [uri, rest] of requeued)
+            this.pending.set(uri, rest);
         return out;
     }
 }

package/dist/core/lsp-protocol.d.ts

@@ -6,4 +6,4 @@ export declare function buildRequest(op: LspOperation, params: LspRequestParams)
     method: string;
     params: unknown;
 } | undefined;
-export declare function parseResult(op: LspOperation, raw: unknown): LspResult;
+export declare function parseResult(op: LspOperation, raw: unknown, fallbackUri?: string): LspResult;

package/dist/core/lsp-protocol.js

@@ -3,6 +3,11 @@ export function pathToUri(p) {
     if (p.startsWith("/")) {
         return `file://${p.split("/").map(encodeURIComponent).join("/")}`;
     }
+    const drive = /^([A-Za-z]):[\\/](.*)$/.exec(p);
+    if (drive)
+        return `file:///${drive[1]}:/${drive[2].split(/[\\/]/).map(encodeURIComponent).join("/")}`;
+    if (p.startsWith("\\\\"))
+        return `file://${p.slice(2).split(/[\\/]/).map(encodeURIComponent).join("/")}`;
     return pathToFileURL(p).href;
 }
 export function uriToPath(uri) {
@@ -47,7 +52,7 @@ export function buildRequest(op, params) {
             return { method: "textDocument/prepareCallHierarchy", params: { ...td, position } };
     }
 }
-export function parseResult(op, raw) {
+export function parseResult(op, raw, fallbackUri) {
     switch (op) {
         case "goToDefinition":
         case "findReferences":
@@ -62,7 +67,7 @@ export function parseResult(op, raw) {
         case "documentSymbol":
         case "workspaceSymbol":
         case "prepareCallHierarchy": {
-            const symbols = toSymbols(raw);
+            const symbols = toSymbols(raw, op === "documentSymbol" ? fallbackUri : undefined);
             return symbols.length ? { kind: "symbols", symbols } : { kind: "none" };
         }
         case "incomingCalls":
@@ -92,21 +97,28 @@ function toLocations(raw) {
     })
         .filter((l) => l !== undefined);
 }
-function toSymbols(raw) {
+function toSymbols(raw, fallbackUri) {
     const out = [];
-    const walk = (x, fallbackUri) => {
+    const walk = (x, inheritedUri) => {
         const loc = x.location;
-        const uri = loc?.uri ?? (typeof x.uri === "string" ? x.uri : fallbackUri);
+        const uri = loc?.uri ?? (typeof x.uri === "string" ? x.uri : inheritedUri);
         const range = (loc?.range ?? x.selectionRange ?? x.range);
         if (typeof x.name === "string" && uri) {
-            const s = range?.start ?? { line: 0, character: 0 };
-            out.push({ name: x.name, ...(symbolKindName(x.kind) ? { kind: symbolKindName(x.kind) } : {}), uri, line: s.line + 1, character: s.character });
+            const s = range?.start;
+            out.push({
+                name: x.name,
+                ...(symbolKindName(x.kind) ? { kind: symbolKindName(x.kind) } : {}),
+                uri,
+                line: (s?.line ?? 0) + 1,
+                character: s?.character ?? 0,
+                ...(s === undefined ? { positionUnknown: true } : {}),
+            });
         }
         for (const child of asArray(x.children))
             walk(child, uri);
     };
     for (const x of asArray(raw))
-        walk(x);
+        walk(x, fallbackUri);
     return out;
 }
 function toCallSymbols(raw) {

package/dist/core/lsp-session.d.ts

@@ -11,17 +11,27 @@ export declare class TransportLspSession implements LspSession {
     private readonly log;
     private readonly warmup;
     private readonly opened;
+    private readonly openedUris;
     private readonly syncing;
     private readonly createdAt;
-    private warmupBarrierDone;
+    private warmupBarrier?;
+    private warmupDone;
+    private warmupAttempts;
     constructor(transport: LspTransport, languageId: string, readText: LspReadText, log?: (event: string, fields: Record<string, unknown>) => void, warmup?: SessionWarmup, diagnostics?: LspDiagnosticsRegistry);
+    get inFlight(): number;
+    private activeRequests;
     request(op: LspOperation, params: LspRequestParams, signal?: AbortSignal): Promise<LspResult>;
+    private requestOnce;
+    private warmupBarrierOnce;
     private syncOpenedFiles;
     private syncOne;
     private static classifyUnbranded;
     get closed(): boolean;
     openedFiles(): string[];
-    warmOpen(filePaths: string[], signal?: AbortSignal): Promise<void>;
+    warmOpen(filePaths: string[], signal?: AbortSignal): Promise<{
+        opened: number;
+        failed: number;
+    }>;
     notifyFileChanged(filePath: string, signal?: AbortSignal): Promise<void>;
     close(): Promise<void>;
 }

package/dist/core/lsp-session.js

@@ -1,5 +1,6 @@
 import { uriToPath, buildRequest, callHierarchyMethod, parseResult, pathToUri } from "./lsp-protocol.js";
-import { lspFailureOf } from "./lsp.js";
+import { lspFailureOf, SharedAbortScope, settleOnAbort } from "./lsp.js";
+const WARMUP_MAX_ATTEMPTS = 3;
 export class TransportLspSession {
     transport;
     languageId;
@@ -7,9 +8,12 @@ export class TransportLspSession {
     log;
     warmup;
     opened = new Map();
+    openedUris = new Map();
     syncing = new Map();
     createdAt = Date.now();
-    warmupBarrierDone = false;
+    warmupBarrier;
+    warmupDone = false;
+    warmupAttempts = 0;
     constructor(transport, languageId, readText, log = () => { }, warmup = { windowMs: 10_000, retryMs: 1_000 }, diagnostics) {
         this.transport = transport;
         this.languageId = languageId;
@@ -24,7 +28,7 @@ export class TransportLspSession {
                 if (!p || typeof p.uri !== "string" || !Array.isArray(p.diagnostics))
                     return;
                 if (typeof p.version === "number") {
-                    const filePath = uriToPath(p.uri);
+                    const filePath = this.openedUris.get(p.uri) ?? uriToPath(p.uri);
                     const known = this.opened.get(filePath);
                     if (known && p.version < known.version) {
                         this.log("lsp_diagnostics_stale_dropped", { uri: p.uri, version: p.version, current: known.version });
@@ -35,18 +39,34 @@ export class TransportLspSession {
             });
         }
     }
+    get inFlight() {
+        return this.activeRequests;
+    }
+    activeRequests = 0;
     async request(op, params, signal) {
+        this.activeRequests += 1;
+        try {
+            return await this.requestOnce(op, params, signal);
+        }
+        finally {
+            this.activeRequests -= 1;
+        }
+    }
+    async requestOnce(op, params, signal) {
         const built = buildRequest(op, params);
         if (!built)
             return { kind: "none", reason: "unsupported_operation" };
-        await this.syncOpenedFiles(params.filePath, signal);
-        if (!this.warmupBarrierDone && this.warmup.windowMs > 0) {
-            this.warmupBarrierDone = true;
-            if (op !== "goToDefinition") {
-                await this.transport
-                    .request("textDocument/definition", { textDocument: { uri: pathToUri(params.filePath) }, position: { line: 0, character: 0 } }, signal)
-                    .catch(() => undefined);
-            }
+        const sync = await this.syncOpenedFiles(params.filePath, signal);
+        if (!sync.ok) {
+            const reason = signal?.aborted ? "cancelled" : (sync.reason ?? "file_sync_failed");
+            this.log("lsp_op_degraded", { op, file: params.filePath, reason, err: sync.error });
+            return { kind: "none", reason, ...(reason === "file_sync_failed" ? { detail: sync.error } : {}) };
+        }
+        if (this.warmup.windowMs > 0 && !this.warmupDone) {
+            if (op === "goToDefinition")
+                this.warmupDone = true;
+            else
+                await this.warmupBarrierOnce(params.filePath, signal);
         }
         for (let attempt = 0;; attempt++) {
             let raw;
@@ -66,7 +86,7 @@ export class TransportLspSession {
             }
             const result = noHierarchyItem
                 ? { kind: "none", reason: "no_call_hierarchy_item" }
-                : parseResult(op, raw);
+                : parseResult(op, raw, pathToUri(params.filePath));
             if (result.kind === "none" && this.warmup.windowMs > 0 && Date.now() - this.createdAt < this.warmup.windowMs && !signal?.aborted) {
                 await new Promise((r) => setTimeout(r, this.warmup.retryMs));
                 continue;
@@ -84,47 +104,90 @@ export class TransportLspSession {
             return result;
         }
     }
+    async warmupBarrierOnce(filePath, signal) {
+        let entry = this.warmupBarrier;
+        if (entry && entry.scope.signal.aborted)
+            entry = undefined;
+        if (!entry) {
+            if (this.warmupAttempts >= WARMUP_MAX_ATTEMPTS)
+                return;
+            this.warmupAttempts += 1;
+            const scope = new SharedAbortScope();
+            const started = {};
+            const job = this.transport
+                .request("textDocument/definition", { textDocument: { uri: pathToUri(filePath) }, position: { line: 0, character: 0 } }, scope.signal)
+                .then(() => {
+                this.warmupDone = true;
+            })
+                .catch(() => {
+                if (this.warmupBarrier === started.self)
+                    this.warmupBarrier = undefined;
+            });
+            entry = { job, scope };
+            started.self = entry;
+            this.warmupBarrier = entry;
+        }
+        entry.scope.join(signal);
+        await settleOnAbort(entry.job, signal, () => undefined);
+    }
     async syncOpenedFiles(queried, signal) {
         const files = new Set(this.opened.keys());
         files.add(queried);
-        await Promise.all([...files].map((fp) => this.syncOne(fp, signal)));
+        const outcomes = await Promise.all([...files].map(async (fp) => [fp, await this.syncOne(fp, signal)]));
+        return outcomes.find(([fp]) => fp === queried)?.[1] ?? { ok: true };
     }
     syncOne(filePath, signal) {
         const inflight = this.syncing.get(filePath);
-        if (inflight)
-            return inflight;
-        const job = (async () => {
-            let text;
-            try {
-                text = await this.readText(filePath, signal);
-            }
-            catch (e) {
-                this.log("lsp_sync_skipped", {
-                    file: filePath,
-                    error: e instanceof Error ? e.message : String(e),
-                    opened: this.opened.has(filePath),
-                });
-                return;
-            }
-            const cur = this.opened.get(filePath);
-            if (!cur) {
-                this.opened.set(filePath, { version: 1, text });
-                this.transport.notify("textDocument/didOpen", {
-                    textDocument: { uri: pathToUri(filePath), languageId: this.languageId, version: 1, text },
-                });
-            }
-            else if (cur.text !== text) {
-                const version = cur.version + 1;
-                this.opened.set(filePath, { version, text });
-                this.transport.notify("textDocument/didChange", {
-                    textDocument: { uri: pathToUri(filePath), version },
-                    contentChanges: [{ text }],
-                });
-                this.log("lsp_file_resync", { file: filePath, version });
-            }
-        })();
-        this.syncing.set(filePath, job);
-        return job.finally(() => this.syncing.delete(filePath));
+        if (inflight && !inflight.scope.signal.aborted) {
+            inflight.scope.join(signal);
+            return settleOnAbort(inflight.job, signal, () => ({ ok: false, error: "aborted by the caller" }));
+        }
+        const scope = new SharedAbortScope();
+        scope.join(signal);
+        const entry = {
+            scope,
+            job: (async () => {
+                let text;
+                try {
+                    text = await this.readText(filePath, scope.signal);
+                }
+                catch (e) {
+                    const error = e instanceof Error ? e.message : String(e);
+                    this.log("lsp_sync_skipped", { file: filePath, error, opened: this.opened.has(filePath) });
+                    return { ok: false, error };
+                }
+                const cur = this.opened.get(filePath);
+                const uri = pathToUri(filePath);
+                if (!cur) {
+                    this.transport.notify("textDocument/didOpen", {
+                        textDocument: { uri, languageId: this.languageId, version: 1, text },
+                    });
+                    if (this.transport.closed === true) {
+                        this.log("lsp_sync_notify_dropped", { file: filePath, kind: "didOpen" });
+                        return { ok: false, error: "didOpen was not delivered (transport closed)", reason: "server_terminated" };
+                    }
+                    this.opened.set(filePath, { version: 1, text });
+                    this.openedUris.set(uri, filePath);
+                }
+                else if (cur.text !== text) {
+                    const version = cur.version + 1;
+                    this.transport.notify("textDocument/didChange", { textDocument: { uri, version }, contentChanges: [{ text }] });
+                    if (this.transport.closed === true) {
+                        this.log("lsp_sync_notify_dropped", { file: filePath, kind: "didChange", version });
+                        return { ok: false, error: "didChange was not delivered (transport closed)", reason: "server_terminated" };
+                    }
+                    this.opened.set(filePath, { version, text });
+                    this.log("lsp_file_resync", { file: filePath, version });
+                }
+                return { ok: true };
+            })(),
+        };
+        this.syncing.set(filePath, entry);
+        const settled = entry.job.finally(() => {
+            if (this.syncing.get(filePath) === entry)
+                this.syncing.delete(filePath);
+        });
+        return settleOnAbort(settled, signal, () => ({ ok: false, error: "aborted by the caller" }));
     }
     static classifyUnbranded(signal, transport) {
         if (signal?.aborted)
@@ -140,10 +203,12 @@ export class TransportLspSession {
         return [...this.opened.keys()];
     }
     async warmOpen(filePaths, signal) {
-        await Promise.all(filePaths.map((fp) => this.syncOne(fp, signal)));
+        const outcomes = await Promise.all(filePaths.map((fp) => this.syncOne(fp, signal)));
+        const failed = outcomes.filter((o) => !o.ok).length;
+        return { opened: outcomes.length - failed, failed };
     }
     notifyFileChanged(filePath, signal) {
-        return this.syncOne(filePath, signal);
+        return this.syncOne(filePath, signal).then(() => undefined);
     }
     close() {
         return this.transport.close();

package/dist/core/lsp.d.ts

@@ -13,8 +13,9 @@ export interface LspSymbolInfo {
     uri: string;
     line: number;
     character: number;
+    positionUnknown?: boolean;
 }
-export type LspNoneReason = "unsupported_operation" | "server_error" | "timeout" | "cancelled" | "server_terminated" | "no_call_hierarchy_item";
+export type LspNoneReason = "unsupported_operation" | "server_error" | "timeout" | "cancelled" | "server_terminated" | "no_call_hierarchy_item" | "file_sync_failed";
 export type LspResult = {
     kind: "locations";
     locations: LspLocation[];
@@ -35,6 +36,16 @@ export declare function lspFailureOf(e: unknown): {
     reason: LspNoneReason;
     detail?: string;
 } | undefined;
+export declare class SharedAbortScope {
+    private readonly controller;
+    private joiners;
+    private abandoned;
+    get signal(): AbortSignal;
+    join(signal?: AbortSignal): void;
+    private abandon;
+}
+export declare function settleOnAbort<T>(job: Promise<T>, signal: AbortSignal | undefined, onAbort: () => T): Promise<T>;
+export declare function resolveLspPath(filePath: string, cwd?: string): string;
 export interface LspRequestParams {
     filePath: string;
     line?: number;
@@ -55,6 +66,7 @@ export type LspReadText = (filePath: string, signal?: AbortSignal) => Promise<st
 export declare const MAX_LSP_FILE_BYTES: number;
 export interface LspServerManager {
     sessionFor(filePath: string, signal?: AbortSignal, env?: ExecutionEnv): Promise<LspSession | undefined>;
+    unavailableReason?(filePath: string, env?: ExecutionEnv): string | undefined;
     readonly diagnostics?: import("./lsp-diagnostics.js").LspDiagnosticsRegistry;
 }
 export interface LspToolOptions {

package/dist/core/lsp.js

@@ -1,4 +1,5 @@
 import { uriToPath } from "./lsp-protocol.js";
+import { foldRedundantPathSegments, isAbsolutePathForm } from "../tools/fs/safety.js";
 import { Type } from "typebox";
 import { defineTool, errorResult } from "./tools.js";
 export const LSP_OPERATIONS = [
@@ -8,6 +9,7 @@ export const LSP_OPERATIONS = [
 export const LSP_FAILURE_BRAND = "lspFailureReason";
 const LSP_NONE_REASONS = new Set([
     "unsupported_operation", "server_error", "timeout", "cancelled", "server_terminated", "no_call_hierarchy_item",
+    "file_sync_failed",
 ]);
 export function brandLspFailure(e, reason, detail) {
     const carrier = e;
@@ -23,6 +25,54 @@ export function lspFailureOf(e) {
     const d = e.lspFailureDetail;
     return { reason: r, ...(typeof d === "string" ? { detail: d } : {}) };
 }
+export class SharedAbortScope {
+    controller = new AbortController();
+    joiners = 0;
+    abandoned = 0;
+    get signal() {
+        return this.controller.signal;
+    }
+    join(signal) {
+        this.joiners += 1;
+        if (!signal)
+            return;
+        if (signal.aborted) {
+            this.abandon();
+            return;
+        }
+        signal.addEventListener("abort", () => this.abandon(), { once: true });
+    }
+    abandon() {
+        this.abandoned += 1;
+        if (this.abandoned >= this.joiners)
+            this.controller.abort();
+    }
+}
+export function settleOnAbort(job, signal, onAbort) {
+    if (!signal)
+        return job;
+    if (signal.aborted) {
+        void job.catch(() => undefined);
+        return Promise.resolve(onAbort());
+    }
+    return new Promise((resolve, reject) => {
+        const onAbortEvent = () => resolve(onAbort());
+        signal.addEventListener("abort", onAbortEvent, { once: true });
+        job.then((v) => {
+            signal.removeEventListener("abort", onAbortEvent);
+            resolve(v);
+        }, (e) => {
+            signal.removeEventListener("abort", onAbortEvent);
+            reject(e);
+        });
+    });
+}
+export function resolveLspPath(filePath, cwd) {
+    const isAbsForm = isAbsolutePathForm(filePath);
+    if (isAbsForm || !cwd)
+        return foldRedundantPathSegments(filePath);
+    return foldRedundantPathSegments(cwd.replace(/[\\/]+$/, "") + (cwd.includes("\\") ? "\\" : "/") + filePath);
+}
 export const MAX_LSP_FILE_BYTES = 10 * 1000 * 1000;
 function fmt(result, ctx) {
     switch (result.kind) {
@@ -37,7 +87,9 @@ function fmt(result, ctx) {
             return result.symbols.length === 0
                 ? "No symbols found."
                 : `Found ${result.symbols.length} symbol(s):\n` +
-                    result.symbols.map((s) => `- ${s.name}${s.kind ? ` (${s.kind})` : ""} — ${s.uri}:${s.line}:${s.character}`).join("\n");
+                    result.symbols
+                        .map((s) => `- ${s.name}${s.kind ? ` (${s.kind})` : ""} — ${s.uri}${s.positionUnknown ? " (no position reported by the language server)" : `:${s.line}:${s.character}`}`)
+                        .join("\n");
         case "none":
             return fmtNone(result, ctx);
     }
@@ -60,9 +112,14 @@ function fmtNone(result, ctx) {
             return `Error performing ${operation}: the request was cancelled before the language server answered. This is NOT an empty result.`;
         case "server_error":
             return `Error performing ${operation}: ${detail ?? "the language server returned an error"}. This is NOT an empty result — fall back to Grep/Read.`;
+        case "file_sync_failed":
+            return `Error performing ${operation}: "${filePath}" could not be read to synchronize it with the language server${detail ? ` (${detail})` : ""}. This is NOT an empty result — the server was never given the file's current text; re-check the path or fall back to Grep/Read.`;
     }
 }
-const LSP_ERROR_REASONS = new Set(["server_error", "timeout", "cancelled", "server_terminated"]);
+const LSP_ERROR_REASONS = new Set([
+    "server_error", "timeout", "cancelled", "server_terminated",
+    "file_sync_failed",
+]);
 async function filterIgnored(result, isIgnored) {
     if (!isIgnored)
         return result;
@@ -129,11 +186,9 @@ export function createLspTool(manager, opts = {}) {
             if (operation === "workspaceSymbol" && wsQuery === undefined) {
                 return errorResult(`Error (LSP): the "workspaceSymbol" operation needs a query.`);
             }
+            const target = resolveLspPath(filePath, opts.env?.cwd);
             if (opts.env) {
-                const isAbsForm = filePath.startsWith("/") || /^[A-Za-z]:[\\/]/.test(filePath);
-                const cwd = opts.env.cwd;
-                const probe = isAbsForm || !cwd ? filePath : cwd.replace(/[\\/]+$/, "") + (cwd.includes("\\") ? "\\" : "/") + filePath;
-                const info = await opts.env.fileInfo(probe, ctx.signal);
+                const info = await opts.env.fileInfo(target, ctx.signal);
                 if (!info.ok && info.error.code === "not_found")
                     return errorResult(`Error (LSP): File does not exist: ${filePath}`);
                 if (!info.ok && info.error.code === "invalid")
@@ -144,12 +199,13 @@ export function createLspTool(manager, opts = {}) {
                     return `File too large for LSP analysis (${Math.ceil(info.value.size / 1e6)}MB exceeds 10MB limit)`;
                 }
             }
-            const session = await manager.sessionFor(filePath, ctx.signal, opts.env);
+            const session = await manager.sessionFor(target, ctx.signal, opts.env);
             if (!session) {
-                return `LSP is unavailable for "${filePath}" (no language server for its language in this environment). Fall back to Grep/Read for this lookup.`;
+                const why = manager.unavailableReason?.(target, opts.env) ?? "no language server for its language in this environment";
+                return `LSP is unavailable for "${filePath}" (${why}). Fall back to Grep/Read for this lookup.`;
             }
             const seamCharacter = character !== undefined ? character - 1 : undefined;
-            const result = await session.request(operation, { filePath, line, character: seamCharacter, symbol: wsQuery }, ctx.signal);
+            const result = await session.request(operation, { filePath: target, line, character: seamCharacter, symbol: wsQuery }, ctx.signal);
             const final = toModelBase(await filterIgnored(result, opts.isPathIgnored));
             const text = fmt(final, { operation, filePath });
             return final.kind === "none" && final.reason !== undefined && LSP_ERROR_REASONS.has(final.reason) ? errorResult(text) : text;

package/dist/core/mailbox-store.d.ts

@@ -8,12 +8,13 @@ export interface MailboxLease {
     messages: MailboxMessage[];
     maxSeq: number;
 }
+export interface MailboxAppendMessage {
+    from?: string;
+    content: string;
+    sentAt: number;
+}
 export interface MailboxStore {
-    append(scope: string, handle: string, msg: {
-        from?: string;
-        content: string;
-        sentAt: number;
-    }): Promise<number>;
+    append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;
@@ -28,11 +29,7 @@ export declare class InMemoryMailboxStore implements MailboxStore {
     private boxes;
     private key;
     private box;
-    append(scope: string, handle: string, msg: {
-        from?: string;
-        content: string;
-        sentAt: number;
-    }): Promise<number>;
+    append(scope: string, handle: string, msg: MailboxAppendMessage): Promise<number>;
     claimLease(scope: string, handle: string, owner: string, ttlMs: number, now?: number): Promise<MailboxLease | null>;
     ack(scope: string, handle: string, owner: string, upToSeq: number): Promise<void>;
     releaseLease(scope: string, handle: string, owner: string): Promise<void>;