@ycodium-ai/plugin-browser-workbench 0.2.2706 → 0.2.2743

package/dist/index.js

@@ -87,10 +87,376 @@ import * as NodeFSP5 from "node:fs/promises";
 
 // src/attach.ts
 import * as NodeNet from "node:net";
+
+// src/paths.ts
+import * as NodeCrypto from "node:crypto";
+import * as NodeFSP from "node:fs/promises";
+import * as NodePath from "node:path";
+
+// src/platform.ts
+import * as NodeProcess from "node:process";
+var CLI_PLATFORMS = [
+  "linux-x64",
+  "linux-arm64",
+  "darwin-x64",
+  "darwin-arm64",
+  "win32-x64"
+];
+var CLI_DOWNLOAD_BASE_URL = "https://update.code.visualstudio.com";
+var cliRelativePath = (platform3 = NodeProcess.platform) => platform3 === "win32" ? "bin/code.exe" : "bin/code";
+var cliProgramSelector = (platform3 = NodeProcess.platform) => `data:${cliRelativePath(platform3)}`;
+var detectCliPlatform = (platform3 = NodeProcess.platform, arch3 = NodeProcess.arch) => {
+  if (platform3 === "linux" && arch3 === "x64") return "linux-x64";
+  if (platform3 === "linux" && arch3 === "arm64") return "linux-arm64";
+  if (platform3 === "darwin" && arch3 === "x64") return "darwin-x64";
+  if (platform3 === "darwin" && arch3 === "arm64") return "darwin-arm64";
+  if (platform3 === "win32" && arch3 === "x64") return "win32-x64";
+  return null;
+};
+var cliDownloadUrl = (cliPlatform, version) => `${CLI_DOWNLOAD_BASE_URL}/${version}/cli-${cliPlatform}/stable`;
+var cliArchiveKind = (cliPlatform) => cliPlatform.startsWith("linux") ? "tar.gz" : "zip";
+
+// src/paths.ts
+var workbenchPaths = (dataDir) => ({
+  dataDir,
+  binDir: NodePath.join(dataDir, "bin"),
+  cliPath: NodePath.join(dataDir, cliRelativePath()),
+  cliVerifiedPath: NodePath.join(dataDir, "bin", "cli-verified.json"),
+  cliDataDir: NodePath.join(dataDir, "cli-data"),
+  serverDataDir: NodePath.join(dataDir, "server-data"),
+  tokenPath: NodePath.join(dataDir, "serve-web-token"),
+  instancePath: NodePath.join(dataDir, "instance.json"),
+  licensePath: NodePath.join(dataDir, "license-accepted.json"),
+  configPath: NodePath.join(dataDir, "config.json")
+});
+var writeAtomic = async (filePath, contents, mode) => {
+  await NodeFSP.mkdir(NodePath.dirname(filePath), { recursive: true });
+  const tmp = `${filePath}.${NodeCrypto.randomBytes(8).toString("hex")}.tmp`;
+  const payload = typeof contents === "string" ? contents : Buffer.from(contents);
+  try {
+    await NodeFSP.writeFile(tmp, payload, mode === void 0 ? {} : { mode });
+    await NodeFSP.rename(tmp, filePath);
+    if (mode !== void 0) await NodeFSP.chmod(filePath, mode);
+  } catch (error) {
+    await NodeFSP.unlink(tmp).catch(() => void 0);
+    throw error;
+  }
+};
+var fileExists = async (filePath) => {
+  try {
+    await NodeFSP.access(filePath);
+    return true;
+  } catch {
+    return false;
+  }
+};
+var readJsonFile = async (filePath) => {
+  try {
+    const text = await NodeFSP.readFile(filePath, "utf8");
+    return JSON.parse(text);
+  } catch {
+    return null;
+  }
+};
+var writeJsonFile = async (filePath, value, mode) => {
+  await writeAtomic(filePath, `${JSON.stringify(value)}
+`, mode);
+};
+var removeFile = async (filePath) => {
+  await NodeFSP.unlink(filePath).catch(() => void 0);
+};
+var readInstance = (paths) => readJsonFile(paths.instancePath);
+var writeInstance = (paths, record) => writeJsonFile(paths.instancePath, record);
+var readConfigFile = (paths) => readJsonFile(paths.configPath);
+var writeConfigFile = (paths, value) => writeJsonFile(paths.configPath, value);
+var writeLicenseAccepted = async (paths) => {
+  await writeJsonFile(paths.licensePath, { acceptedAt: (/* @__PURE__ */ new Date()).toISOString() });
+};
+var TOKEN_BYTES = 32;
+var readServeWebToken = async (paths) => {
+  try {
+    const text = (await NodeFSP.readFile(paths.tokenPath, "utf8")).trim();
+    return text.length > 0 ? text : null;
+  } catch {
+    return null;
+  }
+};
+var ensureServeWebToken = async (paths) => {
+  const existing = await readServeWebToken(paths);
+  if (existing !== null) return existing;
+  const token = NodeCrypto.randomBytes(TOKEN_BYTES).toString("base64url");
+  await writeAtomic(paths.tokenPath, `${token}
+`, 384);
+  return token;
+};
+var ensureDataDirs = async (paths) => {
+  await NodeFSP.mkdir(paths.binDir, { recursive: true });
+  await NodeFSP.mkdir(paths.cliDataDir, { recursive: true });
+  await NodeFSP.mkdir(paths.serverDataDir, { recursive: true });
+};
+var directorySize = async (dir) => {
+  let total = 0;
+  const walk = async (current) => {
+    let entries;
+    try {
+      entries = await NodeFSP.readdir(current, { withFileTypes: true });
+    } catch {
+      return;
+    }
+    for (const entry of entries) {
+      const child = NodePath.join(current, entry.name);
+      if (entry.isDirectory()) {
+        await walk(child);
+        continue;
+      }
+      try {
+        total += (await NodeFSP.stat(child)).size;
+      } catch {
+      }
+    }
+  };
+  await walk(dir);
+  return total;
+};
+
+// src/types.ts
+var WORKBENCH_PROGRESS_STAGES = [
+  "license",
+  "check-cli",
+  "download-cli",
+  "start-server",
+  "download-server",
+  "register-port"
+];
+var WORKBENCH_PROGRESS_STATUSES = [
+  "started",
+  "progress",
+  "output",
+  "succeeded",
+  "skipped",
+  "failed"
+];
+var WORKBENCH_FAILURE_KINDS = [
+  "license-required",
+  "download-failed",
+  "disk-full",
+  "launch-failed",
+  "port-in-use",
+  "server-download-failed",
+  "grant-expired",
+  "host-key-mismatch",
+  "channel-failed",
+  "unknown"
+];
+var WorkbenchFailure = class extends Error {
+  code;
+  constructor(code, message) {
+    super(message);
+    this.name = "WorkbenchFailure";
+    this.code = code;
+  }
+};
+
+// src/util.ts
+var messageOf = (error) => error instanceof Error ? error.message : String(error);
+var isDiskFull = (error) => {
+  if (typeof error !== "object" || error === null || !("code" in error)) return false;
+  return error.code === "ENOSPC";
+};
+var parsePort = (value) => {
+  const asNumber = (input) => Number.isInteger(input) && input >= 1 && input <= 65535 ? input : null;
+  if (typeof value === "number") return asNumber(value);
+  if (typeof value === "string" && value.trim() !== "") {
+    const parsed = Number(value);
+    return Number.isFinite(parsed) ? asNumber(parsed) : null;
+  }
+  return null;
+};
+var redactWorkbenchSecrets = (line) => line.replaceAll(/([?&]tkn=)[^&\s]+/gi, "$1<redacted>");
+var sleep = (ms, signal) => new Promise((resolve, reject) => {
+  if (signal?.aborted) {
+    reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
+    return;
+  }
+  const timer = setTimeout(() => {
+    signal?.removeEventListener("abort", onAbort);
+    resolve();
+  }, ms);
+  const onAbort = () => {
+    clearTimeout(timer);
+    reject(signal?.reason instanceof Error ? signal.reason : new Error("aborted"));
+  };
+  signal?.addEventListener("abort", onAbort, { once: true });
+});
+
+// src/serveWeb.ts
+var START_SERVER_TIMEOUT_MS = 3e4;
+var DOWNLOAD_SERVER_TIMEOUT_MS = 10 * 6e4;
+var DOWNLOAD_SERVER_POLL_MS = 1e3;
+var WEB_UI_AVAILABLE_PATTERN = /Web UI available at http:\/\/127\.0\.0\.1:(\d+)/;
+var SERVER_DOWNLOADING_PATTERN = /Downloading server\b/;
+var SERVER_STARTING_PATTERN = /Starting server\b/;
+var parseWebUiPort = (line) => {
+  const match = WEB_UI_AVAILABLE_PATTERN.exec(line);
+  if (match === null) return null;
+  const port = Number(match[1]);
+  return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : null;
+};
+var isServerLogLine = (line) => SERVER_DOWNLOADING_PATTERN.test(line) || SERVER_STARTING_PATTERN.test(line);
+var serveWebArgs = (paths) => [
+  "serve-web",
+  "--host",
+  "127.0.0.1",
+  "--port",
+  "0",
+  "--connection-token-file",
+  paths.tokenPath,
+  "--accept-server-license-terms",
+  "--server-data-dir",
+  paths.serverDataDir,
+  "--cli-data-dir",
+  paths.cliDataDir,
+  "--disable-telemetry"
+];
+var splitLines = (text) => {
+  const parts = text.split(/\r?\n/);
+  const rest = parts.pop() ?? "";
+  return { complete: parts, rest };
+};
+var consumeProcessLines = (stream, onLine) => {
+  const decoder = new TextDecoder();
+  let pending = "";
+  const run = async () => {
+    for await (const chunk of stream) {
+      pending += decoder.decode(chunk, { stream: true });
+      const split = splitLines(pending);
+      pending = split.rest;
+      for (const line of split.complete) onLine(redactWorkbenchSecrets(line));
+    }
+    pending += decoder.decode();
+    if (pending.length > 0) onLine(redactWorkbenchSecrets(pending));
+  };
+  return run();
+};
+var waitForServeWebPort = (input) => {
+  const timeoutMs = input.timeoutMs ?? START_SERVER_TIMEOUT_MS;
+  const stderrChunks = [];
+  let settled = false;
+  let resolvePort = () => void 0;
+  let rejectPort = () => void 0;
+  const portPromise = new Promise((resolve, reject) => {
+    resolvePort = resolve;
+    rejectPort = reject;
+  });
+  const finishError = (error) => {
+    if (settled) return;
+    settled = true;
+    rejectPort(error);
+  };
+  const finishPort = (port) => {
+    if (settled) return;
+    settled = true;
+    resolvePort(port);
+  };
+  const timer = setTimeout(() => {
+    finishError(
+      new WorkbenchFailure(
+        "launch-failed",
+        "The VS Code CLI started but did not publish a local address in time."
+      )
+    );
+  }, timeoutMs);
+  void consumeProcessLines(input.handle.stdout, (line) => {
+    input.onStdoutLine(line);
+    const port = parseWebUiPort(line);
+    if (port !== null) finishPort(port);
+  }).catch((error) => {
+    finishError(error instanceof Error ? error : new Error(String(error)));
+  });
+  void consumeProcessLines(input.handle.stderr, (line) => {
+    stderrChunks.push(line);
+    input.onStderrLine(line);
+  }).catch(() => void 0);
+  void input.handle.exited.then((code) => {
+    if (settled) return;
+    const tail = stderrChunks.slice(-20).join("\n");
+    finishError(
+      new WorkbenchFailure(
+        "launch-failed",
+        tail.length > 0 ? `The VS Code CLI exited before it published a local address.
+${tail}` : `The VS Code CLI exited before it published a local address (code ${String(code)}).`
+      )
+    );
+  });
+  return portPromise.then(
+    (port) => {
+      clearTimeout(timer);
+      return { port, stderr: stderrChunks.join("\n") };
+    },
+    (error) => {
+      clearTimeout(timer);
+      throw error;
+    }
+  );
+};
+var serverReadyStatus = (status) => {
+  if (status === 202) return "downloading";
+  if (status === 200 || status === 301 || status === 302 || status === 307 || status === 308) {
+    return "ready";
+  }
+  if (status === 403) return "forbidden";
+  return "other";
+};
+var waitForServerDownload = async (input) => {
+  const timeoutMs = input.timeoutMs ?? DOWNLOAD_SERVER_TIMEOUT_MS;
+  const pollMs = input.pollMs ?? DOWNLOAD_SERVER_POLL_MS;
+  const startedAtMs = Date.now();
+  const deadline = startedAtMs + timeoutMs;
+  const url = `http://127.0.0.1:${String(input.port)}/?tkn=${input.token}`;
+  const serveWebDir = `${input.cliDataDir}/serve-web`;
+  while (Date.now() < deadline) {
+    if (input.signal?.aborted) {
+      throw new WorkbenchFailure("server-download-failed", "The server download was cancelled.");
+    }
+    try {
+      const response = await input.http(
+        url,
+        input.signal === void 0 ? { redirect: "manual" } : { redirect: "manual", signal: input.signal }
+      );
+      const kind = serverReadyStatus(response.status);
+      if (kind === "ready") return;
+      if (kind === "forbidden") {
+        throw new WorkbenchFailure(
+          "server-download-failed",
+          "The VS Code server rejected the connection token."
+        );
+      }
+    } catch (error) {
+      if (error instanceof WorkbenchFailure) throw error;
+    }
+    const transferredBytes = await directorySize(serveWebDir);
+    input.onTransfer(
+      computeTransfer({
+        transferredBytes,
+        totalBytes: null,
+        startedAtMs,
+        nowMs: Date.now()
+      })
+    );
+    await sleep(pollMs, input.signal);
+  }
+  throw new WorkbenchFailure(
+    "server-download-failed",
+    "The VS Code server did not become ready in time."
+  );
+};
+
+// src/attach.ts
 var ATTACH_PROBE_TIMEOUT_MS = 1e3;
 var probeLoopback = (port, timeoutMs = ATTACH_PROBE_TIMEOUT_MS) => new Promise((resolve) => {
   const socket = NodeNet.connect({ host: "127.0.0.1", port });
   const finish = (ok) => {
+    clearTimeout(timer);
     socket.removeAllListeners();
     socket.destroy();
     resolve(ok);
@@ -105,6 +471,31 @@ var probeLoopback = (port, timeoutMs = ATTACH_PROBE_TIMEOUT_MS) => new Promise((
     finish(false);
   });
 });
+var OWNERSHIP_PROBE_TIMEOUT_MS = 1e3;
+var probeServeWebOwnership = async (input) => {
+  const http = input.http ?? fetch;
+  const timeoutMs = input.timeoutMs ?? OWNERSHIP_PROBE_TIMEOUT_MS;
+  const ask = async (tkn) => {
+    try {
+      const response = await http(`http://127.0.0.1:${String(input.port)}/?tkn=${tkn}`, {
+        redirect: "manual",
+        signal: AbortSignal.timeout(timeoutMs)
+      });
+      return serverReadyStatus(response.status);
+    } catch {
+      return "down";
+    }
+  };
+  const [withToken, withWrong] = await Promise.all([ask(input.token), ask("not-the-token")]);
+  if (withWrong === "forbidden" && (withToken === "ready" || withToken === "downloading")) {
+    return "ours";
+  }
+  if (withWrong === "downloading" && (withToken === "downloading" || withToken === "ready")) {
+    return "pending";
+  }
+  if (withWrong === "ready") return "foreign";
+  return "unknown";
+};
 
 // src/catalog.ts
 var catalog = {
@@ -125,12 +516,16 @@ var catalog = {
   },
   running: {
     stopFirst: "Stop the workbench before updating the CLI."
+  },
+  adopt: {
+    notOurs: "The workbench server found from the last run does not accept this machine's token, so Ycodium let go of it. Open again to start a fresh one."
   }
 };
 var failureMessage = (kind) => catalog.failure[kind];
 var attachNoListenerMessage = (port) => catalog.attach.noListener.replace("{{port}}", String(port));
 
 // src/cli.ts
+import * as NodeCrypto2 from "node:crypto";
 import * as NodeFS from "node:fs";
 import * as NodeFSP2 from "node:fs/promises";
 import * as NodeProcess2 from "node:process";
@@ -139,46 +534,6 @@ import * as NodeStreamPromises from "node:stream/promises";
 
 // src/archive.ts
 import * as NodeZlib from "node:zlib";
-
-// src/types.ts
-var WORKBENCH_PROGRESS_STAGES = [
-  "license",
-  "check-cli",
-  "download-cli",
-  "start-server",
-  "download-server",
-  "register-port"
-];
-var WORKBENCH_PROGRESS_STATUSES = [
-  "started",
-  "progress",
-  "output",
-  "succeeded",
-  "skipped",
-  "failed"
-];
-var WORKBENCH_FAILURE_KINDS = [
-  "license-required",
-  "download-failed",
-  "disk-full",
-  "launch-failed",
-  "port-in-use",
-  "server-download-failed",
-  "grant-expired",
-  "host-key-mismatch",
-  "channel-failed",
-  "unknown"
-];
-var WorkbenchFailure = class extends Error {
-  code;
-  constructor(code, message) {
-    super(message);
-    this.name = "WorkbenchFailure";
-    this.code = code;
-  }
-};
-
-// src/archive.ts
 var TAR_BLOCK = 512;
 var ZIP_LOCAL = 67324752;
 var ZIP_CENTRAL = 33639248;
@@ -299,166 +654,15 @@ var extractCliBinary = async (archive, kind) => {
   return pickCliBinary(await extractZip(archive));
 };
 
-// src/platform.ts
-import * as NodeProcess from "node:process";
-var CLI_DOWNLOAD_BASE_URL = "https://update.code.visualstudio.com/latest";
-var cliRelativePath = (platform3 = NodeProcess.platform) => platform3 === "win32" ? "bin/code.exe" : "bin/code";
-var cliProgramSelector = (platform3 = NodeProcess.platform) => `data:${cliRelativePath(platform3)}`;
-var detectCliPlatform = (platform3 = NodeProcess.platform, arch3 = NodeProcess.arch) => {
-  if (platform3 === "linux" && arch3 === "x64") return "linux-x64";
-  if (platform3 === "linux" && arch3 === "arm64") return "linux-arm64";
-  if (platform3 === "darwin" && arch3 === "x64") return "darwin-x64";
-  if (platform3 === "darwin" && arch3 === "arm64") return "darwin-arm64";
-  if (platform3 === "win32" && arch3 === "x64") return "win32-x64";
-  return null;
-};
-var cliDownloadUrl = (cliPlatform) => `${CLI_DOWNLOAD_BASE_URL}/cli-${cliPlatform}/stable`;
-var cliArchiveKind = (cliPlatform) => cliPlatform.startsWith("win32") ? "zip" : "tar.gz";
-
-// src/paths.ts
-import * as NodeCrypto from "node:crypto";
-import * as NodeFSP from "node:fs/promises";
-import * as NodePath from "node:path";
-var workbenchPaths = (dataDir) => ({
-  dataDir,
-  binDir: NodePath.join(dataDir, "bin"),
-  cliPath: NodePath.join(dataDir, cliRelativePath()),
-  cliDataDir: NodePath.join(dataDir, "cli-data"),
-  serverDataDir: NodePath.join(dataDir, "server-data"),
-  tokenPath: NodePath.join(dataDir, "serve-web-token"),
-  instancePath: NodePath.join(dataDir, "instance.json"),
-  licensePath: NodePath.join(dataDir, "license-accepted.json"),
-  configPath: NodePath.join(dataDir, "config.json")
-});
-var writeAtomic = async (filePath, contents, mode) => {
-  await NodeFSP.mkdir(NodePath.dirname(filePath), { recursive: true });
-  const tmp = `${filePath}.${NodeCrypto.randomBytes(8).toString("hex")}.tmp`;
-  const payload = typeof contents === "string" ? contents : Buffer.from(contents);
-  try {
-    await NodeFSP.writeFile(tmp, payload, mode === void 0 ? {} : { mode });
-    await NodeFSP.rename(tmp, filePath);
-    if (mode !== void 0) await NodeFSP.chmod(filePath, mode);
-  } catch (error) {
-    await NodeFSP.unlink(tmp).catch(() => void 0);
-    throw error;
-  }
-};
-var fileExists = async (filePath) => {
-  try {
-    await NodeFSP.access(filePath);
-    return true;
-  } catch {
-    return false;
-  }
-};
-var readJsonFile = async (filePath) => {
-  try {
-    const text = await NodeFSP.readFile(filePath, "utf8");
-    return JSON.parse(text);
-  } catch {
-    return null;
-  }
-};
-var writeJsonFile = async (filePath, value, mode) => {
-  await writeAtomic(filePath, `${JSON.stringify(value)}
-`, mode);
-};
-var removeFile = async (filePath) => {
-  await NodeFSP.unlink(filePath).catch(() => void 0);
-};
-var readInstance = (paths) => readJsonFile(paths.instancePath);
-var writeInstance = (paths, record) => writeJsonFile(paths.instancePath, record);
-var readConfigFile = (paths) => readJsonFile(paths.configPath);
-var writeConfigFile = (paths, value) => writeJsonFile(paths.configPath, value);
-var writeLicenseAccepted = async (paths) => {
-  await writeJsonFile(paths.licensePath, { acceptedAt: (/* @__PURE__ */ new Date()).toISOString() });
-};
-var TOKEN_BYTES = 32;
-var readServeWebToken = async (paths) => {
-  try {
-    const text = (await NodeFSP.readFile(paths.tokenPath, "utf8")).trim();
-    return text.length > 0 ? text : null;
-  } catch {
-    return null;
-  }
-};
-var ensureServeWebToken = async (paths) => {
-  const existing = await readServeWebToken(paths);
-  if (existing !== null) return existing;
-  const token = NodeCrypto.randomBytes(TOKEN_BYTES).toString("base64url");
-  await writeAtomic(paths.tokenPath, `${token}
-`, 384);
-  return token;
-};
-var ensureDataDirs = async (paths) => {
-  await NodeFSP.mkdir(paths.binDir, { recursive: true });
-  await NodeFSP.mkdir(paths.cliDataDir, { recursive: true });
-  await NodeFSP.mkdir(paths.serverDataDir, { recursive: true });
-};
-var directorySize = async (dir) => {
-  let total = 0;
-  const walk = async (current) => {
-    let entries;
-    try {
-      entries = await NodeFSP.readdir(current, { withFileTypes: true });
-    } catch {
-      return;
-    }
-    for (const entry of entries) {
-      const child = NodePath.join(current, entry.name);
-      if (entry.isDirectory()) {
-        await walk(child);
-        continue;
-      }
-      try {
-        total += (await NodeFSP.stat(child)).size;
-      } catch {
-      }
-    }
-  };
-  await walk(dir);
-  return total;
-};
-
-// src/util.ts
-var messageOf = (error) => error instanceof Error ? error.message : String(error);
-var isDiskFull = (error) => {
-  if (typeof error !== "object" || error === null || !("code" in error)) return false;
-  return error.code === "ENOSPC";
-};
-var parsePort = (value) => {
-  const asNumber = (input) => Number.isInteger(input) && input >= 1 && input <= 65535 ? input : null;
-  if (typeof value === "number") return asNumber(value);
-  if (typeof value === "string" && value.trim() !== "") {
-    const parsed = Number(value);
-    return Number.isFinite(parsed) ? asNumber(parsed) : null;
-  }
-  return null;
-};
-var redactWorkbenchSecrets = (line) => line.replaceAll(/([?&]tkn=)[^&\s]+/gi, "$1<redacted>");
-var isProcessAlive = (pid) => {
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
+// src/cliRelease.ts
+var PINNED_CLI_VERSION = "1.139.1";
+var PINNED_CLI_SHA256 = {
+  "linux-x64": "e079ddb70377cca515ab0cf5ca1ee4095a14e1f510af4b10a75b01c6018f9f02",
+  "linux-arm64": "5bc80c3622a628a8aee4be15967bdc7a039235d867c3d1bedf1b373d2d731dc7",
+  "darwin-x64": "7b8f895cf37909814aa3f1b71aa01fa58a468a71d1267098c1346bae3c8ac25e",
+  "darwin-arm64": "43ec2f4506beafde0783134de0b4b5fb94fd0e017d47a7b4ee6559b8bc363dea",
+  "win32-x64": "046b75c3e8ddad7692e05e20c0f8cab87ecfa66ec2fc92d55cc4e32044b522bf"
 };
-var sleep = (ms, signal) => new Promise((resolve, reject) => {
-  if (signal?.aborted) {
-    reject(signal.reason instanceof Error ? signal.reason : new Error("aborted"));
-    return;
-  }
-  const timer = setTimeout(() => {
-    signal?.removeEventListener("abort", onAbort);
-    resolve();
-  }, ms);
-  const onAbort = () => {
-    clearTimeout(timer);
-    reject(signal?.reason instanceof Error ? signal.reason : new Error("aborted"));
-  };
-  signal?.addEventListener("abort", onAbort, { once: true });
-});
 
 // src/cli.ts
 var CLI_DOWNLOAD_SUFFIX = ".download";
@@ -468,7 +672,6 @@ var parseCliVersion = (stdout) => {
   const version = match?.[1];
   return version === void 0 || version.length === 0 ? null : version;
 };
-var cliIsInstalled = (paths) => fileExists(paths.cliPath);
 var readInstalledCliVersion = async (processApi) => {
   const result = await processApi.run({
     program: cliProgramSelector(),
@@ -480,24 +683,65 @@ var readInstalledCliVersion = async (processApi) => {
   }
   return parseCliVersion(result.stdout) ?? parseCliVersion(result.stderr) ?? "unknown";
 };
+var sha256Hex = (bytes) => NodeCrypto2.createHash("sha256").update(bytes).digest("hex");
+var fileSha256 = async (filePath) => {
+  const hash = NodeCrypto2.createHash("sha256");
+  await NodeStreamPromises.pipeline(NodeFS.createReadStream(filePath), hash);
+  return hash.digest("hex");
+};
+var isVerifiedCliInstall = (value) => {
+  if (typeof value !== "object" || value === null) return false;
+  const record = value;
+  return typeof record["version"] === "string" && typeof record["archiveSha256"] === "string" && typeof record["binarySha256"] === "string" && CLI_PLATFORMS.some((platform3) => platform3 === record["platform"]);
+};
+var readVerifiedCli = async (paths, options) => {
+  const platform3 = options.platform === void 0 ? detectCliPlatform() : options.platform;
+  const record = await readJsonFile(paths.cliVerifiedPath);
+  if (!isVerifiedCliInstall(record)) return null;
+  if (record.version !== PINNED_CLI_VERSION || record.platform !== platform3) return null;
+  if (!await fileExists(paths.cliPath)) return null;
+  if (!options.checkBinary) return record;
+  const actual = await fileSha256(paths.cliPath).catch(() => null);
+  return actual === record.binarySha256 ? record : null;
+};
+var writeVerifiedCli = (paths, install) => writeJsonFile(paths.cliVerifiedPath, install);
+var clearVerifiedCli = (paths) => removeFile(paths.cliVerifiedPath);
 var contentLengthOf = (response) => {
   const raw = response.headers.get("content-length");
   if (raw === null || raw.trim() === "") return null;
   const parsed = Number(raw);
   return Number.isFinite(parsed) && parsed >= 0 ? parsed : null;
 };
+var hostOf = (url) => {
+  try {
+    return new URL(url).host;
+  } catch {
+    return url;
+  }
+};
+var describeNetworkError = (error) => {
+  const message = messageOf(error);
+  if (typeof error !== "object" || error === null || !("cause" in error)) return message;
+  const cause = error.cause;
+  if (typeof cause !== "object" || cause === null) return message;
+  const code = cause.code;
+  const causeMessage = messageOf(cause);
+  return `${message}: ${typeof code === "string" && !causeMessage.includes(code) ? `${code} ` : ""}${causeMessage}`;
+};
 var streamResponseToFile = async (input) => {
   if (input.response.body === null) {
     throw new WorkbenchFailure("download-failed", "The CLI download had no body.");
   }
   const totalBytes = contentLengthOf(input.response);
   const startedAtMs = Date.now();
+  const hash = NodeCrypto2.createHash("sha256");
   let transferredBytes = 0;
   const readable = NodeStream.Readable.fromWeb(
     input.response.body
   );
   readable.on("data", (chunk) => {
     transferredBytes += chunk.length;
+    hash.update(chunk);
     input.onTransfer(
       computeTransfer({
         transferredBytes,
@@ -514,8 +758,13 @@ var streamResponseToFile = async (input) => {
     if (isDiskFull(error)) {
       throw new WorkbenchFailure("disk-full", messageOf(error));
     }
-    throw error;
+    const of = totalBytes === null ? "" : ` of ${String(totalBytes)}`;
+    throw new WorkbenchFailure(
+      "download-failed",
+      `The VS Code CLI download stopped after ${String(transferredBytes)}${of} bytes (${describeNetworkError(error)}).`
+    );
   }
+  return hash.digest("hex");
 };
 var downloadCliBinary = async (input) => {
   const platform3 = input.platform === void 0 ? detectCliPlatform() : input.platform;
@@ -525,31 +774,44 @@ var downloadCliBinary = async (input) => {
       `This machine's platform (${NodeProcess2.platform}/${NodeProcess2.arch}) has no VS Code CLI build.`
     );
   }
-  const url = input.url ?? cliDownloadUrl(platform3);
+  const version = PINNED_CLI_VERSION;
+  const expectedSha256 = input.expectedSha256 ?? PINNED_CLI_SHA256[platform3];
+  const url = input.url ?? cliDownloadUrl(platform3, version);
   let response;
   try {
     response = await input.http(url, input.signal === void 0 ? {} : { signal: input.signal });
   } catch (error) {
     if (isDiskFull(error)) throw new WorkbenchFailure("disk-full", messageOf(error));
-    throw new WorkbenchFailure("download-failed", messageOf(error));
+    throw new WorkbenchFailure(
+      "download-failed",
+      `Could not reach ${hostOf(url)} to download VS Code CLI ${version} (${describeNetworkError(error)}). Check this machine's internet access and proxy settings.`
+    );
   }
   if (!response.ok) {
+    const host = hostOf(response.url === "" ? url : response.url);
     throw new WorkbenchFailure(
       "download-failed",
-      `The CLI download returned HTTP ${String(response.status)}.`
+      `${host} answered HTTP ${String(response.status)} for VS Code CLI ${version}. If this machine reaches the internet through a proxy or firewall, check that it allows ${host}.`
     );
   }
   await NodeFSP2.mkdir(input.paths.binDir, { recursive: true });
   const archivePath = `${input.destPath}${CLI_DOWNLOAD_SUFFIX}`;
   try {
-    await streamResponseToFile({
+    const archiveSha256 = await streamResponseToFile({
       response,
       filePath: archivePath,
       onTransfer: input.onTransfer
     });
+    if (archiveSha256 !== expectedSha256) {
+      throw new WorkbenchFailure(
+        "download-failed",
+        `The downloaded VS Code CLI ${version} (${platform3}) did not match its published SHA-256 (expected ${expectedSha256.slice(0, 12)}\u2026, got ${archiveSha256.slice(0, 12)}\u2026) and was discarded. If this machine uses a proxy, make sure it does not alter downloads.`
+      );
+    }
     const archive = await NodeFSP2.readFile(archivePath);
     const binary = await extractCliBinary(archive, cliArchiveKind(platform3));
     await writeAtomic(input.destPath, binary, 493);
+    return { version, platform: platform3, archiveSha256, binarySha256: sha256Hex(binary) };
   } catch (error) {
     if (error instanceof WorkbenchFailure) throw error;
     if (isDiskFull(error)) throw new WorkbenchFailure("disk-full", messageOf(error));
@@ -559,180 +821,31 @@ var downloadCliBinary = async (input) => {
   }
 };
 
-// src/serveWeb.ts
-var START_SERVER_TIMEOUT_MS = 3e4;
-var DOWNLOAD_SERVER_TIMEOUT_MS = 10 * 6e4;
-var DOWNLOAD_SERVER_POLL_MS = 1e3;
-var WEB_UI_AVAILABLE_PATTERN = /Web UI available at http:\/\/127\.0\.0\.1:(\d+)/;
-var SERVER_DOWNLOADING_PATTERN = /Downloading server\b/;
-var SERVER_STARTING_PATTERN = /Starting server\b/;
-var parseWebUiPort = (line) => {
-  const match = WEB_UI_AVAILABLE_PATTERN.exec(line);
-  if (match === null) return null;
-  const port = Number(match[1]);
-  return Number.isInteger(port) && port >= 1 && port <= 65535 ? port : null;
-};
-var isServerLogLine = (line) => SERVER_DOWNLOADING_PATTERN.test(line) || SERVER_STARTING_PATTERN.test(line);
-var serveWebArgs = (paths) => [
-  "serve-web",
-  "--host",
-  "127.0.0.1",
-  "--port",
-  "0",
-  "--connection-token-file",
-  paths.tokenPath,
-  "--accept-server-license-terms",
-  "--server-data-dir",
-  paths.serverDataDir,
-  "--cli-data-dir",
-  paths.cliDataDir,
-  "--disable-telemetry"
-];
-var splitLines = (text) => {
-  const parts = text.split(/\r?\n/);
-  const rest = parts.pop() ?? "";
-  return { complete: parts, rest };
-};
-var consumeProcessLines = (stream, onLine) => {
-  const decoder = new TextDecoder();
-  let pending = "";
-  const run = async () => {
-    for await (const chunk of stream) {
-      pending += decoder.decode(chunk, { stream: true });
-      const split = splitLines(pending);
-      pending = split.rest;
-      for (const line of split.complete) onLine(redactWorkbenchSecrets(line));
-    }
-    pending += decoder.decode();
-    if (pending.length > 0) onLine(redactWorkbenchSecrets(pending));
-  };
-  return run();
-};
-var waitForServeWebPort = (input) => {
-  const timeoutMs = input.timeoutMs ?? START_SERVER_TIMEOUT_MS;
-  const stderrChunks = [];
-  let settled = false;
-  let resolvePort = () => void 0;
-  let rejectPort = () => void 0;
-  const portPromise = new Promise((resolve, reject) => {
-    resolvePort = resolve;
-    rejectPort = reject;
-  });
-  const finishError = (error) => {
-    if (settled) return;
-    settled = true;
-    rejectPort(error);
-  };
-  const finishPort = (port) => {
-    if (settled) return;
-    settled = true;
-    resolvePort(port);
-  };
-  const timer = setTimeout(() => {
-    finishError(
-      new WorkbenchFailure(
-        "launch-failed",
-        "The VS Code CLI started but did not publish a local address in time."
-      )
-    );
-  }, timeoutMs);
-  void consumeProcessLines(input.handle.stdout, (line) => {
-    input.onStdoutLine(line);
-    const port = parseWebUiPort(line);
-    if (port !== null) finishPort(port);
-  }).catch((error) => {
-    finishError(error instanceof Error ? error : new Error(String(error)));
-  });
-  void consumeProcessLines(input.handle.stderr, (line) => {
-    stderrChunks.push(line);
-    input.onStderrLine(line);
-  }).catch(() => void 0);
-  void input.handle.exited.then((code) => {
-    if (settled) return;
-    const tail = stderrChunks.slice(-20).join("\n");
-    finishError(
-      new WorkbenchFailure(
-        "launch-failed",
-        tail.length > 0 ? `The VS Code CLI exited before it published a local address.
-${tail}` : `The VS Code CLI exited before it published a local address (code ${String(code)}).`
-      )
-    );
-  });
-  return portPromise.then(
-    (port) => {
-      clearTimeout(timer);
-      return { port, stderr: stderrChunks.join("\n") };
-    },
-    (error) => {
-      clearTimeout(timer);
-      throw error;
-    }
-  );
-};
-var serverReadyStatus = (status) => {
-  if (status === 202) return "downloading";
-  if (status === 200 || status === 301 || status === 302 || status === 307 || status === 308) {
-    return "ready";
-  }
-  if (status === 403) return "forbidden";
-  return "other";
-};
-var waitForServerDownload = async (input) => {
-  const timeoutMs = input.timeoutMs ?? DOWNLOAD_SERVER_TIMEOUT_MS;
-  const pollMs = input.pollMs ?? DOWNLOAD_SERVER_POLL_MS;
-  const startedAtMs = Date.now();
-  const deadline = startedAtMs + timeoutMs;
-  const url = `http://127.0.0.1:${String(input.port)}/?tkn=${input.token}`;
-  const serveWebDir = `${input.cliDataDir}/serve-web`;
-  while (Date.now() < deadline) {
-    if (input.signal?.aborted) {
-      throw new WorkbenchFailure("server-download-failed", "The server download was cancelled.");
-    }
-    try {
-      const response = await input.http(
-        url,
-        input.signal === void 0 ? { redirect: "manual" } : { redirect: "manual", signal: input.signal }
-      );
-      const kind = serverReadyStatus(response.status);
-      if (kind === "ready") return;
-      if (kind === "forbidden") {
-        throw new WorkbenchFailure(
-          "server-download-failed",
-          "The VS Code server rejected the connection token."
-        );
-      }
-    } catch (error) {
-      if (error instanceof WorkbenchFailure) throw error;
-    }
-    const transferredBytes = await directorySize(serveWebDir);
-    input.onTransfer(
-      computeTransfer({
-        transferredBytes,
-        totalBytes: null,
-        startedAtMs,
-        nowMs: Date.now()
-      })
-    );
-    await sleep(pollMs, input.signal);
-  }
-  throw new WorkbenchFailure(
-    "server-download-failed",
-    "The VS Code server did not become ready in time."
-  );
-};
-
 // src/instance.ts
-var instanceIsLive = async (record) => isProcessAlive(record.pid) && await probeLoopback(record.port);
-var reapOrphanInstance = async (paths) => {
+var classifyRecord = async (record, paths) => {
+  const token = await readServeWebToken(paths);
+  if (token === null) return "stale";
+  const ownership = await probeServeWebOwnership({ port: record.port, token });
+  if (ownership !== "unknown") return ownership;
+  return await probeLoopback(record.port) ? "unresponsive" : "stale";
+};
+var reconcileInstanceRecord = async (paths, log) => {
   const record = await readInstance(paths);
   if (record === null) return;
-  if (isProcessAlive(record.pid)) {
-    try {
-      process.kill(record.pid, "SIGTERM");
-    } catch {
-    }
+  const state = await classifyRecord(record, paths);
+  if (state === "foreign" || state === "stale") {
+    log?.info("dropping a recorded workbench instance that is not ours or not listening", {
+      port: record.port,
+      state
+    });
+    await removeFile(paths.instancePath);
+    return;
+  }
+  if (state === "unresponsive") {
+    log?.info("recorded workbench port is listening but does not answer yet; keeping its record", {
+      port: record.port
+    });
   }
-  await removeFile(paths.instancePath);
 };
 var startServeWeb = async (input) => {
   await ensureDataDirs(input.paths);
@@ -759,26 +872,23 @@ var startServeWeb = async (input) => {
       startedAt: (/* @__PURE__ */ new Date()).toISOString()
     };
     await writeInstance(input.paths, record);
-    return { handle, record };
+    return { owned: true, handle, record };
   } catch (error) {
     await handle.kill("SIGTERM").catch(() => void 0);
     throw error;
   }
 };
 var STOP_GRACE_MS = 5e3;
-var stopManagedProcess = async (managed, paths) => {
-  if (managed !== null) {
-    await managed.handle.kill("SIGTERM").catch(() => void 0);
-    const timedOut = await Promise.race([
-      managed.handle.exited.then(() => false).catch(() => false),
-      sleep(STOP_GRACE_MS).then(() => true)
-    ]);
-    if (timedOut) {
-      await managed.handle.kill("SIGKILL").catch(() => void 0);
-      await managed.handle.exited.catch(() => void 0);
-    }
+var stopOwnedHandle = async (handle) => {
+  await handle.kill("SIGTERM").catch(() => void 0);
+  const timedOut = await Promise.race([
+    handle.exited.then(() => false).catch(() => false),
+    sleep(STOP_GRACE_MS).then(() => true)
+  ]);
+  if (timedOut) {
+    await handle.kill("SIGKILL").catch(() => void 0);
+    await handle.exited.catch(() => void 0);
   }
-  await removeFile(paths.instancePath);
 };
 
 // src/productPatch.ts
@@ -900,6 +1010,8 @@ var windowTitleTemplate = (machineLabel) => {
 // src/runtime.ts
 var MANAGED_LABEL = "VS Code";
 var EXTERNAL_LABEL = "code-server";
+var UNRESPONSIVE_GRACE_MS = START_SERVER_TIMEOUT_MS;
+var UNRESPONSIVE_POLL_MS = 1e3;
 var WorkbenchRuntime = class {
   bus = new ProgressBus();
   ctx;
@@ -910,13 +1022,15 @@ var WorkbenchRuntime = class {
   externalPort = null;
   externalListenPort = null;
   outputStage = "start-server";
-  constructor(ctx) {
+  unresponsiveGraceMs;
+  constructor(ctx, options = {}) {
     this.ctx = ctx;
+    this.unresponsiveGraceMs = options.unresponsiveGraceMs ?? UNRESPONSIVE_GRACE_MS;
     this.paths = workbenchPaths(ctx.paths.dataDir);
   }
-  /** 激活时收孤儿、按设置接外接端口。不能让 activate 失败。 */
+  /** 激活时收拾实例记录（不对任何进程发信号）、按设置接外接端口。不能让 activate 失败。 */
   async start() {
-    await reapOrphanInstance(this.paths);
+    await reconcileInstanceRecord(this.paths, this.ctx.log);
     const desired = await this.desiredExternalPort();
     if (desired === null) return;
     try {
@@ -930,7 +1044,7 @@ var WorkbenchRuntime = class {
   }
   async dispose() {
     await this.enqueue(async () => {
-      await this.stopManaged();
+      await this.stopManaged("keep");
       await this.clearExternal();
     });
   }
@@ -941,10 +1055,7 @@ var WorkbenchRuntime = class {
     return this.enqueue(() => this.inRun(() => this.runOpen(payload)));
   }
   stop() {
-    return this.enqueue(async () => {
-      await this.stopManaged();
-      return {};
-    });
+    return this.enqueue(() => this.stopManaged("stop"));
   }
   update() {
     return this.enqueue(() => this.inRun(() => this.runUpdate()));
@@ -1000,7 +1111,8 @@ var WorkbenchRuntime = class {
     return parsePort(file?.attachPort);
   }
   async readStatus() {
-    const installed = await cliIsInstalled(this.paths);
+    const verified = await readVerifiedCli(this.paths, { checkBinary: false });
+    const installed = verified !== null;
     const live = await this.managedIsLive();
     const external = this.externalPort !== null && this.externalListenPort !== null ? { port: this.externalListenPort, portId: this.externalPort.portId } : void 0;
     if (live && this.managed !== null) {
@@ -1022,30 +1134,27 @@ var WorkbenchRuntime = class {
         external
       };
     }
-    let cliVersion;
-    if (installed) {
-      try {
-        cliVersion = await readInstalledCliVersion(this.ctx.process);
-      } catch {
-        cliVersion = void 0;
-      }
-    }
     return {
       mode: "none",
       installed,
       running: false,
-      ...cliVersion === void 0 ? {} : { cliVersion }
+      ...verified === null ? {} : { cliVersion: verified.version }
     };
   }
+  /**
+   * 工作台算在跑：端口上的服务只收我们的令牌（ours），或还在下载、令牌对错都回 202（pending）。
+   * 没有句柄时只按 ours 领养，pending 不足以证明是我们的，留给 Open 等下载完再复判。
+   * 这里不改任何状态：一轮 503/超时、或下载阶段的 202，都不能抹掉本次 spawn 的句柄。
+   */
   async managedIsLive() {
     if (this.managed !== null) {
-      if (await instanceIsLive(this.managed.record)) return true;
-      this.managed = null;
-      return false;
+      const state = await classifyRecord(this.managed.record, this.paths);
+      return state === "ours" || state === "pending";
     }
     const record = await readInstance(this.paths);
-    if (record === null) return false;
-    return instanceIsLive(record);
+    if (record === null || await classifyRecord(record, this.paths) !== "ours") return false;
+    this.managed = { owned: false, record };
+    return true;
   }
   async runOpen(payload) {
     const desiredExternal = await this.desiredExternalPort();
@@ -1110,7 +1219,7 @@ var WorkbenchRuntime = class {
     }
     if (!patched) return;
     this.ctx.log.info("restarting the workbench server to apply the patched product.json");
-    await this.stopManaged();
+    await this.stopManaged("keep");
     await this.stepStartServer(cliVersion);
     await this.stepDownloadServer(token);
   }
@@ -1124,31 +1233,44 @@ var WorkbenchRuntime = class {
     await writeLicenseAccepted(this.paths);
     this.stage("license", "succeeded");
   }
+  /**
+   * 只复用校验记录与二进制都对得上钉死版本的 CLI。旧版插件装的（没有记录）、版本不同的、
+   * 装好后被换掉的，一律重下钉死的版本，不运行它。
+   */
   async stepCheckAndDownloadCli() {
     this.stage("check-cli", "started");
-    if (await fileExists(this.paths.cliPath)) {
-      try {
-        const version = await readInstalledCliVersion(this.ctx.process);
-        this.stage("check-cli", "succeeded", { detail: version });
-        this.stage("download-cli", "skipped", { skipReason: "already-installed" });
-        return version;
-      } catch (error) {
-        this.fail("check-cli", "unknown", messageOf(error));
-      }
+    const verified = await readVerifiedCli(this.paths, { checkBinary: true });
+    if (verified !== null) {
+      this.stage("check-cli", "succeeded", { detail: verified.version });
+      this.stage("download-cli", "skipped", { skipReason: "already-installed" });
+      return verified.version;
     }
-    this.stage("check-cli", "succeeded");
+    this.stage(
+      "check-cli",
+      "succeeded",
+      await fileExists(this.paths.cliPath) ? {
+        detail: `The VS Code CLI on this machine is not the verified ${PINNED_CLI_VERSION} build; downloading that build to replace it.`
+      } : {}
+    );
     return this.stepDownloadCli(this.paths.cliPath);
   }
-  async stepDownloadCli(destPath) {
+  /** 下载、校验并装上钉死的版本：`stagingPath` 与 `cliPath` 不同时校验通过后才改名换上。 */
+  async stepDownloadCli(stagingPath) {
     this.stage("download-cli", "started");
     try {
-      await downloadCliBinary({
+      await clearVerifiedCli(this.paths);
+      const install = await downloadCliBinary({
         http: this.ctx.http,
         paths: this.paths,
-        destPath,
+        destPath: stagingPath,
         onTransfer: (transfer) => this.stage("download-cli", "progress", { transfer })
       });
+      if (stagingPath !== this.paths.cliPath) await NodeFSP5.rename(stagingPath, this.paths.cliPath);
+      await writeVerifiedCli(this.paths, install);
     } catch (error) {
+      if (stagingPath !== this.paths.cliPath) {
+        await NodeFSP5.unlink(stagingPath).catch(() => void 0);
+      }
       this.rethrowAs(error, "download-cli");
     }
     try {
@@ -1162,15 +1284,14 @@ var WorkbenchRuntime = class {
   async stepStartServer(cliVersion) {
     this.stage("start-server", "started");
     this.outputStage = "start-server";
-    if (this.managed !== null && await instanceIsLive(this.managed.record)) {
-      this.stage("start-server", "skipped", { skipReason: "already-running" });
-      return;
-    }
-    const record = await readInstance(this.paths);
-    if (record !== null && await instanceIsLive(record)) {
-      this.managed = { handle: orphanHandle(record.pid), record };
-      this.stage("start-server", "skipped", { skipReason: "already-running" });
-      return;
+    const record = this.managed?.record ?? await readInstance(this.paths);
+    if (record !== null) {
+      const state = await this.settleRecord(record);
+      if (state !== "forgotten") {
+        if (this.managed === null) this.managed = { owned: false, record };
+        this.stage("start-server", "skipped", { skipReason: "already-running" });
+        return;
+      }
     }
     try {
       this.managed = await startServeWeb({
@@ -1189,6 +1310,39 @@ var WorkbenchRuntime = class {
       detail: `127.0.0.1:${String(started.record.port)}`
     });
   }
+  /**
+   * 判定一条记录能不能接管。ours / pending 原样返回；foreign / stale 与等满时限仍答不出的
+   * 记录一律忘掉（删记录；若是本次自己 spawn 的实例，先停它自己的句柄），返回 "forgotten"。
+   * 不依赖记录里的 pid，也不对任何别的进程发信号。
+   */
+  async settleRecord(record) {
+    let state = await classifyRecord(record, this.paths);
+    if (state === "unresponsive") {
+      this.stage("start-server", "output", {
+        detail: "Waiting for the previous workbench server to answer..."
+      });
+      const deadline = Date.now() + this.unresponsiveGraceMs;
+      const pollMs = Math.min(UNRESPONSIVE_POLL_MS, Math.max(1, this.unresponsiveGraceMs / 4));
+      while (state === "unresponsive" && Date.now() < deadline) {
+        await sleep(pollMs);
+        state = await classifyRecord(record, this.paths);
+      }
+    }
+    if (state === "ours" || state === "pending") return state;
+    await this.forgetRecord(record, state);
+    return "forgotten";
+  }
+  async forgetRecord(record, state) {
+    this.ctx.log.warn("forgetting a recorded workbench instance", { port: record.port, state });
+    if (this.managedPort !== null) {
+      await this.managedPort.unregister().catch(() => void 0);
+      this.managedPort = null;
+    }
+    const managed = this.managed;
+    this.managed = null;
+    if (managed?.owned === true) await stopOwnedHandle(managed.handle);
+    await removeFile(this.paths.instancePath);
+  }
   onProcessLine(line) {
     if (line.trim().length === 0) return;
     const stage = isServerLogLine(line) ? "download-server" : this.outputStage;
@@ -1208,8 +1362,19 @@ var WorkbenchRuntime = class {
         onTransfer: (transfer) => this.stage("download-server", "progress", { transfer })
       });
     } catch (error) {
+      if (!managed.owned) {
+        const state = await classifyRecord(managed.record, this.paths);
+        if (state !== "ours" && state !== "pending") await this.forgetRecord(managed.record, state);
+      }
       this.rethrowAs(error, "download-server", "server-download-failed");
     }
+    if (!managed.owned) {
+      const state = await classifyRecord(managed.record, this.paths);
+      if (state !== "ours") {
+        await this.forgetRecord(managed.record, state);
+        this.fail("download-server", "unknown", catalog.adopt.notOurs);
+      }
+    }
     this.stage("download-server", "succeeded");
   }
   async stepRegisterManaged() {
@@ -1234,27 +1399,20 @@ var WorkbenchRuntime = class {
     this.stage("register-port", "succeeded");
     return this.managedPort.portId;
   }
+  /**
+   * 「更新」装的是插件钉死的版本，不是官方最新版：已装且校验通过就什么都不下；
+   * 否则下到 `bin/code.new`，校验通过后才换上，失败时原来的二进制不动。
+   */
   async runUpdate() {
     if (await this.managedIsLive()) {
       throw new WorkbenchFailure("unknown", catalog.running.stopFirst);
     }
-    this.stage("download-cli", "started");
-    const destPath = `${this.paths.cliPath}${CLI_NEW_SUFFIX}`;
-    try {
-      await downloadCliBinary({
-        http: this.ctx.http,
-        paths: this.paths,
-        destPath,
-        onTransfer: (transfer) => this.stage("download-cli", "progress", { transfer })
-      });
-      await NodeFSP5.rename(destPath, this.paths.cliPath);
-    } catch (error) {
-      await NodeFSP5.unlink(destPath).catch(() => void 0);
-      this.rethrowAs(error, "download-cli");
+    const verified = await readVerifiedCli(this.paths, { checkBinary: true });
+    if (verified !== null) {
+      this.stage("download-cli", "skipped", { skipReason: "already-installed" });
+      return { cliVersion: verified.version };
     }
-    this.stage("download-cli", "succeeded");
-    const version = await readInstalledCliVersion(this.ctx.process);
-    return { cliVersion: version };
+    return { cliVersion: await this.stepDownloadCli(`${this.paths.cliPath}${CLI_NEW_SUFFIX}`) };
   }
   async attachPort(port) {
     if (!await probeLoopback(port)) {
@@ -1278,21 +1436,32 @@ var WorkbenchRuntime = class {
     this.externalPort = null;
     this.externalListenPort = null;
   }
-  async stopManaged() {
+  /**
+   * 停托管实例。只停本次运行自己 spawn 的句柄；记录里的 pid 不对它发信号：跨过一次重启
+   * 它可能已被系统重用，令牌验的是端口上的服务，不是那个 pid。
+   * - "keep"（插件停用、补丁后的内部重启）：保留仍在服务的记录，下次激活或紧接着的
+   *   start-server 可以接上；
+   * - "stop"（用户 Stop）：句柄停完后记录仍在，说明端口上有个无法证明能安全停的服务
+   *   （领养来的，或孙进程脱离了句柄）。放弃接管：删记录、状态不再显示在跑，把端口报给
+   *   调用方。否则 Stop 停不掉、Update 又要求先 Stop，形成单向门。
+   */
+  async stopManaged(mode) {
     if (this.managedPort !== null) {
       await this.managedPort.unregister().catch(() => void 0);
       this.managedPort = null;
     }
-    await stopManagedProcess(this.managed, this.paths);
+    const managed = this.managed;
     this.managed = null;
-    const leftover = await readInstance(this.paths);
-    if (leftover !== null && isProcessAlive(leftover.pid)) {
-      try {
-        process.kill(leftover.pid, "SIGTERM");
-      } catch {
-      }
-    }
+    if (managed?.owned === true) await stopOwnedHandle(managed.handle);
+    await reconcileInstanceRecord(this.paths, this.ctx.log);
+    if (mode === "keep") return {};
+    const record = await readInstance(this.paths);
+    if (record === null) return {};
     await removeFile(this.paths.instancePath);
+    this.ctx.log.warn("released a workbench server it cannot stop; it may still be running", {
+      port: record.port
+    });
+    return { released: { port: record.port } };
   }
   rethrowAs(error, stage, fallback = "download-failed") {
     if (error instanceof WorkbenchFailure) {
@@ -1306,19 +1475,6 @@ var capabilityReason = (error) => {
   const reason = error.reason;
   return typeof reason === "string" ? reason : null;
 };
-var orphanHandle = (pid) => ({
-  pid,
-  stdout: emptyBytes(),
-  stderr: emptyBytes(),
-  writeStdin: async () => void 0,
-  closeStdin: async () => void 0,
-  kill: async (signal) => {
-    if (isProcessAlive(pid)) process.kill(pid, signal ?? "SIGTERM");
-  },
-  exited: Promise.resolve(null)
-});
-async function* emptyBytes() {
-}
 
 // src/schemas.ts
 var emptyObject = {
@@ -1389,6 +1545,20 @@ var statusResultSchema = {
     }
   }
 };
+var stopResultSchema = {
+  type: "object",
+  additionalProperties: false,
+  properties: {
+    released: {
+      type: "object",
+      additionalProperties: false,
+      required: ["port"],
+      properties: {
+        port: { type: "integer", minimum: 1, maximum: 65535 }
+      }
+    }
+  }
+};
 var updateResultSchema = {
   type: "object",
   additionalProperties: false,
@@ -1433,7 +1603,7 @@ var progressItemSchema = {
 // src/index.ts
 var index_default = definePlugin({
   id: "browser-workbench",
-  apiVersion: 2,
+  apiVersion: 3,
   activate: (ctx) => {
     const runtime = new WorkbenchRuntime(ctx);
     void runtime.start().catch((error) => {
@@ -1489,10 +1659,10 @@ var index_default = definePlugin({
     });
     ctx.command({
       name: "stop",
-      description: "Stop the managed VS Code CLI and unregister its port.",
+      description: "Stop the managed VS Code CLI and unregister its port. A server this run did not start is released, not killed; the result then carries its port.",
       scope: "operate",
       payloadSchema: emptyPayloadSchema,
-      resultSchema: emptyResultSchema,
+      resultSchema: stopResultSchema,
       handle: () => runtime.stop()
     });
     ctx.command({