hammoc 1.1.6 → 1.2.1

package/packages/server/dist/handlers/websocket.js

@@ -5,11 +5,13 @@
  * Story 4.6: Timeout handling and error management
  */
 import { Server as SocketIOServer } from 'socket.io';
-import { existsSync, unlinkSync } from 'fs';
-import { ERROR_CODES, IMAGE_CONSTRAINTS, parseQueueScript, TERMINAL_ERRORS } from '@hammoc/shared';
+import { existsSync, unlinkSync, readFileSync, readdirSync, statSync } from 'fs';
+import { randomUUID } from 'crypto';
+import { ERROR_CODES, IMAGE_CONSTRAINTS, parseQueueScript, TERMINAL_ERRORS, ROOT_BRANCH_KEY } from '@hammoc/shared';
 import i18next from '../i18n.js';
 import { SUPPORTED_LANGUAGES } from '@hammoc/shared';
 import { isLocalIP, extractClientIP } from '../utils/networkUtils.js';
+import { query as sdkQuery } from '@anthropic-ai/claude-agent-sdk';
 import { ChatService } from '../services/chatService.js';
 import { SessionService } from '../services/sessionService.js';
 import { parseSDKError, AbortedError, SDKErrorCode } from '../utils/errors.js';
@@ -24,6 +26,11 @@ import { rateLimitProbeService } from '../services/rateLimitProbeService.js';
 import { ptyService } from '../services/ptyService.js';
 import { projectService } from '../services/projectService.js';
 import { dashboardService } from '../services/dashboardService.js';
+import { summarize } from '../services/summarizeService.js';
+import { parseJSONLFile, transformToHistoryMessages } from '../services/historyParser.js';
+import { buildRawMessageTree, getActiveRawBranch, getDefaultRawBranchSelections, findBranchSelectionsForUuid } from '../utils/messageTree.js';
+import { sessionBufferManager } from '../services/sessionBufferManager.js';
+import { imageStorageService } from '../services/imageStorageService.js';
 const log = createLogger('websocket');
 // Alias for concise usage in guards
 const queueInstances = getQueueInstances;
@@ -93,6 +100,8 @@ const chainResumableSessions = new Set();
 let chainItemCounter = 0;
 const CHAIN_MAX_RETRIES = 3;
 const UUID_RE = /^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$/i;
+// Story 25.9: Per-socket summarizing state — requestId prevents race between cancel + new request
+const socketSummarizing = new Map();
 /** Generate a unique chain item ID */
 function generateChainItemId() {
     return `chain-${Date.now()}-${++chainItemCounter}`;
@@ -139,7 +148,12 @@ function cleanupChainIfIdle(sessionId) {
         return;
     }
     chainState.delete(sessionId);
-    chainResumableSessions.delete(sessionId);
+    // NOTE: chainResumableSessions is intentionally NOT deleted here.
+    // It tracks whether a session has ever completed a successful handleChatSend,
+    // which is needed for future chain:add items to use resume mode. Deleting it
+    // causes the next chain drain to attempt a fresh session with an existing
+    // sessionId, resulting in "process exited with code 1".
+    //
     // NOTE: chainDrainGeneration is intentionally NOT deleted here.
     // Deleting would reset the counter to 0, allowing stale timers from before
     // cleanup to match a new gen=1 value (ABA problem).
@@ -303,6 +317,7 @@ function scheduleChainDrain(sessionId, lang) {
                     const remainingPending = remaining?.filter(item => item.status === 'pending').length ?? 0;
                     log.info(`[CHAIN-DRAIN] finally: cleaning up stream, remainingItems=${remaining?.length ?? 0}, remainingPending=${remainingPending}`);
                     const chainEndSlug = sessionProjectMap.get(sessionId) ?? null;
+                    await completeBufferAndBroadcast(sessionId, chainEndSlug, stream);
                     cleanupStream(sessionId);
                     emitStreamChange(sessionId, false, chainEndSlug);
                     // Persist per-session permission mode before cleanup
@@ -379,78 +394,100 @@ export function isSessionStreaming(sessionId) {
     const stream = activeStreams.get(sessionId);
     return !!stream && stream.status === 'running';
 }
-/** Completed stream buffers kept independently of activeStreams.
- *  When a stream completes, its buffer is saved here for 5 seconds so clients
- *  joining during the JSONL flush window can still receive the completed turn.
- *  This is separate from activeStreams so new streams can be created immediately
- *  without losing the completed buffer. */
-const completedBuffers = new Map();
-/** Timer handles for completedBuffer expiry, keyed by sessionId.
- *  Tracked so we can cancel the previous timer when a new buffer replaces it,
- *  allowing the old buffer to be GC'd immediately instead of waiting for expiry. */
-const completedBufferTimers = new Map();
-/** How long to keep completed buffers (ms). Allows JSONL to flush before
- *  fetchMessages becomes the sole source for this turn's data. */
-const COMPLETED_BUFFER_TTL_MS = 5000;
-/** Get the earliest stream start timestamp (active OR recently completed).
- *  When both exist (e.g., chain: previous turn completed + new turn running),
- *  returns the earlier one so fetchMessages excludes ALL stream-period messages.
- *  Both the completed turn and active turn are provided via buffer replay. */
-export function getStreamStartedAt(sessionId) {
-    const stream = activeStreams.get(sessionId);
-    const runningStart = stream && stream.status === 'running' ? stream.startedAt : null;
-    const completedStart = completedBuffers.get(sessionId)?.startedAt ?? null;
-    if (runningStart && completedStart)
-        return Math.min(runningStart, completedStart);
-    return runningStart ?? completedStart;
+/** Get session IDs that have active socket connections for a given project */
+export function getJoinedSessionIdsByProject(projectSlug) {
+    const sessionIds = new Set();
+    for (const [socketId, slug] of socketProjectRoom.entries()) {
+        if (slug !== projectSlug)
+            continue;
+        const sessionId = socketSessionRoom.get(socketId);
+        if (sessionId && UUID_RE.test(sessionId)) {
+            sessionIds.add(sessionId);
+        }
+    }
+    return sessionIds;
 }
-/** Get start timestamp of the currently running stream only (ignores completed buffers). */
-export function getRunningStreamStartedAt(sessionId) {
-    const stream = activeStreams.get(sessionId);
-    return stream && stream.status === 'running' ? stream.startedAt : null;
+/**
+ * Wait for JSONL to contain conversation data, then reload buffer and broadcast.
+ * The SDK writes user/assistant messages asynchronously after returning from
+ * sendMessageWithCallbacks, so we poll until the data appears.
+ */
+async function completeBufferAndBroadcast(sessionId, projectSlug, stream) {
+    const aborted = stream?.abortController.signal.aborted ?? false;
+    const usage = stream?.deferredUsage;
+    if (projectSlug) {
+        try {
+            const messages = await pollFileStabilityThenReload(sessionId, projectSlug);
+            sessionBufferManager.setStreaming(sessionId, false);
+            io.to(`session:${sessionId}`).emit('stream:complete-messages', {
+                sessionId, messages, usage, ...(aborted && { aborted: true }),
+            });
+        }
+        catch (err) {
+            log.error(`completeBufferAndBroadcast: failed for ${sessionId}:`, err);
+            sessionBufferManager.setStreaming(sessionId, false);
+            const fallback = sessionBufferManager.get(sessionId)?.messages ?? [];
+            io.to(`session:${sessionId}`).emit('stream:complete-messages', {
+                sessionId, messages: fallback, usage, ...(aborted && { aborted: true }),
+            });
+        }
+    }
+    else {
+        sessionBufferManager.setStreaming(sessionId, false);
+        const buf = sessionBufferManager.get(sessionId);
+        io.to(`session:${sessionId}`).emit('stream:complete-messages', {
+            sessionId, messages: buf?.messages ?? [], usage, ...(aborted && { aborted: true }),
+        });
+    }
 }
-/** Get the completed buffer for a session (null if none or expired). */
-export function getCompletedBuffer(sessionId) {
-    const completed = completedBuffers.get(sessionId);
-    return completed ? completed.events : null;
+/**
+ * Poll until the JSONL file size stabilizes (3 consecutive checks unchanged),
+ * then reload the buffer from the confirmed JSONL data.
+ * Used for both normal completion and abort — SDK writes asynchronously
+ * after returning from sendMessageWithCallbacks.
+ */
+const FILE_POLL_INTERVAL_MS = 100;
+const FILE_POLL_TIMEOUT_MS = 5000;
+const FILE_POLL_STABLE_COUNT = 3;
+async function pollFileStabilityThenReload(sessionId, projectSlug) {
+    const svc = new SessionService();
+    const filePath = svc.getSessionFilePath(projectSlug, sessionId);
+    const getFileSize = () => {
+        try {
+            return existsSync(filePath) ? statSync(filePath).size : -1;
+        }
+        catch {
+            return -1;
+        }
+    };
+    let lastSize = getFileSize();
+    let stableCount = 0;
+    const startedAt = Date.now();
+    const deadline = startedAt + FILE_POLL_TIMEOUT_MS;
+    while (Date.now() < deadline) {
+        await new Promise(resolve => setTimeout(resolve, FILE_POLL_INTERVAL_MS));
+        const currentSize = getFileSize();
+        // Don't count stability if file doesn't exist yet (-1)
+        if (currentSize >= 0 && currentSize === lastSize) {
+            stableCount++;
+            if (stableCount >= FILE_POLL_STABLE_COUNT)
+                break;
+        }
+        else {
+            stableCount = 0;
+            lastSize = currentSize;
+        }
+    }
+    log.info(`pollFileStability: session=${sessionId}, elapsed=${Date.now() - startedAt}ms, stable=${stableCount >= FILE_POLL_STABLE_COUNT}`);
+    return sessionBufferManager.reloadFromJSONL(sessionId, projectSlug);
 }
-/** Clean up a stream from activeStreams immediately. Saves the buffer to
- *  completedBuffers for 5 seconds so it remains available independently
- *  of any new stream that may be created for the same session. */
+/** Clean up a stream from activeStreams immediately.
+ *  Story 27.1: SessionBufferManager retains the messages; no completedBuffer needed. */
 function cleanupStream(streamKey, expectedStream) {
     const current = activeStreams.get(streamKey);
     // Identity guard: if caller specifies the expected stream but a replacement has
-    // taken over, don't delete activeStreams (would remove the new stream). However,
-    // still save the completed buffer so clients can replay the finished turn.
+    // taken over, don't delete activeStreams (would remove the new stream).
     const replaced = expectedStream && current !== expectedStream;
-    const stream = expectedStream ?? current;
-    // Keep a reference to the completed buffer independently of activeStreams.
-    // No copy needed — the buffer is immutable after completion (createStreamEmit
-    // only pushes to running streams). Only the buffer array is retained; the rest
-    // of the stream object (sockets, chatService, etc.) is released for GC.
-    if (stream && stream.buffer.length > 0) {
-        // Only write if this stream is newer than (or same as) any existing entry.
-        // An older stream's delayed finalizeStream must not overwrite a newer buffer.
-        const existing = completedBuffers.get(streamKey);
-        if (!existing || stream.startedAt >= existing.startedAt) {
-            // Cancel previous expiry timer so the old buffer can be GC'd immediately
-            const prevTimer = completedBufferTimers.get(streamKey);
-            if (prevTimer)
-                clearTimeout(prevTimer);
-            completedBuffers.set(streamKey, {
-                events: stream.buffer,
-                startedAt: stream.startedAt,
-            });
-            const timer = setTimeout(() => {
-                // Guard: only delete if this timer is still the current one for this key.
-                if (completedBufferTimers.get(streamKey) === timer) {
-                    completedBuffers.delete(streamKey);
-                    completedBufferTimers.delete(streamKey);
-                }
-            }, COMPLETED_BUFFER_TTL_MS);
-            completedBufferTimers.set(streamKey, timer);
-        }
-    }
     // Only delete from activeStreams and clean up socket mappings if the stream
     // hasn't been replaced. When replaced, the new stream owns those resources.
     if (!replaced) {
@@ -512,6 +549,8 @@ export function createHeadlessStream(sessionId, abortController, projectSlug) {
         startedAt: Date.now(),
     };
     activeStreams.set(sessionId, stream);
+    // Story 27.1: Initialize SessionBufferManager for headless stream
+    sessionBufferManager.create(sessionId, true);
     if (projectSlug) {
         sessionProjectMap.set(sessionId, projectSlug);
     }
@@ -528,11 +567,20 @@ export function createHeadlessStream(sessionId, abortController, projectSlug) {
 export function rekeyStream(stream, newSessionId) {
     if (stream.sessionId === newSessionId)
         return;
+    // For fork streams, reset startedAt to now. The SDK has finished copying
+    // history (all with timestamps <= now) and is about to start generating
+    // the response. This lets the streamStartedAt JSONL filter correctly
+    // distinguish copied history from the streaming response.
+    if (stream.isFork) {
+        stream.startedAt = Date.now();
+    }
     const oldSessionId = stream.sessionId;
     const projectSlug = sessionProjectMap.get(oldSessionId);
     activeStreams.delete(oldSessionId);
     stream.sessionId = newSessionId;
     activeStreams.set(newSessionId, stream);
+    // Story 27.1: Re-key buffer alongside stream
+    sessionBufferManager.rekey(oldSessionId, newSessionId);
     if (projectSlug) {
         sessionProjectMap.delete(oldSessionId);
         sessionProjectMap.set(newSessionId, projectSlug);
@@ -545,7 +593,7 @@ export function rekeyStream(stream, newSessionId) {
 }
 /**
  * Mark a stream as completed and broadcast stream-change.
- * Cleans up from activeStreams map.
+ * Story 27.1: Re-parses JSONL → replaces buffer → broadcasts stream:complete-messages.
  */
 export async function finalizeStream(sessionId) {
     const stream = activeStreams.get(sessionId);
@@ -554,6 +602,9 @@ export async function finalizeStream(sessionId) {
         if (finalMode)
             await persistSessionPermissionMode(sessionId, finalMode);
         stream.status = 'completed';
+        // Story 27.1: JSONL is fully written (appendFileSync). Reload buffer from disk
+        // and broadcast confirmed messages to all session viewers.
+        await completeBufferAndBroadcast(sessionId, sessionProjectMap.get(sessionId), stream);
         // Pass stream reference so cleanupStream won't accidentally clean up a
         // replacement stream that started during the async persistence above.
         cleanupStream(sessionId, stream);
@@ -584,6 +635,14 @@ function emitStreamChange(sessionId, active, projectSlug) {
     else {
         io.emit('session:stream-change', payload);
     }
+    // When streaming ends, check if sockets are still connected to the session.
+    // If so, transition from "streaming" to "waiting" for session list viewers.
+    if (!active && projectSlug) {
+        const room = io.sockets.adapter.rooms.get(`session:${sessionId}`);
+        if (room && room.size > 0) {
+            io.to(`project:${projectSlug}`).emit('session:waiting-change', { sessionId, waiting: true, projectSlug });
+        }
+    }
 }
 /**
  * Broadcast session:stream-change to project room (or all clients as fallback).
@@ -696,8 +755,6 @@ export async function initializeWebSocket(httpServer) {
         if (connectedClients === 1) {
             rateLimitProbeService.startPolling((data) => { io.emit('rateLimit:update', data); }, (data) => { io.emit('apiHealth:update', data); });
         }
-        // Send subscriber status immediately (credential file check, no network call)
-        socket.emit('auth:subscriber', { isSubscriber: rateLimitProbeService.hasOAuthCredentials() });
         // Send cached rate limit data immediately to newly connected client
         const cachedRateLimit = rateLimitProbeService.getCachedResult();
         if (cachedRateLimit) {
@@ -737,6 +794,14 @@ export async function initializeWebSocket(httpServer) {
                 }
                 existingStream.abortController.abort('another-client');
             }
+            // Ensure this socket is in the session room so that chain:add events
+            // emitted right after chat:send pass the room membership check.
+            // Only join the room — do NOT update socketSessionRoom here, because
+            // session:join uses it to find and leave the previous session room.
+            // Overwriting it early would prevent proper cleanup of old rooms.
+            if (data.sessionId && !socket.rooms.has(`session:${streamKey}`)) {
+                socket.join(`session:${streamKey}`);
+            }
             // Collect all sockets viewing this session (from persistent session room)
             const initialSockets = new Set([socket]);
             const roomSockets = io.sockets.adapter.rooms.get(`session:${streamKey}`);
@@ -756,6 +821,9 @@ export async function initializeWebSocket(httpServer) {
                 pendingPermissions: new Map(),
                 status: 'running',
                 startedAt: Date.now(),
+                resumeSessionAt: data.resumeSessionAt,
+                expectedBranchTotal: data.expectedBranchTotal,
+                isFork: !!data.forkSession,
             };
             activeStreams.set(streamKey, stream);
             // Bump drain generation so any pending scheduled drain is invalidated
@@ -763,10 +831,10 @@ export async function initializeWebSocket(httpServer) {
             for (const sock of initialSockets) {
                 socketToSession.set(sock.id, streamKey);
             }
+            // Story 27.1: Initialize SessionBufferManager for this stream
+            sessionBufferManager.create(streamKey, true);
             // Story 20.1: Populate session→project mapping for dashboard triggers
-            // Use stream.sessionId (mutable) instead of captured streamKey to handle
-            // race condition where rekeyStream() may have already changed the session ID
-            projectService.findProjectByPath(data.workingDirectory).then((project) => {
+            projectService.findProjectByPath(data.workingDirectory).then(async (project) => {
                 if (project && stream.status === 'running') {
                     sessionProjectMap.set(stream.sessionId, project.projectSlug);
                     triggerDashboardStatusChange(project.projectSlug);
@@ -786,7 +854,10 @@ export async function initializeWebSocket(httpServer) {
                 // A replacement stream (from another chat:send) may have already taken over
                 // the same key — deleting it would be a race condition.
                 if (isCurrentStream) {
+                    // Story 27.1: JSONL is fully written (appendFileSync). Reload buffer
+                    // from disk and broadcast confirmed messages to all session viewers.
                     const sendEndSlug = sessionProjectMap.get(endedSessionId) ?? null;
+                    await completeBufferAndBroadcast(endedSessionId, sendEndSlug, stream);
                     cleanupStream(endedSessionId);
                     emitStreamChange(endedSessionId, false, sendEndSlug);
                     // Persist per-session permission mode before cleanup
@@ -965,6 +1036,17 @@ export async function initializeWebSocket(httpServer) {
             }
             // Story 24.3: Track session room membership for session:leave room management
             socketSessionRoom.set(socket.id, sessionId);
+            // Register sessionProjectMap on join so leave cleanup can find the slug.
+            if (projectSlug && UUID_RE.test(sessionId)) {
+                if (!sessionProjectMap.has(sessionId)) {
+                    sessionProjectMap.set(sessionId, projectSlug);
+                }
+            }
+            // Notify session list viewers that this session is now connected (waiting).
+            // Skip if the session is actively streaming — it's already shown as streaming.
+            if (projectSlug && UUID_RE.test(sessionId) && !activeStreams.has(sessionId)) {
+                socket.to(`project:${projectSlug}`).emit('session:waiting-change', { sessionId, waiting: true, projectSlug });
+            }
             const stream = activeStreams.get(sessionId);
             // Story 24.1: Send current chain state on join (in-memory + persisted failures)
             // Only attempt disk read for valid UUID sessionIds to avoid unbounded lock map growth
@@ -988,10 +1070,10 @@ export async function initializeWebSocket(httpServer) {
                 socket.emit('chain:update', { sessionId, items: freshItems });
             }
             if (!stream || stream.status !== 'running') {
-                // Emit inactive status + completed buffer replay.
+                // Story 27.1: Deliver buffer messages via stream:history (no HTTP fetch needed).
                 // Wrapped in a helper that re-checks activeStreams because the async
                 // preference-read path can yield, and a new stream may start in between.
-                const emitInactiveWithReplay = (permissionMode) => {
+                const emitInactiveWithHistory = async (permissionMode) => {
                     // Stale callback guard: if the socket has left this session (moved to
                     // another session or disconnected), don't emit anything for the old session.
                     if (socketSessionRoom.get(socket.id) !== sessionId || !socket.connected) {
@@ -999,21 +1081,55 @@ export async function initializeWebSocket(httpServer) {
                     }
                     // Re-check: if a running stream appeared during async wait, emit active
                     // state instead of stale inactive. Without this, the client would miss
-                    // the initial stream:status/buffer-replay for the new stream.
+                    // the initial stream:status/stream:history for the new stream.
                     const freshStream = activeStreams.get(sessionId);
                     if (freshStream && freshStream.status === 'running') {
                         socketToSession.set(socket.id, sessionId);
-                        const bufSnapshot = [...freshStream.buffer];
                         const freshMode = freshStream.chatService?.getPermissionMode();
+                        // Deliver buffer messages (history + streaming data so far)
+                        const buf = sessionBufferManager.get(sessionId);
+                        if (buf && buf.messages.length > 0) {
+                            socket.emit('stream:history', { sessionId, messages: buf.messages });
+                        }
                         socket.emit('stream:status', { active: true, sessionId, permissionMode: freshMode });
-                        // Only replay active buffer — completedBuffer is served via fetchMessages API
-                        socket.emit('stream:buffer-replay', { sessionId, events: bufSnapshot });
+                        socket.emit('stream:buffer-replay', { sessionId, events: [...freshStream.buffer] });
                         freshStream.sockets.add(socket);
                         return;
                     }
+                    // Completed stream still flushing (polling JSONL): deliver history +
+                    // raw buffer replay so the joining browser sees the full conversation
+                    // immediately, matching what already-connected browsers saw via live events.
+                    // stream:complete-messages will follow shortly with confirmed data.
+                    const completedStream = freshStream ?? activeStreams.get(sessionId);
+                    if (completedStream && completedStream.status === 'completed' && completedStream.buffer.length > 0) {
+                        socketToSession.set(socket.id, sessionId);
+                        const buf = sessionBufferManager.get(sessionId);
+                        if (buf && buf.messages.length > 0) {
+                            socket.emit('stream:history', { sessionId, messages: buf.messages });
+                        }
+                        socket.emit('stream:status', { active: true, sessionId, permissionMode });
+                        socket.emit('stream:buffer-replay', { sessionId, events: [...completedStream.buffer] });
+                        completedStream.sockets.add(socket);
+                        return;
+                    }
+                    // Inactive: deliver buffer messages or parse JSONL as fallback
+                    let buf = sessionBufferManager.get(sessionId);
+                    const resolvedSlug = projectSlug || sessionProjectMap.get(sessionId);
+                    if (!buf && resolvedSlug) {
+                        // Buffer missing (server restart or first visit) — parse JSONL and create buffer
+                        sessionBufferManager.create(sessionId);
+                        try {
+                            await sessionBufferManager.reloadFromJSONL(sessionId, resolvedSlug);
+                            buf = sessionBufferManager.get(sessionId);
+                        }
+                        catch (err) {
+                            log.warn(`session:join: failed to load JSONL for ${sessionId}:`, err);
+                        }
+                    }
+                    if (buf && buf.messages.length > 0) {
+                        socket.emit('stream:history', { sessionId, messages: buf.messages });
+                    }
                     socket.emit('stream:status', { active: false, sessionId, permissionMode });
-                    // completedBuffer is NOT replayed here — fetchMessages API already merges
-                    // completedBuffer data into its response, so the client gets it via HTTP.
                 };
                 // For 'always' sync policy, restore per-session permission mode from disk
                 const resolvedSlug = projectSlug || sessionProjectMap.get(sessionId);
@@ -1024,32 +1140,46 @@ export async function initializeWebSocket(httpServer) {
                             if (projectPath) {
                                 const perms = await projectService.readSessionPermissions(projectPath);
                                 const savedMode = perms[sessionId];
-                                emitInactiveWithReplay(savedMode);
+                                await emitInactiveWithHistory(savedMode);
                                 return;
                             }
                         }
-                        emitInactiveWithReplay();
+                        await emitInactiveWithHistory();
                     }).catch(() => {
-                        emitInactiveWithReplay();
+                        emitInactiveWithHistory();
                     });
                 }
                 else {
-                    emitInactiveWithReplay();
+                    emitInactiveWithHistory();
                 }
                 return;
             }
             socketToSession.set(socket.id, sessionId);
-            // Snapshot BEFORE adding socket to broadcast set to prevent race.
-            const bufferSnapshot = [...stream.buffer];
             const permissionMode = stream.chatService?.getPermissionMode();
-            // Emit order matters for the client:
-            // 1. stream:status { active: true } → client calls restoreStreaming + trimMessagesAfterLastUser
-            // 2. active buffer replay → client sets streaming segments for the current turn
-            // Note: completedBuffer (previous chain turn) is NOT replayed here — the client's
-            // fetchMessages API already merges completedBuffer data into its response. Sending
-            // it as buffer-replay too would cause duplicate user messages on session entry.
+            // Story 27.1: Deliver buffer messages (history + streaming data accumulated so far)
+            // so a new browser joining mid-stream sees the full context immediately.
+            let buf = sessionBufferManager.get(sessionId);
+            // Buffer may have been destroyed if all sockets left briefly — recover from JSONL
+            if (!buf) {
+                const slug = sessionProjectMap.get(sessionId);
+                if (slug) {
+                    sessionBufferManager.create(sessionId, true);
+                    sessionBufferManager.reloadFromJSONL(sessionId, slug)
+                        .then(() => {
+                        const recovered = sessionBufferManager.get(sessionId);
+                        if (recovered && recovered.messages.length > 0) {
+                            socket.emit('stream:history', { sessionId, messages: recovered.messages });
+                        }
+                    })
+                        .catch(() => { });
+                }
+            }
+            if (buf && buf.messages.length > 0) {
+                socket.emit('stream:history', { sessionId, messages: buf.messages });
+            }
             socket.emit('stream:status', { active: true, sessionId, permissionMode });
-            socket.emit('stream:buffer-replay', { sessionId, events: bufferSnapshot });
+            // Replay raw event buffer so the client can build streaming segments
+            socket.emit('stream:buffer-replay', { sessionId, events: [...stream.buffer] });
             // NOW add to broadcast set — live events flow from here
             stream.sockets.add(socket);
         });
@@ -1069,6 +1199,25 @@ export async function initializeWebSocket(httpServer) {
             const roomSessionId = sessionId || prevSessionId || socketSessionRoom.get(socket.id);
             if (roomSessionId) {
                 socket.leave(`session:${roomSessionId}`);
+                // Story 27.1: Destroy buffer when no sockets remain AND no active stream.
+                // Active stream needs the buffer for mid-stream joiners and completion.
+                const remaining = io.sockets.adapter.rooms.get(`session:${roomSessionId}`);
+                if ((!remaining || remaining.size === 0) && !activeStreams.has(roomSessionId)) {
+                    sessionBufferManager.destroy(roomSessionId);
+                }
+                // Notify session list viewers when no sockets remain for this session
+                if (!remaining || remaining.size === 0) {
+                    const slug = socketProjectRoom.get(socket.id) || sessionProjectMap.get(roomSessionId);
+                    if (slug) {
+                        io.to(`project:${slug}`).emit('session:waiting-change', { sessionId: roomSessionId, waiting: false, projectSlug: slug });
+                    }
+                }
+            }
+            // Story 25.9: Cancel in-progress summary on session leave
+            const sumState = socketSummarizing.get(socket.id);
+            if (sumState?.abortController) {
+                sumState.abortController.abort();
+                socketSummarizing.set(socket.id, { activeRequestId: null, abortController: null });
             }
             // Story 24.3: Clean up session room tracking on leave
             // Only clear project room if the leaving session matches current tracking.
@@ -1193,6 +1342,234 @@ export async function initializeWebSocket(httpServer) {
                 log.error(`Failed to clear persisted failures for session ${sessionId}:`, err);
             });
         });
+        // Story 25.8: Standalone file rewind
+        socket.on('session:rewind-files', async (data) => {
+            const lang = socket.data.language || 'en';
+            const t = i18next.getFixedT(lang);
+            if (!data || typeof data !== 'object')
+                return;
+            const { sessionId, workingDirectory, messageUuid, dryRun } = data;
+            // Validation
+            if (!sessionId || typeof sessionId !== 'string' || !UUID_RE.test(sessionId) ||
+                !messageUuid || typeof messageUuid !== 'string') {
+                socket.emit('error', { code: ERROR_CODES.VALIDATION_ERROR, message: t('ws.error.rewindMissingParams') });
+                return;
+            }
+            if (!workingDirectory || typeof workingDirectory !== 'string') {
+                socket.emit('error', { code: ERROR_CODES.VALIDATION_ERROR, message: t('ws.error.rewindMissingParams') });
+                return;
+            }
+            // Validate socket is a member of the session room
+            if (!socket.rooms.has(`session:${sessionId}`))
+                return;
+            log.info(`session:rewind-files sessionId=${sessionId}, messageUuid=${messageUuid}, dryRun=${!!dryRun}`);
+            try {
+                const sessionService = new SessionService();
+                const projectSlug = sessionService.encodeProjectPath(workingDirectory);
+                const rewindQuery = sdkQuery({
+                    prompt: '',
+                    options: {
+                        resume: sessionId,
+                        cwd: workingDirectory,
+                        enableFileCheckpointing: true,
+                        // Do NOT pass sessionId here — CLI rejects --session-id
+                        // combined with --resume unless --fork-session is also set.
+                        // resume: sessionId already identifies the session.
+                    },
+                });
+                try {
+                    const rewindResult = await rewindQuery.rewindFiles(messageUuid, { dryRun: !!dryRun });
+                    log.info(`rewindFiles result: canRewind=${rewindResult.canRewind}, filesChanged=${rewindResult.filesChanged?.length ?? 0}, insertions=${rewindResult.insertions ?? 0}, deletions=${rewindResult.deletions ?? 0}`);
+                    if (rewindResult.canRewind) {
+                        socket.emit('session:rewind-result', {
+                            success: true,
+                            dryRun: !!dryRun,
+                            filesChanged: rewindResult.filesChanged,
+                            insertions: rewindResult.insertions,
+                            deletions: rewindResult.deletions,
+                        });
+                    }
+                    else {
+                        socket.emit('session:rewind-result', {
+                            success: false,
+                            dryRun: !!dryRun,
+                            error: rewindResult.error,
+                        });
+                    }
+                }
+                finally {
+                    // Clean up the query object
+                    rewindQuery.close();
+                }
+            }
+            catch (err) {
+                const msg = err instanceof Error ? err.message : String(err);
+                log.error(`session:rewind-files error: ${msg}`);
+                socket.emit('session:rewind-result', {
+                    success: false,
+                    dryRun: !!dryRun,
+                    error: msg,
+                });
+            }
+        });
+        // Story 25.9: Generate conversation summary
+        socket.on('session:generate-summary', async (data) => {
+            const lang = socket.data.language || 'en';
+            if (!data || typeof data !== 'object')
+                return;
+            const { sessionId, messageUuid } = data;
+            // Validate sessionId
+            if (!sessionId || typeof sessionId !== 'string' || !UUID_RE.test(sessionId)) {
+                socket.emit('session:summary-result', { messageUuid: messageUuid ?? '', error: 'Invalid sessionId' });
+                return;
+            }
+            // Validate messageUuid format
+            if (!messageUuid || typeof messageUuid !== 'string' || !UUID_RE.test(messageUuid)) {
+                socket.emit('session:summary-result', { messageUuid: messageUuid ?? '', error: 'Invalid messageUuid format' });
+                return;
+            }
+            // Validate socket is in the session room
+            if (!socket.rooms.has(`session:${sessionId}`)) {
+                socket.emit('session:summary-result', { messageUuid, error: 'Not joined to session' });
+                return;
+            }
+            // Abort any in-progress summary before starting a new one
+            const prevState = socketSummarizing.get(socket.id);
+            if (prevState?.abortController) {
+                prevState.abortController.abort();
+            }
+            const requestId = randomUUID();
+            const abortController = new AbortController();
+            socketSummarizing.set(socket.id, { activeRequestId: requestId, abortController });
+            try {
+                const sessionService = new SessionService();
+                // Find projectSlug for this session — try sessionProjectMap first, then socketProjectRoom
+                const projectSlug = sessionProjectMap.get(sessionId) || socketProjectRoom.get(socket.id);
+                if (!projectSlug) {
+                    socket.emit('session:summary-result', { messageUuid, error: 'Session project not found' });
+                    return;
+                }
+                const filePath = sessionService.getSessionFilePath(projectSlug, sessionId);
+                const rawMessages = await parseJSONLFile(filePath);
+                // Find messageUuid index
+                const targetIdx = rawMessages.findIndex((m) => m.uuid === messageUuid);
+                if (targetIdx === -1) {
+                    socket.emit('session:summary-result', { messageUuid, error: 'Message not found' });
+                    return;
+                }
+                // Extract messages AFTER the target (not including it)
+                const afterMessages = rawMessages
+                    .slice(targetIdx + 1)
+                    .filter((m) => (m.type === 'user' || m.type === 'assistant') && m.message)
+                    .map((m) => ({
+                    role: m.message.role,
+                    content: typeof m.message.content === 'string'
+                        ? m.message.content
+                        : m.message.content
+                            .filter((b) => b.type === 'text' && b.text)
+                            .map((b) => b.text)
+                            .join('\n'),
+                }))
+                    .filter((m) => m.content.length > 0);
+                // Min message guard: need at least 2 pairs (4 messages)
+                if (afterMessages.length < 4) {
+                    socket.emit('session:summary-result', { messageUuid, error: 'Too few messages to summarize' });
+                    return;
+                }
+                // Resolve project originalPath for Agent SDK cwd
+                let cwd;
+                try {
+                    cwd = await projectService.resolveOriginalPath(projectSlug);
+                }
+                catch (err) {
+                    log.warn(`Failed to resolve originalPath for ${projectSlug}, summarize will proceed without cwd:`, err);
+                }
+                log.info(`session:generate-summary sessionId=${sessionId}, messageUuid=${messageUuid}, targetMessages=${afterMessages.length}`);
+                const summary = await summarize(afterMessages, {
+                    signal: abortController.signal,
+                    locale: lang !== 'en' ? lang : undefined,
+                    cwd,
+                    projectSlug,
+                });
+                socket.emit('session:summary-result', { requestId, messageUuid, summary });
+            }
+            catch (err) {
+                if (abortController.signal.aborted) {
+                    // Cancelled — don't emit error
+                    return;
+                }
+                const msg = err instanceof Error ? err.message : String(err);
+                log.error(`session:generate-summary error: ${msg}`);
+                socket.emit('session:summary-result', { requestId, messageUuid, error: msg });
+            }
+            finally {
+                // Only clean up if this request is still the active one
+                const current = socketSummarizing.get(socket.id);
+                if (current?.activeRequestId === requestId) {
+                    socketSummarizing.set(socket.id, { activeRequestId: null, abortController: null });
+                }
+            }
+        });
+        // Story 25.9: Cancel ongoing summary
+        socket.on('session:cancel-summary', (data) => {
+            if (!data || typeof data !== 'object')
+                return;
+            const { sessionId } = data;
+            if (!sessionId || typeof sessionId !== 'string')
+                return;
+            // Only cancel if socket is in the session room (prevents cross-session cancel)
+            if (!socket.rooms.has(`session:${sessionId}`))
+                return;
+            const state = socketSummarizing.get(socket.id);
+            if (state?.abortController) {
+                state.abortController.abort();
+                socketSummarizing.set(socket.id, { activeRequestId: null, abortController: null });
+            }
+        });
+        // Story 27.3: Branch viewer mode — switch branch via custom selections
+        socket.on('messages:switch-branch', async (data) => {
+            try {
+                if (!data || typeof data !== 'object')
+                    return;
+                const { sessionId, branchSelections } = data;
+                if (!sessionId || typeof sessionId !== 'string')
+                    return;
+                // Validate branchSelections shape: must be a plain object with non-negative integer values
+                if (branchSelections != null) {
+                    if (typeof branchSelections !== 'object' || Array.isArray(branchSelections)) {
+                        socket.emit('error', { code: 'INVALID_DATA', message: 'Invalid branchSelections format' });
+                        return;
+                    }
+                    for (const val of Object.values(branchSelections)) {
+                        if (typeof val !== 'number' || !Number.isInteger(val) || val < 0) {
+                            socket.emit('error', { code: 'INVALID_DATA', message: 'Invalid branch selection value' });
+                            return;
+                        }
+                    }
+                }
+                // Validate socket is in the session room
+                if (!socket.rooms.has(`session:${sessionId}`)) {
+                    socket.emit('error', { code: 'NOT_IN_SESSION', message: 'Not joined to session' });
+                    return;
+                }
+                // Guard: reject during active streaming
+                if (activeStreams.has(sessionId)) {
+                    socket.emit('error', { code: 'STREAMING_ACTIVE', message: 'Cannot switch branches during streaming' });
+                    return;
+                }
+                const projectSlug = sessionProjectMap.get(sessionId) || socketProjectRoom.get(socket.id);
+                if (!projectSlug) {
+                    socket.emit('error', { code: 'PROJECT_NOT_FOUND', message: 'Session project not found' });
+                    return;
+                }
+                const historyMessages = await sessionBufferManager.reloadFromJSONL(sessionId, projectSlug, branchSelections);
+                socket.emit('stream:history', { sessionId, messages: historyMessages });
+            }
+            catch (err) {
+                log.error('messages:switch-branch error:', err);
+                socket.emit('error', { code: 'BRANCH_SWITCH_ERROR', message: 'Failed to switch branch' });
+            }
+        });
         // Story 20.1: Dashboard subscribe/unsubscribe
         socket.on('dashboard:subscribe', () => {
             socket.join('dashboard');
@@ -1250,11 +1627,7 @@ export async function initializeWebSocket(httpServer) {
             const qs = getOrCreateQueueService(data.projectSlug);
             qs.cancelPause();
         });
-        // eslint-disable-next-line @typescript-eslint/no-explicit-any
-        socket.on('queue:dismiss', (data) => {
-            const qs = getOrCreateQueueService(data.projectSlug);
-            qs.dismiss();
-        });
+        // queue:dismiss moved to HTTP POST — see queueController.dismissQueue
         socket.on('queue:removeItem', (data) => {
             const qs = getOrCreateQueueService(data.projectSlug);
             qs.removeItem(data.itemIndex);
@@ -1449,6 +1822,24 @@ export async function initializeWebSocket(httpServer) {
                 }
                 socketToSession.delete(socket.id);
             }
+            // Story 27.1: Destroy buffer when no sockets remain in the session room
+            const disconnectSessionId = sessionId || socketSessionRoom.get(socket.id);
+            if (disconnectSessionId) {
+                // Socket.io removes the socket from rooms before calling disconnect,
+                // so rooms.get() already reflects the post-disconnect state.
+                const remaining = io.sockets.adapter.rooms.get(`session:${disconnectSessionId}`);
+                if (!remaining || remaining.size === 0) {
+                    // Only destroy if no active stream (streaming continues in background)
+                    if (!activeStreams.has(disconnectSessionId)) {
+                        sessionBufferManager.destroy(disconnectSessionId);
+                    }
+                    // Notify session list viewers when no sockets remain for this session
+                    const slug = socketProjectRoom.get(socket.id) || sessionProjectMap.get(disconnectSessionId);
+                    if (slug) {
+                        io.to(`project:${slug}`).emit('session:waiting-change', { sessionId: disconnectSessionId, waiting: false, projectSlug: slug });
+                    }
+                }
+            }
             socketSessionRoom.delete(socket.id);
             // Release queue edit lock only if this socket owns it
             const disconnectProjectSlug = socketProjectRoom.get(socket.id);
@@ -1459,6 +1850,12 @@ export async function initializeWebSocket(httpServer) {
                 }
             }
             socketProjectRoom.delete(socket.id);
+            // Story 25.9: Cleanup summarizing state on disconnect
+            const sumState = socketSummarizing.get(socket.id);
+            if (sumState?.abortController) {
+                sumState.abortController.abort();
+            }
+            socketSummarizing.delete(socket.id);
             // PTY sessions are NOT cleaned up on socket disconnect.
             // They persist until explicitly closed by the user, the PTY process exits,
             // or the server shuts down. This prevents losing long-running terminal
@@ -1524,7 +1921,7 @@ function validateImages(images, lang) {
 async function handleChatSend(stream, data, abortController, lang) {
     const emit = createStreamEmit(stream);
     const t = i18next.getFixedT(lang);
-    const { content, workingDirectory, sessionId, resume, permissionMode, model, images, effort } = data;
+    const { content, workingDirectory, sessionId, resume, permissionMode, model, images, effort, resumeSessionAt: rawResumeSessionAt, forkSession, rewindToMessageUuid } = data;
     // Validate images if present (Story 5.5)
     if (images && images.length > 0) {
         const validation = validateImages(images, lang);
@@ -1546,22 +1943,106 @@ async function handleChatSend(stream, data, abortController, lang) {
     }
     // Buffer the user's message so reconnecting clients can display it
     // (SDK may not have written the JSONL file yet at reconnect time).
-    // Include timestamp for correct ordering. For images, only send count
-    // (not full base64 data) to avoid bloating the buffer.
-    emit('user:message', {
-        content,
-        sessionId: sessionId || '',
-        timestamp: new Date().toISOString(),
-        ...(images && images.length > 0 ? { imageCount: images.length } : {}),
-    });
-    const isResuming = resume && sessionId;
+    // Skip for fork sessions — the fork prompt is delivered via SessionBufferManager
+    // (stream:history event) instead, avoiding duplicate user messages on the client.
+    // Shared instance — reused for image storage, root-branch resolution, and fork-history below.
     const sessionService = new SessionService();
+    const projectSlug = sessionService.encodeProjectPath(workingDirectory);
+    // Story 27.2: Store images as files, emit URL-based ImageRef[] instead of base64.
+    if (!forkSession) {
+        let imageRefs;
+        if (images && images.length > 0) {
+            imageRefs = await imageStorageService.storeImages(projectSlug, sessionId || '', images);
+        }
+        emit('user:message', {
+            content,
+            sessionId: sessionId || '',
+            timestamp: new Date().toISOString(),
+            ...(imageRefs && imageRefs.length > 0 ? { images: imageRefs } : {}),
+        });
+    }
+    const isResuming = resume && sessionId;
+    // Story 25.7: resumeSessionAt/rewindToMessageUuid require a valid resume flow
+    // Story 25.11: forkSession also requires resume context (SDK needs original session to read)
+    if ((rawResumeSessionAt || rewindToMessageUuid || forkSession) && !isResuming) {
+        emit('error', {
+            code: ERROR_CODES.VALIDATION_ERROR,
+            message: t('ws.error.resumeSessionAtRequiresResume', { defaultValue: 'resumeSessionAt, rewindToMessageUuid, and forkSession require resume=true and a valid sessionId' }),
+        });
+        return false;
+    }
+    // Root-level edit branching is not supported — the SDK's --resume-session-at
+    // only accepts assistant message UUIDs, and there is no assistant before the
+    // first user message. The client should not send ROOT_BRANCH_KEY; reject if received.
+    let resumeSessionAt = rawResumeSessionAt;
+    if (resumeSessionAt === ROOT_BRANCH_KEY) {
+        emit('error', {
+            code: ERROR_CODES.VALIDATION_ERROR,
+            message: 'Root-level edit branching is not supported',
+        });
+        return false;
+    }
+    // Story 25.11 + 27.1: Cache fork history from original session JSONL into
+    // SessionBufferManager before SDK starts. The new session's JSONL may not
+    // exist yet when the client navigates, so we store it in the buffer and
+    // deliver via stream:history on session:join.
+    if (forkSession && sessionId && resumeSessionAt) {
+        try {
+            const filePath = sessionService.getSessionFilePath(projectSlug, sessionId);
+            if (existsSync(filePath)) {
+                const rawMessages = await parseJSONLFile(filePath);
+                const tree = buildRawMessageTree(rawMessages);
+                // Find the branch path that contains the fork point message
+                const selections = findBranchSelectionsForUuid(tree.roots, resumeSessionAt)
+                    ?? getDefaultRawBranchSelections(tree.roots);
+                const { messages: activeBranchRaw } = getActiveRawBranch(tree.roots, selections);
+                const transformed = transformToHistoryMessages(activeBranchRaw, projectSlug, sessionId);
+                // Truncate at the resumeSessionAt message (the fork branch point).
+                const forkIdx = transformed.findIndex(m => m.id === resumeSessionAt || m.id.startsWith(resumeSessionAt + '-'));
+                const forkHistory = forkIdx >= 0
+                    ? transformed.slice(0, forkIdx + 1)
+                    : transformed;
+                // Append the fork user prompt so the client sees it as part of the history.
+                forkHistory.push({
+                    id: `fork-user-${Date.now()}`,
+                    type: 'user',
+                    content,
+                    timestamp: new Date().toISOString(),
+                });
+                // Store in SessionBufferManager (buffer was already created by chat:send handler)
+                sessionBufferManager.setMessages(stream.sessionId, forkHistory);
+                log.debug(`Fork history cached in buffer: ${forkHistory.length} messages from session ${sessionId}`);
+            }
+        }
+        catch (err) {
+            log.warn('Failed to cache fork history:', err);
+        }
+    }
     let timeoutId = null;
+    // Snapshot JSONL files before SDK query to detect phantom checkpoint files.
+    // The SDK's file checkpointing creates separate JSONL files (new UUIDs) with
+    // only file-history-snapshot entries alongside the real session file. These
+    // are redundant copies of checkpoint state already present in the session
+    // file and are not needed for rewindFiles() to function.
+    let preQueryFiles = null;
+    try {
+        const projectDir = sessionService.getProjectDir(projectSlug);
+        if (existsSync(projectDir)) {
+            preQueryFiles = new Set(readdirSync(projectDir).filter(f => f.endsWith('.jsonl')));
+        }
+    }
+    catch {
+        // Non-critical — cleanup will be skipped if snapshot fails
+    }
     try {
         const chatService = new ChatService({ workingDirectory, permissionMode });
         stream.chatService = chatService;
         // Load preferences early for advanced settings + timeout
         const effectivePrefs = await preferencesService.getEffectivePreferences();
+        // Clamp 'max' effort to 'high' for non-Opus 4.6 models
+        const resolvedEffort = effort ?? effectivePrefs.defaultEffort;
+        const isOpus46 = model && (model === 'claude-opus-4-6' || model === 'opus' || model.includes('opus-4-6'));
+        const effectiveEffort = resolvedEffort === 'max' && !isOpus46 ? 'high' : resolvedEffort;
         const chatOptions = {
             ...(isResuming ? { resume: sessionId } : { sessionId }),
             abortController,
@@ -1572,11 +2053,13 @@ async function handleChatSend(stream, data, abortController, lang) {
             maxThinkingTokens: effectivePrefs.maxThinkingTokens,
             maxTurns: effectivePrefs.maxTurns,
             maxBudgetUsd: effectivePrefs.maxBudgetUsd,
-            // Strip 'max' effort for Claude.ai subscribers (CLI exits with code 1)
-            effort: (() => {
-                const e = effort ?? effectivePrefs.defaultEffort;
-                return (e === 'max' && rateLimitProbeService.hasOAuthCredentials()) ? 'high' : e;
-            })(),
+            effort: effectiveEffort,
+            // Story 25.7: conversation branching via resumeSessionAt
+            ...(resumeSessionAt ? { resumeSessionAt } : {}),
+            // Story 25.11: fork session — create new session from branch point
+            ...(forkSession ? { forkSession: true } : {}),
+            enableFileCheckpointing: true,
+            ...(rewindToMessageUuid ? { rewindToMessageUuid } : {}),
         };
         // Create canUseTool callback for permission & AskUserQuestion handling
         // Promise stays pending if socket disconnected — SDK naturally waits
@@ -1588,6 +2071,19 @@ async function handleChatSend(stream, data, abortController, lang) {
                 log.debug('Auto-approving ExitPlanMode: current permissionMode is bypassPermissions');
                 return { behavior: 'allow', updatedInput: input };
             }
+            // Auto-approve CLI safety checks in Bypass mode when user preference is enabled.
+            // The CLI sends safety check prompts even in bypass mode for certain tools (e.g. Write).
+            // When autoApproveSafetyChecks is true, skip the permission UI for non-interactive tools.
+            if (toolName !== 'AskUserQuestion' && chatService.getPermissionMode() === 'bypassPermissions') {
+                try {
+                    const prefs = await preferencesService.readPreferences();
+                    if (prefs.autoApproveSafetyChecks ?? true) {
+                        log.debug(`Auto-approving safety check for ${toolName}: autoApproveSafetyChecks enabled`);
+                        return { behavior: 'allow', updatedInput: input };
+                    }
+                }
+                catch { /* fall through to normal permission flow */ }
+            }
             const isAskUserQuestion = toolName === 'AskUserQuestion';
             const requestId = options.toolUseID || `perm-${++permissionRequestCounter}`;
             log.debug(`canUseTool called: tool=${toolName}, toolUseID=${options.toolUseID}, requestId=${requestId}`);
@@ -1661,6 +2157,7 @@ async function handleChatSend(stream, data, abortController, lang) {
             emit,
             stream,
             isResuming: !!isResuming,
+            isFork: !!forkSession,
             initialSessionId: sessionId,
             rekeyStream: (sid) => rekeyStream(stream, sid),
             broadcastStreamChange,
@@ -1680,6 +2177,18 @@ async function handleChatSend(stream, data, abortController, lang) {
             hasEmittedOutput = true;
             origOnSessionInit?.(sid, metadata);
         };
+        // Defer completion until JSONL is flushed — keeps client in streaming state.
+        // Usage data is stored and included in stream:complete-messages.
+        const baseOnComplete = callbacks.onComplete;
+        callbacks.onComplete = (response) => {
+            if (response.usage) {
+                stream.deferredUsage = response.usage;
+                emit('context:usage', response.usage);
+            }
+            if (notificationService.shouldNotify(stream.sockets.size)) {
+                notificationService.notifyComplete(stream.sessionId, response.content);
+            }
+        };
         // Browser-only callbacks
         callbacks.onActivity = (messageType) => {
             resetTimeout(`onActivity:${messageType}`);
@@ -1753,9 +2262,13 @@ async function handleChatSend(stream, data, abortController, lang) {
             // SDK may return "No conversation found" as an error result (not a thrown exception).
             // Convert to a thrown error so the retry logic below can handle it.
             if (sendResult.isError && isResumeAttempt && !abortController.signal.aborted && !hasEmittedOutput) {
-                log.info(`[RESUME-RETRY] SDK returned error result while resuming, converting to thrown error for retry`);
+                log.info(`[RESUME-RETRY] SDK returned error result while resuming, converting to thrown error for retry. result="${(sendResult.content || '').slice(0, 200)}"`);
                 throw new Error(sendResult.content || 'Resume returned error result');
             }
+            // Story 25.7: warn client if file rewind failed (non-fatal)
+            if (chatService.rewindWarning) {
+                emit('error', { code: 'REWIND_WARNING', message: chatService.rewindWarning });
+            }
             // Resume succeeded or non-resume — flush any gated events
             ungateCallbacks();
             if (gatedResultError)
@@ -1775,7 +2288,8 @@ async function handleChatSend(stream, data, abortController, lang) {
             if (isResumeAttempt
                 && !abortController.signal.aborted
                 && !hasEmittedOutput
-                && !isNonSessionError) {
+                && !isNonSessionError
+                && !chatOptions.resumeSessionAt) {
                 log.info(`[RESUME-RETRY] resume failed, retrying without resume: sessionId=${sessionId}, error=${parsedError.message.slice(0, 120)}`);
                 // Discard gated events and restore original callbacks for the retry
                 gatedResultError = null;
@@ -1784,8 +2298,7 @@ async function handleChatSend(stream, data, abortController, lang) {
                 // Delete stale session file from the aborted first send so the SDK
                 // can create a fresh session with the same ID (avoids "Session ID already in use").
                 if (sessionId) {
-                    const encoded = sessionService.encodeProjectPath(workingDirectory);
-                    const staleFile = sessionService.getSessionFilePath(encoded, sessionId);
+                    const staleFile = sessionService.getSessionFilePath(projectSlug, sessionId);
                     try {
                         if (existsSync(staleFile)) {
                             unlinkSync(staleFile);
@@ -1796,8 +2309,9 @@ async function handleChatSend(stream, data, abortController, lang) {
                         log.warn(`[RESUME-RETRY] failed to delete stale session file: ${staleFile}`, e);
                     }
                 }
-                const retryOptions = { ...chatOptions, resume: undefined, sessionId };
+                const retryOptions = { ...chatOptions, resume: undefined, resumeSessionAt: undefined, sessionId };
                 delete retryOptions.resume;
+                delete retryOptions.resumeSessionAt;
                 resetTimeout('resume-retry');
                 await chatService.sendMessageWithCallbacks(content, callbacks, retryOptions, canUseTool, (messageType) => {
                     resetTimeout(`raw:${messageType}`);
@@ -1838,6 +2352,40 @@ async function handleChatSend(stream, data, abortController, lang) {
         if (timeoutId) {
             clearTimeout(timeoutId);
         }
+        // Delete phantom checkpoint files created by SDK file checkpointing.
+        // These are separate JSONL files (new UUIDs) containing only
+        // file-history-snapshot entries. The same snapshot data already exists
+        // in the actual session file, so these are redundant and not needed
+        // for rewindFiles() to function.
+        if (preQueryFiles) {
+            try {
+                const projectDir = sessionService.getProjectDir(projectSlug);
+                const postQueryFiles = readdirSync(projectDir).filter(f => f.endsWith('.jsonl'));
+                // Skip the active session's JSONL — for new sessions, the SDK creates
+                // this file during the query so it's not in preQueryFiles, but it's
+                // the real session file, not a phantom checkpoint.
+                const activeSessionFile = `${stream.sessionId}.jsonl`;
+                for (const file of postQueryFiles) {
+                    if (preQueryFiles.has(file) || file === activeSessionFile)
+                        continue;
+                    const filePath = `${projectDir}/${file}`;
+                    try {
+                        const raw = readFileSync(filePath, 'utf8');
+                        const hasConversation = raw.includes('"type":"user"') || raw.includes('"type":"assistant"');
+                        if (!hasConversation) {
+                            unlinkSync(filePath);
+                            log.info(`Deleted phantom checkpoint file: ${file}`);
+                        }
+                    }
+                    catch {
+                        // Skip unreadable files
+                    }
+                }
+            }
+            catch (cleanupErr) {
+                log.warn('Failed to clean up phantom checkpoint files:', cleanupErr);
+            }
+        }
     }
 }
 //# sourceMappingURL=websocket.js.map