@automaton-labs/aib 0.0.1

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

@@ -0,0 +1,1790 @@
+#!/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)
+    };
+  }
+
+  try {
+    if (process.platform !== "win32") {
+      process.kill(-pid, "SIGTERM");
+    } else {
+      process.kill(pid, "SIGTERM");
+    }
+    if (process.platform !== "win32" && !waitForProcessExit(pid, 2000)) {
+      try {
+        process.kill(-pid, "SIGKILL");
+      } catch {
+        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 (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)
+  };
+}
+
+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)
+  };
+}
+
+function stopAibOwnedRuntimeProcessesUnix() {
+  const roots = [
+    rootDir,
+    path.join(rootDir, "packages", "cli")
+  ].map((item) => String(item));
+  const result = run("ps", ["-eo", "pid=,args="], { timeoutMs: 10_000 });
+  if (result.status !== 0) {
+    return {
+      attempted: true,
+      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) => isAibOwnedRuntimeCommandLine(row.commandLine, roots))
+    .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,
+    killed,
+    status: errors.length === 0 ? 0 : 1,
+    error: errors.join("; ") || null
+  };
+}
+
+function isAibOwnedRuntimeCommandLine(commandLine, roots) {
+  if (!commandLine) {
+    return false;
+  }
+  const underAibRoot = roots.some((root) => root && commandLine.includes(root));
+  if (!underAibRoot) {
+    return false;
+  }
+  const hasRunMarker = commandLine.includes("managed-host-runs");
+  const isAibWatchdog = commandLine.includes("manage-serve-web-host.cjs") && commandLine.includes("watchdog");
+  const isPackagedRuntime =
+    commandLine.includes("/runtimes/code-server/") ||
+    commandLine.includes("\\runtimes\\code-server\\") ||
+    commandLine.includes("/runtimes/browser/") ||
+    commandLine.includes("\\runtimes\\browser\\");
+  return hasRunMarker || isAibWatchdog || isPackagedRuntime;
+}
+
+function sleepSync(ms) {
+  try {
+    Atomics.wait(new Int32Array(new SharedArrayBuffer(4)), 0, 0, ms);
+  } catch {
+    // Best-effort delay only.
+  }
+}
+
+function waitForProcessExit(pid, timeoutMs) {
+  const deadline = Date.now() + timeoutMs;
+  while (Date.now() < deadline) {
+    if (!isProcessAlive(pid)) {
+      return true;
+    }
+    sleepSync(50);
+  }
+  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
+};