ai-or-die 0.1.0

package/docs/specs/authentication.md

@@ -0,0 +1,167 @@
+# Authentication Specification
+
+## Overview
+
+ai-or-die provides optional token-based authentication for both HTTP and WebSocket connections. Authentication is managed by two independent classes: a server-side `AuthManager` utility and a client-side `AuthManager` in the browser.
+
+---
+
+## Server-Side Auth
+
+### AuthManager Class
+
+Source: `src/utils/auth.js`
+
+A utility class for token management, rate limiting, and Express middleware generation. While the class is available, the server (`src/server.js`) currently implements auth inline rather than delegating to this class.
+
+#### Token Management
+
+| Method | Description |
+|--------|-------------|
+| `generateToken()` | Generates a 32-byte random hex string via `crypto.randomBytes(32).toString('hex')` |
+| `validateToken(token)` | Checks if `token` is in the internal `Set` |
+| `addToken(token)` | Adds a token to the `Set` |
+| `removeToken(token)` | Removes a token from the `Set` |
+| `clearTokens()` | Clears all stored tokens |
+
+#### Middleware Factory
+
+`createMiddleware(requiredToken)` returns an Express middleware that:
+
+1. If `requiredToken` is falsy, calls `next()` (no auth required).
+2. Extracts the token from:
+   - `Authorization: Bearer <token>` header, or
+   - `?token=<token>` query parameter.
+3. Compares against `requiredToken`.
+4. Returns `401 Unauthorized` with `{ error: "Unauthorized", message: "Valid authentication token required" }` on mismatch.
+
+#### WebSocket Validator
+
+`createWebSocketValidator(requiredToken)` returns a function compatible with the `ws` library's `verifyClient` callback:
+
+1. If `requiredToken` is falsy, returns `true` (no auth required).
+2. Parses the URL from `info.req.url`.
+3. Extracts `?token=` query parameter.
+4. Returns `token === requiredToken`.
+
+#### Rate Limiting
+
+`rateLimit(identifier, maxRequests = 100, windowMs = 60000)`:
+
+1. Tracks request timestamps per `identifier` (typically IP address).
+2. Filters to requests within the current window.
+3. Returns `false` if the limit is exceeded, `true` otherwise.
+4. Pushes the current timestamp on success.
+
+`createRateLimitMiddleware(maxRequests = 100, windowMs = 60000)` returns Express middleware that:
+- Identifies the client by `req.ip || req.connection.remoteAddress`.
+- Returns `429 Too Many Requests` with `retryAfter` header when the limit is hit.
+
+`cleanupRateLimit()`:
+- Removes entries older than 1 hour from the rate limiter `Map`.
+- Should be called periodically to prevent memory growth.
+
+---
+
+### Server Auth Implementation
+
+Source: `src/server.js` (inline in `setupExpress()`)
+
+The server implements authentication directly rather than using the `AuthManager` class:
+
+1. **Pre-auth endpoints** -- `/auth-status` and `/auth-verify` are registered before the auth middleware, making them accessible without a token.
+
+2. **Auth middleware** -- Registered conditionally when `!this.noAuth && this.auth`:
+   ```js
+   const token = req.headers.authorization || req.query.token;
+   if (token !== `Bearer ${this.auth}` && token !== this.auth) {
+     return res.status(401).json({ error: 'Unauthorized' });
+   }
+   ```
+   This accepts either:
+   - `Authorization: Bearer <token>` header
+   - `?token=<token>` query parameter (raw token, no Bearer prefix)
+   - `Authorization: <token>` header (raw token, matched directly)
+
+3. **WebSocket auth** -- The `verifyClient` callback on the `ws.Server`:
+   ```js
+   verifyClient: (info) => {
+     if (!this.noAuth && this.auth) {
+       const url = new URL(info.req.url, 'ws://localhost');
+       const token = url.searchParams.get('token');
+       return token === this.auth;
+     }
+     return true;
+   }
+   ```
+
+---
+
+### CLI Auth Flow
+
+Source: `bin/cc-web.js`
+
+| CLI Flag | Behavior |
+|----------|----------|
+| `--auth <token>` | Use the provided string as the auth token |
+| `--disable-auth` | Set `noAuth = true`; no token is required |
+| _(neither flag)_ | Auto-generate a random 10-character token using a charset that excludes ambiguous characters (`0`, `O`, `1`, `l`, `I`) |
+
+The random token generator:
+```js
+const chars = 'ABCDEFGHJKMNPQRSTUVWXYZabcdefghjkmnpqrstuvwxyz23456789';
+```
+This produces tokens that are easy to read and transcribe (e.g., `kP7nVm3Qxt`).
+
+The generated token is printed to the terminal with bold yellow ANSI formatting for visibility.
+
+---
+
+## Client-Side Auth
+
+### AuthManager (Browser)
+
+Source: `src/public/auth.js`
+
+A global singleton instantiated as `window.authManager`.
+
+#### Token Storage
+
+Tokens are stored in `sessionStorage` under the key `cc-web-token`. This means:
+- The token persists across page reloads within the same tab.
+- The token is cleared when the tab/browser is closed.
+- Each browser tab can have its own independent auth state.
+
+#### Initialization Flow
+
+`initialize()` is called on page load:
+
+1. Calls `GET /auth-status` to check if auth is required.
+2. If auth is required and no stored token exists, calls `showLoginPrompt()`.
+3. If auth is required and a token exists, calls `POST /auth-verify` to validate it.
+4. If validation fails, clears the stored token and shows the login prompt.
+5. Returns `true` if authenticated (or auth not required), `false` if the login prompt was shown.
+
+#### Login Prompt
+
+`showLoginPrompt()` creates a full-screen overlay (`z-index: 10000`) with:
+- A password input field for the access token.
+- A submit button that calls `verifyToken()`.
+- Error display for invalid tokens.
+- Visual feedback during verification (input disabled, button text changes to "Authenticating...").
+- On success: overlay is removed and `window.location.reload()` triggers full re-initialization.
+- On failure: error message is shown, form is re-enabled.
+
+#### Helper Methods
+
+| Method | Description |
+|--------|-------------|
+| `getAuthHeaders()` | Returns `{ Authorization: "Bearer <token>" }` or empty object |
+| `getWebSocketUrl(baseUrl)` | Appends `?token=<token>` (or `&token=<token>`) to the WebSocket URL |
+| `logout()` | Clears `sessionStorage`, reloads the page |
+
+#### Integration Points
+
+- `ClaudeCodeWebInterface.authFetch(url, options)` merges `authManager.getAuthHeaders()` into every fetch request.
+- WebSocket connections use `authManager.getWebSocketUrl()` to append the token to the connection URL.
+- `SessionTabManager.loadSessions()` and `closeSession()` include auth headers via `window.authManager.getAuthHeaders()`.

package/docs/specs/bridges.md

@@ -0,0 +1,210 @@
+# Bridge Specification
+
+Bridges manage the spawning, I/O, and lifecycle of CLI agent processes via `node-pty`. Each bridge class owns a `Map<sessionId, BridgeSession>` of active pty sessions.
+
+---
+
+## Common Interface
+
+Every bridge implements the same public API:
+
+| Method | Signature | Description |
+|--------|-----------|-------------|
+| `startSession` | `(sessionId, options) => Promise<BridgeSession>` | Spawn the CLI process in a pty and wire up output/exit/error callbacks. Throws if `sessionId` already exists. |
+| `sendInput` | `(sessionId, data) => Promise<void>` | Write raw data to the pty stdin. Throws if session is missing or inactive. |
+| `resize` | `(sessionId, cols, rows) => Promise<void>` | Resize the pty dimensions. Logs a warning on failure instead of throwing. |
+| `stopSession` | `(sessionId) => Promise<void>` | Send `SIGTERM`; after a 5-second grace period, send `SIGKILL`. Removes the session from the internal Map. |
+| `getSession` | `(sessionId) => BridgeSession \| undefined` | Return the raw session object. |
+| `getAllSessions` | `() => Array<{ id, workingDir, created, active }>` | List all sessions with metadata. |
+| `cleanup` | `() => Promise<void>` | Stop all active sessions. |
+
+### BridgeSession Object
+
+```js
+{
+  process: IPty,          // node-pty process handle
+  workingDir: string,     // cwd the process was started in
+  created: Date,
+  active: boolean,
+  killTimeout: Timeout|null  // handle for the SIGKILL escalation timer
+}
+```
+
+### startSession Options
+
+```js
+{
+  workingDir: string,                  // defaults to process.cwd()
+  dangerouslySkipPermissions: boolean, // defaults to false (Claude/Codex only)
+  onOutput: (data: string) => void,
+  onExit: (code: number, signal: number) => void,
+  onError: (error: Error) => void,
+  cols: number,                        // defaults to 80
+  rows: number                         // defaults to 24
+}
+```
+
+### PTY Environment
+
+All bridges spawn with these environment variables:
+
+```
+TERM=xterm-256color
+FORCE_COLOR=1
+COLORTERM=truecolor
+```
+
+The pty name is set to `xterm-color`.
+
+### Command Discovery
+
+Each bridge's constructor calls `findCommand()` which iterates through platform-specific candidate paths. Discovery works differently depending on whether the candidate is an absolute path or a bare command name:
+
+- **Absolute paths:** Checked via `fs.existsSync()` only. On Windows, candidates are expanded with `.exe` and `.cmd` suffixes (e.g., `C:\Users\foo\.claude\local\claude` also checks `claude.exe` and `claude.cmd`).
+- **Bare command names:** Checked via `commandExists()`, which runs `which` (Linux/macOS) or `where` (Windows) with a 5-second timeout to prevent hangs on systems with large PATH or network-mapped drives.
+
+The first match wins. If none are found, a fallback default command name is used (e.g., `'claude'`).
+
+### Spawn Watchdog
+
+After a PTY process is spawned, a 30-second watchdog timer starts. If no data, exit, or error event fires within that period, the process is killed and an error is reported to the caller. This prevents zombie processes on Windows where ConPTY initialization can hang silently. The watchdog is cleared on the first `onData`, `onExit`, or `on('error')` event.
+
+### Availability Check
+
+`isAvailable()` returns `true` if the resolved command differs from the fallback default (meaning a specific path was found), or if the fallback command exists on PATH. The server checks `isAvailable()` before attempting to spawn a tool session, returning an immediate error to the client if the CLI is not installed.
+
+The result is cached for 60 seconds (`_availableCache` / `_availableCacheTime`) to avoid repeated synchronous `where`/`which` calls that block the Node.js event loop. On Windows, `where.exe` can take several seconds when scanning large PATH variables or network-mapped drives, which would stall all WebSocket message processing during concurrent session starts.
+
+---
+
+## ClaudeBridge
+
+Source: `src/claude-bridge.js`
+
+### Command Search Paths
+
+```
+/home/ec2-user/.claude/local/claude
+claude                                (PATH lookup)
+claude-code                           (PATH lookup)
+~/.claude/local/claude
+~/.local/bin/claude
+/usr/local/bin/claude
+/usr/bin/claude
+```
+
+Fallback: `'claude'`
+
+### CLI Arguments
+
+| Flag | Condition |
+|------|-----------|
+| `--dangerously-skip-permissions` | When `options.dangerouslySkipPermissions` is `true` |
+
+### Trust Prompt Auto-Accept
+
+The bridge monitors output for the string `"Do you trust the files in this folder?"`. On first detection, it sends `\r` (Enter) after a 500ms delay to auto-confirm the default trust option. This is tracked via a `trustPromptHandled` boolean to prevent duplicate submissions.
+
+### Output Buffer
+
+A rolling `dataBuffer` (max 10,000 chars, trimmed to last 5,000) is maintained for trust prompt detection. This buffer is internal to the bridge and separate from the server-level `outputBuffer`.
+
+---
+
+## CodexBridge
+
+Source: `src/codex-bridge.js`
+
+### Command Search Paths
+
+```
+~/.codex/local/codex
+codex                    (PATH lookup)
+codex-code               (PATH lookup)
+~/.local/bin/codex
+/usr/local/bin/codex
+/usr/bin/codex
+```
+
+Fallback: `'codex'`
+
+### CLI Arguments
+
+| Flag | Condition |
+|------|-----------|
+| `--dangerously-bypass-approvals-and-sandbox` | When `options.dangerouslySkipPermissions` is `true` |
+
+### Notes
+
+- No trust prompt handling (Codex does not prompt for folder trust).
+- Maintains an internal `dataBuffer` (same 10,000/5,000 limits) for future prompt detection.
+
+---
+
+## AgentBridge
+
+Source: `src/agent-bridge.js`
+
+### Command Search Paths
+
+```
+~/.cursor/local/cursor-agent
+cursor-agent             (PATH lookup)
+~/.local/bin/cursor-agent
+/usr/local/bin/cursor-agent
+/usr/bin/cursor-agent
+```
+
+Fallback: `'cursor-agent'`
+
+### CLI Arguments
+
+None. The agent is spawned with an empty args array.
+
+### Notes
+
+- No `dangerouslySkipPermissions` option. The AgentBridge `startSession` does not destructure or use that option.
+- Maintains an internal `dataBuffer` (same 10,000/5,000 limits) for future prompt detection.
+
+---
+
+## Planned Bridges
+
+The following bridges are planned but not yet implemented. They should follow the same common interface described above.
+
+### BaseBridge (Planned)
+
+A shared base class that extracts the duplicated logic from ClaudeBridge, CodexBridge, and AgentBridge:
+
+- Cross-platform command discovery (`find*Command`, `commandExists`)
+- Session lifecycle management (`startSession`, `stopSession`, `sendInput`, `resize`)
+- Output buffering with configurable limits
+- Kill timeout escalation (SIGTERM then SIGKILL after 5s)
+- PTY environment setup
+
+Each concrete bridge would extend `BaseBridge` and provide:
+- `commandSearchPaths` -- ordered array of paths to search
+- `fallbackCommand` -- default command name
+- `buildArgs(options)` -- returns the CLI arguments array
+- `onDataHook(data, buffer)` -- optional per-bridge output processing (e.g., trust prompt handling)
+
+### CopilotBridge (Planned)
+
+- Command: `copilot`
+- Installation: `npm install -g @github/copilot`
+- Search paths: standard locations following the same pattern as existing bridges
+
+### GeminiBridge (Planned)
+
+- Command: `gemini`
+- Installation: `npm install -g @google/gemini-cli`
+- Search paths: standard locations following the same pattern as existing bridges
+
+### TerminalBridge (Planned)
+
+Opens a raw shell session rather than an AI agent.
+
+- Linux/macOS: spawns `$SHELL` (defaults to `/bin/bash`)
+- Windows: spawns `powershell.exe` or `cmd.exe`
+- No `dangerouslySkipPermissions` or AI-specific flags
+- Useful for running manual commands alongside agent sessions

package/docs/specs/client-app.md

@@ -0,0 +1,308 @@
+# Client Application Specification
+
+The frontend is a single-page application served from `src/public/`. It runs entirely in the browser with no build step -- all JavaScript is loaded directly via `<script>` tags.
+
+---
+
+## Dependencies
+
+| Library | Version | Source | Purpose |
+|---------|---------|--------|---------|
+| xterm.js | 5.3.0 | unpkg CDN | Terminal emulator component |
+| xterm-addon-fit | 0.8.0 | unpkg CDN | Auto-fit terminal to container |
+| xterm-addon-web-links | 0.9.0 | unpkg CDN | Clickable URLs in terminal output |
+| JetBrains Mono | -- | Google Fonts | Monospace font for terminal |
+| Inter | -- | Google Fonts | UI font for headers, tabs, controls |
+
+---
+
+## ClaudeCodeWebInterface
+
+Source: `src/public/app.js` (~2100 lines)
+
+The main application controller. Instantiated once on page load.
+
+### Constructor Properties
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `terminal` | Terminal | xterm.js instance |
+| `fitAddon` | FitAddon | Auto-resize addon |
+| `webLinksAddon` | WebLinksAddon | Clickable URL addon |
+| `socket` | WebSocket | Active WebSocket connection |
+| `connectionId` | string | Server-assigned connection UUID |
+| `currentClaudeSessionId` | string | Currently joined session ID |
+| `currentClaudeSessionName` | string | Currently joined session name |
+| `reconnectAttempts` | number | Counter for exponential backoff |
+| `maxReconnectAttempts` | number | 5 |
+| `reconnectDelay` | number | 1000ms base delay |
+| `folderMode` | boolean | Always `true` |
+| `currentFolderPath` | string | Current path in folder browser |
+| `claudeSessions` | Array | Cached session list from server |
+| `isCreatingNewSession` | boolean | Flag for new-session folder picker flow |
+| `isMobile` | boolean | Detected via `detectMobile()` |
+| `currentMode` | string | `'chat'` |
+| `planDetector` | PlanDetector | Plan mode detection instance |
+| `aliases` | Object | `{ claude: 'Claude', codex: 'Codex' }` -- populated from `/api/config` |
+| `sessionTabManager` | SessionTabManager | Tab bar controller |
+| `usageStats` | Object | Latest usage data |
+| `sessionTimer` | Object | Session timer data from server |
+| `sessionTimerInterval` | Interval | Client-side timer tick |
+| `splitContainer` | Object | Split/tile view controller |
+
+### Initialization Flow
+
+`init()` performs these steps in order:
+
+1. Call `window.authManager.initialize()`. If it returns `false`, the login prompt is displayed and initialization halts.
+2. Fetch `/api/config` to get folder mode, aliases, and base folder.
+3. Set up the terminal (xterm.js with fit addon and web links addon).
+4. Establish WebSocket connection.
+5. Set up UI event handlers (folder browser, session controls, resize observer).
+6. Initialize `SessionTabManager`.
+7. Initialize `PlanDetector`.
+8. Load existing sessions from the server.
+9. Start usage polling interval.
+
+### WebSocket Management
+
+- **Connection:** Constructs the URL with the session token via `authManager.getWebSocketUrl()`. Reconnects automatically with exponential backoff up to `maxReconnectAttempts`.
+- **Message handling:** Routes incoming messages by `type` field to appropriate handlers (output rendering, session state updates, usage updates, etc.).
+- **Output rendering:** Writes raw terminal data directly to xterm.js via `terminal.write(data)`. Also feeds data to `planDetector.processOutput(data)` and `sessionTabManager.markSessionActivity()`.
+
+### Terminal Configuration
+
+```js
+{
+  cursorBlink: true,
+  theme: {
+    background: '#0d1117',
+    foreground: '#f0f6fc',
+    cursor: '#f0f6fc',
+    // Full 16-color ANSI palette configured
+  },
+  fontFamily: "'JetBrains Mono', 'Cascadia Code', 'Fira Code', monospace",
+  fontSize: 14,          // 13 on mobile
+  lineHeight: 1.2,
+  scrollback: 10000,
+  allowProposedApi: true
+}
+```
+
+The terminal auto-resizes via `FitAddon` triggered by a `ResizeObserver` on the terminal container, debounced to prevent excessive resize messages.
+
+### Folder Browser
+
+A modal dialog for selecting working directories:
+- Fetches directory listings from `GET /api/folders?path=...`.
+- Supports navigating up to parent (within `baseFolder` bounds).
+- Supports creating new folders via `POST /api/create-folder`.
+- On selection, either creates a new session or sets the working directory.
+
+### Agent Start Controls
+
+When a session has no running agent, the UI presents buttons to start:
+- **Claude** -- sends `{ type: "start_claude" }`
+- **Codex** -- sends `{ type: "start_codex" }`
+- **Copilot** -- sends `{ type: "start_copilot" }`
+- **Gemini** -- sends `{ type: "start_gemini" }`
+- **Terminal** -- sends `{ type: "start_terminal" }`
+
+Each button's label uses the configured alias from `/api/config`. Buttons are disabled for tools that are not available on the server.
+
+A 45-second client-side timeout acts as a safety net: if no `_started`, `error`, or `exit` message arrives from the server within that window, the loading spinner is replaced with an error message. This prevents the UI from getting permanently stuck if the server fails to respond (e.g., due to a process hang on Windows).
+
+### Usage Dashboard
+
+Polls usage data via the WebSocket `get_usage` message at regular intervals. Displays:
+- Session timer (elapsed/remaining in the current session window)
+- Token consumption (input, output, cache)
+- Cost tracking
+- Burn rate and depletion predictions
+- Plan information
+
+### Authenticated Fetch
+
+`authFetch(url, options)` wraps `fetch()` to automatically include auth headers:
+```js
+const authHeaders = window.authManager.getAuthHeaders();
+const mergedOptions = {
+  ...options,
+  headers: { ...authHeaders, ...(options.headers || {}) }
+};
+return fetch(url, mergedOptions);
+```
+
+---
+
+## SessionTabManager
+
+Source: `src/public/session-manager.js` (~1125 lines)
+
+Manages the browser-style tab bar for multi-session support.
+
+### State
+
+| Property | Type | Description |
+|----------|------|-------------|
+| `tabs` | `Map<sessionId, HTMLElement>` | Tab DOM elements |
+| `activeSessions` | `Map<sessionId, SessionData>` | Session metadata |
+| `activeTabId` | string | Currently active tab's session ID |
+| `tabOrder` | Array | Visual ordering of tab IDs |
+| `tabHistory` | Array | Most-recently-used ordering (max 50 entries) |
+| `notificationsEnabled` | boolean | Whether desktop notifications are permitted |
+
+### Tab Operations
+
+| Operation | Trigger |
+|-----------|---------|
+| Create | "New Tab" button, Ctrl/Cmd+T |
+| Close | Close button, Ctrl/Cmd+W, middle-click |
+| Switch | Tab click, Ctrl/Cmd+Tab (next), Ctrl/Cmd+Shift+Tab (prev), Alt+1-9 |
+| Rename | Double-click tab |
+| Reorder | Drag and drop |
+| Close Others | Right-click context menu |
+
+### Tab Display Name Resolution
+
+1. If the session name is customized (does not start with "Session " containing ":"), use it.
+2. Otherwise, extract the last path component of `workingDir` as the folder name.
+3. Fall back to the default session name.
+
+### Drag and Drop
+
+Tabs are `draggable="true"`. Reordering uses these events:
+- `dragstart` -- stores the session ID and adds a `.dragging` class.
+- `dragover` -- calculates insertion point via `getDragAfterElement()` (finds the closest tab element based on mouse X position).
+- `dragend` -- syncs the visual order to `tabOrder` and updates overflow menus.
+
+### Mobile Behavior
+
+On viewports <= 768px wide:
+- Only the first 2 tabs are visible.
+- An overflow dropdown shows remaining tabs with a count badge.
+- Tabs are automatically reordered by `lastAccessed` timestamp so the most recently used tabs are always visible.
+
+### Status Indicators
+
+Each tab has a status dot with states:
+- **idle** -- default, no activity
+- **active** -- agent is producing output (adds `.pulse` animation)
+- **error** -- an error occurred in the session
+- **unread** -- output completed in a background tab (blue indicator)
+
+### Unread Detection
+
+When a session transitions from `active` to `idle` in a background tab (not the currently viewed tab), it is marked as unread. This happens via two mechanisms:
+
+1. **Work completion timeout (90s):** If no new output arrives for 90 seconds while the status was `active`, the tab is marked as unread and a notification is sent.
+2. **Command completion patterns:** Output is checked against regex patterns for common completion indicators:
+   - `build successful`, `compilation finished`, `tests passed`
+   - `deployment complete`, `npm install completed`
+   - `successfully compiled`, `Done in X.Xs`
+
+### Desktop Notifications
+
+- Requests permission on first load (deferred by 2 seconds).
+- Shows a prompt banner if permission is `"default"`.
+- Sends `Notification` when the page is not visible and the event is for a background tab.
+- Falls back to in-page toast notifications + vibration on mobile.
+- Notifications auto-close after 5 seconds.
+- Clicking a notification switches to the relevant tab and focuses the window.
+
+### Keyboard Shortcuts
+
+| Shortcut | Action |
+|----------|--------|
+| Ctrl/Cmd + T | New tab |
+| Ctrl/Cmd + W | Close current tab |
+| Ctrl/Cmd + Tab | Next tab (uses MRU history first, falls back to visual order) |
+| Ctrl/Cmd + Shift + Tab | Previous tab (visual order) |
+| Alt + 1-9 | Switch to tab by index |
+
+---
+
+## PlanDetector
+
+Source: `src/public/plan-detector.js` (~186 lines)
+
+Monitors terminal output for plan mode activation and plan content.
+
+### Detection Markers
+
+**Plan mode start indicators:**
+- `"Plan mode is active"`
+- `"you MUST NOT make any edits"`
+- `"present your plan by calling the ExitPlanMode tool"`
+- `"Starting plan mode"`
+
+**Completed plan patterns:**
+- `## Implementation Plan:`
+- `### <number>. ` (numbered sections)
+- `## Plan:`
+- `### Plan Overview`
+- `## Proposed Solution:`
+
+**Plan mode end indicators:**
+- `"User has approved your plan"`
+- `"You can now start coding"`
+- `"Plan mode exited"`
+- `"Exiting plan mode"`
+
+### Processing Flow
+
+1. Raw output is appended to an internal buffer (max 10,000 entries, trimmed to 5,000).
+2. Recent text is extracted with ANSI codes stripped.
+3. Checks are performed in order: plan start, completed plan content, plan end.
+4. Callbacks `onPlanModeChange(isActive)` and `onPlanDetected(plan)` fire on state changes.
+
+### Plan Extraction
+
+Three strategies are attempted in order:
+1. Match `## Implementation Plan:` to a terminal prompt indicator.
+2. Match a structured plan header with 2+ `###` subsections.
+3. Match any plan-like content in the last 5,000 characters.
+
+The extracted plan text is cleaned of ANSI codes and normalized line endings.
+
+---
+
+## AuthManager (Client)
+
+Source: `src/public/auth.js` (~245 lines)
+
+See the [Authentication Specification](authentication.md) for full details. Key points:
+
+- Global singleton at `window.authManager`.
+- Token persisted in `sessionStorage` (per-tab, cleared on browser close).
+- Full-screen login overlay with password input.
+- `getAuthHeaders()` returns `{ Authorization: "Bearer <token>" }`.
+- `getWebSocketUrl(baseUrl)` appends `?token=<token>` to WebSocket URLs.
+
+---
+
+## PWA Support
+
+### Service Worker
+
+Source: `src/public/service-worker.js`
+
+- **Cache name:** `claude-code-web-v1`
+- **Precached resources:** `/`, `/index.html`, `/style.css`, `/app.js`, `/session-manager.js`, `/plan-detector.js`
+- **Strategy for API/WebSocket routes:** Network only, with a 503 offline fallback.
+- **Strategy for static assets:** Network first, cache on success, fall back to cache when offline.
+- Activates immediately via `skipWaiting()` + `clients.claim()`.
+- Cleans up old caches on activation.
+
+### Manifest
+
+Source: `src/public/manifest.json`
+
+Provides installable PWA metadata. Icons are dynamically generated SVGs served by the Express server at `/icon-{size}.png`.
+
+### Dynamic Icon Generation
+
+The server generates SVG icons at sizes 16, 32, 144, 180, 192, and 512 pixels:
+- Dark background (`#1a1a1a`) with rounded corners.
+- Monospace "CC" text in orange (`#ff6b00`).
+- Served as `image/svg+xml` with a 1-year `Cache-Control`.