specrails-desktop 2.64.2 → 2.65.0

package/server/dist/modules/missions/runtime/agent-chat-manager.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentChatManager = exports.SessionRebuildBusyError = void 0;
+exports.isClosedFlowSessionError = isClosedFlowSessionError;
 exports.sanitizeAgentTitle = sanitizeAgentTitle;
 const crypto_1 = require("crypto");
 const readline_1 = require("readline");
@@ -13,6 +14,7 @@ const promises_1 = require("node:fs/promises");
 const win_spawn_1 = require("../../../util/win-spawn");
 const providers_1 = require("../../../providers");
 const runtime_1 = require("../../../providers/runtime");
+const project_env_1 = require("../../../project-env");
 const registry_1 = require("../../../providers/registry");
 const spawn_lifecycle_1 = require("../../execution/runtime/spawn-lifecycle");
 const live_session_1 = require("../../../providers/live-session");
@@ -23,6 +25,7 @@ const desktop_db_1 = require("../../../desktop-db");
 const feature_flags_1 = require("../../../feature-flags");
 const agent_cwd_manager_1 = require("./agent-cwd-manager");
 const agent_operator_prompt_1 = require("./agent-operator-prompt");
+const mission_tool_policy_1 = require("./mission-tool-policy");
 const agent_mcp_config_1 = require("../../../agent-mcp-config");
 const codex_spawn_1 = require("../../../plugins/codex-spawn");
 const workspace_resolution_1 = require("../../../workspace-resolution");
@@ -36,6 +39,8 @@ const explore_draft_title_1 = require("../../conversations/runtime/explore-draft
 const agent_input_store_1 = require("./agent-input-store");
 const agent_steering_1 = require("./agent-steering");
 const core_session_runner_1 = require("./core-session-runner");
+const audit_1 = require("../../audit");
+const agent_failure_briefing_1 = require("./agent-failure-briefing");
 const agent_session_store_1 = require("./agent-session-store");
 /**
  * Providers report an expired or foreign resume token as a normalized error.
@@ -53,6 +58,12 @@ function isStaleResumeError(message) {
 class SessionRebuildBusyError extends Error {
 }
 exports.SessionRebuildBusyError = SessionRebuildBusyError;
+/** Core refused the turn because the session is closed (or unknown after a restart), or another driver opened it. */
+function isClosedFlowSessionError(error, code) {
+    if (code === 'session_closed' || code === 'session_not_found' || code === 'session_driver_mismatch')
+        return true;
+    return !!error && /\bsession\b[^\n]{0,200}\bis closed\b|session_closed/i.test(error);
+}
 class AgentChatManager {
     _broadcast;
     _db;
@@ -61,6 +72,11 @@ class AgentChatManager {
     _active = new Map();
     /** Missions' Core agent sessions (null = legacy transports only). */
     _coreSessions = null;
+    _agentAudit = null;
+    /** Flow mode port (null = no Flow: every turn is a normal mission turn). */
+    _flowTurns = null;
+    /** Flow Core sessions that already received the conversation history. */
+    _briefedFlowSessions = new Set();
     _nativeInputNotifiers = new Map();
     /** Conversations with a turn in-flight but not yet spawned. Closes the TOCTOU
      *  window the attachment-extraction await opens between the busy guard and
@@ -101,6 +117,86 @@ class AgentChatManager {
     setCoreSessions(coreSessions) {
         this._coreSessions = coreSessions;
     }
+    /** Composition-time wiring of the agent actions audit (per pinned project). */
+    setAgentAudit(resolve) {
+        this._agentAudit = resolve;
+    }
+    /** Composition-time wiring of Flow mode (the Flow module binds the port). */
+    setFlowTurnContext(flowTurns) {
+        this._flowTurns = flowTurns;
+    }
+    /** The active Flow of a conversation, or null (never throws into a turn). */
+    _flowTurn(conversationId) {
+        if (!this._flowTurns)
+            return null;
+        try {
+            return this._flowTurns.forConversation(conversationId);
+        }
+        catch (error) {
+            console.error(`[agent-chat] Flow lookup failed (${conversationId}):`, error);
+            return null;
+        }
+    }
+    /** Whether this turn may offer Flow (never throws into a turn). */
+    async _flowOfferable(conversationId) {
+        if (!this._flowTurns?.offerable)
+            return false;
+        try {
+            return await this._flowTurns.offerable(conversationId);
+        }
+        catch {
+            return false;
+        }
+    }
+    /**
+     * Replace the Flow's Core session for this turn (closed, or opened by another
+     * provider): the Flow commits a new session id, the old one is closed without
+     * touching this turn. Null when the Flow cannot renew (no longer active).
+     */
+    async _renewFlowTurn(conversation, flowTurn, reason) {
+        if (!this._flowTurns?.renewSession)
+            return null;
+        try {
+            const renewed = await this._flowTurns.renewSession(conversation.id, flowTurn.flowId);
+            if (!renewed || renewed.coreSessionId === flowTurn.coreSessionId)
+                return null;
+            if (this._coreSessions)
+                await this._coreSessions.closeFlowSession(conversation, flowTurn.coreSessionId, reason);
+            return renewed;
+        }
+        catch (error) {
+            console.warn(`[agent-chat] Flow session renewal failed (${conversation.id}):`, error);
+            return null;
+        }
+    }
+    /** True while the conversation runs in Flow (mid-turn input interrupts). */
+    isFlowActive(conversationId) {
+        return this._flowTurn(conversationId) !== null;
+    }
+    /** Throws when this conversation's provider cannot run a Flow session now. */
+    async assertFlowSupport(conversationId) {
+        const conversation = (0, agent_store_1.getAgentConversation)(this._db, conversationId);
+        if (!conversation)
+            throw new Error('Unknown conversation');
+        if (!this._coreSessions)
+            throw new Error('Flow needs Core agent sessions, which are not configured');
+        await this._coreSessions.assertFlowSupport(conversation, conversation.provider);
+    }
+    /** Stop a running Flow turn and close the Flow's Core session. Never throws. */
+    async closeFlowSession(conversationId, coreSessionId, reason) {
+        if (this._disposed)
+            return;
+        try {
+            if (this.isBusy(conversationId))
+                this.abort(conversationId);
+            const conversation = (0, agent_store_1.getAgentConversation)(this._db, conversationId);
+            if (conversation && this._coreSessions)
+                await this._coreSessions.closeFlowSession(conversation, coreSessionId, reason);
+        }
+        catch (error) {
+            console.warn(`[agent-chat] closing Flow session ${coreSessionId} failed:`, error);
+        }
+    }
     /** Conversation deleted: close its Core session (reads the row before it is dropped). */
     closeCoreSession(conversationId) {
         const conversation = (0, agent_store_1.getAgentConversation)(this._db, conversationId);
@@ -228,10 +324,11 @@ class AgentChatManager {
     }
     /** Projected Core session state of one mission (null when it never ran in Core). */
     sessionState(conversationId) {
-        const cursor = (0, agent_session_store_1.getSessionCursor)(this._db, conversationId);
-        if (!cursor)
+        // Across the mission's Core sessions: its own and, in Flow, the Flow's.
+        const state = (0, agent_session_store_1.conversationSessionState)(this._db, conversationId);
+        if (!state)
             return null;
-        return { residentPhase: cursor.residentPhase, processAlive: cursor.processAlive, liveSubagents: cursor.liveSubagents, subagents: (0, agent_session_store_1.listSubagents)(this._db, conversationId) };
+        return { ...state, subagents: (0, agent_session_store_1.listSubagents)(this._db, conversationId) };
     }
     /** Stop a mission's background sub-agents through its Core session. */
     async stopSubagents(conversationId, subagentIds) {
@@ -255,6 +352,13 @@ class AgentChatManager {
         return this._coreSessions.waitSubagents(conversation, subagentIds, timeoutMs);
     }
     /** Plugin MCP servers for a project-pinned mission (empty for providers without plugin MCP entries). */
+    /** Base environment of a mission agent: the pinned project's agent
+     *  environment mode when that project is loaded, otherwise the Desktop
+     *  environment (unchanged in `inherit` mode). */
+    _agentBaseEnv(projectId, adapter) {
+        const db = projectId ? this._registry?.getContext(projectId)?.db : undefined;
+        return (0, project_env_1.projectAgentSourceEnv)(db, (0, runtime_1.providerEnvAllowlist)(adapter));
+    }
     _pluginMcpServers(providerId, projectId) {
         const project = projectId ? this._registry?.getProjectRow?.(projectId) : null;
         if (!project)
@@ -421,6 +525,18 @@ class AgentChatManager {
         const conversationId = conversation.id;
         const tierLevel = (0, agent_tier_1.normalizeLevel)(options.tierLevel ?? conversation.tier_level);
         const adapter = (0, providers_1.getAdapter)(conversation.provider);
+        // Flow mode: an active Flow turns this mission turn into a Flow turn (its own
+        // Core session in the worktree). There is no legacy transport for Flow.
+        let flowTurn = this._flowTurn(conversationId);
+        if (flowTurn && !this._coreSessions) {
+            this._emitError(conversationId, 'Flow needs Core agent sessions; this turn was not started.', { code: 'flow_sessions_unavailable', provider: adapter.id });
+            return;
+        }
+        // Never send to a closed Flow session or one another provider opened: a new
+        // session takes the turn (seeded with the conversation history below).
+        if (flowTurn && this._coreSessions && !this._coreSessions.flowSessionUsable(flowTurn.coreSessionId, adapter.id)) {
+            flowTurn = await this._renewFlowTurn(conversation, flowTurn, 'flow_session_renewed') ?? flowTurn;
+        }
         // Resolve a model that is VALID for this provider. A stale model from another
         // provider (e.g. claude's "sonnet" after switching to codex) is rejected by
         // the provider — fall back to the provider's default instead of failing.
@@ -510,7 +626,12 @@ class AgentChatManager {
         const localProtocolNote = (0, registry_1.isLocalAdapterId)(adapter.id)
             ? ' | Protocol: fenced protocol blocks MUST be tagged exactly problem-frame, spec-draft or options (never json); never ask the user to type #noframe'
             : '';
-        const turnSettings = `Permission level: ${tierLevel} (${['observe', 'edit', 'operate', 'autonomous'][tierLevel]}) | Provider: ${adapter.id} | Model: ${model}${reasoningEffort ? ` | Reasoning effort: ${reasoningEffort}` : ''}${localProtocolNote}`;
+        const flowNote = flowTurn
+            ? ` | Flow: worktree=${JSON.stringify(flowTurn.cwd)}${flowTurn.branch ? ` branch=${flowTurn.branch}` : ''} (write only inside it)`
+            // Only await when Flow is wired: an unconditional await would put a
+            // microtask before the spawn on every mission turn (no Flow port ⇒ no offer).
+            : this._flowTurns?.offerable && await this._flowOfferable(conversationId) ? ' | Flow: offerable' : '';
+        const turnSettings = `Permission level: ${tierLevel} (${['observe', 'edit', 'operate', 'autonomous'][tierLevel]}) | Provider: ${adapter.id} | Model: ${model}${reasoningEffort ? ` | Reasoning effort: ${reasoningEffort}` : ''}${localProtocolNote}${flowNote}`;
         const contextPrefix = conversation.pinned_project_id
             ? `[Active project: projectId="${conversation.pinned_project_id}" | ${turnSettings}. Use this project for project-scoped tools; changing the execution target requires changing the conversation pin.]`
             : `[No project pinned (Home) | ${turnSettings}]`;
@@ -522,17 +643,26 @@ class AgentChatManager {
         const inputReceiptNote = options.queueId
             ? `[Mission input ID: ${JSON.stringify(options.queueId)}. After reading this message, confirm receipt with specrails_mission(action:"acknowledge_inputs", inputIds:[this exact ID]). This records reading, not completion of the requested work.]\n\n`
             : '';
-        const prompt = `${contextPrefix}\n\n${projectSnapshot}\n\n${inputReceiptNote}${userWithAttachments}`;
+        // Back to Flow: the review the Flow agent must address rides this user turn once.
+        const flowBriefing = flowTurn?.briefing ? `${flowTurn.briefing}\n\n` : '';
+        const prompt = `${contextPrefix}\n\n${projectSnapshot}\n\n${inputReceiptNote}${flowBriefing}${userWithAttachments}`;
+        const basePrompt = flowTurn ? flowTurn.systemPrompt : (0, agent_operator_prompt_1.buildOperatorSystemPrompt)();
         const systemPrompt = hasAttachments
-            ? `${(0, agent_operator_prompt_1.buildOperatorSystemPrompt)()}\n\n${attachment_manager_1.USER_ATTACHMENT_SYSTEM_NOTE}`
-            : (0, agent_operator_prompt_1.buildOperatorSystemPrompt)();
+            ? `${basePrompt}\n\n${attachment_manager_1.USER_ATTACHMENT_SYSTEM_NOTE}`
+            : basePrompt;
         const effectivePrompt = (useResume) => {
-            const freshPrompt = !useResume && historyBlock ? `${contextPrefix}\n\n${historyBlock}\n\n${prompt}` : prompt;
+            // A Flow session receives the conversation history once (its own Core
+            // session journals the rest); a mission turn includes it when fresh.
+            const withHistory = flowTurn ? !this._briefedFlowSessions.has(flowTurn.coreSessionId) : !useResume;
+            const freshPrompt = withHistory && historyBlock ? `${contextPrefix}\n\n${historyBlock}\n\n${prompt}` : prompt;
             return adapter.capabilities.systemPromptArg ? freshPrompt : `${systemPrompt}\n\n---\n\n${freshPrompt}`;
         };
         // Only pass native image paths to providers that can vision-load them (codex
         // `--image`); claude/gemini already have the `@path` ref folded into prompt.
         const spawnImagePaths = adapter.capabilities.supportsImageInput ? imagePaths : undefined;
+        // Native read-only boundary for legacy transports (one-shot and native live
+        // sessions). Core sessions get the matching session policy instead.
+        const spawnPolicy = flowTurn ? {} : (0, mission_tool_policy_1.missionSpawnPolicy)(adapter);
         let currentCapability = null;
         let currentInvocationId;
         try {
@@ -544,10 +674,13 @@ class AgentChatManager {
             const projectMcpPath = adapter.projectMcpPath?.('.');
             const needsConversationMcpCwd = !!projectMcpPath &&
                 node_path_1.default.dirname(projectMcpPath) !== '.';
-            const cwd = needsConversationMcpCwd
-                ? (0, agent_cwd_manager_1.ensureAgentConversationCwd)(conversationId)
-                : (0, agent_cwd_manager_1.ensureAgentCwd)();
+            const cwd = flowTurn
+                ? flowTurn.cwd
+                : needsConversationMcpCwd
+                    ? (0, agent_cwd_manager_1.ensureAgentConversationCwd)(conversationId)
+                    : (0, agent_cwd_manager_1.ensureAgentCwd)();
             const timestamp = () => new Date().toISOString();
+            let missionCoreTurn = false;
             const invoke = async (useResume) => {
                 // A stale-session retry is another process: its capability and bearer
                 // file must be new so late calls from the old bridge stay revoked.
@@ -560,14 +693,17 @@ class AgentChatManager {
                 // Core agent sessions: a resident session presents this turn's capability
                 // through structured MCP specs (no provider-specific argv).
                 const coreContext = this._coreSessions
-                    ? await this._coreSessions.prepareTurn(conversation, adapter, { capability: agentCapability, external: (0, external_mcp_1.resolveExternalEntries)(adapter.id, this._db), plugins: this._pluginMcpServers(adapter.id, conversation.pinned_project_id) })
+                    ? await this._coreSessions.prepareTurn(conversation, adapter, { capability: agentCapability, external: (0, external_mcp_1.resolveExternalEntries)(adapter.id, this._db), plugins: this._pluginMcpServers(adapter.id, conversation.pinned_project_id), flow: flowTurn })
                     : null;
+                if (coreContext && !flowTurn)
+                    missionCoreTurn = true;
                 if (!coreContext)
                     try {
                         const wiring = (0, agent_mcp_config_1.prepareAgentMcp)({
                             adapterId: adapter.id, conversationId, invocationId, cwd,
                             port: this._port, capability: agentCapability,
                             external: (0, external_mcp_1.resolveExternalEntries)(adapter.id, this._db),
+                            readOnly: spawnPolicy.toolPolicy === 'read-only',
                         });
                         mcpArgs = wiring.extraArgs;
                         mcpEnv = wiring.env;
@@ -588,15 +724,19 @@ class AgentChatManager {
                 let capturedSessionId = useResume ? conversation.session_id ?? null : null;
                 let capturedError = null;
                 console.log(`[agent-chat] turn start conv=${conversationId} provider=${adapter.id} binary=${adapter.binary} ` +
-                    `action=${action} model=${model} cwd=${cwd} mcp=${coreContext ? `core-session:${coreContext.mcpServers.map((server) => server.name).join(',') || 'none'}` : mcpArgs.length ? 'mcp-config' : Object.keys(mcpEnv).join(',') || 'none'}`);
+                    `action=${action} model=${model} cwd=${cwd} mcp=${coreContext ? `core-session:${coreContext.mcpServers.map((server) => server.name).join(',') || 'none'}` : mcpArgs.length ? 'mcp-config' : Object.keys(mcpEnv).join(',') || 'none'} ` +
+                    `tools=${coreContext ? `core:${coreContext.policy.permissions ?? 'default'}/${coreContext.policy.tools?.mode ?? 'default'}` : spawnPolicy.toolPolicy ?? `default(${(0, mission_tool_policy_1.missionReadOnlyGap)(adapter) ?? 'n/a'})`}`);
                 const buildOpts = {
-                    prompt: effectivePrompt(useResume),
+                    // A new mission session generation is seeded with the conversation history.
+                    prompt: effectivePrompt(useResume && !coreContext?.freshSession),
                     systemPrompt: adapter.capabilities.systemPromptArg ? systemPrompt : undefined,
                     model,
-                    sessionId: useResume ? conversation.session_id ?? undefined : undefined,
+                    sessionId: useResume && !flowTurn ? conversation.session_id ?? undefined : undefined,
                     extraArgs: mcpArgs,
                     imagePaths: spawnImagePaths,
                     reasoning_effort: reasoningEffort,
+                    // Read-only by construction (mission-read-only-policy); MCP tools stay callable.
+                    ...spawnPolicy,
                 };
                 const nativeRunner = coreContext ? (0, core_session_runner_1.createCoreSessionRunner)(coreContext) : (0, live_session_1.nativeLiveSessionRunner)(adapter);
                 let invocationLive = true;
@@ -844,7 +984,7 @@ class AgentChatManager {
                     adapter,
                     action,
                     cwd,
-                    env: (0, runtime_1.buildProviderEnv)(adapter, buildOpts, { ...process.env, ...mcpEnv }),
+                    env: (0, runtime_1.buildProviderEnv)(adapter, buildOpts, { ...this._agentBaseEnv(conversation.pinned_project_id, adapter), ...mcpEnv }),
                     spawn: this._spawnOwned.bind(this),
                     buildOpts,
                     inactivityTimeoutMs: Number.parseInt(process.env.SPECRAILS_AGENT_INACTIVITY_MS ?? '', 10) || 5 * 60_000,
@@ -871,6 +1011,16 @@ class AgentChatManager {
                                 }
                                 break;
                             case 'tool-use':
+                                // Core-session turns are audited by the session projector (full
+                                // input); native provider turns are audited here from the preview.
+                                if (!coreContext && this._agentAudit && conversation.pinned_project_id) {
+                                    try {
+                                        const recorder = this._agentAudit(conversation.pinned_project_id);
+                                        if (recorder)
+                                            (0, audit_1.recordToolCall)(recorder, { runId: conversationId, role: 'mission', source: 'provider-stream' }, ev.name, ev.inputPreview);
+                                    }
+                                    catch { /* audit is observing only */ }
+                                }
                                 if (this._isTurnLive(conversationId)) {
                                     this._broadcast({
                                         type: 'agent_tool',
@@ -970,7 +1120,8 @@ class AgentChatManager {
             // is still the one this turn actually ran on (a foreign session id must not
             // pollute the new provider's freshly-reset state).
             const persistSession = (sessionId) => {
-                if (this._disposed)
+                // A Flow turn's provider session belongs to the Flow's Core session, never the mission's.
+                if (this._disposed || flowTurn)
                     return;
                 const fresh = (0, agent_store_1.getAgentConversation)(this._db, conversationId);
                 if (fresh && fresh.provider === conversation.provider) {
@@ -994,9 +1145,9 @@ class AgentChatManager {
             const record = (outcome, status) => {
                 if (this._disposed || outcome.disposed)
                     return;
-                this._recordTurn(conversation, adapter, model, outcome, status);
+                this._recordTurn(conversation, adapter, model, outcome, status, flowTurn ? 'flow' : 'agent-chat');
             };
-            const canResume = !!conversation.session_id && adapter.capabilities.nativeResume;
+            const canResume = !flowTurn && !!conversation.session_id && adapter.capabilities.nativeResume;
             let r = await invoke(canResume);
             if (this._disposed || r.disposed)
                 return;
@@ -1012,6 +1163,54 @@ class AgentChatManager {
                 record(r, 'aborted');
                 return;
             }
+            // A Flow session Core reports closed (a journal closed by a pause, a
+            // hand-off or a previous process): reopen as a new session and retry
+            // once, never a user-facing failure. Nothing ran in a closed session.
+            if (flowTurn &&
+                !r.spawnFailed && !r.fullText && !r.checkpointed &&
+                !r.events.some((event) => event.kind === 'tool-use' || event.kind === 'tool-result') &&
+                isClosedFlowSessionError(r.error, r.errorCode)) {
+                const renewed = await this._renewFlowTurn(conversation, flowTurn, 'flow_session_closed');
+                if (renewed) {
+                    console.log(`[agent-chat] Flow session ${flowTurn.coreSessionId} is closed — retrying in ${renewed.coreSessionId} conv=${conversationId}`);
+                    flowTurn = renewed;
+                    r = await invoke(false);
+                    if (this._disposed || r.disposed)
+                        return;
+                    if (!(0, agent_store_1.getAgentConversation)(this._db, conversationId)) {
+                        record(r, 'aborted');
+                        return;
+                    }
+                    if (this._abortedTurns.delete(conversationId)) {
+                        settleAborted(r);
+                        record(r, 'aborted');
+                        return;
+                    }
+                }
+            }
+            // The mission's Core session is closed or was opened by another provider
+            // (e.g. a switch before this process knew the session's driver): continue
+            // in a new generation, seeded with the history, once. Nothing ran.
+            if (!flowTurn && missionCoreTurn && this._coreSessions &&
+                !r.spawnFailed && !r.fullText && !r.checkpointed &&
+                !r.events.some((event) => event.kind === 'tool-use' || event.kind === 'tool-result') &&
+                isClosedFlowSessionError(r.error, r.errorCode)) {
+                const renewed = await this._coreSessions.renewMissionSession(conversation, adapter.id, r.errorCode === 'session_driver_mismatch' ? 'driver_mismatch' : 'session_closed');
+                console.log(`[agent-chat] mission Core session unusable (${r.errorCode ?? r.error}) — retrying in ${renewed} conv=${conversationId}`);
+                persistSession(null);
+                r = await invoke(false);
+                if (this._disposed || r.disposed)
+                    return;
+                if (!(0, agent_store_1.getAgentConversation)(this._db, conversationId)) {
+                    record(r, 'aborted');
+                    return;
+                }
+                if (this._abortedTurns.delete(conversationId)) {
+                    settleAborted(r);
+                    record(r, 'aborted');
+                    return;
+                }
+            }
             // Retry only a verified stale resume that did not execute tools. An empty
             // reply can still have launched a rail or edited a spec; replaying that
             // turn would duplicate its mutations and spend tokens twice.
@@ -1055,6 +1254,11 @@ class AgentChatManager {
                 record(r, 'failed');
                 return;
             }
+            if (flowTurn)
+                this._briefedFlowSessions.add(flowTurn.coreSessionId);
+            if (flowTurn?.briefing && this._flowTurns?.briefingDelivered) {
+                void this._flowTurns.briefingDelivered(conversationId, flowTurn.flowId).catch((error) => console.warn(`[agent-chat] Flow return briefing not cleared (${conversationId}): ${error instanceof Error ? error.message : String(error)}`));
+            }
             if (r.text || r.checkpointed) {
                 const message = r.text ? (0, agent_store_1.addAgentMessage)(this._db, { conversationId, role: 'assistant', content: r.text, ...(r.coreTurnId ? { coreTurnId: r.coreTurnId, turnOrigin: 'user' } : {}) }) : undefined;
                 persistSession(r.sessionId);
@@ -1092,7 +1296,7 @@ class AgentChatManager {
      * Broadcasts `spending.invalidated` for the pinned project (app-global Home
      * turns carry no projectId, so no per-project dashboard to invalidate).
      */
-    _recordTurn(conversation, adapter, model, outcome, status) {
+    _recordTurn(conversation, adapter, model, outcome, status, surface = 'agent-chat') {
         if (this._disposed)
             return;
         try {
@@ -1107,6 +1311,7 @@ class AgentChatManager {
                 conversation_id: conversation.id,
                 project_id: conversation.pinned_project_id ?? null,
                 provider: adapter.id,
+                surface,
                 status,
                 started_at: outcome.startedAt,
                 finished_at: finishedAt,
@@ -1303,6 +1508,17 @@ class AgentChatManager {
                 this.postPrDecisionCard(conversationId, envelope);
                 return;
             }
+            // A Flow → Spec run that went back to its Flow keeps the failure it
+            // stopped with (the settle-time `runtime` snapshot): the delivery's own
+            // codes now say `returned_to_flow`, and the card still explains why.
+            if (envelope.statusCode === 'returned_to_flow' && !envelope.runtime) {
+                try {
+                    const previous = JSON.parse(existing[existing.length - 1].content);
+                    if (previous.runtime?.failure)
+                        envelope = { ...envelope, runtime: previous.runtime };
+                }
+                catch { /* a malformed stored card is simply replaced */ }
+            }
             const serialized = JSON.stringify(envelope);
             // Keep the newest history anchor: client cold-load dedupe uses the same
             // newest-row rule, so a crash between hydration and this repair cannot
@@ -1388,6 +1604,53 @@ class AgentChatManager {
         }
     }
     _systemTurnRuns = new Set();
+    /**
+     * Persist an app-authored system row once per `dedupeKey` (durable: an
+     * existing row with the same key is never duplicated, across restarts too)
+     * and broadcast `agent_system_row` so open clients append it live. NEVER throws.
+     */
+    postSystemRow(conversationId, row, dedupeKey) {
+        if (this._disposed)
+            return null;
+        try {
+            if (!(0, agent_store_1.getAgentConversation)(this._db, conversationId))
+                return null;
+            const existing = (0, agent_store_1.findAgentSystemMessages)(this._db, conversationId, (content) => {
+                try {
+                    return JSON.parse(content).dedupeKey === dedupeKey;
+                }
+                catch {
+                    return false;
+                }
+            });
+            if (existing.length > 0)
+                return null;
+            const content = { ...row, dedupeKey };
+            const message = (0, agent_store_1.addAgentMessage)(this._db, { conversationId, role: 'system', content: JSON.stringify(content) });
+            this._broadcast({ type: 'agent_system_row', conversationId, messageId: message.id, ...content, timestamp: message.created_at });
+            return message.id;
+        }
+        catch (err) {
+            console.error(`[agent-chat] postSystemRow failed (${conversationId}):`, err);
+            return null;
+        }
+    }
+    /**
+     * Start ONE automatic, app-authored turn through the normal path (queued
+     * behind a live turn, Flow-aware, accounted, interruptible). The durable
+     * queue id `turnKey` makes a repeat (reload, retry, restart) a no-op. It is
+     * rendered as a muted automatic briefing, never as the person's speech.
+     * Returns once admitted; the turn runs in the background. NEVER throws.
+     */
+    async startAutomaticTurn(conversationId, text, opts) {
+        if (this._disposed || !(0, agent_store_1.getAgentConversation)(this._db, conversationId))
+            return 'skipped';
+        if ((0, agent_input_store_1.getAgentInput)(this._db, conversationId, opts.turnKey))
+            return 'skipped';
+        const ref = { kind: agent_failure_briefing_1.FAILURE_BRIEFING_REF_KIND, id: opts.turnKey, label: opts.label, token: '', metadata: { automatic: true } };
+        void this.sendMessage(conversationId, text, { queueId: opts.turnKey, contextRefs: [ref] }).catch((err) => console.error(`[agent-chat] automatic turn failed (${conversationId}):`, err));
+        return 'started';
+    }
     /**
      * Dismiss a RUN-ONLY card (mission-rail-cards: a shared-cwd launch keyed on a
      * synthetic `run:<runId>` id — there is no delivery row for the decision