specrails-desktop 2.61.0 → 2.63.0

package/server/dist/modules/agents/runtime/agent-store.js

@@ -47,6 +47,8 @@ function mapMessage(row) {
         attachment_ids: ids,
         context_refs: parseJsonArray(row.context_refs, isContextRef),
         intents: parseIntents(row.intent),
+        ...(row.core_turn_id ? { core_turn_id: row.core_turn_id } : {}),
+        ...(row.turn_origin === 'user' || row.turn_origin === 'subagent' || row.turn_origin === 'system' ? { turn_origin: row.turn_origin } : {}),
         created_at: row.created_at,
     };
 }
@@ -128,7 +130,7 @@ function addAgentMessage(db, input) {
     const id = (0, crypto_1.randomUUID)();
     const attachmentIds = input.attachmentIds && input.attachmentIds.length ? JSON.stringify(input.attachmentIds) : null;
     const contextRefs = input.contextRefs && input.contextRefs.length ? JSON.stringify(input.contextRefs) : null;
-    db.prepare('INSERT INTO agent_messages (id, conversation_id, role, content, attachment_ids, context_refs) VALUES (?, ?, ?, ?, ?, ?)').run(id, input.conversationId, input.role, input.content, attachmentIds, contextRefs);
+    db.prepare('INSERT INTO agent_messages (id, conversation_id, role, content, attachment_ids, context_refs, turn_origin, core_turn_id) VALUES (?, ?, ?, ?, ?, ?, ?, ?)').run(id, input.conversationId, input.role, input.content, attachmentIds, contextRefs, input.turnOrigin ?? null, input.coreTurnId ?? null);
     // Touch the parent so the list stays ordered by latest activity.
     db.prepare("UPDATE agent_conversations SET updated_at = datetime('now') WHERE id = ?").run(input.conversationId);
     return mapMessage(db.prepare('SELECT * FROM agent_messages WHERE id = ?').get(id));

package/server/dist/modules/execution/runtime/queue-manager.js

@@ -2217,8 +2217,12 @@ class QueueManager {
         // values are read from the server env (with login-shell recovery for missing
         // names) at spawn time. Apply this before Specrails' own env overlays so
         // internal SPECRAILS_* control-plane values always win.
+        let environmentNotice = null;
         if (this._db) {
             spawnEnv = (0, project_env_1.applyWorktreeEnvPassthrough)(this._db, spawnEnv);
+            // One value-free line naming unresolved configured names (written to the
+            // job log once the readers exist). The run proceeds without them.
+            environmentNotice = (0, project_env_1.worktreeEnvPassthroughWarning)(this._db, spawnEnv);
         }
         const telemetryEnabled = !!(this._projectId && this._db && (0, db_1.getProjectSettings)(this._db).pipelineTelemetryEnabled);
         // Resolve the framework version ONCE at spawn time — `framework/current`
@@ -2605,6 +2609,10 @@ class QueueManager {
         const stdoutReader = (0, readline_1.createInterface)({ input: child.stdout, crlfDelay: Infinity });
         const stderrReader = (0, readline_1.createInterface)({ input: child.stderr, crlfDelay: Infinity });
         this._jobReaders.set(jobId, { stdout: stdoutReader, stderr: stderrReader });
+        if (environmentNotice) {
+            persistEvent({ event_type: 'log', source: 'stderr', payload: JSON.stringify({ line: environmentNotice }) }, false);
+            emitLine('stderr', environmentNotice);
+        }
         stdoutReader.on('line', (line) => {
             if (this._disposed)
                 return;

package/server/dist/modules/loops/runtime/loop-executors.js

@@ -181,6 +181,7 @@ function createLoopExecutors(opts = {}) {
     const completionContexts = new Map();
     const runtimeConfigPath = (cwd) => (0, node_path_1.join)(opts.pluginScope?.().stateRoot ?? cwd, '.specrails', 'agent-runtime.json');
     return {
+        ...(opts.environmentNotice ? { environmentNotice: opts.environmentNotice } : {}),
         async cancelDefinition({ runId, contextPath, requestId }) {
             const host = (0, agent_runtime_bridge_1.readFrozenRuntimeHost)(contextPath, resolveEnv(), runId);
             await (0, agent_runtime_bridge_1.runAgentRuntimeControl)({ kind: 'cancel', runId, contextPath, requestId, ...host });

package/server/dist/modules/loops/runtime/loop-implement-recipe.js

@@ -48,10 +48,21 @@ function configurableImplementGraph(capabilities) {
     node('reset-confidence', 'Reset confidence after answer', 'assign', { set: { planInvestigated: false } }, { next: 'architect', failed: 'failed' });
     node('validate', 'Validate OpenSpec', 'openspec-validate', { change }, { pass: 'freeze', fail: 'architect', failed: 'failed' });
     node('freeze', 'Freeze approved artifacts', 'artifact-contract', { change, contractId: 'plan', action: 'freeze' }, { pass: 'initialize-corrections', fail: 'architect', failed: 'failed' });
-    node('initialize-corrections', 'Initialize automatic correction budget', 'assign', { set: { correctionAttempts: 0, correctionLimit: 3 } }, { next: 'developer', failed: 'failed' });
+    node('initialize-corrections', 'Initialize automatic correction budget', 'assign', { set: { correctionAttempts: 0, correctionLimit: 3, implementationAttempts: 0, implementationLimit: 3 } }, { next: 'developer', failed: 'failed' });
     const implementation = objectSchema({ summary: string, incomplete: strings, blocker }, ['summary', 'incomplete']);
-    turn('developer', 'Developer', 'build', `Implement every approved task for change ${change} using the bound official apply skill. Preserve proposal, design and specs; only tick tasks you completed. Report summary and incomplete task descriptions. Prior execution evidence and human answers: {{history.text}}`, implementation, 'tasks', writes);
-    node('tasks', 'Check artifacts and completed tasks', 'artifact-contract', { change, contractId: 'plan', action: 'check', requireCompletedTasks: true }, { pass: 'verify', fail: 'developer', failed: 'failed' });
+    turn('developer', 'Developer', 'build', `Implement every approved task for change ${change} using the bound official apply skill. Preserve proposal, design and specs; only tick tasks you completed. Report summary and incomplete task descriptions. If a task cannot be finished because of a host precondition or environment blocker outside this change (for example the sandbox forbids starting a local server, a credential or tool is missing), keep the work done, leave that task unchecked and return the structured blocker (kind, command, cwd, evidence, requiredAction). A failing test, a test you cannot make pass, or unexpected browser or tool behaviour is NOT a host blocker: change the test or the implementation instead. The host confirms a blocker by running its own verification before ending the run; a failure it reproduces comes back as a correction. Prior execution evidence and human answers: {{history.text}}`, implementation, 'developer-blocker', writes);
+    node('developer-blocker', 'Developer reported a host blocker', 'condition', { expr: 'exists($outputs.developer.structured.blocker) && $outputs.developer.structured.blocker != null' }, { true: 'developer-blocker-kind', false: 'tasks' });
+    // Credentials, network and variables are the person's to provide. Any other
+    // blocker is confirmed by the host's own verification: a host precondition
+    // ends at host-blocked, a reproduced failure becomes a correction, and
+    // passing checks reach the reviewer, whose rejection of unfinished tasks is
+    // corrected within the same budget.
+    node('developer-blocker-kind', 'Blocker needs the person', 'condition', { expr: ['credential', 'network', 'environment-variable'].map(kind => `$outputs.developer.structured.blocker.kind == "${kind}"`).join(' || ') }, { true: 'developer-blocked', false: 'verify' });
+    node('tasks', 'Check artifacts and completed tasks', 'artifact-contract', { change, contractId: 'plan', action: 'check', requireCompletedTasks: true }, { pass: 'verify', fail: 'implementation-budget', failed: 'failed' });
+    // Incomplete tasks send the developer back, but only while each attempt changes the candidate and within budget.
+    node('implementation-budget', 'Check implementation attempt budget', 'condition', { expr: '$vars.implementationAttempts < $vars.implementationLimit' }, { true: 'implementation-progress', false: 'implementation-exhausted' });
+    node('implementation-progress', 'Check implementation progress', 'condition', { expr: '!exists($vars.lastImplementationHash) || $outputs.developer.candidateHash != $vars.lastImplementationHash' }, { true: 'begin-implementation', false: 'implementation-stalled' });
+    node('begin-implementation', 'Count implementation attempt', 'assign', { increment: { implementationAttempts: 1 }, set: { lastImplementationHash: '{{outputs.developer.candidateHash}}' } }, { next: 'developer', failed: 'failed' });
     node('verify', 'Verify candidate', 'verify', verifyParams, verifyEnds('reviewer', 'correction-context', 'host-blocked'));
     turn('reviewer', 'Reviewer', 'assess', `Review change ${change} read-only against all approved artifacts and frozen ticket acceptance criteria. Inspect real code and the host verification evidence: {{outputs.verify}}. Return approved, summary, issues, score (0-100), and aspects. Acceptance policy: ${reviewPolicy}. For any rejection or below-threshold score, explain the concrete unmet requirement and actionable repair in summary and issues; passing commands do not prove every acceptance obligation. Prior execution: {{history.text}}`, objectSchema({ approved: { type: 'boolean' }, summary: string, issues: strings, score, aspects: objectSchema(Object.fromEntries(Object.keys(aspects).map(aspect => [aspect, score]))) }), 'review-policy');
     node('review-policy', 'Review acceptance policy', 'condition', { expr: ['$outputs.reviewer.structured.approved == true', '$outputs.reviewer.structured.issues.length == 0', '$outputs.reviewer.structured.score >= 70', ...Object.entries(aspects).map(([aspect, threshold]) => `$outputs.reviewer.structured.aspects.${aspect} >= ${threshold}`)].join(' && ') }, { true: 'approve', false: 'correction-context' });
@@ -67,7 +78,7 @@ function configurableImplementGraph(capabilities) {
     node('approval-policy', 'Approval decision', 'condition', { expr: '$outputs.approve.response.approved == true' }, { true: 'archive', false: 'failed' });
     node('archive', 'Archive OpenSpec', 'openspec-archive', { change, allowArchived: true, requiresVerified: true, reviewedCandidate: '{{outputs.reviewer.candidateHash}}', approvedCandidate: '{{outputs.approve.candidateHash}}' }, { next: 'verify-archive', failed: 'verify' });
     node('verify-archive', 'Verify archived candidate', 'verify', verifyParams, verifyEnds('done', 'failed', 'host-blocked-archive'));
-    nodes.push({ id: 'done', type: 'end', position: { x: 0, y: nodes.length * 140 }, data: { outcome: 'success', requiresVerified: true } }, { id: 'failed', type: 'end', position: { x: 360, y: nodes.length * 140 }, data: { outcome: 'failure' } }, { id: 'correction-stalled', type: 'end', position: { x: 720, y: nodes.length * 140 }, data: { outcome: 'failure', reason: `Automatic correction made no candidate changes. Host verification is valid: {{outputs.verify.valid}}. Acceptance policy: ${reviewPolicy}. Latest review findings: {{run.latestReview}}. Fixer diagnosis: {{outputs.fixer.structured.summary}}` } }, { id: 'correction-exhausted', type: 'end', position: { x: 1080, y: nodes.length * 140 }, data: { outcome: 'failure', reason: `Automatic correction limit reached ({{run.correctionAttempts}}/{{run.correctionLimit}}). Acceptance policy: ${reviewPolicy}. Latest review findings: {{run.latestReview}}. Fixer diagnosis: {{outputs.fixer.structured.summary}}. Host verification: {{outputs.verify}}` } }, { id: 'fixer-blocked', type: 'end', position: { x: 1440, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'Fixer reported a host blocker ({{outputs.fixer.structured.blocker.kind}}): {{outputs.fixer.structured.blocker.requiredAction}} Evidence: {{outputs.fixer.structured.blocker.evidence}}', ...(hostBlockers ? { blockerFrom: 'fixer' } : {}) } });
+    nodes.push({ id: 'done', type: 'end', position: { x: 0, y: nodes.length * 140 }, data: { outcome: 'success', requiresVerified: true } }, { id: 'failed', type: 'end', position: { x: 360, y: nodes.length * 140 }, data: { outcome: 'failure' } }, { id: 'correction-stalled', type: 'end', position: { x: 720, y: nodes.length * 140 }, data: { outcome: 'failure', reason: `Automatic correction made no candidate changes. Host verification is valid: {{outputs.verify.valid}}. Acceptance policy: ${reviewPolicy}. Latest review findings: {{run.latestReview}}. Fixer diagnosis: {{outputs.fixer.structured.summary}}` } }, { id: 'correction-exhausted', type: 'end', position: { x: 1080, y: nodes.length * 140 }, data: { outcome: 'failure', reason: `Automatic correction limit reached ({{run.correctionAttempts}}/{{run.correctionLimit}}). Acceptance policy: ${reviewPolicy}. Latest review findings: {{run.latestReview}}. Fixer diagnosis: {{outputs.fixer.structured.summary}}. Host verification: {{outputs.verify}}` } }, { id: 'implementation-stalled', type: 'end', position: { x: 720, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'The developer made no changes while approved tasks are still incomplete. Incomplete: {{outputs.developer.structured.incomplete}}. Developer summary: {{outputs.developer.structured.summary}}' } }, { id: 'implementation-exhausted', type: 'end', position: { x: 1080, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'Implementation attempt limit reached ({{run.implementationAttempts}}/{{run.implementationLimit}}) with approved tasks still incomplete. Incomplete: {{outputs.developer.structured.incomplete}}. Developer summary: {{outputs.developer.structured.summary}}' } }, { id: 'developer-blocked', type: 'end', position: { x: 1440, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'Developer reported a host blocker ({{outputs.developer.structured.blocker.kind}}): {{outputs.developer.structured.blocker.requiredAction}} Evidence: {{outputs.developer.structured.blocker.evidence}}', ...(hostBlockers ? { blockerFrom: 'developer' } : {}) } }, { id: 'fixer-blocked', type: 'end', position: { x: 1440, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'Fixer reported a host blocker ({{outputs.fixer.structured.blocker.kind}}): {{outputs.fixer.structured.blocker.requiredAction}} Evidence: {{outputs.fixer.structured.blocker.evidence}}', ...(hostBlockers ? { blockerFrom: 'fixer' } : {}) } });
     if (hostBlockers) {
         const hostBlocked = (id, source) => ({ id, type: 'end', position: { x: 1800, y: nodes.length * 140 }, data: { outcome: 'failure', blockerFrom: source, reason: `Host blocker ({{outputs.${source}.blocker.kind}}): {{outputs.${source}.blocker.reason}} Required action: {{outputs.${source}.blocker.requiredAction}}` } });
         nodes.push(hostBlocked('host-blocked', 'verify'), hostBlocked('host-blocked-archive', 'verify-archive'));

package/server/dist/modules/loops/runtime/loop-run-manager.js

@@ -756,6 +756,10 @@ class LoopRunManager {
             throw new Error('runtime_run_completed: Fork a completed workflow to continue');
         this._cancelled.delete(runId);
         this.claimDefinition({ ...frozen.request, runId });
+        // Cards and chips that showed the restart/interruption pause follow the resumed run live.
+        const request = frozen.request;
+        this._emit({ type: 'loop.run_resumed', projectId: request.projectId, loopRunId: runId, railIndex: request.railIndex ?? null,
+            ticketIds: request.spec?.ticketIds ?? (request.ticketId == null ? [] : [request.ticketId]) });
         const task = this._run(frozen.request, { resume: true, ...input }).finally(() => { this.releaseDefinition(runId); this._definitionTasks.delete(runId); });
         this._definitionTasks.set(runId, task);
         return task;
@@ -1005,6 +1009,13 @@ class LoopRunManager {
         logLine(`▶ Loop "${req.loopName ?? req.loopId}" started${req.spec?.title ? ` — spec: ${req.spec.title}` : ''}`);
         if (req.isolation)
             logLine(`⎇ Isolated worktree: ${req.isolation.worktreePath} (branch ${req.isolation.branch})`);
+        let environmentNotice = null;
+        try {
+            environmentNotice = this.executors.environmentNotice?.() ?? null;
+        }
+        catch { /* diagnostic only */ }
+        if (environmentNotice)
+            logLine(environmentNotice, 'stderr');
         if (!definitionEngine && !usageTelemetryAvailable) {
             logLine(`⚠️ ${adapter.displayName} does not report token/cost usage in headless mode; usage totals will remain unavailable.` +
                 (configuredMaxCostUsd !== undefined

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

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentChatManager = void 0;
+exports.AgentChatManager = exports.SessionRebuildBusyError = void 0;
 exports.sanitizeAgentTitle = sanitizeAgentTitle;
 const crypto_1 = require("crypto");
 const readline_1 = require("readline");
@@ -35,6 +35,8 @@ const agent_store_1 = require("../../agents/runtime/agent-store");
 const explore_draft_title_1 = require("../../conversations/runtime/explore-draft-title");
 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 agent_session_store_1 = require("./agent-session-store");
 /**
  * Providers report an expired or foreign resume token as a normalized error.
  * Those errors are safe to recover from by clearing the token and retrying the
@@ -47,12 +49,18 @@ function isStaleResumeError(message) {
         /unknown (?:session|thread)(?: id)?\b/i.test(message) ||
         /(?:session|thread)(?: id)?\b[^\n]{0,160}\b(?:not found|does not exist)\b/i.test(message));
 }
+/** A projection rebuild was requested while a turn is running. */
+class SessionRebuildBusyError extends Error {
+}
+exports.SessionRebuildBusyError = SessionRebuildBusyError;
 class AgentChatManager {
     _broadcast;
     _db;
     _port;
     _registry;
     _active = new Map();
+    /** Missions' Core agent sessions (null = legacy transports only). */
+    _coreSessions = null;
     _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
@@ -89,6 +97,21 @@ class AgentChatManager {
         // A sidecar restart must retain unsent input without replaying operations.
         (0, agent_input_store_1.recoverPendingAgentInputs)(db);
     }
+    /** Composition-time wiring of Core agent sessions (see agent-sessions module). */
+    setCoreSessions(coreSessions) {
+        this._coreSessions = coreSessions;
+    }
+    /** 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);
+        if (!conversation || !this._coreSessions)
+            return Promise.resolve();
+        return this._coreSessions.close(conversation);
+    }
+    /** A turn is live while its provider child or its Core session turn is running. */
+    _isTurnLive(conversationId) {
+        return this._active.has(conversationId) || !!this._coreSessions?.handle(conversationId);
+    }
     async _awaitWhileLive(work) {
         if (this._disposed)
             return { disposed: true };
@@ -160,11 +183,11 @@ class AgentChatManager {
     }
     /** True while a turn is streaming for this conversation. */
     isStreaming(conversationId) {
-        return !this._disposed && this._active.has(conversationId);
+        return !this._disposed && this._isTurnLive(conversationId);
     }
     /** True while a turn is in flight (spawned or reserved). */
     isBusy(conversationId) {
-        return !this._disposed && (this._active.has(conversationId) || this._reserved.has(conversationId));
+        return !this._disposed && (this._isTurnLive(conversationId) || this._reserved.has(conversationId));
     }
     pendingMessages(conversationId) {
         return (this._queue.get(conversationId) ?? []).map((item) => ({
@@ -192,8 +215,62 @@ class AgentChatManager {
                 pendingMessages: this.pendingMessages(conversationId),
                 streamingText: this._streamingText.get(conversationId) ?? '',
             })),
+            // Core agent sessions with background work: the client restores the
+            // background indicator and live sub-agent rows from this after reconnecting.
+            sessions: (0, agent_session_store_1.listActiveSessionCursors)(this._db).map((cursor) => ({
+                conversationId: cursor.conversationId,
+                residentPhase: cursor.residentPhase,
+                processAlive: cursor.processAlive,
+                liveSubagents: cursor.liveSubagents,
+                subagents: (0, agent_session_store_1.listSubagents)(this._db, cursor.conversationId).filter((node) => node.phase === 'running'),
+            })),
         };
     }
+    /** 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)
+            return null;
+        return { residentPhase: cursor.residentPhase, processAlive: cursor.processAlive, liveSubagents: cursor.liveSubagents, 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) {
+        const conversation = (0, agent_store_1.getAgentConversation)(this._db, conversationId);
+        if (!conversation || !this._coreSessions)
+            return [];
+        return this._coreSessions.stopSubagents(conversation, subagentIds);
+    }
+    /** Delegated runtime: launch a sub-agent on the mission's configured provider. */
+    async delegateSubagent(conversationId, params) {
+        const conversation = (0, agent_store_1.getAgentConversation)(this._db, conversationId);
+        if (!conversation || !this._coreSessions)
+            throw new Error('This mission does not run in a Core session.');
+        return this._coreSessions.delegate(conversation, params);
+    }
+    /** Delegated runtime: wait for sub-agents (results are delivered to the agent once). */
+    async waitSubagents(conversationId, subagentIds, timeoutMs) {
+        const conversation = (0, agent_store_1.getAgentConversation)(this._db, conversationId);
+        if (!conversation || !this._coreSessions)
+            throw new Error('This mission does not run in a Core session.');
+        return this._coreSessions.waitSubagents(conversation, subagentIds, timeoutMs);
+    }
+    /** Plugin MCP servers for a project-pinned mission (empty for providers without plugin MCP entries). */
+    _pluginMcpServers(providerId, projectId) {
+        const project = projectId ? this._registry?.getProjectRow?.(projectId) : null;
+        if (!project)
+            return [];
+        const execution = (0, workspace_resolution_1.resolveProjectExecution)(project);
+        return (0, codex_spawn_1.resolveCodexPluginMcpServers)({ providerId, stateRoot: execution.cwd, repositoryPath: project.path, legacyProviderId: project.provider });
+    }
+    /** Rebuild a mission's session projection from Core's journal (operator repair). */
+    async rebuildSessionProjection(conversationId) {
+        const conversation = (0, agent_store_1.getAgentConversation)(this._db, conversationId);
+        if (!conversation || !this._coreSessions)
+            return null;
+        if (this._isTurnLive(conversationId))
+            throw new SessionRebuildBusyError('Wait for the current turn to finish before rebuilding');
+        return this._coreSessions.rebuildProjection(conversation);
+    }
     notifyConversationCreated(conversationId) {
         this._broadcast({ type: 'agent_conversation_created', conversationId, timestamp: new Date().toISOString() });
     }
@@ -478,25 +555,31 @@ class AgentChatManager {
                 const invocationId = (0, crypto_1.randomUUID)();
                 currentCapability = agentCapability;
                 currentInvocationId = invocationId;
-                let mcpArgs;
-                let mcpEnv;
-                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),
-                    });
-                    mcpArgs = wiring.extraArgs;
-                    mcpEnv = wiring.env;
-                    const project = conversation.pinned_project_id ? this._registry?.getProjectRow?.(conversation.pinned_project_id) : null;
-                    if (adapter.id === 'codex' && project) {
-                        const execution = (0, workspace_resolution_1.resolveProjectExecution)(project);
-                        mcpArgs.push(...(0, codex_spawn_1.buildCodexPluginArgs)({ providerId: adapter.id, stateRoot: execution.cwd, repositoryPath: project.path, legacyProviderId: project.provider }));
+                let mcpArgs = [];
+                let mcpEnv = {};
+                // 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) })
+                    : null;
+                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),
+                        });
+                        mcpArgs = wiring.extraArgs;
+                        mcpEnv = wiring.env;
+                        const project = conversation.pinned_project_id ? this._registry?.getProjectRow?.(conversation.pinned_project_id) : null;
+                        if (adapter.id === 'codex' && project) {
+                            const execution = (0, workspace_resolution_1.resolveProjectExecution)(project);
+                            mcpArgs.push(...(0, codex_spawn_1.buildCodexPluginArgs)({ providerId: adapter.id, stateRoot: execution.cwd, repositoryPath: project.path, legacyProviderId: project.provider }));
+                        }
+                    }
+                    catch (err) {
+                        throw new Error('Specrails could not prepare its MCP tools. The agent was not launched. Check the app installation and retry. ' + (err instanceof Error ? err.message : String(err)));
                     }
-                }
-                catch (err) {
-                    throw new Error('Specrails could not prepare its MCP tools. The agent was not launched. Check the app installation and retry. ' + (err instanceof Error ? err.message : String(err)));
-                }
                 const action = useResume ? 'chat-resume' : 'chat-turn';
                 const startedAt = new Date().toISOString();
                 let streamed = '';
@@ -505,7 +588,7 @@ 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=${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'}`);
                 const buildOpts = {
                     prompt: effectivePrompt(useResume),
                     systemPrompt: adapter.capabilities.systemPromptArg ? systemPrompt : undefined,
@@ -515,7 +598,7 @@ class AgentChatManager {
                     imagePaths: spawnImagePaths,
                     reasoning_effort: reasoningEffort,
                 };
-                const nativeRunner = (0, live_session_1.nativeLiveSessionRunner)(adapter);
+                const nativeRunner = coreContext ? (0, core_session_runner_1.createCoreSessionRunner)(coreContext) : (0, live_session_1.nativeLiveSessionRunner)(adapter);
                 let invocationLive = true;
                 let nativeSink;
                 let nativeDrain = Promise.resolve();
@@ -782,13 +865,13 @@ class AgentChatManager {
                                 // A killed child (abort / conversation DELETE) keeps flushing its
                                 // buffered stdout — suppress the broadcasts once it left _active
                                 // so stragglers can't resurrect client-side streaming state.
-                                if (this._active.has(conversationId)) {
+                                if (this._isTurnLive(conversationId)) {
                                     this._streamingText.set(conversationId, streamed.slice(segmentStart));
                                     this._broadcast({ type: 'agent_stream', conversationId, delta: ev.text, timestamp: timestamp() });
                                 }
                                 break;
                             case 'tool-use':
-                                if (this._active.has(conversationId)) {
+                                if (this._isTurnLive(conversationId)) {
                                     this._broadcast({
                                         type: 'agent_tool',
                                         conversationId,
@@ -802,7 +885,7 @@ class AgentChatManager {
                             case 'tool-result':
                                 // Feeds the activity-log modal's output column. Claude-only
                                 // today; other adapters never emit this kind.
-                                if (this._active.has(conversationId)) {
+                                if (this._isTurnLive(conversationId)) {
                                     this._broadcast({
                                         type: 'agent_tool_result',
                                         conversationId,
@@ -845,7 +928,10 @@ class AgentChatManager {
                     this._nativeInputNotifiers.delete(conversationId);
                     stopSteering();
                     this._steeringCapabilities.delete(conversationId);
-                    (0, agent_capability_1.revokeAgentCapability)(agentCapability);
+                    // A resident Core session keeps presenting this capability for its
+                    // background turns until the next turn rotates it or Core retires it.
+                    if (!this._coreSessions?.retains(conversationId, agentCapability))
+                        (0, agent_capability_1.revokeAgentCapability)(agentCapability);
                     (0, agent_mcp_config_1.removeAgentCapabilityFile)(conversationId, invocationId);
                     currentCapability = null;
                     currentInvocationId = undefined;
@@ -874,7 +960,8 @@ class AgentChatManager {
                 if (result.stderrTail && (result.spawnFailed || (result.code ?? 0) !== 0 || !text)) {
                     console.error(`[agent-chat] ${adapter.id} stderr:\n${result.stderrTail}`);
                 }
-                return { disposed: false, text, fullText: streamed.trim(), checkpointed, sessionId: capturedSessionId, error: capturedError, code: result.code, spawnFailed: result.spawnFailed, stderrTail: result.stderrTail, events: result.events, startedAt };
+                const coreResult = result;
+                return { disposed: false, text, fullText: streamed.trim(), checkpointed, sessionId: capturedSessionId, error: capturedError, code: result.code, spawnFailed: result.spawnFailed, stderrTail: result.stderrTail, events: result.events, startedAt, ...(coreResult.usage ? { usage: coreResult.usage } : {}), ...(coreResult.coreTurnId ? { coreTurnId: coreResult.coreTurnId } : {}), ...(coreResult.errorCode ? { errorCode: coreResult.errorCode } : {}) };
             };
             // Conversation CONFIG (provider/model/tier) is owned by the PATCH route —
             // never write turn-START snapshots back at settle, or a mid-turn provider
@@ -896,9 +983,9 @@ class AgentChatManager {
                 // Deliberate user Stop: keep any partial text (it was already streamed to
                 // the client), never auto-heal, never surface an error.
                 if (r.text && (0, agent_store_1.getAgentConversation)(this._db, conversationId)) {
-                    const message = (0, agent_store_1.addAgentMessage)(this._db, { conversationId, role: 'assistant', content: r.text });
+                    const message = (0, agent_store_1.addAgentMessage)(this._db, { conversationId, role: 'assistant', content: r.text, ...(r.coreTurnId ? { coreTurnId: r.coreTurnId, turnOrigin: 'user' } : {}) });
                     persistSession(r.sessionId);
-                    this._broadcast({ type: 'agent_done', conversationId, fullText: r.text, messageId: message.id, timestamp: timestamp() });
+                    this._broadcast({ type: 'agent_done', conversationId, fullText: r.text, messageId: message.id, ...(r.coreTurnId ? { coreTurnId: r.coreTurnId } : {}), timestamp: timestamp() });
                 }
             };
             // Cost accounting (HIGH-3): exactly one row per settled turn, whichever
@@ -964,14 +1051,15 @@ class AgentChatManager {
                     const message = (0, agent_store_1.addAgentMessage)(this._db, { conversationId, role: 'assistant', content: r.text });
                     this._broadcast({ type: 'agent_partial', conversationId, fullText: r.text, messageId: message.id, error: reason, timestamp: timestamp() });
                 }
-                this._emitError(conversationId, reason);
+                this._emitError(conversationId, reason, r.errorCode ? { code: r.errorCode, provider: adapter.id } : undefined);
                 record(r, 'failed');
                 return;
             }
             if (r.text || r.checkpointed) {
-                const message = r.text ? (0, agent_store_1.addAgentMessage)(this._db, { conversationId, role: 'assistant', content: r.text }) : undefined;
+                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);
-                this._broadcast({ type: 'agent_done', conversationId, fullText: r.text, ...(message ? { messageId: message.id } : {}), timestamp: timestamp() });
+                // The Core turn id anchors this turn's sub-agents under the reply in every client.
+                this._broadcast({ type: 'agent_done', conversationId, fullText: r.text, ...(message ? { messageId: message.id } : {}), ...(r.coreTurnId ? { coreTurnId: r.coreTurnId } : {}), timestamp: timestamp() });
                 record(r, 'success');
                 // AI title after the FIRST completed turn (industry standard — ChatGPT /
                 // Claude.ai), on the conversation's own provider. The deterministic title
@@ -989,7 +1077,7 @@ class AgentChatManager {
         }
         finally {
             this._steeringCapabilities.delete(conversationId);
-            if (currentCapability)
+            if (currentCapability && !this._coreSessions?.retains(conversationId, currentCapability))
                 (0, agent_capability_1.revokeAgentCapability)(currentCapability);
             if (currentInvocationId)
                 (0, agent_mcp_config_1.removeAgentCapabilityFile)(conversationId, currentInvocationId);
@@ -1009,10 +1097,11 @@ class AgentChatManager {
             return;
         try {
             const finishedAt = new Date().toISOString();
-            const { result, estimated } = (0, result_event_1.finaliseInvocationResult)(adapter, outcome.events, {
-                fallbackModel: model,
-                durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(outcome.startedAt)),
-            });
+            const finaliseOptions = { fallbackModel: model, durationMs: Math.max(0, Date.parse(finishedAt) - Date.parse(outcome.startedAt)) };
+            // Core sessions report a normalized per-turn delta; never reparse provider frames for them.
+            const { result, estimated } = outcome.usage
+                ? (0, result_event_1.finaliseNormalisedResult)(adapter, outcome.usage, finaliseOptions)
+                : (0, result_event_1.finaliseInvocationResult)(adapter, outcome.events, finaliseOptions);
             (0, desktop_db_1.recordAgentInvocation)(this._db, {
                 id: (0, crypto_1.randomUUID)(),
                 conversation_id: conversation.id,
@@ -1437,6 +1526,12 @@ class AgentChatManager {
             (0, agent_capability_1.revokeAgentCapability)(capability);
         this._steeringCapabilities.delete(conversationId);
         this._nativeInputNotifiers.delete(conversationId);
+        const coreTurn = this._coreSessions?.handle(conversationId);
+        if (coreTurn) {
+            // Stop the turn inside the resident session; never kill a process by PID.
+            void coreTurn.interrupt();
+            return true;
+        }
         const child = this._active.get(conversationId);
         if (!child)
             return false;
@@ -1478,6 +1573,7 @@ class AgentChatManager {
             this._closeChildIo(child);
         }
         this._active.clear();
+        this._coreSessions?.shutdown();
         for (const child of this._auxProcesses) {
             const reader = this._auxReaders.get(child);
             try {
@@ -1490,10 +1586,11 @@ class AgentChatManager {
         this._auxReaders.clear();
         this._auxProcesses.clear();
     }
-    _emitError(conversationId, error) {
+    /** `detail.code` lets clients explain known failures (e.g. `policy_unenforceable`) in the user's language. */
+    _emitError(conversationId, error, detail) {
         if (this._disposed)
             return;
-        this._broadcast({ type: 'agent_error', conversationId, error, timestamp: new Date().toISOString() });
+        this._broadcast({ type: 'agent_error', conversationId, error, ...(detail ?? {}), timestamp: new Date().toISOString() });
     }
 }
 exports.AgentChatManager = AgentChatManager;

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

@@ -6,8 +6,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.isAgentChatEnabled = isAgentChatEnabled;
 exports.createAgentChatRouter = createAgentChatRouter;
 const fs_1 = __importDefault(require("fs"));
+const agent_session_store_1 = require("./agent-session-store");
 const multer_1 = __importDefault(require("multer"));
 const express_1 = require("express");
+const agent_chat_manager_1 = require("./agent-chat-manager");
 const providers_1 = require("../../../providers");
 const provider_selection_1 = require("../../../provider-selection");
 const agent_tier_1 = require("./agent-tier");
@@ -213,8 +215,72 @@ function createAgentChatRouter(deps) {
             messages: (0, agent_input_store_1.decorateAgentInputMessages)(desktopDb, (0, agent_store_1.listAgentMessages)(desktopDb, conversation.id)),
             pendingMessages: manager.pendingMessages(conversation.id),
             live: manager.conversationLive(conversation.id),
+            session: manager.sessionState(conversation.id),
         });
     });
+    // ── Sub-agents of a mission's Core agent session (core-agent-sessions-host) ──
+    router.get('/conversations/:id/subagents', (req, res) => {
+        const conversation = (0, agent_store_1.getAgentConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'Unknown conversation' });
+            return;
+        }
+        res.json({ subagents: (0, agent_session_store_1.listSubagents)(desktopDb, conversation.id), session: manager.sessionState(conversation.id) });
+    });
+    router.get('/conversations/:id/subagents/:subagentId/events', (req, res) => {
+        const conversation = (0, agent_store_1.getAgentConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'Unknown conversation' });
+            return;
+        }
+        const after = Number.parseInt(String(req.query.after ?? '0'), 10);
+        const limit = Number.parseInt(String(req.query.limit ?? '200'), 10);
+        if (!Number.isSafeInteger(after) || after < 0 || !Number.isSafeInteger(limit) || limit < 1 || limit > 1000) {
+            res.status(400).json({ error: 'after must be ≥ 0 and limit between 1 and 1000' });
+            return;
+        }
+        res.json((0, agent_session_store_1.pageSubagentEvents)(desktopDb, conversation.id, String(req.params.subagentId), after, limit));
+    });
+    router.post('/conversations/:id/subagents/stop', async (req, res) => {
+        const conversation = (0, agent_store_1.getAgentConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'Unknown conversation' });
+            return;
+        }
+        const ids = req.body?.subagentIds;
+        if (ids !== undefined && (!Array.isArray(ids) || ids.length > 500 || !ids.every((id) => typeof id === 'string' && id.length > 0 && id.length <= 200))) {
+            res.status(400).json({ error: 'subagentIds must be an array of ids' });
+            return;
+        }
+        try {
+            res.json({ stopped: await manager.stopSubagents(conversation.id, ids) });
+        }
+        catch (err) {
+            res.status(502).json({ error: err instanceof Error ? err.message : 'Could not stop the sub-agents' });
+        }
+    });
+    router.post('/conversations/:id/session/rebuild', async (req, res) => {
+        const conversation = (0, agent_store_1.getAgentConversation)(desktopDb, String(req.params.id));
+        if (!conversation) {
+            res.status(404).json({ error: 'Unknown conversation' });
+            return;
+        }
+        try {
+            const result = await manager.rebuildSessionProjection(conversation.id);
+            if (!result) {
+                res.status(409).json({ error: 'This mission does not run in a Core session' });
+                return;
+            }
+            res.json(result);
+        }
+        catch (err) {
+            if (err instanceof agent_chat_manager_1.SessionRebuildBusyError) {
+                res.status(409).json({ error: err.message });
+                return;
+            }
+            res.status(502).json({ error: err instanceof Error ? err.message : 'Could not rebuild the session projection' });
+        }
+    });
     router.patch('/conversations/:id', (req, res) => {
         const conversation = (0, agent_store_1.getAgentConversation)(desktopDb, String(req.params.id));
         if (!conversation) {
@@ -289,6 +355,8 @@ function createAgentChatRouter(deps) {
     router.delete('/conversations/:id', (req, res) => {
         const id = String(req.params.id);
         manager.abort(id);
+        // Must run before the row is deleted: it reads the conversation's scope.
+        void manager.closeCoreSession(id).catch((e) => console.error('[agent-chat] Core session close failed:', e));
         (0, transient_children_1.killBackgroundProcessesForChat)(id);
         (0, transient_children_1.purgeBackgroundProcessHistory)({ chatId: id });
         (0, agent_store_1.deleteAgentConversation)(desktopDb, id);

package/server/dist/modules/missions/runtime/agent-operator-prompt.js

@@ -546,13 +546,12 @@ the user's language.
 a description following the template, at least one acceptance criterion, and
 you have no outstanding question. Then — and only then — emit the complete
 final \`spec-draft\` block one last time, state the one-line short summary you
-will attach, and ask exactly one question: whether to create it. Say what
-creation does: one normal write for the spec itself, plus by default one
-short background AI pass that appends a Contract Layer (exact identifiers,
-data shapes, invariants for the implementing agents) — small cost, seconds.
-If the user declines the enrichment ("no contract layer"), you will pass
-\`contractRefine: false\`. Do not call any persisting tool until the user
-answers yes to that render. If they edit, update and re-render.
+will attach, and ask exactly one question: whether to create it. The
+Contract Layer is always added: never ask about it, never offer to skip it and
+never present it as an option (the user does not want that question). Pass
+\`contractRefine: false\` only when the user asked for no contract layer on
+their own initiative. Do not call any persisting tool until the user answers
+yes to that render. If they edit, update and re-render.
 
 **Pausing.** There is no draft-ticket path for you (\`save_draft\` needs a real
 app Explore conversation). If the user pauses, summarize the full draft state
@@ -569,8 +568,8 @@ summary later.
   author — the same post-persist enrichment the app's Add Spec runs. After the
   spec lands, one short background AI pass appends a \`## Contract Layer\`
   section (naming contract, data shapes, state machine, invariants, file touch
-  list). Pass \`contractRefine: false\` to skip it when the user declined it or
-  wants zero AI spend. It requires a structured-action provider (currently
+  list). Never ask whether to add it. Pass \`contractRefine: false\` only when
+  the user asked, unprompted, for no contract layer or zero AI spend. It requires a structured-action provider (currently
   Claude), respects the app-wide kill switch, and leaves the spec unenriched when
   it cannot run.
 - The enrichment is asynchronous: the commit returns immediately and the