@sema-agent/server 4.2.0 → 4.3.0

package/dist/boot/execution-env.js

@@ -353,7 +353,14 @@ export function createExecutionEnv(ctx) {
     // (no on-the-fly npm path on Kata; a miss degrades the lsp tool gracefully, same as E2B).
     const lspProvider = config.remoteExec?.provider;
     const lspManager = (lspProvider === "e2b" || lspProvider === "k8s") && config.lspEnabled
-        ? createE2bLspManager({ log: (event, fields) => logger.info(event, fields), scheme: lspProvider === "k8s" ? "ws" : "wss" })
+        ? createE2bLspManager({
+            log: (event, fields) => logger.info(event, fields),
+            scheme: lspProvider === "k8s" ? "ws" : "wss",
+            // §DESIGN-V2 F11: pass the lane explicitly — the bridge metrics' `provider` label names the
+            // DEPLOYMENT lane, not the WS scheme (the two happen to correlate today but are different axes).
+            provider: lspProvider,
+            metrics,
+        })
         : // TOC local LSP (core 1.190): the host lane runs on THIS machine, so core's `NodeLspManager` spawns the
             // language server as a LOCAL child_process over stdio (CC `services/lsp` parity). Its default resolveRoot uses
             // `env.cwd` — and core passes each task's executionEnv (the per-agent WORKTREE env, so the server roots in the

package/dist/http/server.d.ts

@@ -466,6 +466,22 @@ export declare function validateUserSkills(skills: unknown): string | null;
 export declare function createHttpServer(rawDeps: ServiceDeps): http.Server & {
     denyExpiredApprovals: (now: number) => Promise<void>;
 };
-/** Stable, low-cardinality route label for metrics/logs (ids collapsed to `:id`). */
+/** SSE: replay durable events after Last-Event-ID, then tail until the run is terminal (or stale). */
+/**
+ * The differences a concrete log (task_run | image_bake) feeds the ONE resumable SSE reader (P2.8). Everything
+ * the reader does — Last-Event-ID/`?from=` resume, the 416 retention boundary, the per-poll concurrent
+ * status+events read, the terminal re-fetch (the terminal event lands in the gap before the status flips), the
+ * stale fallback, the 15-min cap, the 15s idle heartbeat — is provider-agnostic and lives in `streamSseLog`.
+ * 🔴 The task_run provider MUST keep the existing wire bytes EXACTLY (center's relay + 730+ tests depend on it).
+ */
+/** POST endpoints that trigger BILLABLE work — the fail-closed auth guard must cover ALL of them (council: the
+ *  guard's inline list had drifted from the handlers and missed `/v1/approvals/:id/decide`, which resumes a run
+ *  via resumeCheckpoint/store.decide → paid tokens). Keep this in sync when adding a billable POST route. */
+export declare function isBillableSubmitPath(url: string): boolean;
+/** Stable, low-cardinality route label for metrics/logs (ids collapsed to `:id`).
+ *  [#104] 字面量**先于**模式:此前模式先查,五条精确路由被形状桶吞掉(`/v1/approvals/stream`
+ *  落 ":id"、`/v1/images/{bakes,select,register}` 落 ":profile"、`/v1/images/bakes/claim` 落
+ *  "bakes/:id")——长连接 stream 的 duration 混进 :id 桶正是 fleet/stream 案的同族错桶病。
+ *  精确匹配恒比形状匹配更对,序修零反例(billable-route-declaration 门逐样本钉)。 */
 export declare function routeLabel(_method: string, url: string): string;
 //# sourceMappingURL=server.d.ts.map

package/dist/http/server.js

@@ -2427,7 +2427,9 @@ export function createHttpServer(rawDeps) {
 /** POST endpoints that trigger BILLABLE work — the fail-closed auth guard must cover ALL of them (council: the
  *  guard's inline list had drifted from the handlers and missed `/v1/approvals/:id/decide`, which resumes a run
  *  via resumeCheckpoint/store.decide → paid tokens). Keep this in sync when adding a billable POST route. */
-function isBillableSubmitPath(url) {
+// [#104/#87-A3] exported for the declaration gate (test/billable-route-declaration.test.ts):每条路由
+// 标签必须显式申明 billable,与本谓词逐样本对账——「Keep this in sync」从注释请求变成机器断言。
+export function isBillableSubmitPath(url) {
     return (url === "/v1/side-query" || // [1469] one-shot brain call — runs the model, so it rides every billable-submit gate
         url === "/v1/tasks" ||
         url === "/v1/tasks/stream" ||
@@ -2503,13 +2505,17 @@ const ROUTE_LABEL_LITERALS = new Set([
     "/v1/fleet/stream",
     "/v1/memory/export", "/v1/sendfile-links",
 ]);
-/** Stable, low-cardinality route label for metrics/logs (ids collapsed to `:id`). */
+/** Stable, low-cardinality route label for metrics/logs (ids collapsed to `:id`).
+ *  [#104] 字面量**先于**模式:此前模式先查,五条精确路由被形状桶吞掉(`/v1/approvals/stream`
+ *  落 ":id"、`/v1/images/{bakes,select,register}` 落 ":profile"、`/v1/images/bakes/claim` 落
+ *  "bakes/:id")——长连接 stream 的 duration 混进 :id 桶正是 fleet/stream 案的同族错桶病。
+ *  精确匹配恒比形状匹配更对,序修零反例(billable-route-declaration 门逐样本钉)。 */
 export function routeLabel(_method, url) {
+    if (ROUTE_LABEL_LITERALS.has(url))
+        return url;
     for (const [re, label] of ROUTE_LABEL_PATTERNS)
         if (re.test(url))
             return label;
-    if (ROUTE_LABEL_LITERALS.has(url))
-        return url;
     return "other";
 }
 /** CORS v2: allowlist semantics. A SINGLE configured origin keeps the v1 posture

package/dist/lsp/e2b-bridge.d.ts

@@ -3,16 +3,33 @@
  * **auth token** `LSP_TOKEN` (the endpoint is a public `wss://<port>-<id>.e2b.app` URL — the runner connects with
  * `?token=<secret>`; without it, anyone with the URL could read the workspace via LSP, council #4). Frame parsing
  * uses the unit-tested {@link FRAME_DECODER_JS} (council #1/#2/#5).
+ *
+ * redesign⑤ (#96 §DESIGN-V2 F4): the WS server now rides an explicit `http.createServer` instead of binding its
+ * own socket (`new WebSocketServer({host,port})`) — the same port also answers `GET /healthz` (host-side liveness
+ * probe, §DESIGN-V2 F2/C6) without a second port or dependency. The EADDRINUSE loud-exit handler MOVES with the
+ * bind onto the http server (`server.on('error', …)`, same `lsp-bridge wss error` text + `exit 1` — test/lsp-e2b.test.ts
+ * :256-269 pins this exact text/code); `ws` still forwards its underlying server's `'error'` to `wss`, so nothing
+ * downstream (per-connection handling) changes.
  */
 export declare const BRIDGE_SOURCE: string;
+/** Bridge dir inside the sandbox(声明提前:tsserver 定值路径引用它)。 */
+export declare const BRIDGE_DIR = "/home/user/.lsp-bridge";
+/** tls 的 tsserver.js 定值路径(#96 真机门):install 腿保证在场,connect 腿经
+ *  `initializationOptions.tsserver.path` 告知 tls(v4 起无 CLI 旗可用)。 */
+export declare const TSSERVER_JS_PATH = "/home/user/.lsp-bridge/node_modules/typescript/lib/tsserver.js";
 /** Language server command per languageId. P1 = typescript/javascript; dart/kotlin land with their template servers.
  *  `--stdio` only where the server needs it to pick stdio over its other transports (the node-based servers);
- *  gopls/jdtls/kotlin-language-server/sourcekit-lsp/`dart language-server` speak LSP over stdio by default. */
+ *  gopls/jdtls/kotlin-language-server/sourcekit-lsp/`dart language-server` speak LSP over stdio by default.
+ *  #96 真机门发现(E2B 真沙箱逐帧取证,test/lsp-e2b-bridge-live.test.ts):typescript-language-server
+ *  **不自动发现全局 typescript**(只认 workspace 内 node_modules/typescript 或显式 tsserver 路径),
+ *  `npm i -g … typescript` 装成之后 initialize 仍答 "Could not find a valid TypeScript installation";
+ *  且 v4 起 `--tsserver-path` CLI 旗已移除(未知参数=进程退 1,第二轮真机实测)——路径只能走 LSP
+ *  `initializationOptions.tsserver.path`(TSSERVER_JS_PATH,connectE2bLspBridge 对 ts/js 传入),
+ *  typescript 本体由 lspInstallCommand 落进 BRIDGE_DIR 定值路径(烤好模板文件在场则秒过)。 */
 export declare const SERVER_CMD: Readonly<Record<string, string>>;
 /** npm packages a non-baked sandbox needs (on-the-fly install). Languages absent here (go) REQUIRE a baked template. */
 export declare const SERVER_NPM: Readonly<Record<string, string>>;
-/** Bridge dir + port inside the sandbox. One bridge process per language → distinct ports. */
-export declare const BRIDGE_DIR = "/home/user/.lsp-bridge";
+/** One bridge process per language → distinct ports.(BRIDGE_DIR 声明已提前至 SERVER_CMD 上方。) */
 export declare function portForLanguage(language: string): number;
 /** FOREGROUND install (run via `env.exec` — must finish before the start). A baked template makes both checks
  *  skip instantly; a non-baked sandbox npm-installs the server + ws here (slow once per sandbox). */
@@ -21,4 +38,20 @@ export declare function lspInstallCommand(language: string): string;
  *  foreground run: E2B reaps the foreground process group on completion, killing an in-shell `&`/nohup child.
  *  So node is the FOREGROUND here and E2B keeps the background command alive. */
 export declare function lspStartCommand(language: string, port: number, token: string): string;
+/** Where the on-the-fly `npm i` output from {@link lspInstallCommand} lands — previously had zero readers
+ *  (§DESIGN-V2 F7 bonus fix); an install failure now tails this for the `lastError`/event snippet. */
+export declare const LSP_SETUP_LOG = "/tmp/lsp-setup.log";
+/** BRIDGE_DIR-relative log the bridge process itself appends to (fatal errors, child exits) — §DESIGN-V2 C4. */
+export declare function bridgeLogFile(): string;
+/** Per-port pidfile the bridge writes ONLY after a confirmed bind (BRIDGE_SOURCE's `listen` callback) — see its
+ *  header comment for why a losing (EADDRINUSE) second bridge must never clobber this. */
+export declare function bridgePidFile(port: number): string;
+/** §DESIGN-V2 F3: verify a prior bridge generation ACTUALLY stopped before the host mints a replacement.
+ *  Exit 0 = confirmed dead (or the pidfile never existed — nothing was ever listening) → safe to start a new
+ *  generation on this port. Exit 1 = still alive after the bound wait — the caller MUST NOT start a new bridge:
+ *  an unconfirmed kill risks EADDRINUSE (the new generation's fresh token would then be permanently rejected by
+ *  the still-listening old process, the token check in BRIDGE_SOURCE) — better to stay `dead` than double-burn
+ *  the restart budget on a doomed attempt. POSIX `sh` only (no `seq`/bashisms — sandboxes vary in shell).
+ *  Bound: 20 × 0.1s = 2s. */
+export declare function terminateBridgeCommand(port: number): string;
 //# sourceMappingURL=e2b-bridge.d.ts.map

package/dist/lsp/e2b-bridge.js

@@ -14,23 +14,60 @@ import { FRAME_DECODER_JS } from "./lsp-frames.js";
  * **auth token** `LSP_TOKEN` (the endpoint is a public `wss://<port>-<id>.e2b.app` URL — the runner connects with
  * `?token=<secret>`; without it, anyone with the URL could read the workspace via LSP, council #4). Frame parsing
  * uses the unit-tested {@link FRAME_DECODER_JS} (council #1/#2/#5).
+ *
+ * redesign⑤ (#96 §DESIGN-V2 F4): the WS server now rides an explicit `http.createServer` instead of binding its
+ * own socket (`new WebSocketServer({host,port})`) — the same port also answers `GET /healthz` (host-side liveness
+ * probe, §DESIGN-V2 F2/C6) without a second port or dependency. The EADDRINUSE loud-exit handler MOVES with the
+ * bind onto the http server (`server.on('error', …)`, same `lsp-bridge wss error` text + `exit 1` — test/lsp-e2b.test.ts
+ * :256-269 pins this exact text/code); `ws` still forwards its underlying server's `'error'` to `wss`, so nothing
+ * downstream (per-connection handling) changes.
  */
 export const BRIDGE_SOURCE = FRAME_DECODER_JS +
     String.raw `
 const { WebSocketServer } = require('ws');
 const { spawn } = require('child_process');
 const { URLSearchParams } = require('url');
+const http = require('http');
+const fs = require('fs');
 const PORT = Number(process.env.LSP_PORT || 8123);
 const CMD = (process.env.LSP_CMD || 'typescript-language-server --stdio').split(' ');
 const TOKEN = process.env.LSP_TOKEN || '';
 const MAX = 50 * 1024 * 1024;
 const HEARTBEAT_MS = Number(process.env.LSP_HEARTBEAT_MS || 30000);
-const wss = new WebSocketServer({ host: '0.0.0.0', port: PORT });
+const START_MS = Date.now();
+// Per-port pidfile (BRIDGE_DIR-relative — lspStartCommand cd's there first): the host reads this to verify a
+// prior generation ACTUALLY stopped before minting a replacement (§DESIGN-V2 F3) — an unconfirmed kill risks a
+// new generation's token being permanently rejected by a still-listening old process (the token check below).
+// Written ONLY after a successful bind (inside the listen callback) — a SECOND bridge racing this same port
+// must NOT clobber the FIRST (still listening) bridge's pidfile with its own (about-to-die) pid.
+const PIDFILE = 'bridge-' + PORT + '.pid';
+const LOGFILE = 'bridge.log';
+function logLine(line) { try { fs.appendFileSync(LOGFILE, line + '\n'); } catch {} }
+// Process-fatal hardening (§DESIGN-V2 C1/C2): an uncaught exception/rejection anywhere in this process previously
+// died silently (no stderr line, no log) — the host's only signal was the WS going dead with no explanation.
+process.on('uncaughtException', (err) => { const m = 'lsp-bridge fatal ' + (err && err.message); console.error(m); logLine(m); process.exit(1); });
+process.on('unhandledRejection', (err) => { const m = 'lsp-bridge fatal ' + (err && err.message); console.error(m); logLine(m); process.exit(1); });
+function tokenOf(url) { return new URLSearchParams(((url || '').split('?')[1]) || '').get('token'); }
+const server = http.createServer((req, res) => {
+  const path = ((req && req.url) || '').split('?')[0];
+  if (path === '/healthz') {
+    // Same-origin auth as the WS gate below: TOKEN unset = open (dev/test), TOKEN set + mismatch = 401.
+    if (TOKEN && tokenOf(req.url) !== TOKEN) { res.writeHead(401); res.end(); return; }
+    const body = JSON.stringify({ pid: process.pid, uptimeMs: Date.now() - START_MS, connections: wss.clients.size, generationToken: TOKEN.slice(0, 8) });
+    res.writeHead(200, { 'Content-Type': 'application/json' });
+    res.end(body);
+    return;
+  }
+  const body = http.STATUS_CODES[426]; // preserves ws's own default "upgrade required" response for any other path
+  res.writeHead(426, { 'Content-Length': Buffer.byteLength(body), 'Content-Type': 'text/plain' });
+  res.end(body);
+});
 // A zero-listener 'error' on ANY EventEmitter throws and crashes the process (Node default). Without this, a
 // bind failure (e.g. EADDRINUSE — a second bridge start racing the same port) took down the WHOLE bridge
 // process, killing every language's LSP session in the sandbox, not just the one that failed to start (HRD-LSP-4).
 // Exit loud + explicit instead of an uncaught-exception dump so the failure is at least attributable.
-wss.on('error', (err) => { console.error('lsp-bridge wss error', err && err.message); process.exit(1); });
+server.on('error', (err) => { const m = 'lsp-bridge wss error ' + (err && err.message); console.error(m); logLine(m); process.exit(1); });
+const wss = new WebSocketServer({ server });
 wss.on('connection', (ws, req) => {
   // Same zero-listener 'error' hazard as wss above, but per-connection: registered FIRST, before anything else
   // touches this socket. Close (don't crash) — the heartbeat reaper's own ws.terminate() below is a routine
@@ -51,7 +88,7 @@ wss.on('connection', (ws, req) => {
   // CALLER's process group instead of the (nonexistent) child (HRD-LSP-4; same hazard class as bake-runner's
   // spawner, src/bake-runner/main.ts).
   ws.on('close', () => { if (child.pid !== undefined) child.kill(); });
-  child.on('exit', () => { try { ws.close(); } catch {} });
+  child.on('exit', (code, signal) => { logLine('lsp-bridge child exit code=' + code + ' signal=' + signal); try { ws.close(); } catch {} });
 });
 // Reap half-open connections: the E2B proxy kills a WS at ~60-75s and the kill can be SILENT on THIS side too —
 // no close frame, so the per-connection language server above would outlive its dead socket (one leaked server
@@ -63,11 +100,25 @@ setInterval(() => {
     try { ws.ping(); } catch {}
   }
 }, HEARTBEAT_MS);
-console.log('lsp-bridge listening', PORT);
+server.listen(PORT, '0.0.0.0', () => {
+  try { fs.writeFileSync(PIDFILE, String(process.pid)); } catch (e) { logLine('lsp-bridge pidfile write failed ' + (e && e.message)); }
+  console.log('lsp-bridge listening', PORT);
+});
 `;
+/** Bridge dir inside the sandbox(声明提前:tsserver 定值路径引用它)。 */
+export const BRIDGE_DIR = "/home/user/.lsp-bridge";
+/** tls 的 tsserver.js 定值路径(#96 真机门):install 腿保证在场,connect 腿经
+ *  `initializationOptions.tsserver.path` 告知 tls(v4 起无 CLI 旗可用)。 */
+export const TSSERVER_JS_PATH = `${BRIDGE_DIR}/node_modules/typescript/lib/tsserver.js`;
 /** Language server command per languageId. P1 = typescript/javascript; dart/kotlin land with their template servers.
  *  `--stdio` only where the server needs it to pick stdio over its other transports (the node-based servers);
- *  gopls/jdtls/kotlin-language-server/sourcekit-lsp/`dart language-server` speak LSP over stdio by default. */
+ *  gopls/jdtls/kotlin-language-server/sourcekit-lsp/`dart language-server` speak LSP over stdio by default.
+ *  #96 真机门发现(E2B 真沙箱逐帧取证,test/lsp-e2b-bridge-live.test.ts):typescript-language-server
+ *  **不自动发现全局 typescript**(只认 workspace 内 node_modules/typescript 或显式 tsserver 路径),
+ *  `npm i -g … typescript` 装成之后 initialize 仍答 "Could not find a valid TypeScript installation";
+ *  且 v4 起 `--tsserver-path` CLI 旗已移除(未知参数=进程退 1,第二轮真机实测)——路径只能走 LSP
+ *  `initializationOptions.tsserver.path`(TSSERVER_JS_PATH,connectE2bLspBridge 对 ts/js 传入),
+ *  typescript 本体由 lspInstallCommand 落进 BRIDGE_DIR 定值路径(烤好模板文件在场则秒过)。 */
 export const SERVER_CMD = {
     typescript: "typescript-language-server --stdio",
     javascript: "typescript-language-server --stdio",
@@ -85,8 +136,7 @@ export const SERVER_NPM = {
     javascript: "typescript-language-server typescript",
     python: "pyright",
 };
-/** Bridge dir + port inside the sandbox. One bridge process per language → distinct ports. */
-export const BRIDGE_DIR = "/home/user/.lsp-bridge";
+/** One bridge process per language → distinct ports.(BRIDGE_DIR 声明已提前至 SERVER_CMD 上方。) */
 export function portForLanguage(language) {
     // stable per-language port; extend the table as templates add servers (dev-mobile: dart/kotlin/java/swift)
     const ports = { typescript: 8123, javascript: 8123, dart: 8124, kotlin: 8125, python: 8126, go: 8127, java: 8128, swift: 8129 };
@@ -101,6 +151,13 @@ export function lspInstallCommand(language) {
         `mkdir -p ${BRIDGE_DIR}`,
         `[ -f ${BRIDGE_DIR}/node_modules/ws/package.json ] || (cd ${BRIDGE_DIR} && echo '{}' > package.json && npm i ws >/tmp/lsp-setup.log 2>&1)`,
         npm ? `command -v ${cmd.split(" ")[0]} >/dev/null || npm i -g ${npm} >>/tmp/lsp-setup.log 2>&1` : "true",
+        // #96 真机门:tls 只认 workspace typescript 或显式 tsserver 路径(全局装了也不认)——把 typescript
+        // 落到 BRIDGE_DIR 定值路径,与 TSSERVER_JS_PATH(initializationOptions 腿)同源。烤好模板文件在场则秒过。
+        // 🔴 钉 @5:裸 `typescript` 现装到 7.x(Go 原生港,lib/ 无 tsserver.js,真机实测)——tls 绑死
+        // TS5 的 JS tsserver。TS7 自带原生 LSP 是未来的换代方向(届时连 tls 一起退役),不是本车。
+        npm?.includes("typescript")
+            ? `[ -f ${TSSERVER_JS_PATH} ] || (cd ${BRIDGE_DIR} && npm i typescript@5 >>/tmp/lsp-setup.log 2>&1)`
+            : "true",
     ].join(" && ");
 }
 /** Start the bridge — run as a TRUE background command (`env.startBackground`), NOT `&`-backgrounded inside a
@@ -109,4 +166,34 @@ export function lspInstallCommand(language) {
 export function lspStartCommand(language, port, token) {
     return `cd ${BRIDGE_DIR} && LSP_PORT=${port} LSP_TOKEN='${token}' LSP_CMD='${SERVER_CMD[language]}' node bridge.cjs`;
 }
+/** Where the on-the-fly `npm i` output from {@link lspInstallCommand} lands — previously had zero readers
+ *  (§DESIGN-V2 F7 bonus fix); an install failure now tails this for the `lastError`/event snippet. */
+export const LSP_SETUP_LOG = "/tmp/lsp-setup.log";
+/** BRIDGE_DIR-relative log the bridge process itself appends to (fatal errors, child exits) — §DESIGN-V2 C4. */
+export function bridgeLogFile() {
+    return `${BRIDGE_DIR}/bridge.log`;
+}
+/** Per-port pidfile the bridge writes ONLY after a confirmed bind (BRIDGE_SOURCE's `listen` callback) — see its
+ *  header comment for why a losing (EADDRINUSE) second bridge must never clobber this. */
+export function bridgePidFile(port) {
+    return `${BRIDGE_DIR}/bridge-${port}.pid`;
+}
+/** §DESIGN-V2 F3: verify a prior bridge generation ACTUALLY stopped before the host mints a replacement.
+ *  Exit 0 = confirmed dead (or the pidfile never existed — nothing was ever listening) → safe to start a new
+ *  generation on this port. Exit 1 = still alive after the bound wait — the caller MUST NOT start a new bridge:
+ *  an unconfirmed kill risks EADDRINUSE (the new generation's fresh token would then be permanently rejected by
+ *  the still-listening old process, the token check in BRIDGE_SOURCE) — better to stay `dead` than double-burn
+ *  the restart budget on a doomed attempt. POSIX `sh` only (no `seq`/bashisms — sandboxes vary in shell).
+ *  Bound: 20 × 0.1s = 2s. */
+export function terminateBridgeCommand(port) {
+    const pidfile = bridgePidFile(port);
+    return [
+        `[ -f ${pidfile} ] || exit 0`,
+        `PID=$(cat ${pidfile})`,
+        `kill "$PID" 2>/dev/null`,
+        `i=0`,
+        `while [ $i -lt 20 ]; do kill -0 "$PID" 2>/dev/null || exit 0; i=$((i+1)); sleep 0.1; done`,
+        `exit 1`,
+    ].join("; ");
+}
 //# sourceMappingURL=e2b-bridge.js.map

package/dist/lsp/e2b-manager.d.ts

@@ -1,5 +1,5 @@
 import { connectWsLspTransport } from "./ws-transport.js";
-import { E2bLspManager, type LspCapableEnv } from "./manager.js";
+import { E2bLspManager, type LspCapableEnv, type LspUnavailableReason } from "./manager.js";
 import type { LspTransport } from "./types.js";
 export interface E2bLspOptions {
     /** Injectable for tests (no E2B/ws). */
@@ -20,11 +20,74 @@ export interface E2bLspOptions {
     scheme?: "ws" | "wss";
     /** Observability hook (open/heal/degrade events) — prod wires the service logger. */
     log?: (event: string, fields: Record<string, unknown>) => void;
+    /** §DESIGN-V2 F11: metrics registry (structural — matches the narrow surface remote-env-e2b.ts's `cfg.metrics`
+     *  already uses). `provider`/`generation`/`reason` labels are filled in by this module, never left freeform. */
+    metrics?: {
+        inc(name: string, labels?: Record<string, string>): void;
+    };
+    /** §DESIGN-V2 F11: the deployment lane feeding this manager (boot/execution-env.ts passes it explicitly —
+     *  "e2b" or "k8s" — rather than this module guessing it back out of `scheme`, which is a WS-protocol detail
+     *  that happens to correlate with the lane but isn't the same axis). Defaults to inferring from `scheme` only
+     *  so existing callers that don't pass it (tests) keep working. */
+    provider?: string;
+    /** §DESIGN-V2 F2/C6: health-probe override for tests (no real sandbox network). Defaults to a real
+     *  `GET /healthz` fetch (1s timeout) — `scheme` maps to the probe's URL scheme, F11 (`wss→https`, `ws→http`). */
+    probe?: (env: LspCapableEnv, port: number, token: string, scheme: "ws" | "wss") => Promise<boolean>;
 }
 /** Start (+ install on a non-baked template) the language server + bridge inside THIS env's sandbox, then connect.
  *  Every call starts (or re-starts) the bridge unconditionally — the one production caller is
  *  `createE2bLspManager`, which de-dupes per env+port before ever reaching here (see its doc). */
 export declare function openE2bLspTransport(language: string, env: LspCapableEnv, opts?: E2bLspOptions): Promise<LspTransport | undefined>;
+/** §DESIGN-V2 A: `starting` while the write+install+startBackground sequence is in flight; `ready` once at
+ *  least one WS connect through this generation has succeeded; `dead` once this generation is confirmed (or
+ *  presumed, per its own failure) unusable — the ONLY way out of `dead` is minting a new generation. */
+export type BridgeState = "starting" | "ready" | "dead";
+/**
+ * §DESIGN-V2 A/F3/F6: one bridge RESOURCE per env+port (not per language — `portForLanguage` maps
+ * typescript/javascript onto the SAME port/process off the same `SERVER_CMD`, HRD-LSP-4). A crashed/never-
+ * booted bridge can be replaced by minting a new `generation` (bounded by `MAX_BRIDGE_GENERATIONS` — a
+ * crash-loop must degrade the language, not burn the sandbox indefinitely); the NEW generation is only ever
+ * minted after `terminateBridgeCommand` confirms the OLD one actually stopped (F3) — an unconfirmed kill risks
+ * EADDRINUSE permanently rejecting the new generation's fresh token (the old process is still the one
+ * listening, and its token check has no way to know a replacement was intended).
+ */
+export interface E2bBridgeHandle {
+    readonly port: number;
+    /** Pinned once per generation — the shared bridge resource's auth secret. A per-LANGUAGE token would be
+     *  rejected by the one bridge process actually listening whenever two languages share a port (see the
+     *  module doc's HRD-LSP-4 reference): the second language mints a different token, the bridge only
+     *  recognizes whichever token started it, auth fails, retries exhaust, and that language is permanently
+     *  degraded to grep/read_file for the task. */
+    readonly token: string;
+    /** The `LSP_CMD` this generation's bridge process was launched with — identity documentation (ts/js sharing
+     *  one value/port/process is legitimate, §DESIGN-V2 "不做"); not read back by this module. */
+    readonly serverCmd: string;
+    /** 1 at first mint; +1 every restart. Bounds the restart budget (`MAX_BRIDGE_GENERATIONS`). */
+    readonly generation: number;
+    state: BridgeState;
+    /** The most recent human-readable diagnostic (write/install/start/connect failure, or a probe verdict) —
+     *  feeds `lastError`-style debugging; the MODEL-facing word is `deathReason` (via `unavailableReason`), not
+     *  this free-text string. */
+    lastError?: string;
+    /** The SPECIFIC reason THIS generation died (unset while starting/ready). `unavailableReason`-facing
+     *  reporting overrides this to `bridge-restart-budget-exhausted` once `generation >= MAX_BRIDGE_GENERATIONS`
+     *  — "further restarts won't help" is a different (and, once true, more useful) word than "what killed the
+     *  last one." */
+    deathReason?: LspUnavailableReason;
+    /** True once this generation has completed at least one real WS connect. Gates the fast healthz-probe heal
+     *  path (§DESIGN-V2 F2/F6): a generation that has never connected yet is still cold-starting, not dead —
+     *  treating an unreachable healthz as "dead" during that window would misjudge ordinary boot lag as a crash
+     *  and burn a restart generation for nothing. A generation that HAS connected before, though, really should
+     *  be reachable again quickly, so it skips the blind 6×1500ms retry loop and asks the bridge directly. */
+    everConnected: boolean;
+    /** Resolves once the write+install+startBackground sequence has been ATTEMPTED for this generation — `false`
+     *  (with `state` already flipped to `dead` + `deathReason`/`lastError` set) means it failed before ever
+     *  reaching a connect attempt. */
+    ready: Promise<boolean>;
+}
+/** 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 declare const MAX_BRIDGE_GENERATIONS = 3;
 /** The single shared `LspServerManager` for the deployment (`RunnerDeps.lspManager`). */
 export declare function createE2bLspManager(opts?: E2bLspOptions): E2bLspManager;
 //# sourceMappingURL=e2b-manager.d.ts.map

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

package/dist/lsp/ws-transport.js

@@ -209,7 +209,7 @@ export class WsLspTransport {
  * 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 async function connectWsLspTransport(wsUrl, rootPath, signal) {
+export async function connectWsLspTransport(wsUrl, rootPath, signal, initializationOptions) {
     let socket;
     try {
         socket = new WebSocket(wsUrl);
@@ -245,6 +245,9 @@ export async function connectWsLspTransport(wsUrl, rootPath, signal) {
             processId: null,
             rootUri: pathToUri(rootPath),
             capabilities: { textDocument: { definition: {}, references: {}, hover: {}, documentSymbol: {}, implementation: {}, callHierarchy: {} }, workspace: { symbol: {} } },
+            // #96 真机门:tls 的 tsserver 路径只能走这里(v4 移除了 CLI 旗);非 tls 服务器按 LSP 规范忽略
+            // 未知 initializationOptions。缺席时不发键(老行为逐字保持)。
+            ...(initializationOptions !== undefined ? { initializationOptions } : {}),
         }, signal);
         transport.notify("initialized", {});
         return transport;

package/dist/observability/metrics.js

@@ -295,6 +295,12 @@ export function createMetrics() {
     // LOCAL floor(now/windowMs); replica clock skew splits a fleet window into disjoint buckets (soft-limit leak).
     m.gauge("fleet_counter_bucket_skew_ms", "DB clock minus local clock in ms (S10) — skew splits cross-replica counter windows");
     m.gauge("fleet_clock_probe_ok", "1 = last DB clock probe succeeded, 0 = failing (skew gauge is stale while 0)");
+    // #96 redesign⑤ (§DESIGN-V2 E): LSP sandbox-bridge lifecycle + session outcomes — previously zero metrics
+    // existed for the whole subsystem (a dead bridge or a stuck restart budget had no fleet-level signal).
+    m.counter("lsp_bridge_start_total", "LSP sandbox bridge (re)starts attempted, by provider and generation");
+    m.counter("lsp_bridge_dead_total", "LSP sandbox bridge generations that died, by reason (the word IS the model-facing unavailableReason)");
+    m.counter("lsp_session_open_total", "LSP session opens, by language and outcome (ok/failed)");
+    m.counter("lsp_session_heal_total", "LSP session heals (dead-transport reopen), by outcome (ok/failed)");
     // S21 — which backend snapshot blobs actually land on (minio|sql). Partial MINIO_* config silently falls to sql.
     m.gauge("snapshot_blob_backend", "1 on the active snapshot-blob backend series (S21), by backend (minio|sql)");
     // S22 — memory embed/KNN runtime failures (boot said vector; runtime silently degrades to lexical).

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@sema-agent/server",
-  "version": "4.2.0",
+  "version": "4.3.0",
   "description": "Sema Server — the server/API implementation layer for Sema, wiring core, registry, model providers, and cloud agent execution. Built on @sema-agent/core.",
   "type": "module",
   "license": "BUSL-1.1",