@shepai/cli 1.179.1 → 1.180.0-pr548.764147

package/dist/packages/core/src/infrastructure/services/interactive/interactive-session.service.js

@@ -10,15 +10,22 @@
  * are spawned in unit tests — the factory is replaced with a test double).
  */
 import * as crypto from 'node:crypto';
-import { InteractiveSessionStatus, InteractiveMessageRole, AgentType, AgentAuthMethod, } from '../../../domain/generated/output.js';
+import { InteractiveSessionStatus, InteractiveMessageRole, AgentType, AgentAuthMethod, WorkflowStepStatus, } from '../../../domain/generated/output.js';
 import { ConcurrentSessionLimitError } from '../../../domain/errors/concurrent-session-limit.error.js';
 import { getSettings, hasSettings } from '../settings.service.js';
-/** Default idle timeout if no settings are loaded (15 minutes). */
-const DEFAULT_TIMEOUT_MS = 15 * 60 * 1000;
 /** Default concurrent session cap. */
 const DEFAULT_CAP = 3;
-/** Maximum time to wait for the agent to become ready (60 seconds). */
-const BOOT_TIMEOUT_MS = 60_000;
+/**
+ * Boot-phase watchdog: how long the agent is allowed to go WITHOUT
+ * emitting any stream event (delta / tool_use / tool_result / status)
+ * before we consider the boot stuck and abort it.
+ *
+ * This is an IDLE timer, not a wall-clock budget: each event received
+ * resets it. That's essential for application-creation flows where the
+ * first turn legitimately takes many minutes (scaffold + install + build
+ * a whole project). A fixed wall-clock budget would kill those mid-way.
+ */
+const BOOT_IDLE_TIMEOUT_MS = 120_000;
 /**
  * Core service managing interactive agent session lifecycles.
  * Must be registered as a singleton in the DI container.
@@ -40,6 +47,7 @@ export class InteractiveSessionService {
     executorFactory;
     featureRepo;
     contextBuilder;
+    workflowStepRepo;
     /** Live sessions indexed by sessionId. */
     sessions = new Map();
     /** Cached agentSessionIds from stopped sessions, keyed by featureId. */
@@ -52,23 +60,73 @@ export class InteractiveSessionService {
      * subscribe here so they continue receiving events from new sessions.
      */
     featureSubscribers = new Map();
-    constructor(sessionRepo, messageRepo, executorFactory, featureRepo, contextBuilder) {
+    /**
+     * Global subscribers — receive every chunk from every session tagged
+     * with its feature scope key. Used by the global turn-status SSE
+     * endpoint so the sidebar can track all active sessions without
+     * polling.
+     */
+    globalSubscribers = new Set();
+    /**
+     * Currently-active workflow step id per feature scope. Set by the
+     * orchestrator (`RunWorkflowUseCase`) before each agent turn and
+     * cleared between steps. `persistMessage` reads this so every row
+     * it inserts is tagged with the right `step_id`. In-memory only —
+     * the DB is the source of truth for per-message `stepId`.
+     */
+    activeStepByFeature = new Map();
+    constructor(sessionRepo, messageRepo, executorFactory, featureRepo, contextBuilder, workflowStepRepo) {
         this.sessionRepo = sessionRepo;
         this.messageRepo = messageRepo;
         this.executorFactory = executorFactory;
         this.featureRepo = featureRepo;
         this.contextBuilder = contextBuilder;
+        this.workflowStepRepo = workflowStepRepo;
     }
     // ---------------------------------------------------------------------------
     // Public API
     // ---------------------------------------------------------------------------
-    async startSession(featureId, worktreePath, model, agentType) {
+    async startSession(featureId, worktreePath, model, agentType, systemPrompt, initialUserMessage) {
         const cap = this.getCap();
         const activeCount = await this.sessionRepo.countActiveSessions();
         if (activeCount >= cap) {
             throw new ConcurrentSessionLimitError(activeCount, cap);
         }
-        // Create DB record with booting status
+        // ─────────────────────────────────────────────────────────────
+        // Resume-aware boot: look up the previous session's agent
+        // sessionId BEFORE inserting the new row.
+        //
+        // Ordering matters CRITICALLY here. If we created the new DB
+        // session row first and then called `findByFeatureId`, the repo
+        // would return the row we just inserted (most recent by
+        // createdAt) — which has no agentSessionId yet — and the old,
+        // semantically-still-meaningful row would be invisible. That
+        // silently downgrades every reboot to a `createSession` call,
+        // stranding the agent with zero conversation history and making
+        // it answer "this appears to be the start of our conversation"
+        // to the user's second message. Look it up first.
+        // ─────────────────────────────────────────────────────────────
+        let previousAgentSessionId;
+        for (const [, s] of this.sessions) {
+            if (s.featureId === featureId && s.agentSessionId) {
+                previousAgentSessionId = s.agentSessionId;
+                break;
+            }
+        }
+        // Also check stoppedSessions cache (populated on stop)
+        previousAgentSessionId ??= this.stoppedAgentSessionIds.get(featureId);
+        // Fall back to DB — the in-memory cache may be empty after
+        // service restart, hot reload, or Turbopack module re-init.
+        //
+        // Use `findLatestAgentSessionIdForFeature` (not `findByFeatureId`
+        // → `getAgentSessionId`) so we walk BACK through history to find
+        // the most recent session that actually captured an
+        // agentSessionId. This covers the case where the latest row is a
+        // failed-boot session with a NULL agentSessionId — without this,
+        // one bad boot would permanently orphan the agent conversation.
+        previousAgentSessionId ??=
+            (await this.sessionRepo.findLatestAgentSessionIdForFeature(featureId)) ?? undefined;
+        // Create DB record with booting status (AFTER the lookup above).
         const now = new Date();
         const session = {
             id: crypto.randomUUID(),
@@ -80,36 +138,28 @@ export class InteractiveSessionService {
             updatedAt: now,
         };
         await this.sessionRepo.create(session);
+        this.notifyByFeatureId(featureId, {
+            delta: '',
+            done: false,
+            sessionStatus: InteractiveSessionStatus.booting,
+        });
         // Mark as processing immediately so the FAB shows the spinner during boot
-        void this.sessionRepo.updateTurnStatus(session.id, 'processing');
-        // Carry over agentSessionId from previous session so resumption works
-        let previousAgentSessionId;
-        for (const [, s] of this.sessions) {
-            if (s.featureId === featureId && s.agentSessionId) {
-                previousAgentSessionId = s.agentSessionId;
-                break;
-            }
-        }
-        // Also check stoppedSessions cache (populated on stop)
-        previousAgentSessionId ??= this.stoppedAgentSessionIds.get(featureId);
-        // Fall back to DB — the in-memory cache may be empty after service restart
-        if (!previousAgentSessionId) {
-            const latestDbSession = await this.sessionRepo.findByFeatureId(featureId);
-            if (latestDbSession) {
-                previousAgentSessionId =
-                    (await this.sessionRepo.getAgentSessionId(latestDbSession.id)) ?? undefined;
-            }
-        }
-        // Set up in-memory state
+        void this.updateTurnStatusAndNotify(session.id, featureId, 'processing');
+        // Set up in-memory state. CRITICAL: pendingUserContent must be set
+        // BEFORE completeBootAsync is dispatched below. Setting it from the
+        // caller after startSession returns is a race — the async boot may
+        // already be reading state.pendingUserContent === undefined on the
+        // same microtask, fall into the "no-first-turn" branch, and silently
+        // skip the kickoff send.
         const state = {
             sessionId: session.id,
             featureId,
             worktreePath,
             model,
             agentType,
+            systemPrompt,
             handle: null,
             agentSessionId: previousAgentSessionId,
-            timer: null,
             currentAssistantBuffer: '',
             toolEventsLog: [],
             subscribers: new Set(),
@@ -117,6 +167,7 @@ export class InteractiveSessionService {
             turnQueue: [],
             pendingInteraction: null,
             pendingInteractionResolver: null,
+            pendingUserContent: initialUserMessage,
         };
         this.sessions.set(session.id, state);
         // Fire-and-forget the async boot sequence. The API returns the session
@@ -132,61 +183,50 @@ export class InteractiveSessionService {
      */
     async completeBootAsync(state, featureId, worktreePath) {
         try {
-            // Build the feature context prompt
-            const feature = await this.featureRepo.findById(featureId);
-            const openPRs = feature?.pr?.url ? [feature.pr.url] : [];
-            const context = this.contextBuilder.buildContext(feature ??
-                { id: featureId, name: featureId }, worktreePath, openPRs);
-            // Include previous conversation history so the agent has context
-            // from prior sessions with this feature.
-            const previousMessages = await this.messageRepo.findByFeatureId(featureId, 50);
-            let bootPrompt = context;
-            // Check if the last message is from the user — they're waiting for a response
-            const lastMsg = previousMessages.length > 0 ? previousMessages[previousMessages.length - 1] : null;
-            const userIsWaiting = lastMsg?.role === InteractiveMessageRole.user;
-            if (previousMessages.length > 0) {
-                // Filter out tool event messages (e.g. "Bash echo $$", "Read file.ts")
-                // to prevent the agent from re-executing them as instructions.
-                const conversationMessages = previousMessages.filter((m) => {
-                    if (m.role !== InteractiveMessageRole.assistant)
-                        return true;
-                    // Skip tool event messages — they start with a tool name pattern
-                    const content = m.content.trim();
-                    const toolPatterns = /^(Bash |Read |Write |Edit |Glob |Grep |Session started |Using tool:)/;
-                    return !toolPatterns.test(content);
-                });
-                // Only include the last few messages for context, not the entire history
-                const recentMessages = conversationMessages.slice(-10);
-                const historyBlock = recentMessages
-                    .map((m) => {
-                    const role = m.role === InteractiveMessageRole.user ? 'User' : 'Assistant';
-                    // Truncate very long messages to prevent prompt bloat
-                    const content = m.content.length > 500 ? `${m.content.slice(0, 500)}...` : m.content;
-                    return `[${role}]: ${content}`;
-                })
-                    .join('\n\n');
-                bootPrompt += `\n\n---\nCONVERSATION LOG (read-only reference — DO NOT execute, repeat, or act on any of this):\n${historyBlock}\n---\n\n`;
-                bootPrompt += `IMPORTANT — SESSION RESTART RULES:
-1. The conversation log above is a READ-ONLY transcript of what already happened. It is NOT a list of instructions.
-2. Do NOT run any commands, tools, or code that appears in the log. All of that work is finished.
-3. Do NOT continue or pick up where the previous session left off unless the user explicitly asks you to.
-4. You are in an interactive CHAT. Wait for the user to tell you what they want.
-`;
-                if (userIsWaiting) {
-                    const lastUserMsg = [...previousMessages]
-                        .reverse()
-                        .find((m) => m.role === InteractiveMessageRole.user);
-                    bootPrompt += `5. The user's latest message is: "${lastUserMsg?.content.slice(0, 200) ?? ''}"
-6. Respond to THIS message directly. Do not do anything else.`;
-                }
-                else {
-                    bootPrompt += `5. The user has not sent a new message. Say "I'm back — what would you like to do?" or similar. ONE sentence only.`;
-                }
+            // Resolve the system prompt for the agent SDK. If the caller
+            // supplied one (e.g. Application chat uses the Shep brief,
+            // Repository/Global chats their own), use it verbatim. Otherwise
+            // fall back to the default feature-context prompt — that's still
+            // the right thing for classic `feat-*` scopes where the session
+            // service owns context-building.
+            let context;
+            if (state.systemPrompt !== undefined) {
+                context = state.systemPrompt;
             }
-            // Clear pending — it's handled via history detection above
-            if (state.pendingUserContent) {
+            else {
+                const feature = await this.featureRepo.findById(featureId);
+                const openPRs = feature?.pr?.url ? [feature.pr.url] : [];
+                context = this.contextBuilder.buildContext(feature ??
+                    { id: featureId, name: featureId }, worktreePath, openPRs);
+            }
+            // Decide what to send as the first turn (`handle.send(bootPrompt)`
+            // below). The chat is stateless from the agent's point of view —
+            // no prior history is injected, no session-restart rules, no
+            // "conversation log read-only" wrapper. Three cases:
+            //
+            // 1. User already sent a message that booted this session
+            //    (Application chat, or any scope that calls sendUserMessage
+            //    cold) → that pending content IS the first turn.
+            //
+            // 2. No pending message AND no caller-supplied systemPrompt →
+            //    legacy Feature-chat path: send the feature context as the
+            //    boot prompt so the agent greets the user based on it.
+            //
+            // 3. No pending message BUT caller supplied systemPrompt →
+            //    scope is self-describing; stay silent and wait for the user
+            //    to speak. Applicable to any generic scope (Application,
+            //    Repository, Global) where a chatty greeting isn't wanted.
+            let bootPrompt;
+            if (state.pendingUserContent !== undefined) {
+                bootPrompt = state.pendingUserContent;
                 state.pendingUserContent = undefined;
             }
+            else if (state.systemPrompt === undefined) {
+                bootPrompt = context;
+            }
+            else {
+                bootPrompt = '';
+            }
             // Resolve agent type and auth config from settings
             const resolvedAgentType = this.resolveAgentType(state.agentType);
             const authConfig = this.resolveAuthConfig();
@@ -216,21 +256,42 @@ export class InteractiveSessionService {
                 });
             }
             state.handle = handle;
+            // If there's no first user turn to act on, don't push anything —
+            // the session is ready the moment the SDK handle exists. The user
+            // will send their first message through the normal turn path.
+            if (!bootPrompt) {
+                await this.updateSessionStatusAndNotify(state.sessionId, state.featureId, InteractiveSessionStatus.ready);
+                void this.updateTurnStatusAndNotify(state.sessionId, state.featureId, 'idle');
+                return;
+            }
             // Send the boot prompt and iterate stream for the greeting
             await handle.send(bootPrompt);
             let greetingText = '';
             const bootAbort = new AbortController();
             state.streamAbort = bootAbort;
-            // Set up boot timeout
-            const bootTimeout = setTimeout(() => {
+            // Idle watchdog: reset on every event. If the agent goes silent
+            // for longer than BOOT_IDLE_TIMEOUT_MS, abort the boot. This is
+            // NOT a wall-clock budget — long first turns (full project
+            // scaffold + install + build) are fine as long as the stream
+            // keeps producing events.
+            let bootTimeout = setTimeout(() => {
                 bootAbort.abort();
-            }, BOOT_TIMEOUT_MS);
+            }, BOOT_IDLE_TIMEOUT_MS);
+            const bumpBootWatchdog = () => {
+                clearTimeout(bootTimeout);
+                bootTimeout = setTimeout(() => {
+                    bootAbort.abort();
+                }, BOOT_IDLE_TIMEOUT_MS);
+            };
             try {
                 for await (const event of handle.stream()) {
                     if (bootAbort.signal.aborted) {
-                        throw new Error(`Agent boot timed out after ${BOOT_TIMEOUT_MS / 1000}s`);
+                        throw new Error(`Agent boot stalled for ${BOOT_IDLE_TIMEOUT_MS / 1000}s with no stream activity`);
                     }
-                    this.resetTimer(state);
+                    // Any event = proof of life. Reset the boot watchdog so a
+                    // long-running first turn (full project scaffold) isn't
+                    // killed as long as the stream keeps producing events.
+                    bumpBootWatchdog();
                     switch (event.type) {
                         case 'delta':
                             if (event.content) {
@@ -300,19 +361,17 @@ export class InteractiveSessionService {
                                 createdAt: new Date(),
                                 updatedAt: new Date(),
                             };
-                            await this.messageRepo.create(greetingMsg);
-                            await this.sessionRepo.updateStatus(state.sessionId, InteractiveSessionStatus.ready);
+                            await this.persistMessage(greetingMsg);
+                            await this.updateSessionStatusAndNotify(state.sessionId, state.featureId, InteractiveSessionStatus.ready);
                             // If there's a pending user message, the next turn will set 'processing'.
                             // Otherwise boot greeting is expected — mark idle.
                             if (!state.pendingUserContent) {
-                                void this.sessionRepo.updateTurnStatus(state.sessionId, 'idle');
+                                void this.updateTurnStatusAndNotify(state.sessionId, state.featureId, 'idle');
                             }
                             state.currentAssistantBuffer = '';
                             state.toolEventsLog = [];
                             // Notify subscribers of end-of-turn
                             this.notify(state, { delta: '', done: true });
-                            // Start idle timer now that the session is live
-                            this.resetTimer(state);
                             return; // Boot complete
                         }
                         case 'error':
@@ -335,15 +394,14 @@ export class InteractiveSessionService {
                     createdAt: new Date(),
                     updatedAt: new Date(),
                 };
-                await this.messageRepo.create(greetingMsg);
+                await this.persistMessage(greetingMsg);
             }
-            await this.sessionRepo.updateStatus(state.sessionId, InteractiveSessionStatus.ready);
+            await this.updateSessionStatusAndNotify(state.sessionId, state.featureId, InteractiveSessionStatus.ready);
             if (!state.pendingUserContent) {
-                void this.sessionRepo.updateTurnStatus(state.sessionId, 'idle');
+                void this.updateTurnStatusAndNotify(state.sessionId, state.featureId, 'idle');
             }
             state.currentAssistantBuffer = '';
             state.toolEventsLog = [];
-            this.resetTimer(state);
         }
         catch (err) {
             // If session was already cleaned up by stopSession, nothing more to do
@@ -353,7 +411,7 @@ export class InteractiveSessionService {
             // eslint-disable-next-line no-console
             console.error(`[InteractiveSession] boot failed for session ${state.sessionId}:`, err);
             try {
-                await this.sessionRepo.updateStatus(state.sessionId, InteractiveSessionStatus.error);
+                await this.updateSessionStatusAndNotify(state.sessionId, state.featureId, InteractiveSessionStatus.error);
             }
             catch {
                 // Best-effort DB update
@@ -379,7 +437,6 @@ export class InteractiveSessionService {
         }
         state.turnQueue.length = 0;
         state.turnInProgress = false;
-        this.clearTimer(state);
         // Cache agentSessionId so resumption works when session restarts
         if (state.agentSessionId) {
             this.stoppedAgentSessionIds.set(state.featureId, state.agentSessionId);
@@ -395,8 +452,8 @@ export class InteractiveSessionService {
             }
             state.handle = null;
         }
-        await this.sessionRepo.updateStatus(sessionId, InteractiveSessionStatus.stopped, new Date());
-        void this.sessionRepo.updateTurnStatus(sessionId, 'idle');
+        await this.updateSessionStatusAndNotify(sessionId, state.featureId, InteractiveSessionStatus.stopped, new Date());
+        void this.updateTurnStatusAndNotify(sessionId, state.featureId, 'idle');
     }
     async sendMessage(sessionId, content) {
         const dbSession = await this.sessionRepo.findById(sessionId);
@@ -418,9 +475,7 @@ export class InteractiveSessionService {
             createdAt: now,
             updatedAt: now,
         };
-        await this.messageRepo.create(message);
-        // Reset idle timer on user activity
-        this.resetTimer(state);
+        await this.persistMessage(message);
         await this.sessionRepo.updateLastActivity(sessionId, now);
         // Guard: only one turn at a time per session (SDK stream is not concurrent-safe)
         if (state.turnInProgress) {
@@ -443,7 +498,7 @@ export class InteractiveSessionService {
             state.currentAssistantBuffer = '';
             state.toolEventsLog = [];
             // Mark turn as processing for dot indicator
-            void this.sessionRepo.updateTurnStatus(state.sessionId, 'processing');
+            void this.updateTurnStatusAndNotify(state.sessionId, state.featureId, 'processing');
             // Send the message to the SDK session
             await state.handle.send(prompt);
             // Set up abort controller for this stream
@@ -454,8 +509,6 @@ export class InteractiveSessionService {
                 for await (const event of state.handle.stream()) {
                     if (abort.signal.aborted)
                         break;
-                    // Reset idle timer on each event received
-                    this.resetTimer(state);
                     switch (event.type) {
                         case 'delta':
                             if (event.content) {
@@ -510,7 +563,7 @@ export class InteractiveSessionService {
                                 createdAt: now,
                                 updatedAt: now,
                             };
-                            await this.messageRepo.create(msg);
+                            await this.persistMessage(msg);
                             state.currentAssistantBuffer = '';
                             state.toolEventsLog = [];
                             // Accumulate usage from this turn
@@ -524,7 +577,7 @@ export class InteractiveSessionService {
                             }
                             // Mark as unread — if user has the chat open, the frontend
                             // will immediately call markRead to clear it
-                            void this.sessionRepo.updateTurnStatus(state.sessionId, 'unread');
+                            void this.updateTurnStatusAndNotify(state.sessionId, state.featureId, 'unread');
                             // Notify subscribers of end-of-turn
                             this.notify(state, { delta: '', done: true });
                             return; // Turn complete
@@ -619,7 +672,7 @@ export class InteractiveSessionService {
                     createdAt: now,
                     updatedAt: now,
                 };
-                await this.messageRepo.create(msg);
+                await this.persistMessage(msg);
                 state.currentAssistantBuffer = '';
                 state.toolEventsLog = [];
                 this.notify(state, { delta: '', done: true });
@@ -639,7 +692,7 @@ export class InteractiveSessionService {
                 }
                 this.sessions.delete(state.sessionId);
                 try {
-                    await this.sessionRepo.updateStatus(state.sessionId, InteractiveSessionStatus.error);
+                    await this.updateSessionStatusAndNotify(state.sessionId, state.featureId, InteractiveSessionStatus.error);
                 }
                 catch {
                     // Best-effort DB update
@@ -675,6 +728,8 @@ export class InteractiveSessionService {
         }
         // Also clear the cached agentSessionId so next session starts fresh
         this.stoppedAgentSessionIds.delete(featureId);
+        await this.workflowStepRepo.deleteByFeatureId(featureId);
+        this.activeStepByFeature.delete(featureId);
         return this.messageRepo.deleteByFeatureId(featureId);
     }
     async getSession(sessionId) {
@@ -692,7 +747,7 @@ export class InteractiveSessionService {
     // ---------------------------------------------------------------------------
     // Feature-scoped API (frontend doesn't manage sessions)
     // ---------------------------------------------------------------------------
-    async sendUserMessage(featureId, content, worktreePath, model, agentType) {
+    async sendUserMessage(featureId, content, worktreePath, model, agentType, systemPrompt, agentKickoffOverride) {
         // 1. Persist user message to DB immediately — this is the source of truth
         const now = new Date();
         const userMsg = {
@@ -703,7 +758,7 @@ export class InteractiveSessionService {
             createdAt: now,
             updatedAt: now,
         };
-        await this.messageRepo.create(userMsg);
+        await this.persistMessage(userMsg);
         // 2. Find active session for this feature
         let state = this.findActiveStateForFeature(featureId);
         // If the caller requested a different model/agent than the running session,
@@ -724,7 +779,6 @@ export class InteractiveSessionService {
             const dbSession = await this.sessionRepo.findById(state.sessionId);
             if (dbSession?.status === InteractiveSessionStatus.ready) {
                 // Session ready — send to agent (guarded: one turn at a time)
-                this.resetTimer(state);
                 await this.sessionRepo.updateLastActivity(state.sessionId, now);
                 if (state.turnInProgress) {
                     state.turnQueue.push(content);
@@ -748,14 +802,22 @@ export class InteractiveSessionService {
             if (dbSession &&
                 (dbSession.status === InteractiveSessionStatus.ready ||
                     dbSession.status === InteractiveSessionStatus.booting)) {
-                await this.sessionRepo.updateStatus(dbSession.id, InteractiveSessionStatus.stopped, new Date());
-            }
-            // Boot a new session — startSession will find the agentSessionId from DB
-            const session = await this.startSession(featureId, worktreePath, model, agentType);
-            const newState = this.sessions.get(session.id);
-            if (newState) {
-                newState.pendingUserContent = content;
+                await this.updateSessionStatusAndNotify(dbSession.id, featureId, InteractiveSessionStatus.stopped, new Date());
             }
+            // Boot a new session — startSession will find the agentSessionId from DB.
+            // Pass the first-turn content as `initialUserMessage` so it's
+            // written to the session state atomically BEFORE completeBootAsync
+            // is dispatched. Do NOT set pendingUserContent after startSession
+            // returns — that races with the async boot and results in the
+            // first turn being silently dropped.
+            //
+            // When the caller supplies `agentKickoffOverride` (e.g. the
+            // application-creation flow's "read SHEP_BRIEF.md first"
+            // directive), the agent's first turn uses the override while the
+            // DB-persisted user message keeps the raw `content` untouched —
+            // so the chat UI still shows just the user's verbatim request.
+            const firstTurnContent = agentKickoffOverride ?? content;
+            await this.startSession(featureId, worktreePath, model, agentType, systemPrompt, firstTurnContent);
         }
         return userMsg;
     }
@@ -783,7 +845,6 @@ export class InteractiveSessionService {
                 startedAt: dbSession?.startedAt
                     ? new Date(dbSession.startedAt).toISOString()
                     : new Date().toISOString(),
-                idleTimeoutMinutes: Math.round(this.getTimeoutMs() / 60_000),
                 lastActivityAt: dbSession?.lastActivityAt
                     ? new Date(dbSession.lastActivityAt).toISOString()
                     : new Date().toISOString(),
@@ -808,7 +869,6 @@ export class InteractiveSessionService {
                         startedAt: latest.startedAt
                             ? new Date(latest.startedAt).toISOString()
                             : new Date().toISOString(),
-                        idleTimeoutMinutes: Math.round(this.getTimeoutMs() / 60_000),
                         lastActivityAt: latest.lastActivityAt
                             ? new Date(latest.lastActivityAt).toISOString()
                             : new Date().toISOString(),
@@ -836,7 +896,37 @@ export class InteractiveSessionService {
         }
         // Include pending interaction if one exists
         const pendingInteraction = state?.pendingInteraction ?? null;
-        return { messages, sessionStatus, streamingText, sessionInfo, turnStatus, pendingInteraction };
+        // ── Workflow view — derived entirely from the DB so a browser
+        // refresh or daemon restart sees the exact same progress state.
+        // A step row in `running` status means the orchestrator had
+        // started that step before the crash; recovery flips it to
+        // `interrupted` at boot so we never show stale "running" after
+        // the daemon dies.
+        const workflowSteps = await this.workflowStepRepo.listByFeature(featureId);
+        let workflow = null;
+        if (workflowSteps.length > 0) {
+            const running = workflowSteps.find((s) => s.status === WorkflowStepStatus.running);
+            workflow = {
+                workflowId: workflowSteps[0].workflowId,
+                steps: workflowSteps,
+                currentStepId: running?.id ?? null,
+            };
+            // Derive turnStatus from the workflow: if any step is running,
+            // the agent is working — regardless of whether the in-memory
+            // session has been reloaded yet. This is the fix for "lose
+            // in-progress after refresh": the answer is always a SELECT.
+            if (running)
+                turnStatus = 'processing';
+        }
+        return {
+            messages,
+            sessionStatus,
+            streamingText,
+            sessionInfo,
+            turnStatus,
+            pendingInteraction,
+            workflow,
+        };
     }
     subscribeByFeature(featureId, onChunk) {
         // Subscribe at the feature level so the callback survives session restarts.
@@ -855,6 +945,12 @@ export class InteractiveSessionService {
             }
         };
     }
+    subscribeAll(onChunk) {
+        this.globalSubscribers.add(onChunk);
+        return () => {
+            this.globalSubscribers.delete(onChunk);
+        };
+    }
     async stopByFeature(featureId) {
         const state = this.findActiveStateForFeature(featureId);
         if (!state)
@@ -865,13 +961,13 @@ export class InteractiveSessionService {
         // Find the active session for this feature and clear unread status
         const state = this.findActiveStateForFeature(featureId);
         if (state) {
-            void this.sessionRepo.updateTurnStatus(state.sessionId, 'idle');
+            void this.updateTurnStatusAndNotify(state.sessionId, state.featureId, 'idle');
             return;
         }
         // Fallback: check DB for the latest active session
         const latest = await this.sessionRepo.findByFeatureId(featureId);
         if (latest) {
-            void this.sessionRepo.updateTurnStatus(latest.id, 'idle');
+            void this.updateTurnStatusAndNotify(latest.id, featureId, 'idle');
         }
     }
     async getTurnStatuses(featureIds) {
@@ -905,7 +1001,7 @@ export class InteractiveSessionService {
             createdAt: now,
             updatedAt: now,
         };
-        await this.messageRepo.create(userMsg);
+        await this.persistMessage(userMsg);
         // Resolve the Promise that the canUseTool callback is awaiting.
         // This unblocks the SDK stream — the agent resumes with the user's answers.
         state.pendingInteractionResolver(answers);
@@ -913,10 +1009,53 @@ export class InteractiveSessionService {
         state.pendingInteraction = null;
         state.pendingInteractionResolver = null;
         // Update turn status back to processing
-        void this.sessionRepo.updateTurnStatus(state.sessionId, 'processing');
+        void this.updateTurnStatusAndNotify(state.sessionId, state.featureId, 'processing');
         // Clear the "Waiting for your response..." log
         state.subscribers.forEach((sub) => sub({ delta: '', done: false }));
     }
+    // ---------------------------------------------------------------------------
+    // Workflow orchestrator hooks
+    // ---------------------------------------------------------------------------
+    setActiveStep(featureId, stepId) {
+        this.activeStepByFeature.set(featureId, stepId);
+    }
+    clearActiveStep(featureId) {
+        this.activeStepByFeature.delete(featureId);
+    }
+    notifyWorkflowStep(featureId, step) {
+        this.notifyByFeatureId(featureId, {
+            delta: '',
+            done: false,
+            workflowStep: step,
+        });
+    }
+    /**
+     * Resolves the next time any subscriber receives a `done: true`
+     * chunk for the given feature. The orchestrator subscribes BEFORE
+     * sending the step prompt so the resolution can't race with the
+     * agent finishing before the promise is set up.
+     */
+    async waitForTurnDone(featureId, signal) {
+        return new Promise((resolve, reject) => {
+            if (signal?.aborted) {
+                reject(new Error('waitForTurnDone aborted'));
+                return;
+            }
+            const unsubscribe = this.subscribeByFeature(featureId, (chunk) => {
+                if (chunk.done) {
+                    unsubscribe();
+                    signal?.removeEventListener('abort', onAbort);
+                    resolve();
+                }
+            });
+            const onAbort = () => {
+                unsubscribe();
+                signal?.removeEventListener('abort', onAbort);
+                reject(new Error('waitForTurnDone aborted'));
+            };
+            signal?.addEventListener('abort', onAbort);
+        });
+    }
     /**
      * Build the onUserQuestion callback for a session.
      * Called by the SDK's canUseTool when the agent invokes AskUserQuestion.
@@ -938,7 +1077,7 @@ export class InteractiveSessionService {
                     createdAt: now,
                     updatedAt: now,
                 };
-                await this.messageRepo.create(msg);
+                await this.persistMessage(msg);
                 state.currentAssistantBuffer = '';
                 state.toolEventsLog = [];
                 // Notify subscribers so the frontend picks up the new message
@@ -949,7 +1088,7 @@ export class InteractiveSessionService {
             // Store the interaction data for the frontend
             state.pendingInteraction = interaction;
             // Update turn status so the dot indicator shows amber
-            void this.sessionRepo.updateTurnStatus(state.sessionId, 'awaiting_input');
+            void this.updateTurnStatusAndNotify(state.sessionId, state.featureId, 'awaiting_input');
             // Notify subscribers so SSE pushes the interaction to the frontend
             state.subscribers.forEach((sub) => sub({
                 delta: '',
@@ -1014,7 +1153,7 @@ export class InteractiveSessionService {
                 createdAt: new Date(),
                 updatedAt: new Date(),
             };
-            await this.messageRepo.create(msg);
+            await this.persistMessage(msg);
         }
         catch {
             // Non-critical — don't fail the turn for a tool event
@@ -1036,33 +1175,68 @@ export class InteractiveSessionService {
         if (featureSubs) {
             featureSubs.forEach((sub) => sub(chunk));
         }
+        this.globalSubscribers.forEach((sub) => sub(state.featureId, chunk));
+    }
+    /**
+     * Notify feature-level subscribers when no in-memory session state is
+     * available (e.g. while persisting the user message before cold-boot).
+     * Session-scoped subscribers don't exist yet at that point.
+     */
+    notifyByFeatureId(featureId, chunk) {
+        const featureSubs = this.featureSubscribers.get(featureId);
+        if (featureSubs) {
+            featureSubs.forEach((sub) => sub(chunk));
+        }
+        this.globalSubscribers.forEach((sub) => sub(featureId, chunk));
     }
     // ---------------------------------------------------------------------------
-    // Timer helpers
+    // Mutation helpers — every DB write that changes observable state must go
+    // through one of these so SSE subscribers receive a matching notification.
+    // This is the contract that lets the client drop periodic polling.
     // ---------------------------------------------------------------------------
-    /** Start or restart the idle timeout timer for a session. */
-    resetTimer(state) {
-        this.clearTimer(state);
-        const timeoutMs = this.getTimeoutMs();
-        state.timer = setTimeout(() => {
-            void this.stopSession(state.sessionId);
-        }, timeoutMs);
+    /** Persist a message AND notify subscribers. Use everywhere instead of
+     *  calling `messageRepo.create` directly. The current active workflow
+     *  step for the feature (if any) is stamped onto the row so every
+     *  message is grouped under the right step card in the UI. */
+    async persistMessage(message) {
+        const activeStepId = this.activeStepByFeature.get(message.featureId);
+        const tagged = message.stepId || !activeStepId ? message : { ...message, stepId: activeStepId };
+        await this.messageRepo.create(tagged);
+        this.notifyByFeatureId(tagged.featureId, {
+            delta: '',
+            done: false,
+            message: tagged,
+        });
     }
-    /** Cancel the idle timer for a session. */
-    clearTimer(state) {
-        if (state.timer !== null) {
-            clearTimeout(state.timer);
-            state.timer = null;
+    /** Update session status AND notify subscribers. Passes `endedAt` to
+     *  the repo only when supplied so call-arity matches the legacy
+     *  two-argument shape (keeps existing test expectations happy). */
+    async updateSessionStatusAndNotify(sessionId, featureId, status, endedAt) {
+        if (endedAt === undefined) {
+            await this.sessionRepo.updateStatus(sessionId, status);
         }
+        else {
+            await this.sessionRepo.updateStatus(sessionId, status, endedAt);
+        }
+        this.notifyByFeatureId(featureId, {
+            delta: '',
+            done: false,
+            sessionStatus: status,
+        });
     }
-    /** Read the auto-timeout from settings or fall back to default. */
-    getTimeoutMs() {
-        if (!hasSettings())
-            return DEFAULT_TIMEOUT_MS;
-        const settings = getSettings();
-        const minutes = settings.interactiveAgent?.autoTimeoutMinutes ?? 15;
-        return minutes * 60 * 1000;
+    /** Update turn status AND notify subscribers. */
+    async updateTurnStatusAndNotify(sessionId, featureId, turnStatus) {
+        await this.sessionRepo.updateTurnStatus(sessionId, turnStatus);
+        this.notifyByFeatureId(featureId, {
+            delta: '',
+            done: false,
+            turnStatus,
+        });
     }
+    // Idle-eviction timer removed. Live agent sessions are preserved
+    // indefinitely and only stop on an explicit user action (Stop
+    // button, new session reset, server shutdown). See `stopSession`
+    // for the only teardown path.
     /** Read the concurrent session cap from settings or fall back to default. */
     getCap() {
         if (!hasSettings())