fix(simulator): Reap orphaned OSLog helpers by workspace

Persist workspace identity with simulator OSLog helper ownership and reconcile
same-workspace helpers whose owner PID is no longer alive. This lets a new
server startup clean up detached log stream helpers left behind by abnormal
termination without killing helpers from other active workspaces or sessions.

Remove the dead legacy simulator log capture path and its lifecycle/status
plumbing so cleanup behavior is owned by the durable OSLog registry path.

Fixes #382
Co-Authored-By: Codex <noreply@openai.com>

Author: cameroncooke

CHANGELOG.md

@@ -1,5 +1,11 @@
 # Changelog
 
+## [Unreleased]
+
+### Fixed
+
+- Fixed simulator OSLog helper cleanup so server and daemon startup reconcile same-workspace orphaned log streams without stopping helpers owned by live sessions in other workspaces ([#382](https://github.com/getsentry/XcodeBuildMCP/issues/382)).
+
 ## [2.5.0-beta.1]
 
 ### Breaking

docs/investigations/orphaned-simctl-log-stream-2026-05-01.md

@@ -0,0 +1,100 @@
+# Investigation: Orphaned simctl OSLog processes when MCP server exits abnormally
+
+**Issue:** [#382](https://github.com/getsentry/XcodeBuildMCP/issues/382)
+**Date:** 2026-05-01
+**Status:** Confirmed and fixed for simulator OSLog helpers.
+
+## Summary
+
+The issue described orphaned simulator helper processes after abnormal server exits. The final fix is deliberately narrow:
+
+- `simctl spawn … log stream …` OSLog helpers are registry-backed and now reconciled safely across MCP/daemon restarts.
+- `simctl launch --console-pty …` remains intentionally unregistered. It is tied to the launched app lifecycle, and adding a durable registry for it would overreach the accepted design.
+- The old `src/utils/log_capture.ts` path was dead production code and has been removed.
+
+The fix does not change public tool schemas.
+
+## Final design
+
+### OSLog helpers are workspace-scoped
+
+Durable OSLog registry records now store owner identity as:
+
+```ts
+owner: {
+  instanceId: string;
+  pid: number;
+  workspaceKey: string;
+}
+```
+
+The `workspaceKey` is configured during MCP, CLI, and daemon startup from the same workspace-root hashing used by daemon socket paths. Existing internal records without `owner.workspaceKey` are treated as invalid and pruned. No registry versioning or migration was added.
+
+### Reconciliation only reaps safe orphans
+
+Startup reconciliation runs for both MCP server startup and daemon startup. It scans durable OSLog records and only stops a helper when all of these are true:
+
+1. The record belongs to the current workspace.
+2. The owner PID is not the current process.
+3. The owner PID is no longer alive.
+4. The helper process still matches the expected `simctl spawn … log stream …` command.
+
+Records from other workspaces are skipped. Records owned by live processes are skipped, including live foreign MCP/daemon sessions in the same workspace.
+
+### App-scoped cleanup is no longer global
+
+`stop_app_sim` and relaunch cleanup still clean OSLog helpers for the target simulator/bundle, but only when the record is:
+
+- owned by the current runtime instance, or
+- in the same workspace with a dead owner PID.
+
+This prevents one active session from killing another active session’s OSLog helper.
+
+### Last-chance cleanup covers local live helpers
+
+MCP lifecycle and daemon lifecycle now install synchronous `exit` cleanup for in-process OSLog sessions. This only signals locally known child processes; it does not perform async registry deletion. If a helper survives, the next startup reconciliation can reap it from the durable registry.
+
+Daemon crash handling was also brought closer to MCP parity with `uncaughtException` and `unhandledRejection` handling that requests shutdown with a non-zero exit code.
+
+### Dead log-capture path removed
+
+`src/utils/log_capture.ts` duplicated old simulator log-capture behavior, but there were no production callers. It also left misleading lifecycle/status fields such as `activeLogSessions` and `simulatorLogSessionCount`.
+
+Removed:
+
+- `src/utils/log_capture.ts`
+- `src/utils/__tests__/log_capture.test.ts`
+- `src/utils/__tests__/log_capture_escape.test.ts`
+- legacy re-exports from `src/utils/log-capture/index.ts`
+- legacy shutdown/status references to `stopAllLogCaptures`, `activeLogSessions`, and `simulatorLogSessionCount`
+
+## Why console-PTY is not registered
+
+`simctl launch --console-pty --terminate-running-process …` is app-lifecycle-bound. It exists to capture the launched app’s stdout/stderr while the app is running. The accepted fix avoids adding a console-PTY registry because that would create a second durable lifecycle model for a helper whose lifetime is already coupled to the app launch.
+
+The strategic cleanup surface is the OSLog helper registry, because OSLog helpers are detached, long-lived, and already have durable records that can be reconciled after abnormal exits.
+
+## Verification expectations
+
+Automated coverage should verify:
+
+- OSLog registry records require `owner.workspaceKey`.
+- records without `owner.workspaceKey` are pruned.
+- same-workspace dead-owner OSLog helpers are reconciled.
+- other-workspace records are skipped.
+- same-workspace live-owner records are skipped.
+- app-scoped cleanup skips live foreign owners.
+- lifecycle snapshots and session status do not expose deleted legacy log-capture fields.
+- synchronous exit cleanup signals only live local OSLog helpers.
+
+Manual smoke testing should verify:
+
+1. Clean shutdown stops helpers owned by the current server.
+2. After `SIGKILL` of an MCP server, restarting in the same workspace reaps the orphaned `simctl spawn … log stream …` helper.
+3. Two live sessions in the same workspace do not kill each other’s OSLog helpers.
+4. Startup from workspace A does not kill workspace B helpers.
+5. `stop_app_sim` does not kill live foreign-owner OSLog helpers.
+
+## Known boundary
+
+This fix does not promise to kill every possible `simctl launch --console-pty` process. That helper is intentionally not part of the durable OSLog registry. The implemented production safety guarantee is: workspace-scoped OSLog helpers are cleaned up without killing helpers owned by other live sessions.

src/cli.ts

@@ -8,6 +8,7 @@ import { listCliWorkflowIdsFromManifest } from './runtime/tool-catalog.ts';
 import { flushAndCloseSentry, initSentry, recordBootstrapDurationMetric } from './utils/sentry.ts';
 import { coerceLogLevel, setLogLevel, type LogLevel } from './utils/logger.ts';
 import { hydrateSentryDisabledEnvFromProjectConfig } from './utils/sentry-config.ts';
+import { configureRuntimeWorkspaceKey } from './utils/runtime-instance.ts';
 
 function findTopLevelCommand(argv: string[]): string | undefined {
   const flagsWithValue = new Set(['--socket', '--log-level', '--style']);
@@ -133,6 +134,7 @@ async function main(): Promise<void> {
     cwd: result.runtime.cwd,
     projectConfigPath: result.configPath,
   });
+  configureRuntimeWorkspaceKey(workspaceKey);
 
   const cliExposedWorkflowIds = await listCliWorkflowIdsFromManifest({
     excludeWorkflows: ['session-management', 'workflow-discovery'],

src/daemon.ts

@@ -42,6 +42,11 @@ import {
 } from './utils/sentry.ts';
 import { isXcodemakeBinaryAvailable, isXcodemakeEnabled } from './utils/xcodemake/index.ts';
 import { hydrateSentryDisabledEnvFromProjectConfig } from './utils/sentry-config.ts';
+import { configureRuntimeWorkspaceKey } from './utils/runtime-instance.ts';
+import {
+  reconcileSimulatorLaunchOsLogOrphansForWorkspace,
+  terminateLiveSimulatorLaunchOsLogSessionsSync,
+} from './utils/log-capture/index.ts';
 
 async function checkExistingDaemon(socketPath: string): Promise<boolean> {
   return new Promise<boolean>((resolve) => {
@@ -128,6 +133,7 @@ async function main(): Promise<void> {
     cwd: result.runtime.cwd,
     projectConfigPath: result.configPath,
   });
+  configureRuntimeWorkspaceKey(workspaceKey);
 
   const logPath = resolveDaemonLogPath(workspaceKey);
   if (logPath) {
@@ -153,6 +159,20 @@ async function main(): Promise<void> {
 
   log('info', `[Daemon] Workspace: ${workspaceRoot}`);
   log('info', `[Daemon] Socket: ${socketPath}`);
+  try {
+    const reconciliation = await reconcileSimulatorLaunchOsLogOrphansForWorkspace(workspaceKey);
+    if (reconciliation.stoppedSessionCount > 0 || reconciliation.errorCount > 0) {
+      log(
+        reconciliation.errorCount > 0 ? 'warn' : 'info',
+        `[Daemon] Simulator OSLog reconciliation: ${JSON.stringify(reconciliation)}`,
+      );
+    }
+  } catch (error) {
+    log(
+      'warn',
+      `[Daemon] Simulator OSLog reconciliation failed: ${error instanceof Error ? error.message : String(error)}`,
+    );
+  }
   if (logPath) {
     log('info', `[Daemon] Logs: ${logPath}`);
   }
@@ -268,7 +288,7 @@ async function main(): Promise<void> {
   };
 
   // Unified shutdown handler
-  const shutdown = (): void => {
+  const shutdown = (exitCode = 0): void => {
     if (isShuttingDown) {
       return;
     }
@@ -292,7 +312,7 @@ async function main(): Promise<void> {
 
       log('info', '[Daemon] Cleanup complete');
       void flushAndCloseSentry(2000).finally(() => {
-        process.exit(0);
+        process.exit(exitCode);
       });
     });
 
@@ -393,8 +413,20 @@ async function main(): Promise<void> {
     });
   });
 
-  process.on('SIGTERM', shutdown);
-  process.on('SIGINT', shutdown);
+  const handleCrash = (reason: unknown): void => {
+    recordDaemonLifecycleMetric('crash');
+    const message = reason instanceof Error ? reason.message : String(reason);
+    log('error', `[Daemon] Crash: ${message}`, { sentry: true });
+    shutdown(1);
+  };
+
+  process.on('exit', () => {
+    terminateLiveSimulatorLaunchOsLogSessionsSync();
+  });
+  process.on('SIGTERM', () => shutdown(0));
+  process.on('SIGINT', () => shutdown(0));
+  process.on('uncaughtException', handleCrash);
+  process.on('unhandledRejection', handleCrash);
 }
 
 main().catch(async (err) => {

src/mcp/resources/__tests__/session-status.test.ts

@@ -7,7 +7,6 @@ import type { ChildProcess } from 'node:child_process';
 import { describe, it, expect, beforeEach, afterEach } from 'vitest';
 import { clearDaemonActivityRegistry } from '../../../daemon/activity-registry.ts';
 import { getDefaultDebuggerManager } from '../../../utils/debugger/index.ts';
-import { activeLogSessions } from '../../../utils/log_capture.ts';
 import { activeDeviceLogSessions } from '../../../utils/log-capture/device-log-sessions.ts';
 import {
   clearAllSimulatorLaunchOsLogSessionsForTests,
@@ -34,9 +33,12 @@ describe('session-status resource', () => {
   beforeEach(async () => {
     registryDir = mkdtempSync(path.join(tmpdir(), 'xcodebuildmcp-session-status-'));
     setSimulatorLaunchOsLogRegistryDirOverrideForTests(registryDir);
-    setRuntimeInstanceForTests({ instanceId: 'session-status-test', pid: process.pid });
+    setRuntimeInstanceForTests({
+      instanceId: 'session-status-test',
+      pid: process.pid,
+      workspaceKey: 'workspace-a',
+    });
     setSimulatorLaunchOsLogRecordActiveOverrideForTests(async () => true);
-    activeLogSessions.clear();
     activeDeviceLogSessions.clear();
     clearAllProcesses();
     await clearAllSimulatorLaunchOsLogSessionsForTests();
@@ -45,7 +47,6 @@ describe('session-status resource', () => {
   });
 
   afterEach(async () => {
-    activeLogSessions.clear();
     activeDeviceLogSessions.clear();
     clearAllProcesses();
     await clearAllSimulatorLaunchOsLogSessionsForTests();
@@ -64,7 +65,6 @@ describe('session-status resource', () => {
       expect(result.contents).toHaveLength(1);
       const parsed = JSON.parse(result.contents[0].text);
 
-      expect(parsed.logging.simulator.activeSessionIds).toEqual([]);
       expect(parsed.logging.simulator.activeLaunchOsLogSessions).toEqual([]);
       expect(parsed.logging.device.activeSessionIds).toEqual([]);
       expect(parsed.debug.currentSessionId).toBe(null);

src/mcp/tools/simulator/__tests__/stop_app_sim.test.ts

@@ -67,7 +67,11 @@ describe('stop_app_sim tool', () => {
     trackedChildren.clear();
     registryDir = mkdtempSync(path.join(tmpdir(), 'xcodebuildmcp-stop-app-sim-'));
     setSimulatorLaunchOsLogRegistryDirOverrideForTests(registryDir);
-    setRuntimeInstanceForTests({ instanceId: 'stop-app-sim-test', pid: process.pid });
+    setRuntimeInstanceForTests({
+      instanceId: 'stop-app-sim-test',
+      pid: process.pid,
+      workspaceKey: 'workspace-a',
+    });
     setSimulatorLaunchOsLogRecordActiveOverrideForTests(async (record) => {
       const child = trackedChildren.get(record.helperPid);
       return child ? child.exitCode == null : true;

src/server/__tests__/mcp-lifecycle.test.ts

@@ -61,7 +61,11 @@ describe('mcp lifecycle coordinator', () => {
   beforeEach(async () => {
     registryDir = mkdtempSync(path.join(tmpdir(), 'xcodebuildmcp-mcp-lifecycle-'));
     setSimulatorLaunchOsLogRegistryDirOverrideForTests(registryDir);
-    setRuntimeInstanceForTests({ instanceId: 'mcp-lifecycle-test', pid: process.pid });
+    setRuntimeInstanceForTests({
+      instanceId: 'mcp-lifecycle-test',
+      pid: process.pid,
+      workspaceKey: 'workspace-a',
+    });
     setSimulatorLaunchOsLogRecordActiveOverrideForTests(async () => true);
     await clearAllSimulatorLaunchOsLogSessionsForTests();
     vi.restoreAllMocks();
@@ -130,6 +134,29 @@ describe('mcp lifecycle coordinator', () => {
     expect(onShutdown.mock.calls[0]?.[0]?.reason).toBe('unhandled-rejection');
   });
 
+  it('terminates live local OSLog sessions on process exit', async () => {
+    const processRef = new TestProcess();
+    const onShutdown = vi.fn().mockResolvedValue(undefined);
+    const child = createTrackedChild(555);
+    await registerSimulatorLaunchOsLogSession({
+      process: child,
+      simulatorUuid: 'sim-1',
+      bundleId: 'io.sentry.app',
+      logFilePath: '/tmp/app.log',
+    });
+    const coordinator = createMcpLifecycleCoordinator({
+      commandExecutor: createMockExecutor({ output: '' }),
+      processRef,
+      onShutdown,
+    });
+
+    coordinator.attachProcessHandlers();
+    processRef.emit('exit');
+
+    expect(child.kill).toHaveBeenCalledWith('SIGTERM');
+    expect(onShutdown).not.toHaveBeenCalled();
+  });
+
   it('maps broken stdout pipes to shutdowns', async () => {
     const suppressSpy = vi
       .spyOn(shutdownState, 'suppressProcessStdioWrites')
@@ -179,7 +206,11 @@ describe('mcp lifecycle snapshot', () => {
   beforeEach(async () => {
     registryDir = mkdtempSync(path.join(tmpdir(), 'xcodebuildmcp-mcp-lifecycle-'));
     setSimulatorLaunchOsLogRegistryDirOverrideForTests(registryDir);
-    setRuntimeInstanceForTests({ instanceId: 'mcp-lifecycle-test', pid: process.pid });
+    setRuntimeInstanceForTests({
+      instanceId: 'mcp-lifecycle-test',
+      pid: process.pid,
+      workspaceKey: 'workspace-a',
+    });
     setSimulatorLaunchOsLogRecordActiveOverrideForTests(async () => true);
     await clearAllSimulatorLaunchOsLogSessionsForTests();
   });