Add SESSION_ALREADY_EXISTS error code for session conflicts

Replaces RESOURCE_BUSY with a semantically correct error code that
properly indicates a uniqueness constraint violation rather than a
temporary lock.

Author: ghostwriternr

CLAUDE.md

@@ -293,6 +293,8 @@ Turbo handles task orchestration (`turbo.json`) with dependency-aware builds.
 
 **Focus on the change, not how it was discovered** - never reference "review feedback", "PR comments", or "code review" in commit messages. Describe what the change does and why, not that someone asked for it.
 
+**Avoid bullet points** - write prose, not lists. If you need bullets to explain a change, you're either committing too much at once or over-explaining implementation details. The body should be a brief paragraph, not a changelog.
+
 Good examples:
 
 ```

packages/sandbox-container/src/services/session-manager.ts

@@ -32,7 +32,7 @@ export class SessionManager {
           success: false,
           error: {
             message: `Session '${options.id}' already exists`,
-            code: ErrorCode.RESOURCE_BUSY,
+            code: ErrorCode.SESSION_ALREADY_EXISTS,
             details: {
               sessionId: options.id
             }

packages/sandbox/src/errors/adapter.ts

@@ -26,6 +26,7 @@ import type {
   PortNotExposedContext,
   ProcessErrorContext,
   ProcessNotFoundContext,
+  SessionAlreadyExistsContext,
   ValidationFailedContext
 } from '@repo/shared/errors';
 import { ErrorCode } from '@repo/shared/errors';
@@ -58,6 +59,7 @@ import {
   ProcessNotFoundError,
   SandboxError,
   ServiceNotRespondingError,
+  SessionAlreadyExistsError,
   ValidationFailedError
 } from './classes';
 
@@ -123,6 +125,12 @@ export function createErrorFromResponse(errorResponse: ErrorResponse): Error {
         errorResponse as unknown as ErrorResponse<ProcessErrorContext>
       );
 
+    // Session Errors
+    case ErrorCode.SESSION_ALREADY_EXISTS:
+      return new SessionAlreadyExistsError(
+        errorResponse as unknown as ErrorResponse<SessionAlreadyExistsContext>
+      );
+
     // Port Errors
     case ErrorCode.PORT_ALREADY_EXPOSED:
       return new PortAlreadyExposedError(

packages/sandbox/src/errors/classes.ts

@@ -28,6 +28,7 @@ import type {
   ProcessExitedBeforeReadyContext,
   ProcessNotFoundContext,
   ProcessReadyTimeoutContext,
+  SessionAlreadyExistsContext,
   ValidationFailedContext
 } from '@repo/shared/errors';
 
@@ -236,6 +237,25 @@ export class ProcessError extends SandboxError<ProcessErrorContext> {
   }
 }
 
+// ============================================================================
+// Session Errors
+// ============================================================================
+
+/**
+ * Error thrown when a session already exists
+ */
+export class SessionAlreadyExistsError extends SandboxError<SessionAlreadyExistsContext> {
+  constructor(errorResponse: ErrorResponse<SessionAlreadyExistsContext>) {
+    super(errorResponse);
+    this.name = 'SessionAlreadyExistsError';
+  }
+
+  // Type-safe accessors
+  get sessionId() {
+    return this.context.sessionId;
+  }
+}
+
 // ============================================================================
 // Port Errors
 // ============================================================================

packages/sandbox/src/errors/index.ts

@@ -109,6 +109,8 @@ export {
   ProcessReadyTimeoutError,
   SandboxError,
   ServiceNotRespondingError,
+  // Session Errors
+  SessionAlreadyExistsError,
   // Validation Errors
   ValidationFailedError
 } from './classes';

packages/sandbox/src/sandbox.ts

@@ -38,7 +38,7 @@ import {
   ErrorCode,
   ProcessExitedBeforeReadyError,
   ProcessReadyTimeoutError,
-  SandboxError
+  SessionAlreadyExistsError
 } from './errors';
 import { CodeInterpreter } from './interpreter';
 import { isLocalhostPattern } from './request-handler';
@@ -1015,10 +1015,7 @@ export class Sandbox<Env = unknown> extends Container<Env> implements ISandbox {
       this.logger.debug('Default session initialized', { sessionId });
     } catch (error: unknown) {
       // Session may already exist (e.g., after hot reload or concurrent request)
-      if (
-        error instanceof SandboxError &&
-        error.code === ErrorCode.RESOURCE_BUSY
-      ) {
+      if (error instanceof SessionAlreadyExistsError) {
         this.logger.debug(
           'Session exists in container but not in DO state, syncing',
           { sessionId }

packages/shared/src/errors/codes.ts

@@ -43,6 +43,9 @@ export const ErrorCode = {
   PROCESS_PERMISSION_DENIED: 'PROCESS_PERMISSION_DENIED',
   PROCESS_ERROR: 'PROCESS_ERROR',
 
+  // Session Errors (409)
+  SESSION_ALREADY_EXISTS: 'SESSION_ALREADY_EXISTS',
+
   // Port Errors (409)
   PORT_ALREADY_EXPOSED: 'PORT_ALREADY_EXPOSED',
   PORT_IN_USE: 'PORT_IN_USE',

packages/shared/src/errors/contexts.ts

@@ -48,6 +48,10 @@ export interface ProcessErrorContext {
   stderr?: string;
 }
 
+export interface SessionAlreadyExistsContext {
+  sessionId: string;
+}
+
 /**
  * Process readiness error contexts
  */

packages/shared/src/errors/index.ts

@@ -57,6 +57,7 @@ export type {
   ProcessExitedBeforeReadyContext,
   ProcessNotFoundContext,
   ProcessReadyTimeoutContext,
+  SessionAlreadyExistsContext,
   ValidationFailedContext
 } from './contexts';
 // Export utility functions

packages/shared/src/errors/status-map.ts

@@ -42,6 +42,7 @@ export const ERROR_STATUS_MAP: Record<ErrorCode, number> = {
   [ErrorCode.PORT_ALREADY_EXPOSED]: 409,
   [ErrorCode.PORT_IN_USE]: 409,
   [ErrorCode.RESOURCE_BUSY]: 409,
+  [ErrorCode.SESSION_ALREADY_EXISTS]: 409,
 
   // 502 Bad Gateway
   [ErrorCode.SERVICE_NOT_RESPONDING]: 502,