🤖 fix: prevent background process name collisions (#1070)

ethanndickson · web-flow · commit aaf26a81b0f9 · 2025-12-10T08:18:27.000Z
## Problem

Background processes are stored in a `Map&lt;processId, BackgroundProcess&gt;`
in `BackgroundProcessManager`. The `processId` was set directly from
`displayName`, and it's also used to compute the output directory:

```typescript
const processId = config.displayName;
// ...
const outputDir = `${bgOutputDir}/${workspaceId}/${processId}`;
```

When a new process is spawned in the background with a display name that
was previously used:

1. It gets the **same `outputDir`** as the old process
2. The old `exit_code` file still exists in that directory (written by
shell trap on exit)
3. When `refreshRunningStatuses()` checks the new process, it reads the
**stale `exit_code` file**
4. The new process is immediately marked as `"exited"` even though it
just started
5. The banner filters to `status === "running"` → **process doesn't
appear**

Additionally, the map entry itself gets overwritten, losing tracking of
any previous process with that name.

## Fix

Append incrementing suffix `(1)`, `(2)`, etc. when a collision is
detected:

```typescript
let processId = config.displayName;
let suffix = 1;
while (this.processes.has(processId)) {
  processId = `${config.displayName} (${suffix})`;
  suffix++;
}
```

This ensures each process gets a unique `outputDir`, so no stale
`exit_code` files interfere.

The original `displayName` is preserved separately on the
`BackgroundProcess` object for UI display - the banner shows clean names
like "Dev Server" while the agent receives unique IDs like "Dev Server
(1)" to reference specific processes.

_Generated with `mux`_
diff --git a/src/node/services/backgroundProcessManager.ts b/src/node/services/backgroundProcessManager.ts
@@ -170,8 +170,13 @@ export class BackgroundProcessManager extends EventEmitter<BackgroundProcessMana
   > {
     log.debug(`BackgroundProcessManager.spawn() called for workspace ${workspaceId}`);
 
-    // Process ID is the display name directly
-    const processId = config.displayName;
+    // Generate unique processId, appending (1), (2), etc. on collision
+    let processId = config.displayName;
+    let suffix = 1;
+    while (this.processes.has(processId)) {
+      processId = `${config.displayName} (${suffix})`;
+      suffix++;
+    }
 
     // Spawn via executor with background infrastructure
     // spawnProcess uses runtime.tempDir() internally for output directory
