# IDE Services Session Recovery Mechanism

## Overview
The VS Code extension now includes automatic session recovery for IDE services. Session files are treated as ephemeral and automatically recreated when needed.

## How It Works

### Server Side (handler.php)
- Sessions are stored in `/storage/rsx-ide-bridge/auth-{session}.json` files
- These files are transient and can be deleted anytime (e.g., during cache clear)
- When a session is not found, the server returns:
  ```json
  {
    "error": "Session not found",
    "code": 401,
    "recoverable": true,
    "recovery": "Create new session via POST /_ide/service/auth/create"
  }
  ```

### Client Side (VS Code Extension)
The extension automatically recovers from session loss:

1. **Initial Request**: Attempts to use existing session if available
2. **Session Not Found**: If server returns 401 with "Session not found"
3. **Automatic Recovery**:
   - Creates new session via `/auth/create`
   - Retries the original request with new session
4. **Transparent to User**: No user intervention required

## Implementation

### TypeScript/JavaScript (formatting_provider.ts)
```typescript
async make_authenticated_request(endpoint: string, data: any, retry_count: number = 0) {
    // Try the request
    try {
        const response = await this.make_request(endpoint, data, 'POST', true, headers);
        return response;
    } catch (error: any) {
        // Check if recoverable
        if (retry_count === 0 && error.message.includes('Session not found')) {
            // Clear old session
            this.auth_data = null;
            // Retry with new session
            return this.make_authenticated_request(endpoint, data, retry_count + 1);
        }
        throw error;
    }
}
```

## Benefits

1. **Zero Configuration**: Works automatically, no setup needed
2. **Resilient**: Survives cache clears, server restarts, file deletions
3. **Transparent**: Users never see authentication errors
4. **Stateless**: Session files are temporary and disposable

## Testing

1. **Normal Operation**: Extension should work normally
2. **Session Deletion**: Delete `/storage/rsx-ide-bridge/auth-*.json` files
3. **Cache Clear**: Run `php artisan rsx:clean`
4. **Expected Result**: Extension automatically recovers and continues working

## Troubleshooting

If recovery fails:
1. Check server logs: `/storage/logs/laravel.log`
2. Check VS Code Output panel: "RSpade Formatter" channel
3. Verify `/_ide/service/auth/create` endpoint is accessible
4. Ensure workspace has write permissions for `/storage/rsx-ide-bridge/`

## Security Notes

- Sessions are workspace-specific (stored locally)
- Each session has unique client/server keys
- Signatures prevent replay attacks
- Sessions can be manually revoked by deleting files