hammoc 1.8.4 → 1.9.0

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

@@ -7,11 +7,15 @@
 import { Server as SocketIOServer } from 'socket.io';
 import { existsSync, unlinkSync, readFileSync, readdirSync, statSync } from 'fs';
 import { randomUUID } from 'crypto';
-import { ERROR_CODES, IMAGE_CONSTRAINTS, parseQueueScript, TERMINAL_ERRORS, ROOT_BRANCH_KEY, effectiveModelIs1M } from '@hammoc/shared';
+import { ERROR_CODES, IMAGE_CONSTRAINTS, PDF_CONSTRAINTS, ATTACHMENT_TOTAL_MAX_SIZE_BYTES, parseQueueScript, TERMINAL_ERRORS, ROOT_BRANCH_KEY, effectiveModelIs1M, DEFAULT_PREFERENCES } from '@hammoc/shared';
 import i18next from '../i18n.js';
 import { SUPPORTED_LANGUAGES } from '@hammoc/shared';
 import { isLocalIP, extractClientIP } from '../utils/networkUtils.js';
+import { denyBackgroundBash } from '../utils/backgroundToolGuard.js';
 import { createChatEngine } from '../services/chatEngineFactory.js';
+import { EngineResidencyRegistry } from '../services/engineResidencyRegistry.js';
+import { normalizeResidencyConfig } from '../utils/residencyPolicy.js';
+import { shouldReuseResidentEngine, shouldRegisterOnCreate } from '../utils/residencyActivation.js';
 import { SessionService, sessionService } from '../services/sessionService.js';
 import { parseSDKError, AbortedError, SDKErrorCode } from '../utils/errors.js';
 import { createSessionMiddleware } from '../middleware/session.js';
@@ -22,6 +26,7 @@ import { getOrCreateQueueService, getQueueInstances } from '../controllers/queue
 import { createLogger } from '../utils/logger.js';
 import { clampEffortForModel, supportsAdaptiveThinking } from '../utils/effortUtils.js';
 import { shouldForwardCliProgress, shouldForwardCliPtyMirror } from '../utils/cliEngineUtils.js';
+import { resolveStopStrategy, shouldSuppressResultError, shouldNotifyComplete, shouldRetryResumeAfterError, shouldWaitForBackgroundTasks, } from '../utils/stopStrategy.js';
 import { getCliScreen, getCliScreenStall, setCliScreenStall, deleteCliScreen } from '../services/cliScreenCache.js';
 import { createScreenStallWatchdog } from '../services/cliScreenStallWatchdog.js';
 import { modelMissingNative1MSupport } from '../utils/bundledBinaryModelSupport.js';
@@ -35,7 +40,8 @@ import { dashboardService } from '../services/dashboardService.js';
 import { fileWatcherService } from '../services/fileWatcherService.js';
 import { summarize } from '../services/summarizeService.js';
 import { parseJSONLFile, transformToHistoryMessages } from '../services/historyParser.js';
-import { buildRawMessageTree, getActiveRawBranch, getDefaultRawBranchSelections, findBranchSelectionsForUuid } from '../utils/messageTree.js';
+import { waitForBackgroundTasksAndFollowUp } from '../utils/backgroundTaskPoller.js';
+import { buildRawMessageTree, getActiveRawBranch, getDefaultRawBranchSelections, findBranchSelectionsForUuid, repairPostCompactParenting } from '../utils/messageTree.js';
 import { sessionBufferManager } from '../services/sessionBufferManager.js';
 import { imageStorageService } from '../services/imageStorageService.js';
 import { isSnippetRef, resolveSnippet, listSnippets, SnippetError } from '../utils/snippetResolver.js';
@@ -103,6 +109,74 @@ let connectedClients = 0;
 // Primary maps: sessionId → ActiveStream, socketId → sessionId
 const activeStreams = new Map();
 const socketToSession = new Map();
+// ── Story 38.7: engine residency ACTIVATION ──────────────────────────────────
+// Turn-boundary process residency (Story 38.5 delivered the registry + resource
+// policy as a "ready seam"; this story wires it into the turn flow). One SDK engine
+// process is kept alive per active session so a follow-up turn REUSES it (no ~3s
+// re-spawn) instead of re-creating one. It is ALWAYS activated together with the
+// bounds (idle sweep + LRU cap) so idle sessions cannot accumulate processes
+// ("무정책 상주 금지"); the CLI (PTY) lifecycle is untouched (SDK-engine only).
+//
+// The registry's getConfig must be SYNCHRONOUS (register/sweep call it inline), but
+// preferences load async — so we hold a snapshot refreshed from the preferences
+// `handleChatSend` already reads every send (+ once at bootstrap). A missing/absent
+// pref falls back to the DEFAULT (never 0 → the sweep/cap can never be silently
+// disabled by an old preferences file that predates these keys).
+let residencyConfig = normalizeResidencyConfig({
+    idleTimeoutMs: DEFAULT_PREFERENCES.sdkIdleTimeoutMs,
+    maxEngines: DEFAULT_PREFERENCES.sdkMaxResidentEngines,
+});
+function refreshResidencyConfig(prefs) {
+    residencyConfig = normalizeResidencyConfig({
+        idleTimeoutMs: prefs.sdkIdleTimeoutMs ?? DEFAULT_PREFERENCES.sdkIdleTimeoutMs,
+        maxEngines: prefs.sdkMaxResidentEngines ?? DEFAULT_PREFERENCES.sdkMaxResidentEngines,
+    });
+}
+// The third arg lets the idle sweep / LRU eviction see which sessions have a turn
+// in progress (status === 'running') and skip them: a mid-flight turn is alive even
+// when its activity clock is stale (the clock ticks only at turn start), so without
+// this guard a turn outliving the idle timeout — a slow tool run, or an
+// AskUserQuestion awaiting the user — would be evicted while streaming and killed.
+const engineResidency = new EngineResidencyRegistry(() => residencyConfig, undefined, (sessionId) => activeStreams.get(sessionId)?.status === 'running');
+/**
+ * Server shutdown hook: stop the idle sweep and close every resident SDK engine
+ * (clean control-channel teardown). Idempotent; safe if residency never started.
+ */
+export async function shutdownEngineResidency() {
+    await engineResidency.stop();
+}
+/**
+ * Evict + close the resident SDK engine for `sessionId`, if any (idempotent,
+ * no-op on a miss). For OUT-OF-BAND writers on a session's JSONL — the queue
+ * executor resuming a session, or session deletion. A parked resident engine
+ * keeps the conversation in PROCESS MEMORY; letting another engine append turns
+ * to the same JSONL would fork the on-disk history from what the resident
+ * engine believes, so the writer must evict first (the next chat send then
+ * resumes fresh from JSONL and sees the appended turns).
+ */
+export async function evictResidentEngine(sessionId) {
+    await engineResidency.remove(sessionId);
+}
+/**
+ * Whether a session JSONL already holds real conversation turns (same heuristic
+ * as the phantom-checkpoint cleanup in handleChatSend's finally). The resume-retry
+ * branch DELETES the target file before retrying fresh (clears "Session ID already
+ * in use") — that recovery is designed for the conversation-less stub an aborted
+ * first send leaves behind. A file with real history must never be wiped by it
+ * (e.g. a resident engine dying between turns fails the resume the same way).
+ * Fail-safe: an unreadable file is treated as real history — never delete blind.
+ */
+function sessionFileHasConversation(filePath) {
+    try {
+        if (!existsSync(filePath))
+            return false;
+        const raw = readFileSync(filePath, 'utf8');
+        return raw.includes('"type":"user"') || raw.includes('"type":"assistant"');
+    }
+    catch {
+        return true;
+    }
+}
 // Story 24.3: Track which session room each socket joined (for session:leave room management)
 const socketSessionRoom = new Map();
 // Track which project room each socket joined (for leave on session switch)
@@ -296,6 +370,15 @@ function scheduleChainDrain(sessionId, lang) {
             const drainSuccess = await handleChatSend(stream, { content: nextItem.content, workingDirectory, sessionId, resume: chainResumableSessions.has(sessionId) || undefined, permissionMode, model, effort }, abortController, lang);
             if (!drainSuccess)
                 throw new Error('handleChatSend returned false');
+            // Background tasks pending at end_turn hold the chain too — advancing
+            // now would start the next item while this one is still working.
+            // (markMainEnded here for the same reason as the chat:send path: the
+            // browser onComplete replacement swallows the streamCallbacks-level one.)
+            stream.backgroundTracker?.markMainEnded();
+            if (stream.backgroundTracker?.isWaiting) {
+                const drainBgSlug = sessionProjectMap.get(sessionId) ?? null;
+                await waitForBackgroundTasks(stream.backgroundTracker, sessionId, drainBgSlug, abortController.signal, stream.streamCallbacks);
+            }
             // Success: mark as 'sent' and remove from chain
             nextItem.status = 'sent';
             chainResumableSessions.add(sessionId);
@@ -418,11 +501,18 @@ function createStreamEmit(stream) {
         }
     };
 }
-/** Get session IDs of all currently running active streams */
-export function getActiveStreamSessionIds() {
-    return [...activeStreams.entries()]
-        .filter(([, stream]) => stream.status === 'running')
-        .map(([key]) => key);
+/**
+ * Session ids of all currently running streams mapped to their turn start time (ms).
+ * The session list uses this to treat a streaming session's "last activity" as live —
+ * the on-disk index timestamp is only refreshed at turn end and is stale mid-turn.
+ */
+export function getActiveStreamStartTimes() {
+    const out = new Map();
+    for (const [key, stream] of activeStreams.entries()) {
+        if (stream.status === 'running')
+            out.set(key, stream.startedAt);
+    }
+    return out;
 }
 /**
  * Running streams for a project, with their captured first prompt. Used by the
@@ -449,7 +539,9 @@ export function getActiveSessionCountsByProject() {
     for (const [sessionId, stream] of activeStreams.entries()) {
         if (stream.status !== 'running')
             continue;
-        const slug = sessionProjectMap.get(sessionId);
+        // Prefer the synchronously-captured stream.projectSlug — sessionProjectMap is
+        // populated async and misses streams that just started (same as meta lookup).
+        const slug = stream.projectSlug ?? sessionProjectMap.get(sessionId);
         if (slug) {
             counts.set(slug, (counts.get(slug) ?? 0) + 1);
         }
@@ -593,6 +685,34 @@ async function pollFileStabilityThenReload(sessionId, projectSlug) {
     log.info(`pollFileStability: session=${sessionId}, elapsed=${Date.now() - startedAt}ms, stable=${stableCount >= FILE_POLL_STABLE_COUNT}`);
     return sessionBufferManager.reloadFromJSONL(sessionId, projectSlug);
 }
+/**
+ * Wait for all background tasks to complete by watching the session JSONL.
+ * The engine returns from `query()` at end_turn while background tasks
+ * (Bash/Agent run_in_background, engine-initiated async agents) are still
+ * running, then auto-resumes generation in the same session when they finish.
+ * The shared poller resolves pendings, registers launches that happen inside
+ * follow-up generations (e.g. SendMessage re-engaging an agent), and holds the
+ * turn open until the follow-up reaches end_turn.
+ *
+ * @returns true when settled, false on abort/timeout
+ */
+async function waitForBackgroundTasks(tracker, sessionId, projectSlug, abortSignal, callbacks) {
+    if (!tracker.isWaiting)
+        return true;
+    const slug = projectSlug ?? new SessionService().encodeProjectPath('');
+    if (!slug) {
+        log.warn(`[BG-WAIT] no projectSlug for session ${sessionId}, cannot poll JSONL — skipping wait`);
+        return false;
+    }
+    const filePath = new SessionService().getSessionFilePath(slug, sessionId);
+    return waitForBackgroundTasksAndFollowUp({
+        filePath,
+        tracker,
+        abortSignal,
+        callbacks,
+        logPrefix: `[BG-WAIT ${sessionId.slice(0, 8)}]`,
+    });
+}
 /** Clean up a stream from activeStreams immediately.
  *  Story 27.1: SessionBufferManager retains the messages; no completedBuffer needed. */
 function cleanupStream(streamKey, expectedStream) {
@@ -619,6 +739,40 @@ function cleanupStream(streamKey, expectedStream) {
         }
     }
 }
+/**
+ * Story 38.7: stop a running turn's generation on `stream`, routing to the primitive
+ * that actually reaches the engine.
+ *
+ * On a RESIDENT SDK engine the per-turn abortController is not wired to the
+ * (turn-1-created) live query, and `processStream` never polls the abort signal — so a
+ * reused turn-2+ generation can ONLY be stopped by `interrupt()` (turn-only; the
+ * session/generator survives so the next send continues). A hard abort is kept for the
+ * CLI engine (PTY Ctrl+C rides the abortController) or an SDK engine whose query isn't
+ * up yet (`resolveStopStrategy` decides). If interrupt() throws on a resident engine —
+ * where abort cannot reach its live query — the engine is closed via the registry to
+ * unstick the parked stream and force a fresh resume on the next send.
+ *
+ * The CALLER sets the outcome flag BEFORE calling: `userInterrupted` for a
+ * keep-the-session stop (Stop button, chain cancel) or `timedOut` for a
+ * treat-as-failure stop (inactivity timeout). This function only decides HOW
+ * generation stops, not the turn's success / eviction outcome.
+ */
+function requestTurnStop(stream, reason) {
+    const svc = stream.chatService;
+    const strategy = resolveStopStrategy({ engineMode: stream.engineMode, canInterrupt: !!svc?.interrupt });
+    if (strategy === 'interrupt') {
+        Promise.resolve(svc.interrupt()).catch((err) => {
+            log.warn(`interrupt() failed for session ${stream.sessionId} (${reason}), hard aborting + evicting: ${err instanceof Error ? err.message : String(err)}`);
+            stream.abortController.abort(reason);
+            // A resident live query is unreachable by abort — close it so the parked stream
+            // unwinds and the next send resumes fresh from JSONL (crash-reconnect path).
+            void engineResidency.remove(stream.sessionId);
+        });
+    }
+    else {
+        stream.abortController.abort(reason);
+    }
+}
 /** Normalize legacy 'never' sync policy to 'streaming' */
 function normalizeSyncPolicy(policy) {
     return policy === 'streaming' ? 'streaming' : 'always';
@@ -711,6 +865,24 @@ export function rekeyStream(stream, newSessionId) {
         sock.leave(`session:${oldSessionId}`);
         sock.join(`session:${newSessionId}`);
     }
+    // Story 38.7: mirror the residency entry onto the SDK-assigned id.
+    //  · fork — a fork is a NEW query for a NEW session; register it under the assigned
+    //    id WITHOUT disturbing the ORIGINAL session's resident entry (rekey would move
+    //    the original's engine, which must stay independent). Registering here (during
+    //    the send, before the callback path's turn-end close) is also what makes the
+    //    fork engine resident so it survives into the forked session's next turn.
+    //  · non-fork — the SDK confirmed a (possibly different) id for the SAME session;
+    //    move the resident entry from the old key to the new one.
+    // No-op for a CLI engine (register is a feature-detect no-op; nothing registered
+    // under the old key for rekey to move).
+    if (stream.chatService && stream.engineMode === 'sdk') {
+        if (stream.isFork) {
+            void engineResidency.register(newSessionId, stream.chatService, stream.engineMode);
+        }
+        else {
+            engineResidency.rekey(oldSessionId, newSessionId);
+        }
+    }
 }
 /**
  * Mark a stream as completed and broadcast stream-change.
@@ -776,6 +948,27 @@ function emitQuestionChange(sessionId, hasPendingQuestion) {
         triggerDashboardStatusChange(projectSlug);
     }
 }
+/**
+ * Story 38.3: settle and clear every pending permission / AskUserQuestion for a
+ * stream. On Stop (interrupt or abort) the `canUseTool` gate may be parked awaiting a
+ * user response that will now never come — resolving each as "denied" unblocks that
+ * awaited promise (so the SDK isn't left waiting on a permission), and clearing the
+ * map prevents a leak. Also clears the question badge. No-op when nothing is pending.
+ */
+function settleStreamPermissions(stream, sessionId) {
+    if (stream.pendingPermissions.size === 0)
+        return;
+    for (const pending of stream.pendingPermissions.values()) {
+        try {
+            pending.resolve({ approved: false });
+        }
+        catch {
+            /* already settled */
+        }
+    }
+    stream.pendingPermissions.clear();
+    emitQuestionChange(sessionId, false);
+}
 /**
  * Broadcast session:stream-change to project room (or all clients as fallback).
  * Used by queue service to signal stream start/end.
@@ -819,6 +1012,17 @@ export async function initializeWebSocket(httpServer) {
         cors: config.cors,
         maxHttpBufferSize: 100 * 1024 * 1024, // 100MB for base64 image payloads
     });
+    // Story 38.7: seed the residency config from disk and begin the periodic idle
+    // sweep. Activation without the sweep would let resident engines accumulate
+    // unbounded — starting it here is the mandatory other half of "무정책 상주 금지".
+    // The sweep timer is unref'd (never keeps the process alive on its own).
+    try {
+        refreshResidencyConfig(await preferencesService.getEffectivePreferences());
+    }
+    catch {
+        // Fall back to the DEFAULT-derived config already in `residencyConfig`.
+    }
+    engineResidency.start();
     // Mirror project-room membership into fileWatcherService so every code path
     // that calls socket.join/leave with a `project:<slug>` room transparently
     // starts or stops the chokidar watcher for that project. socket.io emits
@@ -932,13 +1136,20 @@ export async function initializeWebSocket(httpServer) {
         });
         // Start rate limit polling on first client connection
         if (connectedClients === 1) {
-            rateLimitProbeService.startPolling((data) => { io.emit('rateLimit:update', data); }, (data) => { io.emit('apiHealth:update', data); });
+            rateLimitProbeService.startPolling((data) => { io.emit('rateLimit:update', data); }, (data) => { io.emit('apiHealth:update', data); }, (throttledUntil) => { io.emit('rateLimit:throttled', { throttledUntil }); });
         }
         // Send cached rate limit data immediately to newly connected client
         const cachedRateLimit = rateLimitProbeService.getCachedResult();
         if (cachedRateLimit) {
             socket.emit('rateLimit:update', cachedRateLimit);
         }
+        // Inside a usage-API Retry-After window the cache is empty and no rateLimit:update can
+        // arrive until the recovery poll — tell the connecting client honestly why the bars are
+        // empty instead of leaving it on "checking…".
+        const usageThrottledUntil = rateLimitProbeService.getThrottledUntil();
+        if (usageThrottledUntil) {
+            socket.emit('rateLimit:throttled', { throttledUntil: usageThrottledUntil });
+        }
         // Send cached API health status to newly connected client
         const cachedHealth = rateLimitProbeService.getApiHealth();
         if (cachedHealth) {
@@ -972,6 +1183,13 @@ export async function initializeWebSocket(httpServer) {
                     }
                 }
                 existingStream.abortController.abort('another-client');
+                // Story 38.7: a resident engine's live query is unreachable by the old turn's
+                // abort (and this replacement send is about to build a new stream on the SAME
+                // session key). Evict + close the old resident SYNCHRONOUSLY (the map delete is
+                // synchronous) so the replacement's registry.get() misses and creates a fresh,
+                // resuming engine — avoiding two turns racing one shared iterator. The close
+                // also unwinds the old turn's parked stream.
+                void engineResidency.remove(streamKey);
             }
             // Ensure this socket is in the session room so that chain:add events
             // emitted right after chat:send pass the room membership check.
@@ -1030,6 +1248,32 @@ export async function initializeWebSocket(httpServer) {
                 const sendSuccess = await handleChatSend(stream, data, abortController, lang);
                 if (sendSuccess)
                     chainResumableSessions.add(stream.sessionId);
+                // Hammoc invariant: end_turn = done. If background tasks are pending
+                // when the stream ends (run_in_background OR the engine deciding to
+                // background a subagent on its own), the SDK returns at end_turn while
+                // those tasks keep running, then auto-resumes into the JSONL. Wait for
+                // completion AND the auto-resume follow-up before declaring the turn
+                // done — otherwise queue/chain advance prematurely, session status
+                // flips to idle, and completion notifications fire early. The stream
+                // stays in activeStreams during the wait, blocking chain drain or
+                // replacement.
+                //
+                // markMainEnded must happen HERE: the browser path replaces
+                // callbacks.onComplete (completion deferral), so the streamCallbacks-
+                // level markMainEnded never fires on this path. Gated on sendSuccess —
+                // after an error/abort the engine process is not trustworthy to ever
+                // deliver a completion notification, so waiting would only hang.
+                if (sendSuccess)
+                    stream.backgroundTracker?.markMainEnded();
+                // Story 38.3: a user interrupt (Stop) means "stop now" — do NOT hold the turn
+                // waiting on background tasks. The hard-abort path already short-circuits this
+                // via its aborted signal; the interrupt path leaves the signal unset, so gate
+                // on the flag explicitly.
+                const bgTracker = stream.backgroundTracker;
+                if (shouldWaitForBackgroundTasks(!!stream.userInterrupted, !!bgTracker?.isWaiting)) {
+                    const bgSlug = sessionProjectMap.get(stream.sessionId) ?? null;
+                    await waitForBackgroundTasks(bgTracker, stream.sessionId, bgSlug, abortController.signal, stream.streamCallbacks);
+                }
             }
             finally {
                 stream.status = 'completed';
@@ -1117,20 +1361,40 @@ export async function initializeWebSocket(httpServer) {
                 socket.emit('permission:already-resolved', { requestId: data.requestId });
             }
         });
-        // Handle chat:abort event — find stream and abort, notify all viewers
+        // Handle chat:abort event — the Stop button. Story 38.3 splits the single
+        // "abort the whole SDK stream" path into two:
+        //   • SDK engine → INTERRUPT (turn-only): stop just this turn's generation via
+        //     the persistent query's interrupt(), keeping the session/generator alive so
+        //     the conversation can continue (the point of Epic 38). The interrupted turn
+        //     ends with an error result, which handleChatSend suppresses (userInterrupted).
+        //   • CLI engine → ABORT (unchanged): the PTY Ctrl+C path runs off the
+        //     abortController signal, so CLI keeps aborting the controller as before.
+        // The wire event is unchanged (no new field) — the split is server-internal, and
+        // the observable outcome (streaming stops for every viewer) is preserved. Explicit
+        // session teardown (close()) still flows through the existing teardown events
+        // (another-client / chain-cleared / disconnect); higher-level session lifecycle is
+        // Story 38.5.
         socket.on('chat:abort', () => {
             const sessionId = socketToSession.get(socket.id);
             if (!sessionId)
                 return;
             const stream = activeStreams.get(sessionId);
             if (stream && stream.status === 'running') {
-                // Emit abort notification to all connected viewers BEFORE triggering abort.
-                // This ensures passive viewers (who didn't initiate the abort) also
-                // receive a completion signal, preventing them from being stuck in isStreaming=true.
+                // Emit stop notification to all connected viewers BEFORE triggering the stop.
+                // This ensures passive viewers (who didn't initiate it) also receive a
+                // completion signal, preventing them from being stuck in isStreaming=true.
                 for (const sock of stream.sockets) {
                     sock.emit('stream:detached', { sessionId, reason: 'user-abort' });
                 }
-                stream.abortController.abort('user-abort');
+                // Settle any parked permission/AskUserQuestion first so canUseTool unblocks
+                // and nothing leaks — for both engines.
+                settleStreamPermissions(stream, sessionId);
+                // Story 38.3 AC1 / 38.7: mark the turn as a user stop (its interrupt error
+                // result is suppressed) and route to interrupt (SDK, turn-only — the session
+                // survives so it can continue) or a hard abort (CLI / boot window). On a
+                // resident SDK engine this is the ONLY way to reach the reused live query.
+                stream.userInterrupted = true;
+                requestTurnStop(stream, 'user-abort');
             }
             // Also clear any pending prompt chain — user expects everything to stop.
             // Always bump generation to invalidate any in-flight drain timers,
@@ -1625,7 +1889,11 @@ export async function initializeWebSocket(httpServer) {
                 if (removedItem?.status === 'sending') {
                     const stream = activeStreams.get(sessionId);
                     if (stream && stream.status === 'running') {
-                        stream.abortController.abort('chain-item-removed');
+                        // Story 38.7: on a resident SDK engine the abortController can't reach the
+                        // reused live query — route through interrupt() (turn-only, session kept),
+                        // marking it as an intended stop so no error card appears (matches Stop).
+                        stream.userInterrupted = true;
+                        requestTurnStop(stream, 'chain-item-removed');
                     }
                 }
                 const filtered = items.filter(item => item.id !== id);
@@ -1687,7 +1955,10 @@ export async function initializeWebSocket(httpServer) {
             if (items?.some(item => item.status === 'sending')) {
                 const stream = activeStreams.get(sessionId);
                 if (stream && stream.status === 'running') {
-                    stream.abortController.abort('chain-cleared');
+                    // Story 38.7: interrupt (turn-only) on a resident SDK engine — abort can't
+                    // reach its reused live query. Marked as an intended stop (no error card).
+                    stream.userInterrupted = true;
+                    requestTurnStop(stream, 'chain-cleared');
                 }
             }
             chainState.set(sessionId, []);
@@ -1726,11 +1997,29 @@ export async function initializeWebSocket(httpServer) {
                 return;
             log.info(`session:rewind-files sessionId=${sessionId}, messageUuid=${messageUuid}, dryRun=${!!dryRun}`);
             try {
-                // Standalone rewind is now a ChatEngine operation (Story 32.3) — the SDK
-                // mechanism (throwaway resume query + markRewindDirty + close) lives
-                // behind the seam in ChatService.rewindFiles. The handler keeps only the
-                // transport concerns: result → session:rewind-result mapping.
-                const engine = createChatEngine(await projectService.getEffectiveEngineMode(workingDirectory), { workingDirectory });
+                // Standalone rewind is a ChatEngine operation (Story 32.3) — the SDK mechanism
+                // (throwaway resume query + markRewindDirty + close) lives behind the seam in
+                // ChatService.rewindFiles. The handler keeps only the transport concerns.
+                //
+                // A rewind restores project files — while a turn is streaming it would race
+                // the in-flight generation's own file writes (and the standalone path would
+                // spin a SECOND live query on the same session's JSONL). The UI already
+                // disables the button during streaming; this is the server-side guard for
+                // late tabs / raced clicks. Reject instead of proceeding with a throwaway.
+                if (activeStreams.get(sessionId)?.status === 'running') {
+                    socket.emit('session:rewind-result', {
+                        success: false,
+                        dryRun: !!dryRun,
+                        error: t('ws.error.rewindWhileStreaming'),
+                    });
+                    return;
+                }
+                // Story 38.7: if a LIVE resident engine holds this session, rewind INLINE on
+                // its persistent query (ChatService.rewindFiles reuses currentQuery) — no
+                // second live query on the same session's JSONL. Otherwise use a fresh
+                // throwaway engine (the standalone path).
+                const resident = engineResidency.get(sessionId);
+                const engine = resident ?? createChatEngine(await projectService.getEffectiveEngineMode(workingDirectory), { workingDirectory });
                 const result = await engine.rewindFiles({ sessionId, messageUuid, dryRun: !!dryRun });
                 if (result.canRewind) {
                     socket.emit('session:rewind-result', {
@@ -2220,6 +2509,11 @@ export async function initializeWebSocket(httpServer) {
                 prior.dispose();
                 socketLoginSessions.delete(socket.id);
             }
+            // Snapshot the current active account's credential BEFORE the login PTY overwrites the
+            // credentials file with the new account. The CLI continuously refreshes the active token
+            // (new accessToken + possibly rotated refreshToken), but accounts.json still holds the
+            // copy from original login. Without this, switching back would use a stale/revoked token.
+            accountStorageService.resnapshotAndSave().catch(() => { });
             // The login PTY uses the same binary-path override as chat (global preference).
             let cliBinaryPath;
             try {
@@ -2232,15 +2526,15 @@ export async function initializeWebSocket(httpServer) {
                 onMethodPrompt: () => socket.emit('auth:method-prompt'),
                 onUrl: (url) => socket.emit('auth:url', { url }),
                 onCodePrompt: () => socket.emit('auth:code-prompt'),
-                onComplete: (account) => {
-                    socket.emit('auth:complete', { account });
+                onComplete: async (account) => {
                     socketLoginSessions.delete(socket.id);
-                    // Story BS-8: accumulate the just-written credential into the multi-account store.
-                    // Login already made this account active, so the credentials file holds its credential
-                    // and accountInfoService supplied the email (or null → fallback key, AC1a). Fire-and-forget.
-                    accountStorageService.captureActiveCredential(account?.email ?? null).catch((err) => {
+                    try {
+                        await accountStorageService.captureActiveCredential(account?.email ?? null);
+                    }
+                    catch (err) {
                         log.warn(`BS-8: failed to capture credential after login: ${err instanceof Error ? err.message : String(err)}`);
-                    });
+                    }
+                    socket.emit('auth:complete', { account });
                 },
                 onError: (message) => {
                     socket.emit('auth:error', { message });
@@ -2264,11 +2558,24 @@ export async function initializeWebSocket(httpServer) {
                 socket.emit('auth:error', { message: 'Failed to delete credentials' });
                 return;
             }
-            // Refresh the in-memory account cache so a subsequent /account read reflects the logout.
-            // The client transitions to the inline login flow optimistically (no success event needed).
-            accountInfoService.refresh().catch(() => {
-                /* best-effort — the file is gone regardless */
-            });
+            // Also drop the CLI's identity cache (`oauthAccount` in `~/.claude.json`): it is written at
+            // login and NOT tied to the credential file, so after deleting the credential it would keep
+            // reporting the last login's identity (phantom logged-in account).
+            await accountStorageService.clearCliIdentity().catch(() => { });
+            // BS-8: the multi-account active marker pointed at the credential we just deleted — clear it
+            // (but KEEP the stored accounts so the user can switch back). Then clear the in-memory account
+            // cache DIRECTLY rather than re-running a bootstrap query: the SDK reports a logged-out user as
+            // a non-null `{ tokenSource: 'none' }` stub, so a refresh would re-cache a phantom account and
+            // the UI would show an empty card instead of the login flow.
+            await accountStorageService.setActiveKey(null).catch(() => { });
+            accountInfoService.clear();
+            // Propagate logout to every tab/device so they drop to the login flow too.
+            try {
+                io.emit('account:logged-out');
+            }
+            catch {
+                /* io not ready (e.g. tests) — the originating tab transitions optimistically anyway */
+            }
         });
         // Disconnect: detach socket from stream, DON'T abort or deny permissions
         socket.on('disconnect', (reason) => {
@@ -2440,23 +2747,40 @@ export function getConnectedClientsCount() {
     return connectedClients;
 }
 /**
- * Validate image attachments
- * Story 5.5: Image Attachment
+ * Validate attachments (images + PDFs, distinguished by mimeType)
+ * Story 5.5: Image Attachment / Story BS-11: PDF attachment
+ *
+ * PDFs are SDK-engine-only in Stage 1 (no on-disk file to hand to the CLI/PTY
+ * engine), so a CLI-engine session rejects them explicitly instead of silently
+ * dropping them (AC 15).
  */
-function validateImages(images, lang) {
+function validateAttachments(images, lang, engineMode) {
     const t = i18next.getFixedT(lang);
     if (images.length > IMAGE_CONSTRAINTS.MAX_COUNT) {
         return { valid: false, error: t('ws.error.maxImages', { value: IMAGE_CONSTRAINTS.MAX_COUNT }) };
     }
+    let totalSizeBytes = 0;
     for (const img of images) {
-        if (!IMAGE_CONSTRAINTS.ACCEPTED_TYPES.includes(img.mimeType)) {
+        const isPdf = PDF_CONSTRAINTS.ACCEPTED_TYPES.includes(img.mimeType);
+        if (!isPdf && !IMAGE_CONSTRAINTS.ACCEPTED_TYPES.includes(img.mimeType)) {
             return { valid: false, error: t('ws.error.unsupportedImageFormat', { value: img.mimeType }) };
         }
+        if (isPdf && engineMode === 'cli') {
+            return { valid: false, error: t('ws.error.pdfRequiresSdkEngine') };
+        }
         // base64 size approximation: base64 length * 0.75 ≈ original bytes
         const sizeBytes = Math.ceil(img.data.length * 0.75);
-        if (sizeBytes > IMAGE_CONSTRAINTS.MAX_SIZE_BYTES) {
+        if (isPdf && sizeBytes > PDF_CONSTRAINTS.MAX_SIZE_BYTES) {
+            return { valid: false, error: t('ws.error.pdfSizeExceeded', { value: img.name }) };
+        }
+        if (!isPdf && sizeBytes > IMAGE_CONSTRAINTS.MAX_SIZE_BYTES) {
             return { valid: false, error: t('ws.error.imageSizeExceeded', { value: img.name }) };
         }
+        totalSizeBytes += sizeBytes;
+    }
+    // Combined raw-size cap — the Claude API caps the whole request at 32MB (AC 14)
+    if (totalSizeBytes > ATTACHMENT_TOTAL_MAX_SIZE_BYTES) {
+        return { valid: false, error: t('ws.error.attachmentsSizeExceeded') };
     }
     return { valid: true };
 }
@@ -2469,9 +2793,14 @@ async function handleChatSend(stream, data, abortController, lang) {
     const emit = createStreamEmit(stream);
     const t = i18next.getFixedT(lang);
     const { content: rawContent, workingDirectory, sessionId, resume, permissionMode, model, images, effort, resumeSessionAt: rawResumeSessionAt, forkSession, rewindToMessageUuid } = data;
-    // Validate images if present (Story 5.5)
+    // Story 33.3 / BS-11: resolve the effective engine mode (override > global > 'sdk'
+    // default) BEFORE attachment validation — PDF attachments are SDK-engine-only and a
+    // CLI-engine session must reject them here, before the user:message broadcast below.
+    // Resolved ONCE into this local; all later engine-mode decisions in this turn reuse it.
+    const engineMode = await projectService.getEffectiveEngineMode(workingDirectory);
+    // Validate attachments if present (Story 5.5, PDF: Story BS-11)
     if (images && images.length > 0) {
-        const validation = validateImages(images, lang);
+        const validation = validateAttachments(images, lang, engineMode);
         if (!validation.valid) {
             emit('error', {
                 code: ERROR_CODES.VALIDATION_ERROR,
@@ -2590,6 +2919,7 @@ async function handleChatSend(stream, data, abortController, lang) {
             if (existsSync(filePath)) {
                 const rawMessages = await parseJSONLFile(filePath);
                 const tree = buildRawMessageTree(rawMessages);
+                repairPostCompactParenting(tree);
                 // Find the branch path that contains the fork point message
                 const selections = findBranchSelectionsForUuid(tree.roots, resumeSessionAt)
                     ?? getDefaultRawBranchSelections(tree.roots);
@@ -2625,6 +2955,19 @@ async function handleChatSend(stream, data, abortController, lang) {
     // short-circuits while this is set so no activity can re-arm the timer, and
     // canUseTool clears it + re-arms once the user responds.
     let permissionWaiting = false;
+    // Same pause while engine-announced background tasks are pending. The engine
+    // holds the stream open and stays SILENT while a background agent works
+    // (실측 2026-07-02: 78s of zero stream messages, then the notification) — the
+    // inactivity timer would read that healthy quiet as a stall and abort the
+    // turn at exactly chatTimeoutMs into every longer background task. The
+    // engine's own task lifecycle (task_started → task_notification) is the
+    // authoritative liveness signal here; a genuinely dead engine ends the
+    // stream itself, which ends the turn without the timer's help.
+    let backgroundTasksPending = false;
+    // Set once the turn's stream loop has ended — resetTimeout becomes a no-op so
+    // late tracker transitions (JSONL-poller phase) can't re-arm an abort bomb
+    // into a finished turn.
+    let timerDisposed = false;
     // 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
@@ -2640,23 +2983,75 @@ async function handleChatSend(stream, data, abortController, lang) {
     catch {
         // Non-critical — cleanup will be skipped if snapshot fails
     }
+    // Story 38.7: residency reconciliation flag — the finally keeps a resident engine
+    // ONLY when the turn ended cleanly (success or a session-preserving user interrupt);
+    // any failure / hard-abort / timeout leaves the engine untrustworthy, so it is evicted
+    // there and the next send resumes fresh from JSONL.
+    let turnSucceeded = false;
     try {
         // Load preferences early for advanced settings + timeout
         const effectivePrefs = await preferencesService.getEffectivePreferences();
-        // Story 33.3: resolve the effective engine mode (override > global > 'sdk' default).
-        // Captured once into a local so the progress-callback gating below reuses the same
-        // decision (no second resolve, and `engineMode === 'cli'` stays consistent).
-        const [engineMode, isBmadProject] = await Promise.all([
-            projectService.getEffectiveEngineMode(workingDirectory),
-            projectService.checkBmadProject(workingDirectory),
-        ]);
+        // engineMode was resolved once before attachment validation (BS-11 hoist) — the
+        // progress-callback gating below reuses that same local (no second resolve, and
+        // `engineMode === 'cli'` stays consistent).
+        const isBmadProject = await projectService.checkBmadProject(workingDirectory);
         // Auto-compaction master switch (both engines). Default ON. Gates the engine-internal
         // auto-compact (forwarded into each engine's settings) AND Hammoc's overflow-triggered
         // /compact recovery below, so one toggle controls all auto-compaction.
         const autoCompactEnabled = effectivePrefs.autoCompactEnabled ?? true;
-        const chatService = createChatEngine(engineMode, { workingDirectory, permissionMode, cliBinaryPath: effectivePrefs.cliBinaryPath, cliShowThinkingSummaries: effectivePrefs.cliShowThinkingSummaries, cliResumeChoice: effectivePrefs.cliResumeChoice, autoCompactEnabled, planModeBypassBehavior: effectivePrefs.planModeBypassBehavior });
+        // Story 38.7: keep the sync residency snapshot current from the prefs we just
+        // read (so a settings change takes effect without re-instantiating the registry).
+        refreshResidencyConfig(effectivePrefs);
+        // Story 38.7 — reuse a live resident engine (skip the ~3s re-spawn) or create a
+        // fresh one and register it as resident. `registry.get` returns a live engine
+        // (and touches its activity) or drops a crashed one and returns undefined
+        // (crash-reconnect → the create branch resumes from JSONL). Fork / branch
+        // (resumeSessionAt) / rewind are query() CREATION options, so they never reuse.
+        const isBranchOrRewind = !!resumeSessionAt || !!rewindToMessageUuid;
+        const residentEngine = engineResidency.get(stream.sessionId);
+        const reuseResident = shouldReuseResidentEngine({
+            hasLiveResident: !!residentEngine,
+            engineMode,
+            isFork: !!forkSession,
+            isBranchOrRewind,
+        });
+        let chatService;
+        if (reuseResident) {
+            chatService = residentEngine;
+            // The reused live query keeps its CREATION-time parameters; apply this turn's
+            // runtime-injectable params to it (Story 38.4 seam — first observable here).
+            // model/permissionMode have live-query setters; other creation-time params
+            // (effort, prompt/tool config) stay fixed for the resident engine's lifetime.
+            try {
+                await chatService.setModel?.(model);
+            }
+            catch (err) {
+                log.warn(`setModel on reuse failed for ${stream.sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+            }
+            if (permissionMode) {
+                try {
+                    await chatService.setPermissionMode(permissionMode);
+                }
+                catch (err) {
+                    log.warn(`setPermissionMode on reuse failed for ${stream.sessionId}: ${err instanceof Error ? err.message : String(err)}`);
+                }
+            }
+            log.info(`[RESIDENCY] reusing resident engine for session ${stream.sessionId} (no re-spawn)`);
+        }
+        else {
+            chatService = createChatEngine(engineMode, { workingDirectory, permissionMode, cliBinaryPath: effectivePrefs.cliBinaryPath, cliShowThinkingSummaries: effectivePrefs.cliShowThinkingSummaries, cliResumeChoice: effectivePrefs.cliResumeChoice, autoCompactEnabled, planModeBypassBehavior: effectivePrefs.planModeBypassBehavior });
+        }
         stream.chatService = chatService;
         stream.engineMode = engineMode;
+        // Register a freshly-created SDK engine as resident NOW (before the send) so its
+        // callback path skips the turn-end close() and the process survives into the next
+        // turn. A fork's assigned id is unknown until re-key, so it is registered there
+        // instead (see rekeyStream) — registering under the ORIGINAL key here would clobber
+        // the original session's resident entry. A branch/rewind create REPLACES the prior
+        // resident (register closes the old one). CLI engines are a feature-detect no-op.
+        if (!reuseResident && shouldRegisterOnCreate({ engineMode, isFork: !!forkSession })) {
+            await engineResidency.register(stream.sessionId, chatService, engineMode);
+        }
         const effectiveEffort = clampEffortForModel(effort ?? effectivePrefs.defaultEffort, model);
         // Opus 4.7+ flipped `thinking.display` default to 'omitted' — ThinkingBlock UI stays blank
         // unless we explicitly opt in. For adaptive-thinking models, forward an explicit `thinking`
@@ -2701,6 +3096,14 @@ async function handleChatSend(stream, data, abortController, lang) {
         // Create canUseTool callback for permission & AskUserQuestion handling
         // Promise stays pending if socket disconnected — SDK naturally waits
         const canUseTool = async (toolName, input, options) => {
+            // Hammoc forbids tool-level background execution so `end_turn = done` stays true —
+            // see backgroundToolGuard. Must run before the bypass auto-approve branches below,
+            // otherwise a background Bash would slip through in Bypass mode.
+            const bgDeny = denyBackgroundBash(toolName, input);
+            if (bgDeny) {
+                log.info(`[canUseTool] blocking ${toolName} run_in_background — steer to OS-level detach`);
+                return bgDeny;
+            }
             // Auto-approve ExitPlanMode when the current permission mode is Bypass.
             // Use chatService.getPermissionMode() instead of the closure-captured variable
             // so that mid-stream permission mode changes (e.g. Plan → Bypass) are reflected.
@@ -2816,11 +3219,14 @@ async function handleChatSend(stream, data, abortController, lang) {
         const resetTimeout = (source) => {
             if (isCliEngine)
                 return; // CLI mode: no inactivity timeout (see above)
+            if (timerDisposed)
+                return; // turn already ended — never re-arm
             // Story 35.1: while awaiting user input (permission / AskUserQuestion) the timer
             // is paused — ignore every activity-driven reset (onActivity, raw PTY frames,
             // compact/retry) so the wait stays indefinite. canUseTool clears the pause and
             // calls this once to re-arm when the user responds.
-            if (permissionWaiting)
+            // Same for pending background tasks: the engine's silence is by-design there.
+            if (permissionWaiting || backgroundTasksPending)
                 return;
             if (source)
                 lastResetSource = source;
@@ -2828,9 +3234,37 @@ async function handleChatSend(stream, data, abortController, lang) {
                 clearTimeout(timeoutId);
             timeoutId = setTimeout(() => {
                 log.warn(`TIMEOUT FIRED after ${timeoutMs}ms inactivity (last reset by: ${lastResetSource})`);
-                abortController.abort('timeout');
+                // Story 38.7: on a resident SDK engine the per-turn abortController does not
+                // reach the reused live query and processStream never polls it, so a hard abort
+                // cannot stop a stuck turn-2+ generation — route the timeout through interrupt()
+                // (the same primitive as Stop). Mark `timedOut` so the interrupt error result is
+                // suppressed, a timeout error is surfaced, and the engine is evicted (fresh
+                // resume next send). The CLI / not-yet-created path still hard-aborts (where the
+                // abort IS wired and the catch below emits the timeout error).
+                if (resolveStopStrategy({ engineMode, canInterrupt: !!stream.chatService?.interrupt }) === 'interrupt') {
+                    stream.timedOut = true;
+                }
+                requestTurnStop(stream, 'timeout');
             }, timeoutMs);
         };
+        // Story 38.3 (AC4): dispose the inactivity timer at the TURN-ENDING result, not at
+        // generator/finally teardown. Epic 38's persistent stream breaks the old
+        // "generator lifetime = turn" assumption: after the turn-ending result the stream
+        // stays open (background hold, follow-up), so dispose must key off the SAME result
+        // boundary the engine's Stop hook decides. Called from the turn-ending onComplete
+        // (below) — which fires only at the real end, never at an intermediate hold result —
+        // so the timer is gone the instant the turn ends and the brief re-arm that
+        // onBackgroundState(waiting=false) would otherwise trigger at that boundary is
+        // cancelled. The finally still calls this as a crash/abort backstop. Idempotent.
+        const disposeTimer = () => {
+            if (timeoutId) {
+                clearTimeout(timeoutId);
+                timeoutId = null;
+            }
+            timerDisposed = true;
+        };
+        // Arm at turn start. (Per-turn arm across a resident process is Story 38.5; today
+        // the engine is one turn per instance, so turn start == handleChatSend start.)
         resetTimeout('initial');
         // CLI screen-stall watchdog (soft, advisory — see cliScreenStallWatchdog). The reconstructed
         // screen changes ~1×/second while claude is healthy (spinner glyph + ticking clock), so a long
@@ -2890,13 +3324,15 @@ async function handleChatSend(stream, data, abortController, lang) {
         // Story 37.8: mirror refresh interval (ms) — the user's preference, applied as the engine's
         // trailing-throttle interval. undefined → engine default (200ms). Harmless when the mirror is off.
         const mirrorThrottleMs = effectivePrefs.cliMirrorThrottleMs;
-        const backgroundTracker = new BackgroundTaskTracker((state) => {
-            emit('background:waiting', {
-                sessionId: sessionIdRef.current ?? sessionId,
-                waiting: state.waiting,
-                pendingCount: state.pending,
-            });
-        });
+        // The tracker is a thin pending-id set fed by SDK task events (task_started /
+        // task-notification). Two consumers: (a) turn-boundary GATE 2 (2026-07-12 fix
+        // — chatService passes it into streamHandler, which holds the turn while a
+        // completed task's queued notification has not been injected yet; the Stop
+        // ledger alone cannot see that window), (b) the crash-safety-net poller
+        // (waitForBackgroundTasks below). The amber "waiting" card follows the same
+        // combined verdict via callbacks.onBackgroundState.
+        const backgroundTracker = new BackgroundTaskTracker();
+        stream.backgroundTracker = backgroundTracker;
         // Build shared callbacks (common logic for browser & queue paths)
         const { callbacks, sessionIdRef } = buildStreamCallbacks({
             emit,
@@ -2919,6 +3355,25 @@ async function handleChatSend(stream, data, abortController, lang) {
                 sessionService.saveSessionId(workingDirectory, sid).catch(() => { });
             },
         });
+        // Same object survives the wrapper reassignments below — the post-turn
+        // background wait re-broadcasts follow-up records through it.
+        stream.streamCallbacks = callbacks;
+        // Story 38.3: a turn-only interrupt (Stop on the SDK engine) ends the turn with an
+        // `error_during_execution` result. That is the intended stop, not a failure — swallow
+        // its error emission (viewers already got `stream:detached`) so no spurious error card
+        // appears; onComplete still finalizes the partial turn. Innermost wrapper so it survives
+        // the resume-gating reassignments below (they capture and restore THIS function).
+        const _preInterruptOnResultError = callbacks.onResultError;
+        callbacks.onResultError = (data) => {
+            // Story 38.7: an inactivity TIMEOUT on a resident engine also ends the turn via
+            // interrupt() (its raw error result is likewise an intended stop) — suppress it and
+            // surface a proper timeout error below instead.
+            if (shouldSuppressResultError(!!stream.userInterrupted || !!stream.timedOut)) {
+                log.info(`[interrupt] suppressing result:error for ${stream.timedOut ? 'timed-out' : 'user-interrupted'} turn (subtype=${data.subtype})`);
+                return;
+            }
+            _preInterruptOnResultError?.(data);
+        };
         // Track whether SDK has started producing user-visible output.
         // Used to guard resume-retry: if output was already emitted, retrying
         // would cause duplicate content / tool side-effects.
@@ -2932,11 +3387,23 @@ async function handleChatSend(stream, data, abortController, lang) {
         // Usage data is stored and included in stream:complete-messages.
         const _baseOnComplete = callbacks.onComplete;
         callbacks.onComplete = (response) => {
+            // Story 38.3 (AC4): onComplete fires ONLY at the turn-ending result (an
+            // intermediate background hold fires nothing) — so this is the exact turn
+            // boundary at which to dispose the inactivity timer.
+            disposeTimer();
+            // Turn ended — restart the residency idle clock from NOW so the timeout is
+            // measured from turn END, not turn start. The activity clock is otherwise only
+            // set at turn start, so a turn longer than the idle timeout would leave the
+            // engine instantly sweepable the moment it goes inactive. Pairs with the
+            // in-progress guard above (which protects the turn WHILE running).
+            engineResidency.touch(stream.sessionId);
             if (response.usage) {
                 stream.deferredUsage = response.usage;
                 emit('context:usage', response.usage);
             }
-            if (notificationService.shouldNotify(stream.sockets.size)) {
+            // Story 38.3: a user-interrupted turn ends with a completion for finalization,
+            // but it is a Stop, not a natural finish — skip the "완료" notification.
+            if (shouldNotifyComplete(!!stream.userInterrupted, notificationService.shouldNotify(stream.sockets.size))) {
                 notificationService.notifyComplete(stream.sessionId, response.content);
             }
         };
@@ -2944,6 +3411,37 @@ async function handleChatSend(stream, data, abortController, lang) {
         callbacks.onActivity = (messageType) => {
             resetTimeout(`onActivity:${messageType}`);
         };
+        // Story 38.2: background-work state, derived from the engine's Stop-hook
+        // snapshot (fired by processStream at each result). Replaces the retired
+        // ack-marker tracker's onChange — same two consumers, same wire payload:
+        //  (a) inactivity-timer pause/resume (pending → stop the timer; back to 0 →
+        //      re-arm so normal hang detection governs the rest of the turn),
+        //  (b) the `background:waiting` emit (amber card).
+        // Granularity note (AC6): the tracker onChange fired per tool_result; this
+        // fires at the result/Stop boundary. The observable end-state is identical
+        // (in-flight → card on, none → card off); mid-turn incremental granularity
+        // is Story 38.3's concern, not restored here.
+        callbacks.onBackgroundState = (state) => {
+            const pending = state.pendingCount > 0;
+            if (pending !== backgroundTasksPending) {
+                backgroundTasksPending = pending;
+                if (pending) {
+                    if (timeoutId) {
+                        clearTimeout(timeoutId);
+                        timeoutId = null;
+                    }
+                    log.info(`inactivity timer paused: ${state.pendingCount} background task(s) in flight`);
+                }
+                else {
+                    resetTimeout('background-tasks-resolved');
+                }
+            }
+            emit('background:waiting', {
+                sessionId: sessionIdRef.current ?? sessionId,
+                waiting: state.waiting,
+                pendingCount: state.pendingCount,
+            });
+        };
         callbacks.onError = (error) => {
             // Ignore abort errors from replaced streams (another-client or user-abort)
             if (abortController.signal.aborted) {
@@ -3023,15 +3521,59 @@ async function handleChatSend(stream, data, abortController, lang) {
                 }
             }).catch(() => { });
         }
+        // Guard (mirrors the queue executor's `!response.done` check): the engine can
+        // end the stream WITHOUT ever yielding a result — silent process death. No
+        // throw, no error result, so without this the turn would read as a clean
+        // success and a dead engine would stay RESIDENT: every following send reuses
+        // it and ends as another silent empty turn, each reuse refreshing the idle
+        // clock so the sweep never reclaims it. A result-less end is also the NORMAL
+        // shape for a replaced/stopped turn (close() unwinds the parked stream), so
+        // an intended teardown returns quietly instead of raising an error card.
+        // Returns true when the turn must FAIL (caller returns false → the finally's
+        // residency reconciliation evicts the engine; next send resumes from JSONL).
+        const failIfEndedWithoutResult = (r) => {
+            if (r.done)
+                return false;
+            gatedResultError = null;
+            gatedComplete = null;
+            ungateCallbacks();
+            if (!abortController.signal.aborted && !stream.userInterrupted) {
+                log.error(`SDK stream ended without a result message: sessionId=${stream.sessionId}`);
+                const msg = t('ws.error.engineTerminated');
+                emit('error', { code: ERROR_CODES.CHAT_ERROR, message: msg });
+                if (notificationService.shouldNotify(stream.sockets.size)) {
+                    notificationService.notifyError(stream.sessionId, msg);
+                }
+            }
+            return true;
+        };
         try {
             const sendResult = await chatService.sendMessageWithCallbacks(content, callbacks, chatOptions, canUseTool, (messageType) => {
                 resetTimeout(`raw:${messageType}`);
             }, generationProgressCb, cliPhaseCb, screenFrameCb, mirrorThrottleMs, backgroundTracker, (mode) => {
                 emit('permission:mode-change', { mode });
             });
+            // Story 38.7: the inactivity timeout ended this resident turn via interrupt() (its
+            // raw error result was suppressed above). Surface the timeout error and FAIL the
+            // turn — before the resume-retry check, so it isn't mistaken for a resume failure —
+            // so the queue retries and the reconciliation evicts the (timed-out) engine for a
+            // fresh resume next send.
+            if (stream.timedOut) {
+                gatedResultError = null;
+                gatedComplete = null;
+                ungateCallbacks();
+                emit('error', { code: ERROR_CODES.TIMEOUT_ERROR, message: t('ws.error.timeout') });
+                return false;
+            }
+            // Silent termination — the stream ended with no result at all (see helper).
+            if (failIfEndedWithoutResult(sendResult)) {
+                return false;
+            }
             // 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) {
+            // Story 38.3: a user interrupt also ends the turn with an error result — it must
+            // NOT be mistaken for a resume failure and retried (the user asked to stop).
+            if (shouldRetryResumeAfterError({ isError: !!sendResult.isError, isResumeAttempt, aborted: abortController.signal.aborted, userInterrupted: !!stream.userInterrupted, hasEmittedOutput })) {
                 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');
             }
@@ -3061,21 +3603,37 @@ async function handleChatSend(stream, data, abortController, lang) {
                 gatedResultError = null;
                 gatedComplete = null;
                 ungateCallbacks();
+                // Story 38.7: on a resident engine the failed send's persistent query is NOT
+                // closed at turn end (resident), so the /compact + retry would reuse the dead
+                // query. Close it so /compact rebuilds a fresh resuming query (pre-residency this
+                // reset came free from the turn-end close). No-op for a fresh/CLI engine.
+                await chatService.close?.();
                 resetTimeout('auto-compact');
-                // Run /compact to shrink context (preserves session file)
-                await chatService.sendMessageWithCallbacks('/compact', callbacks, chatOptions, canUseTool, (messageType) => {
+                // Run /compact to shrink context (preserves session file). The command is
+                // a maintenance turn — don't re-attach this send's user payload (SDK base64
+                // images / CLI image paths) or re-apply the inline rewind to it; those
+                // belong to the retried original message, not to /compact (images would
+                // otherwise enter the context twice).
+                const compactOptions = { ...chatOptions, images: undefined, attachedImagePaths: undefined, rewindToMessageUuid: undefined };
+                const compactResult = await chatService.sendMessageWithCallbacks('/compact', callbacks, compactOptions, canUseTool, (messageType) => {
                     resetTimeout(`compact:${messageType}`);
                 }, generationProgressCb, cliPhaseCb, screenFrameCb, mirrorThrottleMs, backgroundTracker, (mode) => {
                     emit('permission:mode-change', { mode });
                 });
+                if (failIfEndedWithoutResult(compactResult)) {
+                    return false;
+                }
                 // Retry the original message after compaction
                 log.info(`[AUTO-COMPACT] compaction done, retrying original message: sessionId=${sessionId}`);
                 resetTimeout('auto-compact-retry');
-                await chatService.sendMessageWithCallbacks(content, callbacks, chatOptions, canUseTool, (messageType) => {
+                const compactRetryResult = await chatService.sendMessageWithCallbacks(content, callbacks, chatOptions, canUseTool, (messageType) => {
                     resetTimeout(`retry:${messageType}`);
                 }, generationProgressCb, cliPhaseCb, screenFrameCb, mirrorThrottleMs, backgroundTracker, (mode) => {
                     emit('permission:mode-change', { mode });
                 });
+                if (failIfEndedWithoutResult(compactRetryResult)) {
+                    return false;
+                }
                 // Resume failed for other unknown reasons — retry without resume (fresh session).
                 // Guards:
                 //  1. Only when resuming (not a fresh session send)
@@ -3087,12 +3645,22 @@ async function handleChatSend(stream, data, abortController, lang) {
                 && !abortController.signal.aborted
                 && !hasEmittedOutput
                 && parsedError.code === SDKErrorCode.UNKNOWN
-                && !chatOptions.resumeSessionAt) {
+                && !chatOptions.resumeSessionAt
+                // Data-loss guard: the retry below DELETES the session file. Only enter
+                // for the conversation-less stub this recovery was built for — a file
+                // with real history means a genuine resume failure (dead resident
+                // engine, transient spawn error); surface that error instead of wiping
+                // the user's conversation record.
+                && !(sessionId && sessionFileHasConversation(sessionService.getSessionFilePath(projectSlug, sessionId)))) {
                 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;
                 gatedComplete = null;
                 ungateCallbacks();
+                // Story 38.7: reset a resident engine's dead persistent query (kept open because
+                // resident) so the retry rebuilds a fresh query with retryOptions (resume removed)
+                // instead of reusing the failed one. No-op for a fresh/CLI engine.
+                await chatService.close?.();
                 // 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) {
@@ -3111,11 +3679,14 @@ async function handleChatSend(stream, data, abortController, lang) {
                 delete retryOptions.resume;
                 delete retryOptions.resumeSessionAt;
                 resetTimeout('resume-retry');
-                await chatService.sendMessageWithCallbacks(content, callbacks, retryOptions, canUseTool, (messageType) => {
+                const retryResult = await chatService.sendMessageWithCallbacks(content, callbacks, retryOptions, canUseTool, (messageType) => {
                     resetTimeout(`raw:${messageType}`);
                 }, generationProgressCb, cliPhaseCb, screenFrameCb, mirrorThrottleMs, backgroundTracker, (mode) => {
                     emit('permission:mode-change', { mode });
                 });
+                if (failIfEndedWithoutResult(retryResult)) {
+                    return false;
+                }
             }
             else {
                 // Not retrying — flush gated error events before re-throwing
@@ -3127,6 +3698,7 @@ async function handleChatSend(stream, data, abortController, lang) {
                 throw sendError;
             }
         }
+        turnSucceeded = true; // Story 38.7: clean end → keep the engine resident (see finally)
         return true;
     }
     catch (error) {
@@ -3156,9 +3728,17 @@ async function handleChatSend(stream, data, abortController, lang) {
         return false;
     }
     finally {
+        // Backstop dispose: the turn-ending onComplete already disposed the timer at the
+        // result boundary (Story 38.3 AC4, via the block-scoped disposeTimer); this inline
+        // copy — using the function-scoped locals visible here — covers the paths that never
+        // reach a turn-ending result: a thrown abort/error, or the generator ending mid-hold.
+        // Late background-tracker transitions (JSONL-poller phase after this return) must not
+        // re-arm the timer into a finished turn.
         if (timeoutId) {
             clearTimeout(timeoutId);
+            timeoutId = null;
         }
+        timerDisposed = true;
         // Screen-stall watchdog teardown: clear the pending timer so a stale fire can't leak into the
         // NEXT turn (the stream object is reused and its status flips back to 'running'), and drop any
         // active stall so every viewer's "looks stuck?" affordance clears when the turn ends.
@@ -3197,6 +3777,28 @@ async function handleChatSend(stream, data, abortController, lang) {
                 log.warn('Failed to clean up phantom checkpoint files:', cleanupErr);
             }
         }
+        // Story 38.7: residency reconciliation. Keep the engine resident only on a clean end
+        // (success or a session-preserving interrupt → turnSucceeded). Any failure / hard
+        // abort / timeout leaves the persistent query in a state isLive() can't flag (it stays
+        // non-null after an error/abort — only close() nulls it), so evict + close it here;
+        // the next send then misses the registry and resumes fresh from JSONL. The peek
+        // identity guard avoids evicting a REPLACEMENT engine that an another-client send
+        // already registered under this same session key.
+        // A tracker-hold grace EXPIRY also evicts even though the turn SUCCEEDED
+        // client-side (2026-07-12 dual-gate fix): the expiry abandoned a read parked
+        // on the shared session iterator — kept resident, that dead read would steal
+        // the next turn's first message, and a late follow-up could generate
+        // invisibly. Eviction closes the query (settling the parked read); the next
+        // send resumes from JSONL, where the already-recorded notification surfaces.
+        const holdExpired = !!stream.chatService?.lastTurnTrackerHoldExpired;
+        if ((!turnSucceeded || holdExpired) && stream.chatService && stream.engineMode === 'sdk') {
+            if (engineResidency.peek(stream.sessionId) === stream.chatService) {
+                if (holdExpired && turnSucceeded) {
+                    log.info(`[RESIDENCY] evicting after tracker-hold grace expiry: sessionId=${stream.sessionId} (parked read on the shared iterator must not survive into the next turn)`);
+                }
+                void engineResidency.remove(stream.sessionId);
+            }
+        }
     }
 }
 //# sourceMappingURL=websocket.js.map