specrails-desktop 2.61.0 → 2.63.0

package/docs/platforms/windows.md

@@ -15,14 +15,14 @@ Installers are published on every release under:
 
 > 📥 `https://specrails.dev/downloads/specrails-desktop/latest/`
 
-Pick the pair that matches your CPU architecture:
+Pick the installer that matches your CPU architecture:
 
-| Architecture | NSIS installer (recommended) | MSI installer (enterprise/group-policy) |
-| --- | --- | --- |
-| x64 | `specrails-desktop-<version>-x64-setup.exe` | `specrails-desktop-<version>-x64.msi` |
-| ARM64 | `specrails-desktop-<version>-arm64-setup.exe` | `specrails-desktop-<version>-arm64.msi` |
+| Architecture | Installer |
+| --- | --- |
+| x64 | `specrails-desktop-<version>-x64-setup.exe` |
+| ARM64 | `specrails-desktop-<version>-arm64-setup.exe` |
 
-If you are unsure which to use, the NSIS `-setup.exe` is the right choice for individual installs; the MSI exists for enterprise deployment. Versioned copies live at `downloads/specrails-desktop/v<version>/` for archival and deep-linking.
+Windows ships only the NSIS installer. For unattended or managed deployment, run it silently with `/S` (optionally `/D=<install dir>` as the last argument). Releases up to 2.62 also published an `.msi`; see [Updates](#updates) for how those installations migrate. The installer provisions Microsoft Edge WebView2 when it is missing, downloading it through a small embedded bootstrapper (Windows 11 and current Windows 10 already include it). Versioned copies live at `downloads/specrails-desktop/v<version>/` for archival and deep-linking.
 
 A machine-readable `manifest.json` in `latest/` describes the current release (version, sha256, size) per platform, including `windows-x64` and `windows-arm64` entries — consumers can read it to build download links without hardcoding a version.
 
@@ -59,7 +59,7 @@ When the bundle is present, the Tauri host sets `SPECRAILS_IS_DESKTOP=1` and `SP
 
 The desktop app self-updates via the Tauri updater plugin. It checks a GitHub Releases `latest.json` endpoint and, on Windows, applies updates with `installMode: "passive"` — the update runs with a minimal progress UI and the app relaunches into the new version.
 
-Updates preserve the installation format: NSIS installs receive a signed `-setup.exe` updater artifact, and MSI installs receive a signed `.msi` artifact for the same architecture. The signatures are Tauri/minisign integrity signatures, separate from Authenticode signing. An incomplete installer/signature pair blocks publication; the release no longer silently substitutes MSI for NSIS.
+Updates use the signed NSIS `-setup.exe` for the same architecture. Installations made from an earlier `.msi` receive that NSIS update too: the installer detects the MSI installation and removes it before installing, so a single installation remains (Windows may ask for administrator approval to remove the machine-wide MSI). The signatures are Tauri/minisign integrity signatures, separate from Authenticode signing. An incomplete installer/signature pair blocks publication.
 
 Normal quit and updates request an authenticated graceful shutdown of the owned sidecar first, giving processes and persistent logs time to close before a bounded force-stop fallback.
 
@@ -73,8 +73,8 @@ Reserved paths (`.specrails/profiles/**`, `.claude/agents/custom-*.md`) are pres
 
 ## Uninstall
 
-- NSIS: use the **Start Menu → Specrails → Uninstall** entry, or *Settings → Apps*.
-- MSI: use *Settings → Apps* or `msiexec /x <msi-path>`.
+- Use the **Start Menu → Specrails → Uninstall** entry, or *Settings → Apps*.
+- An installation from an earlier `.msi` release that has not updated yet: *Settings → Apps* or `msiexec /x <msi-path>`.
 
 ## Known limitations
 

package/local-runner/dist/specrails-local-runner.js

@@ -4036,7 +4036,7 @@ var require_core = __commonJS({
       constructor(opts = {}) {
         this.schemas = {};
         this.refs = {};
-        this.formats = {};
+        this.formats = /* @__PURE__ */ Object.create(null);
         this._compilations = /* @__PURE__ */ new Set();
         this._loading = {};
         this._cache = /* @__PURE__ */ new Map();

package/mcp-bridge/dist/specrails-mcp.js

@@ -7051,7 +7051,7 @@ function connectBridge(clientFacing, appFacing) {
       });
     }
     pending.clear();
-    closeBoth();
+    if (!appFacing.recoverable) closeBoth();
   };
 }
 
@@ -7062,7 +7062,7 @@ function authenticatedFetch(agentHeaders, fetchImpl = fetch) {
     const token = readMcpToken();
     const headers = new Headers(init?.headers);
     if (token) headers.set("Authorization", `Bearer ${token}`);
-    for (const [key, value] of Object.entries(agentHeaders)) headers.set(key, value);
+    for (const [key, value] of Object.entries(typeof agentHeaders === "function" ? agentHeaders() : agentHeaders)) headers.set(key, value);
     const response = await fetchImpl(input, { ...init, headers });
     const refreshed = response.status === 401 ? readMcpToken() : null;
     if (refreshed && refreshed !== token) {
@@ -7073,12 +7073,25 @@ function authenticatedFetch(agentHeaders, fetchImpl = fetch) {
     return response;
   };
 }
+function rejectsStaleSession(err) {
+  const failure = err;
+  if (failure?.code === 404) return true;
+  return failure?.code === 403 && typeof failure.message === "string" && /reinitiali[sz]e/i.test(failure.message);
+}
+function isLostStream(error2) {
+  return /SSE stream disconnected|Maximum reconnection attempts|Failed to reconnect/i.test(error2.message);
+}
 var RecoveringHttpTransport = class {
-  constructor(create) {
+  constructor(create, log = () => {
+  }) {
     this.create = create;
+    this.log = log;
     this.current = this.attach(create());
   }
   create;
+  log;
+  /** connectBridge keeps the client side open when the app side can recover. */
+  recoverable = true;
   onmessage;
   onerror;
   onclose;
@@ -7086,12 +7099,19 @@ var RecoveringHttpTransport = class {
   initializeMessage;
   recovery;
   closed = false;
+  /** The last recovery failed; the next request must reinitialize first. */
+  stale = false;
   attach(transport) {
     transport.onmessage = (message, extra) => {
       if (transport === this.current && !this.closed) this.onmessage?.(message, extra);
     };
     transport.onerror = (error2) => {
-      if (transport === this.current && !this.closed) this.onerror?.(error2);
+      if (transport !== this.current || this.closed) return;
+      if (isLostStream(error2)) {
+        this.stale = true;
+        this.log("stream-lost", error2.message);
+      }
+      this.onerror?.(error2);
     };
     transport.onclose = () => {
       if (transport === this.current && !this.closed) this.onclose?.();
@@ -7104,21 +7124,31 @@ var RecoveringHttpTransport = class {
   async send(message) {
     if (this.closed) throw new Error("MCP bridge is closed");
     if ("method" in message && message.method === "initialize") this.initializeMessage = message;
+    if (this.stale && this.initializeMessage && message !== this.initializeMessage) this.recovery ??= this.recover("retry after a failed recovery");
     if (this.recovery) await this.recovery;
     const attempted = this.current;
     try {
       await attempted.send(message);
     } catch (err) {
-      if (err?.code !== 404 || !this.initializeMessage || message === this.initializeMessage) throw err;
-      if (attempted === this.current) {
-        this.recovery ??= this.reinitialize().finally(() => {
-          this.recovery = void 0;
-        });
-      }
+      if (!rejectsStaleSession(err) || !this.initializeMessage || message === this.initializeMessage) throw err;
+      if (attempted === this.current) this.recovery ??= this.recover(`session rejected (${err.code})`);
       if (this.recovery) await this.recovery;
       await this.current.send(message);
     }
   }
+  recover(reason) {
+    this.log("recover", reason);
+    return this.reinitialize().then(() => {
+      this.stale = false;
+      this.log("recovered");
+    }).catch((error2) => {
+      this.stale = true;
+      this.log("recover-failed", error2 instanceof Error ? error2.message : String(error2));
+      throw error2;
+    }).finally(() => {
+      this.recovery = void 0;
+    });
+  }
   async reinitialize() {
     const previous = this.current;
     const next = this.attach(this.create());
@@ -7141,9 +7171,6 @@ var RecoveringHttpTransport = class {
         void next.send({ ...this.initializeMessage, id }).catch(reject);
       });
       await next.send({ jsonrpc: "2.0", method: "notifications/initialized" });
-    } catch (err) {
-      await this.close();
-      throw err;
     } finally {
       if (timer) clearTimeout(timer);
       next.onmessage = relay;
@@ -7171,15 +7198,55 @@ var RecoveringHttpTransport = class {
 };
 
 // mcp-bridge/src/index.ts
+var import_node_fs = require("node:fs");
+var import_node_path = require("node:path");
+var LOG_LIMIT_BYTES = 256 * 1024;
+function lifecycleLog() {
+  const capabilityFile = process.env.SPECRAILS_AGENT_CAPABILITY_FILE?.trim();
+  if (!capabilityFile) return () => {
+  };
+  const file = (0, import_node_path.join)((0, import_node_path.dirname)(capabilityFile), "bridge.log");
+  return (event, detail) => {
+    try {
+      try {
+        if ((0, import_node_fs.statSync)(file).size > LOG_LIMIT_BYTES) (0, import_node_fs.truncateSync)(file, 0);
+      } catch {
+      }
+      (0, import_node_fs.appendFileSync)(file, `${(/* @__PURE__ */ new Date()).toISOString()} pid=${process.pid} ${event}${detail ? ` ${detail.replace(/\s+/g, " ").slice(0, 500)}` : ""}
+`, { mode: 384 });
+    } catch {
+    }
+  };
+}
 async function main() {
-  const fetchWithCredentials = authenticatedFetch(agentForwardHeaders());
-  const appFacing = new RecoveringHttpTransport(() => new StreamableHTTPClientTransport(appUrl(), { fetch: fetchWithCredentials }));
+  const log = lifecycleLog();
+  log("start", `ppid=${process.ppid}`);
+  for (const signal of ["SIGTERM", "SIGINT", "SIGHUP"]) process.once(signal, () => {
+    log("signal", signal);
+    process.exit(0);
+  });
+  process.on("exit", (code) => log("exit", `code=${code}`));
+  process.stdin.once("end", () => log("stdin-end", "the client closed its side"));
+  agentForwardHeaders();
+  const fetchWithCredentials = authenticatedFetch(() => agentForwardHeaders());
+  const appFacing = new RecoveringHttpTransport(() => new StreamableHTTPClientTransport(appUrl(), { fetch: fetchWithCredentials }), log);
   const clientFacing = new StdioServerTransport();
   connectBridge(clientFacing, appFacing);
+  const relayError = appFacing.onerror;
+  appFacing.onerror = (error2) => {
+    log("app-error", error2.message);
+    relayError?.(error2);
+  };
+  const relayClose = appFacing.onclose;
+  appFacing.onclose = () => {
+    log("close", "app side closed");
+    relayClose?.();
+  };
   await appFacing.start();
   await clientFacing.start();
 }
 main().catch((err) => {
+  lifecycleLog()("fatal", err instanceof Error ? err.message : String(err));
   process.stderr.write(`[specrails-mcp] fatal: ${err instanceof Error ? err.message : String(err)}
 `);
   process.exit(1);

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.61.0",
+  "version": "2.63.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -56,7 +56,7 @@
   "dependencies": {
     "@modelcontextprotocol/sdk": "^1.29.0",
     "@tailwindcss/typography": "^0.5.19",
-    "ajv": "^8.17.1",
+    "ajv": "^8.20.0",
     "better-sqlite3": "^12.8.0",
     "chokidar": "^5.0.0",
     "cross-spawn": "^7.0.6",
@@ -71,29 +71,28 @@
     "selfsigned": "^5.5.0",
     "tree-kill": "^1.2.2",
     "werift": "^0.23.0",
-    "ws": "^8.21.0",
+    "ws": "^8.22.0",
     "zod": "^3.25.76"
   },
   "devDependencies": {
+    "@babel/parser": "^7.29.9",
     "@tauri-apps/cli": "^2.0.0",
     "@types/better-sqlite3": "^7.6.0",
-    "@types/chokidar": "^1.7.5",
     "@types/cross-spawn": "^6.0.6",
-    "@types/diff": "^7.0.2",
     "@types/express": "^5.0.6",
     "@types/js-yaml": "^4.0.9",
     "@types/multer": "^2.1.0",
-    "@types/node": "^25.5.0",
+    "@types/node": "^26.6.5",
     "@types/pdf-parse": "^1.1.5",
     "@types/supertest": "^7.2.0",
     "@types/ws": "^8.5.0",
-    "@vitest/coverage-v8": "^4.1.10",
+    "@vitest/coverage-v8": "^5.0.3",
     "concurrently": "^9.2.1",
     "esbuild": "^0.28.1",
     "supertest": "^7.2.2",
     "tsx": "^4.23.0",
-    "typescript": "^5.4.0",
-    "vitest": "^4.1.10"
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.3"
   },
   "overrides": {
     "ip": "npm:@eggjs/ip@2.1.0",

package/server/dist/agent-mcp-config.js

@@ -8,6 +8,8 @@ exports.resolveNodeCommand = resolveNodeCommand;
 exports.buildSpecrailsMcpEntry = buildSpecrailsMcpEntry;
 exports.mergeSpecrailsIntoWorkspaceMcp = mergeSpecrailsIntoWorkspaceMcp;
 exports.buildAgentMcpArgs = buildAgentMcpArgs;
+exports.prepareAgentMcpSpec = prepareAgentMcpSpec;
+exports.rotateAgentSessionCapability = rotateAgentSessionCapability;
 exports.removeAgentCapabilityFile = removeAgentCapabilityFile;
 exports.prepareAgentMcp = prepareAgentMcp;
 exports.syncExternalServersIntoJsonFile = syncExternalServersIntoJsonFile;
@@ -235,6 +237,45 @@ function buildAgentTurnEntry(opts) {
     }
     return entry;
 }
+function stringRecord(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const entries = Object.entries(value).filter((entry) => typeof entry[1] === 'string');
+    return entries.length ? Object.fromEntries(entries) : undefined;
+}
+/**
+ * MCP servers for a resident Core agent session. The `specrails` bridge reads
+ * the conversation's capability file on every request, and this call
+ * atomically (re)writes that file with the CURRENT turn's capability — so a
+ * long-lived provider process always acts under the latest turn's tier.
+ * External servers are passed through as structured specs.
+ */
+function prepareAgentMcpSpec(opts) {
+    const entry = buildAgentTurnEntry({ conversationId: opts.conversationId, port: opts.port, capability: opts.capability });
+    if (!entry)
+        throw new Error('The bundled Specrails MCP bridge is unavailable.');
+    // Specrails authorizes every action against the mission tier; never auto-approve external servers.
+    const specs = [{ name: 'specrails', command: entry.command, args: [...entry.args], env: { ...entry.env }, autoApprove: true }];
+    for (const server of opts.external ?? []) {
+        if (server.name === 'specrails')
+            continue;
+        const config = server.config;
+        if (typeof config.url === 'string') {
+            const headers = stringRecord(config.headers);
+            specs.push({ name: server.name, url: config.url, ...(headers ? { headers } : {}) });
+        }
+        else if (typeof config.command === 'string') {
+            const env = stringRecord(config.env);
+            specs.push({ name: server.name, command: config.command, args: Array.isArray(config.args) ? config.args.filter((arg) => typeof arg === 'string') : [], ...(env ? { env } : {}) });
+        }
+    }
+    return specs;
+}
+/** Rotate the resident session's capability for a new turn (atomic rewrite). */
+function rotateAgentSessionCapability(conversationId, port, capability) {
+    if (!buildAgentTurnEntry({ conversationId, port, capability }))
+        throw new Error('The bundled Specrails MCP bridge is unavailable.');
+}
 /** Delete the on-disk bearer as soon as its owning agent turn settles. */
 function removeAgentCapabilityFile(conversationId, invocationId) {
     if (!AGENT_CONVERSATION_ID_RE.test(conversationId) ||

package/server/dist/core-compat.js

@@ -12,6 +12,7 @@ exports.getCLIStatus = getCLIStatus;
 exports.checkCoreCompat = checkCoreCompat;
 exports.coreCompatSupportsProvider = coreCompatSupportsProvider;
 const child_process_1 = require("child_process");
+const agent_sessions_1 = require("./modules/agent-sessions");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const setup_manager_1 = require("./setup-manager");
@@ -264,6 +265,7 @@ async function checkCoreCompat() {
         contractFound: true,
         contractSchemaVersion: contract.schemaVersion,
         supportedProviders,
+        sessions: contract.agentRuntime?.sessions ? (0, agent_sessions_1.checkSessionContract)(contract.agentRuntime.sessions) : null,
     };
 }
 /** True only when the located Core contract explicitly renders this provider. */

package/server/dist/desktop-db.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.AGENT_SEARCH_INDEX_DDL = void 0;
+exports.GLOBAL_SUBAGENT_RUNTIME_KEY = exports.GLOBAL_ALLOW_SUBAGENTS_KEY = exports.AGENT_SEARCH_INDEX_DDL = void 0;
 exports.setProjectProvidersMirror = setProjectProvidersMirror;
 exports.getDesktopDbPath = getDesktopDbPath;
 exports.rebuildAgentSearchIndex = rebuildAgentSearchIndex;
@@ -19,6 +19,9 @@ exports.updateProjectRepository = updateProjectRepository;
 exports.removeProjectRepository = removeProjectRepository;
 exports.removeProject = removeProject;
 exports.touchProject = touchProject;
+exports.getGlobalAllowSubagents = getGlobalAllowSubagents;
+exports.getGlobalSubagentRuntime = getGlobalSubagentRuntime;
+exports.setGlobalSubagentRuntime = setGlobalSubagentRuntime;
 exports.getDesktopSetting = getDesktopSetting;
 exports.setDesktopSetting = setDesktopSetting;
 exports.setProjectSetupSession = setProjectSetupSession;
@@ -39,6 +42,7 @@ exports.getWebhook = getWebhook;
 exports.addWebhook = addWebhook;
 exports.updateWebhook = updateWebhook;
 exports.removeWebhook = removeWebhook;
+const project_settings_1 = require("./modules/project-settings");
 const fs_1 = __importDefault(require("fs"));
 const path_1 = __importDefault(require("path"));
 const os_1 = __importDefault(require("os"));
@@ -683,6 +687,75 @@ function applyDesktopMigrations(db) {
             if (!columns.includes('workspace_paths'))
                 db.exec('ALTER TABLE project_repositories ADD COLUMN workspace_paths TEXT');
         },
+        // 33: core-agent-sessions-host — Desktop's rebuildable projection of Core
+        // agent sessions. Core's journal (~/.specrails/sessions/<scope>/) is the
+        // source of truth; these rows are re-derivable by replaying it. Cursor and
+        // projected rows are always written in one transaction. Column-guarded for
+        // migration replay fixtures.
+        () => {
+            db.exec(`
+        CREATE TABLE IF NOT EXISTS agent_session_cursors (
+          conversation_id TEXT PRIMARY KEY REFERENCES agent_conversations(id) ON DELETE CASCADE,
+          core_session_id TEXT NOT NULL,
+          scope TEXT NOT NULL,
+          last_seq INTEGER NOT NULL DEFAULT 0,
+          resident_phase TEXT NOT NULL DEFAULT 'idle' CHECK (resident_phase IN ('idle', 'turn', 'background')),
+          process_alive INTEGER NOT NULL DEFAULT 0,
+          live_subagents INTEGER NOT NULL DEFAULT 0,
+          updated_at TEXT NOT NULL DEFAULT (datetime('now'))
+        );
+        CREATE TABLE IF NOT EXISTS agent_subagents (
+          conversation_id TEXT NOT NULL REFERENCES agent_conversations(id) ON DELETE CASCADE,
+          subagent_id TEXT NOT NULL,
+          parent_id TEXT,
+          kind TEXT NOT NULL CHECK (kind IN ('foreground', 'background')),
+          agent_type TEXT,
+          description TEXT NOT NULL,
+          phase TEXT NOT NULL CHECK (phase IN ('running', 'idle', 'failed', 'stopped', 'killed', 'interrupted')),
+          reason TEXT,
+          restarts INTEGER NOT NULL DEFAULT 0,
+          launched_turn_id TEXT,
+          started_at TEXT NOT NULL,
+          ended_at TEXT,
+          usage_json TEXT,
+          tool_uses INTEGER,
+          duration_ms INTEGER,
+          result_summary TEXT,
+          updated_at TEXT NOT NULL DEFAULT (datetime('now')),
+          PRIMARY KEY (conversation_id, subagent_id)
+        );
+        CREATE INDEX IF NOT EXISTS idx_agent_subagents_turn ON agent_subagents(conversation_id, launched_turn_id);
+        CREATE TABLE IF NOT EXISTS agent_subagent_events (
+          conversation_id TEXT NOT NULL,
+          subagent_id TEXT NOT NULL,
+          seq INTEGER NOT NULL,
+          channel TEXT NOT NULL CHECK (channel IN ('text', 'tool')),
+          delta TEXT,
+          tool_json TEXT,
+          created_at TEXT NOT NULL DEFAULT (datetime('now')),
+          PRIMARY KEY (conversation_id, subagent_id, seq),
+          FOREIGN KEY (conversation_id, subagent_id) REFERENCES agent_subagents(conversation_id, subagent_id) ON DELETE CASCADE
+        );
+      `);
+            const invocationColumns = db.prepare('PRAGMA table_info(agent_invocations)').all().map((c) => c.name);
+            if (!invocationColumns.includes('origin'))
+                db.exec(`ALTER TABLE agent_invocations ADD COLUMN origin TEXT NOT NULL DEFAULT 'user' CHECK (origin IN ('user', 'subagent', 'system'));`);
+            const messageColumns = db.prepare('PRAGMA table_info(agent_messages)').all().map((c) => c.name);
+            if (!messageColumns.includes('core_turn_id'))
+                db.exec(`ALTER TABLE agent_messages ADD COLUMN core_turn_id TEXT;`);
+            if (!messageColumns.includes('turn_origin'))
+                db.exec(`ALTER TABLE agent_messages ADD COLUMN turn_origin TEXT CHECK (turn_origin IS NULL OR turn_origin IN ('user', 'subagent', 'system'));`);
+            db.exec(`CREATE INDEX IF NOT EXISTS idx_agent_messages_core_turn ON agent_messages(conversation_id, core_turn_id) WHERE core_turn_id IS NOT NULL;`);
+        },
+        // 34: hybrid sub-agent runtime — sub-agents Core launched on another
+        // provider record which driver and model ran them. Column-guarded.
+        () => {
+            const columns = db.prepare('PRAGMA table_info(agent_subagents)').all().map((c) => c.name);
+            if (!columns.includes('delegated_driver'))
+                db.exec('ALTER TABLE agent_subagents ADD COLUMN delegated_driver TEXT');
+            if (!columns.includes('delegated_model'))
+                db.exec('ALTER TABLE agent_subagents ADD COLUMN delegated_model TEXT');
+        },
     ];
     (0, sqlite_migrations_1.applyNumberedMigrations)(db, migrations);
 }
@@ -805,6 +878,30 @@ function removeProject(db, id) {
 function touchProject(db, id) {
     db.prepare("UPDATE projects SET last_seen_at = datetime('now') WHERE id = ?").run(id);
 }
+/** App-global "Allow sub-agents" for missions without a project (default off). */
+exports.GLOBAL_ALLOW_SUBAGENTS_KEY = 'agent_allow_subagents';
+function getGlobalAllowSubagents(db) {
+    return getDesktopSetting(db, exports.GLOBAL_ALLOW_SUBAGENTS_KEY) === 'true';
+}
+/** App-wide "Run sub-agents with" for missions without a project; null = the mission agent's provider. */
+exports.GLOBAL_SUBAGENT_RUNTIME_KEY = 'agent_subagent_runtime';
+function getGlobalSubagentRuntime(db) {
+    const raw = getDesktopSetting(db, exports.GLOBAL_SUBAGENT_RUNTIME_KEY);
+    if (!raw)
+        return null;
+    try {
+        return (0, project_settings_1.parseSubagentRuntimeSetting)(JSON.parse(raw));
+    }
+    catch {
+        return null;
+    }
+}
+function setGlobalSubagentRuntime(db, value) {
+    if (value === null)
+        db.prepare('DELETE FROM desktop_settings WHERE key = ?').run(exports.GLOBAL_SUBAGENT_RUNTIME_KEY);
+    else
+        setDesktopSetting(db, exports.GLOBAL_SUBAGENT_RUNTIME_KEY, JSON.stringify(value));
+}
 function getDesktopSetting(db, key) {
     const row = db.prepare('SELECT value FROM desktop_settings WHERE key = ?').get(key);
     return row?.value;
@@ -828,9 +925,9 @@ function recordAgentInvocation(db, input) {
       id, conversation_id, project_id, provider, surface, model, status,
       started_at, finished_at, duration_ms, duration_api_ms,
       tokens_in, tokens_out, tokens_cache_read, tokens_cache_create,
-      total_cost_usd, total_cost_usd_estimated, num_turns, session_id
-    ) VALUES (?, ?, ?, ?, 'agent-chat', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
-  `).run(input.id, input.conversation_id, input.project_id ?? null, input.provider, input.model ?? null, input.status, input.started_at, input.finished_at ?? null, input.duration_ms ?? null, input.duration_api_ms ?? null, input.tokens_in ?? null, input.tokens_out ?? null, input.tokens_cache_read ?? null, input.tokens_cache_create ?? null, input.total_cost_usd ?? null, input.total_cost_usd_estimated ? 1 : 0, input.num_turns ?? null, input.session_id ?? null);
+      total_cost_usd, total_cost_usd_estimated, num_turns, session_id, origin
+    ) VALUES (?, ?, ?, ?, 'agent-chat', ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?, ?)
+  `).run(input.id, input.conversation_id, input.project_id ?? null, input.provider, input.model ?? null, input.status, input.started_at, input.finished_at ?? null, input.duration_ms ?? null, input.duration_api_ms ?? null, input.tokens_in ?? null, input.tokens_out ?? null, input.tokens_cache_read ?? null, input.tokens_cache_create ?? null, input.total_cost_usd ?? null, input.total_cost_usd_estimated ? 1 : 0, input.num_turns ?? null, input.session_id ?? null, input.origin ?? 'user');
 }
 /**
  * Sum of all agent-chat turn costs, optionally since an ISO instant (inclusive).

package/server/dist/desktop-router.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.createDesktopRouter = createDesktopRouter;
+const project_settings_1 = require("./modules/project-settings");
 const http_1 = require("./modules/subscription-usage/adapters/http");
 const runtime_role_prompts_router_1 = require("./runtime-role-prompts-router");
 const express_1 = require("express");
@@ -816,11 +817,26 @@ function createDesktopRouter(registry, broadcast, usageService) {
             'http://localhost:3000';
         const costAlertThresholdRaw = (0, desktop_db_1.getDesktopSetting)(registry.desktopDb, 'cost_alert_threshold_usd');
         const costAlertThresholdUsd = costAlertThresholdRaw != null ? parseFloat(costAlertThresholdRaw) : null;
-        res.json({ port: parseInt(port, 10), specrailsTechUrl, costAlertThresholdUsd });
+        const allowSubagents = (0, desktop_db_1.getGlobalAllowSubagents)(registry.desktopDb);
+        res.json({ port: parseInt(port, 10), specrailsTechUrl, costAlertThresholdUsd, allowSubagents, subagentRuntime: (0, desktop_db_1.getGlobalSubagentRuntime)(registry.desktopDb) });
     });
     // PUT /api/settings — update app-level settings
     router.put('/settings', (req, res) => {
-        const { port, specrailsTechUrl, costAlertThresholdUsd } = req.body ?? {};
+        const { port, specrailsTechUrl, costAlertThresholdUsd, allowSubagents } = req.body ?? {};
+        if (allowSubagents !== undefined && typeof allowSubagents !== 'boolean') {
+            res.status(400).json({ error: 'allowSubagents must be a boolean' });
+            return;
+        }
+        let subagentRuntime;
+        if (req.body?.subagentRuntime !== undefined) {
+            try {
+                subagentRuntime = (0, project_settings_1.parseSubagentRuntimeSetting)(req.body.subagentRuntime);
+            }
+            catch (error) {
+                res.status(400).json({ error: error.message });
+                return;
+            }
+        }
         if (port !== undefined) {
             const n = Number(port);
             if (!Number.isInteger(n) || n < 1 || n > 65535) {
@@ -848,6 +864,19 @@ function createDesktopRouter(registry, broadcast, usageService) {
                 (0, desktop_db_1.setDesktopSetting)(registry.desktopDb, 'cost_alert_threshold_usd', String(costAlertThresholdUsd));
             }
         }
+        if (allowSubagents !== undefined) {
+            const previous = (0, desktop_db_1.getGlobalAllowSubagents)(registry.desktopDb);
+            (0, desktop_db_1.setDesktopSetting)(registry.desktopDb, desktop_db_1.GLOBAL_ALLOW_SUBAGENTS_KEY, allowSubagents ? 'true' : 'false');
+            // Project-less missions re-read their sub-agent policy.
+            if (previous !== allowSubagents)
+                registry.notifySettingsChanged({ projectId: null });
+        }
+        if (subagentRuntime !== undefined) {
+            const previous = JSON.stringify((0, desktop_db_1.getGlobalSubagentRuntime)(registry.desktopDb));
+            (0, desktop_db_1.setGlobalSubagentRuntime)(registry.desktopDb, subagentRuntime);
+            if (previous !== JSON.stringify(subagentRuntime))
+                registry.notifySettingsChanged({ projectId: null });
+        }
         res.json({ ok: true });
     });
     // ─── Budget routes ────────────────────────────────────────────────────────────

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