specrails-desktop 2.60.0 → 2.62.0

package/server/dist/index.js

@@ -19,6 +19,8 @@ const desktop_router_1 = require("./desktop-router");
 const provider_detection_1 = require("./provider-detection");
 const provider_selection_1 = require("./provider-selection");
 const desktop_db_1 = require("./desktop-db");
+const sqlite_1 = require("./modules/project-settings/adapters/sqlite");
+const agent_sessions_1 = require("./modules/agent-sessions");
 const legacy_migration_1 = require("./legacy-migration");
 const framework_reseed_1 = require("./framework-reseed");
 const project_router_1 = require("./project-router");
@@ -31,6 +33,13 @@ const feature_flags_1 = require("./feature-flags");
 const mobile_1 = require("./mobile");
 const mcp_1 = require("./mcp");
 const agent_chat_manager_1 = require("./modules/missions/runtime/agent-chat-manager");
+const mission_core_sessions_1 = require("./modules/missions/runtime/mission-core-sessions");
+const session_host_registry_1 = require("./modules/agent-sessions/runtime/session-host-registry");
+const http_2 = require("./modules/agent-sessions/adapters/http");
+const host_process_1 = require("./modules/agent-sessions/adapters/host-process");
+const core_sessions_availability_1 = require("./modules/agent-sessions/runtime/core-sessions-availability");
+const registry_1 = require("./providers/registry");
+const agent_capability_1 = require("./mcp/agent-capability");
 const agent_chat_router_1 = require("./modules/missions/runtime/agent-chat-router");
 const blueprint_chat_manager_1 = require("./modules/builder/runtime/blueprint-chat-manager");
 const blueprint_router_1 = require("./modules/builder/runtime/blueprint-router");
@@ -282,6 +291,7 @@ let _registry = null;
 let _mobileGateway = null;
 let _mcpManager = null;
 let _agentChatManager = null;
+let _sessionHosts = null;
 let _blueprintChatManager = null;
 let _headroomManager = null;
 server.on('upgrade', (request, socket, head) => {
@@ -654,10 +664,56 @@ function applyPtyWsRateLimiting(ws) {
     });
     const agentChatManager = new agent_chat_manager_1.AgentChatManager(broadcast, registry.desktopDb, port, registry);
     _agentChatManager = agentChatManager;
+    // Core agent sessions (core-agent-sessions-host): one supervised Core host per
+    // project scope; missions use it when SPECRAILS_CORE_SESSIONS allows and the
+    // selected Core advertises `sessions`. Otherwise missions keep legacy runners.
+    const sessionHosts = new session_host_registry_1.SessionHostRegistry({
+        launcher: new host_process_1.CoreHostLauncher({ host: { name: 'specrails-desktop', version: process.env.npm_package_version ?? 'unknown' } }),
+        clock: { now: () => Date.now(), after: (ms, callback) => { const timer = setTimeout(callback, ms); timer.unref?.(); return { cancel: () => clearTimeout(timer) }; } },
+        onStatus: (scope, status, detail, code) => {
+            console.log(`[agent-sessions] ${scope}: ${status}${detail ? ` (${detail})` : ''}`);
+            // App-level event (no projectId): open missions show a notice when their scope degrades.
+            broadcast({ type: 'agent_sessions_host', scope, status, detail: detail ?? null, code: code ?? null, timestamp: new Date().toISOString() });
+        },
+    });
+    _sessionHosts = sessionHosts;
+    const projectAllowsSubagents = (projectId) => {
+        // A pinned project that is not loaded cannot vouch for sub-agents.
+        const context = registry.getContext(projectId);
+        return context ? (0, sqlite_1.getProjectSettings)(context.db).allowSubagents : false;
+    };
+    const missionCoreSessions = new mission_core_sessions_1.MissionCoreSessions({
+        db: registry.desktopDb,
+        registry: sessionHosts,
+        port,
+        broadcast: (message) => broadcast(message),
+        adapterFor: registry_1.getAdapter,
+        availability: () => (0, core_sessions_availability_1.coreSessionsAvailability)(),
+        projectKey: (projectId) => registry.getProjectRow(projectId)?.slug ?? null,
+        revokeCapability: agent_capability_1.revokeAgentCapability,
+        // "Allow sub-agents": the project setting decides; missions without a project use the app setting.
+        subagentPolicy: (conversation) => (0, agent_sessions_1.resolveSubagentPolicy)({
+            surface: 'mission',
+            projectAllows: conversation.pinned_project_id ? projectAllowsSubagents(conversation.pinned_project_id) : null,
+            globalAllows: (0, desktop_db_1.getGlobalAllowSubagents)(registry.desktopDb),
+        }),
+        // "Run sub-agents with": the project's choice, or the app-wide one without a project.
+        subagentRuntime: (conversation) => {
+            if (!conversation.pinned_project_id)
+                return (0, desktop_db_1.getGlobalSubagentRuntime)(registry.desktopDb);
+            const context = registry.getContext(conversation.pinned_project_id);
+            return context ? (0, sqlite_1.getProjectSettings)(context.db).subagentRuntime : null;
+        },
+    });
+    agentChatManager.setCoreSessions(missionCoreSessions);
+    registry.onSettingsChanged((scope) => { void missionCoreSessions.refreshSubagentPolicy(scope); });
+    registry.onProjectRemoved(({ slug }) => { void sessionHosts.stop(slug); });
     // Publish the instance to the process-wide registry so the rails layer can
     // post PR-decision cards (safe-pr-review-flow). Left null when agent chat is
     // disabled — the rails callers are null-safe and simply skip the card.
     (0, agent_chat_registry_1.setAgentChatManager)((0, agent_chat_router_1.isAgentChatEnabled)() ? agentChatManager : null);
+    // Before the agent router: `/api/agent/session-hosts` is not a conversation route.
+    app.use('/api/agent/session-hosts', (0, http_2.createSessionHostsRouter)(sessionHosts));
     app.use('/api/agent', (0, agent_chat_router_1.createAgentChatRouter)({ manager: agentChatManager, desktopDb: registry.desktopDb }));
     // Project Builder day-0 chat + orchestrated commit (add-project-builder).
     // App-level like agent chat — a Builder conversation runs before any project
@@ -790,6 +846,8 @@ async function shutdown() {
         Promise.resolve().then(() => _mobileGateway?.stop()),
         Promise.resolve().then(() => _mcpManager?.stop()),
         Promise.resolve().then(() => _agentChatManager?.shutdown()),
+        // Core session hosts record running work as interrupted and release their journals.
+        Promise.resolve().then(() => _sessionHosts?.stopAll()),
         Promise.resolve().then(() => _blueprintChatManager?.shutdown()),
     ]);
     // The shell can exit before its application descendants. Keep the event

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/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-bridge.js

@@ -166,6 +166,18 @@ async function runAgentRuntimeInvocation(options) {
         config.providers = (0, agent_runtime_settings_1.stripDesktopConnectionFields)(config.providers, (0, agent_runtime_settings_1.coreConnectionFieldGates)(runtime.api?.capabilities));
         if (runtime.api?.capabilities?.configurableGuardrails !== 1)
             delete config.guardrails;
+        // Setup commands are a `setupCommands` capability: an older Core rejects the unknown key, so strip it and say so once in the run log.
+        if (config.setup !== undefined && !(0, agent_runtime_settings_1.coreSupportsSetupCommands)(runtime.api?.capabilities)) {
+            if (config.setup.length) {
+                try {
+                    options.onLine?.(`[runtime] setup commands ignored: the installed Core does not advertise setupCommands (${config.setup.length} configured)\n`);
+                }
+                catch { /* Advisory log observer. */ }
+            }
+            delete config.setup;
+        }
+        else if (config.setup)
+            config.setup = scopedHostChecks(config.setup, admittedContext.repositories);
         if (definitionEngine && (runtime.api?.capabilities?.engineV2 !== 1 || runtime.api?.capabilities?.workflowDefinitions !== 1))
             throw new Error('engine_unsupported: Update Core to run workflow definitions');
         const compilationConfig = structuredClone(config);

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-runtime/runtime/agent-runtime-effective-config.js

@@ -76,6 +76,8 @@ function resolveEffectiveRuntimeConfig(input, options) {
         }
     fillDefaultRoleModels(config);
     config.verification = config.verification.filter(check => options.repositoryIds.includes(check.repositoryId));
+    if (config.setup)
+        config.setup = config.setup.filter(check => options.repositoryIds.includes(check.repositoryId));
     return { config, origins: { architect: override ? 'explicit-launch-override' : options.source, developer: override ? 'explicit-launch-override' : options.source, reviewer: override ? 'explicit-launch-override' : options.source } };
 }
 /**

package/server/dist/modules/agent-runtime/runtime/agent-runtime-settings-router.js

@@ -21,6 +21,10 @@ function withDefaultRoleModels(body) {
     return { ...body, agents: filled.agents, ...(filled.roles ? { roles: filled.roles } : {}), ...(filled.fixer ? { fixer: filled.fixer } : {}) };
 }
 const loop_role_engines_1 = require("../../loops/runtime/loop-role-engines");
+/** The settings API always answers `setup` as an array; the file keeps it absent until the user saves one. */
+function withSetupList(config) {
+    return config ? { ...config, setup: config.setup ?? [] } : config;
+}
 function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
     /** Guardrail catalog of the loaded Core (configurable-guardrails): ids + phase; the UI owns labels. `supported:false` on older cores. */
     router.get('/:projectId/agent-runtime/guardrails', async (_req, res) => {
@@ -70,7 +74,7 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
                 openRolesAvailable = capabilities?.openRoles === 1;
             }
             catch { /* Ordinary settings remain readable without capability support. */ }
-            res.json({ configured, config, runtimeAvailable: (0, agent_runtime_loader_1.findCoreAgentRuntimeEntry)() !== null, efficiencyAvailable, openRolesAvailable,
+            res.json({ configured, config: withSetupList(config), runtimeAvailable: (0, agent_runtime_loader_1.findCoreAgentRuntimeEntry)() !== null, efficiencyAvailable, openRolesAvailable,
                 workflowRoleDefaults: openRolesAvailable && config ? (0, agent_runtime_effective_config_1.workflowRoleDefaults)(config) : {} });
         }
         catch (err) {
@@ -147,7 +151,7 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
                 }
             }
             const saved = (0, agent_runtime_settings_1.saveAgentRuntimeConfig)(ctx(req).project, config);
-            res.json({ configured: true, config: saved, runtimeAvailable, efficiencyAvailable, openRolesAvailable });
+            res.json({ configured: true, config: withSetupList(saved), runtimeAvailable, efficiencyAvailable, openRolesAvailable });
         }
         catch (err) {
             const validation = err instanceof agent_runtime_settings_1.AgentRuntimeConfigError;

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

@@ -25,6 +25,7 @@ exports.loadRuntimeRolePrompts = loadRuntimeRolePrompts;
 exports.saveRuntimeRolePrompts = saveRuntimeRolePrompts;
 exports.validateRuntimeProviderOverride = validateRuntimeProviderOverride;
 exports.forCoreRuntime = forCoreRuntime;
+exports.coreSupportsSetupCommands = coreSupportsSetupCommands;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
@@ -136,17 +137,18 @@ function validateLoopRuntimeSettings(input, providers = loadRuntimeProviders())
     const config = validateAgentRuntimeConfig({ ...input, enabled: true, providers: portableProviders, verification: [] });
     if (['architect', 'developer', 'reviewer', 'fixer'].some(role => !config.rolePrompts?.[role]?.trim()))
         throw new AgentRuntimeConfigError('Loop agents require an explicit definition for architect, developer, reviewer and fixer');
-    const { enabled: _enabled, providers: _providers, verification: _checks, ...settings } = config;
+    const { enabled: _enabled, providers: _providers, verification: _checks, setup: _setup, ...settings } = config;
     return settings;
 }
 /** Read only repository checks from the old project file. Role migration is explicit. */
 function loadLoopRuntimeConfig(file, input, selection = { provider: 'claude' }) {
-    let verification = [];
+    let verification = [], setup = undefined;
     try {
         const saved = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
         if (!saved || typeof saved !== 'object' || Array.isArray(saved))
             throw new AgentRuntimeConfigError('Saved runtime configuration must be an object');
         verification = saved.verification ?? [];
+        setup = saved.setup;
     }
     catch (error) {
         if (error.code !== 'ENOENT')
@@ -163,7 +165,7 @@ function loadLoopRuntimeConfig(file, input, selection = { provider: 'claude' })
         settings.fixer = inherit(settings.fixer);
     for (const [role, agent] of Object.entries(settings.roles ?? {}))
         settings.roles[role] = inherit(agent);
-    return validateAgentRuntimeConfig({ ...settings, providers, enabled: true, verification });
+    return validateAgentRuntimeConfig({ ...settings, providers, enabled: true, verification, ...(setup !== undefined ? { setup } : {}) });
 }
 const CLI_PROVIDERS = ['claude', 'codex', 'gemini', 'kimi'];
 const ROLES = ['architect', 'developer', 'reviewer'];
@@ -260,10 +262,12 @@ function validateAgentRuntimeConfig(input) {
         if (!Number.isFinite(value) || (key !== 'maxCostUsd' && !Number.isSafeInteger(value)))
             throw new AgentRuntimeConfigError('Workflow limits must be finite, safe numbers');
     }
-    const keys = config.verification.flatMap(command => command.key ? [command.key] : []);
+    // `setup` entries share the verification entry shape and rules (Core validates both with one validator; keys are unique across the two lists).
+    const hostCommands = [...config.verification, ...(config.setup ?? [])];
+    const keys = hostCommands.flatMap(command => command.key ? [command.key] : []);
     if (new Set(keys).size !== keys.length)
         throw new AgentRuntimeConfigError('Verification check keys must be unique');
-    for (const command of config.verification) {
+    for (const command of hostCommands) {
         for (const value of [command.label, ...(command.policy?.inputs ?? []), ...(command.policy?.toolchainInputs ?? []), ...(command.policy?.resources ?? [])])
             if (value !== undefined && (!value.trim() || value.includes('\0')))
                 throw new AgentRuntimeConfigError('Invalid verification label or policy input');
@@ -482,7 +486,7 @@ function validateRuntimeProviderOverride(value) {
         throw new AgentRuntimeConfigError('Invalid runtime provider override effort');
     return structuredClone(raw);
 }
-/** Older Core runtimes reject unknown top-level keys: drop `guardrails` unless the loaded Core advertises `configurableGuardrails`. */
+/** Older Core runtimes reject unknown top-level keys: drop `guardrails` unless the loaded Core advertises `configurableGuardrails`, and `setup` unless it advertises `setupCommands`. */
 function forCoreRuntime(config, capabilities) {
     let out = config;
     if (capabilities?.openRoles !== 1 && out.roles !== undefined) {
@@ -495,6 +499,10 @@ function forCoreRuntime(config, capabilities) {
         const { guardrails: _dropped, ...rest } = out;
         out = rest;
     }
+    if (!coreSupportsSetupCommands(capabilities) && out.setup !== undefined) {
+        const { setup: _dropped, ...rest } = out;
+        out = rest;
+    }
     // The per-role thinking switch is known only to cores advertising `roleThinkingControl`.
     if (capabilities?.roleThinkingControl !== 1 && ([...Object.values(out.agents ?? {}), ...Object.values(out.roles ?? {})].some(agent => agent?.thinking !== undefined) || out.fixer?.thinking !== undefined)) {
         const strip = (agent) => { const { thinking: _t, ...rest } = agent; return rest; };
@@ -502,3 +510,7 @@ function forCoreRuntime(config, capabilities) {
     }
     return out;
 }
+/** Core advertises `setupCommands: 1` when its verify piece runs `RuntimeConfig.setup` before each verification plan. */
+function coreSupportsSetupCommands(capabilities) {
+    return (capabilities?.setupCommands ?? 0) >= 1;
+}

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;
+}