specrails-desktop 2.61.0 → 2.63.0

package/server/dist/mcp/tools/app-settings.js

@@ -23,6 +23,7 @@ function appTools() {
             description: 'Read or update app-level Specrails settings (theme, language, daily budget, cost-alert threshold, Code Explorer summary language + monthly summary budget). ' +
                 'Actions: get, set, runtime_providers.list (connections + live status), runtime_providers.test (probe an OpenAI-compatible baseUrl without saving), runtime_providers.save (replace the connections list — local AI engines re-register live). ' +
                 'The MCP enable flag and permission tiers are read-only here (user-controlled in the app). ' +
+                '"Allow sub-agents" and "Run sub-agents with" are also read-only here (an agent must not grant itself sub-agents): get reports allowSubagentsWithoutProject and subagentRuntimeWithoutProject, and with projectId the project settings (null runtime = same as the mission agent). ' +
                 'dailyBudgetUsd here is APP-WIDE (all projects combined); per-project caps live in specrails_analytics(budget_set).',
             hintTier: 'read',
             tier: (args) => (args.action === 'set' || args.action === 'runtime_providers.save' ? 'write' : 'read'),
@@ -43,6 +44,7 @@ function appTools() {
                     .optional()
                     .describe('APP-WIDE daily budget cap USD across all projects; null clears it. Per-project caps live in specrails_analytics(budget_set).'),
                 costAlertThresholdUsd: zod_1.z.number().min(0).nullable().optional(),
+                projectId: zod_1.z.string().optional().describe('get: also report this project\'s "Allow sub-agents" setting'),
                 summaryLanguage: zod_1.z
                     .enum(['en', 'es'])
                     .optional()
@@ -83,6 +85,11 @@ function appTools() {
                         // Code Explorer settings (same keys + defaults as GET /api/code-explorer-settings)
                         summaryLanguage: (0, desktop_db_1.getDesktopSetting)(db, 'summary_language') === 'es' ? 'es' : 'en',
                         summaryMonthlyBudgetUsd: nonNegNum((0, desktop_db_1.getDesktopSetting)(db, 'summary_monthly_budget_usd')) ?? 5.0,
+                        allowSubagentsWithoutProject: (0, desktop_db_1.getGlobalAllowSubagents)(db),
+                        subagentRuntimeWithoutProject: (0, desktop_db_1.getGlobalSubagentRuntime)(db),
+                        ...(typeof args.projectId === 'string' && args.projectId
+                            ? await projectSubagentSettings(ctx, args.projectId)
+                            : {}),
                         mcp: {
                             enabled: (0, mcp_tiers_1.isMcpEnabled)(db),
                             tierWrite: (0, mcp_tiers_1.isTierEnabled)(db, 'write'),
@@ -161,3 +168,7 @@ function writeNumOrClear(db, key, value) {
     else
         (0, desktop_db_1.setDesktopSetting)(db, key, String(value));
 }
+async function projectSubagentSettings(ctx, projectId) {
+    const settings = (await (0, types_1.apiCall)(ctx, 'GET', `/projects/${encodeURIComponent(projectId)}/settings`));
+    return { projectAllowSubagents: settings.allowSubagents === true, projectSubagentRuntime: settings.subagentRuntime ?? null };
+}

package/server/dist/mcp/tools/env.js

@@ -15,6 +15,26 @@ function uniq(names) {
     }
     return out;
 }
+/** Names and states only: rebuild each record field by field so nothing but
+ *  the documented, value-free fields can ever reach an MCP client. */
+function sanitizeStatus(raw) {
+    const report = (raw && typeof raw === 'object' ? raw : {});
+    const names = Array.isArray(report.names) ? report.names : [];
+    return {
+        checking: report.checking === true,
+        loginShellRecovery: report.loginShellRecovery !== false,
+        timeoutMs: typeof report.timeoutMs === 'number' ? report.timeoutMs : null,
+        statuses: names
+            .filter((entry) => typeof entry?.name === 'string' && typeof entry?.status === 'string')
+            .map((entry) => ({
+            name: entry.name,
+            status: entry.status,
+            shell: typeof entry.shell === 'string' ? entry.shell : null,
+            checkedAt: typeof entry.checkedAt === 'string' ? entry.checkedAt : null,
+            exitCode: typeof entry.exitCode === 'number' ? entry.exitCode : null,
+        })),
+    };
+}
 function envTools() {
     return [
         {
@@ -22,11 +42,12 @@ function envTools() {
             title: 'Project worktree environment',
             description: 'Read, scan, and configure the per-project environment variable NAME allowlist used for rail jobs and isolated loop worktrees. ' +
                 'Values are never read or stored by this tool; runs read them from the server environment and can recover configured names from the login shell when the desktop process is missing them. scan inspects safe repo config files such as package.json, .npmrc, .yarnrc.yml and pnpm-workspace.yaml for ${VAR} / process.env.VAR references and private scoped package auth hints. ' +
-                'Actions: get (read current names), scan (discover candidates), set (write names), auto_configure (scan then merge discovered names into settings).',
+                'Each configured name reports a value-free resolution status: inherited, recovered (from the login shell), not-defined, probe-timeout or probe-failed. ' +
+                'Actions: get (read current names and their statuses), status (statuses only), recheck (probe the login shell now, then return statuses), scan (discover candidates), set (write names), auto_configure (scan then merge discovered names into settings).',
             hintTier: 'read',
             tier: (args) => (args.action === 'set' || args.action === 'auto_configure' ? 'write' : 'read'),
             inputSchema: {
-                action: zod_1.z.enum(['get', 'scan', 'set', 'auto_configure']).describe('Operation'),
+                action: zod_1.z.enum(['get', 'status', 'recheck', 'scan', 'set', 'auto_configure']).describe('Operation'),
                 projectId: zod_1.z.string().optional().describe('Project id (defaults to the active project)'),
                 names: zod_1.z.array(zod_1.z.string()).optional().describe('set: env var names to configure'),
                 merge: zod_1.z.boolean().optional().describe('set: merge with existing names instead of replacing them (default true)'),
@@ -36,7 +57,21 @@ function envTools() {
                 const base = (0, types_1.projectPath)(ctx, args.projectId);
                 if (action === 'get') {
                     const settings = await (0, types_1.apiCall)(ctx, 'GET', `${base}/settings`);
-                    return { names: Array.isArray(settings.worktreeEnvPassthrough) ? settings.worktreeEnvPassthrough : [] };
+                    const names = Array.isArray(settings.worktreeEnvPassthrough) ? settings.worktreeEnvPassthrough : [];
+                    // Statuses are best-effort: an older server without the route still answers names.
+                    try {
+                        const { statuses } = sanitizeStatus(await (0, types_1.apiCall)(ctx, 'GET', `${base}/env-passthrough/status`));
+                        return { names, statuses };
+                    }
+                    catch {
+                        return { names };
+                    }
+                }
+                if (action === 'status') {
+                    return sanitizeStatus(await (0, types_1.apiCall)(ctx, 'GET', `${base}/env-passthrough/status`));
+                }
+                if (action === 'recheck') {
+                    return sanitizeStatus(await (0, types_1.apiCall)(ctx, 'POST', `${base}/env-passthrough/recheck`));
                 }
                 if (action === 'scan') {
                     const project = (0, types_1.requireProject)(ctx, args.projectId).project;

package/server/dist/mcp/tools/mission.js

@@ -2,18 +2,30 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.missionTools = missionTools;
 const zod_1 = require("zod");
+const agent_chat_registry_1 = require("../../modules/missions/runtime/agent-chat-registry");
 function missionTools() {
     return [{
             name: 'specrails_mission',
             title: 'Mission user updates',
-            description: 'First-party mission only: acknowledge authenticated user updates received during the current running turn. For MCP mission_user_updates, read every block, replan, and acknowledge_updates with the exact latest revision in a separate call before invoking other tools. For the initial Mission input ID or native user messages carrying queueId, acknowledge_inputs with those inputIds only after reading them; this records a read receipt and does not release the MCP revision gate. Does not execute, retry or undo any action and cannot change permissions, provider or project pin.',
+            description: 'First-party mission only: acknowledge authenticated user updates received during the current running turn. For MCP mission_user_updates, read every block, replan, and acknowledge_updates with the exact latest revision in a separate call before invoking other tools. For the initial Mission input ID or native user messages carrying queueId, acknowledge_inputs with those inputIds only after reading them; this records a read receipt and does not release the MCP revision gate. Does not execute, retry or undo any action and cannot change permissions, provider or project pin. ' +
+                'When the mission says Specrails launches its sub-agents: subagent_start (description, instructions, optional contextTurns) delegates a task to a sub-agent on the configured provider; subagent_wait returns finished results (results you never wait for arrive later as a message); subagent_list shows them; subagent_stop stops them. These actions are refused in missions whose agent launches its own sub-agents.',
+            // Delegation is gated by the project's "Allow sub-agents" / "Run sub-agents with" settings, like native sub-agents.
             tier: 'read',
             inputSchema: {
-                action: zod_1.z.enum(['acknowledge_updates', 'acknowledge_inputs']),
+                action: zod_1.z.enum(['acknowledge_updates', 'acknowledge_inputs', 'subagent_start', 'subagent_wait', 'subagent_list', 'subagent_stop']),
+                description: zod_1.z.string().min(1).max(200).optional().describe('subagent_start: a short name for the task, shown to the user'),
+                instructions: zod_1.z.string().min(1).max(64 * 1024).optional().describe('subagent_start: the complete, self-contained task for the sub-agent'),
+                agentType: zod_1.z.string().min(1).max(100).optional().describe('subagent_start: optional label for the kind of work (e.g. "review")'),
+                contextTurns: zod_1.z.number().int().min(0).max(10).optional().describe('subagent_start: how many recent turns of this conversation to hand over'),
+                subagentIds: zod_1.z.array(zod_1.z.string().min(1).max(200)).max(50).optional().describe('subagent_wait / subagent_stop: limit to these sub-agents (default: all of this mission)'),
+                timeoutSeconds: zod_1.z.number().int().min(0).max(300).optional().describe('subagent_wait: how long to wait (default 60, max 300); call again to keep waiting'),
                 revision: zod_1.z.number().int().positive().max(Number.MAX_SAFE_INTEGER).optional().describe('Required for acknowledge_updates: exact latest revision delivered in mission_user_updates. Never guess; an older acknowledgement cannot release newer messages.'),
                 inputIds: zod_1.z.array(zod_1.z.string().min(1).max(200)).min(1).max(50).optional().describe('Required for acknowledge_inputs: exact initial Mission input ID or queueId values from native user messages you have read in this invocation.'),
             },
             handler: (ctx, args) => {
+                // Delegation actions are async; the acknowledge actions stay synchronous (callers rely on sync throws).
+                if (typeof args.action === 'string' && args.action.startsWith('subagent_'))
+                    return delegationAction(ctx, args);
                 if (args.action === 'acknowledge_inputs') {
                     if (!ctx.firstPartyAgent || !ctx.acknowledgeAgentInputsRead)
                         throw new Error('This action requires an active first-party mission turn.');
@@ -27,3 +39,34 @@ function missionTools() {
             },
         }];
 }
+async function delegationAction(ctx, args) {
+    if (!ctx.firstPartyAgent || !ctx.originConversationId)
+        throw new Error('This action requires an active first-party mission turn.');
+    const manager = (0, agent_chat_registry_1.getAgentChatManager)();
+    if (!manager)
+        throw new Error('Missions are not available.');
+    const conversationId = ctx.originConversationId;
+    const ids = Array.isArray(args.subagentIds) ? args.subagentIds : undefined;
+    switch (args.action) {
+        case 'subagent_start': {
+            if (typeof args.description !== 'string' || typeof args.instructions !== 'string')
+                throw new Error('subagent_start needs a description and instructions.');
+            return manager.delegateSubagent(conversationId, {
+                description: args.description, prompt: args.instructions,
+                ...(typeof args.agentType === 'string' ? { agentType: args.agentType } : {}),
+                ...(typeof args.contextTurns === 'number' ? { contextTurns: args.contextTurns } : {}),
+            });
+        }
+        case 'subagent_wait':
+            return manager.waitSubagents(conversationId, ids, (typeof args.timeoutSeconds === 'number' ? args.timeoutSeconds : 60) * 1000);
+        case 'subagent_stop':
+            return { stopped: await manager.stopSubagents(conversationId, ids) };
+        case 'subagent_list':
+            return {
+                subagents: (manager.sessionState(conversationId)?.subagents ?? [])
+                    .filter((node) => node.delegated)
+                    .map((node) => ({ subagentId: node.subagentId, description: node.description, phase: node.phase, provider: node.delegated.driver, model: node.delegated.model, result: node.resultSummary })),
+            };
+    }
+    throw new Error(`Unknown action: ${String(args.action)}`);
+}

package/server/dist/mcp/tools/specs.js

@@ -57,7 +57,7 @@ function specsTools() {
                 'assignee, prerequisites, metadata. THE canonical way to persist a spec refined in conversation — do NOT route ' +
                 'a finished spec through create/generate, which re-generate the content with AI and lossily rewrite it. ' +
                 'Agent-authored inserts (use b) are enriched with a Contract Layer BY DEFAULT via one short background AI pass ' +
-                '— pass contractRefine: false to skip it, e.g. when the user declined it), ' +
+                '— never ask the user about it; pass contractRefine: false only when they asked for no contract layer unprompted), ' +
                 'generate (same as create but takes a pre-formed idea string; both accept contextScope/attachments/createLocal), ' +
                 'ai_edit (ai-spawn, AI-edit a ticket title+description), ' +
                 'cancel_ai_edit (abort an in-flight ai-edit), contract_refine (ai-spawn, append/re-fire a Contract Layer — Claude or Codex; ' +
@@ -172,7 +172,7 @@ function specsTools() {
                 contractRefine: zod_1.z
                     .boolean()
                     .optional()
-                    .describe('create/generate/commit_draft: enrich the spec with a Contract Layer post-persist (Claude or Codex). DEFAULTS TO TRUE — pass false to opt out (e.g. the user asked for no contract layer)'),
+                    .describe('create/generate/commit_draft: enrich the spec with a Contract Layer post-persist (Claude or Codex). DEFAULTS TO TRUE and is never asked about — pass false only when the user asked for no contract layer unprompted'),
                 attachmentIds: zod_1.z.array(zod_1.z.string()).optional().describe('create/generate/ai_edit: attachment ids (create/generate require pendingSpecId)'),
                 // ── ai_edit ──────────────────────────────────────────────────────
                 instructions: zod_1.z.string().optional().describe('ai_edit: natural-language editing instructions (required)'),

package/server/dist/modules/accounting/runtime/result-event.js

@@ -21,6 +21,7 @@
 // Spec: openspec/changes/add-multi-provider-support/specs/project-spending/spec.md
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.finaliseInvocationResult = finaliseInvocationResult;
+exports.finaliseNormalisedResult = finaliseNormalisedResult;
 exports.normaliseResultEvent = normaliseResultEvent;
 const pricing_1 = require("./pricing");
 const local_adapter_1 = require("../../../providers/local-adapter");
@@ -30,7 +31,14 @@ const local_adapter_1 = require("../../../providers/local-adapter");
  * pricing-table fallback when the adapter does not report `total_cost_usd`.
  */
 function finaliseInvocationResult(adapter, events, opts = {}) {
-    const result = adapter.extractResult(events);
+    return finaliseNormalisedResult(adapter, adapter.extractResult(events), opts);
+}
+/**
+ * Same finalisation for a result that is already normalised (e.g. a turn
+ * reported by Core's session runtime): model/duration stamping and the
+ * native-cost-absent estimation rules, with identical null semantics.
+ */
+function finaliseNormalisedResult(adapter, result, opts = {}) {
     const cloned = { ...result };
     // Stamp the model from the caller when the adapter did not derive one. The
     // adapter contract permits leaving `model` undefined; the manager knows the

package/server/dist/modules/agent-runtime/runtime/agent-runtime-controls.js

@@ -373,9 +373,34 @@ class AgentRuntimeControls {
             this.statusCache.delete(runId);
         }
     }
+    /** The error a run logged when it failed before any Core step ran; null otherwise. */
+    launchFailure(runId) {
+        const run = this.ctx.db.prepare('SELECT final_outcome, iteration_count, core_revision FROM loop_runs WHERE id = ?').get(runId);
+        if (!run || run.final_outcome !== 'failed' || run.iteration_count || run.core_revision != null)
+            return null;
+        const rows = this.ctx.db.prepare("SELECT payload FROM events WHERE job_id = ? AND event_type = 'log' ORDER BY seq DESC LIMIT 20").all(runId);
+        for (const row of rows) {
+            try {
+                const line = JSON.parse(row.payload).line;
+                if (typeof line === 'string' && /^error:/i.test(line.trim()))
+                    return line.trim().replace(/^error:\s*/i, '').slice(0, 2000);
+            }
+            catch { /* not a log line */ }
+        }
+        return null;
+    }
     /** Read-only recovery assessment. canResume is admission, not a repair claim. */
     async diagnose(runId) {
         const summary = await this.summary(runId);
+        // Rejected before Core started (e.g. an unsupported model/effort): no runtime
+        // scope was ever written, so the launch error is the whole diagnosis.
+        const launchError = summary.status === 'unavailable' ? this.launchFailure(runId) : null;
+        if (launchError)
+            return {
+                runId, summary: { ...summary, error: launchError }, recommendation: 'fix_launch_precondition',
+                reason: 'The run was rejected before Core started, so there is no runtime state or evidence. Fix the reported precondition (or change the launch settings) before launching again; Resume is not possible.',
+                launchError, repeatFailureCount: null, recentFailures: [],
+            };
         if (summary.historical || summary.status === 'unavailable')
             return {
                 runId, summary, recommendation: 'inspect_saved_evidence',

package/server/dist/modules/agent-sessions/adapters/host-process.js

@@ -0,0 +1,73 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CoreHostLauncher = void 0;
+const node_child_process_1 = require("node:child_process");
+const agent_runtime_loader_1 = require("../../agent-runtime/runtime/agent-runtime-loader");
+const core_node_runtime_1 = require("../../../core-node-runtime");
+const win_spawn_1 = require("../../../util/win-spawn");
+const errors_1 = require("../domain/errors");
+const protocol_1 = require("../domain/protocol");
+const rpc_client_1 = require("./rpc-client");
+/**
+ * Launches `node <core>/cli.js host --stdio --scope <scope>` through the same
+ * Core and Node resolution as implementation runs (bundled Node under pkg,
+ * Windows-safe environment), then performs the protocol handshake.
+ */
+class CoreHostLauncher {
+    options;
+    constructor(options = {}) {
+        this.options = options;
+    }
+    async launch(scope) {
+        const cli = (this.options.cli ?? agent_runtime_loader_1.findCoreAgentRuntimeCli)();
+        if (!cli)
+            throw new errors_1.SessionRequestError('The selected Core runtime does not include the agent runtime CLI', { code: 'driver_unavailable', retryable: false });
+        const env = (0, win_spawn_1.windowsSpawnEnv)(this.options.env ?? process.env);
+        const args = [cli, 'host', '--stdio', '--scope', scope];
+        const command = (this.options.node ?? core_node_runtime_1.resolveCoreNodeRuntime)();
+        const child = (this.options.spawnProcess ?? ((cmd, argv, opts) => (0, node_child_process_1.spawn)(cmd, argv, { env: opts.env, shell: false, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] })))(command, args, { env });
+        if (!child.stdin || !child.stdout)
+            throw new errors_1.SessionRequestError('Session host has no stdio pipes', { code: 'internal', retryable: true });
+        let stderr = '';
+        child.stderr?.on('data', (chunk) => {
+            const text = chunk.toString('utf8');
+            stderr = (stderr + text).slice(-8_192);
+            this.options.onStderr?.(scope, text);
+        });
+        const exited = new Promise((resolve) => {
+            child.once('exit', (code) => resolve(code));
+            child.once('error', () => resolve(null));
+        });
+        const grace = this.options.shutdownGraceMs ?? 10_000;
+        const client = new rpc_client_1.StdioSessionHostClient({ stdin: child.stdin, stdout: child.stdout }, {
+            ...(this.options.requestTimeoutMs !== undefined ? { timeoutMs: this.options.requestTimeoutMs } : {}),
+            onClose: async () => {
+                // Ask for a graceful stop (interruptions recorded, lease released), then make sure the tree is gone.
+                await Promise.race([client.request('host.shutdown', { graceMs: grace }).catch(() => undefined), exited]);
+                const forced = setTimeout(() => { if (child.pid)
+                    (0, win_spawn_1.treeKillSafe)(child.pid, 'SIGKILL'); }, grace);
+                await exited;
+                clearTimeout(forced);
+            },
+        });
+        void exited.then((code) => client.markClosed(`Session host exited (code ${code ?? 'none'})${stderr ? `: ${stderr.trim().split('\n').at(-1)}` : ''}`));
+        let initialize;
+        try {
+            initialize = await client.request('initialize', {
+                protocolVersions: [...protocol_1.SUPPORTED_PROTOCOL_VERSIONS],
+                host: this.options.host ?? { name: 'specrails-desktop', version: 'dev' },
+                scope,
+            });
+            if (initialize.capabilities?.sessions !== 1)
+                throw new errors_1.SessionRequestError('Core session host does not advertise sessions', { code: 'protocol_mismatch', retryable: false });
+        }
+        catch (error) {
+            if (child.pid)
+                (0, win_spawn_1.treeKillSafe)(child.pid, 'SIGKILL');
+            client.markClosed('Session host failed to initialize');
+            throw error;
+        }
+        return Object.assign(client, { initialize, pid: child.pid });
+    }
+}
+exports.CoreHostLauncher = CoreHostLauncher;

package/server/dist/modules/agent-sessions/adapters/http.js

@@ -0,0 +1,31 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createSessionHostsRouter = createSessionHostsRouter;
+const express_1 = require("express");
+const SCOPE_RE = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+/**
+ * Inbound adapter: Core session host status per scope and manual retry of a
+ * degraded scope (after the cause, e.g. another Desktop instance, is gone).
+ */
+function createSessionHostsRouter(control) {
+    const router = (0, express_1.Router)();
+    router.get('/', (_req, res) => {
+        res.json({ hosts: control.hosts() });
+    });
+    router.post('/:scope/retry', async (req, res) => {
+        const scope = String(req.params.scope);
+        if (!SCOPE_RE.test(scope)) {
+            res.status(400).json({ error: 'Invalid scope' });
+            return;
+        }
+        try {
+            await control.retry(scope);
+            res.json({ host: control.hosts().find((host) => host.scope === scope) ?? { scope, status: 'absent', detail: null, code: null } });
+        }
+        catch (error) {
+            // The retry ran; the scope reports why it is still unavailable.
+            res.status(502).json({ error: error instanceof Error ? error.message : 'Retry failed', host: control.hosts().find((host) => host.scope === scope) ?? null });
+        }
+    });
+    return router;
+}

package/server/dist/modules/agent-sessions/adapters/rpc-client.js

@@ -0,0 +1,147 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.StdioSessionHostClient = exports.MAX_RESPONSE_BYTES = void 0;
+const node_string_decoder_1 = require("node:string_decoder");
+const errors_1 = require("../domain/errors");
+/** Longest accepted response line from the host. */
+exports.MAX_RESPONSE_BYTES = 16 * 1024 * 1024;
+/**
+ * JSON-RPC 2.0 client for the Core session host over NDJSON stdio.
+ * Requests time out; every pending request is rejected when the connection
+ * ends; notifications fan out to subscribers (session.event, session.lagged,
+ * host.leaseLost).
+ */
+class StdioSessionHostClient {
+    transport;
+    options;
+    nextId = 1;
+    pending = new Map();
+    eventListeners = new Set();
+    lagListeners = new Set();
+    closeListeners = new Set();
+    closedReason = null;
+    closedCode = null;
+    constructor(transport, options = {}) {
+        this.transport = transport;
+        this.options = options;
+        const decoder = new node_string_decoder_1.StringDecoder('utf8');
+        let buffer = '';
+        transport.stdout.on('data', (chunk) => {
+            buffer += typeof chunk === 'string' ? chunk : decoder.write(chunk);
+            for (;;) {
+                const newline = buffer.indexOf('\n');
+                if (newline < 0)
+                    break;
+                const line = buffer.slice(0, newline).trim();
+                buffer = buffer.slice(newline + 1);
+                if (line)
+                    this.receive(line);
+            }
+            if (Buffer.byteLength(buffer) > exports.MAX_RESPONSE_BYTES)
+                this.markClosed('Session host sent an oversized frame');
+        });
+        transport.stdout.on('end', () => this.markClosed('Session host closed its output'));
+        transport.stdin.on('error', () => this.markClosed('Session host input closed'));
+    }
+    get closed() {
+        return this.closedReason !== null;
+    }
+    request(method, params = {}) {
+        if (this.closedReason)
+            return Promise.reject(new errors_1.SessionRequestError(this.closedReason, this.closedCode ? { code: this.closedCode, retryable: false } : { code: 'host_unavailable', retryable: true }));
+        const id = this.nextId++;
+        return new Promise((resolve, reject) => {
+            const timer = setTimeout(() => {
+                this.pending.delete(id);
+                reject(new errors_1.SessionRequestError(`Session host did not answer ${method} in time`, { code: 'host_timeout', retryable: true }));
+            }, this.options.timeoutMs ?? 60_000);
+            timer.unref?.();
+            this.pending.set(id, { method, resolve: resolve, reject, timer });
+            this.transport.stdin.write(`${JSON.stringify({ jsonrpc: '2.0', id, method, params })}\n`);
+        });
+    }
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+        return () => { this.eventListeners.delete(listener); };
+    }
+    onLagged(listener) {
+        this.lagListeners.add(listener);
+        return () => { this.lagListeners.delete(listener); };
+    }
+    onClose(listener) {
+        if (this.closedReason) {
+            listener(this.closedReason, this.closedCode ?? undefined);
+            return () => { };
+        }
+        this.closeListeners.add(listener);
+        return () => { this.closeListeners.delete(listener); };
+    }
+    async close() {
+        if (this.closedReason)
+            return;
+        await this.options.onClose?.();
+        this.markClosed('Session host closed');
+    }
+    /** The process ended (called by the launcher). A known `code` (e.g. `journal_locked`) travels to pending requests and close listeners. */
+    markClosed(reason, code) {
+        if (this.closedReason)
+            return;
+        this.closedReason = reason;
+        this.closedCode = code ?? null;
+        for (const [id, request] of this.pending) {
+            clearTimeout(request.timer);
+            request.reject(new errors_1.SessionRequestError(reason, code ? { code, retryable: false } : { code: 'host_unavailable', retryable: true }));
+            this.pending.delete(id);
+        }
+        for (const listener of this.closeListeners)
+            listener(reason, code);
+        this.closeListeners.clear();
+    }
+    receive(line) {
+        let message;
+        try {
+            message = JSON.parse(line);
+        }
+        catch {
+            return;
+        }
+        if (typeof message.method === 'string') {
+            const params = (message.params ?? {});
+            if (message.method === 'session.event') {
+                const envelope = { sessionId: String(params.sessionId), seq: Number(params.seq), event: params.event };
+                for (const listener of this.eventListeners)
+                    listener(envelope);
+            }
+            else if (message.method === 'session.lagged') {
+                for (const listener of this.lagListeners)
+                    listener(String(params.sessionId), Number(params.deliveredSeq));
+            }
+            else if (message.method === 'host.leaseLost') {
+                this.markClosed('Another session host took over this scope', 'journal_locked');
+            }
+            return;
+        }
+        // The host could not start and printed its fatal result (e.g. another host owns the journal).
+        if (message.type === 'runtime-result' && message.status === 'failed') {
+            const error = message.error;
+            const detail = typeof error === 'object' && error !== null ? error : { message: error };
+            this.markClosed(typeof detail.message === 'string' ? detail.message : 'The session host failed to start', typeof detail.code === 'string' ? detail.code : undefined);
+            return;
+        }
+        if (typeof message.id !== 'number')
+            return;
+        const request = this.pending.get(message.id);
+        if (!request)
+            return;
+        this.pending.delete(message.id);
+        clearTimeout(request.timer);
+        if (message.error && typeof message.error === 'object') {
+            const error = message.error;
+            request.reject(new errors_1.SessionRequestError(error.message ?? `Session host rejected ${request.method}`, error.data ?? { code: 'internal', retryable: false }, error.code));
+        }
+        else {
+            request.resolve(message.result ?? {});
+        }
+    }
+}
+exports.StdioSessionHostClient = StdioSessionHostClient;

package/server/dist/modules/agent-sessions/application/session-event-pump.js

@@ -0,0 +1,99 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.SessionEventPump = void 0;
+const projection_1 = require("../domain/projection");
+const PAGE = 500;
+/**
+ * Applies one Core session's committed events to a surface sink exactly once
+ * and in order. Duplicates are ignored, gaps are filled from the host's
+ * journal (`session.events`), and `attach` rebuilds the in-memory projection
+ * by replaying up to the sink's cursor without re-applying anything.
+ */
+class SessionEventPump {
+    sessionId;
+    client;
+    sink;
+    listener;
+    state;
+    chain = Promise.resolve();
+    detached = false;
+    constructor(sessionId, client, sink, listener = () => { }) {
+        this.sessionId = sessionId;
+        this.client = client;
+        this.sink = sink;
+        this.listener = listener;
+        this.state = (0, projection_1.initialProjection)(sessionId);
+    }
+    get projection() {
+        return this.state;
+    }
+    /** Rebuild state up to the sink cursor, then apply everything after it. */
+    attach() {
+        return this.enqueue(async () => {
+            const cursor = this.sink.cursor(this.sessionId);
+            this.state = (0, projection_1.initialProjection)(this.sessionId);
+            await this.fetchFrom(0, cursor);
+            await this.fetchFrom(this.state.lastSeq);
+        });
+    }
+    /** A live notification. */
+    push(envelope) {
+        if (envelope.sessionId !== this.sessionId)
+            return Promise.resolve();
+        return this.enqueue(async () => {
+            const result = (0, projection_1.reduceEnvelope)(this.state, envelope);
+            if (result.status === 'duplicate')
+                return;
+            if (result.status === 'gap') {
+                await this.fetchFrom(this.state.lastSeq);
+                return;
+            }
+            this.commit(envelope.seq, result.state, result.ops);
+        });
+    }
+    /** The host dropped queued notifications; catch up from the journal. */
+    catchUp() {
+        return this.enqueue(() => this.fetchFrom(this.state.lastSeq));
+    }
+    detach() {
+        this.detached = true;
+    }
+    /** Page through the journal; events up to `rebuildUntil` only rebuild state. */
+    async fetchFrom(afterSeq, rebuildUntil = 0) {
+        let cursor = afterSeq;
+        for (;;) {
+            if (this.detached)
+                return;
+            if (rebuildUntil > 0 && cursor >= rebuildUntil)
+                return;
+            const page = await this.client.request('session.events', { sessionId: this.sessionId, afterSeq: cursor, limit: PAGE });
+            for (const envelope of page.events) {
+                const result = (0, projection_1.reduceEnvelope)(this.state, envelope);
+                if (result.status !== 'applied')
+                    continue;
+                if (envelope.seq <= rebuildUntil)
+                    this.state = result.state;
+                else
+                    this.commit(envelope.seq, result.state, result.ops);
+                cursor = envelope.seq;
+                if (rebuildUntil > 0 && cursor >= rebuildUntil)
+                    return;
+            }
+            if (!page.hasMore || page.events.length === 0)
+                return;
+        }
+    }
+    commit(seq, state, ops) {
+        // The sink owns the transaction (ops + cursor); state advances only after it committed.
+        this.sink.apply(this.sessionId, seq, ops);
+        this.state = state;
+        if (ops.length > 0)
+            this.listener(this.sessionId, ops, state);
+    }
+    enqueue(task) {
+        const run = this.chain.then(task);
+        this.chain = run.catch(() => undefined);
+        return run;
+    }
+}
+exports.SessionEventPump = SessionEventPump;

package/server/dist/modules/agent-sessions/domain/availability.js

@@ -0,0 +1,25 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DEFAULT_CORE_SESSIONS_FLAG = void 0;
+exports.parseCoreSessionsFlag = parseCoreSessionsFlag;
+exports.resolveCoreSessionsAvailability = resolveCoreSessionsAvailability;
+exports.DEFAULT_CORE_SESSIONS_FLAG = 'auto';
+function parseCoreSessionsFlag(raw) {
+    const value = raw?.trim().toLowerCase();
+    if (value === 'on' || value === '1' || value === 'true')
+        return 'on';
+    if (value === 'auto')
+        return 'auto';
+    if (value === 'off' || value === '0' || value === 'false')
+        return 'off';
+    return exports.DEFAULT_CORE_SESSIONS_FLAG;
+}
+function resolveCoreSessionsAvailability(flag, capabilities, contractCompatible = true) {
+    if (flag === 'off')
+        return { enabled: false, flag, reason: 'Core sessions are disabled (SPECRAILS_CORE_SESSIONS=off)' };
+    if (capabilities?.sessions !== 1)
+        return { enabled: false, flag, reason: 'The selected Core does not advertise the sessions capability; using legacy transports' };
+    if (!contractCompatible)
+        return { enabled: false, flag, reason: 'The selected Core session contract is not compatible with this Desktop; using legacy transports' };
+    return { enabled: true, flag, reason: flag === 'on' ? 'Core sessions forced on' : 'Core sessions available' };
+}