ai-or-die 0.1.0

package/docs/specs/e2e-testing.md

@@ -0,0 +1,311 @@
+# E2E Testing Specification
+
+This document outlines the end-to-end testing strategy for the ai-or-die web application, covering framework selection, architectural decisions, and the full test plan.
+
+## 1. Research Findings
+
+### 1.1 Testing WebSocket-Based Node.js Apps
+
+**Recommended approach: Mocha + native `ws` client.**
+
+The `ws` npm package (already a project dependency) doubles as both server and client library. For Mocha-based integration tests, the pattern is straightforward:
+
+- Start the server in a `before()` hook via the `ClaudeCodeWebServer` class
+- Create `ws` client connections in each test
+- Tear down in `after()` hooks
+
+This avoids adding any new dependencies. The `ws` client supports the same event model as the browser `WebSocket` API, making test code transferable.
+
+Alternative approaches considered and rejected:
+- **jest-websocket-mock** -- Jest-specific, doesn't fit our Mocha setup
+- **mock-socket** -- Adds a mock layer we don't need; we want real server integration
+- **MSW (Mock Service Worker)** -- Overkill for server-side WebSocket testing
+
+**Sources:**
+- [Integration testing WebSocket server in Node.JS (Medium)](https://medium.com/@basavarajkn/integration-testing-websocket-server-in-node-js-2997d107414c)
+- [WebSocket Tests: Complete Guide 2025 (VideoSDK)](https://www.videosdk.live/developer-hub/websocket/websocket-tests)
+- [ws GitHub repository](https://github.com/websockets/ws)
+
+### 1.2 Testing xterm.js Terminal Emulation E2E
+
+xterm.js itself uses Playwright for its integration test suite, running tests against the browser-rendered terminal canvas. For our use case, however, the critical path is **server-side**: data flows from the spawned CLI process through node-pty, over WebSocket, to the client. The xterm.js rendering layer is a display concern.
+
+**Our strategy splits into two tiers:**
+
+| Tier | What it tests | Tool |
+|------|--------------|------|
+| Server E2E | Server boot, WebSocket protocol, session lifecycle, PTY I/O | Mocha + `ws` client |
+| Browser E2E (future) | xterm.js rendering, keyboard input, UI interactions | Playwright |
+
+For the initial test suite, Tier 1 (server E2E) provides the highest coverage-to-effort ratio. It validates the entire backend pipeline without requiring a browser.
+
+**Sources:**
+- [xterm.js Contributing Wiki](https://github.com/xtermjs/xterm.js/wiki/Contributing)
+- [Playwright E2E Guide 2026 (DeviQA)](https://www.deviqa.com/blog/guide-to-playwright-end-to-end-testing-in-2025/)
+
+### 1.3 Testing node-pty Without Real CLI Tools
+
+The key insight: **we don't need to mock node-pty at all**. The `TerminalBridge` already spawns the user's default shell (bash on Linux, PowerShell on Windows). A shell is a perfectly valid "mock tool" -- we can:
+
+1. Start a terminal session (spawns bash/powershell)
+2. Send `echo "test input"` as input
+3. Verify the echoed output appears in the WebSocket stream
+
+This tests the full node-pty pipeline (spawn, write, read, resize, kill) using a real pseudo-terminal, without needing Claude/Copilot/Gemini installed. The `TerminalBridge.isAvailable()` always returns `true` since a shell is always present.
+
+For CI environments where specific tool bridges need validation, lightweight mock scripts can simulate CLI behavior:
+
+```bash
+#!/bin/bash
+# mock-tool.sh -- Simulates a CLI tool
+echo "Mock Tool v1.0"
+while IFS= read -r line; do
+    echo "Response: $line"
+done
+```
+
+**Sources:**
+- [node-pty GitHub (microsoft/node-pty)](https://github.com/microsoft/node-pty)
+- [Node.js PTY Deep Dive (w3tutorials)](https://www.w3tutorials.net/blog/nodejs-pty/)
+
+### 1.4 Express + WebSocket E2E Best Practices (2025/2026)
+
+Current best practices for testing Express + WebSocket servers:
+
+1. **Decouple server from port binding** -- The `ClaudeCodeWebServer` class already supports this via `start()` returning a promise. Use port 0 for auto-assignment in tests.
+2. **Lifecycle in hooks** -- `before()` starts server, `after()` calls `close()`. Keep server instances per `describe` block to avoid cross-contamination.
+3. **Async-first** -- Mocha 11.x natively handles async/await and returned promises.
+4. **Timeout management** -- WebSocket tests need longer timeouts (5-10s) for PTY spawn + output propagation.
+5. **Parallel safety** -- Each test suite uses a unique port (0 = OS-assigned) and isolated session state.
+
+**Sources:**
+- [Fullstack Open: E2E Testing with Playwright](https://fullstackopen.com/en/part5/end_to_end_testing_playwright/)
+- [Testing Socket.io With Mocha and Chai](https://alexzywiak.github.io/testing-socket-io-with-mocha-and-chai/index.html)
+
+### 1.5 Can Playwright/Puppeteer Test xterm.js Terminals?
+
+**Yes, but with caveats.**
+
+xterm.js renders to a `<canvas>` element (via its WebGL or Canvas renderer), which means standard DOM selectors don't work for reading terminal content. Approaches:
+
+- **xterm.js API access via `page.evaluate()`** -- Expose the `Terminal` instance on `window`, then call `terminal.buffer.active.getLine(row).translateToString()` to read terminal content programmatically.
+- **Keyboard simulation** -- Playwright's `page.keyboard.type()` sends keystrokes that xterm.js captures.
+- **Screenshot comparison** -- Visual regression testing via `page.screenshot()` comparisons.
+
+For the initial test suite, browser-level tests are **deferred**. The server E2E tests with `ws` clients cover the critical data path. Browser tests can be added later as a Playwright layer when UI regression testing becomes a priority.
+
+**Sources:**
+- [Playwright GitHub](https://github.com/microsoft/playwright)
+- [xterm.js GitHub](https://github.com/xtermjs/xterm.js)
+
+---
+
+## 2. Test Architecture
+
+### 2.1 Design Principles
+
+- **No new dependencies** -- Use Mocha (devDependency), `ws` and `assert` (both already available)
+- **Real server, real PTY** -- No mocking of node-pty or WebSocket; test the actual stack
+- **Mock the tools, not the infrastructure** -- Use bash/echo as the "tool" instead of Claude/Copilot
+- **Cross-platform** -- Tests must pass on Linux and Windows CI; use `TerminalBridge` (shell) as the universal tool
+- **Deterministic** -- Avoid timing-dependent assertions; use event-driven waits with timeouts
+- **Isolated** -- Each test suite starts its own server on an ephemeral port
+
+### 2.2 File Structure
+
+```
+test/
+  session-store.test.js      # Existing: unit tests for SessionStore
+  claude-bridge.test.js       # Existing: unit tests for ClaudeBridge
+  server-alias.test.js        # Existing: unit tests for server aliases
+  e2e.test.js                 # NEW: server E2E tests (this spec)
+```
+
+### 2.3 Helper Utilities (embedded in test file)
+
+```javascript
+// Wait for a specific WebSocket message type
+function waitForMessage(ws, type, timeoutMs = 5000) { ... }
+
+// Create an authenticated WebSocket connection
+function connectWs(port, token, sessionId) { ... }
+
+// Send a typed message and await a specific response type
+function sendAndWait(ws, message, expectedType, timeoutMs) { ... }
+```
+
+---
+
+## 3. Test Plan
+
+### 3.1 Server Boot & Health (`describe('Server lifecycle')`)
+
+| Test | What it validates |
+|------|-------------------|
+| Server starts on ephemeral port | `ClaudeCodeWebServer.start()` resolves; port > 0 |
+| Health endpoint returns OK | `GET /api/health` -> `{ status: 'ok' }` |
+| Config endpoint returns tool info | `GET /api/config` -> contains `tools.terminal.available: true` |
+| Server shuts down cleanly | `server.close()` completes without error |
+
+### 3.2 Authentication (`describe('Authentication')`)
+
+| Test | What it validates |
+|------|-------------------|
+| Auth-enabled: valid token accepted | `GET /api/health` with `Bearer <token>` -> 200 |
+| Auth-enabled: invalid token rejected | `GET /api/health` with wrong token -> 401 |
+| Auth-enabled: missing token rejected | `GET /api/health` with no auth -> 401 |
+| Auth-enabled: WS with valid token connects | WS `?token=<token>` -> receives `connected` message |
+| Auth-enabled: WS with invalid token rejected | WS `?token=wrong` -> connection refused |
+| No-auth mode: all requests accepted | `noAuth: true` -> health endpoint accessible without token |
+
+### 3.3 WebSocket Connection (`describe('WebSocket connection')`)
+
+| Test | What it validates |
+|------|-------------------|
+| Connection receives `connected` message | First message is `{ type: 'connected', connectionId: <uuid> }` |
+| Ping/pong works | Send `{ type: 'ping' }` -> receive `{ type: 'pong' }` |
+| Clean disconnect | Close WS -> no server errors |
+
+### 3.4 Session Management (`describe('Session management')`)
+
+| Test | What it validates |
+|------|-------------------|
+| Create session via WS | Send `create_session` -> receive `session_created` with `sessionId` |
+| Create session via REST | `POST /api/sessions/create` -> 200 with `sessionId` |
+| List sessions | `GET /api/sessions/list` -> includes created session |
+| Join existing session | Send `join_session` with valid ID -> receive `session_joined` with output buffer |
+| Join non-existent session | Send `join_session` with bad ID -> receive `error` |
+| Leave session | Send `leave_session` -> receive `session_left` |
+| Delete session via REST | `DELETE /api/sessions/:id` -> 200, session gone from list |
+| Delete non-existent session | `DELETE /api/sessions/bad-id` -> 404 |
+
+### 3.5 Tool Session Lifecycle (`describe('Terminal tool session')`)
+
+| Test | What it validates |
+|------|-------------------|
+| Start terminal session | Send `start_terminal` -> receive `terminal_started` |
+| Terminal produces output | After start, receive `output` messages (shell prompt) |
+| Send input, receive output | Send `echo hello` -> output contains `hello` |
+| Resize terminal | Send `resize` with new cols/rows -> no error |
+| Stop terminal session | Send `stop` -> receive `exit` message |
+| Cannot start two tools in same session | Start terminal, then start terminal again -> receive `error` |
+| Echo unique marker through terminal (cross-platform) | Start terminal -> drain initial output -> send `echo MARKER` -> verify marker in collected output -> stop |
+
+### 3.6 Input/Output Round-Trip (`describe('I/O round-trip')`)
+
+| Test | What it validates |
+|------|-------------------|
+| Echo command round-trip | Send `echo MARKER_STRING` -> output stream contains `MARKER_STRING` |
+| Multi-line output | Send command producing multiple lines -> all lines received |
+| Special characters | Send `echo "hello world & <test>"` -> output preserves content |
+| Output buffer replay | Join session -> `session_joined` includes prior output in buffer |
+
+### 3.7 Multi-Session (`describe('Multi-session management')`)
+
+| Test | What it validates |
+|------|-------------------|
+| Create multiple sessions | Create 3 sessions -> list shows 3 |
+| Sessions are isolated | Start terminal in session A, send input -> session B gets no output |
+| Switch sessions | Leave session A, join session B -> receive B's buffer |
+| Delete active session | Delete session with running terminal -> process stops, session removed |
+
+---
+
+## 4. Cross-Platform Considerations
+
+### 4.1 Shell Differences
+
+| Aspect | Linux/macOS | Windows |
+|--------|-------------|---------|
+| Default shell | bash/zsh | PowerShell/cmd |
+| Echo command | `echo hello` | `echo hello` (works in both) |
+| Line endings | `\n` | `\r\n` |
+| Exit command | `exit` | `exit` |
+| Prompt detection | `$` or `#` | `PS C:\>` or `>` |
+
+The test suite uses `echo` for I/O validation, which works identically across shells. Output assertions use substring matching (`.includes()`) rather than exact string comparison to handle prompt/formatting differences.
+
+### 4.2 CI Matrix
+
+```yaml
+# Example GitHub Actions matrix
+strategy:
+  matrix:
+    os: [ubuntu-latest, windows-latest]
+    node: [18, 20, 22]
+```
+
+### 4.3 Timeout Handling
+
+PTY process startup varies by platform. Windows ConPTY is slower than Unix PTY. Tests use:
+- 5s default message timeout
+- 10s timeout for PTY output propagation
+- 30s Mocha suite timeout
+
+---
+
+## 5. Future Enhancements
+
+### 5.1 Browser E2E with Playwright (Tier 2)
+
+When browser-level testing is needed:
+
+```javascript
+// Example Playwright test structure
+test('terminal displays tool output', async ({ page }) => {
+  await page.goto(`http://localhost:${port}?token=${authToken}`);
+
+  // Wait for xterm.js canvas to render
+  await page.waitForSelector('.xterm-screen canvas');
+
+  // Read terminal content via xterm API
+  const content = await page.evaluate(() => {
+    const term = window.__terminal__;
+    const buffer = term.buffer.active;
+    let text = '';
+    for (let i = 0; i < buffer.cursorY + 1; i++) {
+      text += buffer.getLine(i).translateToString(true) + '\n';
+    }
+    return text;
+  });
+
+  expect(content).toContain('expected output');
+});
+```
+
+### 5.2 Mock Tool Scripts
+
+For testing specific tool bridge behaviors (trust prompts, dangerous mode flags):
+
+```bash
+#!/bin/bash
+# test/fixtures/mock-claude.sh
+echo "Claude Code v1.0.0 (mock)"
+echo "Do you trust the files in this folder?"
+read -r response
+echo "Trust accepted: $response"
+while IFS= read -r line; do
+    echo "Assistant: I received '$line'"
+done
+```
+
+### 5.3 Performance/Load Testing
+
+- Concurrent WebSocket connections (50-100 simultaneous)
+- Session creation throughput
+- Output streaming latency under load
+- Memory usage with many active PTY sessions
+
+---
+
+## 6. Dependencies
+
+No new dependencies required.
+
+| Package | Role | Status |
+|---------|------|--------|
+| `mocha` | Test runner | Already in devDependencies |
+| `assert` | Assertions | Node.js built-in |
+| `ws` | WebSocket client in tests | Already in dependencies |
+| `http` | HTTP client for REST endpoints | Node.js built-in |
+| `node-pty` | PTY spawning (via bridges) | Already in dependencies |

package/docs/specs/server.md

@@ -0,0 +1,334 @@
+# Server Specification
+
+Source: `src/server.js` -- class `ClaudeCodeWebServer`
+
+## Constructor
+
+```js
+new ClaudeCodeWebServer(options)
+```
+
+| Option | Type | Default | Description |
+|--------|------|---------|-------------|
+| `port` | number | `7777` | HTTP/HTTPS listen port |
+| `auth` | string | `undefined` | Bearer token for authentication; when set, all HTTP and WebSocket requests must provide it |
+| `noAuth` | boolean | `false` | Disable authentication entirely (`--disable-auth`) |
+| `dev` | boolean | `false` | Enable verbose console logging |
+| `https` | boolean | `false` | Start an HTTPS server instead of HTTP |
+| `cert` | string | -- | Path to PEM certificate file (required when `https` is true) |
+| `key` | string | -- | Path to PEM private key file (required when `https` is true) |
+| `folderMode` | boolean | `true` | Enable folder-selection UI (defaults to true; always enabled in current CLI) |
+| `sessionHours` | number | `5` | Session window duration in hours; also read from `CLAUDE_SESSION_HOURS` env |
+| `plan` | string | `'max20'` | Subscription plan type (`pro`, `max5`, `max20`, `custom`); also read from `CLAUDE_PLAN` env |
+| `customCostLimit` | number | `50.00` | Dollar cost limit for custom plans; also read from `CLAUDE_COST_LIMIT` env |
+| `claudeAlias` | string | `'Claude'` | UI display name for Claude agent; also read from `CLAUDE_ALIAS` env |
+| `codexAlias` | string | `'Codex'` | UI display name for Codex agent; also read from `CODEX_ALIAS` env |
+| `agentAlias` | string | `'Cursor'` | UI display name for the third agent; also read from `AGENT_ALIAS` env |
+
+### Internal State
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `claudeSessions` | `Map<string, Session>` | All sessions keyed by UUID |
+| `webSocketConnections` | `Map<string, WsInfo>` | Active WebSocket connections keyed by UUID |
+| `claudeBridge` | `ClaudeBridge` | Bridge instance managing Claude CLI processes |
+| `codexBridge` | `CodexBridge` | Bridge instance managing Codex CLI processes |
+| `agentBridge` | `AgentBridge` | Bridge instance managing Cursor Agent processes |
+| `sessionStore` | `SessionStore` | Persistence layer for session data |
+| `usageReader` | `UsageReader` | Reads JSONL usage logs from `~/.claude/projects/` |
+| `usageAnalytics` | `UsageAnalytics` | Calculates burn rate, predictions, plan limits |
+| `selectedWorkingDir` | string \| null | Currently selected working directory via folder browser |
+| `baseFolder` | string | `process.cwd()` at startup -- root for path validation |
+| `isShuttingDown` | boolean | Prevents duplicate shutdown sequences |
+
+---
+
+## REST API Endpoints
+
+### Public (pre-auth)
+
+#### `GET /auth-status`
+Returns whether authentication is required.
+
+**Response:**
+```json
+{ "authRequired": true, "authenticated": false }
+```
+
+#### `POST /auth-verify`
+Validates a token against the server's configured auth token.
+
+**Request body:** `{ "token": "..." }`
+**Success:** `{ "valid": true }`
+**Failure (401):** `{ "valid": false, "error": "Invalid token" }`
+
+### Protected (behind auth middleware when auth is enabled)
+
+#### `GET /api/health`
+Health check.
+
+**Response:**
+```json
+{ "status": "ok", "claudeSessions": 3, "activeConnections": 2 }
+```
+
+#### `GET /api/sessions/list`
+List all sessions with metadata.
+
+**Response:**
+```json
+{
+  "sessions": [
+    {
+      "id": "uuid",
+      "name": "Session 2/5/2026, 10:30:00 AM",
+      "created": "2026-02-05T10:30:00.000Z",
+      "active": true,
+      "workingDir": "/home/user/project",
+      "connectedClients": 1,
+      "lastActivity": "2026-02-05T11:00:00.000Z"
+    }
+  ]
+}
+```
+
+#### `POST /api/sessions/create`
+Create a new session.
+
+**Request body:** `{ "name": "...", "workingDir": "/path" }`
+- `workingDir` is validated against `baseFolder`.
+- Falls back to `selectedWorkingDir` or `baseFolder` when omitted.
+
+**Response:**
+```json
+{ "success": true, "sessionId": "uuid", "session": { "id": "...", "name": "...", "workingDir": "..." } }
+```
+
+#### `GET /api/sessions/:sessionId`
+Get details of a single session.
+
+**Response:** Session object with `id`, `name`, `created`, `active`, `workingDir`, `connectedClients`, `lastActivity`.
+
+**404** when session ID is unknown.
+
+#### `DELETE /api/sessions/:sessionId`
+Delete a session. Stops the running agent process (if any), sends `session_deleted` to all connected WebSocket clients, and removes the session from the in-memory Map and disk persistence.
+
+**Response:** `{ "success": true, "message": "Session deleted" }`
+
+#### `GET /api/config`
+Returns server configuration relevant to the client.
+
+**Response:**
+```json
+{
+  "folderMode": true,
+  "selectedWorkingDir": "/home/user/project",
+  "baseFolder": "/home/user",
+  "aliases": { "claude": "Claude", "codex": "Codex", "agent": "Cursor" }
+}
+```
+
+#### `GET /api/folders`
+Browse directories within `baseFolder`.
+
+**Query params:**
+- `path` -- directory to list (default: `baseFolder`)
+- `showHidden` -- `"true"` to include dotfiles
+
+**Response:**
+```json
+{
+  "currentPath": "/home/user/projects",
+  "parentPath": "/home/user",
+  "folders": [ { "name": "repo", "path": "/home/user/projects/repo", "isDirectory": true } ],
+  "home": "/home/user",
+  "baseFolder": "/home/user"
+}
+```
+
+#### `POST /api/set-working-dir`
+Set the server-wide working directory for new sessions.
+
+**Request body:** `{ "path": "/absolute/path" }`
+**Response:** `{ "success": true, "workingDir": "/absolute/path" }`
+
+#### `POST /api/folders/select`
+Alias for `POST /api/set-working-dir` with identical behavior.
+
+#### `POST /api/create-folder`
+Create a new directory inside an allowed parent.
+
+**Request body:** `{ "parentPath": "/base/path", "folderName": "new-dir" }`
+- `folderName` must not contain `/` or `\`.
+- Both `parentPath` and resulting path are validated.
+
+**Response:** `{ "success": true, "path": "/base/path/new-dir", "message": "..." }`
+
+#### `POST /api/close-session`
+Clears `selectedWorkingDir` back to `null`.
+
+**Response:** `{ "success": true, "message": "Working directory cleared" }`
+
+#### `GET /api/sessions/persistence`
+Returns persistence metadata from `SessionStore.getSessionMetadata()`.
+
+**Response:**
+```json
+{
+  "exists": true,
+  "savedAt": "2026-02-05T10:00:00.000Z",
+  "sessionCount": 3,
+  "fileSize": 4096,
+  "version": "1.0",
+  "currentSessions": 3,
+  "autoSaveEnabled": true,
+  "autoSaveInterval": 30000
+}
+```
+
+#### `GET /`
+Serves `src/public/index.html`.
+
+---
+
+## WebSocket
+
+### Setup
+
+The WebSocket server (`ws.Server`) is attached to the same HTTP(S) server instance. A `verifyClient` callback checks the `?token=` query parameter against `this.auth` when authentication is enabled.
+
+### Connection Lifecycle
+
+1. Client connects. Server assigns a `wsId` (UUID), stores it in `webSocketConnections`, and sends `{ type: "connected", connectionId: wsId }`.
+2. If `?sessionId=` is present in the URL and the session exists, the server auto-joins that session.
+3. On close or error, the connection is removed from `webSocketConnections` and its session's `connections` Set.
+
+### Message Protocol
+
+All messages are JSON. The `type` field determines the handler.
+
+| Client Message | Description |
+|---------------|-------------|
+| `create_session` | Create a new session and join it. Fields: `name`, `workingDir`. |
+| `join_session` | Join an existing session. Fields: `sessionId`. Replays the last 200 lines of the output buffer. |
+| `leave_session` | Disconnect from current session without stopping the agent. |
+| `start_claude` | Launch Claude CLI in the current session. Fields: `options` (optional). Pre-checks tool availability. |
+| `start_codex` | Launch Codex CLI in the current session. Fields: `options` (optional). Pre-checks tool availability. |
+| `start_copilot` | Launch Copilot CLI in the current session. Fields: `options` (optional). Pre-checks tool availability. |
+| `start_gemini` | Launch Gemini CLI in the current session. Fields: `options` (optional). Pre-checks tool availability. |
+| `start_terminal` | Launch a terminal shell in the current session. Fields: `options` (optional). Pre-checks tool availability. |
+
+**`start_*` Error Handling**: All tool start messages go through `startToolSession`, which sends an `error` message for every failure path:
+
+| Condition | Error message |
+|-----------|--------------|
+| No session joined | "No session joined. Please create or join a session first." |
+| Session not in map | "Session not found. It may have been deleted. Please create a new session." |
+| Agent already running | "An agent is already running in this session" |
+| Tool not available | "{tool} is not available. Please ensure the {tool} CLI is installed..." |
+| Spawn failure | "Failed to start {tool}: {error}" |
+
+| `input` | Send raw terminal input to the running agent. Fields: `data`. |
+| `resize` | Resize the pty. Fields: `cols`, `rows`. |
+| `stop` | Terminate the running agent process. |
+| `ping` | Keep-alive. Server responds with `{ type: "pong" }`. |
+| `get_usage` | Request usage statistics. Server responds with `usage_update`. |
+
+| Server Message | Description |
+|---------------|-------------|
+| `connected` | Initial connection acknowledgment with `connectionId`. |
+| `session_created` | Session successfully created. Fields: `sessionId`, `sessionName`, `workingDir`. |
+| `session_joined` | Joined an existing session. Fields: `sessionId`, `sessionName`, `workingDir`, `active`, `outputBuffer`. |
+| `session_left` | Successfully left the session. Fields: `sessionId`. |
+| `session_deleted` | Session was deleted by another client or via REST API. |
+| `claude_started` / `codex_started` / `agent_started` | Agent process launched. |
+| `claude_stopped` / `codex_stopped` / `agent_stopped` | Agent process terminated. |
+| `output` | Terminal output data from the agent. Fields: `data`. |
+| `exit` | Agent process exited. Fields: `code`, `signal`. |
+| `error` | Error message. Fields: `message`. |
+| `info` | Informational message (e.g., "No agent is running"). |
+| `pong` | Response to `ping`. |
+| `usage_update` | Usage statistics payload (see Usage Analytics spec). |
+
+### Broadcasting
+
+`broadcastToSession(sessionId, data)` iterates the session's `connections` Set, verifies each WebSocket is open and belongs to the correct session, then sends the JSON-serialized message.
+
+---
+
+## Session Management
+
+### In-Memory Session Object
+
+```js
+{
+  id: 'uuid',
+  name: 'Session 2/5/2026, 10:30:00 AM',
+  created: Date,
+  lastActivity: Date,
+  active: false,                // true when an agent process is running
+  agent: null,                  // 'claude' | 'codex' | 'agent' | null
+  workingDir: '/path',
+  connections: Set<wsId>,       // WebSocket connection IDs
+  outputBuffer: [],             // Rolling buffer of terminal output strings
+  maxBufferSize: 1000,          // Max items in outputBuffer
+  sessionStartTime: Date|null,  // Set on first agent start
+  sessionUsage: {               // Aggregated token/cost tracking
+    requests: 0,
+    inputTokens: 0,
+    outputTokens: 0,
+    cacheTokens: 0,
+    totalCost: 0,
+    models: {}
+  }
+}
+```
+
+### Auto-Save
+
+Sessions are persisted to disk via `SessionStore` every 30 seconds (`setInterval`). The `saveSessionsToDisk()` method also fires:
+- After session creation
+- After session deletion
+- On `beforeExit`
+- During graceful shutdown
+
+### Session Restoration
+
+On startup, `loadPersistedSessions()` loads sessions from disk. All sessions are restored with `active: false` and empty `connections` Sets since pty processes do not survive restarts.
+
+---
+
+## Graceful Shutdown
+
+Registered on `SIGINT` and `SIGTERM`. The `handleShutdown()` method:
+
+1. Sets `isShuttingDown = true` to prevent re-entry.
+2. Saves all sessions to disk.
+3. Clears the auto-save interval.
+4. Calls `close()` which:
+   - Saves sessions again.
+   - Closes the WebSocket server.
+   - Closes the HTTP server.
+   - Stops all active agent processes (routing to the correct bridge based on `session.agent`).
+   - Clears `claudeSessions` and `webSocketConnections` Maps.
+5. Calls `process.exit(0)`.
+
+---
+
+## Path Validation
+
+Two methods enforce directory traversal prevention:
+
+- **`isPathWithinBase(targetPath)`** -- Resolves `targetPath` and checks that it starts with the resolved `baseFolder`.
+- **`validatePath(targetPath)`** -- Returns `{ valid: true, path: resolvedPath }` or `{ valid: false, error: '...' }`.
+
+Every endpoint that accepts a filesystem path (`/api/folders`, `/api/set-working-dir`, `/api/create-folder`, `/api/sessions/create`, etc.) calls `validatePath()` before performing any I/O. The `baseFolder` is always `process.cwd()` at server startup time.
+
+---
+
+## Static Assets and PWA
+
+- `express.static` serves `src/public/`.
+- `manifest.json` is served with `Content-Type: application/manifest+json`.
+- Dynamic SVG icons are generated at `/icon-{16,32,144,180,192,512}.png` with monospace "CC" text on a dark background, served as `image/svg+xml` with a 1-year cache header.