@aria-cli/tools 1.0.8 → 1.0.10

package/src/executors/shell.ts

@@ -1,1243 +0,0 @@
-/**
- * @aria/tools - Shell tool executors
- *
- * Implementation of shell operations for ARIA tool system.
- */
-
-import { spawn } from "node:child_process";
-import { constants as osConstants } from "node:os";
-import type {
-  ProcessInfoRef,
-  ProcessRegistryRef,
-  ToolContext,
-  ToolResult,
-  WaitProcessResultRef,
-} from "../types.js";
-import type { PTYSession } from "./pty.js";
-import { success, fail, getErrorMessage } from "./utils.js";
-import { classifyCommand, classifyExecInvocation } from "./shell-safety.js";
-
-/**
- * Environment variables that are dangerous in ALL contexts — including
- * the host's own process.env. These enable code injection or library
- * hijacking and should never reach child processes.
- */
-export const BLOCKED_ENV_VARS = new Set([
-  "LD_PRELOAD",
-  "LD_LIBRARY_PATH",
-  "DYLD_INSERT_LIBRARIES",
-  "DYLD_FRAMEWORK_PATH",
-  "DYLD_LIBRARY_PATH",
-  "BASH_ENV",
-  "ENV",
-  "CDPATH",
-  "GLOBIGNORE",
-  "PROMPT_COMMAND",
-  "SHELLOPTS",
-  "BASHOPTS",
-  // Git context hijacks: inherited vars can redirect repository resolution.
-  "GIT_DIR",
-  "GIT_WORK_TREE",
-  "GIT_INDEX_FILE",
-  "GIT_OBJECT_DIRECTORY",
-  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
-  "GIT_COMMON_DIR",
-  "GIT_PREFIX",
-  "GIT_INTERNAL_SUPER_PREFIX",
-  "GIT_CONFIG",
-  "GIT_CONFIG_GLOBAL",
-  "GIT_CONFIG_SYSTEM",
-  "GIT_CONFIG_COUNT",
-  "GIT_CEILING_DIRECTORIES",
-]);
-
-/**
- * Git environment keys that can redirect repository/config context or mutate
- * commit identity unexpectedly when inherited by child processes.
- *
- * NOTE: We intentionally keep transport/debug keys like GIT_SSH_COMMAND and
- * GIT_TRACE untouched to avoid breaking legitimate workflows.
- */
-const GIT_BLOCKED_EXACT_KEYS = new Set([
-  "GIT_DIR",
-  "GIT_WORK_TREE",
-  "GIT_INDEX_FILE",
-  "GIT_INDEX_VERSION",
-  "GIT_COMMON_DIR",
-  "GIT_OBJECT_DIRECTORY",
-  "GIT_ALTERNATE_OBJECT_DIRECTORIES",
-  "GIT_CEILING_DIRECTORIES",
-  "GIT_DISCOVERY_ACROSS_FILESYSTEM",
-  "GIT_NAMESPACE",
-  "GIT_CONFIG",
-  "GIT_CONFIG_GLOBAL",
-  "GIT_CONFIG_SYSTEM",
-  "GIT_CONFIG_NOSYSTEM",
-  "GIT_CONFIG_COUNT",
-  "GIT_CONFIG_PARAMETERS",
-]);
-
-const GIT_BLOCKED_PREFIXES = [
-  "GIT_CONFIG_KEY_",
-  "GIT_CONFIG_VALUE_",
-  "GIT_AUTHOR_",
-  "GIT_COMMITTER_",
-];
-
-export function isBlockedGitEnvVar(key: string): boolean {
-  const upper = key.toUpperCase();
-  if (GIT_BLOCKED_EXACT_KEYS.has(upper)) {
-    return true;
-  }
-  return GIT_BLOCKED_PREFIXES.some((prefix) => upper.startsWith(prefix));
-}
-
-/**
- * Strip git-context env keys from a source env object.
- */
-export function sanitizeGitEnv(
-  env: NodeJS.ProcessEnv | Record<string, string | undefined> = process.env,
-): Record<string, string> {
-  const sanitized: Record<string, string> = {};
-  for (const [key, value] of Object.entries(env)) {
-    if (value === undefined) continue;
-    if (isBlockedGitEnvVar(key)) continue;
-    sanitized[key] = value;
-  }
-  return sanitized;
-}
-
-/**
- * Additional variables blocked from tool-injected input (inputEnv, ctx.env)
- * but NOT from process.env. The host's PATH/HOME/SHELL are legitimate —
- * only tool-provided overrides are dangerous (hijacking resolution paths).
- */
-export const BLOCKED_INPUT_ENV_VARS = new Set([
-  ...BLOCKED_ENV_VARS,
-  // Executable/module resolution hijacks (aria-mx5)
-  "PATH",
-  "NODE_OPTIONS",
-  "NODE_PATH",
-  "PYTHONPATH",
-  // Shell/environment manipulation
-  "IFS",
-  "HOME",
-  "SHELL",
-  "EDITOR",
-  "VISUAL",
-  // Java runtime hijacks (aria-skg)
-  "JAVA_TOOL_OPTIONS",
-  "_JAVA_OPTIONS",
-  "CLASSPATH",
-  // Ruby runtime hijacks (aria-skg)
-  "RUBYOPT",
-  "GEM_HOME",
-  "GEM_PATH",
-  // Perl runtime hijacks (aria-skg)
-  "PERL5OPT",
-  "PERL5LIB",
-  // Python startup hijack (aria-skg) — PYTHONPATH already covered above
-  "PYTHONSTARTUP",
-]);
-
-function isBlockedProcessEnvVar(key: string): boolean {
-  return BLOCKED_ENV_VARS.has(key.toUpperCase()) || isBlockedGitEnvVar(key);
-}
-
-function isBlockedInputEnvVar(key: string): boolean {
-  return BLOCKED_INPUT_ENV_VARS.has(key.toUpperCase()) || isBlockedGitEnvVar(key);
-}
-
-/**
- * Merges environment variables from context and input.
- *
- * Three-tier filtering:
- * - process.env: filtered through BLOCKED_ENV_VARS (injection-only vars like LD_PRELOAD)
- * - ctx.env / inputEnv: filtered through BLOCKED_INPUT_ENV_VARS (also blocks PATH/HOME/SHELL hijacking)
- */
-export function mergeEnv(
-  ctx: ToolContext,
-  inputEnv?: Record<string, string>,
-): Record<string, string> {
-  let sanitizedInput = inputEnv;
-  if (inputEnv) {
-    sanitizedInput = {};
-    for (const [key, value] of Object.entries(inputEnv)) {
-      if (isBlockedInputEnvVar(key)) {
-        continue;
-      }
-      sanitizedInput[key] = value;
-    }
-  }
-  let sanitizedCtxEnv = ctx.env;
-  if (ctx.env) {
-    sanitizedCtxEnv = {};
-    for (const [key, value] of Object.entries(ctx.env)) {
-      if (isBlockedInputEnvVar(key)) {
-        continue;
-      }
-      sanitizedCtxEnv[key] = value;
-    }
-  }
-  // Filter process.env through the base blocklist only — the host's
-  // PATH/HOME/SHELL are legitimate and needed by child processes.
-  const sanitizedProcessEnv: Record<string, string> = {};
-  for (const [key, value] of Object.entries(process.env)) {
-    if (value === undefined) continue;
-    if (isBlockedProcessEnvVar(key)) {
-      continue;
-    }
-    sanitizedProcessEnv[key] = value;
-  }
-  return {
-    ...sanitizedProcessEnv,
-    ...sanitizedCtxEnv,
-    ...sanitizedInput,
-  } as Record<string, string>;
-}
-
-/**
- * Sanitize environment for child processes without requiring a ToolContext.
- *
- * Applies the same two-tier filtering as mergeEnv:
- * - process.env is filtered through BLOCKED_ENV_VARS
- * - inputEnv (caller-supplied overrides) is filtered through BLOCKED_INPUT_ENV_VARS
- *
- * Intended for executors (e.g. PTY) that do not have a ToolContext.
- */
-export function sanitizeEnv(inputEnv?: Record<string, string>): Record<string, string> {
-  // Filter process.env through the base blocklist
-  const sanitizedProcessEnv: Record<string, string> = {};
-  for (const [key, value] of Object.entries(process.env)) {
-    if (value === undefined) continue;
-    if (isBlockedProcessEnvVar(key)) {
-      continue;
-    }
-    sanitizedProcessEnv[key] = value;
-  }
-
-  // Filter inputEnv through the stricter input blocklist
-  let sanitizedInput: Record<string, string> | undefined;
-  if (inputEnv) {
-    sanitizedInput = {};
-    for (const [key, value] of Object.entries(inputEnv)) {
-      if (isBlockedInputEnvVar(key)) {
-        continue;
-      }
-      sanitizedInput[key] = value;
-    }
-  }
-
-  return {
-    ...sanitizedProcessEnv,
-    ...sanitizedInput,
-  };
-}
-
-// ============================================================================
-// Bash Executor
-// ============================================================================
-
-export interface BashInput {
-  /** Shell command to execute */
-  command: string;
-  /** Working directory override */
-  cwd?: string;
-  /** Additional environment variables */
-  env?: Record<string, string>;
-  /** Timeout in milliseconds */
-  timeout?: number;
-}
-
-export interface BashOutput {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}
-
-/**
- * Executes a command through bash shell.
- * Supports shell features like pipes, redirection, and variable expansion.
- */
-export async function executeBash(input: BashInput, ctx: ToolContext): Promise<ToolResult> {
-  // Shell safety: block catastrophic commands before any execution
-  const risk = classifyCommand(input.command);
-  if (risk === "blocked") {
-    return fail(`Command blocked by shell safety policy: ${input.command}`);
-  }
-
-  // Check if already aborted before starting
-  if (ctx.abortSignal?.aborted) {
-    return fail("Command cancelled");
-  }
-
-  const cwd = input.cwd ?? ctx.workingDir;
-  const env = mergeEnv(ctx, input.env);
-  const timeout = input.timeout ?? 120_000;
-  return executeExec(
-    {
-      program: "/bin/bash",
-      args: ["-lc", input.command],
-      cwd,
-      env: input.env,
-      timeout,
-    },
-    {
-      ...ctx,
-      workingDir: cwd,
-      env,
-    },
-  );
-}
-
-// ============================================================================
-// Exec Executor
-// ============================================================================
-
-export interface ExecInput {
-  /** Program to execute */
-  program: string;
-  /** Arguments to pass to the program */
-  args?: string[];
-  /** Working directory override */
-  cwd?: string;
-  /** Additional environment variables */
-  env?: Record<string, string>;
-  /** Timeout in milliseconds */
-  timeout?: number;
-}
-
-export interface ExecOutput {
-  stdout: string;
-  stderr: string;
-  exitCode: number;
-}
-
-function signalExecProcessTree(
-  pid: number | undefined,
-  signal: NodeJS.Signals,
-  detachedProcessGroup: boolean,
-): void {
-  if (!pid) {
-    return;
-  }
-
-  if (detachedProcessGroup) {
-    try {
-      process.kill(-pid, signal);
-      return;
-    } catch {
-      // Fall back to the leader PID if the process group is already gone or unsupported.
-    }
-  }
-
-  try {
-    process.kill(pid, signal);
-  } catch {
-    // Process may already be dead.
-  }
-}
-
-function isExecProcessTreeAlive(pid: number | undefined, detachedProcessGroup: boolean): boolean {
-  if (!pid) {
-    return false;
-  }
-
-  if (detachedProcessGroup) {
-    try {
-      process.kill(-pid, 0);
-      return true;
-    } catch {
-      // Fall through to the leader PID check in case the group probe is unsupported.
-    }
-  }
-
-  try {
-    process.kill(pid, 0);
-    return true;
-  } catch {
-    return false;
-  }
-}
-
-async function waitForExecProcessTreeExit(
-  pid: number | undefined,
-  detachedProcessGroup: boolean,
-  timeoutMs = 1_000,
-): Promise<void> {
-  if (!pid) {
-    return;
-  }
-
-  const deadline = Date.now() + timeoutMs;
-  while (Date.now() < deadline) {
-    if (!isExecProcessTreeAlive(pid, detachedProcessGroup)) {
-      return;
-    }
-    await new Promise((resolve) => setTimeout(resolve, 25));
-  }
-}
-
-/**
- * Executes a program directly without shell interpretation.
- * Safer than bash as it doesn't expand shell metacharacters.
- */
-export async function executeExec(input: ExecInput, ctx: ToolContext): Promise<ToolResult> {
-  const args = input.args ?? [];
-
-  // Shell safety: block catastrophic commands before any execution.
-  // For explicit shell wrappers (e.g. bash -c ...), classify payload command.
-  const reconstructed = [input.program, ...args].join(" ");
-  const risk = classifyExecInvocation(input.program, args);
-  if (risk === "blocked") {
-    return fail(`Command blocked by shell safety policy: ${reconstructed}`, {
-      stdout: "",
-      stderr: "",
-      exitCode: 1,
-    } satisfies ExecOutput);
-  }
-
-  // Check if already aborted before starting
-  if (ctx.abortSignal?.aborted) {
-    return fail("Command cancelled", {
-      stdout: "",
-      stderr: "",
-      exitCode: 1,
-    } satisfies ExecOutput);
-  }
-
-  const cwd = input.cwd ?? ctx.workingDir;
-  const env = mergeEnv(ctx, input.env);
-  const timeout = input.timeout ?? 120_000;
-
-  return new Promise((resolve) => {
-    const detachedProcessGroup = process.platform !== "win32";
-    const proc = spawn(input.program, args, {
-      cwd,
-      env,
-      detached: detachedProcessGroup,
-    });
-
-    // Track PID in process registry for cleanup on session close
-    if (proc.pid && ctx.processRegistry) {
-      ctx.processRegistry.add(proc.pid, {
-        command: input.program,
-        args,
-        cwd,
-        interactive: false,
-      });
-    }
-
-    let stdout = "";
-    let stderr = "";
-    let timedOut = false;
-    let cancelled = false;
-    let resolved = false;
-    let timeoutId: NodeJS.Timeout | undefined;
-    let killTimeoutId: NodeJS.Timeout | undefined;
-
-    const doResolve = (
-      result: ToolResult,
-      exit?: { exitCode?: number | null; signal?: string | null },
-    ) => {
-      if (resolved) return;
-      resolved = true;
-      if (timeoutId) clearTimeout(timeoutId);
-      if (killTimeoutId) clearTimeout(killTimeoutId);
-      // Clean up abort listener
-      if (ctx.abortSignal && onAbort) {
-        ctx.abortSignal.removeEventListener("abort", onAbort);
-      }
-      // Keep detached process groups tracked until the whole group is gone.
-      ctx.processRegistry?.recordExitMetadata?.(proc.pid ?? 0, exit);
-      if (
-        proc.pid &&
-        ctx.processRegistry &&
-        !(detachedProcessGroup && isExecProcessTreeAlive(proc.pid, detachedProcessGroup))
-      ) {
-        ctx.processRegistry.remove(proc.pid, exit);
-      }
-      resolve(result);
-    };
-
-    // Wire abort signal to kill the process
-    let onAbort: (() => void) | undefined;
-    if (ctx.abortSignal) {
-      onAbort = () => {
-        cancelled = true;
-        signalExecProcessTree(proc.pid, "SIGTERM", detachedProcessGroup);
-        // Follow up with SIGKILL if SIGTERM doesn't work
-        killTimeoutId = setTimeout(() => {
-          signalExecProcessTree(proc.pid, "SIGKILL", detachedProcessGroup);
-        }, 1000);
-      };
-      ctx.abortSignal.addEventListener("abort", onAbort, { once: true });
-    }
-
-    if (timeout) {
-      timeoutId = setTimeout(() => {
-        timedOut = true;
-        signalExecProcessTree(proc.pid, "SIGTERM", detachedProcessGroup);
-        // If SIGTERM doesn't work, follow up with SIGKILL after 1 second
-        killTimeoutId = setTimeout(() => {
-          signalExecProcessTree(proc.pid, "SIGKILL", detachedProcessGroup);
-        }, 1000);
-      }, timeout);
-    }
-
-    proc.stdout?.on("data", (data: Buffer) => {
-      stdout += data.toString();
-    });
-
-    proc.stderr?.on("data", (data: Buffer) => {
-      stderr += data.toString();
-    });
-
-    proc.on("error", (err) => {
-      const exitCode =
-        typeof err === "object" &&
-        err &&
-        "code" in err &&
-        (err as { code?: unknown }).code === "ENOENT"
-          ? 127
-          : 1;
-      doResolve(
-        fail(getErrorMessage(err), {
-          stdout: "",
-          stderr,
-          exitCode,
-        } satisfies ExecOutput),
-      );
-    });
-
-    proc.on("close", (code, signal) => {
-      void (async () => {
-        if (cancelled || timedOut) {
-          if (killTimeoutId) {
-            clearTimeout(killTimeoutId);
-            killTimeoutId = undefined;
-          }
-          signalExecProcessTree(proc.pid, "SIGKILL", detachedProcessGroup);
-          await waitForExecProcessTreeExit(proc.pid, detachedProcessGroup);
-        }
-
-        if (cancelled) {
-          doResolve(
-            fail("Command cancelled", {
-              stdout,
-              stderr,
-              exitCode: code ?? 1,
-            } satisfies ExecOutput),
-            { exitCode: code, signal },
-          );
-          return;
-        }
-
-        if (timedOut) {
-          doResolve(
-            fail("Command timed out", {
-              stdout,
-              stderr,
-              exitCode: code ?? 1,
-            } satisfies ExecOutput),
-            { exitCode: code, signal },
-          );
-          return;
-        }
-
-        if (signal) {
-          const signaledExitCode = osConstants.signals[signal] ?? 1;
-          doResolve(
-            fail(`Command exited due to signal ${signal}`, {
-              stdout,
-              stderr,
-              exitCode: code ?? signaledExitCode,
-            } satisfies ExecOutput),
-            { exitCode: code, signal },
-          );
-          return;
-        }
-
-        const exitCode = code ?? 0;
-        if (exitCode === 0) {
-          doResolve(
-            success("Command executed successfully", {
-              stdout,
-              stderr,
-              exitCode,
-            } satisfies ExecOutput),
-            { exitCode, signal },
-          );
-        } else {
-          doResolve(
-            fail(`Command exited with code ${exitCode}`, {
-              stdout,
-              stderr,
-              exitCode,
-            } satisfies ExecOutput),
-            { exitCode, signal },
-          );
-        }
-      })();
-    });
-  });
-}
-
-// ============================================================================
-// Spawn Executor
-// ============================================================================
-
-export interface SpawnInput {
-  /** Program to execute */
-  program: string;
-  /** Arguments to pass to the program */
-  args?: string[];
-  /** Working directory override */
-  cwd?: string;
-  /** Additional environment variables */
-  env?: Record<string, string>;
-  /** Start as interactive PTY session (enables write_stdin). Default: false */
-  interactive?: boolean;
-}
-
-export interface SpawnOutput {
-  pid: number;
-}
-
-/**
- * Spawns a background process and returns immediately with its PID.
- * The process is detached and will continue running after the parent exits.
- */
-export async function executeSpawn(input: SpawnInput, ctx: ToolContext): Promise<ToolResult> {
-  // Shell safety: block catastrophic commands before spawning.
-  // Detached processes are especially dangerous — they outlive the session.
-  // For explicit shell wrappers (e.g. bash -c ...), classify payload command.
-  const args = input.args ?? [];
-  const reconstructed = [input.program, ...args].join(" ");
-  const risk = classifyExecInvocation(input.program, args);
-  if (risk === "blocked") {
-    return fail(`Command blocked by shell safety policy: ${reconstructed}`);
-  }
-
-  // Check if already aborted before spawning
-  if (ctx.abortSignal?.aborted) {
-    return fail("Command cancelled");
-  }
-
-  // Check for interactive mode — use PTY instead of detached spawn
-  if (input.interactive === true) {
-    if (!ctx.ptySessionStore) {
-      return fail("PTY session store not available — interactive mode requires runner wiring");
-    }
-
-    // Import createPTYSession dynamically to avoid circular deps at module level
-    const { createPTYSession } = await import("./pty.js");
-    const session = await createPTYSession({
-      command: input.program,
-      args: input.args,
-      cwd: input.cwd ?? ctx.workingDir,
-      env: mergeEnv(ctx, input.env),
-    });
-
-    const pid = session.pid;
-    if (!pid) {
-      session.close();
-      return fail("Failed to start interactive session: no PID");
-    }
-
-    // Register in both stores
-    ctx.ptySessionStore.add(pid, session);
-    if (ctx.processRegistry) {
-      ctx.processRegistry.add(pid, {
-        command: input.program,
-        args: input.args ?? [],
-        cwd: input.cwd ?? ctx.workingDir,
-        interactive: true,
-      });
-    }
-
-    const deregisterInteractiveSession = (): void => {
-      ctx.ptySessionStore?.remove(pid);
-      if (ctx.processRegistry?.has(pid)) {
-        ctx.processRegistry.remove(pid, {
-          exitCode: session.exitCode ?? null,
-        });
-      }
-    };
-
-    if (!session.isRunning) {
-      deregisterInteractiveSession();
-    } else {
-      const lifecycleCheckInterval = setInterval(() => {
-        if (!session.isRunning) {
-          clearInterval(lifecycleCheckInterval);
-          deregisterInteractiveSession();
-        }
-      }, 50);
-      lifecycleCheckInterval.unref?.();
-
-      // Wire abort signal to PTY cleanup so ESC/Ctrl+C kills the session
-      if (ctx.abortSignal) {
-        const onAbort = () => {
-          clearInterval(lifecycleCheckInterval);
-          session.close();
-          deregisterInteractiveSession();
-        };
-        ctx.abortSignal.addEventListener("abort", onAbort, { once: true });
-      }
-    }
-
-    return success(`Started interactive session with PID ${pid}`, { pid } satisfies SpawnOutput);
-  }
-
-  const cwd = input.cwd ?? ctx.workingDir;
-  const env = mergeEnv(ctx, input.env);
-
-  return new Promise((resolve) => {
-    let resolved = false;
-    let fallbackTimeoutId: NodeJS.Timeout | undefined;
-
-    const doResolve = (result: ToolResult) => {
-      if (resolved) return;
-      resolved = true;
-      if (fallbackTimeoutId) clearTimeout(fallbackTimeoutId);
-      resolve(result);
-    };
-
-    // Wire abort signal to kill the spawned process.
-    // The listener is NOT removed in doResolve because the spawned process
-    // outlives the function call. The { once: true } option auto-cleans it.
-    let spawnedPid: number | undefined;
-    if (ctx.abortSignal) {
-      ctx.abortSignal.addEventListener(
-        "abort",
-        () => {
-          if (spawnedPid) {
-            try {
-              // Kill the process group (negative PID) since process is detached
-              process.kill(-spawnedPid, "SIGTERM");
-            } catch {
-              try {
-                process.kill(spawnedPid, "SIGTERM");
-              } catch {
-                // Process may already be dead
-              }
-            }
-          }
-        },
-        { once: true },
-      );
-    }
-
-    try {
-      const proc = spawn(input.program, args, {
-        cwd,
-        env,
-        detached: true,
-        stdio: "ignore",
-      });
-
-      // Handle spawn errors (e.g., program not found)
-      proc.on("error", (err) => {
-        doResolve(fail(getErrorMessage(err)));
-      });
-
-      // If we have a PID, the spawn was successful
-      if (proc.pid) {
-        spawnedPid = proc.pid;
-        proc.on("exit", (code, signal) => {
-          ctx.processRegistry?.recordExitMetadata?.(proc.pid!, {
-            exitCode: code,
-            signal,
-          });
-          if (ctx.processRegistry && !isExecProcessTreeAlive(proc.pid, true)) {
-            ctx.processRegistry.remove(proc.pid!, {
-              exitCode: code,
-              signal,
-            });
-          }
-        });
-        // Track PID in process registry for cleanup on session close.
-        // Spawned (detached) processes are never deregistered here —
-        // they live until exit, killAll(), or the user explicitly kills them.
-        if (ctx.processRegistry) {
-          ctx.processRegistry.add(proc.pid, {
-            command: input.program,
-            args,
-            cwd,
-            interactive: false,
-          });
-        }
-        // Unref to allow parent to exit independently
-        proc.unref();
-        doResolve(
-          success(`Spawned process with PID ${proc.pid}`, {
-            pid: proc.pid,
-          } satisfies SpawnOutput),
-        );
-      } else {
-        // This shouldn't normally happen, but handle it just in case
-        // Wait briefly for error event
-        fallbackTimeoutId = setTimeout(() => {
-          doResolve(fail("Failed to spawn process: no PID returned"));
-        }, 100);
-      }
-    } catch (err) {
-      doResolve(fail(getErrorMessage(err)));
-    }
-  });
-}
-
-// ============================================================================
-// Kill Executor
-// ============================================================================
-
-export interface KillInput {
-  /** Process ID to kill */
-  pid: number;
-  /** Signal to send (default: SIGTERM) */
-  signal?: string;
-}
-
-export interface KillOutput {
-  pid: number;
-  signal: string;
-}
-
-/**
- * Sends a signal to terminate a process by PID.
- */
-export async function executeKill(input: KillInput, ctx: ToolContext): Promise<ToolResult> {
-  const signal = input.signal ?? "SIGTERM";
-
-  try {
-    // Validate and normalize the signal
-    const validatedSignal = validateSignal(signal);
-    if (validatedSignal === undefined) {
-      return fail(`Invalid signal: ${signal}`);
-    }
-
-    // Use process-tree signaling only for ARIA-tracked processes. Generic pid
-    // kills must preserve pid-only semantics for foreign process groups.
-    if (ctx.processRegistry?.has(input.pid)) {
-      signalProcessTree(input.pid, validatedSignal);
-    } else {
-      process.kill(input.pid, validatedSignal);
-    }
-
-    // Keep tracked processes authoritative until exit is actually observed.
-    const registry = ctx.processRegistry;
-    if (registry?.waitForExit && shouldUntrackAfterSignal(validatedSignal)) {
-      await registry.waitForExit(input.pid, 2_000);
-    }
-
-    const signalName = typeof validatedSignal === "number" ? signal : validatedSignal;
-    return success(`Sent ${signalName} to process ${input.pid}`, {
-      pid: input.pid,
-      signal: signalName,
-    } satisfies KillOutput);
-  } catch (err: unknown) {
-    if (err instanceof Error && "code" in err) {
-      const nodeErr = err as NodeJS.ErrnoException;
-      if (nodeErr.code === "ESRCH") {
-        return fail(`Process not found: ${input.pid}`);
-      }
-      if (nodeErr.code === "EPERM") {
-        return fail(`Permission denied to kill process: ${input.pid}`);
-      }
-    }
-    return fail(getErrorMessage(err));
-  }
-}
-
-/**
- * Valid signal names that can be used with process.kill.
- */
-const VALID_SIGNALS = [
-  "SIGHUP",
-  "SIGINT",
-  "SIGQUIT",
-  "SIGILL",
-  "SIGTRAP",
-  "SIGABRT",
-  "SIGBUS",
-  "SIGFPE",
-  "SIGKILL",
-  "SIGUSR1",
-  "SIGSEGV",
-  "SIGUSR2",
-  "SIGPIPE",
-  "SIGALRM",
-  "SIGTERM",
-  "SIGSTKFLT",
-  "SIGCHLD",
-  "SIGCONT",
-  "SIGSTOP",
-  "SIGTSTP",
-  "SIGTTIN",
-  "SIGTTOU",
-  "SIGURG",
-  "SIGXCPU",
-  "SIGXFSZ",
-  "SIGVTALRM",
-  "SIGPROF",
-  "SIGWINCH",
-  "SIGIO",
-  "SIGPWR",
-  "SIGSYS",
-] as const;
-
-type ValidSignal = (typeof VALID_SIGNALS)[number];
-
-const NON_TERMINATING_SIGNALS = new Set<NodeJS.Signals>([
-  "SIGCHLD",
-  "SIGCONT",
-  "SIGSTOP",
-  "SIGTSTP",
-  "SIGTTIN",
-  "SIGTTOU",
-  "SIGURG",
-  "SIGWINCH",
-]);
-
-/**
- * Type guard to check if a string is a valid signal name.
- */
-function isValidSignalName(signal: string): signal is ValidSignal {
-  return VALID_SIGNALS.includes(signal.toUpperCase() as ValidSignal);
-}
-
-/**
- * Validates a signal and returns either the validated signal name or number.
- * Returns undefined for invalid signals.
- */
-function validateSignal(signal: string): NodeJS.Signals | number | undefined {
-  // Handle numeric signal
-  if (/^\d+$/.test(signal)) {
-    const num = parseInt(signal, 10);
-    if (num >= 1 && num <= 31) {
-      return num;
-    }
-    return undefined;
-  }
-
-  // Handle signal names
-  const upperSignal = signal.toUpperCase();
-  if (isValidSignalName(upperSignal)) {
-    return upperSignal as NodeJS.Signals;
-  }
-
-  return undefined;
-}
-
-function shouldUntrackAfterSignal(signal: NodeJS.Signals | number): boolean {
-  if (typeof signal === "number") {
-    const signalName = resolveSignalName(signal);
-    if (!signalName) {
-      // Unknown numeric signals are treated conservatively.
-      return false;
-    }
-    return !NON_TERMINATING_SIGNALS.has(signalName);
-  }
-
-  return !NON_TERMINATING_SIGNALS.has(signal);
-}
-
-function signalProcessTree(pid: number, signal: NodeJS.Signals | number): void {
-  try {
-    if (pid > 0) {
-      process.kill(-pid, signal);
-      return;
-    }
-  } catch {
-    // Fall back to the tracked pid itself when there is no process group to target.
-  }
-
-  process.kill(pid, signal);
-}
-
-function resolveSignalName(signal: number): NodeJS.Signals | undefined {
-  for (const [name, value] of Object.entries(osConstants.signals)) {
-    if (value === signal) {
-      return name as NodeJS.Signals;
-    }
-  }
-  return undefined;
-}
-
-// ============================================================================
-// Process Observability Executors
-// ============================================================================
-
-export interface ListProcessesInput {
-  /** Include exited process snapshots from recent registry history */
-  includeExited?: boolean;
-}
-
-export interface ListProcessesOutput {
-  processes: ProcessInfoRef[];
-  count: number;
-}
-
-function hasLegacyGetAll(
-  registry: ProcessRegistryRef,
-): registry is ProcessRegistryRef & { getAll(): number[] } {
-  return typeof (registry as { getAll?: unknown }).getAll === "function";
-}
-
-export async function executeListProcesses(
-  rawInput: unknown,
-  ctx: ToolContext,
-): Promise<ToolResult> {
-  const input = toRecord(rawInput);
-  const includeExited = typeof input?.includeExited === "boolean" ? input.includeExited : false;
-
-  if (!ctx.processRegistry) {
-    return fail("Process registry not available");
-  }
-
-  const registry = ctx.processRegistry;
-  const processes =
-    typeof registry.listProcesses === "function"
-      ? registry.listProcesses({ includeExited })
-      : hasLegacyGetAll(registry)
-        ? registry.getAll().map(
-            (pid): ProcessInfoRef => ({
-              pid,
-              command: null,
-              args: [],
-              cwd: null,
-              interactive: false,
-              startedAt: new Date().toISOString(),
-              runtimeMs: 0,
-              status: "running",
-              exitCode: null,
-              signal: null,
-              endedAt: null,
-            }),
-          )
-        : [];
-
-  return success(`Found ${processes.length} tracked process${processes.length === 1 ? "" : "es"}`, {
-    processes,
-    count: processes.length,
-  } satisfies ListProcessesOutput);
-}
-
-export interface WaitProcessInput {
-  /** PID to wait on */
-  pid: number;
-  /** Max wait duration in milliseconds (max 300000, default 30000) */
-  timeoutMs?: number;
-  /** Deprecated alias for timeoutMs */
-  timeout?: number;
-}
-
-export interface WaitProcessOutput {
-  pid: number;
-  status: "running" | "exited";
-  exited: boolean;
-  timedOut: boolean;
-  waitedMs: number;
-  command: string | null;
-  args: string[];
-  cwd: string | null;
-  interactive: boolean;
-  startedAt: string;
-  endedAt: string | null;
-  runtimeMs: number;
-  exitCode: number | null;
-  signal: string | null;
-}
-
-export async function executeWaitProcess(rawInput: unknown, ctx: ToolContext): Promise<ToolResult> {
-  const input = toRecord(rawInput);
-  if (!input) {
-    return fail("Invalid input: expected an object");
-  }
-
-  const pid = typeof input.pid === "number" ? input.pid : NaN;
-  if (!pid || pid <= 0 || !Number.isInteger(pid)) {
-    return fail("Invalid PID: must be a positive integer");
-  }
-  if (pid === process.pid) {
-    return fail("Cannot wait on own process");
-  }
-
-  const timeoutMsInput = input.timeoutMs;
-  if (
-    timeoutMsInput !== undefined &&
-    (typeof timeoutMsInput !== "number" || Number.isNaN(timeoutMsInput))
-  ) {
-    return fail("Invalid timeoutMs: must be a number");
-  }
-
-  const timeoutInput = input.timeout;
-  if (
-    timeoutInput !== undefined &&
-    (typeof timeoutInput !== "number" || Number.isNaN(timeoutInput))
-  ) {
-    return fail("Invalid timeout: must be a number");
-  }
-  const timeoutMs = Math.min(Math.max(0, timeoutMsInput ?? timeoutInput ?? 30_000), 300_000);
-
-  if (!ctx.processRegistry) {
-    return fail("Process registry not available");
-  }
-  if (typeof ctx.processRegistry.waitForExit !== "function") {
-    return fail("Process registry does not support waiting");
-  }
-
-  const startedAt = Date.now();
-  const waitResult = await ctx.processRegistry.waitForExit(pid, timeoutMs);
-  const waitedMs = Math.max(0, Date.now() - startedAt);
-  if (waitResult.status === "not_found" || !waitResult.process) {
-    return fail(`Process not tracked: ${pid}`, {
-      pid,
-      exited: false,
-      status: "not_found",
-      timedOut: false,
-      waitedMs,
-    });
-  }
-
-  const data = mapWaitResult(waitResult, waitedMs);
-  if (waitResult.status === "running" || waitResult.timedOut) {
-    return fail(`Timed out waiting for process ${pid}`, data);
-  }
-
-  return success(`Process ${pid} exited`, data);
-}
-
-function mapWaitResult(waitResult: WaitProcessResultRef, waitedMs: number): WaitProcessOutput {
-  const processInfo = waitResult.process!;
-  const status = waitResult.status === "exited" ? "exited" : "running";
-  return {
-    pid: waitResult.pid,
-    status,
-    exited: status === "exited",
-    timedOut: waitResult.timedOut,
-    waitedMs,
-    command: processInfo.command,
-    args: processInfo.args,
-    cwd: processInfo.cwd,
-    interactive: processInfo.interactive,
-    startedAt: processInfo.startedAt,
-    endedAt: processInfo.endedAt,
-    runtimeMs: processInfo.runtimeMs,
-    exitCode: processInfo.exitCode,
-    signal: processInfo.signal,
-  };
-}
-
-function toRecord(rawInput: unknown): Record<string, unknown> | undefined {
-  if (!rawInput || typeof rawInput !== "object") {
-    return undefined;
-  }
-  return rawInput as Record<string, unknown>;
-}
-
-// ============================================================================
-// WriteStdin Executor
-// ============================================================================
-
-export interface WriteStdinInput {
-  /** PID of the interactive process to write to */
-  pid: number;
-  /** Input string to send to the process */
-  input: string;
-  /** Milliseconds to wait for output after writing (max 30000) */
-  timeout?: number;
-}
-
-export interface WriteStdinOutput {
-  /** Recent output from the session after writing */
-  output: string;
-}
-
-/**
- * Sends input to an interactive PTY session by PID.
- * Requires the process to have been spawned with interactive=true.
- */
-export async function executeWriteStdin(rawInput: unknown, ctx: ToolContext): Promise<ToolResult> {
-  // Validate input shape at runtime
-  if (!rawInput || typeof rawInput !== "object") {
-    return fail("Invalid input: expected an object");
-  }
-  const input = rawInput as Record<string, unknown>;
-
-  const pid = typeof input.pid === "number" ? input.pid : NaN;
-  const inputStr = typeof input.input === "string" ? input.input : undefined;
-  const timeout = typeof input.timeout === "number" ? input.timeout : undefined;
-
-  // Validate PID
-  if (!pid || pid <= 0 || !Number.isInteger(pid)) {
-    return fail("Invalid PID: must be a positive integer");
-  }
-  if (pid === process.pid) {
-    return fail("Cannot write to own process");
-  }
-
-  // Validate input string
-  if (inputStr === undefined) {
-    return fail("Input must be a string");
-  }
-
-  // Look up PTY session store
-  if (!ctx.ptySessionStore) {
-    return fail("PTY session store not available");
-  }
-
-  if (!ctx.ptySessionStore.has(pid)) {
-    return fail(
-      `No interactive session found for PID ${pid}. Use spawn with interactive=true first.`,
-    );
-  }
-
-  // The ptySessionStore ref uses `unknown` return to avoid circular deps,
-  // but the concrete store returns PTYSession instances.
-  const session = ctx.ptySessionStore.get(pid) as PTYSession | undefined;
-  if (!session) {
-    return fail(
-      `No interactive session found for PID ${pid}. Use spawn with interactive=true first.`,
-    );
-  }
-
-  if (!session.isRunning) {
-    return fail(`Process ${pid} has exited (code: ${session.exitCode ?? "unknown"})`);
-  }
-
-  try {
-    // Capture output length before write to extract new output after
-    const outputLenBefore = session.output.length;
-
-    // Write input to the PTY session
-    session.write(inputStr);
-
-    // If timeout specified, poll for new output with early return
-    if (timeout && timeout > 0) {
-      const waitMs = Math.min(timeout, 30_000);
-      const deadline = Date.now() + waitMs;
-      const pollInterval = 50; // Check every 50ms
-      while (Date.now() < deadline) {
-        await new Promise((resolve) => setTimeout(resolve, pollInterval));
-        if (session.output.length > outputLenBefore) break;
-        if (!session.isRunning) break;
-      }
-    }
-
-    // Extract output produced after the write
-    const fullOutput = session.output;
-    const newOutput = fullOutput.slice(outputLenBefore);
-
-    // Cap returned output to 10KB to avoid bloating tool results
-    const cappedOutput = newOutput.length > 10_000 ? newOutput.slice(-10_000) : newOutput;
-
-    return success(`Wrote ${inputStr.length} bytes to PID ${pid}`, {
-      output: cappedOutput,
-    } satisfies WriteStdinOutput);
-  } catch (error) {
-    const msg = error instanceof Error ? error.message : String(error);
-    return fail(`Failed to write to PID ${pid}: ${msg}`);
-  }
-}