specrails-desktop 2.60.0 → 2.62.0

package/docs/internals/operations-runbook.md

@@ -140,6 +140,17 @@ If a single provider or feature is breaking the app, you can turn it off with an
 
 These are the most common ops escape hatches; see [Configuration → Environment variables](configuration.md#environment-variables) for the complete list of gates and flags.
 
+### Missions on Core agent sessions
+
+With `SPECRAILS_CORE_SESSIONS` at `auto` (the default) or `on`, missions run in a Core host
+process per project scope (`specrails-core runtime host --stdio --scope …`).
+The server log prefix is `[agent-sessions]`.
+
+- **Status.** The server logs each scope's transitions: `starting`, `ready`, `restarting`, `degraded`. `GET /api/agent/session-hosts` lists them. A degraded scope sends new mission turns through the legacy transport, and the mission shows why, with a **Retry** button (`POST /api/agent/session-hosts/:scope/retry`). Crashes degrade a scope after repeated failures. Some causes degrade it at once, without restart attempts: another Desktop instance holding the journal (`journal_locked`), an incompatible Core (`protocol_mismatch`), or a Core without the host (`driver_unavailable`). Close the other instance or fix Core, then retry.
+- **Session data.** Core owns the journals in `~/.specrails/sessions/<project>/sessions.sqlite`. Desktop's tables (`agent_session_cursors`, `agent_subagents`, `agent_subagent_events`) are a projection. If they look wrong, rebuild them for one mission with `POST /api/agent/conversations/:id/session/rebuild`. This never duplicates messages or spend.
+- **Turn it off.** `SPECRAILS_CORE_SESSIONS=off` returns every mission to the legacy transports. Missions keep their history; sub-agent cards remain for past turns.
+- **Live check (paid, opt-in).** `SPECRAILS_LIVE_PROVIDER_SMOKE=1 npx vitest run server/modules/missions/runtime/mission-core-sessions.live.test.ts` runs real Claude missions against the local `../specrails-core` build. Add `SPECRAILS_LIVE_PROVIDERS=claude,codex` to include Codex, and `SPECRAILS_LIVE_<PROVIDER>_MODEL` to pick a model the account can use.
+
 ### Per-project reset (keeps the registration)
 
 To clear one project's job history, invocations, and telemetry pointers while keeping it registered, delete just that project's `jobs.sqlite` with the app stopped:

package/docs/internals/programmatic-agent-runtime.md

@@ -119,6 +119,8 @@ All routes are under `/api/projects/:projectId`:
 | `POST /agent-runtime/runs/:runId/resume` | Accept `{}`, `{ "approve": ["archive"] }`, `{ "recover": ["developer"] }`, explicit `invalidate` phase IDs, or `{ "answer": "…" }` for a pending question (required while one is open) |
 | `POST /agent-runtime/runs/:runId/cancel` | Cancel a continuation owned by this controller |
 
+Host blockers (Core `hostBlockers: 1` / `setupCommands: 1`): the Implement recipe opts its `verify` nodes into host-owned environment repair and the `blocked` outcome. Core emits `[environment] <command> (<repository>)` and `Environment: installed …` lines on the `verification-output` channel, so they reach the readable job log through the same projection as checks. A precondition Core cannot satisfy (no network for a browser download, registry credentials, a failing `setup` command, a missing toolchain) ends the run at `host-blocked` with `completion.blocker = { kind, reason, command, args, cwd, requiredAction, evidenceId? }`; a fixer-declared `blocker` ends it at `fixer-blocked`. A developer-declared `blocker` ends the run at `developer-blocked` only for kinds the person must provide (`credential`, `network`, `environment-variable`); any other kind goes to host verification first: a host precondition ends at `host-blocked`, a reproduced failure goes to the fixer as a correction, and passing checks reach the reviewer, whose rejection of unfinished tasks is corrected within the same budget. The developer loop is bounded like corrections: when `tasks` finds approved tasks still unchecked, the developer runs again only while its last turn changed the candidate (`implementation-progress`, otherwise `implementation-stalled`) and within `implementationLimit` = 3 attempts (`implementation-exhausted`); both ends report the developer's `incomplete` list and summary. The bridge maps that completion (`ok: false`) to `runtimeStatus: 'blocked'`, the run row shows the blocked badge and the loop log renders "Blocked by the host environment" with the localized kind, the failing command and cwd, the required action and a copy button. Older Core packages receive the pre-blocker definition and no `setup` list.
+
 Resume responds `202` after admission and continues asynchronously. Legacy phase IDs are `architect`, `developer`, `fixer`, `verify`, `reviewer` and `archive`. For engine v2, use `POST /loop-runs/:runId/resume` instead. `recover` contains exact attempt IDs from `GET /loop-runs/:runId/recovery`; approval and answer controls use pending interrupt IDs. Node paths are display context, not recovery identities. The saved-execution panel and job header expose explicit per-attempt selection. Core's lease and Desktop's execution/mount claim jointly prevent competing writers. Resident human pauses keep their original settlement callback; restart recovery reconnects to the frozen delivery allocation and terminal outbox.
 
 Desktop launches `node <Core>/dist/agent-runtime/cli.js` with structured argv (`--approve`, `--recover`, `--invalidate`, `--answer <text>` on resume) and consumes JSON lines for phase events (`workflow-event`), agent output (`agent-event`), verification output, trace spans (`span`: `{ traceId, spanId, name, stepId, attempt, visit, startedAt, endedAt, status, usage?, error? }`) and the terminal `runtime-result`. Spans are stored verbatim as job events for diagnostics and are not narrated in the log. `runtime status --compact` returns `state.traceId`, `pendingApproval`, `pendingQuestion` and per-step `{ status, visits }`. Desktop probes `runtime api` once per executable package content digest; `runtime validate --stdin` runs on every save. The job log shows phase transitions (`[runtime] step_started: developer`), live tool activity per role (`[developer] Read src/app.ts`, `[developer] Bash npm test`) and Core's own phase notes (architecture written, verification passed, review approved or corrections requested); the final JSON of architect and reviewer is not echoed. The narrated view (Relato) derives its milestones from the same events: each runtime phase, the tools used, correction loops and a stopped workflow with Core's structural reason. Accounting uses the invocation's new attempts, so resuming a completed phase does not bill its cumulative history twice. Status queries use `--compact`, are read-only and do not invoke providers; accumulated logs stay in Core's checkpoint instead of overflowing the process status response.

package/docs/internals/source-map.md

@@ -5,7 +5,7 @@ architectural dependency declaration. Search a heading or filename and read only
 the relevant source and tests. Feature prefixes group the legacy server files;
 new bounded modules live under `server/modules/`.
 
-Includes 1018 source/build files. Nearby tests are linked where names
+Includes 1042 source/build files. Nearby tests are linked where names
 match; integration suites may live elsewhere. Use `rg` to find other consumers.
 
 ## cli
@@ -457,7 +457,9 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [AgentRefChip.tsx](../../client/src/features/missions/components/AgentRefChip.tsx)
 - [AgentRunFailureMarker.tsx](../../client/src/features/missions/components/AgentRunFailureMarker.tsx)
 - [AgentRuntimeSelector.tsx](../../client/src/features/missions/components/AgentRuntimeSelector.tsx)
+- [AgentSessionIndicators.tsx](../../client/src/features/missions/components/AgentSessionIndicators.tsx)
 - [AgentSpecDraftCard.tsx](../../client/src/features/missions/components/AgentSpecDraftCard.tsx)
+- [AgentSubagentsCard.tsx](../../client/src/features/missions/components/AgentSubagentsCard.tsx)
 - [AgentThinkingHalo.tsx](../../client/src/features/missions/components/AgentThinkingHalo.tsx) · [test](../../client/src/features/missions/components/__tests__/AgentThinkingHalo.test.tsx)
 - [AgentTierChip.tsx](../../client/src/features/missions/components/AgentTierChip.tsx)
 - [AgentToolbarSelector.tsx](../../client/src/features/missions/components/AgentToolbarSelector.tsx)
@@ -486,6 +488,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [AgentChatContext.tsx](../../client/src/features/missions/context/AgentChatContext.tsx) · [test](../../client/src/features/missions/context/AgentChatContext.test.tsx)
 - [AgentWorkspaceContext.tsx](../../client/src/features/missions/context/AgentWorkspaceContext.tsx) · [test](../../client/src/features/missions/context/__tests__/AgentWorkspaceContext.test.tsx)
 - [MinimizedChatsContext.tsx](../../client/src/features/missions/context/MinimizedChatsContext.tsx) · [test](../../client/src/features/missions/context/__tests__/MinimizedChatsContext.test.tsx)
+- [MissionSessionsContext.tsx](../../client/src/features/missions/context/MissionSessionsContext.tsx) · [test](../../client/src/features/missions/context/__tests__/MissionSessionsContext.test.tsx)
 - [MissionSplitViewsContext.tsx](../../client/src/features/missions/context/MissionSplitViewsContext.tsx)
 - [MissionWindowsContext.tsx](../../client/src/features/missions/context/MissionWindowsContext.tsx) · [test](../../client/src/features/missions/context/__tests__/MissionWindowsContext.test.tsx)
 
@@ -500,10 +503,12 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [agent-context-palette.ts](../../client/src/features/missions/lib/agent-context-palette.ts) · [test](../../client/src/features/missions/lib/__tests__/agent-context-palette.test.ts)
 - [agent-refs.ts](../../client/src/features/missions/lib/agent-refs.ts) · [test](../../client/src/features/missions/lib/__tests__/agent-refs.test.ts)
 - [mission-search.ts](../../client/src/features/missions/lib/mission-search.ts) · [test](../../client/src/features/missions/lib/__tests__/mission-search.test.ts)
+- [mission-sessions.ts](../../client/src/features/missions/lib/mission-sessions.ts) · [test](../../client/src/features/missions/lib/__tests__/mission-sessions.test.ts)
 - [mission-split-layout.ts](../../client/src/features/missions/lib/mission-split-layout.ts) · [test](../../client/src/features/missions/lib/__tests__/mission-split-layout.test.ts)
 - [mission-view-state.ts](../../client/src/features/missions/lib/mission-view-state.ts)
 - [mission-window-controller.ts](../../client/src/features/missions/lib/mission-window-controller.ts) · [test](../../client/src/features/missions/lib/__tests__/mission-window-controller.test.ts)
 - [mission-windows.ts](../../client/src/features/missions/lib/mission-windows.ts) · [test](../../client/src/features/missions/lib/__tests__/mission-windows.test.ts)
+- [subagent-result.ts](../../client/src/features/missions/lib/subagent-result.ts) · [test](../../client/src/features/missions/lib/__tests__/subagent-result.test.ts)
 
 ## client/src/features/plugins/lib
 
@@ -600,6 +605,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [RuntimeRetention.tsx](../../client/src/features/settings/components/RuntimeRetention.tsx) · [test](../../client/src/features/settings/components/__tests__/RuntimeRetention.test.tsx)
 - [RuntimeRolePrompts.tsx](../../client/src/features/settings/components/RuntimeRolePrompts.tsx) · [test](../../client/src/features/settings/components/__tests__/RuntimeRolePrompts.test.tsx)
 - [RuntimeSteering.tsx](../../client/src/features/settings/components/RuntimeSteering.tsx) · [test](../../client/src/features/settings/components/__tests__/RuntimeSteering.test.tsx)
+- [SubagentsSettingsSection.tsx](../../client/src/features/settings/components/SubagentsSettingsSection.tsx) · [test](../../client/src/features/settings/components/__tests__/SubagentsSettingsSection.test.tsx)
 - [TerminalSettingsSection.tsx](../../client/src/features/settings/components/TerminalSettingsSection.tsx)
 
 ## client/src/features/settings/components/pickers
@@ -1098,6 +1104,35 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [agent-runtime-verification-log.ts](../../server/modules/agent-runtime/runtime/agent-runtime-verification-log.ts)
 - [agent-runtime-verification-suggestions.ts](../../server/modules/agent-runtime/runtime/agent-runtime-verification-suggestions.ts) · [test](../../server/modules/agent-runtime/runtime/agent-runtime-verification-suggestions.test.ts)
 
+## server/modules/agent-sessions
+
+- [index.ts](../../server/modules/agent-sessions/index.ts)
+- [ports.ts](../../server/modules/agent-sessions/ports.ts)
+
+## server/modules/agent-sessions/adapters
+
+- [host-process.ts](../../server/modules/agent-sessions/adapters/host-process.ts)
+- [http.ts](../../server/modules/agent-sessions/adapters/http.ts)
+- [rpc-client.ts](../../server/modules/agent-sessions/adapters/rpc-client.ts)
+
+## server/modules/agent-sessions/application
+
+- [session-event-pump.ts](../../server/modules/agent-sessions/application/session-event-pump.ts)
+
+## server/modules/agent-sessions/domain
+
+- [availability.ts](../../server/modules/agent-sessions/domain/availability.ts)
+- [errors.ts](../../server/modules/agent-sessions/domain/errors.ts)
+- [host-state.ts](../../server/modules/agent-sessions/domain/host-state.ts)
+- [projection.ts](../../server/modules/agent-sessions/domain/projection.ts)
+- [protocol.ts](../../server/modules/agent-sessions/domain/protocol.ts)
+- [subagent-policy.ts](../../server/modules/agent-sessions/domain/subagent-policy.ts)
+
+## server/modules/agent-sessions/runtime
+
+- [core-sessions-availability.ts](../../server/modules/agent-sessions/runtime/core-sessions-availability.ts)
+- [session-host-registry.ts](../../server/modules/agent-sessions/runtime/session-host-registry.ts)
+
 ## server/modules/agents/runtime
 
 - [agent-catalog.ts](../../server/modules/agents/runtime/agent-catalog.ts)
@@ -1309,10 +1344,14 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [agent-fence-promotion.ts](../../server/modules/missions/runtime/agent-fence-promotion.ts)
 - [agent-input-store.ts](../../server/modules/missions/runtime/agent-input-store.ts) · [test](../../server/modules/missions/runtime/agent-input-store.test.ts)
 - [agent-operator-prompt.ts](../../server/modules/missions/runtime/agent-operator-prompt.ts) · [test](../../server/modules/missions/runtime/agent-operator-prompt.test.ts)
+- [agent-session-store.ts](../../server/modules/missions/runtime/agent-session-store.ts)
 - [agent-spec-framing.ts](../../server/modules/missions/runtime/agent-spec-framing.ts) · [test](../../server/modules/missions/runtime/agent-spec-framing.test.ts)
 - [agent-steering.ts](../../server/modules/missions/runtime/agent-steering.ts) · [test](../../server/modules/missions/runtime/agent-steering.test.ts)
 - [agent-tier.ts](../../server/modules/missions/runtime/agent-tier.ts)
+- [core-session-runner.ts](../../server/modules/missions/runtime/core-session-runner.ts) · [test](../../server/modules/missions/runtime/core-session-runner.test.ts)
+- [mission-core-sessions.ts](../../server/modules/missions/runtime/mission-core-sessions.ts) · [test](../../server/modules/missions/runtime/mission-core-sessions.test.ts)
 - [mission-run-notify.ts](../../server/modules/missions/runtime/mission-run-notify.ts) · [test](../../server/modules/missions/runtime/mission-run-notify.test.ts)
+- [mission-session-projector.ts](../../server/modules/missions/runtime/mission-session-projector.ts) · [test](../../server/modules/missions/runtime/mission-session-projector.test.ts)
 
 ## server/modules/project-settings
 

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.60.0",
+  "version": "2.62.0",
   "license": "MIT",
   "repository": {
     "type": "git",

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 ────────────────────────────────────────────────────────────