fix: centralize process lifecycle and cancellation handling

Add ProcessManager singleton for centralized process lifecycle management:

- Single AbortController per run for coordinated cancellation
- Process registry to track all spawned child processes
- Signal propagation (SIGINT/SIGTERM) to all children with process tree killing
- Terminal state restoration (cursor visibility) on cleanup
- Configurable timeouts via environment variables:
  - MDFLOW_FETCH_TIMEOUT (default: 10s)
  - MDFLOW_COMMAND_TIMEOUT (default: 30s)
  - MDFLOW_AGENT_TIMEOUT (default: no timeout)

Integration points:
- spinner.ts: Coordinates cursor hide/show with ProcessManager
- command.ts: Registers spawned processes for cleanup
- imports.ts: Uses configurable command timeout, registers inline processes
- cli-runner.ts: Initializes ProcessManager, registers cleanup callbacks
- index.ts: Early initialization for EPIPE handling with cursor restoration

Author: johnlindquist

src/cli-runner.ts

@@ -15,6 +15,7 @@ import {
   resolveCommand, buildArgs, runCommand, extractPositionalMappings,
   extractEnvVars, killCurrentChildProcess, hasInteractiveMarker,
 } from "./command";
+import { getProcessManager } from "./process-manager";
 import {
   expandImports, hasImports,
   expandContentImports, expandCommandImports,
@@ -272,14 +273,14 @@ export class CliRunner {
       localFilePath = await this.resolveFilePath(filePath);
     }
 
-    // Signal handling
-    const handleSignal = async (signal: string) => {
-      killCurrentChildProcess();
-      if (isRemote) await cleanupRemote(localFilePath);
-      process.exit(signal === "SIGINT" ? 130 : 143);
-    };
-    process.on("SIGINT", () => handleSignal("SIGINT"));
-    process.on("SIGTERM", () => handleSignal("SIGTERM"));
+    // Initialize ProcessManager for centralized lifecycle management
+    const pm = getProcessManager();
+    pm.initialize();
+
+    // Register cleanup callback for remote file cleanup
+    if (isRemote) {
+      pm.onCleanup(() => cleanupRemote(localFilePath));
+    }
 
     if (!(await this.env.fs.exists(localFilePath))) {
       throw new FileNotFoundError(`File not found: ${localFilePath}`);

src/command.ts

@@ -1,22 +1,27 @@
 /**
  * Command execution - simple, direct, unix-style
  * No abstraction layers, just frontmatter → CLI args → spawn
+ *
+ * Integrates with ProcessManager for centralized process lifecycle management
  */
 
 import type { AgentFrontmatter } from "./types";
 import { basename } from "path";
 import { teeToStdoutAndCollect, teeToStderrAndCollect } from "./stream";
 import { stopSpinner, isSpinnerRunning } from "./spinner";
+import { getProcessManager } from "./process-manager";
 
 /**
  * Module-level reference to the current child process
  * Used for graceful signal handling (SIGINT/SIGTERM cleanup)
+ * @deprecated Use ProcessManager.getInstance() instead for new code
  */
 let currentChildProcess: ReturnType<typeof Bun.spawn> | null = null;
 
 /**
  * Get the current child process reference
  * Returns null if no process is running
+ * @deprecated Use ProcessManager.getInstance().getActiveProcesses() instead
  */
 export function getCurrentChildProcess(): ReturnType<typeof Bun.spawn> | null {
   return currentChildProcess;
@@ -25,8 +30,18 @@ export function getCurrentChildProcess(): ReturnType<typeof Bun.spawn> | null {
 /**
  * Kill the current child process if running
  * Returns true if a process was killed, false otherwise
+ * @deprecated Use ProcessManager.getInstance().killAll() instead
  */
 export function killCurrentChildProcess(): boolean {
+  // First try ProcessManager (which handles process groups)
+  const pm = getProcessManager();
+  if (pm.activeCount > 0) {
+    pm.killAll();
+    currentChildProcess = null;
+    return true;
+  }
+
+  // Fallback for legacy code
   if (currentChildProcess) {
     try {
       currentChildProcess.kill("SIGTERM");
@@ -330,7 +345,11 @@ export async function runCommand(ctx: RunContext): Promise<RunResult> {
     env: runEnv,
   });
 
-  // Store reference for signal handling
+  // Register with ProcessManager for centralized lifecycle management
+  const pm = getProcessManager();
+  pm.register(proc, command);
+
+  // Store reference for legacy signal handling (deprecated)
   currentChildProcess = proc;
 
   let stdout = "";

src/imports.ts

@@ -261,8 +261,21 @@ export const WARN_TOKENS = 50_000;
 export const CHARS_PER_TOKEN = 4;
 const MAX_CHARS = MAX_TOKENS * CHARS_PER_TOKEN;
 
-/** Command execution timeout in milliseconds (30 seconds) */
-const COMMAND_TIMEOUT_MS = 30_000;
+import { getProcessManager } from "./process-manager";
+
+/** Default command execution timeout in milliseconds (30 seconds) */
+const DEFAULT_COMMAND_TIMEOUT_MS = 30_000;
+
+/**
+ * Get command timeout from ProcessManager or use default
+ */
+function getCommandTimeout(): number {
+  try {
+    return getProcessManager().timeouts.commandTimeout;
+  } catch {
+    return DEFAULT_COMMAND_TIMEOUT_MS;
+  }
+}
 
 /** Maximum command output size in characters (~25k tokens) */
 const MAX_COMMAND_OUTPUT_SIZE = 100_000;
@@ -957,6 +970,7 @@ async function processCommandInline(
   // Track process for timeout cleanup
   let proc: ReturnType<typeof Bun.spawn> | null = null;
   let timedOut = false;
+  const pm = getProcessManager();
 
   try {
     proc = Bun.spawn([shell, ...shellArgs], {
@@ -966,6 +980,9 @@ async function processCommandInline(
       env: env as Record<string, string>,
     });
 
+    // Register with ProcessManager for centralized cleanup on SIGINT/SIGTERM
+    pm.register(proc, `inline: ${actualCommand.slice(0, 40)}`);
+
     // Buffers for final output
     const stdoutChunks: Uint8Array[] = [];
     const stderrChunks: Uint8Array[] = [];
@@ -993,12 +1010,14 @@ async function processCommandInline(
     };
 
     // Improvement #4: Execution timeout using Promise.race
+    // Uses configurable timeout from ProcessManager
+    const commandTimeout = getCommandTimeout();
     const timeoutPromise = new Promise<never>((_, reject) => {
       setTimeout(() => {
         timedOut = true;
         proc?.kill();
-        reject(new Error(`Command timed out after ${COMMAND_TIMEOUT_MS}ms: ${actualCommand}`));
-      }, COMMAND_TIMEOUT_MS);
+        reject(new Error(`Command timed out after ${commandTimeout}ms: ${actualCommand}`));
+      }, commandTimeout);
     });
 
     // Read streams with timeout (stdout/stderr are guaranteed with "pipe" option)

src/index.ts

@@ -3,28 +3,37 @@
  * Entry point for mdflow CLI
  *
  * This is a minimal entry point that:
- * 1. Sets up EPIPE handlers for graceful pipe handling
- * 2. Creates a CliRunner with the real system environment
- * 3. Runs the CLI and exits with the appropriate code
+ * 1. Initializes ProcessManager for centralized lifecycle management
+ * 2. Sets up EPIPE handlers for graceful pipe handling
+ * 3. Creates a CliRunner with the real system environment
+ * 4. Runs the CLI and exits with the appropriate code
  *
  * All orchestration logic is in CliRunner for testability.
  */
 
 import { CliRunner } from "./cli-runner";
 import { BunSystemEnvironment } from "./system-environment";
+import { getProcessManager } from "./process-manager";
 
 async function main() {
+  // Initialize ProcessManager early for centralized signal handling
+  // This ensures cursor restoration and process cleanup on SIGINT/SIGTERM
+  const pm = getProcessManager();
+  pm.initialize();
+
   // Handle EPIPE gracefully when downstream closes the pipe early
   // (e.g., `md task.md | head -n 5`)
   process.stdout.on("error", (err: NodeJS.ErrnoException) => {
     if (err.code === "EPIPE") {
+      pm.restoreTerminal(); // Ensure cursor is visible
       process.exit(0);
     }
     throw err;
   });
 
   process.stderr.on("error", (err: NodeJS.ErrnoException) => {
     if (err.code === "EPIPE") {
+      pm.restoreTerminal(); // Ensure cursor is visible
       process.exit(0);
     }
     throw err;