@schlenkr/ragents 0.1.0

package/plugins/ragents.processes/server/process-table.ts

@@ -0,0 +1,395 @@
+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";
+
+const execFileAsync = promisify(execFile);
+
+export interface ProcessRecord {
+  pid: number;
+  ppid: number;
+  pgid: number;
+  uid: number;
+  startKey: string;
+  command: string;
+}
+
+export interface ProcessTable {
+  list: () => Promise<ProcessRecord[]>;
+  runMarkers: (pids: readonly number[]) => Promise<Map<number, string>>;
+  listeningPorts: (pids: readonly number[]) => Promise<Map<number, RunProcessPort[]>>;
+}
+
+export const processIdOf = (record: Pick<ProcessRecord, "pid" | "startKey">): string =>
+  `${record.pid}-${createHash("sha256").update(record.startKey).digest("hex")}`;
+
+const PID_CHUNK = 400;
+const WILDCARD = "*";
+
+const chunked = (pids: readonly number[]): number[][] => {
+  const chunks: number[][] = [];
+  for (let start = 0; start < pids.length; start += PID_CHUNK) chunks.push(pids.slice(start, start + PID_CHUNK));
+  return chunks;
+};
+
+const runCommand = async (file: string, args: string[], toleratedExitCodes: readonly number[]): Promise<string> => {
+  try {
+    const { stdout } = await execFileAsync(file, args, { encoding: "utf8", maxBuffer: 64 * 1024 * 1024, timeout: 2_000 });
+    return stdout;
+  } catch (error) {
+    const failure = error as Error & { code?: number | string; stdout?: string; stderr?: string };
+    if (typeof failure.code === "number" && toleratedExitCodes.includes(failure.code)) return failure.stdout ?? "";
+    if (failure.code === "ENOENT") throw new Error(`${file} ist nicht installiert; die Prozessüberwachung braucht es`);
+    throw new Error(`${file} ${args[0]} ist fehlgeschlagen: ${(failure.stderr || failure.message).trim()}`);
+  }
+};
+
+const addPort = (ports: RunProcessPort[], port: RunProcessPort): void => {
+  if (!ports.some((known) => known.port === port.port && known.address === port.address)) ports.push(port);
+};
+
+const DARWIN_TABLE_LINE = /^\s*(\d+)\s+(\d+)\s+(\d+)\s+(-?\d+)\s+(\w{3} \w{3} [ \d]\d \d\d:\d\d:\d\d \d{4})\s*(.*)$/;
+const MARKER_TOKEN = new RegExp(`(?:^|\\s)${RUN_MARKER_ENV}=(\\S+)`);
+
+export class ProcessChangedError extends Error {
+  constructor(readonly pid: number) {
+    super(`Prozess ${pid} hat sich während der Umgebungsabfrage geändert`);
+    this.name = "ProcessChangedError";
+  }
+}
+
+export const parseDarwinProcessTable = (text: string): ProcessRecord[] =>
+  text.split("\n").filter((line) => line.trim() !== "").map((line) => {
+    const match = DARWIN_TABLE_LINE.exec(line);
+    if (!match) throw new Error(`Unlesbare Prozesszeile von ps: ${line}`);
+    return {
+      pid: Number(match[1]),
+      ppid: Number(match[2]),
+      pgid: Number(match[3]),
+      uid: Number(match[4]),
+      startKey: match[5],
+      command: match[6],
+    };
+  });
+
+export const parseDarwinMarkers = (text: string, commands?: ReadonlyMap<number, string>): Map<number, string> => {
+  const markers = new Map<number, string>();
+  for (const line of text.split("\n")) {
+    const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+    if (!match) continue;
+    if (match[2].trim() === "<defunct>") continue;
+    const pid = Number(match[1]);
+    const command = commands?.get(pid);
+    if (commands && command === undefined) continue;
+    if (command !== undefined && (!match[2].startsWith(command)
+      || (match[2].length > command.length && !/^\s/.test(match[2].slice(command.length)))))
+      throw new ProcessChangedError(pid);
+    const environment = command === undefined ? match[2] : match[2].slice(command.length);
+    const marker = runMarkerOf(MARKER_TOKEN.exec(environment)?.[1]);
+    if (marker) markers.set(Number(match[1]), marker);
+  }
+  return markers;
+};
+
+const portFromLsofName = (name: string): RunProcessPort | undefined => {
+  const separator = name.lastIndexOf(":");
+  if (separator < 0) return undefined;
+  const port = Number(name.slice(separator + 1));
+  if (!Number.isInteger(port) || port <= 0) return undefined;
+  const host = name.slice(0, separator);
+  const wildcard = host === "*" || host === "0.0.0.0" || host === "[::]";
+  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;
+  for (const line of text.split("\n")) {
+    if (line.startsWith("p")) {
+      const pid = Number(line.slice(1));
+      current = listeners.get(pid) ?? [];
+      listeners.set(pid, current);
+    } else if (line.startsWith("n") && current) {
+      const port = portFromLsofName(line.slice(1));
+      if (port) addPort(current, port);
+    }
+  }
+  return listeners;
+};
+
+const darwinCommands = (text: string): Map<number, string> => new Map(text.split("\n")
+  .filter((line) => line.trim() !== "").map((line) => {
+    const match = /^\s*(\d+)\s+(.*)$/.exec(line);
+    if (!match) throw new Error("Unlesbare Befehlszeile von ps");
+    return [Number(match[1]), match[2]];
+  }));
+
+export const darwinProcessTable = (command: typeof runCommand = runCommand): ProcessTable => ({
+  list: async () =>
+    parseDarwinProcessTable(await command("ps", ["-axww", "-o", "pid=,ppid=,pgid=,uid=,lstart=,args="], [])),
+  runMarkers: async (pids) => {
+    const markers = new Map<number, string>();
+    for (const chunk of chunked(pids)) {
+      let pending = chunk;
+      for (let attempt = 0; pending.length > 0; attempt++) {
+        const readCommands = async () => darwinCommands(await command("ps", ["-ww", "-o", "pid=,args=", "-p", pending.join(",")], [1]));
+        const before = await readCommands();
+        const output = darwinCommands(await command("ps", ["-ww", "-E", "-o", "pid=,args=", "-p", pending.join(",")], [1]));
+        const after = await readCommands();
+        const changed: number[] = [];
+        for (const pid of pending) {
+          const initial = before.get(pid);
+          const current = after.get(pid);
+          const environment = output.get(pid);
+          if (initial === undefined || current === undefined || current.trim() === "<defunct>"
+            || environment === undefined || environment.trim() === "<defunct>") continue;
+          try {
+            if (initial !== current) throw new ProcessChangedError(pid);
+            const marker = parseDarwinMarkers(`${pid} ${environment}`, new Map([[pid, current]])).get(pid);
+            if (marker) markers.set(pid, marker);
+          } catch (error) {
+            if (!(error instanceof ProcessChangedError) || attempt === 2) throw error;
+            changed.push(error.pid);
+          }
+        }
+        pending = changed;
+      }
+    }
+    return markers;
+  },
+  listeningPorts: async (pids) => {
+    const listeners = new Map<number, RunProcessPort[]>();
+    for (const chunk of chunked(pids)) {
+      const output = await command(
+        "lsof",
+        ["-nP", "-iTCP", "-sTCP:LISTEN", "-a", "-p", chunk.join(","), "-Fpn"],
+        [1],
+      );
+      for (const [pid, ports] of parseLsofListeners(output)) listeners.set(pid, ports);
+    }
+    return listeners;
+  },
+});
+
+const PROC = "/proc";
+
+const isGone = (error: unknown): boolean => {
+  const code = (error as NodeJS.ErrnoException).code;
+  return code === "ENOENT" || code === "ESRCH";
+};
+
+const explainAccess = (error: unknown, pid: number, what: string): Error => {
+  const code = (error as NodeJS.ErrnoException).code;
+  if (code === "EACCES" || code === "EPERM") {
+    return new Error(
+      `${what} von Prozess ${pid} ist nicht lesbar (${code}); als root braucht die Prozessüberwachung CAP_SYS_PTRACE`,
+    );
+  }
+  return error instanceof Error ? error : new Error(String(error));
+};
+
+export interface LinuxStat {
+  comm: string;
+  state: string;
+  ppid: number;
+  pgid: number;
+  startTime: string;
+}
+
+export const parseLinuxStat = (text: string): LinuxStat => {
+  const open = text.indexOf("(");
+  const close = text.lastIndexOf(")");
+  const fields = open >= 0 && close > open ? text.slice(close + 2).trim().split(" ") : [];
+  if (fields.length < 20) throw new Error(`Unlesbare stat-Zeile: ${text.trim()}`);
+  return {
+    comm: text.slice(open + 1, close),
+    state: fields[0],
+    ppid: Number(fields[1]),
+    pgid: Number(fields[2]),
+    startTime: fields[19],
+  };
+};
+
+const formatIpv6 = (groups: readonly number[]): string => {
+  let bestStart = -1;
+  let bestLength = 0;
+  for (let index = 0; index < groups.length;) {
+    if (groups[index] !== 0) {
+      index += 1;
+      continue;
+    }
+    let end = index;
+    while (end < groups.length && groups[end] === 0) end += 1;
+    if (end - index > bestLength) {
+      bestStart = index;
+      bestLength = end - index;
+    }
+    index = end;
+  }
+  const hex = groups.map((group) => group.toString(16));
+  if (bestLength < 2) return hex.join(":");
+  const head = hex.slice(0, bestStart).join(":");
+  const tail = hex.slice(bestStart + bestLength).join(":");
+  return `${head}::${tail}`;
+};
+
+export const addressFromHex = (hex: string): string => {
+  if (hex.length === 8) {
+    const bytes = [3, 2, 1, 0].map((index) => parseInt(hex.slice(index * 2, index * 2 + 2), 16));
+    const address = bytes.join(".");
+    return address === "0.0.0.0" ? WILDCARD : address;
+  }
+  if (hex.length === 32) {
+    const bytes: number[] = [];
+    for (let word = 0; word < 4; word += 1) {
+      for (const index of [3, 2, 1, 0]) {
+        const offset = word * 8 + index * 2;
+        bytes.push(parseInt(hex.slice(offset, offset + 2), 16));
+      }
+    }
+    const groups = Array.from({ length: 8 }, (_, index) => (bytes[index * 2] << 8) | bytes[index * 2 + 1]);
+    if (groups.every((group) => group === 0)) return WILDCARD;
+    return formatIpv6(groups);
+  }
+  throw new Error(`Unbekannte Adressform in /proc/net/tcp: ${hex}`);
+};
+
+export interface LinuxListener {
+  inode: string;
+  port: RunProcessPort;
+}
+
+export const parseLinuxTcpTable = (text: string): LinuxListener[] =>
+  text.split("\n").slice(1).filter((line) => line.trim() !== "").flatMap((line) => {
+    const fields = line.trim().split(/\s+/);
+    if (fields.length < 10) throw new Error(`Unlesbare Zeile in /proc/net/tcp: ${line.trim()}`);
+    if (fields[3] !== "0A") return [];
+    const [hexAddress, hexPort] = fields[1].split(":");
+    return [{ inode: fields[9], port: { port: parseInt(hexPort, 16), address: addressFromHex(hexAddress) } }];
+  });
+
+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> => {
+  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`),
+    ]);
+  } catch (error) {
+    if (isGone(error)) return undefined;
+    throw error;
+  }
+  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`);
+  const args = cmdline.toString("utf8").split("\0").filter((argument) => argument !== "");
+  return {
+    pid,
+    ppid: parsed.ppid,
+    pgid: parsed.pgid,
+    uid,
+    startKey: parsed.startTime,
+    command: args.length > 0 ? args.join(" ") : `[${parsed.comm}]`,
+  };
+};
+
+const readLinuxMarker = async (pid: number): Promise<string | undefined> => {
+  let environ: Buffer;
+  try {
+    environ = await readFile(`${PROC}/${pid}/environ`);
+  } catch (error) {
+    if (isGone(error)) return undefined;
+    throw explainAccess(error, pid, "Die Umgebung");
+  }
+  const prefix = `${RUN_MARKER_ENV}=`;
+  const entry = environ.toString("utf8").split("\0").find((candidate) => candidate.startsWith(prefix));
+  return runMarkerOf(entry?.slice(prefix.length));
+};
+
+const linuxListeningInodes = async (): Promise<Map<string, RunProcessPort>> => {
+  const inodes = new Map<string, RunProcessPort>();
+  for (const table of ["tcp", "tcp6"]) {
+    let text: string;
+    try {
+      text = await readFile(`${PROC}/net/${table}`, "utf8");
+    } catch (error) {
+      if (isGone(error)) continue;
+      throw error;
+    }
+    for (const listener of parseLinuxTcpTable(text)) inodes.set(listener.inode, listener.port);
+  }
+  return inodes;
+};
+
+const linuxSocketInodes = async (pid: number): Promise<string[]> => {
+  const directory = `${PROC}/${pid}/fd`;
+  let names: string[];
+  try {
+    names = await readdir(directory);
+  } catch (error) {
+    if (isGone(error)) return [];
+    throw explainAccess(error, pid, "Die Dateideskriptoren");
+  }
+  const inodes: string[] = [];
+  for (const name of names) {
+    let target: string;
+    try {
+      target = await readlink(`${directory}/${name}`);
+    } catch (error) {
+      if (isGone(error)) continue;
+      throw explainAccess(error, pid, "Die Dateideskriptoren");
+    }
+    const match = /^socket:\[(\d+)\]$/.exec(target);
+    if (match) inodes.push(match[1]);
+  }
+  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);
+      }
+      if (ports.length > 0) listeners.set(pid, ports);
+    }
+    return listeners;
+  },
+});
+
+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(`Die Prozessüberwachung kennt die Plattform ${platform} nicht (nur darwin und linux)`);
+};

package/plugins/ragents.processes/server/snapshot.ts

@@ -0,0 +1,63 @@
+import path from "node:path";
+import type { RunProcess, RunProcessPort } from "../contract.js";
+import { processIdOf, type ProcessRecord } from "./process-table.js";
+
+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"]);
+const LABEL_LIMIT = 40;
+
+const scriptOf = (parts: readonly string[]): string | undefined => {
+  const index = parts.findIndex((part, position) => position > 0 && !part.startsWith("-"));
+  if (index < 0 || INLINE_SCRIPT_FLAGS.has(parts[index - 1])) return undefined;
+  return path.basename(parts[index]);
+};
+
+export const labelOf = (command: string): string => {
+  const parts = command.trim().split(/\s+/);
+  const name = path.basename(parts[0] ?? "");
+  const script = INTERPRETERS.has(name) ? scriptOf(parts) : undefined;
+  const label = script ? `${name} ${script}` : name;
+  return label.length > LABEL_LIMIT ? `${label.slice(0, LABEL_LIMIT - 1)}…` : label;
+};
+
+export interface ObservationInput {
+  runId: string;
+  serverPid: number;
+  records: readonly ProcessRecord[];
+  markerOf: (record: ProcessRecord) => string | undefined;
+  ports: ReadonlyMap<number, readonly RunProcessPort[]>;
+  firstSeen: (record: ProcessRecord) => string;
+}
+
+const wildcardFirst = (port: RunProcessPort): number => port.address === "*" ? 0 : 1;
+
+const byPort = (left: RunProcessPort, right: RunProcessPort): number =>
+  left.port - right.port || wildcardFirst(left) - wildcardFirst(right) || left.address.localeCompare(right.address);
+
+const byAppearance = (left: RunProcess, right: RunProcess): 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[] => {
+  const toolCallGroups = new Set(
+    input.records.filter((record) => record.ppid === input.serverPid).map((record) => record.pgid),
+  );
+  return input.records
+    .filter((record) => input.markerOf(record) === input.runId)
+    .filter((record) => record.pid !== input.serverPid)
+    .flatMap((record) => {
+      const ports = [...(input.ports.get(record.pid) ?? [])].sort(byPort);
+      const origin = toolCallGroups.has(record.pgid) ? "tool-call" as const : "background" as const;
+      if (origin === "tool-call" && ports.length === 0) return [];
+      return [{
+        id: processIdOf(record),
+        pid: record.pid,
+        label: labelOf(record.command),
+        command: record.command,
+        origin,
+        ports,
+        seenSince: input.firstSeen(record),
+      }];
+    })
+    .sort(byAppearance);
+};

package/plugins/ragents.processes/server/terminator.ts

@@ -0,0 +1,164 @@
+import { DomainError } from "@aicontainer/ragents";
+import { runMarkerOf } from "@aicontainer/workspace-executor";
+import { processIdOf, type ProcessRecord, type ProcessTable } from "./process-table.js";
+
+export interface ProcessTerminationOptions {
+  table: ProcessTable;
+  serverPid: number;
+  serverUid: number | undefined;
+  termGraceMs?: number;
+  killGraceMs?: number;
+  timeoutMs?: number;
+  pollIntervalMs?: number;
+  sendSignal?: (pid: number, signal: "SIGTERM" | "SIGKILL") => void;
+}
+
+export interface ProcessTerminationContext {
+  signal?: AbortSignal;
+  assertAllowed?: () => void;
+}
+
+interface Attempt {
+  termAt: number;
+  killAt?: number;
+}
+
+const delay = (ms: number): Promise<void> => new Promise((resolve) => setTimeout(resolve, ms));
+const gone = (error: unknown): boolean => (error as NodeJS.ErrnoException).code === "ESRCH";
+
+export class RunProcessTerminator {
+  readonly #options: ProcessTerminationOptions;
+  readonly #termGraceMs: number;
+  readonly #killGraceMs: number;
+  readonly #timeoutMs: number;
+  readonly #pollIntervalMs: number;
+  readonly #sendSignal: NonNullable<ProcessTerminationOptions["sendSignal"]>;
+
+  constructor(options: ProcessTerminationOptions) {
+    this.#options = options;
+    this.#termGraceMs = options.termGraceMs ?? 2_000;
+    this.#killGraceMs = options.killGraceMs ?? 1_000;
+    this.#timeoutMs = options.timeoutMs ?? 8_000;
+    this.#pollIntervalMs = options.pollIntervalMs ?? 100;
+    this.#sendSignal = options.sendSignal ?? ((pid, signal) => { process.kill(pid, signal); });
+    for (const duration of [this.#termGraceMs, this.#killGraceMs, this.#timeoutMs, this.#pollIntervalMs]) {
+      if (!Number.isSafeInteger(duration) || duration < 1) throw new Error("Prozess-Stopp-Zeitgrenzen müssen positive ganze Zahlen sein");
+    }
+  }
+
+  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);
+    await this.#stop(runId, processId, context);
+  }
+
+  async stopRun(runId: string, context: ProcessTerminationContext = {}): Promise<void> {
+    await this.#stop(runId, undefined, context);
+  }
+
+  async #stop(runId: string, processId: string | undefined, context: ProcessTerminationContext): Promise<void> {
+    if (runMarkerOf(runId) !== runId) throw new DomainError("invalid-run", "Ungültige Laufkennung", 400);
+    const deadline = Date.now() + this.#timeoutMs;
+    const attempts = new Map<string, Attempt>();
+    const failures = new Map<string, unknown>();
+    const assertClean = () => {
+      if (failures.size === 1) throw [...failures.values()][0];
+      if (failures.size > 1) throw new AggregateError([...failures.values()], `Prozess-Stopp ist für ${failures.size} Prozesse fehlgeschlagen`);
+    };
+    let first = true;
+    let emptyScans = 0;
+    while (true) {
+      this.#assertAllowed(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);
+      }
+      first = false;
+      const targets = readable.filter((record) => markers.get(record.pid) === runId
+        && (processId === undefined || processIdOf(record) === processId));
+      if (targets.length === 0) {
+        if (processId !== undefined || ++emptyScans >= 2) {
+          assertClean();
+          return;
+        }
+      } else {
+        emptyScans = 0;
+        for (const record of targets) {
+          const key = processIdOf(record);
+          if (failures.has(key)) continue;
+          try {
+            this.#assertUnprotected(record, records);
+            const attempt = attempts.get(key);
+            if (!attempt) {
+              if (await this.#signal(record, runId, "SIGTERM", context, deadline)) attempts.set(key, { termAt: Date.now() });
+            } 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`);
+            }
+          } catch (error) {
+            this.#assertAllowed(context, deadline);
+            if (processId !== undefined) throw error;
+            failures.set(key, error);
+          }
+        }
+        if (targets.every((record) => failures.has(processIdOf(record)))) assertClean();
+      }
+      await delay(Math.min(this.#pollIntervalMs, Math.max(1, deadline - Date.now())));
+    }
+  }
+
+  #readable(record: ProcessRecord): boolean {
+    return this.#options.serverUid === undefined || this.#options.serverUid === 0 || record.uid === this.#options.serverUid;
+  }
+
+  #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;
+    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);
+  }
+
+  #assertAllowed(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`);
+  }
+
+  async #bounded<T>(operation: Promise<T>, deadline: number): Promise<T> {
+    let timer: ReturnType<typeof setTimeout> | undefined;
+    try {
+      return await Promise.race([operation, new Promise<never>((_, reject) => {
+        timer = setTimeout(() => reject(new Error("Die Prozesstabelle antwortet nicht innerhalb der Stopp-Zeitgrenze")), Math.max(1, deadline - Date.now()));
+      })]);
+    } finally {
+      if (timer) clearTimeout(timer);
+    }
+  }
+
+  async #signal(expected: ProcessRecord, runId: string, signal: "SIGTERM" | "SIGKILL", context: ProcessTerminationContext, deadline: number): Promise<boolean> {
+    const markers = await this.#bounded(this.#options.table.runMarkers([expected.pid]), deadline);
+    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);
+    this.#assertUnprotected(current, records);
+    this.#assertAllowed(context, deadline);
+    try {
+      this.#sendSignal(current.pid, signal);
+      return true;
+    } catch (error) {
+      if (gone(error)) return false;
+      throw new Error(`${signal} für Prozess ${current.pid} ist fehlgeschlagen: ${error instanceof Error ? error.message : String(error)}`);
+    }
+  }
+}