@myrialabs/clopen 0.1.8 → 0.1.10

package/backend/lib/snapshot/snapshot-service.ts

@@ -285,47 +285,18 @@ export class SnapshotService {
 	 */
 	async checkRestoreConflicts(
 		sessionId: string,
-		targetCheckpointMessageId: string,
-		projectPath?: string
+		targetCheckpointMessageId: string | null,
+		projectPath?: string,
+		targetPath?: string[]
 	): Promise<RestoreConflictCheck> {
 		const sessionSnapshots = snapshotQueries.getBySessionId(sessionId);
+		const isInitialRestore = targetCheckpointMessageId === null;
 
-		const targetIndex = sessionSnapshots.findIndex(
-			s => s.message_id === targetCheckpointMessageId
+		// Build expected state at target (branch-aware when targetPath is provided)
+		const expectedState = this.buildExpectedState(
+			sessionSnapshots, targetCheckpointMessageId, targetPath
 		);
 
-		if (targetIndex === -1) {
-			return { hasConflicts: false, conflicts: [], checkpointsToUndo: [] };
-		}
-
-		// Build expected state at target (same bidirectional algorithm as restoreSessionScoped)
-		// This determines ALL files that would be affected by the restore
-		const expectedState = new Map<string, string>(); // filepath → expectedHash
-
-		for (let i = 0; i <= targetIndex; i++) {
-			const snap = sessionSnapshots[i];
-			if (!snap.session_changes) continue;
-			try {
-				const changes = JSON.parse(snap.session_changes) as SessionScopedChanges;
-				for (const [filepath, change] of Object.entries(changes)) {
-					expectedState.set(filepath, change.newHash);
-				}
-			} catch { /* skip malformed */ }
-		}
-
-		for (let i = targetIndex + 1; i < sessionSnapshots.length; i++) {
-			const snap = sessionSnapshots[i];
-			if (!snap.session_changes) continue;
-			try {
-				const changes = JSON.parse(snap.session_changes) as SessionScopedChanges;
-				for (const [filepath, change] of Object.entries(changes)) {
-					if (!expectedState.has(filepath)) {
-						expectedState.set(filepath, change.oldHash);
-					}
-				}
-			} catch { /* skip malformed */ }
-		}
-
 		if (expectedState.size === 0) {
 			return { hasConflicts: false, conflicts: [], checkpointsToUndo: [] };
 		}
@@ -354,8 +325,13 @@ export class SnapshotService {
 
 		// Determine reference time for cross-session conflict check
 		// Use min(targetTime, currentHeadTime) to cover both undo and redo
-		const targetSnapshot = sessionSnapshots[targetIndex];
-		const targetTime = targetSnapshot.created_at;
+		// For initial restore, use the session's created_at or the earliest snapshot time
+		const targetSnapshot = isInitialRestore
+			? null
+			: sessionSnapshots.find(s => s.message_id === targetCheckpointMessageId) || null;
+		const targetTime = targetSnapshot
+			? targetSnapshot.created_at
+			: (sessionSnapshots[0]?.created_at || new Date(0).toISOString());
 		let referenceTime = targetTime;
 
 		const currentHead = sessionQueries.getHead(sessionId);
@@ -384,7 +360,9 @@ export class SnapshotService {
 
 		// Check for cross-session conflicts
 		const conflicts: RestoreConflict[] = [];
-		const projectId = targetSnapshot.project_id;
+		const projectId = targetSnapshot
+			? targetSnapshot.project_id
+			: (sessionSnapshots[0]?.project_id || '');
 		const allProjectSnapshots = this.getAllProjectSnapshots(projectId);
 
 		for (const otherSnap of allProjectSnapshots) {
@@ -472,60 +450,29 @@ export class SnapshotService {
 	 * Restore to a checkpoint using session-scoped changes.
 	 * Works in both directions (forward and backward).
 	 *
-	 * Algorithm:
-	 * 1. Walk snapshots [0..targetIndex] → build expected file state at target
-	 * 2. Walk snapshots [targetIndex+1..end] → files changed only after target need reverting
-	 * 3. For each file in the expected state map, compare with current disk and restore if different
+	 * When targetPath is provided, uses branch-aware algorithm:
+	 * 1. Only apply changes from snapshots on the path (root → target)
+	 * 2. Revert ALL changes from snapshots on other branches
+	 * 3. Compare expected state with disk and restore if different
 	 * 4. Update in-memory baseline to match restored state
+	 *
+	 * Falls back to linear algorithm when targetPath is not provided.
 	 */
 	async restoreSessionScoped(
 		projectPath: string,
 		sessionId: string,
-		targetCheckpointMessageId: string,
-		conflictResolutions?: ConflictResolution
+		targetCheckpointMessageId: string | null,
+		conflictResolutions?: ConflictResolution,
+		targetPath?: string[]
 	): Promise<{ restoredFiles: number; skippedFiles: number }> {
 		try {
 			const sessionSnapshots = snapshotQueries.getBySessionId(sessionId);
 
-			const targetIndex = sessionSnapshots.findIndex(
-				s => s.message_id === targetCheckpointMessageId
-			);
-
-			if (targetIndex === -1) {
-				debug.warn('snapshot', 'Target checkpoint snapshot not found');
-				return { restoredFiles: 0, skippedFiles: 0 };
-			}
-
 			// Build expected file state at the target checkpoint
-			// filepath → hash that the file should be at the target
-			const expectedState = new Map<string, string>();
-
-			// Walk snapshots from first to target (inclusive): apply forward changes
-			for (let i = 0; i <= targetIndex; i++) {
-				const snap = sessionSnapshots[i];
-				if (!snap.session_changes) continue;
-				try {
-					const changes = JSON.parse(snap.session_changes) as SessionScopedChanges;
-					for (const [filepath, change] of Object.entries(changes)) {
-						expectedState.set(filepath, change.newHash);
-					}
-				} catch { /* skip */ }
-			}
-
-			// Walk snapshots after target: files changed only after target need reverting to oldHash
-			for (let i = targetIndex + 1; i < sessionSnapshots.length; i++) {
-				const snap = sessionSnapshots[i];
-				if (!snap.session_changes) continue;
-				try {
-					const changes = JSON.parse(snap.session_changes) as SessionScopedChanges;
-					for (const [filepath, change] of Object.entries(changes)) {
-						if (!expectedState.has(filepath)) {
-							// File was first changed AFTER target → revert to pre-change state
-							expectedState.set(filepath, change.oldHash);
-						}
-					}
-				} catch { /* skip */ }
-			}
+			// Branch-aware when targetPath is provided
+			const expectedState = this.buildExpectedState(
+				sessionSnapshots, targetCheckpointMessageId, targetPath
+			);
 
 			debug.log('snapshot', `Restore to checkpoint: ${expectedState.size} files in expected state`);
 
@@ -600,6 +547,124 @@ export class SnapshotService {
 	// Helpers
 	// ========================================================================
 
+	/**
+	 * Build the expected file state map for a restore operation.
+	 *
+	 * Branch-aware algorithm (when targetPath is provided):
+	 * 1. Separate snapshots into path (root→target) vs non-path
+	 * 2. Forward walk: only apply newHash from snapshots on the path (in path order)
+	 * 3. Revert walk: revert ALL non-path snapshots using oldHash (first-wins)
+	 *
+	 * This correctly handles multi-branch checkpoint trees by NOT including
+	 * changes from other branches in the forward walk.
+	 *
+	 * Fallback linear algorithm (when targetPath is not provided):
+	 * Walks all snapshots chronologically — only correct for single-branch paths.
+	 */
+	private buildExpectedState(
+		sessionSnapshots: MessageSnapshot[],
+		targetCheckpointMessageId: string | null,
+		targetPath?: string[]
+	): Map<string, string> {
+		const expectedState = new Map<string, string>();
+		const isInitialRestore = targetCheckpointMessageId === null;
+
+		if (isInitialRestore) {
+			// Revert ALL snapshots → everything goes back to oldHash (first-wins)
+			for (const snap of sessionSnapshots) {
+				if (!snap.session_changes) continue;
+				try {
+					const changes = JSON.parse(snap.session_changes as string) as SessionScopedChanges;
+					for (const [filepath, change] of Object.entries(changes)) {
+						if (!expectedState.has(filepath)) {
+							expectedState.set(filepath, change.oldHash);
+						}
+					}
+				} catch { /* skip malformed */ }
+			}
+		} else if (targetPath && targetPath.length > 0) {
+			// Branch-aware restore: only include snapshots on the path from root to target
+			const pathSet = new Set(targetPath);
+
+			// Separate snapshots into path vs non-path
+			const snapshotByMsgId = new Map<string, MessageSnapshot>();
+			const nonPathSnapshots: MessageSnapshot[] = [];
+
+			for (const snap of sessionSnapshots) {
+				if (pathSet.has(snap.message_id)) {
+					snapshotByMsgId.set(snap.message_id, snap);
+				} else {
+					nonPathSnapshots.push(snap);
+				}
+			}
+
+			// Forward walk: apply path snapshots in path order (root → target)
+			// Later path snapshots overwrite earlier ones for the same file (correct)
+			for (const cpId of targetPath) {
+				const snap = snapshotByMsgId.get(cpId);
+				if (!snap?.session_changes) continue;
+				try {
+					const changes = JSON.parse(snap.session_changes as string) as SessionScopedChanges;
+					for (const [filepath, change] of Object.entries(changes)) {
+						expectedState.set(filepath, change.newHash);
+					}
+				} catch { /* skip malformed */ }
+			}
+
+			// Revert all non-path snapshots (changes on other branches)
+			// Process in chronological order with first-wins semantics:
+			// if two non-path snapshots change the same file, the earliest one's
+			// oldHash is used (state before any branch diverged)
+			for (const snap of nonPathSnapshots) {
+				if (!snap.session_changes) continue;
+				try {
+					const changes = JSON.parse(snap.session_changes as string) as SessionScopedChanges;
+					for (const [filepath, change] of Object.entries(changes)) {
+						if (!expectedState.has(filepath)) {
+							expectedState.set(filepath, change.oldHash);
+						}
+					}
+				} catch { /* skip malformed */ }
+			}
+		} else {
+			// Fallback: linear algorithm (no path info available)
+			const targetIndex = sessionSnapshots.findIndex(
+				s => s.message_id === targetCheckpointMessageId
+			);
+
+			if (targetIndex === -1) {
+				debug.warn('snapshot', 'Target checkpoint snapshot not found (linear fallback)');
+				return expectedState;
+			}
+
+			for (let i = 0; i <= targetIndex; i++) {
+				const snap = sessionSnapshots[i];
+				if (!snap.session_changes) continue;
+				try {
+					const changes = JSON.parse(snap.session_changes as string) as SessionScopedChanges;
+					for (const [filepath, change] of Object.entries(changes)) {
+						expectedState.set(filepath, change.newHash);
+					}
+				} catch { /* skip malformed */ }
+			}
+
+			for (let i = targetIndex + 1; i < sessionSnapshots.length; i++) {
+				const snap = sessionSnapshots[i];
+				if (!snap.session_changes) continue;
+				try {
+					const changes = JSON.parse(snap.session_changes as string) as SessionScopedChanges;
+					for (const [filepath, change] of Object.entries(changes)) {
+						if (!expectedState.has(filepath)) {
+							expectedState.set(filepath, change.oldHash);
+						}
+					}
+				} catch { /* skip malformed */ }
+			}
+		}
+
+		return expectedState;
+	}
+
 	/**
 	 * Calculate line-level change stats for changed files.
 	 */

package/backend/ws/chat/stream.ts

@@ -49,6 +49,14 @@ streamManager.on('stream:lifecycle', (event: { status: string; streamId: string;
 	broadcastPresence().catch(() => {});
 });
 
+// Notify project members when a snapshot is captured (so the timeline modal can refresh stats)
+streamManager.on('snapshot:captured', (event: { projectId: string; chatSessionId: string }) => {
+	const { projectId, chatSessionId } = event;
+	if (!projectId) return;
+
+	ws.emit.projectMembers(projectId, 'snapshot:captured', { projectId, chatSessionId });
+});
+
 // In-memory store for latest chat input state per chat session (keyed by chatSessionId)
 const chatSessionInputState = new Map<string, { text: string; senderId: string; attachments?: any[] }>();
 
@@ -789,4 +797,9 @@ export const streamHandler = createRouter()
 		chatSessionId: t.String(),
 		toolUseId: t.String(),
 		timestamp: t.String()
+	}))
+
+	.emit('snapshot:captured', t.Object({
+		projectId: t.String(),
+		chatSessionId: t.String()
 	}));

package/backend/ws/sessions/crud.ts

@@ -33,7 +33,11 @@ export const crudHandler = createRouter()
 				started_at: t.String(),
 				ended_at: t.Optional(t.String())
 			})),
-			currentSessionId: t.Optional(t.String())
+			currentSessionId: t.Optional(t.String()),
+			unreadSessionIds: t.Array(t.Object({
+				sessionId: t.String(),
+				projectId: t.String()
+			}))
 		})
 	}, async ({ conn }) => {
 		const projectId = ws.getProjectId(conn);
@@ -43,6 +47,10 @@ export const crudHandler = createRouter()
 		// Get the user's saved current session for this project
 		const currentSessionId = projectQueries.getCurrentSessionId(userId, projectId);
 
+		// Get unread sessions for this user/project
+		const unreadRows = sessionQueries.getUnreadSessions(userId, projectId);
+		debug.log('session', `[unread] sessions:list — user=${userId}, project=${projectId}, unreadCount=${unreadRows.length}`, unreadRows);
+
 		// Convert null to undefined for TypeScript optional fields
 		return {
 			sessions: sessions.map(session => ({
@@ -54,7 +62,8 @@ export const crudHandler = createRouter()
 				current_head_message_id: session.current_head_message_id ?? undefined,
 				ended_at: session.ended_at ?? undefined
 			})),
-			currentSessionId: currentSessionId ?? undefined
+			currentSessionId: currentSessionId ?? undefined,
+			unreadSessionIds: unreadRows.map(r => ({ sessionId: r.session_id, projectId: r.project_id }))
 		};
 	})
 
@@ -324,4 +333,27 @@ export const crudHandler = createRouter()
 		const userId = ws.getUserId(conn);
 		projectQueries.setCurrentSessionId(userId, projectId, data.sessionId);
 		debug.log('session', `User ${userId} set current session to ${data.sessionId} in project ${projectId}`);
+	})
+
+	// Mark a session as read for the current user
+	.on('sessions:mark-read', {
+		data: t.Object({
+			sessionId: t.String()
+		})
+	}, async ({ data, conn }) => {
+		const userId = ws.getUserId(conn);
+		sessionQueries.markRead(userId, data.sessionId);
+		debug.log('session', `[unread] Marked session ${data.sessionId} as READ for user ${userId}`);
+	})
+
+	// Mark a session as unread for the current user
+	.on('sessions:mark-unread', {
+		data: t.Object({
+			sessionId: t.String(),
+			projectId: t.String()
+		})
+	}, async ({ data, conn }) => {
+		const userId = ws.getUserId(conn);
+		sessionQueries.markUnread(userId, data.sessionId, data.projectId);
+		debug.log('session', `[unread] Marked session ${data.sessionId} as UNREAD for user ${userId} in project ${data.projectId}`);
 	});

package/backend/ws/snapshot/restore.ts

@@ -14,7 +14,9 @@ import { debug } from '$shared/utils/logger';
 import {
 	buildCheckpointTree,
 	getCheckpointPathToRoot,
-	findSessionEnd
+	findCheckpointForHead,
+	findSessionEnd,
+	INITIAL_NODE_ID
 } from '../../lib/snapshot/helpers';
 import { ws } from '$backend/lib/utils/ws';
 
@@ -53,7 +55,31 @@ export const restoreHandler = createRouter()
 			if (project) projectPath = project.path;
 		}
 
-		const result = await snapshotService.checkRestoreConflicts(sessionId, messageId, projectPath);
+		// Build checkpoint path for branch-aware conflict detection
+		let targetPath: string[] | undefined;
+		let resolvedMessageId: string | null = messageId === INITIAL_NODE_ID ? null : messageId;
+
+		if (messageId !== INITIAL_NODE_ID) {
+			const allMessages = messageQueries.getAllBySessionId(sessionId);
+			const { checkpoints, parentMap } = buildCheckpointTree(allMessages);
+			const checkpointIdSet = new Set(checkpoints.map(c => c.id));
+
+			const resolvedId = checkpointIdSet.has(messageId)
+				? messageId
+				: findCheckpointForHead(messageId, allMessages, checkpointIdSet);
+
+			if (resolvedId) {
+				resolvedMessageId = resolvedId;
+				targetPath = getCheckpointPathToRoot(resolvedId, parentMap);
+			}
+		}
+
+		const result = await snapshotService.checkRestoreConflicts(
+			sessionId,
+			resolvedMessageId,
+			projectPath,
+			targetPath
+		);
 
 		debug.log('snapshot', `Conflict check: ${result.conflicts.length} conflicts, ${result.checkpointsToUndo.length} checkpoints to undo`);
 
@@ -82,12 +108,67 @@ export const restoreHandler = createRouter()
 		})
 	}, async ({ data }) => {
 		const { messageId, sessionId, conflictResolutions } = data;
+		const isInitialRestore = messageId === INITIAL_NODE_ID;
 
-		debug.log('snapshot', 'RESTORE - Moving HEAD to checkpoint');
-		debug.log('snapshot', `Target checkpoint: ${messageId}`);
+		debug.log('snapshot', `RESTORE - ${isInitialRestore ? 'Restoring to initial state' : 'Moving HEAD to checkpoint'}`);
+		debug.log('snapshot', `Target: ${messageId}`);
 		debug.log('snapshot', `Session: ${sessionId}`);
 
-		// 1. Get the checkpoint message
+		// Handle restore to initial state (before any messages)
+		if (isInitialRestore) {
+			// Clear HEAD (no messages active)
+			sessionQueries.clearHead(sessionId);
+			debug.log('snapshot', 'HEAD cleared (initial state)');
+
+			// Clear latest_sdk_session_id so next chat starts fresh
+			const db = (await import('../../lib/database')).getDatabase();
+			db.prepare(`UPDATE chat_sessions SET latest_sdk_session_id = NULL WHERE id = ?`).run(sessionId);
+
+			// Clear checkpoint_tree_state
+			checkpointQueries.deleteForSession(sessionId);
+
+			// Restore file system: revert ALL session changes
+			let filesRestored = 0;
+			let filesSkipped = 0;
+
+			const session = sessionQueries.getById(sessionId);
+			if (session) {
+				const project = projectQueries.getById(session.project_id);
+				if (project) {
+					const result = await snapshotService.restoreSessionScoped(
+						project.path,
+						sessionId,
+						null, // null = restore to initial (before all snapshots)
+						conflictResolutions
+					);
+					filesRestored = result.restoredFiles;
+					filesSkipped = result.skippedFiles;
+				}
+			}
+
+			// Broadcast messages-changed
+			try {
+				ws.emit.chatSession(sessionId, 'chat:messages-changed', {
+					sessionId,
+					reason: 'restore',
+					timestamp: new Date().toISOString()
+				});
+			} catch (err) {
+				debug.error('snapshot', 'Failed to broadcast messages-changed:', err);
+			}
+
+			return {
+				restoredTo: {
+					messageId: INITIAL_NODE_ID,
+					timestamp: new Date().toISOString()
+				},
+				filesRestored,
+				filesSkipped
+			};
+		}
+
+		// Regular checkpoint restore
+		// 1. Get the target message
 		const checkpointMessage = messageQueries.getById(messageId);
 		if (!checkpointMessage) {
 			throw new Error('Checkpoint message not found');
@@ -99,9 +180,19 @@ export const restoreHandler = createRouter()
 
 		// 3. Get all messages and build checkpoint tree
 		const allMessages = messageQueries.getAllBySessionId(sessionId);
-		const { parentMap } = buildCheckpointTree(allMessages);
+		const { checkpoints, parentMap } = buildCheckpointTree(allMessages);
+
+		// 3b. Resolve the correct checkpoint for snapshot/tree operations
+		// The target message may be a non-checkpoint (e.g., assistant response)
+		// when called from edit mode. Walk back to find the nearest ancestor checkpoint.
+		const checkpointIdSet = new Set(checkpoints.map(c => c.id));
+		const resolvedCheckpointId = checkpointIdSet.has(messageId)
+			? messageId
+			: findCheckpointForHead(messageId, allMessages, checkpointIdSet);
 
-		// 4. Find session end (last message of checkpoint's session)
+		debug.log('snapshot', `Resolved checkpoint: ${resolvedCheckpointId} (target was ${messageId})`);
+
+		// 4. Find session end (last message of target's session)
 		const sessionEnd = findSessionEnd(checkpointMessage, allMessages);
 		debug.log('snapshot', `Session end: ${sessionEnd.id}`);
 
@@ -137,12 +228,19 @@ export const restoreHandler = createRouter()
 		}
 
 		// 6. Update checkpoint_tree_state for ancestors
-		const checkpointPath = getCheckpointPathToRoot(messageId, parentMap);
-		if (checkpointPath.length > 1) {
-			checkpointQueries.updateActiveChildrenAlongPath(sessionId, checkpointPath);
+		// Use resolved checkpoint ID (not raw messageId which may be a non-checkpoint)
+		// Also compute checkpointPath for branch-aware file restore
+		let checkpointPath: string[] = [];
+		if (resolvedCheckpointId) {
+			checkpointPath = getCheckpointPathToRoot(resolvedCheckpointId, parentMap);
+			if (checkpointPath.length > 1) {
+				checkpointQueries.updateActiveChildrenAlongPath(sessionId, checkpointPath);
+			}
 		}
 
 		// 7. Restore file system state using session-scoped restore
+		// Use resolved checkpoint ID so the snapshot lookup matches correctly
+		// (snapshots are keyed by checkpoint user message IDs, not assistant messages)
 		let filesRestored = 0;
 		let filesSkipped = 0;
 
@@ -153,8 +251,9 @@ export const restoreHandler = createRouter()
 				const result = await snapshotService.restoreSessionScoped(
 					project.path,
 					sessionId,
-					messageId,
-					conflictResolutions
+					resolvedCheckpointId,
+					conflictResolutions,
+					checkpointPath.length > 0 ? checkpointPath : undefined
 				);
 				filesRestored = result.restoredFiles;
 				filesSkipped = result.skippedFiles;

package/backend/ws/snapshot/timeline.ts

@@ -15,7 +15,8 @@ import {
 	getCheckpointPathToRoot,
 	findCheckpointForHead,
 	isDescendant,
-	getCheckpointFileStats
+	getCheckpointFileStats,
+	INITIAL_NODE_ID
 } from '../../lib/snapshot/helpers';
 import type { CheckpointNode, TimelineResponse } from '../../lib/snapshot/helpers';
 import type { SDKMessage } from '$shared/types/messaging';
@@ -36,11 +37,8 @@ export const timelineHandler = createRouter()
 
 		// 1. Get current HEAD
 		const currentHead = sessionQueries.getHead(sessionId);
-		debug.log('snapshot', `Current HEAD: ${currentHead || 'null'}`);
-
-		if (!currentHead) {
-			return { nodes: [], currentHeadId: null };
-		}
+		const isAtInitialState = !currentHead;
+		debug.log('snapshot', `Current HEAD: ${currentHead || 'null (initial state)'}`);
 
 		// 2. Get all messages
 		const allMessages = messageQueries.getAllBySessionId(sessionId);
@@ -61,8 +59,10 @@ export const timelineHandler = createRouter()
 		const checkpointIdSet = new Set(checkpoints.map(c => c.id));
 
 		// 4. Find which checkpoint HEAD belongs to
-		const activeCheckpointId = findCheckpointForHead(currentHead, allMessages, checkpointIdSet);
-		debug.log('snapshot', `Active checkpoint: ${activeCheckpointId}`);
+		const activeCheckpointId = isAtInitialState
+			? null
+			: findCheckpointForHead(currentHead, allMessages, checkpointIdSet);
+		debug.log('snapshot', `Active checkpoint: ${activeCheckpointId || '(initial)'}`);
 
 		// 5. Build active path (from root to active checkpoint)
 		const activePathIds = new Set<string>();
@@ -76,22 +76,47 @@ export const timelineHandler = createRouter()
 		// 6. Get active children map from database
 		const activeChildrenMap = checkpointQueries.getAllActiveChildren(sessionId);
 
-		// 7. Sort checkpoints by timestamp for file stats calculation
-		const sortedCheckpoints = [...checkpoints].sort(
-			(a, b) => a.timestamp.localeCompare(b.timestamp)
-		);
-
-		// Build next-checkpoint timestamp map for stats
-		const nextTimestampMap = new Map<string, string>();
-		for (let i = 0; i < sortedCheckpoints.length; i++) {
-			const next = sortedCheckpoints[i + 1];
-			if (next) {
-				nextTimestampMap.set(sortedCheckpoints[i].id, next.timestamp);
-			}
+		// 7. Build response nodes
+		const nodes: CheckpointNode[] = [];
+
+		// Find root checkpoints (those with no parent)
+		const rootCheckpointIds = checkpoints
+			.filter(cp => !parentMap.has(cp.id))
+			.map(cp => cp.id);
+
+		// Get session started_at for the initial node timestamp
+		const session = sessionQueries.getById(sessionId);
+		const sessionStartedAt = session?.started_at || new Date().toISOString();
+
+		// Add the "Initial State" node at the beginning
+		// Its activeChildId points to the first root checkpoint on the active path,
+		// or the first root checkpoint if we're at initial state
+		let initialActiveChildId: string | null = null;
+		if (isAtInitialState) {
+			// At initial state: the first root checkpoint (by timestamp) is the active child
+			initialActiveChildId = rootCheckpointIds[0] || null;
+		} else {
+			// Find root checkpoint on active path
+			initialActiveChildId = rootCheckpointIds.find(id => activePathIds.has(id)) || rootCheckpointIds[0] || null;
 		}
 
-		// 8. Build response nodes
-		const nodes: CheckpointNode[] = [];
+		nodes.push({
+			id: INITIAL_NODE_ID,
+			messageId: INITIAL_NODE_ID,
+			parentId: null,
+			activeChildId: initialActiveChildId,
+			timestamp: sessionStartedAt,
+			messageText: 'Session Start',
+			isOnActivePath: isAtInitialState || activePathIds.size > 0,
+			isOrphaned: false,
+			isCurrent: isAtInitialState,
+			hasSnapshot: false,
+			isInitial: true,
+			senderName: null,
+			filesChanged: 0,
+			insertions: 0,
+			deletions: 0
+		});
 
 		for (const cp of checkpoints) {
 			const sdk = JSON.parse(cp.sdk_message) as SDKMessage;
@@ -107,16 +132,16 @@ export const timelineHandler = createRouter()
 				isOrphaned = isDescendant(cp.id, activeCheckpointId, childrenMap);
 			}
 
-			// File stats
-			const nextTimestamp = nextTimestampMap.get(cp.id);
-			const stats = getCheckpointFileStats(cp, allMessages, nextTimestamp);
+			// File stats from checkpoint's own snapshot
+			const stats = getCheckpointFileStats(cp);
 
 			const snapshot = snapshotQueries.getByMessageId(cp.id);
 
 			nodes.push({
 				id: cp.id,
 				messageId: cp.id,
-				parentId: parentCpId,
+				// Root checkpoints have initial node as parent
+				parentId: parentCpId || INITIAL_NODE_ID,
 				activeChildId,
 				timestamp: cp.timestamp,
 				messageText,
@@ -131,11 +156,13 @@ export const timelineHandler = createRouter()
 			});
 		}
 
-		debug.log('snapshot', `Timeline nodes: ${nodes.length}`);
-		debug.log('snapshot', `Active path: ${activePathIds.size} nodes`);
+		const currentHeadId = isAtInitialState ? INITIAL_NODE_ID : activeCheckpointId;
+
+		debug.log('snapshot', `Timeline nodes: ${nodes.length} (including initial)`);
+		debug.log('snapshot', `Active path: ${activePathIds.size} nodes, current: ${currentHeadId}`);
 
 		return {
 			nodes,
-			currentHeadId: activeCheckpointId
+			currentHeadId
 		};
 	});