clawtap/docs/superpowers/specs/2026-03-24-session-id-unification-design.md

# Session ID Unification — CLI UUID as Single Source of Truth

## Problem

The codebase has two session ID systems that create bugs and complexity:

1. **Internal ID** (format `claude-1774300056705` / `codex-1774300056705`): tmux window name, in-memory Map key, DB primary key
2. **CLI UUID** (format `d6d56787-bfaf-4312-ae4d-99683ba45459`): permanent ID from the CLI tool, JSONL filename

These require constant translation via `resolveSessionId()` and `cliToSessionId` Maps. When translation fails:

- Mobile can not receive desktop events (registered under CLI UUID, events broadcast under internal ID)
- handleReconnect creates unwanted tmux windows (lost hasActiveWindow guard)
- SessionsView passes different ID types (project list = CLI UUID, active list = internal ID)
- Latent bug: `_registerCliUUID()` references renamed column `claude_session` (should be `cli_session`)

## Solution

Eliminate internal ID as a session identifier. Use CLI UUID everywhere. Internal ID becomes just a tmux window display name with no programmatic significance.

## Design

### Layer 1: Adapter Internals

**Files:** `server/adapters/claude/tmux-adapter.ts`, `server/adapters/codex/codex-tmux-adapter.ts`, `server/adapters/codex/pane-monitor.ts`, `server/adapters/interface.ts`

**`this.sessions` Map key**: internal ID changes to CLI UUID.

**Eliminated entirely:**
- `cliToSessionId: Map<string, string>` -- no translation needed
- `resolveSessionId()` method -- no translation needed
- `_registerCliUUID()` -- no mapping to maintain (also fixes `claude_session` column bug)
- `_remapCliSession()` -- no remapping needed
- `_removeCliMapping()` -- no mapping to clean up

**`startSession()` returns CLI UUID.** The tmux window name remains `{adapter}-{timestamp}` for tmux display but is not used as an identifier.

**`resumeSession()` / `attachSession()`** take CLI UUID as parameter.

**All event emits** use CLI UUID as first argument.

**`getActiveSessions()`** returns CLI UUID as `sessionId`. The `cliSessionId` field kept for compatibility (same value).

**`_findWindowForSession()`** looks up `window_id` from DB by CLI UUID instead of matching tmux window names.

**`handleSessionStart()` pattern matching**: `w.name.startsWith('claude-')` still works because tmux window names retain the `{adapter}-{timestamp}` format.

**Codex `startSession()` UUID timing**: Codex CLI generates its own UUID (arrives via SessionStart hook or JSONL filename). Add `_waitForCliUUID()` that waits for `session.cliSessionId` to be populated (max 15 seconds). Session initially stored under a temporary key (the window name), re-keyed once UUID is known.

During the temp-key window:
- Hooks arriving from CLI use the `_watcherPending` scanning pattern (already exists) to find the session
- Events are emitted under the temp key (few clients would be registered under it yet)
- Once UUID arrives: session is re-keyed in the Map, DB is upserted, `sessionAdapterMap` updated

If `_waitForCliUUID` times out:
- Kill the tmux window (`tmuxManager.killWindow`)
- Remove the temp session from the Map
- Throw error (propagates to client as WS error message)

**Codex `CodexPaneMonitor`**: stores `sessionId` for event emission -- changes from internal ID to CLI UUID.

### Layer 2: DB Schema

**Files:** `server/db.ts`

**`sessions` table migration:**

Before:
- `id` (PRIMARY KEY) = internal ID
- `cli_session` = CLI UUID

After:
- `id` (PRIMARY KEY) = CLI UUID
- `cli_session` column removed
- `window_name` column added (stores old internal ID for tmux display/debug)

**`SessionRow` interface:**

```typescript
export interface SessionRow {
  id: string;                    // CLI UUID (was internal ID)
  cwd: string;
  window_id: string | null;      // tmux window ID (@N)
  window_name: string | null;    // tmux window name for debug
  adapter: string;
  permission_mode: string;
  created_at: string;
  last_activity: string;
}
```

**Prepared statements:**
- `sessionsUpsert(id=cliUUID, cwd, windowId, windowName, adapter)` -- `id` is CLI UUID
- `sessionsFindByCliSession` -- REMOVED (use primary key lookup)
- `sessionsFindByWindowId` -- unchanged
- `sessionsRemove(id)` -- `id` is now CLI UUID
- Add `sessionsGet(id)` -- simple primary key lookup

**`session_reviews` table**: No changes (already uses CLI UUIDs).

**`session_stats` table**: Verify `session_id` uses CLI UUID. Migrate if needed.

**Migration SQL** (SQLite table rebuild pattern):

```sql
-- Step 1: Create new table with new schema
CREATE TABLE IF NOT EXISTS sessions_new (
  id TEXT PRIMARY KEY,
  cwd TEXT NOT NULL,
  window_id TEXT,
  window_name TEXT,
  adapter TEXT DEFAULT 'claude',
  permission_mode TEXT DEFAULT 'default',
  created_at TEXT DEFAULT (datetime('now')),
  last_activity TEXT DEFAULT (datetime('now'))
);

-- Step 2: Copy data, swapping id and cli_session
-- Skip rows where cli_session is empty, equals the internal ID, or matches {adapter}-{timestamp} pattern
INSERT OR IGNORE INTO sessions_new (id, cwd, window_id, window_name, adapter, permission_mode, created_at, last_activity)
SELECT
  CASE
    WHEN cli_session IS NOT NULL AND cli_session != '' AND cli_session != id THEN cli_session
    ELSE id
  END,
  cwd, window_id, id, adapter, permission_mode, created_at, last_activity
FROM sessions;

-- Step 3: Drop old table and rename
DROP TABLE sessions;
ALTER TABLE sessions_new RENAME TO sessions;

-- Step 4: Recreate indexes
CREATE INDEX IF NOT EXISTS idx_sessions_window ON sessions(window_id);
```

Migration is wrapped in a transaction and runs inside `initDB()` before any adapter initialization. Detection: check if the old `cli_session` column exists (`PRAGMA table_info(sessions)`).

**Handling rows where `cli_session` = internal ID**: Some Codex sessions store the internal ID as both `id` and `cli_session` (when UUID wasn't yet known). The migration uses `CASE WHEN cli_session != id THEN cli_session ELSE id END` — these rows keep their internal ID as `id`. They will be orphaned (no JSONL match) and cleaned up naturally by `clearAll()` on next shutdown.

**`session_stats` table**: This table exists in the schema but is never written to by any code in the codebase (no INSERT statements found). It can be left as-is or dropped. No migration needed.

### Layer 3: Session Manager

**Files:** `server/session-manager.ts`

**`sessionClients` Map key**: CLI UUID (was internal ID).
**`sessionAdapterMap` Map key**: CLI UUID (was internal ID).

**`broadcast(sessionId, message)`**: `sessionId` is CLI UUID. This is the core fix -- adapter events emitted with CLI UUID now match client registration keys.

**`sendSessionCreated()`**: Sends single `sessionId` (CLI UUID). Remove `cliSessionId` field.

**`handleQuery()`**: No `resolveSessionId` call. `options.sessionId` from client is CLI UUID directly.

**`handleReconnect()`**: Greatly simplified. No `resolveSessionId` needed. All 11 existing steps preserved:

1. ~~Resolve internal ID via resolveSessionId~~ REMOVED (no translation needed)
2. Register client under CLI UUID
3. Clear push pending notifications (keyed by CLI UUID)
4. Send SESSION_CREATED (single ID)
5. Send cached status
6. Resume if not in memory — **with `hasActiveWindow` guard**:
   ```
   if session not in memory:
     if tmux window exists: resumeSession (attach to monitor events)
     else: do nothing (just load history from JSONL)
   ```
7. Sync watcher position
8. Load JSONL history (`adapter.getMessages(sessionId)` — CLI UUID directly, no cliSessionId extraction needed)
9. Send streaming state (SESSION_STATE)
10. Replay pending tools and permissions
11. Restore active child reviews (`sessionReviews.getActiveForParent(sessionId)` — CLI UUID directly)

Key simplification in step 11: no longer needs `findByCliSession` to look up parent CWD for child session resume — can use `sessions.get(sessionId)` primary key lookup directly (since `id` is now CLI UUID).

**`triggerPush()`**: Simplified — `sessionId` IS CLI UUID, so child review check uses `sessionId` directly (no need to look up `sessionObj.cliSessionId`). Single `getSession()` call replaces the current two calls with different casts. Uses CLI UUID for sessionClients lookup, push pending, and push payload.

**`session-ended` handler**: `sessionId` parameter IS CLI UUID. The entire convoluted lookup (`findByWindowId` fallback + `getAll().find()`) to extract `cli_session` is eliminated — `sessionId` is already the CLI UUID. Cascade cleanup calls `sessionReviews.getActiveForParent(sessionId)` directly. `sessionClients.delete` and `sessionAdapterMap.delete` remain synchronous (before any async cascade work).

**`server/index.ts` active sessions endpoint**: The dual lookup `getClientCount(s.sessionId) || getClientCount(s.cliSessionId)` simplifies to `getClientCount(s.sessionId)` since both are the same CLI UUID.

**`broadcastReviewStarted/Ended`**: `parentSessionId` is CLI UUID.

### Layer 4: Frontend

**Files:** `src/hooks/useChat.ts`, `src/lib/ws.ts`, `src/components/ChatView.tsx`, `src/components/SessionsView.tsx`, `src/components/FloatingReviewPanel.tsx`, `src/lib/api.ts`

**`useChat.ts`**: Merge `sessionId` and `cliSessionId` states into single `sessionId` (always CLI UUID). `SESSION_CREATED` handler sets one state. All outgoing WS messages (QUERY, ABORT, RECONNECT, SET_MODEL, SET_PERMISSION_MODE, PLAN_RESPONSE) send this single `sessionId`.

**`ws.ts`**: `activeSessionId` stores CLI UUID from `SESSION_CREATED`.

**`ChatView.tsx`**: Header shows single `sessionId` (CLI UUID). Review API calls use `sessionId` directly. Remove `cliSessionId` from ChatHeader props.

**`SessionsView.tsx`**: Both session lists (project + active) now use CLI UUID for `session.sessionId`. `onOpenChat(session.sessionId)` is consistent. `destroySession(session.sessionId)` passes CLI UUID. Push pending lookup `pending[session.sessionId]` uses CLI UUID.

**`FloatingReviewPanel.tsx`**: `childSessionId` prop is CLI UUID.

**`ActiveSessionInfo` interface**: `sessionId` becomes CLI UUID. `cliSessionId` kept as deprecated alias (same value).

### Layer 5: Push Notifications + Permissions

**Files:** `server/push.ts`, `server/permission-manager.ts`, `src/sw.ts`, `src/App.tsx`

**`push.ts`**: `pendingSessions` Map keyed by CLI UUID.

**`permission-manager.ts`**: `PendingPermission.sessionId` is CLI UUID. `sessionPendingIds` Map keyed by CLI UUID.

**`sw.ts`**: Push payload `sessionId` is CLI UUID. Notification click URL `/?session=${cliUUID}`.

**`App.tsx`**: URL parameter `?session=` is CLI UUID. Service worker `OPEN_SESSION` message carries CLI UUID.

### Layer 6: CLI (`bin/codetap`)

**File:** `bin/codetap`

DB queries updated to use new schema (no `cli_session` column, `id` is CLI UUID):

- Line 239 `get_project_sessions()`: Change `SELECT id FROM sessions` to `SELECT window_name FROM sessions` — the function returns IDs to match against tmux window names, which are `{adapter}-{timestamp}` format (stored in `window_name`, not `id`)
- Line 290: Change `SELECT id, adapter, cli_session, cwd` to `SELECT id, adapter, window_name, cwd` — display CLI UUID as `id`, use `window_name` for tmux matching
- Line 260: Match tmux window names against `window_name` column (not `id`)
- Line 382 `--resume`: Simplified to `WHERE id='${SAFE_ID}'` since `id` is now CLI UUID
- Window name generation unchanged (`{adapter}-{timestamp}`)

**Critical**: The `-a` listing mode joins tmux window names against DB session IDs. After migration, this join key changes from `id` to `window_name`. The `IN (...)` SQL clause must query `window_name` column.

## Codex UUID Discovery Flow

```
1. handleQuery() -> adapter.startSession(cwd, options)
2. Codex startSession():
   a. Generate window name "codex-{timestamp}"
   b. Create tmux window
   c. Wait for CLI ready (_waitForReady)
   d. Start _watchForTranscript() (sets up FSWatcher)
   e. NEW: _waitForCliUUID() -- wait for session.cliSessionId to be populated
      - Source 1: handleSessionStart hook fires with session_id
      - Source 2: _watchForTranscript detects JSONL file, extracts UUID from filename
   f. Once UUID known: set as Map key, upsert DB
   g. Return { sessionId: cliUUID }
3. handleQuery() continues with cliUUID
4. registerClient, sendSessionCreated, sendMessage -- all use cliUUID
```

Timeout: 15 seconds. If UUID not discovered, startSession fails with error.

## Files Affected (Complete List)

| File | Change Type | Summary |
|------|------------|---------|
| `server/db.ts` | MODIFY | Schema migration, remove cli_session, add window_name, update SessionRow |
| `server/session-manager.ts` | MODIFY | All Map keys to CLI UUID, simplify handleReconnect, fix triggerPush |
| `server/adapters/claude/tmux-adapter.ts` | MODIFY | sessions Map key, eliminate cliToSessionId/resolveSessionId, events use CLI UUID |
| `server/adapters/codex/codex-tmux-adapter.ts` | MODIFY | Same as Claude adapter, add _waitForCliUUID |
| `server/adapters/codex/pane-monitor.ts` | MODIFY | sessionId is CLI UUID |
| `server/adapters/interface.ts` | MODIFY | Remove resolveSessionId, update ActiveSessionInfo |
| `server/adapters/claude/index.ts` | MODIFY | Remove resolveSessionId delegation |
| `server/adapters/codex/index.ts` | MODIFY | Remove resolveSessionId delegation |
| `server/push.ts` | MODIFY | pendingSessions keyed by CLI UUID |
| `server/permission-manager.ts` | MODIFY | All session indices use CLI UUID |
| `server/transport/client-connection.ts` | NO CHANGE | sessionId field semantics change (now CLI UUID) |
| `server/index.ts` | MODIFY | Remove dual-ID lookups in active-sessions, simplify review endpoints |
| `server/types/messages.ts` | MODIFY | QueryOptions.sessionId is CLI UUID |
| `server/types/adapter.ts` | MODIFY | SessionInfo.sessionId is CLI UUID (already was) |
| `server/ws-types.ts` | NO CHANGE | Just message type constants |
| `src/hooks/useChat.ts` | MODIFY | Merge sessionId + cliSessionId into one |
| `src/lib/ws.ts` | MODIFY | activeSessionId stores CLI UUID |
| `src/lib/api.ts` | MODIFY | destroySession passes CLI UUID |
| `src/components/ChatView.tsx` | MODIFY | Single ID in header, remove cliSessionId usage |
| `src/components/SessionsView.tsx` | MODIFY | Consistent CLI UUID for both lists |
| `src/components/FloatingReviewPanel.tsx` | MODIFY | childSessionId is CLI UUID |
| `src/sw.ts` | MODIFY | Push sessionId is CLI UUID |
| `src/App.tsx` | MODIFY | URL param and SW message use CLI UUID |
| `bin/codetap` | MODIFY | DB queries use new schema |
| `server/adapters/claude/jsonl-store.ts` | NO CHANGE | Already uses CLI UUID |
| `server/adapters/codex/jsonl-store.ts` | NO CHANGE | Already uses CLI UUID |
| `server/adapters/claude/pane-monitor.ts` | NO CHANGE | Uses windowId (tmux ID), not session ID |
| `server/adapters/claude/hook-config.ts` | NO CHANGE | No session IDs |
| `server/adapters/codex/hook-config.ts` | NO CHANGE | No session IDs |
| `server/adapters/registry.ts` | NO CHANGE | No session IDs |
| `server/config.ts` | NO CHANGE | No session IDs |
| `server/stores/jsonl-watcher.ts` | NO CHANGE | File path based |
| `src/hooks/useSessions.ts` | MODIFY | `s.cliSessionId` for green dots → `s.sessionId` (same value after unification) |
| `tests/e2e-spec.feature` | MODIFY | Remove references to `resolveSessionId`, `cliSessionId` dual-ID |

## What This Fixes

1. Mobile receives desktop events in real-time (same broadcast key)
2. handleReconnect does not create unwanted tmux windows (hasActiveWindow guard)
3. SessionsView uses consistent IDs (both lists pass CLI UUID)
4. No more resolveSessionId translation failures
5. Fixes _registerCliUUID bug (references renamed column)
6. Eliminates ~200 lines of translation/mapping code
7. Push notifications navigate to correct session
8. Active session client count lookup simplified (no dual-ID check)

## Scope Boundaries

NOT included in this refactor:
- Changing tmux window names (they remain `{adapter}-{timestamp}` for display)
- Changing JSONL file paths (already CLI UUID based)
- Changing the Cross-AI Review feature (already uses CLI UUIDs)
- Auto N-round debate or other deferred features