@schlenkr/ragents 0.1.4 → 0.1.6

package/packages/workspace-executor/src/files.ts

@@ -0,0 +1,287 @@
+import { watch } from "node:fs";
+import { lstat, mkdir, readdir, readFile, realpath, writeFile } from "node:fs/promises";
+import path from "node:path";
+import { WorkspaceOperationError } from "./errors.js";
+import type { WorkspaceModuleFactory, WorkspaceOperation } from "./module.js";
+import { aliasOf, aliasedRoot, containsWorkspacePath, unknownAliasError, type OperationFootprint } from "./paths.js";
+
+export const FILE_LIST_LIMIT = 500;
+
+export const FILE_READ_LIMIT = 256 * 1024;
+
+const WATCH_DEBOUNCE_MS = 150;
+
+export const FILE_OPERATIONS = {
+  list: "files.list",
+  read: "files.read",
+  watch: "files.watch",
+  attach: "files.attach",
+} as const;
+
+/** Der Unterordner der Wurzel, in dem angehängte Dateien eines Runs liegen. */
+export const ATTACHMENT_DIRECTORY = "attachments";
+
+export interface FileEntry {
+  name: string;
+  kind: "directory" | "file";
+  size: number;
+  modifiedAt: string;
+}
+
+export interface FileListing {
+  /** Der echte Pfad der Wurzel auf dieser Maschine. */
+  location: string;
+  path: string;
+  entries: FileEntry[];
+  truncated: boolean;
+}
+
+export type FileText =
+  | { path: string; size: number; previewable: true; content: string }
+  | { path: string; size: number; previewable: false; reason: string };
+
+/** Erst `ready`, sobald die Beobachtung steht, danach je entprellter Änderung `changed`. */
+export type FileWatchProgress = { kind: "ready" } | { kind: "changed" };
+
+export interface FileWatchListener {
+  onChange: () => void;
+  onError: (error: Error) => void;
+}
+
+const invalid = (message: string): WorkspaceOperationError => new WorkspaceOperationError("workspace-path-invalid", message, 400);
+
+const notFound = (message: string): WorkspaceOperationError => new WorkspaceOperationError("workspace-path-not-found", message, 404);
+
+const missing = (error: unknown): boolean => {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === "ENOENT" || code === "ENOTDIR";
+};
+
+/** Ein Pfad unterhalb einer Wurzel: relativ, mit `/` getrennt und ohne `..`; `.` und leere Abschnitte fallen weg. */
+export const relativeWorkspacePath = (value: string): string => {
+  const segments = value.split("/").filter((segment) => segment !== "" && segment !== ".");
+  if (value.includes("\0") || value.includes("\\") || path.isAbsolute(value) || segments.includes("..")) {
+    throw invalid(`Ungültiger Pfad: ${value}`);
+  }
+  return segments.join("/");
+};
+
+const realRoot = async (root: string): Promise<string> => {
+  try {
+    return await realpath(root);
+  } catch (error) {
+    if (missing(error)) throw notFound(`Den Ordner ${root} gibt es nicht`);
+    throw error;
+  }
+};
+
+/** Löst einen geprüften relativen Pfad auf; ein Symlink darf nicht aus der Wurzel führen. */
+const inside = async (base: string, relative: string): Promise<string> => {
+  let real: string;
+  try {
+    real = await realpath(relative ? path.join(base, ...relative.split("/")) : base);
+  } catch (error) {
+    if (missing(error)) throw notFound(`Nicht gefunden: ${relative || "."}`);
+    throw error;
+  }
+  if (!containsWorkspacePath(base, real)) throw invalid(`Pfad außerhalb des Arbeitsverzeichnisses: ${relative}`);
+  return real;
+};
+
+/** Ein Eintrag, der zwischen Auflisten und Abfragen verschwindet, gehört nicht mehr zum Ordner. */
+const entryOf = async (directory: string, name: string, isDirectory: boolean): Promise<FileEntry | undefined> => {
+  try {
+    const info = await lstat(path.join(directory, name));
+    return { name, kind: isDirectory ? "directory" : "file", size: info.size, modifiedAt: info.mtime.toISOString() };
+  } catch (error) {
+    if (missing(error)) return undefined;
+    throw error;
+  }
+};
+
+const byKindThenName = (left: FileEntry, right: FileEntry): number =>
+  (left.kind === right.kind ? 0 : left.kind === "directory" ? -1 : 1)
+  || left.name.localeCompare(right.name, "de");
+
+const directoryIn = async (base: string, checked: string): Promise<string> => {
+  const directory = await inside(base, checked);
+  if (!(await lstat(directory)).isDirectory()) throw invalid(`Kein Verzeichnis: ${checked || "."}`);
+  return directory;
+};
+
+/** Der echte Pfad eines Ordners unterhalb der Wurzel, geprüft wie jeder Pfad dieses Moduls. */
+export const workspaceDirectory = async (root: string, relative: string): Promise<string> =>
+  directoryIn(await realRoot(root), relativeWorkspacePath(relative));
+
+/** Listet einen Ordner unterhalb der Wurzel: Ordner zuerst, dann alphabetisch, höchstens `FILE_LIST_LIMIT` Einträge. */
+export const listDirectory = async (root: string, relative: string): Promise<FileListing> => {
+  const checked = relativeWorkspacePath(relative);
+  const base = await realRoot(root);
+  const directory = await directoryIn(base, checked);
+  const found = await readdir(directory, { withFileTypes: true });
+  const entries = (await Promise.all(found.map((entry) => entryOf(directory, entry.name, entry.isDirectory()))))
+    .filter((entry): entry is FileEntry => entry !== undefined)
+    .sort(byKindThenName);
+  return {
+    location: base,
+    path: checked,
+    entries: entries.slice(0, FILE_LIST_LIMIT),
+    truncated: entries.length > FILE_LIST_LIMIT,
+  };
+};
+
+/** Liest eine Textdatei unterhalb der Wurzel; eine zu große oder binäre Datei nennt statt des Inhalts den Grund. */
+export const readTextFile = async (root: string, relative: string): Promise<FileText> => {
+  const checked = relativeWorkspacePath(relative);
+  const file = await inside(await realRoot(root), checked);
+  const info = await lstat(file);
+  if (!info.isFile()) throw invalid(`Keine Datei: ${checked || "."}`);
+  const described = { path: checked, size: info.size };
+  if (info.size > FILE_READ_LIMIT) {
+    return { ...described, previewable: false, reason: `Die Datei ist größer als ${FILE_READ_LIMIT / 1024} KB und wird nicht gelesen` };
+  }
+  const content = await readFile(file);
+  if (content.includes(0)) return { ...described, previewable: false, reason: "Die Datei ist binär" };
+  return { ...described, previewable: true, content: content.toString("utf8") };
+};
+
+/** Legt eine angehängte Datei unter einem freien Namen in `attachments` unterhalb der Wurzel ab, nie über eine vorhandene. */
+export const storeAttachment = async (root: string, original: string, content: Uint8Array): Promise<string> => {
+  const directory = path.join(await realRoot(root), ATTACHMENT_DIRECTORY);
+  await mkdir(directory, { recursive: true, mode: 0o755 });
+  if (!(await lstat(directory)).isDirectory()) throw invalid("Das Anhangsverzeichnis ist kein normales Verzeichnis.");
+  const name = path.basename(original).replace(/[^a-zA-Z0-9._-]/g, "_") || "attachment";
+  for (let index = 1; index <= 10000; index += 1) {
+    const candidate = index === 1 ? name : `${index}-${name}`;
+    try {
+      await writeFile(path.join(directory, candidate), content, { mode: 0o644, flag: "wx" });
+      return candidate;
+    } catch (error) {
+      if ((error as NodeJS.ErrnoException).code !== "EEXIST") throw error;
+    }
+  }
+  throw invalid("Im Anhangsverzeichnis sind zu viele gleichnamige Dateien.");
+};
+
+/** Beobachtet einen Ordner rekursiv und meldet Änderungen entprellt; der Rückgabewert beendet die Beobachtung. */
+export const watchDirectory = async (root: string, listener: FileWatchListener): Promise<() => void> => {
+  const directory = await realRoot(root);
+  let debounce: NodeJS.Timeout | undefined;
+  const watcher = watch(directory, { recursive: true }, () => {
+    if (debounce) return;
+    debounce = setTimeout(() => {
+      debounce = undefined;
+      listener.onChange();
+    }, WATCH_DEBOUNCE_MS);
+  });
+  watcher.on("error", listener.onError);
+  return () => {
+    if (debounce) clearTimeout(debounce);
+    watcher.close();
+  };
+};
+
+const pathOf = (input: unknown): string => {
+  const value = (input as { path?: unknown } | null)?.path;
+  if (typeof value !== "string") throw invalid("Die Eingabe braucht einen Pfad als Text");
+  return value;
+};
+
+/** Mit Alias spricht die Eingabe dessen Wurzel an, sonst die des Runs. */
+const aliasFootprint = (input: unknown): OperationFootprint => {
+  const alias = (input as { alias?: unknown } | null)?.alias;
+  return { roots: typeof alias === "string" ? { aliases: [aliasOf(alias) ?? alias], runRoot: false } : { aliases: [], runRoot: true } };
+};
+
+/** Beobachtet bis zum Abbruch; eine gescheiterte Beobachtung beendet die Operation mit ihrer Ursache. */
+const watchUntilAborted = (root: string, signal: AbortSignal, progress: (value: FileWatchProgress) => void): Promise<null> =>
+  new Promise((resolve, reject) => {
+    let close: (() => void) | undefined;
+    let finished = false;
+    const finish = (error?: Error): void => {
+      if (finished) return;
+      finished = true;
+      signal.removeEventListener("abort", aborted);
+      close?.();
+      if (error) reject(error);
+      else resolve(null);
+    };
+    const aborted = (): void => finish();
+    signal.addEventListener("abort", aborted, { once: true });
+    watchDirectory(root, { onChange: () => progress({ kind: "changed" }), onError: finish }).then((stop) => {
+      if (finished || signal.aborted) {
+        stop();
+        finish();
+        return;
+      }
+      close = stop;
+      progress({ kind: "ready" });
+    }, finish);
+  });
+
+/** Dateien des Runs auf dieser Maschine: auflisten, Text lesen, beobachten und Anhänge ablegen, relativ zur Wurzel des Runs oder eines Alias. */
+export const fileModule: WorkspaceModuleFactory = (host) => {
+  /** Die offenen Beobachtungen je Run; Stopp und Shutdown beenden sie, auch wenn ihr Aufrufer nie abbricht. */
+  const watches = new Map<string, Set<AbortController>>();
+  let closed = false;
+  const endWatches = (runId: string): void => {
+    for (const controller of watches.get(runId) ?? []) controller.abort();
+    watches.delete(runId);
+  };
+  /** Alias und Pfad bilden zusammen einen Ort; unter einem gemeinsamen Alias wie `@skills` nennt der Pfad zuerst den Ordner der Wurzel. */
+  const locate = async (runId: string, input: unknown): Promise<{ root: string; path: string }> => {
+    const context = await host.contextFor(runId);
+    const alias = (input as { alias?: unknown } | null)?.alias;
+    const requested = pathOf(input);
+    if (alias === undefined) return { root: context.root, path: requested };
+    const aliases = context.workspaceAliases ?? {};
+    const location = requested === "" ? String(alias) : `${String(alias)}/${requested}`;
+    const found = typeof alias === "string" ? aliasedRoot(location, aliases) : undefined;
+    if (!found) throw unknownAliasError(location, aliases);
+    return { root: found.directory, path: found.rest };
+  };
+  const list: WorkspaceOperation = async ({ runId, input }) => {
+    const { root, path: requested } = await locate(runId, input);
+    return listDirectory(root, requested);
+  };
+  const attach: WorkspaceOperation = async ({ runId, input }) => {
+    const { name, content } = (input ?? {}) as { name?: unknown; content?: unknown };
+    if (typeof name !== "string" || typeof content !== "string") throw invalid("Ein Anhang braucht name und content (Base64) als Text");
+    return { name: await storeAttachment((await host.contextFor(runId)).root, name, Buffer.from(content, "base64")) };
+  };
+  const read: WorkspaceOperation = async ({ runId, input }) => {
+    const { root, path: requested } = await locate(runId, input);
+    return readTextFile(root, requested);
+  };
+  const watchFiles: WorkspaceOperation = async ({ runId, signal, progress }) => {
+    if (!signal || !progress) throw new Error(`${FILE_OPERATIONS.watch} läuft bis zum Abbruch und braucht Abbruchsignal und Fortschritt`);
+    if (closed) throw new Error("Das Dateimodul ist beendet und beobachtet nichts mehr");
+    const own = new AbortController();
+    const running = watches.get(runId) ?? new Set<AbortController>();
+    watches.set(runId, running.add(own));
+    try {
+      const root = (await host.contextFor(runId)).root;
+      return await watchUntilAborted(root, AbortSignal.any([signal, own.signal]), progress);
+    } finally {
+      running.delete(own);
+      if (running.size === 0 && watches.get(runId) === running) watches.delete(runId);
+    }
+  };
+  return {
+    operations: {
+      [FILE_OPERATIONS.list]: list,
+      [FILE_OPERATIONS.read]: read,
+      [FILE_OPERATIONS.watch]: watchFiles,
+      [FILE_OPERATIONS.attach]: attach,
+    },
+    footprints: {
+      [FILE_OPERATIONS.list]: aliasFootprint,
+      [FILE_OPERATIONS.read]: aliasFootprint,
+    },
+    stopRun: async (runId) => endWatches(runId),
+    shutdown: async () => {
+      closed = true;
+      for (const runId of [...watches.keys()]) endWatches(runId);
+    },
+  };
+};

package/packages/workspace-executor/src/index.ts

@@ -2,34 +2,90 @@ export {
   sandboxEnvironment,
   sandboxRunEnvironment,
   workspaceProcessContext,
+  type BaseEnvironment,
   type SandboxHomeEnvironment,
   type WorkspaceProcessContext,
 } from "./context.js";
+export { WorkspaceOperationError } from "./errors.js";
 export {
-  SandboxWorkspaceExecutor,
   WORKSPACE_EXECUTOR_VERSION,
-  WORKSPACE_STOP_OPERATION,
-  languageServerCloseTool,
-  languageServerDiagnosticsTool,
-  languageServerOpenTool,
-  languageServerSnapshotTool,
+  WorkspaceOperationExecutor,
   type WorkspaceExecuteOptions,
   type WorkspaceExecutor,
 } from "./executor.js";
+export {
+  type WorkspaceExecutorModule,
+  type WorkspaceModuleFactory,
+} from "./module.js";
+export { workspaceExecutorModules, type WorkspaceExecutorModuleOptions } from "./modules.js";
+export { RUN_FOLDER_OPERATIONS, runFolderModule, type RunFolderCreated } from "./run-folders.js";
+export {
+  FILE_OPERATIONS,
+  FILE_READ_LIMIT,
+  fileModule,
+  listDirectory,
+  readTextFile,
+  watchDirectory,
+  type FileListing,
+  type FileText,
+  type FileWatchProgress,
+} from "./files.js";
+export {
+  COMMAND_OPERATIONS,
+  COMMAND_OUTPUT_LIMIT,
+  commandModule,
+  type CommandResult,
+  type CommandRunInput,
+} from "./commands.js";
+export {
+  BROWSER_EXECUTABLE_VARIABLE,
+  BROWSER_OPERATIONS,
+  type BrowserCheck,
+  type BrowserCheckResult,
+  type BrowserPageState,
+  type BrowserSnapshot,
+  type BrowserStep,
+  type BrowserTarget,
+  type BrowserViewport,
+} from "./browser/contract.js";
+export { browserModule, type BrowserModuleOptions } from "./browser/module.js";
 export { processGroupExists, runManagedProcess, startManagedService, type ManagedService } from "./managed-process.js";
 export {
-  allowedWorkspacePath,
   containsWorkspacePath,
-  expandWorkspaceAlias,
   resolvedWorkspacePath,
+  rootsOfFields,
+  type AddressedRoots,
+  type OperationFootprint,
   type ResolvedWorkspaceRoot,
 } from "./paths.js";
-export { RUN_MARKER_ENV, runMarkerOf } from "./run-marker.js";
-export { safeProcessEnvironment } from "./safe-environment.js";
-export { createSandboxTools, withAnnotation } from "./sandbox-tools.js";
+export { PROCESS_OPERATIONS, processModule } from "./processes/module.js";
+export { sandboxedLaunch, type ProcessLaunch, type ProcessSandbox } from "./process-sandbox.js";
+export {
+  ProcessChangedError,
+  addressFromHex,
+  darwinProcessTable,
+  hasProcessTable,
+  linuxProcessTable,
+  parseDarwinMarkers,
+  parseDarwinProcessTable,
+  parseLinuxStat,
+  parseLinuxTcpTable,
+  parseLsofListeners,
+  processIdOf,
+  processTableForPlatform,
+  type ProcessRecord,
+  type ProcessTable,
+} from "./processes/process-table.js";
+export { ProcessScanner, type WorkspaceProcessSnapshot } from "./processes/scanner.js";
+export { labelOf, runProcessesFrom } from "./processes/snapshot.js";
+export { RunProcessTerminator } from "./processes/terminator.js";
+export { RUN_MARKER_ENV } from "./run-marker.js";
+export { editorFreeEnvironment, inheritedProcessEnvironment, safeProcessEnvironment } from "./safe-environment.js";
+export { bashLaunch, type BashLaunch } from "./bash-launch.js";
+export { createSandboxTools, sandboxToolsModule, withAnnotation, type SeenFile } from "./sandbox-tools.js";
 export { type SessionIdent } from "./session-ident.js";
 export { shellPlatformText } from "./shell-platform.js";
-export { hostDataDirectory, hostToolFile, pluginToolsDirectory, ragentsDataRoot, workspaceDataDirectory } from "./tools.js";
+export { ragentsDataRoot, workspaceDataDirectory } from "./tools.js";
 export {
   LanguageServerHost,
   changedWorkspaceFiles,
@@ -37,18 +93,26 @@ export {
   type LanguageServerHostOptions,
 } from "./language-server/host.js";
 export {
-  type LanguageServerDiagnostic,
-  type LanguageServerFileDiagnostics,
   type LanguageServerInstanceSnapshot,
   type LanguageServerSeverity,
   type LanguageServerSnapshot,
+  type LanguageServerSolution,
+  type LanguageServerSolutions,
   type LanguageServerState,
 } from "./language-server/contract.js";
 export { diagnosticEntries, formatDiagnostics } from "./language-server/diagnostics.js";
+export {
+  languageServerCloseOperation,
+  languageServerDiagnosticsOperation,
+  languageServerModule,
+  languageServerOpenOperation,
+  languageServerSnapshotOperation,
+  languageServerSolutionsOperation,
+  languageServerSwitchOperation,
+} from "./language-server/module.js";
 export { resolveRootDirectory } from "./language-server/roots.js";
-export { LanguageServerSession, withTimeout, type Diagnostic } from "./language-server/session.js";
+export { LanguageServerSession, withTimeout } from "./language-server/session.js";
 export { solutionProjects } from "./language-server/solution.js";
-export { fsharpAdapter, FSHARP_PLUGIN_ID, FSHARP_SERVER_FILE, FSHARP_SERVER_VARIABLE } from "./language-server/adapters/fsharp.js";
-export { roslynAdapter, ROSLYN_PLUGIN_ID, ROSLYN_SERVER_FILE, ROSLYN_SERVER_VARIABLE } from "./language-server/adapters/roslyn.js";
+export { fsharpAdapter, FSHARP_SERVER_FILE, FSHARP_SERVER_VARIABLE } from "./language-server/adapters/fsharp.js";
+export { roslynAdapter, ROSLYN_SERVER_FILE, ROSLYN_SERVER_VARIABLE } from "./language-server/adapters/roslyn.js";
 export { typescriptAdapter } from "./language-server/adapters/typescript.js";
-export { workspaceLanguageServers } from "./language-server/adapters/index.js";

package/packages/workspace-executor/src/language-server/adapters/roslyn.ts

@@ -26,6 +26,7 @@ export const roslynAdapter: LanguageServerAdapter = {
   label: "Roslyn",
   languages,
   rootDescription: "the .sln file (or a single .csproj)",
+  solutionExtensions: [".sln", ".slnx"],
   resolveRoot: (workspaceRoot, root) => resolveRootFile(workspaceRoot, root, [".sln", ".slnx", ".csproj"]),
   rootDirectory: (root) => path.dirname(root),
   launch: async (context, root) => ({

package/packages/workspace-executor/src/language-server/contract.ts

@@ -25,3 +25,17 @@ export interface LanguageServerInstanceSnapshot {
 export interface LanguageServerSnapshot {
   instances: readonly LanguageServerInstanceSnapshot[];
 }
+
+export interface LanguageServerSolution {
+  /** Relativ zur Wurzel des Arbeitsbereichs, mit Schrägstrichen. */
+  path: string;
+  root: string;
+  state: LanguageServerState | null;
+}
+
+export interface LanguageServerSolutions {
+  source: "git" | "directory";
+  solutions: readonly LanguageServerSolution[];
+  /** Ob im Run schon eine Instanz dieser Sprache offen ist oder gerade geöffnet wird. */
+  opened: boolean;
+}

package/packages/workspace-executor/src/language-server/host.ts

@@ -1,10 +1,17 @@
 import { realpath, stat } from "node:fs/promises";
 import path from "node:path";
 import type { WorkspaceProcessContext } from "../context.js";
-import { runManagedProcess } from "../managed-process.js";
-import type { LanguageServerDiagnostic, LanguageServerInstanceSnapshot, LanguageServerSnapshot } from "./contract.js";
+import { sandboxedLaunch } from "../process-sandbox.js";
+import type {
+  LanguageServerDiagnostic,
+  LanguageServerInstanceSnapshot,
+  LanguageServerSnapshot,
+  LanguageServerSolutions,
+  LanguageServerState,
+} from "./contract.js";
 import { diagnosticEntries, formatDiagnostics } from "./diagnostics.js";
 import { LanguageServerSession, withTimeout, type LanguageServerLaunch } from "./session.js";
+import { runGit, workspaceSolutions } from "./workspace-solutions.js";
 import { allowedWorkspacePath, containsWorkspacePath, expandWorkspaceAlias, resolvedWorkspacePath } from "../paths.js";
 
 export interface LanguageServerAdapter {
@@ -12,6 +19,8 @@ export interface LanguageServerAdapter {
   label: string;
   languages: Readonly<Record<string, string>>;
   rootDescription: string;
+  /** Die Endungen der Solutions, die `<id>_solutions` im Arbeitsbereich sucht; ohne sie gibt es weder Suche noch Umschalten. */
+  solutionExtensions?: readonly string[];
   resolveRoot: (workspaceRoot: string, root: string) => Promise<string>;
   rootDirectory: (root: string) => string;
   launch: (context: WorkspaceProcessContext, root: string) => Promise<LanguageServerLaunch>;
@@ -45,7 +54,6 @@ interface ServerEntry {
 const DEFAULT_IDLE_MS = 20 * 60 * 1000;
 const DEFAULT_OPEN_TIMEOUT_MS = 5 * 60 * 1000;
 const DEFAULT_DIAGNOSTICS_TIMEOUT_MS = 60 * 1000;
-const GIT_TIMEOUT_MS = 30 * 1000;
 
 const messageOf = (error: unknown): string => error instanceof Error ? error.message : String(error);
 
@@ -61,22 +69,11 @@ const git = async (
   tool: string,
   args: readonly string[],
 ): Promise<string> => {
-  let output = "";
-  const result = await runManagedProcess({
-    command: "git",
-    args: [...args],
-    cwd: directory,
-    env: context.env,
-    uid: context.uid,
-    gid: context.gid,
-    label: `git ${args[0]}`,
-    timeoutMs: GIT_TIMEOUT_MS,
-    onStdout: (chunk) => { output += chunk.toString("utf8"); },
-  }).catch((error: unknown) => {
+  const result = await runGit(context, directory, args).catch((error: unknown) => {
     throw new Error(`Ohne paths braucht ${tool} ein Git-Arbeitsverzeichnis: ${messageOf(error)}`);
   });
   if (result.code !== 0) throw new Error(`Ohne paths braucht ${tool} ein Git-Arbeitsverzeichnis (git ${args[0]}: Code ${result.code})`);
-  return output;
+  return result.output;
 };
 
 /** Git nennt seine Pfade relativ zur Repo-Wurzel; `-- .` grenzt sie auf die Wurzel der Instanz ein. */
@@ -107,6 +104,7 @@ export class LanguageServerHost {
   readonly #diagnosticsTimeoutMs: number;
   readonly #servers = new Map<string, ServerEntry>();
   readonly #roots = new Map<string, Set<string>>();
+  readonly #requests = new Map<string, number>();
   readonly #lifetimes = new Map<string, object>();
   readonly #closing = new Map<string, Set<Promise<void>>>();
   readonly #idleTimers = new Map<string, NodeJS.Timeout>();
@@ -129,8 +127,51 @@ export class LanguageServerHost {
     return this.adapter.languages[path.extname(filePath).toLowerCase()] !== undefined;
   }
 
-  async open(runId: string, root: string): Promise<string> {
+  /** Mit `ifNoneOpen` prüft und belegt der Aufruf den Run ohne Unterbrechung: läuft schon ein Öffnen oder ist eine Instanz da, lädt er nichts. */
+  async open(runId: string, root: string, ifNoneOpen = false): Promise<string> {
+    const lifetime = this.#lifetime(runId);
+    if (ifNoneOpen && !this.#idle(runId)) {
+      return `${this.adapter.label} lädt ${root} nicht: in diesem Run ist schon eine Instanz offen oder im Aufbau`;
+    }
+    this.#requests.set(runId, (this.#requests.get(runId) ?? 0) + 1);
+    try {
+      return await this.#open(runId, lifetime, root);
+    } finally {
+      const remaining = (this.#requests.get(runId) ?? 1) - 1;
+      if (remaining > 0) this.#requests.set(runId, remaining);
+      else this.#requests.delete(runId);
+    }
+  }
+
+  async solutions(runId: string): Promise<LanguageServerSolutions> {
+    const extensions = this.adapter.solutionExtensions;
+    if (!extensions) throw new Error(`${this.adapter.label} sucht keine Solutions`);
+    if (this.#closed) throw this.#stopped();
+    const found = await workspaceSolutions(await this.#contextFor(runId), extensions);
+    return {
+      source: found.source,
+      solutions: found.solutions.map((solution) => ({ ...solution, state: this.#stateOf(runId, solution.root) })),
+      opened: !this.#idle(runId),
+    };
+  }
+
+  /** Lädt die Wurzel und beendet jede andere Instanz des Runs; wartet nicht auf das Laden, `null` beendet alle. */
+  async switchTo(runId: string, root: string | null): Promise<string> {
+    if (root === null) return this.close(runId);
     const lifetime = this.#lifetime(runId);
+    const { context, absoluteRoot } = await this.#prepare(runId, lifetime, root);
+    const others = this.#openRoots(runId).filter((entry) => entry !== absoluteRoot);
+    await Promise.all(others.map((entry) => this.#closeInstance(runId, entry)));
+    this.#assertLifetime(runId, lifetime);
+    const current = this.#current(runId, absoluteRoot);
+    const kept = current !== undefined && current.state !== "failed";
+    // Ein Fehlschlag steht mit seiner Ursache im Stand der Instanz.
+    if (!kept) void this.#start(runId, context, absoluteRoot).catch(() => undefined);
+    const closed = others.length === 0 ? "" : `; ${others.length === 1 ? "eine andere Instanz" : `${others.length} andere Instanzen`} beendet`;
+    return `${this.adapter.label} ${kept ? "behält" : "lädt"} ${absoluteRoot}${closed}`;
+  }
+
+  async #open(runId: string, lifetime: object, root: string): Promise<string> {
     const { context, absoluteRoot } = await this.#prepare(runId, lifetime, root);
     const current = this.#current(runId, absoluteRoot);
     if (current && current.state !== "failed") {
@@ -182,11 +223,14 @@ export class LanguageServerHost {
     this.#assertLifetime(runId, lifetime);
     const roots = root === undefined ? this.#openRoots(runId) : [await this.#known(runId, context, root)];
     if (roots.length === 0) throw new Error(`Kein ${this.adapter.label}-Server geöffnet; zuerst ${this.adapter.id}_open aufrufen`);
-    const results = paths === undefined || paths.length === 0
-      ? await this.#changed(runId, context, roots, includeWarnings)
-      : await this.#requested(runId, context, roots, paths, includeWarnings);
-    if (results.length === 0) return `Keine geänderten ${this.adapter.label}-Dateien in den geöffneten Wurzeln`;
-    return results.join("\n\n");
+    if (paths !== undefined && paths.length > 0) return (await this.#requested(runId, context, roots, paths, includeWarnings)).join("\n\n");
+    const failed = root === undefined ? roots.filter((entry) => this.#current(runId, entry)?.state === "failed") : [];
+    const failures = failed.map((entry) =>
+      `${this.adapter.label} für ${entry} nicht geöffnet: ${this.#current(runId, entry)!.summary}; ${this.adapter.id}_open öffnet die Wurzel erneut`);
+    if (failed.length === roots.length) throw new Error(failures.join("\n"));
+    const results = await this.#changed(runId, context, roots.filter((entry) => !failed.includes(entry)), includeWarnings);
+    const text = results.length === 0 ? `Keine geänderten ${this.adapter.label}-Dateien in den geöffneten Wurzeln` : results.join("\n\n");
+    return [text, ...failures].join("\n\n");
   }
 
   async annotate(runId: string, absolutePath: string): Promise<string | undefined> {
@@ -241,8 +285,9 @@ export class LanguageServerHost {
     try {
       const context = await this.#contextFor(runId);
       this.#assertLifetime(runId, lifetime);
+      absoluteRoot = path.resolve(context.root, expandWorkspaceAlias(root, context.workspaceAliases ?? {}));
       const allowed = await Promise.all([context.root, ...context.additionalRoots ?? []].map(resolvedWorkspacePath));
-      const requested = await allowedWorkspacePath(path.resolve(context.root, expandWorkspaceAlias(root, context.workspaceAliases ?? {})), allowed);
+      const requested = await allowedWorkspacePath(absoluteRoot, allowed);
       absoluteRoot = requested;
       const workspaceRoot = allowed.find((directory) => containsWorkspacePath(directory, requested))!;
       absoluteRoot = await this.adapter.resolveRoot(workspaceRoot, requested);
@@ -357,8 +402,9 @@ export class LanguageServerHost {
   async #known(runId: string, context: WorkspaceProcessContext, root: string): Promise<string> {
     const roots = this.#openRoots(runId);
     if (roots.length === 0) throw new Error(`Kein ${this.adapter.label}-Server geöffnet; zuerst ${this.adapter.id}_open aufrufen`);
-    const requested = await resolvedWorkspacePath(path.resolve(context.root, expandWorkspaceAlias(root, context.workspaceAliases ?? {})));
-    const found = roots.find((open) => open === requested);
+    const lexical = path.resolve(context.root, expandWorkspaceAlias(root, context.workspaceAliases ?? {}));
+    const requested = await resolvedWorkspacePath(lexical);
+    const found = roots.find((open) => open === requested || open === lexical);
     if (!found) throw new Error(`Für ${root} ist kein ${this.adapter.label}-Server geöffnet; offen: ${roots.join(", ")}`);
     return found;
   }
@@ -387,6 +433,15 @@ export class LanguageServerHost {
     return [...this.#roots.get(runId) ?? []];
   }
 
+  #idle(runId: string): boolean {
+    return this.#openRoots(runId).length === 0 && !this.#requests.has(runId);
+  }
+
+  #stateOf(runId: string, root: string): LanguageServerState | null {
+    if (!this.#roots.get(runId)?.has(root)) return null;
+    return this.#current(runId, root)?.state ?? "suspended";
+  }
+
   #remember(runId: string, root: string): void {
     const roots = this.#roots.get(runId) ?? new Set<string>();
     roots.add(root);
@@ -440,8 +495,9 @@ export class LanguageServerHost {
         await closing;
         this.#assertCurrent(entry);
         const launch = await this.adapter.launch(context, root);
+        const { command, args } = await sandboxedLaunch(context, launch);
         this.#assertCurrent(entry);
-        entry.initializing = LanguageServerSession.start(launch, this.#openTimeoutMs);
+        entry.initializing = LanguageServerSession.start({ ...launch, command, args: [...args] }, this.#openTimeoutMs);
         const session = await entry.initializing;
         this.#assertCurrent(entry);
         let aborted!: () => void;