semantic-js-mcp 0.9.0 → 0.10.0

package/scripts/lifecycle-memory-benchmark.mjs

@@ -0,0 +1,300 @@
+#!/usr/bin/env node
+
+import {spawn} from "node:child_process";
+import path from "node:path";
+import {mkdtemp, mkdir, rm, writeFile} from "node:fs/promises";
+import {tmpdir} from "node:os";
+import {fileURLToPath} from "node:url";
+import {Client} from "@modelcontextprotocol/sdk/client/index.js";
+import {StdioClientTransport} from "@modelcontextprotocol/sdk/client/stdio.js";
+import {ENVIRONMENT_VARIABLE, NODE_EVENT, PRODUCT, TOOL} from "../protocol.mjs";
+import {
+  LIFECYCLE_MEMORY_BENCHMARK as BENCHMARK,
+  LIFECYCLE_MEMORY_EXIT_CODE,
+  LIFECYCLE_MEMORY_FIELD,
+  LIFECYCLE_MEMORY_METHOD,
+  LIFECYCLE_MEMORY_OBSERVER,
+  LIFECYCLE_MEMORY_REASON,
+  LIFECYCLE_MEMORY_STATUS,
+  LIFECYCLE_MEMORY_SUPPORTED_PLATFORMS,
+} from "./lifecycle-memory-contract.mjs";
+
+const PROCESS_ERROR = Object.freeze({COMMAND_NOT_FOUND: "ENOENT", NOT_FOUND: "ESRCH"});
+const PROCESS_EVENT = Object.freeze({DATA: "data"});
+const PROCESS_SIGNAL = Object.freeze({EXISTS: 0});
+const SUPPORTED_PLATFORM = new Set(LIFECYCLE_MEMORY_SUPPORTED_PLATFORMS);
+const PROVIDER_START_PATTERN = /starting provider (\d+)/;
+const pluginRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+async function waitUntil(predicate, message) {
+  for (let attempt = 0; attempt < BENCHMARK.OBSERVATION_ATTEMPTS; attempt += 1) {
+    const value = await predicate();
+    if (value) return value;
+    await delay(BENCHMARK.OBSERVATION_INTERVAL_MS);
+  }
+  throw new Error(message);
+}
+
+function processExists(pid) {
+  try {
+    process.kill(pid, PROCESS_SIGNAL.EXISTS);
+    return true;
+  } catch (error) {
+    if (error?.code === PROCESS_ERROR.NOT_FOUND) return false;
+    throw error;
+  }
+}
+
+function readResidentSetBytes(pid) {
+  return new Promise((resolve, reject) => {
+    const child = spawn("ps", ["-o", "rss=", "-p", String(pid)], {stdio: ["ignore", "pipe", "pipe"]});
+    const stdout = [];
+    const stderr = [];
+    child.stdout.on(PROCESS_EVENT.DATA, (chunk) => stdout.push(chunk));
+    child.stderr.on(PROCESS_EVENT.DATA, (chunk) => stderr.push(chunk));
+    child.on(NODE_EVENT.ERROR, reject);
+    child.on(NODE_EVENT.CLOSE, (exitCode) => {
+      const kibibytes = Number(Buffer.concat(stdout).toString("utf8").trim());
+      if (exitCode === 0 && Number.isFinite(kibibytes)) {
+        resolve(kibibytes * 1024);
+        return;
+      }
+      const message = Buffer.concat(stderr).toString("utf8").trim() || `ps exited ${exitCode}`;
+      reject(new Error(`Could not read provider RSS: ${message}`));
+    });
+  });
+}
+
+function median(values) {
+  const ordered = [...values].sort((left, right) => left - right);
+  const middle = Math.floor(ordered.length / 2);
+  return ordered.length % 2 === 0 ? (ordered[middle - 1] + ordered[middle]) / 2 : ordered[middle];
+}
+
+function linearSlope(values) {
+  const center = (values.length - 1) / 2;
+  let numerator = 0;
+  let denominator = 0;
+  for (let index = 0; index < values.length; index += 1) {
+    const distance = index - center;
+    numerator += distance * values[index];
+    denominator += distance * distance;
+  }
+  return denominator === 0 ? 0 : numerator / denominator;
+}
+
+function summarize(values) {
+  return {
+    minimumBytes: Math.min(...values),
+    medianBytes: Math.round(median(values)),
+    maximumBytes: Math.max(...values),
+  };
+}
+
+function assessTrend(samples, field, {medianMinimumBytes, medianRatio, slopeMinimumBytes, slopeRatio}) {
+  const values = samples.map((sample) => sample[field]);
+  const firstMedian = median(values.slice(0, BENCHMARK.COMPARISON_WINDOW));
+  const lastMedian = median(values.slice(-BENCHMARK.COMPARISON_WINDOW));
+  const medianGrowthBytes = lastMedian - firstMedian;
+  const slopeBytesPerCycle = linearSlope(values);
+  const maximumMedianGrowthBytes = Math.max(medianMinimumBytes, firstMedian * medianRatio);
+  const maximumSlopeBytesPerCycle = Math.max(slopeMinimumBytes, firstMedian * slopeRatio);
+  return {
+    status:
+      medianGrowthBytes <= maximumMedianGrowthBytes && slopeBytesPerCycle <= maximumSlopeBytesPerCycle
+        ? LIFECYCLE_MEMORY_STATUS.PASS
+        : LIFECYCLE_MEMORY_STATUS.FAIL,
+    firstWindowMedianBytes: Math.round(firstMedian),
+    lastWindowMedianBytes: Math.round(lastMedian),
+    medianGrowthBytes: Math.round(medianGrowthBytes),
+    maximumMedianGrowthBytes: Math.round(maximumMedianGrowthBytes),
+    slopeBytesPerCycle: Math.round(slopeBytesPerCycle),
+    maximumSlopeBytesPerCycle: Math.round(maximumSlopeBytesPerCycle),
+  };
+}
+
+function assertAssessmentContract() {
+  const limits = {
+    medianMinimumBytes: BENCHMARK.SYNTHETIC_MEDIAN_LIMIT_BYTES,
+    medianRatio: 0,
+    slopeMinimumBytes: BENCHMARK.SYNTHETIC_SLOPE_LIMIT_BYTES,
+    slopeRatio: 0,
+  };
+  const stable = Array.from({length: BENCHMARK.SYNTHETIC_SAMPLE_COUNT}, (_, index) => ({
+    [LIFECYCLE_MEMORY_FIELD.SYNTHETIC_VALUE]: BENCHMARK.SYNTHETIC_BASE_BYTES + (index % BENCHMARK.SYNTHETIC_STABLE_VARIATION_BYTES),
+  }));
+  const growing = Array.from({length: BENCHMARK.SYNTHETIC_SAMPLE_COUNT}, (_, index) => ({
+    [LIFECYCLE_MEMORY_FIELD.SYNTHETIC_VALUE]: BENCHMARK.SYNTHETIC_BASE_BYTES + index * BENCHMARK.SYNTHETIC_GROWTH_BYTES_PER_CYCLE,
+  }));
+  assert(
+    assessTrend(stable, LIFECYCLE_MEMORY_FIELD.SYNTHETIC_VALUE, limits).status === LIFECYCLE_MEMORY_STATUS.PASS,
+    "Stable trend failed assessment",
+  );
+  assert(
+    assessTrend(growing, LIFECYCLE_MEMORY_FIELD.SYNTHETIC_VALUE, limits).status === LIFECYCLE_MEMORY_STATUS.FAIL,
+    "Growing trend passed assessment",
+  );
+}
+
+async function createWorkspace() {
+  const workspace = await mkdtemp(path.join(tmpdir(), `${PRODUCT.NAME}-lifecycle-memory-`));
+  const sourceDirectory = path.join(workspace, "src");
+  await mkdir(sourceDirectory, {recursive: true});
+  await writeFile(path.join(workspace, "package.json"), JSON.stringify({private: true, type: "module"}));
+  await writeFile(
+    path.join(workspace, "tsconfig.json"),
+    JSON.stringify({
+      compilerOptions: {strict: true, target: "ES2022", module: "ESNext", moduleResolution: "Bundler"},
+      include: ["src/**/*.ts"],
+    }),
+  );
+  const file = path.join(sourceDirectory, "target.ts");
+  await writeFile(file, 'export function lifecycleMemoryTarget(): string { return "memory"; }\n');
+  return {file, workspace};
+}
+
+function blockedOutput(reason) {
+  return {
+    product: PRODUCT.NAME,
+    status: LIFECYCLE_MEMORY_STATUS.BLOCKED,
+    reason,
+    platform: {current: process.platform, supported: [...SUPPORTED_PLATFORM]},
+  };
+}
+
+async function runBenchmark() {
+  const fixture = await createWorkspace();
+  const providerPids = [];
+  const memorySnapshots = [];
+  let stderrBuffer = "";
+  const client = new Client({name: `${PRODUCT.NAME}-lifecycle-memory`, version: "1.0.0"});
+  const transport = new StdioClientTransport({
+    command: process.execPath,
+    args: ["--expose-gc", path.join(pluginRoot, "scripts", "lifecycle-memory-observer.mjs")],
+    cwd: pluginRoot,
+    stderr: "pipe",
+    env: {
+      ...process.env,
+      [ENVIRONMENT_VARIABLE.CLIENT_IDLE_TIMEOUT_MS]: String(BENCHMARK.CLIENT_IDLE_TIMEOUT_MS),
+    },
+  });
+
+  transport.stderr?.on(PROCESS_EVENT.DATA, (chunk) => {
+    stderrBuffer += chunk.toString();
+    const lines = stderrBuffer.split("\n");
+    stderrBuffer = lines.pop() || "";
+    for (const line of lines) {
+      const providerMatch = PROVIDER_START_PATTERN.exec(line);
+      if (providerMatch) providerPids.push(Number(providerMatch[1]));
+      const memoryOffset = line.indexOf(LIFECYCLE_MEMORY_OBSERVER.PREFIX);
+      if (memoryOffset < 0) continue;
+      try {
+        memorySnapshots.push(JSON.parse(line.slice(memoryOffset + LIFECYCLE_MEMORY_OBSERVER.PREFIX.length)));
+      } catch {
+        // A malformed observer line cannot establish memory evidence.
+      }
+    }
+  });
+
+  const cycles = [];
+  try {
+    await client.connect(transport);
+    await waitUntil(() => memorySnapshots.at(-1), "Initial MCP memory snapshot was not observed");
+
+    for (let cycle = 0; cycle < BENCHMARK.CYCLES; cycle += 1) {
+      const response = await client.callTool({
+        name: TOOL.DOCUMENT_SYMBOLS,
+        arguments: {file: fixture.file, root: fixture.workspace},
+      });
+      assert(!response.isError, response.content?.[0]?.text || `${TOOL.DOCUMENT_SYMBOLS} failed`);
+      const providerPid = await waitUntil(() => providerPids[cycle], `Provider was not observed for cycle ${cycle + 1}`);
+      const providerResidentSetBytes = await readResidentSetBytes(providerPid);
+      await waitUntil(() => !processExists(providerPid), `Provider was not disposed for cycle ${cycle + 1}`);
+      const disposedAt = Date.now();
+      const memory = await waitUntil(
+        () => memorySnapshots.findLast((snapshot) => snapshot.recordedAtEpochMilliseconds > disposedAt),
+        `Post-disposal MCP memory was not observed for cycle ${cycle + 1}`,
+      );
+      cycles.push({cycle: cycle + 1, providerResidentSetBytes, providerDisposed: true, mcp: memory});
+    }
+
+    const measured = cycles.slice(BENCHMARK.WARMUP_CYCLES).map((cycle) => cycle.mcp);
+    const heap = assessTrend(measured, LIFECYCLE_MEMORY_FIELD.HEAP_USED_BYTES, {
+      medianMinimumBytes: BENCHMARK.HEAP_MEDIAN_GROWTH_MINIMUM_BYTES,
+      medianRatio: BENCHMARK.HEAP_MEDIAN_GROWTH_RATIO,
+      slopeMinimumBytes: BENCHMARK.HEAP_SLOPE_MINIMUM_BYTES_PER_CYCLE,
+      slopeRatio: BENCHMARK.HEAP_SLOPE_RATIO_PER_CYCLE,
+    });
+    const residentSet = assessTrend(measured, LIFECYCLE_MEMORY_FIELD.RESIDENT_SET_BYTES, {
+      medianMinimumBytes: BENCHMARK.RSS_MEDIAN_GROWTH_MINIMUM_BYTES,
+      medianRatio: BENCHMARK.RSS_MEDIAN_GROWTH_RATIO,
+      slopeMinimumBytes: BENCHMARK.RSS_SLOPE_MINIMUM_BYTES_PER_CYCLE,
+      slopeRatio: BENCHMARK.RSS_SLOPE_RATIO_PER_CYCLE,
+    });
+    const status =
+      heap.status === LIFECYCLE_MEMORY_STATUS.PASS && residentSet.status === LIFECYCLE_MEMORY_STATUS.PASS
+        ? LIFECYCLE_MEMORY_STATUS.PASS
+        : LIFECYCLE_MEMORY_STATUS.FAIL;
+    return {
+      product: PRODUCT.NAME,
+      status,
+      method: {
+        cycles: BENCHMARK.CYCLES,
+        warmupCyclesExcluded: BENCHMARK.WARMUP_CYCLES,
+        comparisonWindowCycles: BENCHMARK.COMPARISON_WINDOW,
+        garbageCollection: LIFECYCLE_MEMORY_METHOD.GARBAGE_COLLECTION,
+        providerMemory: LIFECYCLE_MEMORY_METHOD.PROVIDER_MEMORY,
+        allocatorRetention: LIFECYCLE_MEMORY_METHOD.ALLOCATOR_RETENTION,
+        platform: {current: process.platform, supported: [...SUPPORTED_PLATFORM]},
+      },
+      assessment: {heap, residentSet},
+      summaries: {
+        mcpHeapUsed: summarize(measured.map((sample) => sample.heapUsedBytes)),
+        mcpResidentSet: summarize(measured.map((sample) => sample.residentSetBytes)),
+        mcpAllocatorAndNativeResidentProxy: summarize(measured.map((sample) => sample.allocatorAndNativeResidentProxyBytes)),
+        childProviderResidentSet: summarize(cycles.map((cycle) => cycle.providerResidentSetBytes)),
+      },
+      samples: cycles.map((cycle) => ({
+        cycle: cycle.cycle,
+        providerResidentSetBytes: cycle.providerResidentSetBytes,
+        providerDisposed: cycle.providerDisposed,
+        mcpHeapUsedBytes: cycle.mcp.heapUsedBytes,
+        mcpResidentSetBytes: cycle.mcp.residentSetBytes,
+        mcpAllocatorAndNativeResidentProxyBytes: cycle.mcp.allocatorAndNativeResidentProxyBytes,
+      })),
+    };
+  } finally {
+    await client.close().catch(() => undefined);
+    await rm(fixture.workspace, {recursive: true, force: true});
+  }
+}
+
+assertAssessmentContract();
+let output;
+if (!SUPPORTED_PLATFORM.has(process.platform)) {
+  output = blockedOutput(LIFECYCLE_MEMORY_REASON.PLATFORM_UNSUPPORTED);
+} else {
+  try {
+    await readResidentSetBytes(process.pid);
+  } catch (error) {
+    output = blockedOutput(
+      error?.code === PROCESS_ERROR.COMMAND_NOT_FOUND
+        ? LIFECYCLE_MEMORY_REASON.PROCESS_COMMAND_UNAVAILABLE
+        : LIFECYCLE_MEMORY_REASON.PROCESS_OBSERVATION_UNAVAILABLE,
+    );
+  }
+  if (!output) output = await runBenchmark();
+}
+process.stdout.write(`${JSON.stringify(output, null, 2)}\n`);
+process.exitCode =
+  output.status === LIFECYCLE_MEMORY_STATUS.PASS
+    ? LIFECYCLE_MEMORY_EXIT_CODE.PASS
+    : output.status === LIFECYCLE_MEMORY_STATUS.BLOCKED
+      ? LIFECYCLE_MEMORY_EXIT_CODE.BLOCKED
+      : LIFECYCLE_MEMORY_EXIT_CODE.FAIL;

package/scripts/lifecycle-memory-contract.mjs

@@ -0,0 +1,53 @@
+export const LIFECYCLE_MEMORY_STATUS = Object.freeze({BLOCKED: "blocked", FAIL: "fail", PASS: "pass"});
+
+export const LIFECYCLE_MEMORY_EXIT_CODE = Object.freeze({PASS: 0, FAIL: 1, BLOCKED: 2});
+
+export const LIFECYCLE_MEMORY_REASON = Object.freeze({
+  PLATFORM_UNSUPPORTED: "provider-rss-observation-requires-posix-ps",
+  PROCESS_COMMAND_UNAVAILABLE: "posix-ps-command-unavailable",
+  PROCESS_OBSERVATION_UNAVAILABLE: "provider-rss-observation-unavailable",
+});
+
+export const LIFECYCLE_MEMORY_METHOD = Object.freeze({
+  GARBAGE_COLLECTION: "explicit-before-each-mcp-snapshot",
+  PROVIDER_MEMORY: "posix-ps-rss",
+  ALLOCATOR_RETENTION: "rss-minus-v8-heap-total-proxy-includes-native-memory",
+});
+
+export const LIFECYCLE_MEMORY_FIELD = Object.freeze({
+  HEAP_USED_BYTES: "heapUsedBytes",
+  RESIDENT_SET_BYTES: "residentSetBytes",
+  SYNTHETIC_VALUE: "value",
+});
+
+export const LIFECYCLE_MEMORY_OBSERVER = Object.freeze({
+  INTERVAL_MILLISECONDS: 100,
+  PREFIX: "semantic-js-mcp-memory:",
+});
+
+const MEBIBYTE = 1024 * 1024;
+
+export const LIFECYCLE_MEMORY_BENCHMARK = Object.freeze({
+  CYCLES: 12,
+  WARMUP_CYCLES: 2,
+  COMPARISON_WINDOW: 3,
+  CLIENT_IDLE_TIMEOUT_MS: 300,
+  OBSERVATION_ATTEMPTS: 200,
+  OBSERVATION_INTERVAL_MS: 50,
+  HEAP_MEDIAN_GROWTH_MINIMUM_BYTES: 4 * MEBIBYTE,
+  HEAP_MEDIAN_GROWTH_RATIO: 0.15,
+  HEAP_SLOPE_MINIMUM_BYTES_PER_CYCLE: 256 * 1024,
+  HEAP_SLOPE_RATIO_PER_CYCLE: 0.01,
+  RSS_MEDIAN_GROWTH_MINIMUM_BYTES: 16 * MEBIBYTE,
+  RSS_MEDIAN_GROWTH_RATIO: 0.15,
+  RSS_SLOPE_MINIMUM_BYTES_PER_CYCLE: MEBIBYTE,
+  RSS_SLOPE_RATIO_PER_CYCLE: 0.01,
+  SYNTHETIC_SAMPLE_COUNT: 10,
+  SYNTHETIC_BASE_BYTES: 1_000,
+  SYNTHETIC_STABLE_VARIATION_BYTES: 2,
+  SYNTHETIC_GROWTH_BYTES_PER_CYCLE: 50,
+  SYNTHETIC_MEDIAN_LIMIT_BYTES: 100,
+  SYNTHETIC_SLOPE_LIMIT_BYTES: 10,
+});
+
+export const LIFECYCLE_MEMORY_SUPPORTED_PLATFORMS = Object.freeze(["darwin", "linux"]);

package/scripts/lifecycle-memory-observer.mjs

@@ -0,0 +1,29 @@
+#!/usr/bin/env node
+
+import {LIFECYCLE_MEMORY_OBSERVER} from "./lifecycle-memory-contract.mjs";
+
+if (typeof global.gc !== "function") {
+  throw new Error("Lifecycle memory observation requires Node.js --expose-gc");
+}
+
+function reportMemory() {
+  global.gc();
+  const usage = process.memoryUsage();
+  process.stderr.write(
+    `${LIFECYCLE_MEMORY_OBSERVER.PREFIX}${JSON.stringify({
+      recordedAtEpochMilliseconds: Date.now(),
+      heapUsedBytes: usage.heapUsed,
+      heapTotalBytes: usage.heapTotal,
+      residentSetBytes: usage.rss,
+      externalBytes: usage.external,
+      arrayBufferBytes: usage.arrayBuffers,
+      allocatorAndNativeResidentProxyBytes: Math.max(0, usage.rss - usage.heapTotal),
+    })}\n`,
+  );
+}
+
+const observationTimer = setInterval(reportMemory, LIFECYCLE_MEMORY_OBSERVER.INTERVAL_MILLISECONDS);
+observationTimer.unref();
+reportMemory();
+
+await import("../server.mjs");

package/scripts/lifecycle-smoke.mjs

@@ -0,0 +1,309 @@
+#!/usr/bin/env node
+
+import path from "node:path";
+import {mkdtemp, mkdir, writeFile} from "node:fs/promises";
+import {tmpdir} from "node:os";
+import {fileURLToPath} from "node:url";
+import {Client} from "@modelcontextprotocol/sdk/client/index.js";
+import {StdioClientTransport} from "@modelcontextprotocol/sdk/client/stdio.js";
+import {PendingRequestRegistry} from "../lib/pending-requests.mjs";
+import {removeTemporaryDirectory} from "../lib/temporary-directory.mjs";
+import {ENVIRONMENT_VARIABLE, PRODUCT, TOOL} from "../protocol.mjs";
+
+const CHECK_STATUS = Object.freeze({OK: "ok"});
+const PROCESS_ERROR = Object.freeze({NOT_FOUND: "ESRCH"});
+const PROCESS_EVENT = Object.freeze({DATA: "data"});
+const PROCESS_SIGNAL = Object.freeze({EXISTS: 0, TERMINATE: "SIGTERM"});
+const LIFECYCLE_PHASE = Object.freeze({
+  CONNECT: "connect",
+  IDLE_DISPOSAL: "idle-disposal",
+  LRU_EVICTION: "lru-eviction",
+  PROVIDER_RECOVERY: "provider-recovery",
+  VUE_BRIDGE_RECOVERY: "vue-bridge-recovery",
+});
+const TIMING = Object.freeze({
+  CLIENT_IDLE_TIMEOUT_MS: 300,
+  CLIENT_MINIMUM_EVICTION_AGE_MS: 50,
+  EVICTION_AGE_WAIT_MS: 75,
+  MAXIMUM_ACTIVE_CLIENTS: 1,
+  OBSERVATION_ATTEMPTS: 160,
+  OBSERVATION_INTERVAL_MS: 50,
+  PENDING_SETTLEMENT_TIMEOUT_MS: 1_000,
+  REGISTRY_OBSERVATION_WAIT_MS: 75,
+  REGISTRY_TIMEOUT_MS: 25,
+  REQUEST_START_WAIT_MS: 25,
+});
+const PROVIDER_START_PATTERN = /starting provider (\d+)/;
+const BRIDGE_START_PATTERN = /starting bridge (\d+)/;
+const pluginRoot = path.resolve(path.dirname(fileURLToPath(import.meta.url)), "..");
+
+function assert(condition, message) {
+  if (!condition) throw new Error(message);
+}
+
+const delay = (milliseconds) => new Promise((resolve) => setTimeout(resolve, milliseconds));
+
+async function waitUntil(predicate, message) {
+  for (let attempt = 0; attempt < TIMING.OBSERVATION_ATTEMPTS; attempt += 1) {
+    if (await predicate()) return;
+    await delay(TIMING.OBSERVATION_INTERVAL_MS);
+  }
+  throw new Error(message);
+}
+
+function processExists(pid) {
+  try {
+    process.kill(pid, PROCESS_SIGNAL.EXISTS);
+    return true;
+  } catch (error) {
+    if (error?.code === PROCESS_ERROR.NOT_FOUND) return false;
+    throw error;
+  }
+}
+
+async function createWorkspace(name, functionName) {
+  const workspace = await mkdtemp(path.join(tmpdir(), `semantic-js-mcp-lifecycle-${name}-`));
+  const sourceDirectory = path.join(workspace, "src");
+  await mkdir(sourceDirectory, {recursive: true});
+  await writeFile(path.join(workspace, "package.json"), JSON.stringify({private: true, type: "module"}));
+  await writeFile(
+    path.join(workspace, "tsconfig.json"),
+    JSON.stringify({
+      compilerOptions: {strict: true, target: "ES2022", module: "ESNext", moduleResolution: "Bundler"},
+      include: ["src/**/*.ts"],
+    }),
+  );
+  const file = path.join(sourceDirectory, "target.ts");
+  await writeFile(file, `export function ${functionName}(): string { return "${name}"; }\n`);
+  return {file, functionName, workspace};
+}
+
+async function createVueWorkspace() {
+  const fixture = await createWorkspace("vue", "bridgeLifecycleTarget");
+  const vueFile = path.join(path.dirname(fixture.file), "target.vue");
+  await writeFile(
+    path.join(fixture.workspace, "tsconfig.json"),
+    JSON.stringify({
+      compilerOptions: {strict: true, target: "ES2022", module: "ESNext", moduleResolution: "Bundler"},
+      include: ["src/**/*.vue"],
+    }),
+  );
+  await writeFile(
+    vueFile,
+    [
+      '<script setup lang="ts">',
+      "function bridgeLifecycleTarget(): number { return 1; }",
+      'const unresolvedText = "bridgeLifecycleTarget";',
+      "</script>",
+      "<template>{{ bridgeLifecycleTarget() }} {{ unresolvedText }}</template>",
+    ].join("\n"),
+  );
+  return {...fixture, file: vueFile};
+}
+
+async function assertDocumentSymbol(client, fixture) {
+  const response = await client.callTool({
+    name: TOOL.DOCUMENT_SYMBOLS,
+    arguments: {file: fixture.file, root: fixture.workspace},
+  });
+  assert(!response.isError, response.content?.[0]?.text || `${TOOL.DOCUMENT_SYMBOLS} failed`);
+  assert(
+    response.structuredContent?.result?.symbols?.some((symbol) => symbol.name === fixture.functionName),
+    `Document symbol missing: ${fixture.functionName}`,
+  );
+}
+
+async function callUntilRecovered(client, fixture) {
+  let lastError;
+  for (let attempt = 0; attempt < TIMING.OBSERVATION_ATTEMPTS; attempt += 1) {
+    try {
+      await assertDocumentSymbol(client, fixture);
+      return;
+    } catch (error) {
+      lastError = error;
+      await delay(TIMING.OBSERVATION_INTERVAL_MS);
+    }
+  }
+  throw lastError || new Error("Provider did not recover");
+}
+
+async function auditUntilBridgeRecovered(client, fixture) {
+  let lastError;
+  for (let attempt = 0; attempt < TIMING.OBSERVATION_ATTEMPTS; attempt += 1) {
+    try {
+      const response = await client.callTool({
+        name: TOOL.AUDIT_NAMED_SYMBOL,
+        arguments: {root: fixture.workspace, symbol: fixture.functionName},
+      });
+      if (!response.isError) return;
+      lastError = new Error(response.content?.[0]?.text || `${TOOL.AUDIT_NAMED_SYMBOL} failed after bridge exit`);
+    } catch (error) {
+      lastError = error;
+    }
+    await delay(TIMING.OBSERVATION_INTERVAL_MS);
+  }
+  throw lastError || new Error("Vue tsserver bridge did not recover");
+}
+
+async function settlesWithin(promise, milliseconds) {
+  let timer;
+  const timeout = new Promise((resolve) => {
+    timer = setTimeout(() => resolve(false), milliseconds);
+  });
+  try {
+    return await Promise.race([
+      promise.then(
+        () => true,
+        () => true,
+      ),
+      timeout,
+    ]);
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+async function assertPendingRequestRegistry() {
+  const registry = new PendingRequestRegistry({
+    timeoutMilliseconds: TIMING.REGISTRY_TIMEOUT_MS,
+    timeoutMessage: (operation) => `timed out: ${operation}`,
+  });
+  const timeoutResult = await registry.create("timeout", "timeout-operation").then(
+    () => undefined,
+    (error) => error,
+  );
+  assert(timeoutResult?.message === "timed out: timeout-operation", "Pending request timeout used the wrong error");
+  assert(registry.size === 0, "Timed-out request remained registered");
+
+  const resolved = registry.create("resolved", "resolved-operation");
+  registry.take("resolved")?.resolve("resolved-value");
+  assert((await resolved) === "resolved-value", "Taken request did not resolve");
+  await delay(TIMING.REGISTRY_OBSERVATION_WAIT_MS);
+  assert(registry.size === 0, "Resolved request retained its timeout");
+
+  const rejected = registry.create("rejected", "rejected-operation").then(
+    () => undefined,
+    (error) => error,
+  );
+  const rejection = new Error("provider exited");
+  registry.rejectAll(rejection);
+  assert((await rejected) === rejection, "Bulk rejection did not preserve the provider error");
+  await delay(TIMING.REGISTRY_OBSERVATION_WAIT_MS);
+  assert(registry.size === 0, "Bulk rejection retained pending requests or timers");
+}
+
+const fixtureA = await createWorkspace("a", "lifecycleTargetA");
+const fixtureB = await createWorkspace("b", "lifecycleTargetB");
+const vueFixture = await createVueWorkspace();
+const providerPids = [];
+const bridgePids = [];
+let lifecyclePhase = LIFECYCLE_PHASE.CONNECT;
+let serverStderr = "";
+let stderrLineBuffer = "";
+const client = new Client({name: "semantic-js-mcp-lifecycle-smoke", version: "1.0.0"});
+const transport = new StdioClientTransport({
+  command: process.execPath,
+  args: [path.join(pluginRoot, "server.mjs")],
+  cwd: pluginRoot,
+  stderr: "pipe",
+  env: {
+    ...process.env,
+    [ENVIRONMENT_VARIABLE.CLIENT_IDLE_TIMEOUT_MS]: String(TIMING.CLIENT_IDLE_TIMEOUT_MS),
+    [ENVIRONMENT_VARIABLE.CLIENT_MINIMUM_EVICTION_AGE_MS]: String(TIMING.CLIENT_MINIMUM_EVICTION_AGE_MS),
+    [ENVIRONMENT_VARIABLE.MAXIMUM_ACTIVE_CLIENTS]: String(TIMING.MAXIMUM_ACTIVE_CLIENTS),
+  },
+});
+
+transport.stderr?.on(PROCESS_EVENT.DATA, (chunk) => {
+  const text = chunk.toString();
+  serverStderr += text;
+  stderrLineBuffer += text;
+  const lines = stderrLineBuffer.split("\n");
+  stderrLineBuffer = lines.pop() || "";
+  for (const line of lines) {
+    const match = PROVIDER_START_PATTERN.exec(line);
+    if (match) providerPids.push(Number(match[1]));
+    const bridgeMatch = BRIDGE_START_PATTERN.exec(line);
+    if (bridgeMatch) bridgePids.push(Number(bridgeMatch[1]));
+  }
+});
+
+try {
+  await assertPendingRequestRegistry();
+  await client.connect(transport);
+
+  lifecyclePhase = LIFECYCLE_PHASE.IDLE_DISPOSAL;
+  await assertDocumentSymbol(client, fixtureA);
+  await waitUntil(() => providerPids.length >= 1, "Cold-start provider was not observed");
+  const initialProvider = providerPids[0];
+  await waitUntil(() => !processExists(initialProvider), "Idle provider was not disposed after its TTL");
+
+  await assertDocumentSymbol(client, fixtureA);
+  await waitUntil(() => providerPids.length >= 2, "Provider was not restarted after idle disposal");
+  const replacementAfterIdle = providerPids[1];
+  assert(replacementAfterIdle !== initialProvider, "Idle disposal reused the exited provider process");
+
+  lifecyclePhase = LIFECYCLE_PHASE.LRU_EVICTION;
+  await delay(TIMING.EVICTION_AGE_WAIT_MS);
+  await assertDocumentSymbol(client, fixtureB);
+  await waitUntil(() => providerPids.length >= 3, "Second workspace provider was not observed");
+  await waitUntil(() => !processExists(replacementAfterIdle), "Least-recently-used provider was not evicted at capacity");
+  const providerBeforeExit = providerPids[2];
+
+  lifecyclePhase = LIFECYCLE_PHASE.PROVIDER_RECOVERY;
+  const pendingDiagnostics = client.callTool({
+    name: TOOL.DIAGNOSTICS,
+    arguments: {file: fixtureB.file, root: fixtureB.workspace},
+  });
+  await delay(TIMING.REQUEST_START_WAIT_MS);
+  process.kill(providerBeforeExit, PROCESS_SIGNAL.TERMINATE);
+  await waitUntil(() => !processExists(providerBeforeExit), "Provider did not exit after the test signal");
+  assert(
+    await settlesWithin(pendingDiagnostics, TIMING.PENDING_SETTLEMENT_TIMEOUT_MS),
+    "Pending diagnostics did not settle promptly after provider exit",
+  );
+  await callUntilRecovered(client, fixtureB);
+  await waitUntil(() => providerPids.length >= 4, "Unexpected provider exit did not create a replacement");
+  assert(providerPids[3] !== providerBeforeExit, "Provider recovery reused the exited process");
+
+  lifecyclePhase = LIFECYCLE_PHASE.VUE_BRIDGE_RECOVERY;
+  await delay(TIMING.EVICTION_AGE_WAIT_MS);
+  await assertDocumentSymbol(client, vueFixture);
+  await waitUntil(() => bridgePids.length >= 1, "Vue tsserver bridge was not observed");
+  const bridgeBeforeExit = bridgePids[0];
+  process.kill(bridgeBeforeExit, PROCESS_SIGNAL.TERMINATE);
+  await waitUntil(() => !processExists(bridgeBeforeExit), "Vue tsserver bridge did not exit after the test signal");
+  await auditUntilBridgeRecovered(client, vueFixture);
+  await waitUntil(() => bridgePids.length >= 2, "Vue tsserver bridge exit did not create a replacement");
+  assert(bridgePids[1] !== bridgeBeforeExit, "Vue tsserver bridge recovery reused the exited process");
+
+  process.stdout.write(
+    `${JSON.stringify(
+      {
+        product: PRODUCT.NAME,
+        deterministicRequestTimeout: CHECK_STATUS.OK,
+        coldStart: CHECK_STATUS.OK,
+        idleClientDisposal: CHECK_STATUS.OK,
+        leastRecentlyUsedClientEviction: CHECK_STATUS.OK,
+        pendingWorkSettlement: CHECK_STATUS.OK,
+        providerExitRecovery: CHECK_STATUS.OK,
+        vueTsserverBridgeRecovery: CHECK_STATUS.OK,
+      },
+      null,
+      2,
+    )}\n`,
+  );
+} catch (error) {
+  const recentServerStderr = serverStderr.trim().split("\n").slice(-40).join("\n");
+  throw new Error(
+    `${error instanceof Error ? error.message : String(error)}\nLifecycle phase: ${lifecyclePhase}\nServer stderr:\n${recentServerStderr || "(empty)"}`,
+    {cause: error},
+  );
+} finally {
+  await client.close().catch(() => undefined);
+  await Promise.all([
+    removeTemporaryDirectory(fixtureA.workspace),
+    removeTemporaryDirectory(fixtureB.workspace),
+    removeTemporaryDirectory(vueFixture.workspace),
+  ]);
+}