Agent mode phase 0: clean up background tasks when switching workspaces

killAllBackgroundCommands() was only ever called from app.on("window-all-closed")/"before-quit" — neither the session-load effect nor changeAgentWorkspace() in Chat.tsx cleaned up the *previous* workspace's tasks when switching to a different one, so they kept running indefinitely and kept counting against MAX_BACKGROUND_TASKS.

- New app/src/process-tree.ts: killProcessTree(pid), since spawn(cmd, {shell:true}).kill() only kills the shell, not whatever it spawned (e.g. npm run dev -> node). POSIX kills the process group (requires detached:true at spawn time, now set); Windows shells out to taskkill /t /f.
- BackgroundTask now carries its workspaceRoot. New killBackgroundCommandsForWorkspace(root) kills and forgets only that workspace's tasks, leaving others running.
- New agent:closeWorkspace IPC call, invoked from Chat.tsx via a small ref-tracking helper right before every place agentWorkspace changes (initial pick, folder change, session load) so the previously-active workspace's tasks get torn down on the actual transition, not just at quit.

This is prep work for a real sandbox/permission system and persistent terminals, both of which need the same workspace-scoped process lifecycle rather than duplicating it.

Author: voidstackloop

app/src/agent-tools.test.ts

@@ -31,6 +31,7 @@ import {
     stopBackgroundCommand,
     listBackgroundCommands,
     killAllBackgroundCommands,
+    killBackgroundCommandsForWorkspace,
     httpRequest,
     findSymbolReferences,
     applyPatch,
@@ -494,6 +495,25 @@ describe("agent-tools", () => {
             for (let i = 0; i < 5; i++) startBackgroundCommand(workspace, "sleep 5", ".", `task-${i}`);
             expect(() => startBackgroundCommand(workspace, "sleep 5")).toThrow(/Already running/);
         });
+
+        it("kills and forgets only the tasks belonging to the given workspace, leaving other workspaces' tasks running", () => {
+            const otherWorkspace = fs.mkdtempSync(path.join(os.tmpdir(), "agent-tools-test-other-"));
+            const { taskId: taskA } = startBackgroundCommand(workspace, "sleep 30");
+            const { taskId: taskB } = startBackgroundCommand(otherWorkspace, "sleep 30");
+
+            const killedCount = killBackgroundCommandsForWorkspace(workspace);
+
+            expect(killedCount).toBe(1);
+            // Killed AND removed from tracking — a task from a workspace you've
+            // switched away from shouldn't linger as a queryable id.
+            expect(() => getBackgroundOutput(taskA)).toThrow(/No background task/);
+            expect(getBackgroundOutput(taskB)).toContain("running");
+            fs.rmSync(otherWorkspace, { recursive: true, force: true });
+        });
+
+        it("returns 0 when the workspace has no background tasks", () => {
+            expect(killBackgroundCommandsForWorkspace(workspace)).toBe(0);
+        });
     });
 
     describe("git tools", () => {

app/src/agent-tools.ts

@@ -7,6 +7,7 @@ import { randomUUID } from "node:crypto";
 import type { ToolDefinition } from "./providers/types";
 import { getAccountToken } from "./accounts";
 import { capturePageScreenshot } from "./browser-capture";
+import { killProcessTree } from "./process-tree";
 
 const execAsync = promisify(exec);
 
@@ -835,6 +836,10 @@ interface BackgroundTask {
     name: string;
     command: string;
     process: ChildProcess;
+    // Absolute path — lets killBackgroundCommandsForWorkspace() target only
+    // the tasks that belong to a workspace being switched away from, rather
+    // than every background task the process has ever started.
+    workspaceRoot: string;
     // Rolling tail of combined stdout+stderr — capped so a chatty dev server
     // can't grow memory unboundedly over a long session.
     output: string;
@@ -861,13 +866,24 @@ export function startBackgroundCommand(
     }
 
     const cwd = resolveSafePath(workspaceRoot, relativeCwd);
-    const child = spawn(command, { cwd, shell: true, stdio: ["ignore", "pipe", "pipe"] });
+    // detached so the shell becomes its own process group leader — lets
+    // killProcessTree() below signal the whole group (shell + whatever it
+    // spawned, e.g. `npm run dev` spawning `node`) instead of just the shell
+    // itself, which is all a plain .kill() would reach. No effect on Windows,
+    // where killProcessTree uses `taskkill /t` instead.
+    const child = spawn(command, {
+        cwd,
+        shell: true,
+        stdio: ["ignore", "pipe", "pipe"],
+        detached: process.platform !== "win32",
+    });
     const id = randomUUID().slice(0, 8);
     const task: BackgroundTask = {
         id,
         name: name?.trim() || command.slice(0, 40),
         command,
         process: child,
+        workspaceRoot: path.resolve(workspaceRoot),
         output: "",
         exitCode: null,
         startedAt: Date.now(),
@@ -909,7 +925,7 @@ export function stopBackgroundCommand(taskId: string): string {
     const task = backgroundTasks.get(taskId);
     if (!task) throw new Error(`No background task with id "${taskId}".`);
     if (task.exitCode !== null) return `Task ${task.id} had already exited with code ${task.exitCode}.`;
-    task.process.kill();
+    if (task.process.pid) killProcessTree(task.process.pid);
     return `Task ${task.id} (${task.name}) stopped.`;
 }
 
@@ -924,11 +940,28 @@ export function listBackgroundCommands(): { id: string; name: string; command: s
 
 export function killAllBackgroundCommands(): void {
     for (const task of backgroundTasks.values()) {
-        if (task.exitCode === null) task.process.kill();
+        if (task.exitCode === null && task.process.pid) killProcessTree(task.process.pid);
     }
     backgroundTasks.clear();
 }
 
+// Only tears down tasks belonging to the workspace being switched away from
+// — background commands are otherwise never cleaned up until app quit
+// (killAllBackgroundCommands, called from window-all-closed/before-quit),
+// so switching to a different workspace mid-session used to leave the old
+// one's tasks running indefinitely, silently eating into MAX_BACKGROUND_TASKS.
+export function killBackgroundCommandsForWorkspace(workspaceRoot: string): number {
+    const root = path.resolve(workspaceRoot);
+    let killed = 0;
+    for (const [id, task] of backgroundTasks) {
+        if (task.workspaceRoot !== root) continue;
+        if (task.exitCode === null && task.process.pid) killProcessTree(task.process.pid);
+        backgroundTasks.delete(id);
+        killed++;
+    }
+    return killed;
+}
+
 function gitCommand(workspaceRoot: string, args: string): Promise<string> {
     return runCommand(workspaceRoot, `git ${args}`, ".");
 }

app/src/main.ts

@@ -754,6 +754,17 @@ function registerIpcHandlers(): void {
         return agentTools.detectProjectScripts(workspaceRoot);
     });
 
+    // Called when the renderer is about to stop using a workspace (switching
+    // to a different folder, or loading a session that points elsewhere) —
+    // without this, background tasks started against the old workspace kept
+    // running indefinitely, since killAllBackgroundCommands() only ever ran
+    // on app quit.
+    ipcMain.handle("agent:closeWorkspace", (_event: IpcMainInvokeEvent, workspaceRoot: string) => {
+        requireString(workspaceRoot, "workspace root");
+        const killedBackgroundTasks = agentTools.killBackgroundCommandsForWorkspace(workspaceRoot);
+        return { killedBackgroundTasks };
+    });
+
     ipcMain.handle("mcp:connect", async (_event: IpcMainInvokeEvent, config: McpServerConfig) => {
         try {
             const { tools } = await mcpClient.connectServer(config);

app/src/preload.ts

@@ -230,6 +230,8 @@ contextBridge.exposeInMainWorld("api", {
             ipcRenderer.invoke("agent:rollbackLastWrite", workspaceRoot),
         detectScripts: (workspaceRoot: string): Promise<ProjectScripts> =>
             ipcRenderer.invoke("agent:detectScripts", workspaceRoot),
+        closeWorkspace: (workspaceRoot: string): Promise<{ killedBackgroundTasks: number }> =>
+            ipcRenderer.invoke("agent:closeWorkspace", workspaceRoot),
     },
 
     mcp: {

app/src/process-tree.test.ts

@@ -0,0 +1,48 @@
+import { describe, it, expect, vi } from "vitest";
+import { spawn, spawnSync } from "node:child_process";
+import { killProcessTree } from "./process-tree";
+
+vi.mock("node:child_process", async (importOriginal) => {
+    const actual = await importOriginal<typeof import("node:child_process")>();
+    return { ...actual, spawnSync: vi.fn() };
+});
+
+function isAlive(pid: number): boolean {
+    try {
+        process.kill(pid, 0);
+        return true;
+    } catch {
+        return false;
+    }
+}
+
+describe("killProcessTree", () => {
+    // Real process-group kill only makes sense on POSIX — Windows has no
+    // equivalent to `detached: true` + negative-pid signaling, and Windows CI
+    // runners don't have `sh`/`sleep` available to build a tree with anyway.
+    it.skipIf(process.platform === "win32")(
+        "kills a detached shell and its child process, not just the shell",
+        async () => {
+            const child = spawn("sh", ["-c", "sleep 30 & wait"], { detached: true, stdio: "ignore" });
+            const shellPid = child.pid!;
+            // Give the shell a moment to fork `sleep` before we look for it.
+            await new Promise((r) => setTimeout(r, 200));
+
+            killProcessTree(shellPid);
+            await new Promise((r) => setTimeout(r, 200));
+
+            expect(isAlive(shellPid)).toBe(false);
+        },
+        10_000
+    );
+
+    it("shells out to taskkill /t /f on win32, regardless of the host platform", () => {
+        killProcessTree(4321, "SIGTERM", "win32");
+        expect(spawnSync).toHaveBeenCalledWith("taskkill", ["/pid", "4321", "/t", "/f"]);
+    });
+
+    it("silently no-ops when the target process is already gone", () => {
+        // A pid essentially guaranteed not to exist.
+        expect(() => killProcessTree(999_999, "SIGTERM", "linux")).not.toThrow();
+    });
+});

app/src/process-tree.ts

@@ -0,0 +1,31 @@
+import { spawnSync } from "node:child_process";
+
+// `spawn(command, {shell: true})` means the tracked pid is the *shell's*
+// pid — calling .kill() on it leaves any grandchildren (e.g. `npm run dev`
+// spawning a real `node` process) running behind. On POSIX this kills the
+// whole process group instead, which requires the child to have been spawned
+// with `detached: true` so it becomes its own group leader (see
+// startBackgroundCommand in agent-tools.ts). On Windows, `taskkill`'s `/t`
+// flag walks the process tree itself, so no special spawn option is needed
+// there.
+export function killProcessTree(
+    pid: number,
+    signal: NodeJS.Signals = "SIGTERM",
+    platform: NodeJS.Platform = process.platform
+): void {
+    if (platform === "win32") {
+        spawnSync("taskkill", ["/pid", String(pid), "/t", "/f"]);
+        return;
+    }
+    try {
+        process.kill(-pid, signal);
+    } catch {
+        // Not a group leader (wasn't spawned detached) or already gone —
+        // fall back to killing just the tracked pid.
+        try {
+            process.kill(pid, signal);
+        } catch {
+            // Already dead.
+        }
+    }
+}

frontend/src/pages/Chat.tsx

@@ -465,6 +465,16 @@ export default function Chat() {
     const bottomRef = useRef<HTMLDivElement>(null);
     const textareaRef = useRef<HTMLTextAreaElement>(null);
     const viewportRef = useRef<HTMLDivElement>(null);
+    // Tracks the workspace this component last told the main process about,
+    // so switching away from one (a different session, or picking a new
+    // folder) can close out its background tasks instead of leaving them
+    // running until app quit.
+    const prevWorkspaceRef = useRef<string | null>(null);
+    function closeWorkspaceIfChanged(next: string | null) {
+        const prev = prevWorkspaceRef.current;
+        if (prev && prev !== next) window.api.agent.closeWorkspace(prev);
+        prevWorkspaceRef.current = next;
+    }
 
     // No session selected yet: pick the most recent one, or create a new one.
     useEffect(() => {
@@ -532,6 +542,7 @@ export default function Chat() {
             setParams(session.params ?? {});
             setSessionSystemPrompt(session.systemPrompt ?? null);
             setAgentMode(session.agentMode ?? false);
+            closeWorkspaceIfChanged(session.agentWorkspace ?? null);
             setAgentWorkspace(session.agentWorkspace ?? null);
             setPendingToolCalls([]);
             setAgentStepCount(0);
@@ -624,6 +635,7 @@ export default function Chat() {
             // workspace folder up front rather than letting tool calls fail later.
             const folder = await window.api.agent.pickWorkspace();
             if (!folder) return;
+            closeWorkspaceIfChanged(folder);
             setAgentWorkspace(folder);
             setAgentMode(true);
             window.api.sessions.update(sessionId, { agentMode: true, agentWorkspace: folder });
@@ -638,6 +650,7 @@ export default function Chat() {
         if (!sessionId) return;
         const folder = await window.api.agent.pickWorkspace();
         if (!folder) return;
+        closeWorkspaceIfChanged(folder);
         setAgentWorkspace(folder);
         window.api.sessions.update(sessionId, { agentWorkspace: folder });
     }

frontend/src/types/electron.d.ts

@@ -511,6 +511,7 @@ export interface ElectronApi {
     ) => Promise<{ result?: unknown; error?: string }>;
     rollbackLastWrite: (workspaceRoot: string) => Promise<RollbackResult | null>;
     detectScripts: (workspaceRoot: string) => Promise<ProjectScripts>;
+    closeWorkspace: (workspaceRoot: string) => Promise<{ killedBackgroundTasks: number }>;
   };
   mcp: {
     connect: (