@automaton-labs/aib 0.0.5 → 0.0.7

package/dist/managed-host/serve-web-host.cjs

@@ -1,602 +1,720 @@
-#!/usr/bin/env node
-
-const crypto = require("node:crypto");
-const fs = require("node:fs");
-const net = require("node:net");
-const os = require("node:os");
-const path = require("node:path");
-const { spawn, spawnSync } = require("node:child_process");
-const {
-  defaultFixtureDir,
-  defaultVsixPath,
-  prepareSpawnCommand,
-  readRegistryEntries,
-  resolveIdeCommand,
-  rootDir,
-  run,
-  sleep,
-  timestampForPath,
-  writeJson
-} = require("../ide-launch/common.cjs");
-
-const managedRootDir = path.join(os.tmpdir(), "aib", "managed-hosts");
-const defaultRunsDir = path.join(rootDir, ".tmp", "managed-host-runs");
-
-function normalizeForId(value) {
-  return path.resolve(String(value)).replace(/[\\/]+$/, "").toLowerCase();
-}
-
-function normalizeForCompare(value) {
-  return path.normalize(String(value)).replace(/[\\/]+$/, "").toLowerCase();
-}
-
-function hashShort(value) {
-  return crypto.createHash("sha1").update(value).digest("hex").slice(0, 16);
-}
-
-function fingerprintFile(filePath) {
-  if (!filePath || !fs.existsSync(filePath)) {
-    return null;
-  }
-
-  const stat = fs.statSync(filePath);
-  const hash = crypto.createHash("sha1").update(fs.readFileSync(filePath)).digest("hex");
-  return {
-    path: path.resolve(filePath),
-    hash,
-    shortHash: hash.slice(0, 12),
-    size: stat.size,
-    mtimeMs: stat.mtimeMs
-  };
-}
-
-function fingerprintsMatch(left, right) {
-  if (!left || !right) {
-    return false;
-  }
-
-  return left.hash === right.hash && left.size === right.size;
-}
-
-function buildHostId(options) {
-  const hostKind = options.hostKind ?? "vscode-serve-web";
-  return `${hostKind}-${hashShort(normalizeForId(options.fixture ?? defaultFixtureDir))}`;
-}
-
-function getHostDir(hostId) {
-  return path.join(managedRootDir, hostId);
-}
-
-function getMetadataPath(hostId) {
-  return path.join(getHostDir(hostId), "metadata.json");
-}
-
-function getWatchdogPath(hostId) {
-  return path.join(getHostDir(hostId), "watchdog.json");
-}
-
-function getLockDir(hostId) {
-  return path.join(getHostDir(hostId), "lock");
-}
-
-function ensureDir(dirPath) {
-  fs.mkdirSync(dirPath, { recursive: true });
-}
-
-function writeText(filePath, value) {
-  ensureDir(path.dirname(filePath));
-  fs.writeFileSync(filePath, value);
-}
-
-function appendText(filePath, value) {
-  ensureDir(path.dirname(filePath));
-  fs.appendFileSync(filePath, value);
-}
-
-function writeJsonAtomic(filePath, payload) {
-  ensureDir(path.dirname(filePath));
-  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
-  try {
-    fs.writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`);
-    fs.renameSync(tempPath, filePath);
-  } catch (error) {
-    try {
-      fs.rmSync(tempPath, { force: true });
-    } catch {
-      // Best-effort cleanup only.
-    }
-    throw error;
-  }
-}
-
-function tail(text, maxLength = 4000) {
-  return text.length > maxLength ? text.slice(text.length - maxLength) : text;
-}
-
-function readTextIfExists(filePath) {
-  try {
-    return fs.readFileSync(filePath, "utf8");
-  } catch {
-    return "";
-  }
-}
-
-function readRecentLogText(root, maxFiles = 12, maxLength = 4000) {
-  if (!fs.existsSync(root)) {
-    return "";
-  }
-  const files = [];
-  collectFiles(root, files, 5);
-  return files
-    .filter((filePath) => filePath.endsWith(".log") || filePath.endsWith(".txt"))
-    .sort((left, right) => {
-      const leftTime = fs.statSync(left).mtimeMs;
-      const rightTime = fs.statSync(right).mtimeMs;
-      return rightTime - leftTime;
-    })
-    .slice(0, maxFiles)
-    .map((filePath) => readTextIfExists(filePath))
-    .join("\n")
-    .slice(-maxLength);
-}
-
-function collectFiles(root, files, maxDepth) {
-  if (maxDepth < 0) {
-    return;
-  }
-  let entries;
-  try {
-    entries = fs.readdirSync(root, { withFileTypes: true });
-  } catch {
-    return;
-  }
-  for (const entry of entries) {
-    const entryPath = path.join(root, entry.name);
-    if (entry.isFile()) {
-      files.push(entryPath);
-    } else if (entry.isDirectory()) {
-      collectFiles(entryPath, files, maxDepth - 1);
-    }
-  }
-}
-
-function isProcessAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) {
-    return false;
-  }
-
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-function workspaceMatchesFixture(entry, fixture) {
-  const expected = normalizeForCompare(fixture);
-  return (entry.workspaceFolders ?? []).some(
-    (workspaceFolder) => normalizeForCompare(workspaceFolder) === expected
-  );
-}
-
-function resolveChromePath(explicitPath) {
-  const candidates = [
-    explicitPath,
-    findPackagedBrowserRuntime(),
-    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
-    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
-    "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe",
-    "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
-    "google-chrome",
-    "google-chrome-stable",
-    "chromium",
-    "chromium-browser",
-    "microsoft-edge"
-  ].filter(Boolean);
-
-  return candidates.find((candidate) => commandOrFileExists(candidate)) ?? null;
-}
-
-function findPackagedBrowserRuntime() {
-  const roots = [
-    path.join(rootDir, "runtimes", "browser"),
-    path.join(rootDir, "runtimes", "chrome"),
-    path.join(rootDir, "runtimes", "chromium")
-  ];
-  const executableNames = process.platform === "win32"
-    ? new Set(["chrome.exe", "chromium.exe", "msedge.exe"])
-    : new Set(["chrome", "chromium"]);
-  for (const runtimeRoot of roots) {
-    const found = findFirstExecutable(runtimeRoot, executableNames, 5);
-    if (found) {
-      return found;
-    }
-  }
-  return null;
-}
-
-function findFirstExecutable(root, executableNames, maxDepth) {
-  if (!fs.existsSync(root) || maxDepth < 0) {
-    return null;
-  }
-  let entries;
-  try {
-    entries = fs.readdirSync(root, { withFileTypes: true });
-  } catch {
-    return null;
-  }
-  for (const entry of entries) {
-    const entryPath = path.join(root, entry.name);
-    if (entry.isFile() && executableNames.has(entry.name) && commandOrFileExists(entryPath)) {
-      return entryPath;
-    }
-  }
-  for (const entry of entries) {
-    if (!entry.isDirectory()) {
-      continue;
-    }
-    const found = findFirstExecutable(path.join(root, entry.name), executableNames, maxDepth - 1);
-    if (found) {
-      return found;
-    }
-  }
-  return null;
-}
-
-function commandOrFileExists(candidate) {
-  if (candidate.includes("\\") || candidate.includes("/") || /^[A-Za-z]:/.test(candidate)) {
-    return fs.existsSync(candidate);
-  }
-
-  const escaped = String(candidate).replace(/"/g, '\\"');
-  const result = process.platform === "win32"
-    ? spawnSync("where.exe", [candidate], { encoding: "utf8", windowsHide: true, stdio: ["ignore", "pipe", "pipe"] })
-    : spawnSync("sh", ["-lc", `command -v "${escaped}"`], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
-  return result.status === 0;
-}
-
-function ideCommandEnv() {
-  return {
-    ...process.env,
-    DONT_PROMPT_WSL_INSTALL: process.env.DONT_PROMPT_WSL_INSTALL ?? "1"
-  };
-}
-
-function makeCommandSpec(command, prefixArgs = [], source = "command") {
-  return {
-    command,
-    prefixArgs,
-    source,
-    displayCommand: [command, ...prefixArgs].join(" ")
-  };
-}
-
-function resolvePackagedNodeRuntime() {
-  const envNodePath = process.env.AIB_NODE_PATH;
-  if (envNodePath && commandOrFileExists(envNodePath)) {
-    return { command: path.resolve(envNodePath), source: "env-node" };
-  }
-
-  const platformDir = nodeRuntimePlatformDir();
-  if (!platformDir) {
-    return { command: process.execPath, source: "process-node" };
-  }
-
-  const candidateRoots = [
-    path.join(rootDir, "runtimes", "node", platformDir),
-    path.join(rootDir, "packages", "cli", "runtimes", "node", platformDir)
-  ];
-  for (const candidateRoot of candidateRoots) {
-    const candidate = process.platform === "win32"
-      ? path.join(candidateRoot, "node.exe")
-      : path.join(candidateRoot, "bin", "node");
-    if (fs.existsSync(candidate)) {
-      return { command: candidate, source: "packaged-node" };
-    }
-  }
-
-  return { command: process.execPath, source: "process-node" };
-}
-
-function nodeRuntimePlatformDir() {
-  const arch = process.arch;
-  if (process.platform === "win32" && arch === "x64") {
-    return "win-x64";
-  }
-  if (process.platform === "linux" && arch === "x64") {
-    return "linux-x64";
-  }
-  if (process.platform === "linux" && arch === "arm64") {
-    return "linux-arm64";
-  }
-  if (process.platform === "darwin" && arch === "x64") {
-    return "darwin-x64";
-  }
-  if (process.platform === "darwin" && arch === "arm64") {
-    return "darwin-arm64";
-  }
-  return null;
-}
-
-function commandDisplayName(commandSpec) {
-  return typeof commandSpec === "string" ? commandSpec : commandSpec.displayCommand;
-}
-
-function commandExecutable(commandSpec) {
-  return typeof commandSpec === "string" ? commandSpec : commandSpec.command;
-}
-
-function commandArgs(commandSpec, args) {
-  return typeof commandSpec === "string" ? args : [...commandSpec.prefixArgs, ...args];
-}
-
-function runCommand(commandSpec, args, options = {}) {
-  return run(commandExecutable(commandSpec), commandArgs(commandSpec, args), options);
-}
-
-function startLoggedCommand(commandSpec, args, options) {
-  return startLoggedProcess(commandExecutable(commandSpec), commandArgs(commandSpec, args), options);
-}
-
-function resolvePackagedCodeServerCommand() {
-  const nodeRuntime = resolvePackagedNodeRuntime();
-  const entryPaths = [
-    path.join(rootDir, "runtimes", "code-server", "node_modules", "code-server", "out", "node", "entry.js"),
-    path.join(rootDir, "packages", "cli", "runtimes", "code-server", "node_modules", "code-server", "out", "node", "entry.js")
-  ];
-  for (const entryPath of entryPaths) {
-    if (fs.existsSync(entryPath)) {
-      return makeCommandSpec(nodeRuntime.command, [entryPath], nodeRuntime.source === "packaged-node"
-        ? "packaged-code-server-entry-bundled-node"
-        : "packaged-code-server-entry");
-    }
-  }
-  return null;
-}
-
-function resolveManagedHostKind(options, commandSpec) {
-  const raw = options.hostKind ?? process.env.AIB_MANAGED_HOST_KIND ?? "";
-  if (raw) {
-    if (raw !== "vscode-serve-web" && raw !== "code-server") {
-      throw new Error("Expected managed host kind to be vscode-serve-web or code-server.");
-    }
-    return raw;
-  }
-
-  const command = commandDisplayName(commandSpec);
-  const commandName = path.basename(String(command)).toLowerCase();
-  return commandName === "code-server"
-    || commandName === "code-server.cmd"
-    || command.endsWith(path.join("code-server", "out", "node", "entry.js"))
-    ? "code-server"
-    : "vscode-serve-web";
-}
-
-function resolveManagedIdeCommand(options) {
-  if (options.ideCommand) {
-    return makeCommandSpec(options.ideCommand, [], "explicit");
-  }
-
-  const rawHostKind = options.hostKind ?? process.env.AIB_MANAGED_HOST_KIND ?? "";
-  if (rawHostKind === "code-server") {
-    if (process.env.AIB_CODE_SERVER_PATH && commandOrFileExists(process.env.AIB_CODE_SERVER_PATH)) {
-      return makeCommandSpec(process.env.AIB_CODE_SERVER_PATH, [], "env-code-server");
-    }
-    const packagedCommand = resolvePackagedCodeServerCommand();
-    if (packagedCommand) {
-      return packagedCommand;
-    }
-    const candidates = [
-      path.join(rootDir, "runtimes", "code-server", "bin", process.platform === "win32" ? "code-server.cmd" : "code-server"),
-      path.join(rootDir, "runtimes", "code-server", "bin", "code-server"),
-      path.join(rootDir, "packages", "cli", "runtimes", "code-server", "bin", process.platform === "win32" ? "code-server.cmd" : "code-server"),
-      path.join(rootDir, "packages", "cli", "runtimes", "code-server", "bin", "code-server"),
-      "code-server"
-    ].filter(Boolean);
-    const found = candidates.find((candidate) => commandOrFileExists(candidate)) ?? "code-server";
-    return makeCommandSpec(found, [], "code-server-path");
-  }
-
-  return makeCommandSpec(resolveIdeCommand({ ide: "code" }), [], "vscode-code");
-}
-
-function buildIdeCommandEnv(runDir) {
-  const env = ideCommandEnv();
-  if (process.platform !== "win32") {
-    const homeDir = path.join(runDir, "home");
-    env.HOME = homeDir;
-    env.VSCODE_CLI_DATA_DIR = path.join(runDir, "cli-data");
-  }
-  return env;
-}
-
-function readJsonFile(filePath) {
-  try {
-    return JSON.parse(fs.readFileSync(filePath, "utf8"));
-  } catch {
-    return null;
-  }
-}
-
-function readMetadataByHostId(hostId) {
-  const metadataPath = getMetadataPath(hostId);
-  const metadata = fs.existsSync(metadataPath) ? readJsonFile(metadataPath) : null;
-  if (!metadata || typeof metadata !== "object") {
-    return null;
-  }
-  return metadata;
-}
-
-function readAllManagedHostEntries() {
-  if (!fs.existsSync(managedRootDir)) {
-    return [];
-  }
-  const entries = [];
-  for (const item of fs.readdirSync(managedRootDir, { withFileTypes: true })) {
-    if (!item.isDirectory()) {
-      continue;
-    }
-    const metadata = readMetadataByHostId(item.name);
-    if (!metadata) {
-      continue;
-    }
-    entries.push({
-      hostId: item.name,
-      metadata
-    });
-  }
-  return entries.sort((left, right) => String(left.hostId).localeCompare(String(right.hostId)));
-}
-
-function compactRuntimeStatus(status, metadata = {}) {
-  return {
-    hostId: status.hostId ?? metadata.hostId ?? null,
-    hostKind: status.hostKind ?? metadata.hostKind ?? null,
-    running: status.running === true,
-    healthy: status.healthy === true,
-    fixture: metadata.fixture ?? status.metadata?.fixture ?? null,
-    runDir: metadata.runDir ?? status.metadata?.runDir ?? null,
-    rootUrl: metadata.rootUrl ?? status.metadata?.rootUrl ?? null,
-    reason: status.reason ?? null
-  };
-}
-
-function writeMetadata(hostId, metadata) {
-  writeJsonAtomic(getMetadataPath(hostId), metadata);
-}
-
-function removeMetadata(hostId) {
-  fs.rmSync(getMetadataPath(hostId), { force: true });
-}
-
-function quoteCmdArg(value) {
-  const raw = String(value);
-  return `"${raw.replace(/%/g, "%%").replace(/"/g, '\\"')}"`;
-}
-
-function quotePowerShellString(value) {
-  return `'${String(value).replace(/'/g, "''")}'`;
-}
-
-function writeWindowsDetachedScript(command, args, options) {
-  ensureDir(path.dirname(options.stdoutPath));
-  ensureDir(path.dirname(options.stderrPath));
-  const scriptPath = `${options.stdoutPath}.cmd`;
-  const cwd = options.cwd ?? rootDir;
-  const commandLine = [
-    quoteCmdArg(command),
-    ...args.map(quoteCmdArg),
-    ">",
-    quoteCmdArg(options.stdoutPath),
-    "2>",
-    quoteCmdArg(options.stderrPath)
-  ].join(" ");
-  writeText(scriptPath, [
-    "@echo off",
-    `cd /d ${quoteCmdArg(cwd)}`,
-    commandLine,
-    ""
-  ].join("\r\n"));
-  return scriptPath;
-}
-
-function startWindowsHiddenScript(scriptPath, options) {
-  const cwd = options.cwd ?? rootDir;
-  const command = [
-    "$p = Start-Process -FilePath 'cmd.exe'",
-    `-ArgumentList @('/d','/s','/c', ${quotePowerShellString(scriptPath)})`,
-    `-WorkingDirectory ${quotePowerShellString(cwd)}`,
-    "-WindowStyle Hidden -PassThru;",
-    "$p.Id"
-  ].join(" ");
-  const result = spawnSync("powershell.exe", [
-    "-NoProfile",
-    "-ExecutionPolicy",
-    "Bypass",
-    "-WindowStyle",
-    "Hidden",
-    "-Command",
-    command
-  ], {
-    cwd,
-    env: options.env ?? process.env,
-    encoding: "utf8",
-    windowsHide: true,
-    stdio: ["ignore", "pipe", "pipe"]
-  });
-  if (result.status !== 0) {
-    appendText(options.stderrPath, `${result.stdout ?? ""}${result.stderr ?? ""}${result.error ? result.error.message : ""}\n`);
-  }
-  const pid = Number(String(result.stdout ?? "").trim().split(/\r?\n/).pop());
-  return {
-    pid: Number.isFinite(pid) && pid > 0 ? pid : null,
-    on() {},
-    unref() {}
-  };
-}
-
-function startLoggedProcess(command, args, options) {
-  const spawnCommand = prepareSpawnCommand(command, args);
-  if (options.detached === true && process.platform === "win32") {
-    const scriptPath = writeWindowsDetachedScript(spawnCommand.command, spawnCommand.args, options);
-    const child = startWindowsHiddenScript(scriptPath, options);
-    return {
-      child,
-      command,
-      args,
-      stdoutPath: options.stdoutPath,
-      stderrPath: options.stderrPath
-    };
-  }
-
-  const stdoutFd = fs.openSync(options.stdoutPath, "a");
-  const stderrFd = fs.openSync(options.stderrPath, "a");
-  const child = spawn(spawnCommand.command, spawnCommand.args, {
-    cwd: options.cwd ?? rootDir,
-    env: options.env ?? process.env,
-    detached: options.detached === true,
-    windowsHide: true,
-    windowsVerbatimArguments: spawnCommand.windowsVerbatimArguments ?? false,
-    stdio: ["ignore", stdoutFd, stderrFd]
-  });
-
-  child.on("error", (error) => {
-    appendText(options.stderrPath, `${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
-  });
-  if (options.detached === true) {
-    child.unref();
-  }
-
-  return {
-    child,
-    command,
-    args,
-    stdoutPath: options.stdoutPath,
-    stderrPath: options.stderrPath
-  };
-}
-
-function stopProcessTree(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) {
-    return {
-      attempted: false,
-      pid
-    };
-  }
-
-  if (process.platform === "win32") {
-    const result = run("taskkill.exe", ["/pid", String(pid), "/t", "/f"], { timeoutMs: 10_000 });
-    return {
-      attempted: true,
-      pid,
-      status: result.status,
-      error: result.error,
-      stdoutTail: tail(result.stdout, 1000),
-      stderrTail: tail(result.stderr, 1000)
-    };
-  }
-
+#!/usr/bin/env node
+
+const crypto = require("node:crypto");
+const fs = require("node:fs");
+const net = require("node:net");
+const os = require("node:os");
+const path = require("node:path");
+const { spawn, spawnSync } = require("node:child_process");
+const {
+  defaultFixtureDir,
+  defaultVsixPath,
+  prepareSpawnCommand,
+  readRegistryEntries,
+  resolveIdeCommand,
+  rootDir,
+  run,
+  sleep,
+  timestampForPath,
+  writeJson
+} = require("../ide-launch/common.cjs");
+
+const managedRootDir = path.join(os.tmpdir(), "aib", "managed-hosts");
+const defaultRunsDir = path.join(rootDir, ".tmp", "managed-host-runs");
+const repoRootDir = findRepoRoot(rootDir);
+const extensionPackageDir = repoRootDir ? path.join(repoRootDir, "packages", "extension") : null;
+const repoDefaultVsixPath = repoRootDir ? path.join(repoRootDir, ".tmp", "vscode-refactor-bridge-extension.vsix") : null;
+
+function normalizeForId(value) {
+  return path.resolve(String(value)).replace(/[\\/]+$/, "").toLowerCase();
+}
+
+function normalizeForCompare(value) {
+  return path.normalize(String(value)).replace(/[\\/]+$/, "").toLowerCase();
+}
+
+function hashShort(value) {
+  return crypto.createHash("sha1").update(value).digest("hex").slice(0, 16);
+}
+
+function findRepoRoot(startDir) {
+  let current = path.resolve(startDir);
+  while (true) {
+    if (fs.existsSync(path.join(current, "packages", "extension", "package.json"))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) {
+      return null;
+    }
+    current = parent;
+  }
+}
+
+function fingerprintFile(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return null;
+  }
+
+  const stat = fs.statSync(filePath);
+  const hash = crypto.createHash("sha1").update(fs.readFileSync(filePath)).digest("hex");
+  return {
+    path: path.resolve(filePath),
+    hash,
+    shortHash: hash.slice(0, 12),
+    size: stat.size,
+    mtimeMs: stat.mtimeMs
+  };
+}
+
+function fingerprintsMatch(left, right) {
+  if (!left || !right) {
+    return false;
+  }
+
+  return left.hash === right.hash && left.size === right.size;
+}
+
+function newestFileMtimeMs(filePath) {
+  if (!filePath || !fs.existsSync(filePath)) {
+    return null;
+  }
+
+  const stat = fs.statSync(filePath);
+  if (stat.isFile()) {
+    return stat.mtimeMs;
+  }
+
+  if (!stat.isDirectory()) {
+    return null;
+  }
+
+  let newest = null;
+  for (const entry of fs.readdirSync(filePath, { withFileTypes: true })) {
+    const childNewest = newestFileMtimeMs(path.join(filePath, entry.name));
+    if (childNewest !== null && (newest === null || childNewest > newest)) {
+      newest = childNewest;
+    }
+  }
+  return newest;
+}
+
+function getExtensionVsixFreshness(vsix) {
+  const resolvedVsix = path.resolve(vsix);
+  const knownDevVsixPaths = [defaultVsixPath, repoDefaultVsixPath].filter(Boolean);
+  if (!extensionPackageDir || !knownDevVsixPaths.some((knownPath) => normalizeForCompare(resolvedVsix) === normalizeForCompare(knownPath))) {
+    return {
+      supported: false,
+      reason: "non-default-vsix",
+      vsix: resolvedVsix
+    };
+  }
+
+  const inputPaths = [
+    path.join(extensionPackageDir, "dist"),
+    path.join(extensionPackageDir, "extension.js"),
+    path.join(extensionPackageDir, "package.json"),
+    path.join(extensionPackageDir, "README.md"),
+    path.join(extensionPackageDir, ".vscodeignore")
+  ];
+  const inputMtimes = inputPaths
+    .map((inputPath) => ({ path: inputPath, mtimeMs: newestFileMtimeMs(inputPath) }))
+    .filter((entry) => entry.mtimeMs !== null);
+  const newestInput = inputMtimes.reduce((best, entry) => {
+    if (!best || entry.mtimeMs > best.mtimeMs) {
+      return entry;
+    }
+    return best;
+  }, null);
+  const vsixMtimeMs = fs.existsSync(resolvedVsix) ? fs.statSync(resolvedVsix).mtimeMs : null;
+  const stale = vsixMtimeMs === null || (newestInput !== null && newestInput.mtimeMs > vsixMtimeMs + 1000);
+
+  return {
+    supported: true,
+    stale,
+    vsix: resolvedVsix,
+    vsixMtimeMs,
+    newestInput
+  };
+}
+
+function packageExtensionVsix() {
+  const npmCommand = process.platform === "win32" ? "npm.cmd" : "npm";
+  return runCommand(npmCommand, ["--silent", "--prefix", "packages/extension", "run", "package:vsix"], {
+    cwd: repoRootDir ?? rootDir,
+    timeoutMs: 120_000
+  });
+}
+
+function buildHostId(options) {
+  const hostKind = options.hostKind ?? "vscode-serve-web";
+  return `${hostKind}-${hashShort(normalizeForId(options.fixture ?? defaultFixtureDir))}`;
+}
+
+function getHostDir(hostId) {
+  return path.join(managedRootDir, hostId);
+}
+
+function getMetadataPath(hostId) {
+  return path.join(getHostDir(hostId), "metadata.json");
+}
+
+function getWatchdogPath(hostId) {
+  return path.join(getHostDir(hostId), "watchdog.json");
+}
+
+function getLockDir(hostId) {
+  return path.join(getHostDir(hostId), "lock");
+}
+
+function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+function writeText(filePath, value) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, value);
+}
+
+function appendText(filePath, value) {
+  ensureDir(path.dirname(filePath));
+  fs.appendFileSync(filePath, value);
+}
+
+function writeJsonAtomic(filePath, payload) {
+  ensureDir(path.dirname(filePath));
+  const tempPath = `${filePath}.${process.pid}.${Date.now()}.tmp`;
+  try {
+    fs.writeFileSync(tempPath, `${JSON.stringify(payload, null, 2)}\n`);
+    fs.renameSync(tempPath, filePath);
+  } catch (error) {
+    try {
+      fs.rmSync(tempPath, { force: true });
+    } catch {
+      // Best-effort cleanup only.
+    }
+    throw error;
+  }
+}
+
+function tail(text, maxLength = 4000) {
+  return text.length > maxLength ? text.slice(text.length - maxLength) : text;
+}
+
+function readTextIfExists(filePath) {
+  try {
+    return fs.readFileSync(filePath, "utf8");
+  } catch {
+    return "";
+  }
+}
+
+function readRecentLogText(root, maxFiles = 12, maxLength = 4000) {
+  if (!fs.existsSync(root)) {
+    return "";
+  }
+  const files = [];
+  collectFiles(root, files, 5);
+  return files
+    .filter((filePath) => filePath.endsWith(".log") || filePath.endsWith(".txt"))
+    .sort((left, right) => {
+      const leftTime = fs.statSync(left).mtimeMs;
+      const rightTime = fs.statSync(right).mtimeMs;
+      return rightTime - leftTime;
+    })
+    .slice(0, maxFiles)
+    .map((filePath) => readTextIfExists(filePath))
+    .join("\n")
+    .slice(-maxLength);
+}
+
+function collectFiles(root, files, maxDepth) {
+  if (maxDepth < 0) {
+    return;
+  }
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return;
+  }
+  for (const entry of entries) {
+    const entryPath = path.join(root, entry.name);
+    if (entry.isFile()) {
+      files.push(entryPath);
+    } else if (entry.isDirectory()) {
+      collectFiles(entryPath, files, maxDepth - 1);
+    }
+  }
+}
+
+function isProcessAlive(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return false;
+  }
+
+  try {
+    process.kill(pid, 0);
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+function workspaceMatchesFixture(entry, fixture) {
+  const expected = normalizeForCompare(fixture);
+  return (entry.workspaceFolders ?? []).some(
+    (workspaceFolder) => normalizeForCompare(workspaceFolder) === expected
+  );
+}
+
+function resolveChromePath(explicitPath) {
+  const candidates = [
+    explicitPath,
+    findPackagedBrowserRuntime(),
+    "C:\\Program Files\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files (x86)\\Google\\Chrome\\Application\\chrome.exe",
+    "C:\\Program Files\\Microsoft\\Edge\\Application\\msedge.exe",
+    "C:\\Program Files (x86)\\Microsoft\\Edge\\Application\\msedge.exe",
+    "google-chrome",
+    "google-chrome-stable",
+    "chromium",
+    "chromium-browser",
+    "microsoft-edge"
+  ].filter(Boolean);
+
+  return candidates.find((candidate) => commandOrFileExists(candidate)) ?? null;
+}
+
+function findPackagedBrowserRuntime() {
+  const roots = [
+    path.join(rootDir, "runtimes", "browser"),
+    path.join(rootDir, "runtimes", "chrome"),
+    path.join(rootDir, "runtimes", "chromium")
+  ];
+  const executableNames = process.platform === "win32"
+    ? new Set(["chrome.exe", "chromium.exe", "msedge.exe"])
+    : new Set(["chrome", "chromium"]);
+  for (const runtimeRoot of roots) {
+    const found = findFirstExecutable(runtimeRoot, executableNames, 5);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+function findFirstExecutable(root, executableNames, maxDepth) {
+  if (!fs.existsSync(root) || maxDepth < 0) {
+    return null;
+  }
+  let entries;
+  try {
+    entries = fs.readdirSync(root, { withFileTypes: true });
+  } catch {
+    return null;
+  }
+  for (const entry of entries) {
+    const entryPath = path.join(root, entry.name);
+    if (entry.isFile() && executableNames.has(entry.name) && commandOrFileExists(entryPath)) {
+      return entryPath;
+    }
+  }
+  for (const entry of entries) {
+    if (!entry.isDirectory()) {
+      continue;
+    }
+    const found = findFirstExecutable(path.join(root, entry.name), executableNames, maxDepth - 1);
+    if (found) {
+      return found;
+    }
+  }
+  return null;
+}
+
+function commandOrFileExists(candidate) {
+  if (candidate.includes("\\") || candidate.includes("/") || /^[A-Za-z]:/.test(candidate)) {
+    return fs.existsSync(candidate);
+  }
+
+  const escaped = String(candidate).replace(/"/g, '\\"');
+  const result = process.platform === "win32"
+    ? spawnSync("where.exe", [candidate], { encoding: "utf8", windowsHide: true, stdio: ["ignore", "pipe", "pipe"] })
+    : spawnSync("sh", ["-lc", `command -v "${escaped}"`], { encoding: "utf8", stdio: ["ignore", "pipe", "pipe"] });
+  return result.status === 0;
+}
+
+function ideCommandEnv() {
+  return {
+    ...process.env,
+    DONT_PROMPT_WSL_INSTALL: process.env.DONT_PROMPT_WSL_INSTALL ?? "1"
+  };
+}
+
+function makeCommandSpec(command, prefixArgs = [], source = "command") {
+  return {
+    command,
+    prefixArgs,
+    source,
+    displayCommand: [command, ...prefixArgs].join(" ")
+  };
+}
+
+function resolvePackagedNodeRuntime() {
+  const envNodePath = process.env.AIB_NODE_PATH;
+  if (envNodePath && commandOrFileExists(envNodePath)) {
+    return { command: path.resolve(envNodePath), source: "env-node" };
+  }
+
+  const platformDir = nodeRuntimePlatformDir();
+  if (!platformDir) {
+    return { command: process.execPath, source: "process-node" };
+  }
+
+  const candidateRoots = [
+    path.join(rootDir, "runtimes", "node", platformDir),
+    path.join(rootDir, "packages", "cli", "runtimes", "node", platformDir)
+  ];
+  for (const candidateRoot of candidateRoots) {
+    const candidate = process.platform === "win32"
+      ? path.join(candidateRoot, "node.exe")
+      : path.join(candidateRoot, "bin", "node");
+    if (fs.existsSync(candidate)) {
+      return { command: candidate, source: "packaged-node" };
+    }
+  }
+
+  return { command: process.execPath, source: "process-node" };
+}
+
+function nodeRuntimePlatformDir() {
+  const arch = process.arch;
+  if (process.platform === "win32" && arch === "x64") {
+    return "win-x64";
+  }
+  if (process.platform === "linux" && arch === "x64") {
+    return "linux-x64";
+  }
+  if (process.platform === "linux" && arch === "arm64") {
+    return "linux-arm64";
+  }
+  if (process.platform === "darwin" && arch === "x64") {
+    return "darwin-x64";
+  }
+  if (process.platform === "darwin" && arch === "arm64") {
+    return "darwin-arm64";
+  }
+  return null;
+}
+
+function commandDisplayName(commandSpec) {
+  return typeof commandSpec === "string" ? commandSpec : commandSpec.displayCommand;
+}
+
+function commandExecutable(commandSpec) {
+  return typeof commandSpec === "string" ? commandSpec : commandSpec.command;
+}
+
+function commandArgs(commandSpec, args) {
+  return typeof commandSpec === "string" ? args : [...commandSpec.prefixArgs, ...args];
+}
+
+function runCommand(commandSpec, args, options = {}) {
+  return run(commandExecutable(commandSpec), commandArgs(commandSpec, args), options);
+}
+
+function startLoggedCommand(commandSpec, args, options) {
+  return startLoggedProcess(commandExecutable(commandSpec), commandArgs(commandSpec, args), options);
+}
+
+function resolvePackagedCodeServerCommand() {
+  const nodeRuntime = resolvePackagedNodeRuntime();
+  const candidates = [
+    {
+      packageRoot: rootDir,
+      entryPath: path.join(rootDir, "runtimes", "code-server", "node_modules", "code-server", "out", "node", "entry.js")
+    },
+    {
+      packageRoot: path.join(rootDir, "packages", "cli"),
+      entryPath: path.join(rootDir, "packages", "cli", "runtimes", "code-server", "node_modules", "code-server", "out", "node", "entry.js")
+    }
+  ];
+  for (const { packageRoot, entryPath } of candidates) {
+    if (fs.existsSync(entryPath) && managedRuntimePlatformStatus(packageRoot).ok) {
+      return makeCommandSpec(nodeRuntime.command, [entryPath], nodeRuntime.source === "packaged-node"
+        ? "packaged-code-server-entry-bundled-node"
+        : "packaged-code-server-entry");
+    }
+  }
+  return null;
+}
+
+function managedRuntimePlatformStatus(packageRoot) {
+  const markerPath = path.join(packageRoot, "runtimes", ".aib-runtime-platform.json");
+  const expectedPlatformKey = `${process.platform}-${process.arch}`;
+  if (!fs.existsSync(markerPath)) {
+    return { ok: true, reason: "missing", expectedPlatformKey, actualPlatformKey: null };
+  }
+  try {
+    const marker = JSON.parse(fs.readFileSync(markerPath, "utf8"));
+    const actualPlatformKey = typeof marker.platformKey === "string"
+      ? marker.platformKey
+      : typeof marker.platform === "string" && typeof marker.arch === "string"
+        ? `${marker.platform}-${marker.arch}`
+        : null;
+    return {
+      ok: actualPlatformKey === expectedPlatformKey,
+      reason: actualPlatformKey === expectedPlatformKey ? "ok" : "mismatch",
+      expectedPlatformKey,
+      actualPlatformKey
+    };
+  } catch {
+    return { ok: false, reason: "invalid", expectedPlatformKey, actualPlatformKey: null };
+  }
+}
+
+function resolveManagedHostKind(options, commandSpec) {
+  const raw = options.hostKind ?? process.env.AIB_MANAGED_HOST_KIND ?? "";
+  if (raw) {
+    if (raw !== "vscode-serve-web" && raw !== "code-server") {
+      throw new Error("Expected managed host kind to be vscode-serve-web or code-server.");
+    }
+    return raw;
+  }
+
+  const command = commandDisplayName(commandSpec);
+  const commandName = path.basename(String(command)).toLowerCase();
+  return commandName === "code-server"
+    || commandName === "code-server.cmd"
+    || command.endsWith(path.join("code-server", "out", "node", "entry.js"))
+    ? "code-server"
+    : "vscode-serve-web";
+}
+
+function resolveManagedIdeCommand(options) {
+  if (options.ideCommand) {
+    return makeCommandSpec(options.ideCommand, [], "explicit");
+  }
+
+  const rawHostKind = options.hostKind ?? process.env.AIB_MANAGED_HOST_KIND ?? "";
+  if (rawHostKind === "code-server") {
+    if (process.env.AIB_CODE_SERVER_PATH && commandOrFileExists(process.env.AIB_CODE_SERVER_PATH)) {
+      return makeCommandSpec(process.env.AIB_CODE_SERVER_PATH, [], "env-code-server");
+    }
+    const packagedCommand = resolvePackagedCodeServerCommand();
+    if (packagedCommand) {
+      return packagedCommand;
+    }
+    const candidates = [
+      path.join(rootDir, "runtimes", "code-server", "bin", process.platform === "win32" ? "code-server.cmd" : "code-server"),
+      path.join(rootDir, "runtimes", "code-server", "bin", "code-server"),
+      path.join(rootDir, "packages", "cli", "runtimes", "code-server", "bin", process.platform === "win32" ? "code-server.cmd" : "code-server"),
+      path.join(rootDir, "packages", "cli", "runtimes", "code-server", "bin", "code-server"),
+      "code-server"
+    ].filter(Boolean);
+    const found = candidates.find((candidate) => commandOrFileExists(candidate)) ?? "code-server";
+    return makeCommandSpec(found, [], "code-server-path");
+  }
+
+  return makeCommandSpec(resolveIdeCommand({ ide: "code" }), [], "vscode-code");
+}
+
+function buildIdeCommandEnv(runDir) {
+  const env = ideCommandEnv();
+  if (process.platform !== "win32") {
+    const homeDir = path.join(runDir, "home");
+    env.HOME = homeDir;
+    env.VSCODE_CLI_DATA_DIR = path.join(runDir, "cli-data");
+  }
+  return env;
+}
+
+function readJsonFile(filePath) {
+  try {
+    return JSON.parse(fs.readFileSync(filePath, "utf8"));
+  } catch {
+    return null;
+  }
+}
+
+function readMetadataByHostId(hostId) {
+  const metadataPath = getMetadataPath(hostId);
+  const metadata = fs.existsSync(metadataPath) ? readJsonFile(metadataPath) : null;
+  if (!metadata || typeof metadata !== "object") {
+    return null;
+  }
+  return metadata;
+}
+
+function readAllManagedHostEntries() {
+  if (!fs.existsSync(managedRootDir)) {
+    return [];
+  }
+  const entries = [];
+  for (const item of fs.readdirSync(managedRootDir, { withFileTypes: true })) {
+    if (!item.isDirectory()) {
+      continue;
+    }
+    const metadata = readMetadataByHostId(item.name);
+    if (!metadata) {
+      continue;
+    }
+    entries.push({
+      hostId: item.name,
+      metadata
+    });
+  }
+  return entries.sort((left, right) => String(left.hostId).localeCompare(String(right.hostId)));
+}
+
+function compactRuntimeStatus(status, metadata = {}) {
+  return {
+    hostId: status.hostId ?? metadata.hostId ?? null,
+    hostKind: status.hostKind ?? metadata.hostKind ?? null,
+    running: status.running === true,
+    healthy: status.healthy === true,
+    fixture: metadata.fixture ?? status.metadata?.fixture ?? null,
+    runDir: metadata.runDir ?? status.metadata?.runDir ?? null,
+    rootUrl: metadata.rootUrl ?? status.metadata?.rootUrl ?? null,
+    reason: status.reason ?? null
+  };
+}
+
+function writeMetadata(hostId, metadata) {
+  writeJsonAtomic(getMetadataPath(hostId), metadata);
+}
+
+function removeMetadata(hostId) {
+  fs.rmSync(getMetadataPath(hostId), { force: true });
+}
+
+function quoteCmdArg(value) {
+  const raw = String(value);
+  return `"${raw.replace(/%/g, "%%").replace(/"/g, '\\"')}"`;
+}
+
+function quotePowerShellString(value) {
+  return `'${String(value).replace(/'/g, "''")}'`;
+}
+
+function writeWindowsDetachedScript(command, args, options) {
+  ensureDir(path.dirname(options.stdoutPath));
+  ensureDir(path.dirname(options.stderrPath));
+  const scriptPath = `${options.stdoutPath}.cmd`;
+  const cwd = options.cwd ?? rootDir;
+  const commandLine = [
+    quoteCmdArg(command),
+    ...args.map(quoteCmdArg),
+    ">",
+    quoteCmdArg(options.stdoutPath),
+    "2>",
+    quoteCmdArg(options.stderrPath)
+  ].join(" ");
+  writeText(scriptPath, [
+    "@echo off",
+    `cd /d ${quoteCmdArg(cwd)}`,
+    commandLine,
+    ""
+  ].join("\r\n"));
+  return scriptPath;
+}
+
+function startWindowsHiddenScript(scriptPath, options) {
+  const cwd = options.cwd ?? rootDir;
+  const command = [
+    "$p = Start-Process -FilePath 'cmd.exe'",
+    `-ArgumentList @('/d','/s','/c', ${quotePowerShellString(scriptPath)})`,
+    `-WorkingDirectory ${quotePowerShellString(cwd)}`,
+    "-WindowStyle Hidden -PassThru;",
+    "$p.Id"
+  ].join(" ");
+  const result = spawnSync("powershell.exe", [
+    "-NoProfile",
+    "-ExecutionPolicy",
+    "Bypass",
+    "-WindowStyle",
+    "Hidden",
+    "-Command",
+    command
+  ], {
+    cwd,
+    env: options.env ?? process.env,
+    encoding: "utf8",
+    windowsHide: true,
+    stdio: ["ignore", "pipe", "pipe"]
+  });
+  if (result.status !== 0) {
+    appendText(options.stderrPath, `${result.stdout ?? ""}${result.stderr ?? ""}${result.error ? result.error.message : ""}\n`);
+  }
+  const pid = Number(String(result.stdout ?? "").trim().split(/\r?\n/).pop());
+  return {
+    pid: Number.isFinite(pid) && pid > 0 ? pid : null,
+    on() {},
+    unref() {}
+  };
+}
+
+function startLoggedProcess(command, args, options) {
+  const spawnCommand = prepareSpawnCommand(command, args);
+  if (options.detached === true && process.platform === "win32") {
+    const scriptPath = writeWindowsDetachedScript(spawnCommand.command, spawnCommand.args, options);
+    const child = startWindowsHiddenScript(scriptPath, options);
+    return {
+      child,
+      command,
+      args,
+      stdoutPath: options.stdoutPath,
+      stderrPath: options.stderrPath
+    };
+  }
+
+  const stdoutFd = fs.openSync(options.stdoutPath, "a");
+  const stderrFd = fs.openSync(options.stderrPath, "a");
+  const child = spawn(spawnCommand.command, spawnCommand.args, {
+    cwd: options.cwd ?? rootDir,
+    env: options.env ?? process.env,
+    detached: options.detached === true,
+    windowsHide: true,
+    windowsVerbatimArguments: spawnCommand.windowsVerbatimArguments ?? false,
+    stdio: ["ignore", stdoutFd, stderrFd]
+  });
+
+  child.on("error", (error) => {
+    appendText(options.stderrPath, `${error instanceof Error ? error.stack ?? error.message : String(error)}\n`);
+  });
+  if (options.detached === true) {
+    child.unref();
+  }
+
+  return {
+    child,
+    command,
+    args,
+    stdoutPath: options.stdoutPath,
+    stderrPath: options.stderrPath
+  };
+}
+
+function stopProcessTree(pid) {
+  if (!Number.isInteger(pid) || pid <= 0) {
+    return {
+      attempted: false,
+      pid
+    };
+  }
+
+  if (process.platform === "win32") {
+    const result = run("taskkill.exe", ["/pid", String(pid), "/t", "/f"], { timeoutMs: 10_000 });
+    return {
+      attempted: true,
+      pid,
+      status: result.status,
+      error: result.error,
+      stdoutTail: tail(result.stdout, 1000),
+      stderrTail: tail(result.stderr, 1000)
+    };
+  }
+
   try {
     if (process.platform !== "win32") {
       process.kill(-pid, "SIGTERM");
@@ -616,142 +734,217 @@ function stopProcessTree(pid) {
       waitForProcessExit(pid, 1000);
     }
     return {
-      attempted: true,
-      pid,
-      status: 0,
-      error: null
-    };
-  } catch (error) {
-    if (process.platform !== "win32") {
-      try {
-        process.kill(pid, "SIGTERM");
-        if (!waitForProcessExit(pid, 2000)) {
-          try {
-            process.kill(pid, "SIGKILL");
-          } catch {
-            // Keep the SIGTERM result; this is best-effort cleanup.
-          }
-          waitForProcessExit(pid, 1000);
-        }
-        return {
-          attempted: true,
-          pid,
-          status: 0,
-          error: null
-        };
-      } catch {
-        // Keep the original process-group error for diagnostics.
-      }
-    }
-    return {
-      attempted: true,
-      pid,
-      status: 1,
-      error: error instanceof Error ? error.message : String(error)
-    };
-  }
-}
-
-function stopProcessesByCommandLineFragment(fragment) {
-  if (process.platform !== "win32" || !fragment) {
-    return {
-      attempted: false,
-      fragment
-    };
-  }
-
-  const escaped = String(fragment).replace(/'/g, "''");
-  const script = [
-    "$fragment = '" + escaped + "'",
-    "Get-CimInstance Win32_Process |",
-    "Where-Object { $_.CommandLine -and $_.CommandLine.Contains($fragment) } |",
-    "ForEach-Object { try { Stop-Process -Id $_.ProcessId -Force -ErrorAction Stop; $_.ProcessId } catch {} }"
-  ].join(" ");
-  const result = run("powershell.exe", ["-NoProfile", "-Command", script], { timeoutMs: 10_000 });
-  return {
-    attempted: true,
-    fragment,
-    status: result.status,
-    error: result.error,
-    stdoutTail: tail(result.stdout, 1000),
-    stderrTail: tail(result.stderr, 1000)
-  };
-}
-
-function stopOrphanedPackagedRuntimeProcesses(activeRunDirs = []) {
-  if (process.platform !== "win32") {
-    return {
-      attempted: false,
-      reason: "unsupported-platform"
-    };
-  }
-
-  const escapedRoot = rootDir.replace(/'/g, "''");
-  const activeList = activeRunDirs
-    .filter(Boolean)
-    .map((item) => "'" + String(item).replace(/'/g, "''") + "'")
-    .join(",");
-  const script = [
-    "$root = '" + escapedRoot + "'",
-    "$active = @(" + activeList + ")",
-    "$runtimePattern = [regex]::Escape($root + '\\runtimes\\')",
-    "$runPattern = [regex]::Escape($root + '\\.tmp\\managed-host-runs\\')",
-    "Get-CimInstance Win32_Process |",
-    "Where-Object {",
-    "  $cmd = $_.CommandLine",
-    "  $cmd -and",
-    "  $cmd -match $runtimePattern -and",
-    "  $cmd -match $runPattern -and",
-    "  -not ($active | Where-Object { $_ -and $cmd.Contains($_) })",
-    "} |",
-    "ForEach-Object { try { Stop-Process -Id $_.ProcessId -Force -ErrorAction Stop; $_.ProcessId } catch {} }"
-  ].join(" ");
-  const result = run("powershell.exe", ["-NoProfile", "-Command", script], { timeoutMs: 10_000 });
-  return {
-    attempted: true,
-    status: result.status,
-    error: result.error,
-    stdoutTail: tail(result.stdout, 1000),
-    stderrTail: tail(result.stderr, 1000)
-  };
-}
-
+      attempted: true,
+      pid,
+      status: 0,
+      error: null
+    };
+  } catch (error) {
+    if (process.platform !== "win32") {
+      try {
+        process.kill(pid, "SIGTERM");
+        if (!waitForProcessExit(pid, 2000)) {
+          try {
+            process.kill(pid, "SIGKILL");
+          } catch {
+            // Keep the SIGTERM result; this is best-effort cleanup.
+          }
+          waitForProcessExit(pid, 1000);
+        }
+        return {
+          attempted: true,
+          pid,
+          status: 0,
+          error: null
+        };
+      } catch {
+        // Keep the original process-group error for diagnostics.
+      }
+    }
+    return {
+      attempted: true,
+      pid,
+      status: 1,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+function stopProcessesByCommandLineFragment(fragment) {
+  if (!fragment) {
+    return {
+      attempted: false,
+      fragment
+    };
+  }
+  if (process.platform !== "win32") {
+    return stopProcessesByCommandLineFragmentUnix(fragment);
+  }
+
+  const escaped = String(fragment).replace(/'/g, "''");
+  const script = [
+    "$self = $PID",
+    "$fragment = '" + escaped + "'",
+    "Get-CimInstance Win32_Process |",
+    "Where-Object { $_.ProcessId -ne $self -and $_.CommandLine -and $_.CommandLine.Contains($fragment) } |",
+    "ForEach-Object { try { Stop-Process -Id $_.ProcessId -Force -ErrorAction Stop; $_.ProcessId } catch {} }"
+  ].join("\n");
+  const result = run("powershell.exe", ["-NoProfile", "-Command", script], { timeoutMs: 10_000 });
+  const killed = result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean).length;
+  return {
+    attempted: true,
+    fragment,
+    killed,
+    status: result.status,
+    error: result.error,
+    stdoutTail: tail(result.stdout, 1000),
+    stderrTail: tail(result.stderr, 1000)
+  };
+}
+
+function stopProcessesByCommandLineFragmentUnix(fragment) {
+  const result = run("ps", ["-eo", "pid=,args="], { timeoutMs: 10_000 });
+  if (result.status !== 0) {
+    return {
+      attempted: true,
+      fragment,
+      killed: 0,
+      status: result.status,
+      error: result.error,
+      stdoutTail: tail(result.stdout, 1000),
+      stderrTail: tail(result.stderr, 1000)
+    };
+  }
+
+  const currentPid = process.pid;
+  const parentPid = process.ppid;
+  const pids = result.stdout
+    .split(/\r?\n/)
+    .map((line) => {
+      const match = line.match(/^\s*(\d+)\s+(.*)$/);
+      if (!match) {
+        return null;
+      }
+      return {
+        pid: Number(match[1]),
+        commandLine: match[2] ?? ""
+      };
+    })
+    .filter(Boolean)
+    .filter((row) => row.pid !== currentPid && row.pid !== parentPid)
+    .filter((row) => row.commandLine.includes(fragment))
+    .map((row) => row.pid);
+
+  const uniquePids = [...new Set(pids)].filter((pid) => Number.isInteger(pid) && pid > 0);
+  let killed = 0;
+  const errors = [];
+  for (const pid of uniquePids) {
+    try {
+      process.kill(pid, "SIGTERM");
+      killed += 1;
+    } catch (error) {
+      errors.push(`${pid}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  if (killed > 0) {
+    sleepSync(250);
+  }
+  for (const pid of uniquePids) {
+    if (!isProcessAlive(pid)) {
+      continue;
+    }
+    try {
+      process.kill(pid, "SIGKILL");
+    } catch (error) {
+      errors.push(`${pid}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+  return {
+    attempted: true,
+    fragment,
+    killed,
+    status: errors.length === 0 ? 0 : 1,
+    error: errors.join("; ") || null
+  };
+}
+
+function stopOrphanedPackagedRuntimeProcesses(activeRunDirs = []) {
+  if (process.platform !== "win32") {
+    return {
+      attempted: false,
+      reason: "unsupported-platform"
+    };
+  }
+
+  const escapedRoot = rootDir.replace(/'/g, "''");
+  const activeList = activeRunDirs
+    .filter(Boolean)
+    .map((item) => "'" + String(item).replace(/'/g, "''") + "'")
+    .join(",");
+  const script = [
+    "$root = '" + escapedRoot + "'",
+    "$active = @(" + activeList + ")",
+    "$runtimePattern = [regex]::Escape($root + '\\runtimes\\')",
+    "$runPattern = [regex]::Escape($root + '\\.tmp\\managed-host-runs\\')",
+    "Get-CimInstance Win32_Process |",
+    "Where-Object {",
+    "  $cmd = $_.CommandLine",
+    "  $cmd -and",
+    "  $cmd -match $runtimePattern -and",
+    "  $cmd -match $runPattern -and",
+    "  -not ($active | Where-Object { $_ -and $cmd.Contains($_) })",
+    "} |",
+    "ForEach-Object { try { Stop-Process -Id $_.ProcessId -Force -ErrorAction Stop; $_.ProcessId } catch {} }"
+  ].join(" ");
+  const result = run("powershell.exe", ["-NoProfile", "-Command", script], { timeoutMs: 10_000 });
+  return {
+    attempted: true,
+    status: result.status,
+    error: result.error,
+    stdoutTail: tail(result.stdout, 1000),
+    stderrTail: tail(result.stderr, 1000)
+  };
+}
+
 function stopAibOwnedRuntimeProcesses() {
   if (process.platform !== "win32") {
     return stopAibOwnedRuntimeProcessesUnix();
   }
-
-  const roots = [
-    rootDir,
-    path.join(rootDir, "packages", "cli")
-  ].map((item) => String(item).replace(/'/g, "''"));
-  const script = [
-    "$roots = @(" + roots.map((item) => "'" + item + "'").join(",") + ")",
-    "$processes = @(Get-CimInstance Win32_Process | Where-Object {",
-    "  $cmd = $_.CommandLine",
-    "  if (-not $cmd) { return $false }",
-    "  $underAibRoot = [bool]($roots | Where-Object { $_ -and $cmd.Contains($_) })",
-    "  $hasRunMarker = $cmd.Contains('managed-host-runs')",
-    "  $isAibWatchdog = $cmd.Contains('manage-serve-web-host.cjs') -and $cmd.Contains('watchdog') -and $underAibRoot",
-    "  $isPackagedRuntime = $underAibRoot -and ($cmd.Contains('\\runtimes\\code-server\\') -or $cmd.Contains('\\runtimes\\browser\\'))",
-    "  $isAibDetachedWrapper = $underAibRoot -and ($cmd.Contains('serve-web.stdout.txt.cmd') -or $cmd.Contains('headless-browser.stdout.txt.cmd') -or $cmd.Contains('watchdog.stdout.txt.cmd'))",
-    "  ($hasRunMarker -and $underAibRoot) -or $isAibWatchdog -or $isPackagedRuntime -or $isAibDetachedWrapper",
-    "})",
-    "$processes | ForEach-Object { try { Stop-Process -Id $_.ProcessId -Force -ErrorAction Stop; $_.ProcessId } catch {} }"
-  ].join("\n");
-  const result = run("powershell.exe", ["-NoProfile", "-Command", script], { timeoutMs: 15_000 });
-  const killed = result.stdout
-    .split(/\r?\n/)
-    .map((line) => line.trim())
-    .filter(Boolean).length;
-  return {
-    attempted: true,
-    killed,
-    status: result.status,
-    error: result.error,
-    stdoutTail: tail(result.stdout, 1000),
-    stderrTail: tail(result.stderr, 1000)
-  };
+
+  const roots = [
+    rootDir,
+    path.join(rootDir, "packages", "cli")
+  ].map((item) => String(item).replace(/'/g, "''"));
+  const script = [
+    "$roots = @(" + roots.map((item) => "'" + item + "'").join(",") + ")",
+    "$processes = @(Get-CimInstance Win32_Process | Where-Object {",
+    "  $cmd = $_.CommandLine",
+    "  if (-not $cmd) { return $false }",
+    "  $underAibRoot = [bool]($roots | Where-Object { $_ -and $cmd.Contains($_) })",
+    "  $hasRunMarker = $cmd.Contains('managed-host-runs')",
+    "  $isAibWatchdog = $cmd.Contains('manage-serve-web-host.cjs') -and $cmd.Contains('watchdog') -and $underAibRoot",
+    "  $isPackagedRuntime = $underAibRoot -and ($cmd.Contains('\\runtimes\\code-server\\') -or $cmd.Contains('\\runtimes\\browser\\'))",
+    "  $isAibDetachedWrapper = $underAibRoot -and ($cmd.Contains('serve-web.stdout.txt.cmd') -or $cmd.Contains('headless-browser.stdout.txt.cmd') -or $cmd.Contains('watchdog.stdout.txt.cmd'))",
+    "  ($hasRunMarker -and $underAibRoot) -or $isAibWatchdog -or $isPackagedRuntime -or $isAibDetachedWrapper",
+    "})",
+    "$processes | ForEach-Object { try { Stop-Process -Id $_.ProcessId -Force -ErrorAction Stop; $_.ProcessId } catch {} }"
+  ].join("\n");
+  const result = run("powershell.exe", ["-NoProfile", "-Command", script], { timeoutMs: 15_000 });
+  const killed = result.stdout
+    .split(/\r?\n/)
+    .map((line) => line.trim())
+    .filter(Boolean).length;
+  return {
+    attempted: true,
+    killed,
+    status: result.status,
+    error: result.error,
+    stdoutTail: tail(result.stdout, 1000),
+    stderrTail: tail(result.stderr, 1000)
+  };
 }
 
 function stopAibOwnedRuntimeProcessesUnix() {
@@ -859,932 +1052,1064 @@ function waitForProcessExit(pid, timeoutMs) {
   }
   return !isProcessAlive(pid);
 }
-
-function readTtlMs(value, fallbackMs = 15 * 60_000) {
-  if (value === null || value === undefined || value === "") {
-    return fallbackMs;
-  }
-  const parsed = Number(value);
-  return Number.isFinite(parsed) ? parsed : fallbackMs;
-}
-
-function metadataLastActivityMs(metadata) {
-  const raw = metadata?.lastActivityAt ?? metadata?.updatedAt ?? metadata?.startedAt;
-  const parsed = typeof raw === "string" ? Date.parse(raw) : NaN;
-  return Number.isFinite(parsed) ? parsed : 0;
-}
-
-function isMetadataExpired(metadata, ttlMs, now = Date.now()) {
-  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
-    return false;
-  }
-  const lastActivityMs = metadataLastActivityMs(metadata);
-  return lastActivityMs > 0 && now - lastActivityMs > ttlMs;
-}
-
-async function tryFetch(url) {
-  try {
-    const response = await fetch(url);
-    return {
-      ok: response.ok,
-      status: response.status,
-      contentType: response.headers.get("content-type")
-    };
-  } catch (error) {
-    return {
-      ok: false,
-      error: error instanceof Error ? error.message : String(error)
-    };
-  }
-}
-
-async function waitFor(name, timeoutMs, pollMs, getState, isReady) {
-  const startedAt = Date.now();
-  const attempts = [];
-
-  while (Date.now() - startedAt <= timeoutMs) {
-    const state = await getState();
-    attempts.push(state);
-    if (isReady(state)) {
-      return {
-        ok: true,
-        durationMs: Date.now() - startedAt,
-        attempts: attempts.length,
-        state
-      };
-    }
-    await sleep(pollMs);
-  }
-
-  return {
-    ok: false,
-    durationMs: Date.now() - startedAt,
-    attempts: attempts.length,
-    error: `${name} did not become ready within ${timeoutMs}ms.`,
-    lastState: attempts.at(-1) ?? null
-  };
-}
-
-async function allocatePort() {
-  return new Promise((resolve, reject) => {
-    const server = net.createServer();
-    server.once("error", reject);
-    server.listen(0, "127.0.0.1", () => {
-      const address = server.address();
-      const port = address && typeof address === "object" ? address.port : null;
-      server.close(() => {
-        if (Number.isInteger(port)) {
-          resolve(port);
-        } else {
-          reject(new Error("Failed to allocate a TCP port."));
-        }
-      });
-    });
-  });
-}
-
-async function acquireLock(hostId, timeoutMs = 15_000, staleMs = 120_000) {
-  const lockDir = getLockDir(hostId);
-  const startedAt = Date.now();
-  ensureDir(path.dirname(lockDir));
-
-  while (Date.now() - startedAt <= timeoutMs) {
-    try {
-      fs.mkdirSync(lockDir);
-      writeJson(path.join(lockDir, "owner.json"), {
-        pid: process.pid,
-        acquiredAt: new Date().toISOString()
-      });
-      return {
-        hostId,
-        lockDir,
-        release() {
-          fs.rmSync(lockDir, { recursive: true, force: true });
-        }
-      };
-    } catch (error) {
-      if (error && error.code === "EEXIST") {
-        const stat = fs.statSync(lockDir);
-        if (Date.now() - stat.mtimeMs > staleMs) {
-          fs.rmSync(lockDir, { recursive: true, force: true });
-          continue;
-        }
-        await sleep(250);
-        continue;
-      }
-      throw error;
-    }
-  }
-
-  throw new Error(`Timed out acquiring managed host lock: ${lockDir}`);
-}
-
-function getMatchingRegistryEntry(metadata) {
-  if (!metadata || typeof metadata.instanceId !== "string") {
-    return null;
-  }
-
-  return readRegistryEntries().find((entry) => entry.instanceId === metadata.instanceId) ?? null;
-}
-
-async function getManagedServeWebHostStatus(options = {}) {
-  if (options.all === true) {
-    return getAllManagedServeWebHostStatuses(options);
-  }
-
-  const fixture = path.resolve(options.fixture ?? defaultFixtureDir);
-  const codeCommand = resolveManagedIdeCommand(options);
-  const hostKind = resolveManagedHostKind(options, codeCommand);
-  const hostId = options.hostId ?? buildHostId({ fixture, hostKind });
-  const expectedVsix = options.vsix ? fingerprintFile(path.resolve(options.vsix)) : null;
-  const metadata = readMetadataByHostId(hostId);
-  if (!metadata) {
-    return {
-      ok: true,
-      hostId,
-      running: false,
-      healthy: false,
-      reason: "metadata-not-found"
-    };
-  }
-
-  const registryEntry = getMatchingRegistryEntry(metadata);
-  const rootUrl = metadata.rootUrl ?? (Number.isInteger(metadata.port) ? `http://127.0.0.1:${metadata.port}` : null);
-  const http = rootUrl ? await tryFetch(rootUrl) : { ok: false, error: "missing rootUrl" };
-  const serveWebAlive = isProcessAlive(metadata.serveWebPid);
-  const browserAlive = isProcessAlive(metadata.browserPid);
-  const extensionHostAlive = registryEntry ? isProcessAlive(registryEntry.pid) : false;
-  const workspaceMatches = registryEntry ? workspaceMatchesFixture(registryEntry, fixture) : false;
-  const vsixMatches = expectedVsix ? fingerprintsMatch(metadata.vsixFingerprint, expectedVsix) : true;
-  const healthy = serveWebAlive && browserAlive && extensionHostAlive && http.ok === true && workspaceMatches && vsixMatches;
-
-  return {
-    ok: true,
-    hostId,
-    running: serveWebAlive || browserAlive || extensionHostAlive,
-    healthy,
-    metadata,
-    health: {
-      serveWebAlive,
-      browserAlive,
-      extensionHostAlive,
-      workspaceMatches,
-      vsixMatches,
-      expectedVsix,
-      http,
-      registryEntry
-    }
-  };
-}
-
-async function getAllManagedServeWebHostStatuses(options = {}) {
-  const entries = readAllManagedHostEntries();
-  const runtimes = [];
-  for (const entry of entries) {
-    const metadata = entry.metadata;
-    const status = await getManagedServeWebHostStatus({
-      ...options,
-      all: false,
-      hostId: entry.hostId,
-      fixture: metadata.fixture ?? defaultFixtureDir,
-      vsix: metadata.vsix,
-      hostKind: metadata.hostKind
-    });
-    runtimes.push(compactRuntimeStatus(status, metadata));
-  }
-  return {
-    ok: true,
-    all: true,
-    count: runtimes.length,
-    running: runtimes.filter((runtime) => runtime.running === true).length,
-    healthy: runtimes.filter((runtime) => runtime.healthy === true).length,
-    runtimes
-  };
-}
-
-async function startManagedServeWebHost(options = {}) {
-  const startedAt = Date.now();
-  const fixture = path.resolve(options.fixture ?? defaultFixtureDir);
-  const ttlMs = readTtlMs(options.ttlMs);
-  const intervalMs = Number.isFinite(Number(options.intervalMs)) && Number(options.intervalMs) > 0
-    ? Number(options.intervalMs)
-    : 30_000;
-  const waitMs = Number.isInteger(options.waitMs) ? options.waitMs : 45_000;
-  const pollMs = Number.isInteger(options.pollMs) ? options.pollMs : 500;
-  const vsix = path.resolve(options.vsix ?? defaultVsixPath);
-  const vsixFingerprint = fingerprintFile(vsix);
-  const reuse = options.reuse !== false;
-  const codeCommand = resolveManagedIdeCommand(options);
-  const hostKind = resolveManagedHostKind(options, codeCommand);
-  const hostId = options.hostId ?? buildHostId({ fixture, hostKind });
-  const runDir = path.resolve(options.runDir ?? path.join(defaultRunsDir, `${hostId}-${timestampForPath()}`));
-  const logsDir = path.join(runDir, "logs");
-  const stepsDir = path.join(runDir, "steps");
-  const userDataDir = path.join(runDir, "user-data");
-  const serverDataDir = path.join(runDir, "server-data");
-  const extensionsDir = path.join(runDir, "extensions");
-  const activeExtensionsDir = hostKind === "code-server" || process.platform === "win32"
-    ? extensionsDir
-    : path.join(serverDataDir, "extensions");
-  const ideEnv = buildIdeCommandEnv(runDir);
-  const steps = [];
-  const failures = [];
-  const beforeRegistry = readRegistryEntries();
-  const beforeInstanceIds = new Set(beforeRegistry.map((entry) => entry.instanceId));
-  let serveWebProcess = null;
-  let browserProcess = null;
-  let metadata = null;
-
-  ensureDir(logsDir);
-  ensureDir(stepsDir);
-  await cleanupExpiredManagedServeWebHosts({ ttlMs });
-
-  async function step(name, fn) {
-    const stepIndex = String(steps.length + 1).padStart(2, "0");
-    const stepPath = path.join(stepsDir, `${stepIndex}-${name.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}.json`);
-    const startedStepAt = Date.now();
-    const record = {
-      name,
-      ok: false,
-      startedAt: new Date(startedStepAt).toISOString()
-    };
-
-    try {
-      record.detail = await fn();
-      record.ok = record.detail?.ok !== false;
-      if (!record.ok) {
-        failures.push(`${name}: ${record.detail?.error ?? "failed"}`);
-      }
-    } catch (error) {
-      record.ok = false;
-      record.error = error instanceof Error ? error.message : String(error);
-      failures.push(`${name}: ${record.error}`);
-    } finally {
-      record.durationMs = Date.now() - startedStepAt;
-      record.finishedAt = new Date().toISOString();
-      record.path = stepPath;
-      writeJson(stepPath, record);
-      steps.push(record);
-    }
-
-    return record;
-  }
-
-  const lock = await acquireLock(hostId);
-  try {
-    if (reuse) {
-      const existingStatus = await getManagedServeWebHostStatus({ fixture, hostId, vsix, ideCommand: options.ideCommand, hostKind });
-      if (existingStatus.healthy) {
-        const updatedMetadata = {
-          ...existingStatus.metadata,
-          updatedAt: new Date().toISOString(),
-          lastActivityAt: new Date().toISOString(),
-          ttlMs,
-          watchdogIntervalMs: intervalMs
-        };
-        writeMetadata(hostId, updatedMetadata);
-        startManagedServeWebWatchdog({ fixture, hostId, ttlMs, intervalMs, logsDir: existingStatus.metadata.logsDir ?? logsDir, ideCommand: options.ideCommand, hostKind });
-        return buildStartSummary({
-          ok: true,
-          reused: true,
-          startedAt,
-          hostId,
-          fixture,
-          vsix,
-          codeCommand,
-          hostKind,
-          runDir: existingStatus.metadata.runDir ?? runDir,
-          logsDir: existingStatus.metadata.logsDir ?? logsDir,
-          stepsDir: existingStatus.metadata.stepsDir ?? stepsDir,
-          metadata: updatedMetadata,
-          steps,
-          failures
-        });
-      }
-      if (existingStatus.metadata) {
-        await stopManagedServeWebHost({ fixture, hostId, removeMetadataOnlyIfKnown: true });
-      }
-    } else {
-      await stopManagedServeWebHost({ fixture, hostId, removeMetadataOnlyIfKnown: true });
-    }
-
-    await step("prepare profile", async () => {
-      ensureDir(path.join(runDir, "home"));
-      ensureDir(path.join(runDir, "cli-data"));
-      ensureDir(path.join(userDataDir, "User"));
-      ensureDir(path.join(serverDataDir, "data", "User"));
-      ensureDir(serverDataDir);
-      ensureDir(extensionsDir);
-      ensureDir(activeExtensionsDir);
-      const settings = {
-        "security.workspace.trust.enabled": false,
-        "workbench.startupEditor": "none"
-      };
-      writeJson(path.join(userDataDir, "User", "settings.json"), settings);
-      writeJson(path.join(serverDataDir, "data", "User", "settings.json"), settings);
-      return {
-        ok: true,
-        runDir,
-        userDataDir,
-        serverDataDir,
-        extensionsDir
-      };
-    });
-
-    await step("install extension", async () => {
-      if (!fs.existsSync(vsix)) {
-        return {
-          ok: false,
-          error: `VSIX does not exist: ${vsix}`
-        };
-      }
-      const result = runCommand(codeCommand, [
-        "--extensions-dir",
-        activeExtensionsDir,
-        "--install-extension",
-        vsix,
-        "--force"
-      ], { timeoutMs: 60_000, env: ideEnv });
-      const stdoutPath = path.join(logsDir, "install-extension.stdout.txt");
-      const stderrPath = path.join(logsDir, "install-extension.stderr.txt");
-      writeText(stdoutPath, result.stdout);
-      writeText(stderrPath, result.stderr);
-      return {
-        ok: result.status === 0,
-        status: result.status,
-        durationMs: result.durationMs,
-        stdoutPath,
-        stderrPath,
-        stdoutTail: tail(result.stdout),
-        stderrTail: tail(result.stderr),
-        error: result.error
-      };
-    });
-    if (failures.length > 0) {
-      return buildStartSummary({ ok: false, reused: false, startedAt, hostId, fixture, vsix, codeCommand, hostKind, runDir, logsDir, stepsDir, metadata, steps, failures });
-    }
-
-    const port = Number.isInteger(options.port) ? options.port : await allocatePort();
-    const rootUrl = `http://127.0.0.1:${port}`;
-
-    const serveWebStdoutPath = path.join(logsDir, "serve-web.stdout.txt");
-    const serveWebStderrPath = path.join(logsDir, "serve-web.stderr.txt");
-
-    await step("start serve-web", async () => {
-      const args = hostKind === "code-server"
-        ? [
-            "--auth",
-            "none",
-            "--bind-addr",
-            `127.0.0.1:${port}`,
-            "--disable-workspace-trust",
-            "--disable-telemetry",
-            "--disable-update-check",
-            "--user-data-dir",
-            userDataDir,
-            "--extensions-dir",
-            activeExtensionsDir,
-            fixture
-          ]
-        : [
-            "--user-data-dir",
-            userDataDir,
-            ...(process.platform === "win32" ? ["--extensions-dir", activeExtensionsDir] : []),
-            "serve-web",
-            "--accept-server-license-terms",
-            "--host",
-            "127.0.0.1",
-            "--port",
-            String(port),
-            "--without-connection-token",
-            "--default-folder",
-            fixture,
-            "--server-data-dir",
-            serverDataDir,
-            "--log",
-            "trace",
-            ...(process.platform !== "win32" ? ["--cli-data-dir", ideEnv.VSCODE_CLI_DATA_DIR ?? path.join(runDir, "cli-data")] : [])
-          ];
-      serveWebProcess = startLoggedCommand(codeCommand, args, {
-        stdoutPath: serveWebStdoutPath,
-        stderrPath: serveWebStderrPath,
-        detached: true,
-        env: ideEnv
-      });
-      return {
-        ok: true,
-        pid: serveWebProcess.child.pid ?? null,
-        command: commandDisplayName(codeCommand),
-        commandSource: codeCommand.source ?? null,
-        hostKind,
-        args,
-        stdoutPath: serveWebStdoutPath,
-        stderrPath: serveWebStderrPath
-      };
-    });
-
-    await step("wait for serve-web http", async () => {
-      return waitFor(
-        "serve-web http",
-        waitMs,
-        pollMs,
-        () => tryFetch(rootUrl),
-        (state) => state.ok === true
-      );
-    });
-
-    await step("wait for extension host agent", async () => {
-      return waitFor(
-        "extension host agent",
-        waitMs,
-        pollMs,
-        () => {
-          const stdout = readTextIfExists(serveWebStdoutPath);
-          const stderr = readTextIfExists(serveWebStderrPath);
-          const userDataLogs = readRecentLogText(path.join(userDataDir, "logs"));
-          const serverDataLogs = readRecentLogText(path.join(serverDataDir, "logs"));
-          const combined = `${stdout}\n${stderr}\n${userDataLogs}\n${serverDataLogs}`;
-          return {
-            ready: combined.includes("Extension host agent started")
-              || combined.includes("Extension host agent listening"),
-            stdoutTail: tail(stdout, 1000),
-            stderrTail: tail(stderr, 1000),
-            logTail: tail(`${userDataLogs}\n${serverDataLogs}`, 1000)
-          };
-        },
-        (state) => state.ready === true
-      );
-    });
-    if (failures.length > 0) {
-      stopProcessTree(serveWebProcess?.child?.pid);
-      return buildStartSummary({ ok: false, reused: false, startedAt, hostId, fixture, vsix, codeCommand, hostKind, runDir, logsDir, stepsDir, metadata, steps, failures });
-    }
-
-    await step("open headless browser client", async () => {
-      const chromePath = resolveChromePath(options.chromePath);
-      if (!chromePath) {
-        return {
-          ok: false,
-          error: "Chrome or Edge executable was not found."
-        };
-      }
-
-      const profileDir = path.join(runDir, "headless-browser-profile");
-      const stdoutPath = path.join(logsDir, "headless-browser.stdout.txt");
-      const stderrPath = path.join(logsDir, "headless-browser.stderr.txt");
-      const url = `${rootUrl}/?folder=${encodeURIComponent(fixture)}`;
-      const browserArgs = [
-        "--headless=new",
-        "--disable-gpu",
-        "--disable-dev-shm-usage",
-        "--disable-background-networking",
-        "--disable-sync",
-        "--no-sandbox",
-        "--remote-debugging-port=0",
-        "--no-first-run",
-        "--no-default-browser-check",
-        `--user-data-dir=${profileDir}`,
-        url
-      ];
-      if (process.platform === "win32") {
-        const scriptPath = writeWindowsDetachedScript(chromePath, browserArgs, {
-          cwd: rootDir,
-          stdoutPath,
-          stderrPath
-        });
-        browserProcess = startWindowsHiddenScript(scriptPath, {
-          cwd: rootDir,
-          stdoutPath,
-          stderrPath
-        });
-      } else {
-        const stdoutFd = fs.openSync(stdoutPath, "a");
-        const stderrFd = fs.openSync(stderrPath, "a");
-        browserProcess = spawn(chromePath, browserArgs, {
-          cwd: rootDir,
-          detached: true,
-          windowsHide: true,
-          stdio: ["ignore", stdoutFd, stderrFd]
-        });
-      }
-      browserProcess.on("error", () => {
-        // Later registry/health waits surface browser startup failures.
-      });
-      browserProcess.unref();
-
-      return {
-        ok: true,
-        pid: browserProcess.pid ?? null,
-        chromePath,
-        profileDir,
-        devToolsActivePortPath: path.join(profileDir, "DevToolsActivePort"),
-        stdoutPath,
-        stderrPath,
-        url
-      };
-    });
-
-    await step("wait for bridge registry entry", async () => {
-      const waitResult = await waitFor(
-        "fresh bridge registry entry",
-        waitMs,
-        pollMs,
-        () => {
-          const entries = readRegistryEntries();
-          const matchingFreshEntries = entries.filter(
-            (entry) => !beforeInstanceIds.has(entry.instanceId) && workspaceMatchesFixture(entry, fixture)
-          );
-          return {
-            ok: matchingFreshEntries.length > 0,
-            entry: matchingFreshEntries[0] ?? null,
-            entryCount: entries.length,
-            matchingFreshCount: matchingFreshEntries.length
-          };
-        },
-        (state) => state.ok === true
-      );
-      return waitResult;
-    });
-    if (failures.length > 0) {
-      stopProcessTree(browserProcess?.pid);
-      stopProcessTree(serveWebProcess?.child?.pid);
-      return buildStartSummary({ ok: false, reused: false, startedAt, hostId, fixture, vsix, codeCommand, hostKind, runDir, logsDir, stepsDir, metadata, steps, failures });
-    }
-
-    const registryEntry = steps.at(-1)?.detail?.state?.entry ?? null;
-    metadata = {
-      hostId,
-      kind: "serve-web-headless-client",
-      hostKind,
-      fixture,
-      vsix,
-      vsixFingerprint,
-      codeCommand: commandDisplayName(codeCommand),
-      codeCommandSource: codeCommand.source ?? null,
-      runDir,
-      logsDir,
-      stepsDir,
-      port,
-      rootUrl,
-      serveWebPid: serveWebProcess?.child?.pid ?? null,
-      browserPid: browserProcess?.pid ?? null,
-      instanceId: registryEntry?.instanceId ?? null,
-      registryPath: registryEntry?.registryPath ?? null,
-      workspaceFolders: registryEntry?.workspaceFolders ?? [],
-      startedAt: new Date(startedAt).toISOString(),
-      updatedAt: new Date().toISOString()
-    };
-    metadata.lastActivityAt = metadata.updatedAt;
-    metadata.ttlMs = ttlMs;
-    metadata.watchdogIntervalMs = intervalMs;
-    writeMetadata(hostId, metadata);
-    startManagedServeWebWatchdog({ fixture, hostId, ttlMs, intervalMs, logsDir, ideCommand: options.ideCommand, hostKind });
-
-    return buildStartSummary({
-      ok: true,
-      reused: false,
-      startedAt,
-      hostId,
-      fixture,
-      vsix,
-      codeCommand: commandDisplayName(codeCommand),
-      codeCommandSource: codeCommand.source ?? null,
-      hostKind,
-      runDir,
-      logsDir,
-      stepsDir,
-      metadata,
-      registryEntry,
-      steps,
-      failures
-    });
-  } finally {
-    lock.release();
-  }
-}
-
-async function stopManagedServeWebHost(options = {}) {
-  if (options.all === true) {
-    return stopAllManagedServeWebHosts(options);
-  }
-
-  const fixture = path.resolve(options.fixture ?? defaultFixtureDir);
-  const codeCommand = resolveManagedIdeCommand(options);
-  const hostKind = resolveManagedHostKind(options, codeCommand);
-  const hostId = options.hostId ?? buildHostId({ fixture, hostKind });
-  const metadata = readMetadataByHostId(hostId);
-  if (!metadata) {
-    return {
-      ok: true,
-      hostId,
-      hostKind,
-      stopped: false,
-      reason: "metadata-not-found"
-    };
-  }
-
-  const stopResults = [];
-  const watchdog = readJsonFile(getWatchdogPath(hostId));
-  if (watchdog && Number.isInteger(watchdog.pid) && watchdog.pid !== process.pid) {
-    stopResults.push({
-      name: "watchdog",
-      ...stopProcessTree(watchdog.pid)
-    });
-  }
-  if (Number.isInteger(metadata.browserPid)) {
-    stopResults.push({
-      name: "headless-browser",
-      ...stopProcessTree(metadata.browserPid)
-    });
-  }
-  if (Number.isInteger(metadata.serveWebPid)) {
-    stopResults.push({
-      name: "serve-web",
-      ...stopProcessTree(metadata.serveWebPid)
-    });
-  }
-  if (typeof metadata.runDir === "string") {
-    stopResults.push({
-      name: "run-dir-processes",
-      ...stopProcessesByCommandLineFragment(metadata.runDir)
-    });
-  }
-
-  let registryCleanup = {
-    removed: false,
-    path: metadata.registryPath ?? null
-  };
-  if (typeof metadata.registryPath === "string") {
-    try {
-      fs.rmSync(metadata.registryPath, { force: true });
-      registryCleanup = {
-        removed: true,
-        path: metadata.registryPath
-      };
-    } catch (error) {
-      registryCleanup = {
-        removed: false,
-        path: metadata.registryPath,
-        error: error instanceof Error ? error.message : String(error)
-      };
-    }
-  }
-
-  removeMetadata(hostId);
-  fs.rmSync(getWatchdogPath(hostId), { force: true });
-  return {
-    ok: true,
-    hostId,
-    hostKind: metadata.hostKind ?? hostKind,
-    stopped: true,
-    metadata,
-    stopResults,
-    registryCleanup
-  };
-}
-
-async function stopAllManagedServeWebHosts(options = {}) {
-  const entries = readAllManagedHostEntries();
-  const stopped = [];
-  for (const entry of entries) {
-    const metadata = entry.metadata;
-    const result = await stopManagedServeWebHost({
-      ...options,
-      all: false,
-      hostId: entry.hostId,
-      fixture: metadata.fixture ?? defaultFixtureDir,
-      hostKind: metadata.hostKind
-    });
-    stopped.push({
-      hostId: entry.hostId,
-      hostKind: result.hostKind ?? metadata.hostKind ?? null,
-      fixture: metadata.fixture ?? null,
-      runDir: metadata.runDir ?? null,
-      stopped: result.stopped === true,
-      reason: result.reason ?? null
-    });
-  }
-  return {
-    ok: true,
-    all: true,
-    count: stopped.length,
-    stopped: stopped.filter((item) => item.stopped === true).length,
-    runtimes: stopped
-  };
-}
-
-async function killManagedServeWebHosts(options = {}) {
-  if (options.all !== true) {
-    return {
-      ok: false,
-      code: "RUNTIME_KILL_REQUIRES_ALL",
-      error: "runtime kill currently requires --all."
-    };
-  }
-  const stopResult = await stopAllManagedServeWebHosts(options);
-  const orphanCleanup = stopAibOwnedRuntimeProcesses();
-  return {
-    ok: true,
-    all: true,
-    stop: stopResult,
-    killed: orphanCleanup.killed ?? 0,
-    orphanCleanup
-  };
-}
-
-async function cleanupExpiredManagedServeWebHosts(options = {}) {
-  const ttlMs = readTtlMs(options.ttlMs);
-  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
-    return {
-      ok: true,
-      ttlMs,
-      stopped: []
-    };
-  }
-  if (!fs.existsSync(managedRootDir)) {
-    return {
-      ok: true,
-      ttlMs,
-      stopped: []
-    };
-  }
-
-  const stopped = [];
-  const activeRunDirs = [];
-  for (const item of fs.readdirSync(managedRootDir, { withFileTypes: true })) {
-    if (!item.isDirectory()) {
-      continue;
-    }
-    const hostId = item.name;
-    const metadata = readMetadataByHostId(hostId);
-    if (!metadata || !isMetadataExpired(metadata, ttlMs)) {
-      if (metadata && typeof metadata.runDir === "string" && metadata.runDir.length > 0) {
-        activeRunDirs.push(metadata.runDir);
-      }
-      continue;
-    }
-    const result = await stopManagedServeWebHost({ hostId, fixture: metadata.fixture ?? defaultFixtureDir });
-    stopped.push({
-      hostId,
-      fixture: metadata.fixture ?? null,
-      lastActivityAt: metadata.lastActivityAt ?? metadata.updatedAt ?? null,
-      stopped: result.stopped === true
-    });
-  }
-  const orphanCleanup = stopOrphanedPackagedRuntimeProcesses(activeRunDirs);
-
-  return {
-    ok: true,
-    ttlMs,
-    stopped,
-    orphanCleanup
-  };
-}
-
-async function runManagedServeWebWatchdog(options = {}) {
-  const fixture = path.resolve(options.fixture ?? defaultFixtureDir);
-  const codeCommand = resolveManagedIdeCommand(options);
-  const hostKind = resolveManagedHostKind(options, codeCommand);
-  const hostId = options.hostId ?? buildHostId({ fixture, hostKind });
-  const ttlMs = readTtlMs(options.ttlMs);
-  const intervalMs = Number.isFinite(Number(options.intervalMs)) && Number(options.intervalMs) > 0
-    ? Number(options.intervalMs)
-    : 30_000;
-  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
-    return {
-      ok: true,
-      hostId,
-      hostKind,
-      watching: false,
-      reason: "ttl-disabled"
-    };
-  }
-
-  writeJsonAtomic(getWatchdogPath(hostId), {
-    pid: process.pid,
-    hostId,
-    hostKind,
-    fixture,
-    ttlMs,
-    intervalMs,
-    startedAt: new Date().toISOString()
-  });
-
-  while (true) {
-    const metadata = readMetadataByHostId(hostId);
-    if (!metadata) {
-      return {
-        ok: true,
-        hostId,
-        hostKind,
-        stopped: false,
-        reason: "metadata-not-found"
-      };
-    }
-    const status = await getManagedServeWebHostStatus({ fixture, hostId, vsix: metadata.vsix, hostKind: metadata.hostKind ?? hostKind });
-    if (!status.running) {
-      return {
-        ok: true,
-        hostId,
-        hostKind: metadata.hostKind ?? hostKind,
-        stopped: false,
-        reason: "not-running"
-      };
-    }
-    if (isMetadataExpired(metadata, ttlMs)) {
-      const result = await stopManagedServeWebHost({ fixture, hostId });
-      return {
-        ok: true,
-        hostId,
-        hostKind: metadata.hostKind ?? hostKind,
-        stopped: result.stopped === true,
-        reason: "ttl-expired"
-      };
-    }
-    await sleep(intervalMs);
-  }
-}
-
-function startManagedServeWebWatchdog(options) {
-  const ttlMs = readTtlMs(options.ttlMs);
-  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
-    return;
-  }
-  const existing = readJsonFile(getWatchdogPath(options.hostId));
-  if (existing && isProcessAlive(existing.pid)) {
-    return;
-  }
-  const stdoutPath = path.join(options.logsDir, "watchdog.stdout.txt");
-  const stderrPath = path.join(options.logsDir, "watchdog.stderr.txt");
-  const nodeRuntime = resolvePackagedNodeRuntime();
-  startLoggedProcess(nodeRuntime.command, [
-    path.join(__dirname, "manage-serve-web-host.cjs"),
-    "watchdog",
-    "--fixture",
-    options.fixture,
-    ...(options.ideCommand ? ["--ide-command", options.ideCommand] : []),
-    ...(options.hostKind ? ["--host-kind", options.hostKind] : []),
-    "--ttl-ms",
-    String(ttlMs),
-    "--interval-ms",
-    String(options.intervalMs ?? 30_000)
-  ], {
-    cwd: rootDir,
-    detached: true,
-    stdoutPath,
-    stderrPath
-  });
-}
-
-function buildStartSummary(input) {
-  const codeCommand = input.codeCommand && typeof input.codeCommand === "object"
-    ? commandDisplayName(input.codeCommand)
-    : input.codeCommand;
-  const codeCommandSource = input.codeCommandSource
-    ?? (input.codeCommand && typeof input.codeCommand === "object" ? input.codeCommand.source : null);
-  const summaryPath = input.reused
-    ? path.join(input.runDir, `reuse-${timestampForPath()}.json`)
-    : path.join(input.runDir, "summary.json");
-  const summary = {
-    ok: input.ok,
-    reused: input.reused,
-    hostId: input.hostId,
-    kind: "serve-web-headless-client",
-    startedAt: new Date(input.startedAt).toISOString(),
-    finishedAt: new Date().toISOString(),
-    durationMs: Date.now() - input.startedAt,
-    fixture: input.fixture,
-    vsix: input.vsix,
-    vsixFingerprint: input.metadata?.vsixFingerprint ?? fingerprintFile(input.vsix),
-    codeCommand,
-    codeCommandSource,
-    hostKind: input.hostKind ?? input.metadata?.hostKind ?? "vscode-serve-web",
-    runDir: input.runDir,
-    metadata: input.metadata,
-    registryEntry: input.registryEntry ?? null,
-    artifacts: {
-      logsDir: input.logsDir,
-      stepsDir: input.stepsDir,
-      summaryPath
-    },
-    steps: input.steps.map((record) => ({
-      name: record.name,
-      ok: record.ok,
-      durationMs: record.durationMs,
-      path: record.path
-    })),
-    failures: input.failures
-  };
-  writeJson(summaryPath, summary);
-  return summary;
-}
-
-module.exports = {
-  buildHostId,
-  cleanupExpiredManagedServeWebHosts,
-  getManagedServeWebHostStatus,
-  killManagedServeWebHosts,
-  runManagedServeWebWatchdog,
-  startManagedServeWebHost,
-  stopManagedServeWebHost
-};
+
+function readTtlMs(value, fallbackMs = 15 * 60_000) {
+  if (value === null || value === undefined || value === "") {
+    return fallbackMs;
+  }
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : fallbackMs;
+}
+
+function metadataLastActivityMs(metadata) {
+  const raw = metadata?.lastActivityAt ?? metadata?.updatedAt ?? metadata?.startedAt;
+  const parsed = typeof raw === "string" ? Date.parse(raw) : NaN;
+  return Number.isFinite(parsed) ? parsed : 0;
+}
+
+function isMetadataExpired(metadata, ttlMs, now = Date.now()) {
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+    return false;
+  }
+  const lastActivityMs = metadataLastActivityMs(metadata);
+  return lastActivityMs > 0 && now - lastActivityMs > ttlMs;
+}
+
+async function tryFetch(url) {
+  try {
+    const response = await fetch(url);
+    return {
+      ok: response.ok,
+      status: response.status,
+      contentType: response.headers.get("content-type")
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+function bridgeHealthUrl(registryEntry) {
+  if (!registryEntry || typeof registryEntry.host !== "string" || !Number.isInteger(registryEntry.port)) {
+    return null;
+  }
+
+  return `http://${registryEntry.host}:${registryEntry.port}/health`;
+}
+
+async function tryPostJson(url, body = {}) {
+  if (!url) {
+    return {
+      ok: false,
+      error: "missing url"
+    };
+  }
+
+  try {
+    const response = await fetch(url, {
+      method: "POST",
+      headers: {
+        "Content-Type": "application/json"
+      },
+      body: JSON.stringify(body)
+    });
+    return {
+      ok: response.ok,
+      status: response.status,
+      contentType: response.headers.get("content-type")
+    };
+  } catch (error) {
+    return {
+      ok: false,
+      error: error instanceof Error ? error.message : String(error)
+    };
+  }
+}
+
+async function waitFor(name, timeoutMs, pollMs, getState, isReady) {
+  const startedAt = Date.now();
+  const attempts = [];
+
+  while (Date.now() - startedAt <= timeoutMs) {
+    const state = await getState();
+    attempts.push(state);
+    if (isReady(state)) {
+      return {
+        ok: true,
+        durationMs: Date.now() - startedAt,
+        attempts: attempts.length,
+        state
+      };
+    }
+    await sleep(pollMs);
+  }
+
+  return {
+    ok: false,
+    durationMs: Date.now() - startedAt,
+    attempts: attempts.length,
+    error: `${name} did not become ready within ${timeoutMs}ms.`,
+    lastState: attempts.at(-1) ?? null
+  };
+}
+
+async function allocatePort() {
+  return new Promise((resolve, reject) => {
+    const server = net.createServer();
+    server.once("error", reject);
+    server.listen(0, "127.0.0.1", () => {
+      const address = server.address();
+      const port = address && typeof address === "object" ? address.port : null;
+      server.close(() => {
+        if (Number.isInteger(port)) {
+          resolve(port);
+        } else {
+          reject(new Error("Failed to allocate a TCP port."));
+        }
+      });
+    });
+  });
+}
+
+async function acquireLock(hostId, timeoutMs = 15_000, staleMs = 120_000) {
+  const lockDir = getLockDir(hostId);
+  const startedAt = Date.now();
+  ensureDir(path.dirname(lockDir));
+
+  while (Date.now() - startedAt <= timeoutMs) {
+    try {
+      fs.mkdirSync(lockDir);
+      writeJson(path.join(lockDir, "owner.json"), {
+        pid: process.pid,
+        acquiredAt: new Date().toISOString()
+      });
+      return {
+        hostId,
+        lockDir,
+        release() {
+          fs.rmSync(lockDir, { recursive: true, force: true });
+        }
+      };
+    } catch (error) {
+      if (error && error.code === "EEXIST") {
+        const owner = readJsonFile(path.join(lockDir, "owner.json"));
+        const ownerPid = Number.isInteger(owner?.pid) ? owner.pid : null;
+        const ownerAlive = ownerPid !== null && isProcessAlive(ownerPid);
+        const stat = fs.statSync(lockDir);
+        if ((ownerPid !== null && !ownerAlive) || Date.now() - stat.mtimeMs > staleMs) {
+          fs.rmSync(lockDir, { recursive: true, force: true });
+          continue;
+        }
+        await sleep(250);
+        continue;
+      }
+      throw error;
+    }
+  }
+
+  throw new Error(`Timed out acquiring managed host lock: ${lockDir}`);
+}
+
+function getMatchingRegistryEntry(metadata) {
+  if (!metadata || typeof metadata.instanceId !== "string") {
+    return null;
+  }
+
+  return readRegistryEntries().find((entry) => entry.instanceId === metadata.instanceId) ?? null;
+}
+
+async function getManagedServeWebHostStatus(options = {}) {
+  if (options.all === true) {
+    return getAllManagedServeWebHostStatuses(options);
+  }
+
+  const fixture = path.resolve(options.fixture ?? defaultFixtureDir);
+  const codeCommand = resolveManagedIdeCommand(options);
+  const hostKind = resolveManagedHostKind(options, codeCommand);
+  const hostId = options.hostId ?? buildHostId({ fixture, hostKind });
+  const expectedVsix = options.vsix ? fingerprintFile(path.resolve(options.vsix)) : null;
+  const metadata = readMetadataByHostId(hostId);
+  if (!metadata) {
+    return {
+      ok: true,
+      hostId,
+      running: false,
+      healthy: false,
+      reason: "metadata-not-found"
+    };
+  }
+
+  const registryEntry = getMatchingRegistryEntry(metadata);
+  const rootUrl = metadata.rootUrl ?? (Number.isInteger(metadata.port) ? `http://127.0.0.1:${metadata.port}` : null);
+  const http = rootUrl ? await tryFetch(rootUrl) : { ok: false, error: "missing rootUrl" };
+  const bridgeHttp = registryEntry
+    ? await tryPostJson(bridgeHealthUrl(registryEntry))
+    : { ok: false, error: "missing registryEntry" };
+  const serveWebAlive = isProcessAlive(metadata.serveWebPid);
+  const browserAlive = isProcessAlive(metadata.browserPid);
+  const extensionHostAlive = registryEntry ? isProcessAlive(registryEntry.pid) : false;
+  const workspaceMatches = registryEntry ? workspaceMatchesFixture(registryEntry, fixture) : false;
+  const vsixMatches = expectedVsix ? fingerprintsMatch(metadata.vsixFingerprint, expectedVsix) : true;
+  const healthy = serveWebAlive && browserAlive && extensionHostAlive && http.ok === true && bridgeHttp.ok === true && workspaceMatches && vsixMatches;
+
+  return {
+    ok: true,
+    hostId,
+    running: serveWebAlive || browserAlive || extensionHostAlive,
+    healthy,
+    metadata,
+    health: {
+      serveWebAlive,
+      browserAlive,
+      extensionHostAlive,
+      workspaceMatches,
+      vsixMatches,
+      expectedVsix,
+      http,
+      bridgeHttp,
+      registryEntry
+    }
+  };
+}
+
+async function getAllManagedServeWebHostStatuses(options = {}) {
+  const entries = readAllManagedHostEntries();
+  const runtimes = [];
+  for (const entry of entries) {
+    const metadata = entry.metadata;
+    const status = await getManagedServeWebHostStatus({
+      ...options,
+      all: false,
+      hostId: entry.hostId,
+      fixture: metadata.fixture ?? defaultFixtureDir,
+      vsix: metadata.vsix,
+      hostKind: metadata.hostKind
+    });
+    runtimes.push(compactRuntimeStatus(status, metadata));
+  }
+  return {
+    ok: true,
+    all: true,
+    count: runtimes.length,
+    running: runtimes.filter((runtime) => runtime.running === true).length,
+    healthy: runtimes.filter((runtime) => runtime.healthy === true).length,
+    runtimes
+  };
+}
+
+async function startManagedServeWebHost(options = {}) {
+  const startedAt = Date.now();
+  const fixture = path.resolve(options.fixture ?? defaultFixtureDir);
+  const ttlMs = readTtlMs(options.ttlMs);
+  const intervalMs = Number.isFinite(Number(options.intervalMs)) && Number(options.intervalMs) > 0
+    ? Number(options.intervalMs)
+    : 30_000;
+  const waitMs = Number.isInteger(options.waitMs) ? options.waitMs : 45_000;
+  const pollMs = Number.isInteger(options.pollMs) ? options.pollMs : 500;
+  const vsix = path.resolve(options.vsix ?? defaultVsixPath);
+  let vsixFingerprint = null;
+  const reuse = options.reuse !== false;
+  const codeCommand = resolveManagedIdeCommand(options);
+  const hostKind = resolveManagedHostKind(options, codeCommand);
+  const hostId = options.hostId ?? buildHostId({ fixture, hostKind });
+  const runDir = path.resolve(options.runDir ?? path.join(defaultRunsDir, `${hostId}-${timestampForPath()}`));
+  const logsDir = path.join(runDir, "logs");
+  const stepsDir = path.join(runDir, "steps");
+  const userDataDir = path.join(runDir, "user-data");
+  const serverDataDir = path.join(runDir, "server-data");
+  const extensionsDir = path.join(runDir, "extensions");
+  const activeExtensionsDir = hostKind === "code-server" || process.platform === "win32"
+    ? extensionsDir
+    : path.join(serverDataDir, "extensions");
+  const ideEnv = buildIdeCommandEnv(runDir);
+  const steps = [];
+  const failures = [];
+  const beforeRegistry = readRegistryEntries();
+  const beforeInstanceIds = new Set(beforeRegistry.map((entry) => entry.instanceId));
+  let serveWebProcess = null;
+  let browserProcess = null;
+  let metadata = null;
+
+  ensureDir(logsDir);
+  ensureDir(stepsDir);
+  await cleanupExpiredManagedServeWebHosts({ ttlMs });
+
+  async function step(name, fn) {
+    const stepIndex = String(steps.length + 1).padStart(2, "0");
+    const stepPath = path.join(stepsDir, `${stepIndex}-${name.replace(/[^a-z0-9]+/gi, "-").toLowerCase()}.json`);
+    const startedStepAt = Date.now();
+    const record = {
+      name,
+      ok: false,
+      startedAt: new Date(startedStepAt).toISOString()
+    };
+
+    try {
+      record.detail = await fn();
+      record.ok = record.detail?.ok !== false;
+      if (!record.ok) {
+        failures.push(`${name}: ${record.detail?.error ?? "failed"}`);
+      }
+    } catch (error) {
+      record.ok = false;
+      record.error = error instanceof Error ? error.message : String(error);
+      failures.push(`${name}: ${record.error}`);
+    } finally {
+      record.durationMs = Date.now() - startedStepAt;
+      record.finishedAt = new Date().toISOString();
+      record.path = stepPath;
+      writeJson(stepPath, record);
+      steps.push(record);
+    }
+
+    return record;
+  }
+
+  const lock = await acquireLock(hostId, Math.max(90_000, waitMs + 45_000));
+  try {
+    await step("ensure fresh extension vsix", async () => {
+      const freshness = getExtensionVsixFreshness(vsix);
+      if (!freshness.supported) {
+        vsixFingerprint = fingerprintFile(vsix);
+        return {
+          ok: true,
+          skipped: true,
+          reason: freshness.reason,
+          vsix: freshness.vsix,
+          vsixFingerprint
+        };
+      }
+
+      if (!freshness.stale) {
+        vsixFingerprint = fingerprintFile(vsix);
+        return {
+          ok: true,
+          packaged: false,
+          stale: false,
+          vsix: freshness.vsix,
+          vsixMtimeMs: freshness.vsixMtimeMs,
+          newestInput: freshness.newestInput,
+          vsixFingerprint
+        };
+      }
+
+      const packageLock = await acquireLock("extension-vsix-package", 180_000, 300_000);
+      try {
+        const lockedFreshness = getExtensionVsixFreshness(vsix);
+        if (lockedFreshness.supported && !lockedFreshness.stale) {
+          vsixFingerprint = fingerprintFile(vsix);
+          return {
+            ok: true,
+            packaged: false,
+            packagedByOtherProcess: true,
+            stale: false,
+            vsix: lockedFreshness.vsix,
+            vsixMtimeMs: lockedFreshness.vsixMtimeMs,
+            newestInput: lockedFreshness.newestInput,
+            vsixFingerprint
+          };
+        }
+
+        const packageResult = packageExtensionVsix();
+        vsixFingerprint = fingerprintFile(vsix);
+        return {
+          ok: packageResult.status === 0 && Boolean(vsixFingerprint),
+          packaged: true,
+          stale: true,
+          status: packageResult.status,
+          error: packageResult.error ?? null,
+          stdoutTail: tail(packageResult.stdout),
+          stderrTail: tail(packageResult.stderr),
+          durationMs: packageResult.durationMs,
+          vsix: freshness.vsix,
+          previousVsixMtimeMs: freshness.vsixMtimeMs,
+          newestInput: freshness.newestInput,
+          vsixFingerprint
+        };
+      } finally {
+        packageLock.release();
+      }
+    });
+    if (failures.length > 0) {
+      return buildStartSummary({ ok: false, reused: false, startedAt, hostId, fixture, vsix, codeCommand, hostKind, runDir, logsDir, stepsDir, metadata, steps, failures, orphanCleanup: null });
+    }
+
+    const orphanCleanup = readMetadataByHostId(hostId) ? null : stopProcessesByCommandLineFragment(hostId);
+    if (reuse) {
+      const existingStatus = await getManagedServeWebHostStatus({ fixture, hostId, vsix, ideCommand: options.ideCommand, hostKind });
+      if (existingStatus.healthy) {
+        const updatedMetadata = {
+          ...existingStatus.metadata,
+          updatedAt: new Date().toISOString(),
+          lastActivityAt: new Date().toISOString(),
+          ttlMs,
+          watchdogIntervalMs: intervalMs
+        };
+        writeMetadata(hostId, updatedMetadata);
+        startManagedServeWebWatchdog({ fixture, hostId, ttlMs, intervalMs, logsDir: existingStatus.metadata.logsDir ?? logsDir, ideCommand: options.ideCommand, hostKind });
+        return buildStartSummary({
+          ok: true,
+          reused: true,
+          startedAt,
+          hostId,
+          fixture,
+          vsix,
+          codeCommand,
+          hostKind,
+          runDir: existingStatus.metadata.runDir ?? runDir,
+          logsDir: existingStatus.metadata.logsDir ?? logsDir,
+          stepsDir: existingStatus.metadata.stepsDir ?? stepsDir,
+          metadata: updatedMetadata,
+          steps,
+          failures,
+          orphanCleanup
+        });
+      }
+      if (existingStatus.metadata) {
+        await stopManagedServeWebHost({ fixture, hostId, removeMetadataOnlyIfKnown: true });
+      }
+    } else {
+      await stopManagedServeWebHost({ fixture, hostId, removeMetadataOnlyIfKnown: true });
+    }
+
+    await step("prepare profile", async () => {
+      ensureDir(path.join(runDir, "home"));
+      ensureDir(path.join(runDir, "cli-data"));
+      ensureDir(path.join(userDataDir, "User"));
+      ensureDir(path.join(serverDataDir, "data", "User"));
+      ensureDir(serverDataDir);
+      ensureDir(extensionsDir);
+      ensureDir(activeExtensionsDir);
+      const settings = {
+        "security.workspace.trust.enabled": false,
+        "workbench.startupEditor": "none"
+      };
+      writeJson(path.join(userDataDir, "User", "settings.json"), settings);
+      writeJson(path.join(serverDataDir, "data", "User", "settings.json"), settings);
+      return {
+        ok: true,
+        runDir,
+        userDataDir,
+        serverDataDir,
+        extensionsDir
+      };
+    });
+
+    await step("install extension", async () => {
+      if (!fs.existsSync(vsix)) {
+        return {
+          ok: false,
+          error: `VSIX does not exist: ${vsix}`
+        };
+      }
+      const result = runCommand(codeCommand, [
+        "--extensions-dir",
+        activeExtensionsDir,
+        "--install-extension",
+        vsix,
+        "--force"
+      ], { timeoutMs: 60_000, env: ideEnv });
+      const stdoutPath = path.join(logsDir, "install-extension.stdout.txt");
+      const stderrPath = path.join(logsDir, "install-extension.stderr.txt");
+      writeText(stdoutPath, result.stdout);
+      writeText(stderrPath, result.stderr);
+      return {
+        ok: result.status === 0,
+        status: result.status,
+        durationMs: result.durationMs,
+        stdoutPath,
+        stderrPath,
+        stdoutTail: tail(result.stdout),
+        stderrTail: tail(result.stderr),
+        error: result.error
+      };
+    });
+    if (failures.length > 0) {
+      return buildStartSummary({ ok: false, reused: false, startedAt, hostId, fixture, vsix, codeCommand, hostKind, runDir, logsDir, stepsDir, metadata, steps, failures, orphanCleanup });
+    }
+
+    const port = Number.isInteger(options.port) ? options.port : await allocatePort();
+    const rootUrl = `http://127.0.0.1:${port}`;
+
+    const serveWebStdoutPath = path.join(logsDir, "serve-web.stdout.txt");
+    const serveWebStderrPath = path.join(logsDir, "serve-web.stderr.txt");
+
+    await step("start serve-web", async () => {
+      const args = hostKind === "code-server"
+        ? [
+            "--auth",
+            "none",
+            "--bind-addr",
+            `127.0.0.1:${port}`,
+            "--disable-workspace-trust",
+            "--disable-telemetry",
+            "--disable-update-check",
+            "--user-data-dir",
+            userDataDir,
+            "--extensions-dir",
+            activeExtensionsDir,
+            fixture
+          ]
+        : [
+            "--user-data-dir",
+            userDataDir,
+            ...(process.platform === "win32" ? ["--extensions-dir", activeExtensionsDir] : []),
+            "serve-web",
+            "--accept-server-license-terms",
+            "--host",
+            "127.0.0.1",
+            "--port",
+            String(port),
+            "--without-connection-token",
+            "--default-folder",
+            fixture,
+            "--server-data-dir",
+            serverDataDir,
+            "--log",
+            "trace",
+            ...(process.platform !== "win32" ? ["--cli-data-dir", ideEnv.VSCODE_CLI_DATA_DIR ?? path.join(runDir, "cli-data")] : [])
+          ];
+      serveWebProcess = startLoggedCommand(codeCommand, args, {
+        stdoutPath: serveWebStdoutPath,
+        stderrPath: serveWebStderrPath,
+        detached: true,
+        env: ideEnv
+      });
+      return {
+        ok: true,
+        pid: serveWebProcess.child.pid ?? null,
+        command: commandDisplayName(codeCommand),
+        commandSource: codeCommand.source ?? null,
+        hostKind,
+        args,
+        stdoutPath: serveWebStdoutPath,
+        stderrPath: serveWebStderrPath
+      };
+    });
+
+    await step("wait for serve-web http", async () => {
+      return waitFor(
+        "serve-web http",
+        waitMs,
+        pollMs,
+        () => tryFetch(rootUrl),
+        (state) => state.ok === true
+      );
+    });
+
+    await step("wait for extension host agent", async () => {
+      return waitFor(
+        "extension host agent",
+        waitMs,
+        pollMs,
+        () => {
+          const stdout = readTextIfExists(serveWebStdoutPath);
+          const stderr = readTextIfExists(serveWebStderrPath);
+          const userDataLogs = readRecentLogText(path.join(userDataDir, "logs"));
+          const serverDataLogs = readRecentLogText(path.join(serverDataDir, "logs"));
+          const combined = `${stdout}\n${stderr}\n${userDataLogs}\n${serverDataLogs}`;
+          return {
+            ready: combined.includes("Extension host agent started")
+              || combined.includes("Extension host agent listening"),
+            stdoutTail: tail(stdout, 1000),
+            stderrTail: tail(stderr, 1000),
+            logTail: tail(`${userDataLogs}\n${serverDataLogs}`, 1000)
+          };
+        },
+        (state) => state.ready === true
+      );
+    });
+    if (failures.length > 0) {
+      stopProcessTree(serveWebProcess?.child?.pid);
+      return buildStartSummary({ ok: false, reused: false, startedAt, hostId, fixture, vsix, codeCommand, hostKind, runDir, logsDir, stepsDir, metadata, steps, failures, orphanCleanup });
+    }
+
+    await step("open headless browser client", async () => {
+      const chromePath = resolveChromePath(options.chromePath);
+      if (!chromePath) {
+        return {
+          ok: false,
+          error: "Chrome or Edge executable was not found."
+        };
+      }
+
+      const profileDir = path.join(runDir, "headless-browser-profile");
+      const stdoutPath = path.join(logsDir, "headless-browser.stdout.txt");
+      const stderrPath = path.join(logsDir, "headless-browser.stderr.txt");
+      const url = `${rootUrl}/?folder=${encodeURIComponent(fixture)}`;
+      const browserArgs = [
+        "--headless=new",
+        "--disable-gpu",
+        "--disable-dev-shm-usage",
+        "--disable-background-networking",
+        "--disable-sync",
+        "--no-sandbox",
+        "--remote-debugging-port=0",
+        "--no-first-run",
+        "--no-default-browser-check",
+        `--user-data-dir=${profileDir}`,
+        url
+      ];
+      if (process.platform === "win32") {
+        const scriptPath = writeWindowsDetachedScript(chromePath, browserArgs, {
+          cwd: rootDir,
+          stdoutPath,
+          stderrPath
+        });
+        browserProcess = startWindowsHiddenScript(scriptPath, {
+          cwd: rootDir,
+          stdoutPath,
+          stderrPath
+        });
+      } else {
+        const stdoutFd = fs.openSync(stdoutPath, "a");
+        const stderrFd = fs.openSync(stderrPath, "a");
+        browserProcess = spawn(chromePath, browserArgs, {
+          cwd: rootDir,
+          detached: true,
+          windowsHide: true,
+          stdio: ["ignore", stdoutFd, stderrFd]
+        });
+      }
+      browserProcess.on("error", () => {
+        // Later registry/health waits surface browser startup failures.
+      });
+      browserProcess.unref();
+
+      return {
+        ok: true,
+        pid: browserProcess.pid ?? null,
+        chromePath,
+        profileDir,
+        devToolsActivePortPath: path.join(profileDir, "DevToolsActivePort"),
+        stdoutPath,
+        stderrPath,
+        url
+      };
+    });
+
+    await step("wait for bridge registry entry", async () => {
+      const waitResult = await waitFor(
+        "fresh bridge registry entry",
+        waitMs,
+        pollMs,
+        () => {
+          const entries = readRegistryEntries();
+          const matchingFreshEntries = entries.filter(
+            (entry) => !beforeInstanceIds.has(entry.instanceId) && workspaceMatchesFixture(entry, fixture)
+          );
+          return {
+            ok: matchingFreshEntries.length > 0,
+            entry: matchingFreshEntries[0] ?? null,
+            entryCount: entries.length,
+            matchingFreshCount: matchingFreshEntries.length
+          };
+        },
+        (state) => state.ok === true
+      );
+      return waitResult;
+    });
+    if (failures.length > 0) {
+      stopProcessTree(browserProcess?.pid);
+      stopProcessTree(serveWebProcess?.child?.pid);
+      return buildStartSummary({ ok: false, reused: false, startedAt, hostId, fixture, vsix, codeCommand, hostKind, runDir, logsDir, stepsDir, metadata, steps, failures, orphanCleanup });
+    }
+
+    const registryEntry = steps.at(-1)?.detail?.state?.entry ?? null;
+    await step("wait for bridge http health", async () => {
+      return waitFor(
+        "bridge http health",
+        waitMs,
+        pollMs,
+        () => tryPostJson(bridgeHealthUrl(registryEntry)),
+        (state) => state.ok === true
+      );
+    });
+    if (failures.length > 0) {
+      stopProcessTree(browserProcess?.pid);
+      stopProcessTree(serveWebProcess?.child?.pid);
+      return buildStartSummary({ ok: false, reused: false, startedAt, hostId, fixture, vsix, codeCommand, hostKind, runDir, logsDir, stepsDir, metadata, registryEntry, steps, failures, orphanCleanup });
+    }
+
+    metadata = {
+      hostId,
+      kind: "serve-web-headless-client",
+      hostKind,
+      fixture,
+      vsix,
+      vsixFingerprint,
+      codeCommand: commandDisplayName(codeCommand),
+      codeCommandSource: codeCommand.source ?? null,
+      runDir,
+      logsDir,
+      stepsDir,
+      port,
+      rootUrl,
+      serveWebPid: serveWebProcess?.child?.pid ?? null,
+      browserPid: browserProcess?.pid ?? null,
+      instanceId: registryEntry?.instanceId ?? null,
+      registryPath: registryEntry?.registryPath ?? null,
+      workspaceFolders: registryEntry?.workspaceFolders ?? [],
+      startedAt: new Date(startedAt).toISOString(),
+      updatedAt: new Date().toISOString()
+    };
+    metadata.lastActivityAt = metadata.updatedAt;
+    metadata.ttlMs = ttlMs;
+    metadata.watchdogIntervalMs = intervalMs;
+    writeMetadata(hostId, metadata);
+    startManagedServeWebWatchdog({ fixture, hostId, ttlMs, intervalMs, logsDir, ideCommand: options.ideCommand, hostKind });
+
+    return buildStartSummary({
+      ok: true,
+      reused: false,
+      startedAt,
+      hostId,
+      fixture,
+      vsix,
+      codeCommand: commandDisplayName(codeCommand),
+      codeCommandSource: codeCommand.source ?? null,
+      hostKind,
+      runDir,
+      logsDir,
+      stepsDir,
+      metadata,
+      registryEntry,
+      steps,
+      failures,
+      orphanCleanup
+    });
+  } finally {
+    lock.release();
+  }
+}
+
+async function stopManagedServeWebHost(options = {}) {
+  if (options.all === true) {
+    return stopAllManagedServeWebHosts(options);
+  }
+
+  const fixture = path.resolve(options.fixture ?? defaultFixtureDir);
+  const codeCommand = resolveManagedIdeCommand(options);
+  const hostKind = resolveManagedHostKind(options, codeCommand);
+  const hostId = options.hostId ?? buildHostId({ fixture, hostKind });
+  const metadata = readMetadataByHostId(hostId);
+  if (!metadata) {
+    const orphanCleanup = stopProcessesByCommandLineFragment(hostId);
+    return {
+      ok: true,
+      hostId,
+      hostKind,
+      stopped: (orphanCleanup.killed ?? 0) > 0,
+      reason: (orphanCleanup.killed ?? 0) > 0 ? "orphan-processes-stopped" : "metadata-not-found",
+      orphanCleanup
+    };
+  }
+
+  const stopResults = [];
+  const watchdog = readJsonFile(getWatchdogPath(hostId));
+  if (watchdog && Number.isInteger(watchdog.pid) && watchdog.pid !== process.pid) {
+    stopResults.push({
+      name: "watchdog",
+      ...stopProcessTree(watchdog.pid)
+    });
+  }
+  if (Number.isInteger(metadata.browserPid)) {
+    stopResults.push({
+      name: "headless-browser",
+      ...stopProcessTree(metadata.browserPid)
+    });
+  }
+  if (Number.isInteger(metadata.serveWebPid)) {
+    stopResults.push({
+      name: "serve-web",
+      ...stopProcessTree(metadata.serveWebPid)
+    });
+  }
+  if (typeof metadata.runDir === "string") {
+    stopResults.push({
+      name: "run-dir-processes",
+      ...stopProcessesByCommandLineFragment(metadata.runDir)
+    });
+  }
+
+  let registryCleanup = {
+    removed: false,
+    path: metadata.registryPath ?? null
+  };
+  if (typeof metadata.registryPath === "string") {
+    try {
+      fs.rmSync(metadata.registryPath, { force: true });
+      registryCleanup = {
+        removed: true,
+        path: metadata.registryPath
+      };
+    } catch (error) {
+      registryCleanup = {
+        removed: false,
+        path: metadata.registryPath,
+        error: error instanceof Error ? error.message : String(error)
+      };
+    }
+  }
+
+  removeMetadata(hostId);
+  fs.rmSync(getWatchdogPath(hostId), { force: true });
+  return {
+    ok: true,
+    hostId,
+    hostKind: metadata.hostKind ?? hostKind,
+    stopped: true,
+    metadata,
+    stopResults,
+    registryCleanup
+  };
+}
+
+async function stopAllManagedServeWebHosts(options = {}) {
+  const entries = readAllManagedHostEntries();
+  const stopped = [];
+  for (const entry of entries) {
+    const metadata = entry.metadata;
+    const result = await stopManagedServeWebHost({
+      ...options,
+      all: false,
+      hostId: entry.hostId,
+      fixture: metadata.fixture ?? defaultFixtureDir,
+      hostKind: metadata.hostKind
+    });
+    stopped.push({
+      hostId: entry.hostId,
+      hostKind: result.hostKind ?? metadata.hostKind ?? null,
+      fixture: metadata.fixture ?? null,
+      runDir: metadata.runDir ?? null,
+      stopped: result.stopped === true,
+      reason: result.reason ?? null
+    });
+  }
+  return {
+    ok: true,
+    all: true,
+    count: stopped.length,
+    stopped: stopped.filter((item) => item.stopped === true).length,
+    runtimes: stopped
+  };
+}
+
+async function killManagedServeWebHosts(options = {}) {
+  if (options.all !== true) {
+    return {
+      ok: false,
+      code: "RUNTIME_KILL_REQUIRES_ALL",
+      error: "runtime kill currently requires --all."
+    };
+  }
+  const stopResult = await stopAllManagedServeWebHosts(options);
+  const orphanCleanup = stopAibOwnedRuntimeProcesses();
+  return {
+    ok: true,
+    all: true,
+    stop: stopResult,
+    killed: orphanCleanup.killed ?? 0,
+    orphanCleanup
+  };
+}
+
+async function cleanupExpiredManagedServeWebHosts(options = {}) {
+  const ttlMs = readTtlMs(options.ttlMs);
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+    return {
+      ok: true,
+      ttlMs,
+      stopped: []
+    };
+  }
+  if (!fs.existsSync(managedRootDir)) {
+    return {
+      ok: true,
+      ttlMs,
+      stopped: []
+    };
+  }
+
+  const stopped = [];
+  const activeRunDirs = [];
+  for (const item of fs.readdirSync(managedRootDir, { withFileTypes: true })) {
+    if (!item.isDirectory()) {
+      continue;
+    }
+    const hostId = item.name;
+    const metadata = readMetadataByHostId(hostId);
+    if (!metadata || !isMetadataExpired(metadata, ttlMs)) {
+      if (metadata && typeof metadata.runDir === "string" && metadata.runDir.length > 0) {
+        activeRunDirs.push(metadata.runDir);
+      }
+      continue;
+    }
+    const result = await stopManagedServeWebHost({ hostId, fixture: metadata.fixture ?? defaultFixtureDir });
+    stopped.push({
+      hostId,
+      fixture: metadata.fixture ?? null,
+      lastActivityAt: metadata.lastActivityAt ?? metadata.updatedAt ?? null,
+      stopped: result.stopped === true
+    });
+  }
+  const orphanCleanup = stopOrphanedPackagedRuntimeProcesses(activeRunDirs);
+
+  return {
+    ok: true,
+    ttlMs,
+    stopped,
+    orphanCleanup
+  };
+}
+
+async function runManagedServeWebWatchdog(options = {}) {
+  const fixture = path.resolve(options.fixture ?? defaultFixtureDir);
+  const codeCommand = resolveManagedIdeCommand(options);
+  const hostKind = resolveManagedHostKind(options, codeCommand);
+  const hostId = options.hostId ?? buildHostId({ fixture, hostKind });
+  const ttlMs = readTtlMs(options.ttlMs);
+  const intervalMs = Number.isFinite(Number(options.intervalMs)) && Number(options.intervalMs) > 0
+    ? Number(options.intervalMs)
+    : 30_000;
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+    return {
+      ok: true,
+      hostId,
+      hostKind,
+      watching: false,
+      reason: "ttl-disabled"
+    };
+  }
+
+  writeJsonAtomic(getWatchdogPath(hostId), {
+    pid: process.pid,
+    hostId,
+    hostKind,
+    fixture,
+    ttlMs,
+    intervalMs,
+    startedAt: new Date().toISOString()
+  });
+
+  while (true) {
+    const metadata = readMetadataByHostId(hostId);
+    if (!metadata) {
+      return {
+        ok: true,
+        hostId,
+        hostKind,
+        stopped: false,
+        reason: "metadata-not-found"
+      };
+    }
+    const status = await getManagedServeWebHostStatus({ fixture, hostId, vsix: metadata.vsix, hostKind: metadata.hostKind ?? hostKind });
+    if (!status.running) {
+      return {
+        ok: true,
+        hostId,
+        hostKind: metadata.hostKind ?? hostKind,
+        stopped: false,
+        reason: "not-running"
+      };
+    }
+    if (isMetadataExpired(metadata, ttlMs)) {
+      const result = await stopManagedServeWebHost({ fixture, hostId });
+      return {
+        ok: true,
+        hostId,
+        hostKind: metadata.hostKind ?? hostKind,
+        stopped: result.stopped === true,
+        reason: "ttl-expired"
+      };
+    }
+    await sleep(intervalMs);
+  }
+}
+
+function startManagedServeWebWatchdog(options) {
+  const ttlMs = readTtlMs(options.ttlMs);
+  if (!Number.isFinite(ttlMs) || ttlMs <= 0) {
+    return;
+  }
+  const existing = readJsonFile(getWatchdogPath(options.hostId));
+  if (existing && isProcessAlive(existing.pid)) {
+    return;
+  }
+  const stdoutPath = path.join(options.logsDir, "watchdog.stdout.txt");
+  const stderrPath = path.join(options.logsDir, "watchdog.stderr.txt");
+  const nodeRuntime = resolvePackagedNodeRuntime();
+  startLoggedProcess(nodeRuntime.command, [
+    path.join(__dirname, "manage-serve-web-host.cjs"),
+    "watchdog",
+    "--fixture",
+    options.fixture,
+    ...(options.ideCommand ? ["--ide-command", options.ideCommand] : []),
+    ...(options.hostKind ? ["--host-kind", options.hostKind] : []),
+    "--ttl-ms",
+    String(ttlMs),
+    "--interval-ms",
+    String(options.intervalMs ?? 30_000)
+  ], {
+    cwd: rootDir,
+    detached: true,
+    stdoutPath,
+    stderrPath
+  });
+}
+
+function buildStartSummary(input) {
+  const codeCommand = input.codeCommand && typeof input.codeCommand === "object"
+    ? commandDisplayName(input.codeCommand)
+    : input.codeCommand;
+  const codeCommandSource = input.codeCommandSource
+    ?? (input.codeCommand && typeof input.codeCommand === "object" ? input.codeCommand.source : null);
+  const summaryPath = input.reused
+    ? path.join(input.runDir, `reuse-${timestampForPath()}.json`)
+    : path.join(input.runDir, "summary.json");
+  const summary = {
+    ok: input.ok,
+    reused: input.reused,
+    hostId: input.hostId,
+    kind: "serve-web-headless-client",
+    startedAt: new Date(input.startedAt).toISOString(),
+    finishedAt: new Date().toISOString(),
+    durationMs: Date.now() - input.startedAt,
+    fixture: input.fixture,
+    vsix: input.vsix,
+    vsixFingerprint: input.metadata?.vsixFingerprint ?? fingerprintFile(input.vsix),
+    codeCommand,
+    codeCommandSource,
+    hostKind: input.hostKind ?? input.metadata?.hostKind ?? "vscode-serve-web",
+    runDir: input.runDir,
+    metadata: input.metadata,
+    registryEntry: input.registryEntry ?? null,
+    artifacts: {
+      logsDir: input.logsDir,
+      stepsDir: input.stepsDir,
+      summaryPath
+    },
+    orphanCleanup: input.orphanCleanup ?? null,
+    steps: input.steps.map((record) => ({
+      name: record.name,
+      ok: record.ok,
+      durationMs: record.durationMs,
+      path: record.path
+    })),
+    failures: input.failures
+  };
+  writeJson(summaryPath, summary);
+  return summary;
+}
+
+module.exports = {
+  buildHostId,
+  cleanupExpiredManagedServeWebHosts,
+  getManagedServeWebHostStatus,
+  killManagedServeWebHosts,
+  runManagedServeWebWatchdog,
+  startManagedServeWebHost,
+  stopManagedServeWebHost
+};