@sema-agent/server 4.2.0 → 5.0.0

package/dist/lsp/e2b-manager.js

@@ -6,41 +6,99 @@
  * `openE2bLspTransport` does the per-sandbox start: write bridge.cjs from BRIDGE_SOURCE (single source of truth —
  * works on baked + un-baked templates) → foreground install (baked template skips instantly) → start the bridge
  * as a TRUE background command (a shell `&` child gets reaped when E2B completes the foreground command) → WS
- * connect via `wss://getHost(port)?token=…` (per-session auth — the URL is public).
+ * connect via `wss://getHost(port)?token=…` (per-session auth — the URL is public). It is a single-shot legacy
+ * primitive (still used standalone by the k8s wiring test) — NOT part of the bridge resource model below; it
+ * carries no generation/dead tracking of its own.
+ *
+ * redesign⑤ (#96 §DESIGN-V2 A/F3/F6): `createE2bLspManager`'s `transportFactory` owns the actual bridge
+ * RESOURCE model — one `E2bBridgeHandle` per env+port, surviving across heals, with a bounded restart budget
+ * (`MAX_BRIDGE_GENERATIONS`) so a bridge that crashes (or a first boot that never completes) degrades that
+ * language gracefully instead of burning sandbox round-trips forever.
  */
 import { randomUUID } from "node:crypto";
 import { connectWsLspTransport } from "./ws-transport.js";
 import { E2bLspManager } from "./manager.js";
-import { BRIDGE_DIR, BRIDGE_SOURCE, lspInstallCommand, lspStartCommand, portForLanguage, SERVER_CMD } from "./e2b-bridge.js";
+import { BRIDGE_DIR, BRIDGE_SOURCE, TSSERVER_JS_PATH, LSP_SETUP_LOG, bridgeLogFile, lspInstallCommand, lspStartCommand, portForLanguage, SERVER_CMD, terminateBridgeCommand, } from "./e2b-bridge.js";
+function describeErr(e) {
+    return e instanceof Error ? e.message : String(e);
+}
+/** Best-effort `tail -n <lines> <path>`, capped — used for both the install-failure snippet (§DESIGN-V2 F7,
+ *  `LSP_SETUP_LOG` — previously had zero readers) and the connect-exhaustion postmortem (§DESIGN-V2 C5/F9,
+ *  `bridge.log`). Returns `undefined` ONLY when the exec itself failed (never observed the log) — an empty
+ *  log is still a meaningful (if boring) tail, distinct from "couldn't look." Caps to the LAST `capBytes` —
+ *  a giant `Content-Length` framing dump truncated from the FRONT still keeps the most recent (relevant) lines. */
+async function tailLog(env, path, lines = 40, capBytes = 4096) {
+    const r = await env.exec(`tail -n ${lines} ${path} 2>/dev/null`).catch(() => undefined);
+    if (!r?.ok)
+        return undefined;
+    const out = r.value?.stdout ?? "";
+    return out.length > capBytes ? out.slice(-capBytes) : out;
+}
+/** §DESIGN-V2 F11: the probe's URL scheme is the WS scheme's HTTP-family counterpart (`wss`'s TLS proxy →
+ *  `https`; the k8s pod network's plain `ws` → plain `http` — same "TLS or not" the WS connect itself uses). */
+function httpSchemeFor(scheme) {
+    return scheme === "wss" ? "https" : "http";
+}
+/** Real `GET /healthz?token=…` probe (§DESIGN-V2 F2/C6) — 1s bound, `fetch` (no new dependency). Any failure
+ *  (no host, network error, non-2xx, timeout) reads as "not confirmed alive"; the caller's decision (skip the
+ *  blind retry loop and go straight to the restart arm) only fires once `everConnected` is true (F6) — a cold
+ *  first boot never reaches this probe. */
+async function defaultProbeHealthz(env, port, token, scheme) {
+    const host = await env.getHost(port);
+    if (!host)
+        return false;
+    try {
+        const res = await fetch(`${httpSchemeFor(scheme)}://${host}/healthz?token=${token}`, { signal: AbortSignal.timeout(1000) });
+        return res.ok;
+    }
+    catch {
+        return false;
+    }
+}
 /** Write bridge.cjs + (foreground) install the language server, then start the bridge as a TRUE background
- *  command. Returns whether the bridge is now up-or-starting (`false` only when the foreground install failed).
- *  A single-shot primitive: it does NOT check whether a bridge is already listening on `port` — a caller that
- *  can have two languages share one port (`createE2bLspManager`, since `portForLanguage` maps typescript AND
- *  javascript onto 8123 off the same `SERVER_CMD`) MUST call this at most ONCE per env+port itself. A second
- *  `node bridge.cjs` on an already-bound port surfaces as an EADDRINUSE `wss` 'error' (e2b-bridge.ts D6
- *  hardening keeps that from crashing the sandbox, but the second attempt still fails and wastes a sandbox
- *  round-trip for nothing — HRD-LSP-4). */
+ *  command. A single-shot primitive: it does NOT check whether a bridge is already listening on `port` — a
+ *  caller that can have two languages share one port (`createE2bLspManager`, since `portForLanguage` maps
+ *  typescript AND javascript onto 8123 off the same `SERVER_CMD`) MUST call this at most ONCE per env+port
+ *  itself. A second `node bridge.cjs` on an already-bound port surfaces as an EADDRINUSE `wss` 'error'
+ *  (e2b-bridge.ts D6 hardening keeps that from crashing the sandbox, but the second attempt still fails and
+ *  wastes a sandbox round-trip for nothing — HRD-LSP-4). None of the three steps' failures are swallowed
+ *  (§DESIGN-V2 F6) — a silently-lost write means `node bridge.cjs` fails at runtime with no signal until
+ *  every connect attempt exhausts; reporting it here is strictly faster AND gives a precise reason. */
 async function startE2bBridge(language, env, port, token) {
-    await env.writeFile(`${BRIDGE_DIR}/bridge.cjs`, BRIDGE_SOURCE).catch(() => undefined);
+    const wrote = await env.writeFile(`${BRIDGE_DIR}/bridge.cjs`, BRIDGE_SOURCE).catch((e) => ({ ok: false, error: e }));
+    if (!wrote.ok) {
+        const detail = "error" in wrote && wrote.error !== undefined ? `bridge.cjs write failed: ${describeErr(wrote.error)}` : "bridge.cjs write failed";
+        return { ok: false, reason: "bridge-start-failed", detail };
+    }
     const installed = await env.exec(lspInstallCommand(language)).catch(() => undefined);
-    if (!installed || !installed.ok)
-        return false;
-    await env.startBackground(lspStartCommand(language, port, token)).catch(() => undefined);
-    return true;
+    if (!installed || !installed.ok || installed.value?.exitCode !== 0) {
+        const snippet = await tailLog(env, LSP_SETUP_LOG);
+        return { ok: false, reason: "install-failed", detail: snippet ? `install failed: ${snippet}` : "install failed (no setup log)" };
+    }
+    try {
+        await env.startBackground(lspStartCommand(language, port, token));
+    }
+    catch (e) {
+        return { ok: false, reason: "bridge-start-failed", detail: `background start failed: ${describeErr(e)}` };
+    }
+    return { ok: true };
 }
 /** Connect (with retry) to an already-started bridge. Each call opens its OWN WS connection — the bridge spawns
  *  a FRESH child language-server process per connection (e2b-bridge.ts `wss.on('connection', …)`), so two
  *  languages sharing one bridge port each still get an isolated language-server instance. */
-async function connectE2bLspBridge(env, port, token, opts) {
+async function connectE2bLspBridge(env, port, token, opts, language) {
     const connect = opts?.connect ?? connectWsLspTransport;
     const retry = opts?.retry ?? { attempts: 6, delayMs: 1500 };
     const root = env.workspaceHandle().mountPath;
+    // #96 真机门:tls(v4 无 CLI 旗)只能经 initializationOptions 拿 tsserver 路径;install 腿已把
+    // typescript 落到 TSSERVER_JS_PATH 定值路径。非 tls 语言不发键(LSP 规范下多余键也会被忽略,但缺席=零风险)。
+    const initOptions = language === "typescript" || language === "javascript" ? { tsserver: { path: TSSERVER_JS_PATH } } : undefined;
     // the bridge starts as a background command → retry the WS connect (with the auth token) while it comes up
     const scheme = opts?.scheme ?? "wss";
     for (let attempt = 0; attempt < retry.attempts; attempt++) {
         const host = await env.getHost(port);
         if (host) {
-            const transport = await connect(`${scheme}://${host}/?token=${token}`, root);
+            const transport = await connect(`${scheme}://${host}/?token=${token}`, root, undefined, initOptions);
             if (transport)
                 return transport;
         }
@@ -57,10 +115,13 @@ export async function openE2bLspTransport(language, env, opts) {
     const port = portForLanguage(language);
     const token = opts?.token ?? randomUUID(); // per-session bridge auth — the getHost URL is public (council #4)
     const started = await startE2bBridge(language, env, port, token);
-    if (!started)
+    if (!started.ok)
         return undefined;
-    return connectE2bLspBridge(env, port, token, opts);
+    return connectE2bLspBridge(env, port, token, opts, language);
 }
+/** A crash-loop must degrade the language, not retry the sandbox forever. 3 covers "an occasional OOM kill";
+ *  a bridge that dies again immediately after 3 fresh starts is a standing failure, not a blip. */
+export const MAX_BRIDGE_GENERATIONS = 3;
 /** The single shared `LspServerManager` for the deployment (`RunnerDeps.lspManager`). */
 export function createE2bLspManager(opts) {
     // One bridge PROCESS + token per env+PORT — not per env+language. `portForLanguage` maps typescript and
@@ -68,29 +129,137 @@ export function createE2bLspManager(opts) {
     // one listening bridge (HRD-LSP-4) and re-invoked `startBackground` on an already-bound port on every open.
     // WeakMap → a destroyed task's bridge bookkeeping is collectible with its env.
     const bridges = new WeakMap();
+    const scheme = opts?.scheme ?? "wss";
+    const provider = opts?.provider ?? (scheme === "ws" ? "k8s" : "e2b");
+    const log = opts?.log ?? (() => { });
+    const metrics = opts?.metrics;
+    const probe = opts?.probe ?? defaultProbeHealthz;
+    /** The model-facing word for this handle's CURRENT death — `deathReason` unless the restart budget is
+     *  exhausted, in which case "further restarts won't help" supersedes whatever specifically killed the last
+     *  generation. */
+    function reasonFor(handle) {
+        if (handle.generation >= MAX_BRIDGE_GENERATIONS)
+            return "bridge-restart-budget-exhausted";
+        return handle.deathReason ?? "bridge-connect-exhausted";
+    }
+    /** The ONE place a handle transitions into `dead` — fires the `lsp_bridge_dead_total{reason}` metric +
+     *  `lsp_bridge_dead` event exactly once per transition (§DESIGN-V2 E), using the ALREADY-budget-aware
+     *  reported reason (not the raw `deathReason`) so the metric bucket for a generation that just hit the cap
+     *  reads as "budget exhausted," not as whatever technical failure happened to be the final straw.
+     *  review finding ③ (independent re-review): idempotent — two concurrent callers CAN both conclude the
+     *  SAME still-"ready" handle is dead (e.g. two languages sharing a port each running their own §DESIGN-V2
+     *  F2 healthz probe before either has written `state="dead"`); without this guard the metric/event fired
+     *  once per CALLER instead of once per TRANSITION. A handle already `dead` keeps its ORIGINAL
+     *  deathReason/lastError (the first caller to observe the death is definitionally the one whose diagnostic
+     *  is accurate — a second, redundant observation shouldn't overwrite it). */
+    function markDead(handle, reason, detail) {
+        if (handle.state === "dead")
+            return reasonFor(handle);
+        handle.state = "dead";
+        handle.deathReason = reason;
+        handle.lastError = detail;
+        const reported = reasonFor(handle);
+        metrics?.inc("lsp_bridge_dead_total", { reason: reported });
+        log("lsp_bridge_dead", { port: handle.port, generation: handle.generation, reason: reported, detail });
+        return reported;
+    }
+    /** §DESIGN-V2 C5/F9: best-effort postmortem — tail the bridge's OWN log after a connect exhausts (or the
+     *  probe declares it dead) and before giving up on this generation. Silent on failure (getting the tail is
+     *  itself best-effort; it must never become a SECOND failure mode). */
+    async function postmortem(env, port) {
+        const tail = await tailLog(env, bridgeLogFile());
+        if (tail !== undefined)
+            log("lsp_bridge_postmortem", { port, tail });
+    }
     return new E2bLspManager({
         log: opts?.log,
+        metrics,
+        hasServerCommand: (language) => Boolean(SERVER_CMD[language]),
         transportFactory: async (language, env) => {
             if (!SERVER_CMD[language])
-                return undefined; // no server for this language → graceful degrade (mirrors
-            // openE2bLspTransport's own guard; MUST run before touching `bridges` — `portForLanguage` falls back to
-            // port 8123 for an unmapped language, which would otherwise silently borrow typescript's live bridge)
+                return { ok: false, reason: "no-server-command" }; // mirrors openE2bLspTransport's
+            // own guard; MUST run before touching `bridges` — `portForLanguage` falls back to port 8123 for an
+            // unmapped language, which would otherwise silently borrow typescript's live bridge.
             const port = portForLanguage(language);
             let perPort = bridges.get(env);
             if (!perPort) {
                 perPort = new Map();
                 bridges.set(env, perPort);
             }
-            let bridge = perPort.get(port);
-            if (!bridge) {
+            let handle = perPort.get(port);
+            if (!handle || handle.state === "dead") {
+                if (handle && handle.generation >= MAX_BRIDGE_GENERATIONS)
+                    return { ok: false, reason: reasonFor(handle) };
+                // review finding ① (independent re-review): the termination-verification (§DESIGN-V2 F3) used to sit
+                // in an `await` HERE, between reading `perPort` above and writing it below — that broke the
+                // run-to-completion dedupe guarantee two languages sharing a port rely on (portForLanguage maps
+                // typescript/javascript onto the SAME port/SERVER_CMD): both could see the same dead handle, both
+                // race past the await, and both mint a COMPETING replacement generation (each calling
+                // startBackground) instead of joining one shared restart. The mint itself — capturing `generation`+
+                // `token` and registering `newHandle` into `perPort` — MUST stay synchronous relative to the
+                // `perPort.get(port)` read above (true again now: "no await above" below). The termination check
+                // moves INSIDE the `ready` chain instead: mint synchronously, verify asynchronously. A SECOND
+                // language arriving while this is in flight now sees `state==="starting"` (not "dead"), skips this
+                // whole branch, and joins the SAME `ready` — exactly the pre-existing dedupe every other caller of
+                // `bridges`/`perPort` already relies on.
+                const priorHandle = handle; // the dying generation (if any) — captured for the async verification below
+                const generation = handle ? handle.generation + 1 : 1;
                 const token = opts?.token ?? randomUUID();
-                bridge = { token, ready: startE2bBridge(language, env, port, token) };
-                perPort.set(port, bridge); // synchronous — no await above (run-to-completion dedupe guard, see E2bBridgeHandle.ready doc)
+                const newHandle = {
+                    port,
+                    token,
+                    serverCmd: SERVER_CMD[language],
+                    generation,
+                    state: "starting",
+                    everConnected: false,
+                    ready: Promise.resolve(false), // placeholder — overwritten synchronously below, before any await
+                };
+                newHandle.ready = (async () => {
+                    if (priorHandle) {
+                        // §DESIGN-V2 F3: verify the OLD generation actually stopped before this one starts — an
+                        // unconfirmed kill risks EADDRINUSE permanently rejecting THIS generation's fresh token (the old
+                        // process is still the one listening). This generation is already minted+registered by the time
+                        // this runs (the dedupe above), so an unconfirmed termination marks IT dead directly rather than
+                        // leaving the prior (already-replaced) handle in the map.
+                        const released = await env.exec(terminateBridgeCommand(port)).catch(() => undefined);
+                        if (!released?.ok || released.value?.exitCode !== 0) {
+                            markDead(newHandle, "bridge-start-failed", "previous generation could not be confirmed stopped — held back from starting to avoid a doomed EADDRINUSE race");
+                            log("lsp_bridge_restart_blocked", { port, generation });
+                            return false;
+                        }
+                    }
+                    const started = await startE2bBridge(language, env, port, token);
+                    if (!started.ok) {
+                        markDead(newHandle, started.reason ?? "bridge-start-failed", started.detail ?? "bridge start failed");
+                        return false;
+                    }
+                    metrics?.inc("lsp_bridge_start_total", { provider, generation: String(generation) });
+                    log("lsp_bridge_start", { port, generation });
+                    return true;
+                })();
+                perPort.set(port, newHandle); // synchronous — no await above (run-to-completion dedupe guard RESTORED)
+                handle = newHandle;
             }
-            const started = await bridge.ready;
+            const started = await handle.ready;
             if (!started)
-                return undefined;
-            return connectE2bLspBridge(env, port, bridge.token, opts);
+                return { ok: false, reason: reasonFor(handle) };
+            if (handle.everConnected) {
+                const alive = await probe(env, handle.port, handle.token, scheme);
+                if (!alive) {
+                    const reason = markDead(handle, "bridge-connect-exhausted", "healthz probe reported the bridge unreachable");
+                    await postmortem(env, port);
+                    return { ok: false, reason };
+                }
+            }
+            const transport = await connectE2bLspBridge(env, handle.port, handle.token, opts, language);
+            if (!transport) {
+                const reason = markDead(handle, "bridge-connect-exhausted", "bridge connect exhausted after all retries");
+                await postmortem(env, port);
+                return { ok: false, reason };
+            }
+            handle.everConnected = true;
+            handle.state = "ready";
+            return { ok: true, transport };
         },
     });
 }

package/dist/lsp/manager.d.ts

@@ -1,13 +1,17 @@
 import { LspDiagnosticsRegistry } from "@sema-agent/core";
 import type { ExecutionEnv } from "@sema-agent/core";
 import type { LspServerManager, LspSession, LspTransport } from "./types.js";
-/** The E2B surface the LSP needs beyond base ExecutionEnv (present on RemoteContainerExecutionEnv). */
+/** The E2B surface the LSP needs beyond base ExecutionEnv (present on RemoteContainerExecutionEnv).
+ *  `exec`'s `stdout` is optional/structural (§DESIGN-V2 F7) — additive to the existing `stderr`-only shape so
+ *  the postmortem/install-failure tail reads (`tail -n … <log>`, whose output arrives on stdout) can use the
+ *  SAME duck-typed surface without widening what a plain command result MUST carry. */
 export interface LspCapableEnv {
     exec(command: string): Promise<{
         ok: boolean;
         value?: {
             exitCode: number;
             stderr: string;
+            stdout?: string;
         };
     }>;
     startBackground(command: string): Promise<void>;
@@ -23,22 +27,56 @@ export interface LspCapableEnv {
         mountPath: string;
     };
 }
+/**
+ * §DESIGN-V2 B/F5/F7: the fixed, model-facing failure vocabulary for `unavailableReason`. Three are STATIC
+ * (re-derivable synchronously from `filePath`+`env` alone, without ever having attempted an open —
+ * `env-not-lsp-capable` / `language-not-mapped` / `no-server-command`); the other five are DYNAMIC (only
+ * knowable after an actual open attempt, so they're recorded in `lastFailure` per env+language and read back).
+ * Short + stable by design — a model reads these directly (core lsp.js renders `why` straight into the tool's
+ * degrade text), so adding/renaming a word is a behavior-facing change, not a refactor.
+ */
+export type LspUnavailableReason = "env-not-lsp-capable" | "language-not-mapped" | "no-server-command" | "install-failed" | "bridge-start-failed" | "bridge-connect-exhausted" | "bridge-restart-budget-exhausted" | "session-open-failed";
+/** §DESIGN-V2 F5: the transport factory's discriminated result — replaces the old plain `LspTransport|undefined`
+ *  so the bridge-resource owner (e2b-manager's `transportFactory`) can report WHY an attempt failed directly
+ *  through its return value, instead of a side channel that could drift from what actually happened. */
+export type LspFactoryResult = {
+    ok: true;
+    transport: LspTransport;
+} | {
+    ok: false;
+    reason: LspUnavailableReason;
+};
 /** Duck-type check: is this ExecutionEnv an E2B adapter with the LSP surface? */
 export declare function isLspCapable(env: ExecutionEnv): env is ExecutionEnv & LspCapableEnv;
 export interface E2bLspManagerOptions {
     /** Opens (+ `initialize`s) a WS transport to the language server inside THIS env's sandbox. */
-    transportFactory: (language: string, env: LspCapableEnv) => Promise<LspTransport | undefined>;
+    transportFactory: (language: string, env: LspCapableEnv) => Promise<LspFactoryResult>;
     /** Override the file-extension → languageId map. */
     extToLang?: Readonly<Record<string, string>>;
     /** Observability hook (open/heal/degrade events) — prod wires the service logger; silent when unset. */
     log?: (event: string, fields: Record<string, unknown>) => void;
+    /** §DESIGN-V2 F5: synchronous re-derivation of the "no-server-command" static reason — owned by the factory
+     *  (e2b-manager's `SERVER_CMD` table), which this generic manager doesn't import. `undefined` (option unset)
+     *  or a `true` return ⇒ a server command IS configured, so a miss (if any) is dynamic (read from
+     *  `lastFailure`) rather than this static one. */
+    hasServerCommand?: (language: string) => boolean;
+    /** §DESIGN-V2 E: `lsp_session_open_total{language,outcome}` / `lsp_session_heal_total{outcome}` — fired at
+     *  the SAME point as the matching `log()` call (event and metric share one source, never drift apart). */
+    metrics?: {
+        inc(name: string, labels?: Record<string, string>): void;
+    };
 }
 export declare class E2bLspManager implements LspServerManager {
-    /** Per-sandbox session cache: env (weak) → language → in-flight/ready session. */
+    /** Per-sandbox session cache: env (weak) → language → the (self-contained, see `startJob`) shared job. */
     private readonly perEnv;
+    /** §DESIGN-V2 B/F10: env (weak) → language → the reason the MOST RECENT open/heal attempt failed. Cleared
+     *  on a successful open (F10) so a stale reason never outlives the failure that produced it. */
+    private readonly lastFailure;
     private readonly factory;
     private readonly extToLang;
     private readonly log;
+    private readonly hasServerCommand;
+    private readonly metrics;
     /** design/121 (core 1.220, board [S] ①): the workspace diagnostics registry — WORKSPACE-scoped (survives
      *  heal/evict; diagnostics belong to files, not servers), drained by the Runner at turn boundaries. Every
      *  session feeds it from `textDocument/publishDiagnostics` (the WS transport now dispatches notifications).
@@ -47,7 +85,36 @@ export declare class E2bLspManager implements LspServerManager {
      *  fileEdited keying is per-uri, and sandbox workspace paths are per-task-unique). */
     readonly diagnostics: LspDiagnosticsRegistry;
     constructor(opts: E2bLspManagerOptions);
-    sessionFor(filePath: string, _signal?: AbortSignal, env?: ExecutionEnv): Promise<LspSession | undefined>;
+    /**
+     * §DESIGN-V2 B: the core 1.86.2+ seam's optional method — WHY the most recent `sessionFor` miss for this
+     * file happened. Three reasons are STATIC (re-derived here fresh, every call, from `filePath`+`env` alone —
+     * never stored, since they don't need an open attempt to be knowable); the rest are DYNAMIC, read back from
+     * `lastFailure`. `undefined` = this exact (env, language) was never attempted (NOT "available" — a
+     * best-effort postmortem surface, per the seam's own contract).
+     */
+    unavailableReason(filePath: string, env?: ExecutionEnv): LspUnavailableReason | undefined;
+    sessionFor(filePath: string, signal?: AbortSignal, env?: ExecutionEnv): Promise<LspSession | undefined>;
+    /**
+     * §DESIGN-V2 F1 (aligned with core's `NodeLspManager.open`, node-lsp-manager.js :123-153 — same self-
+     * contained-job shape, not the same code: that manager also tracks a TTL/LRU cache and per-job
+     * `SharedAbortScope`, which this one has no equivalent of per F9). The returned job is SELF-completing:
+     *
+     *  - self-caches: registers itself into `sessions` synchronously BEFORE returning (so a concurrent caller
+     *    in the SAME microtask sees it — no dedupe race);
+     *  - self-cleans: on failure, removes ITSELF from `sessions` (never a newer entry a racer already installed
+     *    — the `sessions.get(language) === job` check) so the next request retries instead of caching a miss;
+     *  - self-warms: a heal job (`heal` set) `warmOpen`s the carried files as part of settling, before anyone
+     *    can observe it as "done" — no caller-side extra step, no window where a racer sees a warm-less session;
+     *  - self-closes an orphan: if a CONCURRENT heal already replaced this job in `sessions` before it settled
+     *    (this job "lost" the race), the just-opened transport is closed instead of leaked with no owner.
+     *
+     *  Callers must NEVER wrap `settleOnAbort` around a naive `await` of a SHARED promise and then branch the
+     *  logging/cache-eviction on THAT wrapped value — a caller whose OWN signal aborted would then look
+     *  indistinguishable from the job itself failing, misfiring `lsp_session_*_failed` and evicting a still-live
+     *  in-flight entry out from under a concurrent caller (§DESIGN-V2 F1). `sessionFor` only ever wraps the
+     *  RETURN boundary; every cache/log decision above happens INSIDE the job, driven by the job's own outcome.
+     */
+    private startJob;
     private open;
 }
 //# sourceMappingURL=manager.d.ts.map

package/dist/lsp/manager.js

@@ -6,7 +6,9 @@
  * in a WeakMap, so a destroyed task's entries become collectible (its bridge dies with the sandbox).
  *
  * Any miss (no env / unknown language / env without the E2B surface / failed open) → `undefined`, which makes
- * core's tool degrade gracefully to grep/read_file.
+ * core's tool degrade gracefully to grep/read_file. redesign⑤ (#96 §DESIGN-V2 B/F5/F10): the miss now also comes
+ * with a reason (`unavailableReason`, the core 1.86.2+ seam's optional method) — a fixed, model-facing word list
+ * (§DESIGN-V2 F7: "reason 词表=模型可见面", short + stable — changing a word IS a behavior change).
  */
 import path from "node:path";
 import { TransportLspSession, LspDiagnosticsRegistry } from "@sema-agent/core";
@@ -33,12 +35,44 @@ const DEFAULT_EXT_TO_LANG = {
     ".swift": "swift",
     ".rs": "rust",
 };
+/**
+ * §DESIGN-V2 F1/F8/F9: literal-aligned with core's (un-exported, `dist/core/lsp.js`) `settleOnAbort` — same
+ * signature as the PUBLIC `core/lsp.d.ts:47` declaration, so a future dedup (once core exports it) is a
+ * find-and-delete, not a rewrite. Bounds how long *this one caller* waits for a shared job; it must NEVER be
+ * threaded into the job itself (F9: the shared open/heal chain accepts no per-caller signal — see `open`'s
+ * doc). `job` is assumed never to reject (every failure path here resolves to `undefined`); the `.catch` on
+ * the already-aborted branch is defensive parity with core's version, not a behavior this file relies on.
+ */
+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 class E2bLspManager {
-    /** Per-sandbox session cache: env (weak) → language → in-flight/ready session. */
+    /** Per-sandbox session cache: env (weak) → language → the (self-contained, see `startJob`) shared job. */
     perEnv = new WeakMap();
+    /** §DESIGN-V2 B/F10: env (weak) → language → the reason the MOST RECENT open/heal attempt failed. Cleared
+     *  on a successful open (F10) so a stale reason never outlives the failure that produced it. */
+    lastFailure = new WeakMap();
     factory;
     extToLang;
     log;
+    hasServerCommand;
+    metrics;
     /** design/121 (core 1.220, board [S] ①): the workspace diagnostics registry — WORKSPACE-scoped (survives
      *  heal/evict; diagnostics belong to files, not servers), drained by the Runner at turn boundaries. Every
      *  session feeds it from `textDocument/publishDiagnostics` (the WS transport now dispatches notifications).
@@ -50,8 +84,27 @@ export class E2bLspManager {
         this.factory = opts.transportFactory;
         this.extToLang = opts.extToLang ?? DEFAULT_EXT_TO_LANG;
         this.log = opts.log ?? (() => { });
+        this.hasServerCommand = opts.hasServerCommand ?? (() => true);
+        this.metrics = opts.metrics;
+    }
+    /**
+     * §DESIGN-V2 B: the core 1.86.2+ seam's optional method — WHY the most recent `sessionFor` miss for this
+     * file happened. Three reasons are STATIC (re-derived here fresh, every call, from `filePath`+`env` alone —
+     * never stored, since they don't need an open attempt to be knowable); the rest are DYNAMIC, read back from
+     * `lastFailure`. `undefined` = this exact (env, language) was never attempted (NOT "available" — a
+     * best-effort postmortem surface, per the seam's own contract).
+     */
+    unavailableReason(filePath, env) {
+        if (!env || !isLspCapable(env))
+            return "env-not-lsp-capable";
+        const language = this.extToLang[path.extname(filePath).toLowerCase()];
+        if (!language)
+            return "language-not-mapped";
+        if (!this.hasServerCommand(language))
+            return "no-server-command";
+        return this.lastFailure.get(env)?.get(language);
     }
-    async sessionFor(filePath, _signal, env) {
+    async sessionFor(filePath, signal, env) {
         if (!env || !isLspCapable(env))
             return undefined; // no env passed (core <1.86.2) or not the E2B adapter → degrade
         const language = this.extToLang[path.extname(filePath).toLowerCase()];
@@ -62,43 +115,110 @@ export class E2bLspManager {
             sessions = new Map();
             this.perEnv.set(env, sessions);
         }
-        let pending = sessions.get(language);
-        const fresh = !pending; // capture BEFORE assigning, or the open/open_failed log is dead code (review 2026-06-10)
-        if (!pending) {
-            pending = this.open(language, env);
-            sessions.set(language, pending);
-        }
-        let session = await pending;
-        if (fresh)
-            this.log(session ? "lsp_session_open" : "lsp_session_open_failed", { language });
+        let pending = sessions.get(language) ?? this.startJob(env, sessions, language);
+        // §DESIGN-V2 F9: the shared job never sees a per-caller `signal` — it is a CONTRACT, not an accident, that
+        // the chain below has nothing to wire one into. `settleOnAbort` only bounds how long THIS caller waits for
+        // the (unaffected, still-running-for-everyone-else) shared job — Q16. Wiring a per-caller signal into the
+        // shared chain would let one caller's cancellation abort a session other callers are still waiting on.
+        let session = await settleOnAbort(pending, signal, () => undefined);
         if (session?.closed) {
             // Transport died between tool calls (the E2B proxy idle-kills silent WS connections — live-drill
             // finding 2026-06-10). Heal: evict + reopen ONCE — the bridge spawns a fresh server per connection.
             // Carry the dead session's opened files over: a fresh server with no project config only "sees" its
             // open files, so without the replay cross-file ops silently degrade to single-file (live-repro).
-            // Guard against clobbering a concurrent heal: a racer that lost sees sessions.get !== its pending and
-            // adopts the winner's reopen. ⚠️ Relies on JS run-to-completion — there is NO await between the
-            // delete and the set below (this.open() is CALLED but not awaited); do not insert one.
+            // Guard against clobbering a concurrent heal: a racer that lost this race adopts whichever job IS
+            // current in `sessions` (the winner's). `startJob` itself does the `sessions.set` synchronously (no
+            // `await` between creating the job and registering it) — the run-to-completion dedupe guard `startJob`
+            // documents.
             const carry = session.openedFiles();
-            if (sessions.get(language) === pending)
-                sessions.delete(language);
-            pending = sessions.get(language) ?? this.open(language, env);
-            sessions.set(language, pending);
-            session = await pending;
-            if (session)
-                await session.warmOpen(carry);
-            this.log(session ? "lsp_session_heal" : "lsp_session_heal_failed", { language, carried: carry.length });
+            pending = sessions.get(language) === pending ? this.startJob(env, sessions, language, { carry }) : sessions.get(language);
+            session = await settleOnAbort(pending, signal, () => undefined);
         }
-        // failed open → don't cache the miss (retry next request); guarded so a slow loser awaiting an old failed
-        // pending can't evict a NEWER in-flight session a concurrent call already cached.
-        if (!session && sessions.get(language) === pending)
-            sessions.delete(language);
         return session;
     }
+    /**
+     * §DESIGN-V2 F1 (aligned with core's `NodeLspManager.open`, node-lsp-manager.js :123-153 — same self-
+     * contained-job shape, not the same code: that manager also tracks a TTL/LRU cache and per-job
+     * `SharedAbortScope`, which this one has no equivalent of per F9). The returned job is SELF-completing:
+     *
+     *  - self-caches: registers itself into `sessions` synchronously BEFORE returning (so a concurrent caller
+     *    in the SAME microtask sees it — no dedupe race);
+     *  - self-cleans: on failure, removes ITSELF from `sessions` (never a newer entry a racer already installed
+     *    — the `sessions.get(language) === job` check) so the next request retries instead of caching a miss;
+     *  - self-warms: a heal job (`heal` set) `warmOpen`s the carried files as part of settling, before anyone
+     *    can observe it as "done" — no caller-side extra step, no window where a racer sees a warm-less session;
+     *  - self-closes an orphan: if a CONCURRENT heal already replaced this job in `sessions` before it settled
+     *    (this job "lost" the race), the just-opened transport is closed instead of leaked with no owner.
+     *
+     *  Callers must NEVER wrap `settleOnAbort` around a naive `await` of a SHARED promise and then branch the
+     *  logging/cache-eviction on THAT wrapped value — a caller whose OWN signal aborted would then look
+     *  indistinguishable from the job itself failing, misfiring `lsp_session_*_failed` and evicting a still-live
+     *  in-flight entry out from under a concurrent caller (§DESIGN-V2 F1). `sessionFor` only ever wraps the
+     *  RETURN boundary; every cache/log decision above happens INSIDE the job, driven by the job's own outcome.
+     */
+    startJob(env, sessions, language, heal) {
+        const job = this.open(language, env)
+            .then(async (session) => {
+            if (!session) {
+                if (sessions.get(language) === job)
+                    sessions.delete(language); // don't cache a miss — retry next request
+                this.log(heal ? "lsp_session_heal_failed" : "lsp_session_open_failed", { language, ...(heal ? { carried: heal.carry.length } : {}) });
+                this.metrics?.inc(heal ? "lsp_session_heal_total" : "lsp_session_open_total", heal ? { outcome: "failed" } : { language, outcome: "failed" });
+                return undefined;
+            }
+            // review finding ② (independent re-review): `warmOpen` (unlike `syncOne`'s OWN internal `readText`
+            // guard) can still reject — e.g. `TransportLspSession.syncOne`'s unwrapped `this.transport.notify(...)`
+            // call (core lsp-session.js) — and this is the SHARED job every caller for this env+language awaits;
+            // an uncaught rejection here would otherwise propagate through `job` itself. Aligned with core's own
+            // precedent for this exact call (node-lsp-manager.js:137): the carry-over is best-effort — a failed
+            // resync degrades to "not carried," not an aborted heal.
+            if (heal)
+                await session.warmOpen(heal.carry).catch(() => ({ opened: 0, failed: heal.carry.length }));
+            if (sessions.get(language) !== job) {
+                // Orphaned: a concurrent heal replaced us in `sessions` before we settled — the winner's session is
+                // what everyone will use; don't leak this one.
+                await session.close().catch(() => undefined);
+                return undefined;
+            }
+            this.log(heal ? "lsp_session_heal" : "lsp_session_open", { language, ...(heal ? { carried: heal.carry.length } : {}) });
+            this.metrics?.inc(heal ? "lsp_session_heal_total" : "lsp_session_open_total", heal ? { outcome: "ok" } : { language, outcome: "ok" });
+            return session;
+        })
+            .catch((e) => {
+            // Defense in depth (review finding ②): ANY other unexpected throw in the callback above (not just
+            // warmOpen) must not leave a PERMANENTLY REJECTED promise cached in `sessions` — the self-clean-on-
+            // failure logic above only runs on the resolve-undefined path, never on a rejection, so without this
+            // every subsequent `sessionFor` for this env+language would throw instead of degrading.
+            if (sessions.get(language) === job)
+                sessions.delete(language);
+            this.log(heal ? "lsp_session_heal_failed" : "lsp_session_open_failed", {
+                language,
+                error: e instanceof Error ? e.message : String(e),
+                ...(heal ? { carried: heal.carry.length } : {}),
+            });
+            this.metrics?.inc(heal ? "lsp_session_heal_total" : "lsp_session_open_total", heal ? { outcome: "failed" } : { language, outcome: "failed" });
+            return undefined;
+        });
+        sessions.set(language, job); // synchronous — no `await` above (run-to-completion dedupe guard)
+        return job;
+    }
     async open(language, env) {
-        const transport = await this.factory(language, env).catch(() => undefined);
-        if (!transport)
+        // "session-open-failed" is the catch-all: the factory threw instead of returning its normal discriminated
+        // result — everything ELSE (install/start/connect/budget failures) is reported through that result, never
+        // through a rejection, so reaching this branch itself is already the diagnostic (the factory's own
+        // implementation is where a specific reason would have been attached).
+        const result = await this.factory(language, env).catch(() => ({ ok: false, reason: "session-open-failed" }));
+        let byLang = this.lastFailure.get(env);
+        if (!result.ok) {
+            if (!byLang) {
+                byLang = new Map();
+                this.lastFailure.set(env, byLang);
+            }
+            byLang.set(language, result.reason);
             return undefined;
+        }
+        byLang?.delete(language); // F10: a successful open clears any stale reason from a PRIOR failure
+        const transport = result.transport;
         const readText = async (fp) => {
             const r = await env.readTextFile(fp);
             if (!r.ok || r.value === undefined)

package/dist/lsp/ws-transport.d.ts

@@ -36,5 +36,5 @@ export declare class WsLspTransport implements LspTransport {
  * Returns `undefined` on any failure (→ the manager degrades that language gracefully). `wsUrl` is the
  * `wss://…e2b.dev` URL from `sandbox.getHost(port)`; `rootPath` is the in-sandbox workspace root.
  */
-export declare function connectWsLspTransport(wsUrl: string, rootPath: string, signal?: AbortSignal): Promise<LspTransport | undefined>;
+export declare function connectWsLspTransport(wsUrl: string, rootPath: string, signal?: AbortSignal, initializationOptions?: unknown): Promise<LspTransport | undefined>;
 //# sourceMappingURL=ws-transport.d.ts.map