How the Freebuff Broker Manages the Process Tree: A Deep Dive into Isolated Command Execution

The Freebuff terminal command broker manages the process tree by spawning commands in detached helper processes, reaping entire process groups on parent disconnect, and providing cross-platform termination utilities.

The Freebuff CLI relies on a specialized terminal command broker to execute external commands without blocking the UI. This broker, implemented in cli/src/utils/terminal-command-broker.ts, ensures that every spawned command runs in its own isolated process subtree—complete with automatic cleanup when the parent exits or crashes. Understanding how Freebuff manages this process tree is essential for anyone building resilient CLI tools or debugging command execution issues.

Spawning Detached Helper Processes

The broker creates isolated execution environments through careful process configuration.

Process Creation with createTerminalCommandBroker

When terminalCommandBroker.start() is called, the broker spawns a new Node.js process with specific flags that enable proper process tree management:

// From terminal-command-broker.ts lines 82-97
const child = spawn(executable, args, {
  detached: true,
  stdio: ['pipe', 'pipe', 'pipe'],
  windowsHide: true
});

The detached: true option is critical—it causes the child to run in its own process group, making it the group leader. On POSIX systems, this allows signals to be broadcast to the entire group using negative PIDs.

Protocol File Communication

The child process receives its actual command request via stdin and writes results to a one-shot JSON protocol file:

// createProtocolPath() at lines 41-45
const protocolPath = join(tmpdir(), `freebuff-protocol-${randomUUID()}.json`);

This file-based protocol eliminates the need for persistent socket connections between parent and child, simplifying recovery scenarios when the parent crashes.

The TerminalCommandProcess Interface

The start() method returns an object exposing:

• pid – The child process ID for direct monitoring
• kill(signal?) – Terminates the entire process group
• isAlive() – Checks whether the process group is still running
• completion – A promise resolving to the exit code

Reaping Process Groups on Parent Disconnect

A key reliability feature ensures no orphaned processes survive a CLI crash.

Detecting Parent Disappearance

The broker runs waitForParentDisconnect() on startup, polling every 100ms:

// Lines 71-96: Parent liveness polling
async function waitForParentDisconnect(parentPid: number): Promise<void> {
  while (true) {
    try {
      process.kill(parentPid, 0); // Check if parent exists
      await delay(100);
    } catch {
      // Parent is gone—trigger cleanup
      await reapOwnProcessGroup();
      break;
    }
  }
}

The process.kill(parentPid, 0) pattern checks process existence without sending an actual signal.

Cross-Platform Process Group Termination

When reaping is required, the broker uses platform-specific approaches:

Windows (reapOwnProcessGroup, lines 100-107):

const taskkill = spawn('taskkill.exe', ['/pid', process.pid.toString(), '/t', '/f'], {
  windowsHide: true
});

The /t flag targets the entire process tree; /f forces termination.

POSIX (lines 110-115):

process.kill(-process.pid, 'SIGKILL');

The negative PID (-process.pid) sends SIGKILL to every process in the group.

Graceful Termination and Liveness Verification

Freebuff provides utilities for explicit cleanup and health checks.

terminateProcessGroup: User-Initiated Cleanup

This helper (lines 104-124) mirrors the reap logic but allows signal selection:

export function terminateProcessGroup(
  child: ChildProcess,
  signal: NodeJS.Signals = 'SIGTERM'
): void {
  if (process.platform === 'win32') {
    // Windows: taskkill with /t for tree termination
    spawn('taskkill.exe', ['/pid', child.pid!.toString(), '/t', '/f'], ...);
  } else {
    // POSIX: try group kill first, fall back to single process
    try {
      process.kill(-child.pid!, signal);
    } catch {
      child.kill(signal);
    }
  }
}

The fallback to child.kill(signal) handles edge cases where the process group may have already dissolved.

isProcessGroupAlive: Runtime Health Checks

Liveness detection varies by platform (lines 126-136):

export function isProcessGroupAlive(child: ChildProcess): boolean {
  if (process.platform === 'win32') {
    return child.exitCode === null && child.signalCode === null;
  }
  try {
    process.kill(-child.pid!, 0); // Signal 0 checks existence only
    return true;
  } catch {
    return false;
  }
}

On Windows, the implementation checks exitCode and signalCode properties since process.kill() with signal 0 behaves differently.

Complete Usage Examples

Launching and Monitoring a Command

import { terminalCommandBroker } from './utils/terminal-command-broker';

const proc = terminalCommandBroker.start({
  executable: 'npm',
  args: ['install', '--legacy-peer-deps'],
  cwd: '/my/project',
  env: { ...process.env, NODE_ENV: 'production' }
});

// Real-time output streaming
proc.stdout?.pipe(process.stdout);
proc.stderr?.pipe(process.stderr);

// Completion handling
proc.completion
  .then(code => console.log(`npm exited with code ${code}`))
  .catch(err => console.error('Broker failure:', err));

Implementing Timeout-Based Cancellation

const proc = terminalCommandBroker.start({
  executable: 'long-running-script.sh',
  args: []
});

// 30-second timeout
const timeout = setTimeout(() => {
  if (proc.isAlive()) {
    console.warn('Timeout reached—terminating process tree');
    proc.kill('SIGTERM');
    
    // Escalate to SIGKILL after grace period
    setTimeout(() => {
      if (proc.isAlive()) proc.kill('SIGKILL');
    }, 5000);
  }
}, 30000);

proc.completion.finally(() => clearTimeout(timeout));

Key Environment Variables and Flags

Variable / Flag	Purpose	Location
TERMINAL_COMMAND_BROKER_FLAG = '--terminal-command-broker'	Identifies broker invocation mode	terminal-command-broker.ts:17
CODEBUFF_TERMINAL_COMMAND_BROKER	Signals broker environment presence	terminal-command-broker.ts:18
CODEBUFF_TERMINAL_COMMAND_BROKER_PROTOCOL	Path to JSON protocol file	terminal-command-broker.ts:20

These environment markers enable the broker to detect when it's running in helper mode versus normal CLI mode.

Summary

• Detached spawning with detached: true creates isolated process groups that can be targeted as units
• Parent disconnect detection via PID polling every 100ms triggers automatic cleanup of orphaned processes
• Cross-platform termination uses taskkill.exe /t /f on Windows and negative-PID SIGKILL on POSIX
• Graceful degradation falls back from group signals to single-process termination when needed
• Protocol file communication eliminates socket dependencies, improving crash resilience

Frequently Asked Questions

What happens if the Freebuff CLI crashes while a command is running?

The broker's waitForParentDisconnect detects the parent's disappearance through failed process.kill(parentPid, 0) calls. It then automatically invokes reapOwnProcessGroup(), terminating the entire subprocess tree via taskkill.exe on Windows or process.kill(-process.pid, 'SIGKILL') on POSIX systems.

Why does Freebuff use a temporary file for command protocol instead of stdin/stdout?

While initial parameters pass through stdin, results write to a JSON protocol file created by createProtocolPath(). This design ensures the broker can complete and persist output even if the parent disconnects unexpectedly—the file remains readable for potential recovery scenarios.

How can I verify whether a spawned process tree is still active?

Call proc.isAlive() or use the underlying isProcessGroupAlive(child) utility. On POSIX, this attempts process.kill(-child.pid, 0); on Windows, it checks that both child.exitCode and child.signalCode are null.

What's the difference between terminateProcessGroup and reapOwnProcessGroup?

terminateProcessGroup(child, signal) is the external API for parent-initiated cleanup, accepting an optional signal parameter. reapOwnProcessGroup() is the internal self-termination routine called when the broker detects parent disappearance, hardcoded to use SIGKILL/taskkill /f for guaranteed cleanup.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}