🤖 feat: add background bash process execution with SSH support

Adds run_in_background=true option to bash tool for long-running processes
(dev servers, builds, file watchers). Returns process ID and output file
paths for agents to monitor via tail/grep/cat.

Key features:
- Works on both local and SSH runtimes (unified setsid+nohup pattern)
- Output written to files: /tmp/mux-bashes/{workspaceId}/{processId}/
- Exit code captured via bash trap to exit_code file
- Process group termination (SIGTERM → wait → SIGKILL)
- meta.json tracks process metadata

Tools:
- bash(run_in_background=true) - spawns process, returns stdout_path/stderr_path
- bash_background_list - lists processes with file paths
- bash_background_terminate - kills process group

Removed bash_background_read (agents read files directly with bash).

_Generated with mux_

Author: ethanndickson

bun.lock

@@ -1,5 +1,6 @@
 {
   "lockfileVersion": 1,
+  "configVersion": 0,
   "workspaces": {
     "": {
       "name": "mux",

src/browser/components/RightSidebar/CodeReview/ReviewPanel.tsx

@@ -290,7 +290,8 @@ export const ReviewPanel: React.FC<ReviewPanelProps> = ({
         }
 
         const diffOutput = diffResult.data.output ?? "";
-        const truncationInfo = diffResult.data.truncated;
+        const truncationInfo =
+          "truncated" in diffResult.data ? diffResult.data.truncated : undefined;
 
         const fileDiffs = parseDiff(diffOutput);
         const allHunks = extractAllHunks(fileDiffs);

src/cli/run.ts

@@ -17,6 +17,7 @@ import { PartialService } from "@/node/services/partialService";
 import { InitStateManager } from "@/node/services/initStateManager";
 import { AIService } from "@/node/services/aiService";
 import { AgentSession, type AgentSessionChatEvent } from "@/node/services/agentSession";
+import { BackgroundProcessManager } from "@/node/services/backgroundProcessManager";
 import {
   isCaughtUpMessage,
   isStreamAbort,
@@ -267,7 +268,8 @@ async function main(): Promise<void> {
   const historyService = new HistoryService(config);
   const partialService = new PartialService(config, historyService);
   const initStateManager = new InitStateManager(config);
-  const aiService = new AIService(config, historyService, partialService, initStateManager);
+  const backgroundProcessManager = new BackgroundProcessManager();
+  const aiService = new AIService(config, historyService, partialService, initStateManager, backgroundProcessManager);
   ensureProvidersConfig(config);
 
   const session = new AgentSession({
@@ -277,6 +279,7 @@ async function main(): Promise<void> {
     partialService,
     aiService,
     initStateManager,
+    backgroundProcessManager,
   });
 
   await session.ensureMetadata({

src/common/orpc/schemas/runtime.ts

@@ -12,24 +12,33 @@ export const RuntimeModeSchema = z.enum(["local", "worktree", "ssh"]);
  *
  * This allows two-way compatibility: users can upgrade/downgrade without breaking workspaces.
  */
+// Common field for background process output directory
+const bgOutputDirField = z
+  .string()
+  .optional()
+  .meta({ description: "Directory for background process output (e.g., /tmp/mux-bashes)" });
+
 export const RuntimeConfigSchema = z.union([
   // Legacy local with srcBaseDir (treated as worktree)
   z.object({
     type: z.literal("local"),
     srcBaseDir: z.string().meta({
       description: "Base directory where all workspaces are stored (legacy worktree config)",
     }),
+    bgOutputDir: bgOutputDirField,
   }),
   // New project-dir local (no srcBaseDir)
   z.object({
     type: z.literal("local"),
+    bgOutputDir: bgOutputDirField,
   }),
   // Explicit worktree runtime
   z.object({
     type: z.literal("worktree"),
     srcBaseDir: z
       .string()
       .meta({ description: "Base directory where all workspaces are stored (e.g., ~/.mux/src)" }),
+    bgOutputDir: bgOutputDirField,
   }),
   // SSH runtime
   z.object({
@@ -40,6 +49,7 @@ export const RuntimeConfigSchema = z.union([
     srcBaseDir: z
       .string()
       .meta({ description: "Base directory on remote host where all workspaces are stored" }),
+    bgOutputDir: bgOutputDirField,
     identityFile: z
       .string()
       .optional()

src/common/types/tools.ts

@@ -7,6 +7,7 @@
 export interface BashToolArgs {
   script: string;
   timeout_secs?: number; // Optional: defaults to 3 seconds for interactivity
+  run_in_background?: boolean; // Run without blocking (for long-running processes)
 }
 
 interface CommonBashFields {
@@ -26,6 +27,14 @@ export type BashToolResult =
         totalLines: number;
       };
     })
+  | (CommonBashFields & {
+      success: true;
+      output: string;
+      exitCode: 0;
+      backgroundProcessId: string; // Background spawn succeeded
+      stdout_path: string; // Path to stdout log file
+      stderr_path: string; // Path to stderr log file
+    })
   | (CommonBashFields & {
       success: false;
       output?: string;
@@ -190,6 +199,32 @@ export interface StatusSetToolArgs {
   url?: string;
 }
 
+// Bash Background Tool Types
+export interface BashBackgroundTerminateArgs {
+  process_id: string;
+}
+
+export type BashBackgroundTerminateResult =
+  | { success: true; message: string }
+  | { success: false; error: string };
+
+// Bash Background List Tool Types
+export type BashBackgroundListArgs = Record<string, never>;
+
+export interface BashBackgroundListProcess {
+  process_id: string;
+  status: "running" | "exited" | "killed" | "failed";
+  script: string;
+  uptime_ms: number;
+  exitCode?: number;
+  stdout_path: string; // Path to stdout log file
+  stderr_path: string; // Path to stderr log file
+}
+
+export type BashBackgroundListResult =
+  | { success: true; processes: BashBackgroundListProcess[] }
+  | { success: false; error: string };
+
 export type StatusSetToolResult =
   | {
       success: true;

src/common/utils/tools/toolDefinitions.ts

@@ -52,6 +52,18 @@ export const TOOL_DEFINITIONS = {
         .describe(
           `Timeout (seconds, default: ${BASH_DEFAULT_TIMEOUT_SECS}). Start small and increase on retry; avoid large initial values to keep UX responsive`
         ),
+      run_in_background: z
+        .boolean()
+        .default(false)
+        .describe(
+          "Run this command in the background without blocking. " +
+            "Use for processes running >5s (dev servers, builds, file watchers). " +
+            "Do NOT use for quick commands (<5s), interactive processes (no stdin support), " +
+            "or processes requiring real-time output (use foreground with larger timeout instead). " +
+            "Returns immediately with process ID and output file paths (stdout_path, stderr_path). " +
+            "Read output via bash (e.g. tail, grep, cat). " +
+            "Process persists across tool calls until terminated or workspace is removed."
+        ),
     }),
   },
   file_read: {
@@ -229,6 +241,24 @@ export const TOOL_DEFINITIONS = {
       })
       .strict(),
   },
+  bash_background_list: {
+    description:
+      "List all background processes for the current workspace. " +
+      "Useful for discovering running processes after context loss or resuming a conversation.",
+    schema: z.object({}),
+  },
+  bash_background_terminate: {
+    description:
+      "Terminate a background bash process. " +
+      "Sends SIGTERM, waits briefly, then sends SIGKILL if needed. " +
+      "Process output remains available for inspection after termination.",
+    schema: z.object({
+      process_id: z
+        .string()
+        .regex(/^bg-[0-9a-f]{8}$/, "Invalid process ID format")
+        .describe("Background process ID to terminate"),
+    }),
+  },
   web_fetch: {
     description:
       `Fetch a web page and extract its main content as clean markdown. ` +
@@ -272,6 +302,8 @@ export function getAvailableTools(modelString: string): string[] {
   // Base tools available for all models
   const baseTools = [
     "bash",
+    "bash_background_list",
+    "bash_background_terminate",
     "file_read",
     "file_edit_replace_string",
     // "file_edit_replace_lines", // DISABLED: causes models to break repo state

src/common/utils/tools/tools.ts

@@ -1,6 +1,8 @@
 import { type Tool } from "ai";
 import { createFileReadTool } from "@/node/services/tools/file_read";
 import { createBashTool } from "@/node/services/tools/bash";
+import { createBashBackgroundListTool } from "@/node/services/tools/bash_background_list";
+import { createBashBackgroundTerminateTool } from "@/node/services/tools/bash_background_terminate";
 import { createFileEditReplaceStringTool } from "@/node/services/tools/file_edit_replace_string";
 // DISABLED: import { createFileEditReplaceLinesTool } from "@/node/services/tools/file_edit_replace_lines";
 import { createFileEditInsertTool } from "@/node/services/tools/file_edit_insert";
@@ -12,6 +14,7 @@ import { log } from "@/node/services/log";
 
 import type { Runtime } from "@/node/runtime/Runtime";
 import type { InitStateManager } from "@/node/services/initStateManager";
+import type { BackgroundProcessManager } from "@/node/services/backgroundProcessManager";
 
 /**
  * Configuration for tools that need runtime context
@@ -29,6 +32,10 @@ export interface ToolConfiguration {
   runtimeTempDir: string;
   /** Overflow policy for bash tool output (optional, not exposed to AI) */
   overflow_policy?: "truncate" | "tmpfile";
+  /** Background process manager for bash tool (optional, AI-only) */
+  backgroundProcessManager?: BackgroundProcessManager;
+  /** Workspace ID for tracking background processes (optional for token estimation) */
+  workspaceId?: string;
 }
 
 /**
@@ -99,6 +106,8 @@ export async function getToolsForModel(
     // and line number miscalculations. Use file_edit_replace_string instead.
     // file_edit_replace_lines: wrap(createFileEditReplaceLinesTool(config)),
     bash: wrap(createBashTool(config)),
+    bash_background_list: wrap(createBashBackgroundListTool(config)),
+    bash_background_terminate: wrap(createBashBackgroundTerminateTool(config)),
     web_fetch: wrap(createWebFetchTool(config)),
   };
 

src/desktop/main.ts

@@ -564,6 +564,29 @@ if (gotTheLock) {
     }
   });
 
+  // Track if we're in the middle of disposing to prevent re-entry
+  let isDisposing = false;
+
+  app.on("before-quit", (event) => {
+    // Skip if already disposing or no services to clean up
+    if (isDisposing || !services) {
+      return;
+    }
+
+    // Prevent quit, clean up, then quit again
+    event.preventDefault();
+    isDisposing = true;
+
+    services
+      .dispose()
+      .catch((err) => {
+        console.error("Error during ServiceContainer dispose:", err);
+      })
+      .finally(() => {
+        app.quit();
+      });
+  });
+
   app.on("window-all-closed", () => {
     if (process.platform !== "darwin") {
       app.quit();