@schlenkr/ragents 0.1.5 → 0.1.6

package/{plugins/ragents.processes/server → packages/workspace-executor/src/processes}/process-table.ts

@@ -2,8 +2,12 @@ import { execFile } from "node:child_process";
 import { createHash } from "node:crypto";
 import { readdir, readFile, readlink } from "node:fs/promises";
 import { promisify } from "node:util";
-import { RUN_MARKER_ENV, runMarkerOf } from "@aicontainer/workspace-executor";
-import type { RunProcessPort } from "../contract.js";
+import { RUN_MARKER_ENV, runMarkerOf } from "../run-marker.js";
+
+export interface WorkspaceProcessPort {
+  port: number;
+  address: string;
+}
 
 const execFileAsync = promisify(execFile);
 
@@ -19,7 +23,7 @@ export interface ProcessRecord {
 export interface ProcessTable {
   list: () => Promise<ProcessRecord[]>;
   runMarkers: (pids: readonly number[]) => Promise<Map<number, string>>;
-  listeningPorts: (pids: readonly number[]) => Promise<Map<number, RunProcessPort[]>>;
+  listeningPorts: (pids: readonly number[]) => Promise<Map<number, WorkspaceProcessPort[]>>;
 }
 
 export const processIdOf = (record: Pick<ProcessRecord, "pid" | "startKey">): string =>
@@ -46,7 +50,7 @@ const runCommand = async (file: string, args: string[], toleratedExitCodes: read
   }
 };
 
-const addPort = (ports: RunProcessPort[], port: RunProcessPort): void => {
+const addPort = (ports: WorkspaceProcessPort[], port: WorkspaceProcessPort): void => {
   if (!ports.some((known) => known.port === port.port && known.address === port.address)) ports.push(port);
 };
 
@@ -93,7 +97,7 @@ export const parseDarwinMarkers = (text: string, commands?: ReadonlyMap<number,
   return markers;
 };
 
-const portFromLsofName = (name: string): RunProcessPort | undefined => {
+const portFromLsofName = (name: string): WorkspaceProcessPort | undefined => {
   const separator = name.lastIndexOf(":");
   if (separator < 0) return undefined;
   const port = Number(name.slice(separator + 1));
@@ -103,9 +107,9 @@ const portFromLsofName = (name: string): RunProcessPort | undefined => {
   return { port, address: wildcard ? WILDCARD : host.replace(/^\[|\]$/g, "") };
 };
 
-export const parseLsofListeners = (text: string): Map<number, RunProcessPort[]> => {
-  const listeners = new Map<number, RunProcessPort[]>();
-  let current: RunProcessPort[] | undefined;
+export const parseLsofListeners = (text: string): Map<number, WorkspaceProcessPort[]> => {
+  const listeners = new Map<number, WorkspaceProcessPort[]>();
+  let current: WorkspaceProcessPort[] | undefined;
   for (const line of text.split("\n")) {
     if (line.startsWith("p")) {
       const pid = Number(line.slice(1));
@@ -160,7 +164,7 @@ export const darwinProcessTable = (command: typeof runCommand = runCommand): Pro
     return markers;
   },
   listeningPorts: async (pids) => {
-    const listeners = new Map<number, RunProcessPort[]>();
+    const listeners = new Map<number, WorkspaceProcessPort[]>();
     for (const chunk of chunked(pids)) {
       const output = await command(
         "lsof",
@@ -173,13 +177,16 @@ export const darwinProcessTable = (command: typeof runCommand = runCommand): Pro
   },
 });
 
-const PROC = "/proc";
-
 const isGone = (error: unknown): boolean => {
   const code = (error as NodeJS.ErrnoException).code;
   return code === "ENOENT" || code === "ESRCH";
 };
 
+const isDenied = (error: unknown): boolean => {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === "EACCES" || code === "EPERM";
+};
+
 const explainAccess = (error: unknown, pid: number, what: string): Error => {
   const code = (error as NodeJS.ErrnoException).code;
   if (code === "EACCES" || code === "EPERM") {
@@ -258,7 +265,7 @@ export const addressFromHex = (hex: string): string => {
 
 export interface LinuxListener {
   inode: string;
-  port: RunProcessPort;
+  port: WorkspaceProcessPort;
 }
 
 export const parseLinuxTcpTable = (text: string): LinuxListener[] =>
@@ -273,15 +280,15 @@ export const parseLinuxTcpTable = (text: string): LinuxListener[] =>
 const numericEntries = async (directory: string): Promise<number[]> =>
   (await readdir(directory)).filter((name) => /^\d+$/.test(name)).map(Number);
 
-const readLinuxRecord = async (pid: number): Promise<ProcessRecord | undefined> => {
+const readLinuxRecord = async (proc: string, pid: number): Promise<ProcessRecord | undefined> => {
   let stat: string;
   let status: string;
   let cmdline: Buffer;
   try {
     [stat, status, cmdline] = await Promise.all([
-      readFile(`${PROC}/${pid}/stat`, "utf8"),
-      readFile(`${PROC}/${pid}/status`, "utf8"),
-      readFile(`${PROC}/${pid}/cmdline`),
+      readFile(`${proc}/${pid}/stat`, "utf8"),
+      readFile(`${proc}/${pid}/status`, "utf8"),
+      readFile(`${proc}/${pid}/cmdline`),
     ]);
   } catch (error) {
     if (isGone(error)) return undefined;
@@ -290,7 +297,7 @@ const readLinuxRecord = async (pid: number): Promise<ProcessRecord | undefined>
   const parsed = parseLinuxStat(stat);
   if (parsed.state === "Z") return undefined;
   const uid = Number(/^Uid:\s+(\d+)/m.exec(status)?.[1]);
-  if (!Number.isInteger(uid)) throw new Error(`${PROC}/${pid}/status nennt keine Uid`);
+  if (!Number.isInteger(uid)) throw new Error(`${proc}/${pid}/status nennt keine Uid`);
   const args = cmdline.toString("utf8").split("\0").filter((argument) => argument !== "");
   return {
     pid,
@@ -302,12 +309,12 @@ const readLinuxRecord = async (pid: number): Promise<ProcessRecord | undefined>
   };
 };
 
-const readLinuxMarker = async (pid: number): Promise<string | undefined> => {
+const readLinuxMarker = async (proc: string, pid: number, asRoot: boolean): Promise<string | undefined> => {
   let environ: Buffer;
   try {
-    environ = await readFile(`${PROC}/${pid}/environ`);
+    environ = await readFile(`${proc}/${pid}/environ`);
   } catch (error) {
-    if (isGone(error)) return undefined;
+    if (isGone(error) || (isDenied(error) && !asRoot)) return undefined;
     throw explainAccess(error, pid, "Die Umgebung");
   }
   const prefix = `${RUN_MARKER_ENV}=`;
@@ -315,12 +322,12 @@ const readLinuxMarker = async (pid: number): Promise<string | undefined> => {
   return runMarkerOf(entry?.slice(prefix.length));
 };
 
-const linuxListeningInodes = async (): Promise<Map<string, RunProcessPort>> => {
-  const inodes = new Map<string, RunProcessPort>();
+const linuxListeningInodes = async (proc: string): Promise<Map<string, WorkspaceProcessPort>> => {
+  const inodes = new Map<string, WorkspaceProcessPort>();
   for (const table of ["tcp", "tcp6"]) {
     let text: string;
     try {
-      text = await readFile(`${PROC}/net/${table}`, "utf8");
+      text = await readFile(`${proc}/net/${table}`, "utf8");
     } catch (error) {
       if (isGone(error)) continue;
       throw error;
@@ -330,13 +337,13 @@ const linuxListeningInodes = async (): Promise<Map<string, RunProcessPort>> => {
   return inodes;
 };
 
-const linuxSocketInodes = async (pid: number): Promise<string[]> => {
-  const directory = `${PROC}/${pid}/fd`;
+const linuxSocketInodes = async (proc: string, pid: number, asRoot: boolean): Promise<string[]> => {
+  const directory = `${proc}/${pid}/fd`;
   let names: string[];
   try {
     names = await readdir(directory);
   } catch (error) {
-    if (isGone(error)) return [];
+    if (isGone(error) || (isDenied(error) && !asRoot)) return [];
     throw explainAccess(error, pid, "Die Dateideskriptoren");
   }
   const inodes: string[] = [];
@@ -345,7 +352,7 @@ const linuxSocketInodes = async (pid: number): Promise<string[]> => {
     try {
       target = await readlink(`${directory}/${name}`);
     } catch (error) {
-      if (isGone(error)) continue;
+      if (isGone(error) || (isDenied(error) && !asRoot)) continue;
       throw explainAccess(error, pid, "Die Dateideskriptoren");
     }
     const match = /^socket:\[(\d+)\]$/.exec(target);
@@ -354,42 +361,58 @@ const linuxSocketInodes = async (pid: number): Promise<string[]> => {
   return inodes;
 };
 
-const linuxProcessTable = (): ProcessTable => ({
-  list: async () => {
-    const records = await Promise.all((await numericEntries(PROC)).map(readLinuxRecord));
-    return records.filter((record): record is ProcessRecord => record !== undefined);
-  },
-  runMarkers: async (pids) => {
-    const markers = new Map<number, string>();
-    for (const pid of pids) {
-      const marker = await readLinuxMarker(pid);
-      if (marker) markers.set(pid, marker);
-    }
-    return markers;
-  },
-  listeningPorts: async (pids) => {
-    const listeners = new Map<number, RunProcessPort[]>();
-    if (pids.length === 0) return listeners;
-    const inodes = await linuxListeningInodes();
-    if (inodes.size === 0) return listeners;
-    for (const pid of pids) {
-      const ports: RunProcessPort[] = [];
-      for (const inode of await linuxSocketInodes(pid)) {
-        const port = inodes.get(inode);
-        if (port) addPort(ports, port);
+export interface LinuxProcessTableOptions {
+  /** Der Ordner der Prozessdateien; Tests nennen einen eigenen. */
+  readonly proc?: string;
+  /** Als root ist eine gesperrte Umgebung ein fehlendes Recht; sonst hat sich ein eigener Prozess unlesbar gemacht. */
+  readonly asRoot?: boolean;
+}
+
+/** Ohne root liest die Tabelle nur eigene Prozesse; einer, der sich unlesbar gemacht hat (PR_SET_DUMPABLE, etwa ein Chrome-Helfer oder ssh-agent), trägt keinen erkennbaren Marker. */
+export const linuxProcessTable = (options: LinuxProcessTableOptions = {}): ProcessTable => {
+  const proc = options.proc ?? "/proc";
+  const asRoot = options.asRoot ?? process.getuid?.() === 0;
+  return {
+    list: async () => {
+      const records = await Promise.all((await numericEntries(proc)).map((pid) => readLinuxRecord(proc, pid)));
+      return records.filter((record): record is ProcessRecord => record !== undefined);
+    },
+    runMarkers: async (pids) => {
+      const markers = new Map<number, string>();
+      for (const pid of pids) {
+        const marker = await readLinuxMarker(proc, pid, asRoot);
+        if (marker) markers.set(pid, marker);
       }
-      if (ports.length > 0) listeners.set(pid, ports);
-    }
-    return listeners;
-  },
-});
+      return markers;
+    },
+    listeningPorts: async (pids) => {
+      const listeners = new Map<number, WorkspaceProcessPort[]>();
+      if (pids.length === 0) return listeners;
+      const inodes = await linuxListeningInodes(proc);
+      if (inodes.size === 0) return listeners;
+      for (const pid of pids) {
+        const ports: WorkspaceProcessPort[] = [];
+        for (const inode of await linuxSocketInodes(proc, pid, asRoot)) {
+          const port = inodes.get(inode);
+          if (port) addPort(ports, port);
+        }
+        if (ports.length > 0) listeners.set(pid, ports);
+      }
+      return listeners;
+    },
+  };
+};
+
+/** Nur macOS und Linux haben eine Prozesstabelle, aus der sich Run-Marker lesen lassen. */
+export const hasProcessTable = (platform: NodeJS.Platform = process.platform): boolean =>
+  platform === "darwin" || platform === "linux";
 
 export const processTableForPlatform = (platform: NodeJS.Platform = process.platform): ProcessTable => {
   if (platform === "darwin") return darwinProcessTable();
   if (platform === "linux") return linuxProcessTable();
   if (platform === "win32") {
-    throw new Error("Das Plugin ragents.processes läuft nicht unter Windows: für win32 gibt es keine Prozesstabelle. "
-      + "Nimm ragents.processes aus der Plugin-Liste des Profils; die Werkzeuge des Arbeitsbereichs brauchen es nicht.");
+    throw new Error("Unter Windows gibt es keine Prozesstabelle: für Runs, die auf diesem Rechner arbeiten, zeigt und beendet "
+      + "die Prozessüberwachung nichts. Die Werkzeuge des Arbeitsbereichs brauchen sie nicht.");
   }
   throw new Error(`Die Prozessüberwachung kennt die Plattform ${platform} nicht (nur darwin und linux)`);
 };

package/packages/workspace-executor/src/processes/scanner.ts

@@ -0,0 +1,106 @@
+import type { ProcessRecord, ProcessTable, WorkspaceProcessPort } from "./process-table.js";
+import { runProcessesFrom, type WorkspaceProcess } from "./snapshot.js";
+
+export interface WorkspaceProcessSnapshot {
+  observedAt: string;
+  processes: WorkspaceProcess[];
+}
+
+export interface ProcessScannerOptions {
+  table: () => ProcessTable;
+  executorPid: number;
+  executorUid: number | undefined;
+  now?: () => Date;
+}
+
+interface Scan {
+  records: readonly ProcessRecord[];
+  observedAt: string;
+  markers: ReadonlyMap<number, string | undefined>;
+  firstSeen: ReadonlyMap<number, string>;
+}
+
+const keyOf = (record: ProcessRecord): string => `${record.pid}:${record.startKey}`;
+
+/** Liest die markierten Prozesse dieser Maschine; gleichzeitige Abfragen mehrerer Runs teilen sich einen Tabellenscan. */
+export class ProcessScanner {
+  readonly #options: ProcessScannerOptions;
+  readonly #now: () => Date;
+  readonly #markers = new Map<string, string | null>();
+  readonly #firstSeen = new Map<string, string>();
+  #scanning: Promise<Scan> | undefined;
+
+  constructor(options: ProcessScannerOptions) {
+    this.#options = options;
+    this.#now = options.now ?? (() => new Date());
+  }
+
+  async snapshot(runId: string): Promise<WorkspaceProcessSnapshot> {
+    const scan = await this.#shared();
+    const markerOf = (record: ProcessRecord): string | undefined => scan.markers.get(record.pid);
+    const marked = scan.records.filter((record) => markerOf(record) === runId);
+    const ports: ReadonlyMap<number, readonly WorkspaceProcessPort[]> = marked.length > 0
+      ? await this.#options.table().listeningPorts(marked.map((record) => record.pid))
+      : new Map();
+    return {
+      observedAt: scan.observedAt,
+      processes: runProcessesFrom({
+        runId,
+        executorPid: this.#options.executorPid,
+        records: scan.records,
+        markerOf,
+        ports,
+        firstSeen: (record) => {
+          const seen = scan.firstSeen.get(record.pid);
+          if (!seen) throw new Error(`Prozess ${record.pid} ohne Erstsichtung`);
+          return seen;
+        },
+      }),
+    };
+  }
+
+  #shared(): Promise<Scan> {
+    this.#scanning ??= this.#scan().finally(() => {
+      this.#scanning = undefined;
+    });
+    return this.#scanning;
+  }
+
+  #readable(record: ProcessRecord): boolean {
+    const uid = this.#options.executorUid;
+    return uid === undefined || uid === 0 || record.uid === uid;
+  }
+
+  /** Die Umgebung eines Prozesses wird nur einmal gelesen; ein Fehler dabei merkt sich nichts. */
+  async #scan(): Promise<Scan> {
+    const table = this.#options.table();
+    const records = await table.list();
+    const observedAt = this.#now().toISOString();
+    const present = new Set<string>();
+    const unknown: ProcessRecord[] = [];
+    for (const record of records) {
+      const key = keyOf(record);
+      present.add(key);
+      if (!this.#firstSeen.has(key)) this.#firstSeen.set(key, observedAt);
+      if (!this.#markers.has(key) && this.#readable(record)) unknown.push(record);
+    }
+    if (unknown.length > 0) {
+      const found = await table.runMarkers(unknown.map((record) => record.pid));
+      for (const record of unknown) this.#markers.set(keyOf(record), found.get(record.pid) ?? null);
+    }
+    for (const key of [...this.#markers.keys(), ...this.#firstSeen.keys()]) {
+      if (present.has(key)) continue;
+      this.#markers.delete(key);
+      this.#firstSeen.delete(key);
+    }
+    return {
+      records,
+      observedAt,
+      markers: new Map(records.map((record) => [record.pid, this.#markers.get(keyOf(record)) ?? undefined])),
+      firstSeen: new Map(records.flatMap((record) => {
+        const seen = this.#firstSeen.get(keyOf(record));
+        return seen === undefined ? [] : [[record.pid, seen] as const];
+      })),
+    };
+  }
+}

package/{plugins/ragents.processes/server → packages/workspace-executor/src/processes}/snapshot.ts

@@ -1,6 +1,17 @@
 import path from "node:path";
-import type { RunProcess, RunProcessPort } from "../contract.js";
-import { processIdOf, type ProcessRecord } from "./process-table.js";
+import { processIdOf, type ProcessRecord, type WorkspaceProcessPort } from "./process-table.js";
+
+export type WorkspaceProcessOrigin = "tool-call" | "background";
+
+export interface WorkspaceProcess {
+  id: string;
+  pid: number;
+  label: string;
+  command: string;
+  origin: WorkspaceProcessOrigin;
+  ports: WorkspaceProcessPort[];
+  seenSince: string;
+}
 
 const INTERPRETERS = new Set(["node", "nodejs", "bun", "deno", "tsx", "python", "python3", "dotnet", "ruby", "perl", "java"]);
 const INLINE_SCRIPT_FLAGS = new Set(["-e", "--eval", "-p", "--print", "-c"]);
@@ -22,29 +33,30 @@ export const labelOf = (command: string): string => {
 
 export interface ObservationInput {
   runId: string;
-  serverPid: number;
+  /** Der Prozess dieses Executors; seine direkten Kinder sind laufende Werkzeugaufrufe. */
+  executorPid: number;
   records: readonly ProcessRecord[];
   markerOf: (record: ProcessRecord) => string | undefined;
-  ports: ReadonlyMap<number, readonly RunProcessPort[]>;
+  ports: ReadonlyMap<number, readonly WorkspaceProcessPort[]>;
   firstSeen: (record: ProcessRecord) => string;
 }
 
-const wildcardFirst = (port: RunProcessPort): number => port.address === "*" ? 0 : 1;
+const wildcardFirst = (port: WorkspaceProcessPort): number => port.address === "*" ? 0 : 1;
 
-const byPort = (left: RunProcessPort, right: RunProcessPort): number =>
+const byPort = (left: WorkspaceProcessPort, right: WorkspaceProcessPort): number =>
   left.port - right.port || wildcardFirst(left) - wildcardFirst(right) || left.address.localeCompare(right.address);
 
-const byAppearance = (left: RunProcess, right: RunProcess): number =>
+const byAppearance = (left: WorkspaceProcess, right: WorkspaceProcess): number =>
   left.seenSince.localeCompare(right.seenSince) || left.pid - right.pid;
 
-/** Prozesse des Laufs: Hintergrundprozesse immer, Kinder eines laufenden Werkzeugaufrufs nur mit offenem Port. */
-export const runProcessesFrom = (input: ObservationInput): RunProcess[] => {
+/** Prozesse des Runs: Hintergrundprozesse immer, Kinder eines laufenden Werkzeugaufrufs nur mit offenem Port. */
+export const runProcessesFrom = (input: ObservationInput): WorkspaceProcess[] => {
   const toolCallGroups = new Set(
-    input.records.filter((record) => record.ppid === input.serverPid).map((record) => record.pgid),
+    input.records.filter((record) => record.ppid === input.executorPid).map((record) => record.pgid),
   );
   return input.records
     .filter((record) => input.markerOf(record) === input.runId)
-    .filter((record) => record.pid !== input.serverPid)
+    .filter((record) => record.pid !== input.executorPid)
     .flatMap((record) => {
       const ports = [...(input.ports.get(record.pid) ?? [])].sort(byPort);
       const origin = toolCallGroups.has(record.pgid) ? "tool-call" as const : "background" as const;

package/{plugins/ragents.processes/server → packages/workspace-executor/src/processes}/terminator.ts

@@ -1,11 +1,12 @@
-import { DomainError } from "@aicontainer/ragents";
-import { runMarkerOf } from "@aicontainer/workspace-executor";
+import { WorkspaceOperationError } from "../errors.js";
+import { runMarkerOf } from "../run-marker.js";
 import { processIdOf, type ProcessRecord, type ProcessTable } from "./process-table.js";
 
 export interface ProcessTerminationOptions {
   table: ProcessTable;
-  serverPid: number;
-  serverUid: number | undefined;
+  /** Der Prozess dieses Executors; er und seine Vorfahren sind geschützt. */
+  executorPid: number;
+  executorUid: number | undefined;
   termGraceMs?: number;
   killGraceMs?: number;
   timeoutMs?: number;
@@ -15,7 +16,6 @@ export interface ProcessTerminationOptions {
 
 export interface ProcessTerminationContext {
   signal?: AbortSignal;
-  assertAllowed?: () => void;
 }
 
 interface Attempt {
@@ -49,7 +49,7 @@ export class RunProcessTerminator {
   async stop(runId: string, processId: string, context: ProcessTerminationContext = {}): Promise<void> {
     const pid = Number(processId.split("-")[0]);
     if (!/^[1-9]\d*-[a-f0-9]{64}$/.test(processId) || !Number.isSafeInteger(pid) || pid > 2_147_483_647)
-      throw new DomainError("invalid-process", "Ungültige Prozessreferenz", 400);
+      throw new WorkspaceOperationError("invalid-process", "Ungültige Prozessreferenz", 400);
     await this.#stop(runId, processId, context);
   }
 
@@ -58,7 +58,7 @@ export class RunProcessTerminator {
   }
 
   async #stop(runId: string, processId: string | undefined, context: ProcessTerminationContext): Promise<void> {
-    if (runMarkerOf(runId) !== runId) throw new DomainError("invalid-run", "Ungültige Laufkennung", 400);
+    if (runMarkerOf(runId) !== runId) throw new WorkspaceOperationError("invalid-run", "Ungültige Laufkennung", 400);
     const deadline = Date.now() + this.#timeoutMs;
     const attempts = new Map<string, Attempt>();
     const failures = new Map<string, unknown>();
@@ -69,15 +69,15 @@ export class RunProcessTerminator {
     let first = true;
     let emptyScans = 0;
     while (true) {
-      this.#assertAllowed(context, deadline);
+      this.#assertActive(context, deadline);
       const records = await this.#bounded(this.#options.table.list(), deadline);
       const selected = processId === undefined ? records : records.filter((record) => record.pid === Number(processId.split("-")[0]));
       const readable = selected.filter((record) => this.#readable(record));
       const markers = await this.#bounded(this.#options.table.runMarkers(readable.map((record) => record.pid)), deadline);
       if (first && processId !== undefined && selected.length > 0) {
         const record = selected[0];
-        if (processIdOf(record) !== processId) throw new DomainError("stale-process", "Die Prozess-ID wurde inzwischen neu vergeben. Bitte die Prozessliste aktualisieren.", 409);
-        if (markers.get(record.pid) !== runId) throw new DomainError("process-run-mismatch", "Der Prozess gehört nicht zu diesem Lauf", 403);
+        if (processIdOf(record) !== processId) throw new WorkspaceOperationError("stale-process", "Die Prozess-ID wurde inzwischen neu vergeben. Bitte die Prozessliste aktualisieren.", 409);
+        if (markers.get(record.pid) !== runId) throw new WorkspaceOperationError("process-run-mismatch", "Der Prozess gehört nicht zu diesem Run", 403);
       }
       first = false;
       const targets = readable.filter((record) => markers.get(record.pid) === runId
@@ -100,10 +100,10 @@ export class RunProcessTerminator {
             } else if (attempt.killAt === undefined && Date.now() - attempt.termAt >= this.#termGraceMs) {
               if (await this.#signal(record, runId, "SIGKILL", context, deadline)) attempt.killAt = Date.now();
             } else if (attempt.killAt !== undefined && Date.now() - attempt.killAt >= this.#killGraceMs) {
-              throw new Error(`Prozess ${record.pid} von Lauf ${runId} ist nach SIGKILL noch aktiv`);
+              throw new Error(`Prozess ${record.pid} von Run ${runId} ist nach SIGKILL noch aktiv`);
             }
           } catch (error) {
-            this.#assertAllowed(context, deadline);
+            this.#assertActive(context, deadline);
             if (processId !== undefined) throw error;
             failures.set(key, error);
           }
@@ -115,22 +115,21 @@ export class RunProcessTerminator {
   }
 
   #readable(record: ProcessRecord): boolean {
-    return this.#options.serverUid === undefined || this.#options.serverUid === 0 || record.uid === this.#options.serverUid;
+    return this.#options.executorUid === undefined || this.#options.executorUid === 0 || record.uid === this.#options.executorUid;
   }
 
   #assertUnprotected(record: ProcessRecord, records: readonly ProcessRecord[]): void {
-    const protectedPids = new Set([0, 1, this.#options.serverPid]);
-    let parent = records.find((candidate) => candidate.pid === this.#options.serverPid)?.ppid;
+    const protectedPids = new Set([0, 1, this.#options.executorPid]);
+    let parent = records.find((candidate) => candidate.pid === this.#options.executorPid)?.ppid;
     while (parent !== undefined && !protectedPids.has(parent)) {
       protectedPids.add(parent);
       parent = records.find((candidate) => candidate.pid === parent)?.ppid;
     }
-    if (protectedPids.has(record.pid)) throw new DomainError("protected-process", `Prozess ${record.pid} gehört zum geschützten Server-Prozessbaum`, 403);
+    if (protectedPids.has(record.pid)) throw new WorkspaceOperationError("protected-process", `Prozess ${record.pid} gehört zum geschützten Prozessbaum des Executors`, 403);
   }
 
-  #assertAllowed(context: ProcessTerminationContext, deadline: number): void {
+  #assertActive(context: ProcessTerminationContext, deadline: number): void {
     context.signal?.throwIfAborted();
-    context.assertAllowed?.();
     if (Date.now() >= deadline) throw new Error(`Prozess-Stopp hat die Zeitgrenze von ${this.#timeoutMs} ms überschritten`);
   }
 
@@ -150,9 +149,9 @@ export class RunProcessTerminator {
     const records = await this.#bounded(this.#options.table.list(), deadline);
     const current = records.find((record) => record.pid === expected.pid);
     if (!current || current.startKey !== expected.startKey || current.uid !== expected.uid) return false;
-    if (markers.get(current.pid) !== runId) throw new DomainError("process-run-mismatch", `Prozess ${current.pid} gehört nicht mehr zu diesem Lauf`, 403);
+    if (markers.get(current.pid) !== runId) throw new WorkspaceOperationError("process-run-mismatch", `Prozess ${current.pid} gehört nicht mehr zu diesem Run`, 403);
     this.#assertUnprotected(current, records);
-    this.#assertAllowed(context, deadline);
+    this.#assertActive(context, deadline);
     try {
       this.#sendSignal(current.pid, signal);
       return true;

package/packages/workspace-executor/src/run-folders.ts

@@ -0,0 +1,33 @@
+import { mkdir, rm } from "node:fs/promises";
+import { WorkspaceOperationError } from "./errors.js";
+import type { WorkspaceModuleFactory } from "./module.js";
+
+export const RUN_FOLDER_OPERATIONS = {
+  create: "runFolder.create",
+  remove: "runFolder.remove",
+} as const;
+
+export interface RunFolderCreated {
+  /** Ob der Ordner eben entstanden ist; ein schon vorhandener bleibt, wie er ist. */
+  created: boolean;
+}
+
+/** Der neue Ordner je Run auf dieser Maschine; nur ein Executor, der einen Ordner für Runs kennt, legt ihn an, und nur diesen einen je Run. */
+export const runFolderModule = (folderOf: ((runId: string) => string) | undefined): WorkspaceModuleFactory => () => {
+  const folder = (runId: string): string => {
+    if (!folderOf) {
+      throw new WorkspaceOperationError("run-folder-unavailable", "Dieser Executor legt keine Ordner je Run an; auf dem Server tut das der Host", 409);
+    }
+    return folderOf(runId);
+  };
+  return {
+    operations: {
+      [RUN_FOLDER_OPERATIONS.create]: async ({ runId }): Promise<RunFolderCreated> =>
+        ({ created: await mkdir(folder(runId), { recursive: true }) !== undefined }),
+      [RUN_FOLDER_OPERATIONS.remove]: async ({ runId }): Promise<{ removed: true }> => {
+        await rm(folder(runId), { recursive: true, force: true });
+        return { removed: true };
+      },
+    },
+  };
+};

package/packages/workspace-executor/src/safe-environment.ts

@@ -45,3 +45,17 @@ export const safeProcessEnvironment = (source: NodeJS.ProcessEnv): NodeJS.Proces
   }
   return environment;
 };
+
+/** Die Variablen des umgebenden Editors; ein Kindprozess, der sie erbt, hängt sich an VS Code oder Electron. */
+const isEditorVariable = (name: string): boolean => name.startsWith("VSCODE_") || name.startsWith("ELECTRON_");
+
+/** Was eine nicht interaktive Bash von sich aus einliest; über sie käme eine Startdatei des Benutzers in jeden Befehl. */
+const BASH_STARTUP_VARIABLES: ReadonlySet<string> = new Set(["BASH_ENV", "ENV"]);
+
+/** Die ganze Umgebung eines Prozesses ohne die Variablen des umgebenden Editors. */
+export const editorFreeEnvironment = (source: NodeJS.ProcessEnv): Record<string, string> => Object.fromEntries(Object.entries(source)
+  .filter((entry): entry is [string, string] => typeof entry[1] === "string" && !isEditorVariable(entry[0])));
+
+/** Die geerbte Umgebung für Prozesse auf dem eigenen Rechner des Benutzers: alles außer Editor-Variablen und den Startdateien der Bash. */
+export const inheritedProcessEnvironment = (source: NodeJS.ProcessEnv): Record<string, string> => Object.fromEntries(
+  Object.entries(editorFreeEnvironment(source)).filter(([name]) => !BASH_STARTUP_VARIABLES.has(name)));