specrails-desktop 2.61.0 → 2.63.0

package/docs/internals/agent-sessions.md

@@ -0,0 +1,157 @@
+# Core agent sessions in Desktop
+
+Specrails Core runs conversational agent work as **resident sessions**: one
+provider process per conversation that survives between turns, owns its
+sub-agents and records everything in a durable journal. Desktop hosts that
+runtime, projects its events into its own tables and renders them. This page is
+the map for that split. The OpenSpec change
+[`core-agent-sessions-host`](../../openspec/changes/core-agent-sessions-host/design.md)
+holds the decisions; Core's side is documented in Core's `docs/agent-sessions/`.
+
+## Who owns what
+
+| Concern | Owner |
+| --- | --- |
+| Provider processes, provider frames, sub-agent lifecycle, steering, interrupt | Core drivers (Claude stream-json, Codex app-server) |
+| Usage normalisation (per-turn deltas, billed vs estimated cost) | Core |
+| Durable journal `~/.specrails/sessions/<scope>/sessions.sqlite` | Core (single writer per scope) |
+| Host supervision (one host per scope), protocol client, generic projection | Desktop [`server/modules/agent-sessions`](../../server/modules/agent-sessions/README.md) |
+| Surface tables, accounting rows, WebSocket events, UI | Desktop surfaces (missions today) |
+| Queue, receipts, MCP capability, tiers, titles, PR/rail cards | Desktop product rules (unchanged) |
+
+Desktop never interprets provider frames and never branches on provider ids:
+it relies on the driver capabilities Core declares in `initialize`.
+
+## Scopes and hosts
+
+A scope is a project slug, or `global` for missions without a pinned project.
+Desktop starts `specrails-core runtime host --stdio --scope <scope>` lazily on
+the first session of that scope ([`CoreHostLauncher`](../../server/modules/agent-sessions/adapters/host-process.ts))
+and supervises it in the [`SessionHostRegistry`](../../server/modules/agent-sessions/runtime/session-host-registry.ts):
+
+- pings with a timeout; unexpected exits restart with capped backoff;
+- after a restart, tracked sessions are resumed and replayed from their cursors;
+- repeated failures mark the scope `degraded`: new turns use the legacy
+  transport and the mission shows a notice with Retry;
+- causes a restart cannot fix degrade at once: another host owns the journal
+  (`journal_locked`), the protocol does not match, or Core lacks the host;
+- removing a project stops its host; app shutdown sends `host.shutdown`, then
+  tree-kills.
+
+## Turns: the runner seam
+
+Missions run turns through `nativeLiveSessionRunner(adapter) ?? runAiCliInvocation`.
+[`createCoreSessionRunner`](../../server/modules/missions/runtime/core-session-runner.ts)
+is a third implementation of that contract. [`MissionCoreSessions.prepareTurn`](../../server/modules/missions/runtime/mission-core-sessions.ts)
+selects it when the scope is available and Core lists a driver for the
+conversation's provider. The runner opens or resumes the session, sends the
+prompt as one input, maps user-turn events to `AdapterEvent`s, delivers steer
+through `session.send`, and returns Core's normalised usage. Stop goes through a
+`TurnHandle` (`session.interrupt`); deleting a mission calls `session.close`.
+
+MCP: each turn mints a capability and rewrites the conversation's capability
+file; the bridge re-reads it per request, so a resident provider always presents
+the current turn's capability. The capability outlives the turn while
+background work may still call Specrails tools, until the next turn rotates it
+or Core retires the process. Structured MCP specs include the Specrails bridge,
+external servers and app-installed plugin servers.
+
+## Projection
+
+```
+Core journal ──session.event──▶ SessionEventPump ──ProjectionOp[]──▶ ProjectionSink (surface)
+                (seq, dedupe,      (domain/projection.ts,             one transaction:
+                 gap fill)          pure reducer)                      rows + cursor, then WS
+```
+
+- [`SessionEventPump`](../../server/modules/agent-sessions/application/session-event-pump.ts)
+  applies each `(sessionId, seq)` once and in order; gaps and `session.lagged`
+  are filled from `session.events`. On attach it rebuilds in-memory state up to
+  the sink cursor without re-applying.
+- [`MissionSessionProjector`](../../server/modules/missions/runtime/mission-session-projector.ts)
+  is the missions sink. It persists what happens outside user turns: sub-agents
+  (`agent_subagents`) and their output (`agent_subagent_events`), resident phase
+  and cursor (`agent_session_cursors`), and continuation turns as messages with
+  `turn_origin` `subagent`/`system` plus invocations with `origin`. User turns
+  are settled by the mission manager.
+- Continuation turns get a deterministic invocation id, so replay never records
+  a turn twice. `POST /api/agent/conversations/:id/session/rebuild` resets the
+  derived rows and replays the journal silently (see the
+  [API reference](api-reference.md)).
+
+## Sub-agent policy
+
+[`resolveSubagentPolicy`](../../server/modules/agent-sessions/domain/subagent-policy.ts)
+maps `(surface, project setting, app setting)` to `policy.subagents`. A
+conversation with a project follows the project's "Allow sub-agents" setting.
+A conversation without a project follows the app setting. Both default to off.
+Implement pipelines are not a surface, so they never resolve a policy. The
+composition root wires the resolver into `MissionCoreSessions`. Settings
+routes call `ProjectRegistry.notifySettingsChanged`, and
+`MissionCoreSessions.refreshSubagentPolicy` then sends the complete policy to
+each open session of that scope. Core's `session.update` replaces the policy as
+a whole and ignores unchanged configurations, so the resident process is not
+restarted for nothing. A session with running sub-agents reports the change as
+deferred, and the mission offers "Stop agents and apply now". If Core rejects
+a policy with `policy_unenforceable`, the mission shows a localized error that
+names the provider and the setting.
+
+## Sub-agent runtime (who launches them)
+
+The hybrid runtime decides who launches sub-agents once the policy allows them.
+[`resolveSubagentRuntime`](../../server/modules/agent-sessions/domain/subagent-policy.ts)
+maps the "Run sub-agents with" choice (project setting `subagentRuntime`, or the
+app setting for missions without a project), the mission's provider and the
+Core capabilities to `policy.subagentRuntime`:
+
+| Choice | Mission provider | Runtime sent to Core |
+| --- | --- | --- |
+| `null` (same as the mission agent) | any | `{ mode: 'native' }` |
+| provider P, model M, effort E | P | `{ mode: 'native', model?, effort? }`. Only overrides the driver declares through `capabilities.subagentModel` / `subagentEffort` are sent (Claude: model only, Codex: both) |
+| provider P, model M, effort E | not P | `{ mode: 'delegated', driver: P, model: M, effort? }` |
+
+When Core lacks `capabilities.delegation`, or P is not one of its drivers, the
+mission stays native and receives an `agent_session_notice` with code
+`subagents.delegation_unsupported` or `subagents.driver_unavailable` and the
+`provider`. A setting change refreshes open sessions like the policy does.
+
+In a delegated session Core disables the provider's own sub-agent tool and the
+mission agent launches sub-agents through the Specrails MCP: `specrails_mission`
+actions `subagent_start`, `subagent_wait`, `subagent_list` and `subagent_stop`
+call `AgentChatManager.delegateSubagent` / `waitSubagents` / `stopSubagents`,
+which map to Core's `session.delegate`, `session.waitSubagents` and
+`session.stopSubagents`. `MissionCoreSessions` adds a short system prompt
+addendum that tells the agent how to delegate. Each delegated sub-agent is a
+Core child session (its own process, no shared prompt cache), mirrored into the
+mission's tree with `delegated: { driver, model }`; results nobody waited for
+arrive as a system continuation turn. Its usage is billed separately
+(`subagent.usage` with `billing: 'separate'`): the projector records it as its
+own invocation (`core-subagent:<conversation>:<subagent>:<seq>`, origin
+`subagent`, the child's provider) on top of the parent's cost. Migration 34
+adds `delegated_driver` / `delegated_model` to `agent_subagents`.
+
+## UI
+
+The client keeps session state in [`MissionSessionsContext`](../../client/src/features/missions/context/MissionSessionsContext.tsx)
+over a pure reducer ([`mission-sessions.ts`](../../client/src/features/missions/lib/mission-sessions.ts)).
+Each launch renders as a compact line under the message whose `core_turn_id`
+started it. `agent_done` carries `coreTurnId`, so the anchor exists without a
+reload. A launch whose reply has no text sits after the message that preceded
+it. The line is expanded while agents work and folds once they finish. The
+sidebar keeps a live dot for missions with background work. Details are in the
+[missions feature guide](../../client/src/features/missions/README.md).
+
+## Rollout
+
+`SPECRAILS_CORE_SESSIONS` (`auto` by default, `on` or `off`, see
+[configuration](configuration.md)) gates the Core path. It only takes effect
+when the selected Core advertises `sessions` and its session contract matches
+([`core-compat.ts`](../../server/core-compat.ts)). Otherwise, missions keep
+their legacy transports.
+
+## Verify
+
+```bash
+npx vitest run server/modules/agent-sessions server/modules/missions
+npm run test --prefix client -- src/features/missions
+```

package/docs/internals/api-reference.md

@@ -93,8 +93,8 @@ Example — register a project that uses both Claude and Gemini:
 
 | Method | Path | Notes |
 |--------|------|-------|
-| `GET` | `/settings` | App-wide settings |
-| `PUT` | `/settings` | Update any subset of `{ port?, specrailsTechUrl?, costAlertThresholdUsd? }` |
+| `GET` | `/settings` | App-wide settings, including `allowSubagents` (default `false`) and `subagentRuntime` (default `null`) |
+| `PUT` | `/settings` | Update any subset of `{ port?, specrailsTechUrl?, costAlertThresholdUsd?, allowSubagents?, subagentRuntime? }`. `subagentRuntime` is `null` (same as the mission agent) or `{ provider, model, effort: string \| null }` for missions without a project; an invalid value returns `400`. `allowSubagents` is the app-wide "Allow sub-agents" setting for missions without a project. It must be a boolean (otherwise `400` and nothing is written), and a change refreshes the policy of open sessions |
 | `GET` | `/budget` | App-wide budget config |
 | `PATCH` | `/budget` | Update the app-wide daily budget |
 | `GET` | `/theme` | Current UI theme (defaults to `specrails`) |
@@ -149,6 +149,35 @@ Proxies the external specrails-tech agents service (base URL from `desktop_setti
 | `POST` | `/agents` | Create an agent entry |
 | `PATCH` | `/agents/:id` | Update |
 
+### Missions: Core agent session sub-agents (`/api/agent/*`)
+
+These routes are available when a mission ran in a Core agent session (`SPECRAILS_CORE_SESSIONS`, see [agent sessions](../../server/modules/agent-sessions/README.md)). Rows are Desktop's rebuildable projection of Core's session journal.
+
+| Method | Path | Notes |
+|--------|------|-------|
+| `GET` | `/agent/active-turns` | Reconnect snapshot. Besides `turns`, the response includes `sessions[]`: `{ conversationId, residentPhase, processAlive, liveSubagents, subagents }` for missions with background work. |
+| `GET` | `/agent/conversations/:id` | Includes `session`: `{ residentPhase, processAlive, liveSubagents, subagents }`, or `null` when the mission never ran in Core. |
+| `GET` | `/agent/conversations/:id/subagents` | `{ subagents, session }`. Each sub-agent has id, parent, kind, agent type, description, phase (`running`/`idle`/`failed`/`stopped`/`killed`/`interrupted`), reason, restarts, launching Core turn, timestamps, usage, tool uses, duration and result summary. Sub-agents Specrails launched on another provider carry `delegated: { driver, model }`; their usage is recorded as separate `subagent` invocations. |
+| `GET` | `/agent/conversations/:id/subagents/:subagentId/events?after=&limit=` | Paged sub-agent transcript `{ events: [{ seq, channel, delta?, tool?, createdAt }], hasMore }`. `limit` is 1–1000. |
+| `POST` | `/agent/conversations/:id/subagents/stop` | Body `{ subagentIds? }` (all when omitted). Returns `{ stopped }`; `502` when the session host is unavailable. |
+| `POST` | `/agent/conversations/:id/session/rebuild` | Operator repair: replays the mission's Core journal into its sub-agent rows, events, resident state and cursor. Turns already recorded as messages/invocations are not duplicated; the replay is silent, then clients receive `agent_resident_state` and one `agent_subagent` per row. Returns `{ lastSeq, subagents }`; `409` while a turn runs or when the mission has no Core session; `502` when the host is unavailable. |
+
+| `GET` | `/agent/session-hosts` | `{ hosts: [{ scope, status, detail, code }] }`: one entry per Core session host scope (project slug or `global`). `code` explains a degraded scope (`journal_locked`, `protocol_mismatch`, `driver_unavailable`). |
+| `POST` | `/agent/session-hosts/:scope/retry` | Starts a degraded scope again. Returns `{ host }`, or `502` with `{ error, host }` when it is still unavailable. |
+
+WebSocket events for these missions:
+
+- `agent_resident_state`, `agent_subagent`, `agent_subagent_event`;
+- `agent_turn_started` / `agent_turn_done` for turns Core starts after sub-agents finish (origin `subagent` or `system`);
+- `agent_session_updated` (`applied` / `deferred`) and `agent_session_notice` (`level`, `code`, `message`, optional `scope`). The notice covers provider warnings such as `policy.subagent_blocked`, and a turn that fell back to the legacy transport (`host_degraded`, `journal_locked`);
+- `agent_sessions_host` (app-level, no `projectId`): `{ scope, status, detail, code }` on every host status change.
+
+Background turns also stream `agent_stream`, `agent_tool` and `agent_tool_result` with a `turnId`.
+
+`agent_session_notice` with code `subagents.delegation_unsupported` or `subagents.driver_unavailable` (and `provider`) says a "Run sub-agents with" choice cannot be honoured, so the mission stays native. In delegated missions the agent uses the `specrails_mission` MCP actions `subagent_start`, `subagent_wait`, `subagent_list` and `subagent_stop`.
+
+`agent_error` may carry `code` and `provider` for failures the client explains in the user's language. One example is `policy_unenforceable`, sent when a provider cannot honour "Allow sub-agents: off".
+
 ### Webhooks
 
 | Method | Path | Notes |
@@ -405,8 +434,10 @@ Gated by `requireBrowserCaptureEnabled` — returns 404 when the feature is disa
 
 | Method | Path | Notes |
 |--------|------|-------|
-| `GET` | `/settings` | Project settings |
-| `PATCH` | `/settings` | Update |
+| `GET` | `/settings` | Project settings, including `allowSubagents` (default `false`) and `subagentRuntime` (default `null`) |
+| `PATCH` | `/settings` | Update. `allowSubagents` must be a boolean; `subagentRuntime` is `null` or `{ provider, model, effort: string \| null }` (strictly validated). A change to either refreshes the sub-agent policy of the project's open agent sessions. A change to `worktreeEnvPassthrough` (names only) re-warms the project's login-shell recovery |
+| `GET` | `/env-passthrough/status` | Value-free resolution status of every configured `worktreeEnvPassthrough` name: `{ loginShellRecovery, timeoutMs, checking, names: [{ name, status, shell, checkedAt, exitCode }] }`. `status` is `inherited`, `recovered`, `not-defined`, `probe-timeout`, `probe-failed`, or `pending` for a name never checked. Probes first only when a missing name has no valid cached result. Never returns values |
+| `POST` | `/env-passthrough/recheck` | Probe the login shell now (asynchronously, `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS`, default 10 s), then return the same payload as the status route |
 | `GET` | `/terminal-settings` | Per-project terminal overrides |
 | `PATCH` | `/terminal-settings` | Update |
 | `GET` | `/agent-models` | Per-agent model overrides |

package/docs/internals/configuration.md

@@ -175,17 +175,58 @@ shell when a GUI launch does not supply it. A zsh login shell reads `~/.zprofile
 adding it to tracked repository files. Windows uses its inherited environment.
 
 Recovered values stay in a project-owned in-memory overlay, not the server's global
-environment, SQLite or runtime snapshots. Each project's lookup cache expires after
-30 seconds, including failed/empty results, so a repaired profile or rotated shell
-credential can be picked up without restarting Desktop. Removing a configured name
-drops its recovered value immediately. A missing value remains absent: Desktop never
-substitutes a dummy credential or treats a blocked package-manager command as passed.
+environment, SQLite or runtime snapshots. Removing a configured name drops its
+recovered value and status immediately. A missing value remains absent: Desktop
+never substitutes a dummy credential or treats a blocked package-manager command as passed.
+
+#### Login-shell recovery and resolution status
+
+The login-shell probe runs `$SHELL -l -i -c 'printf …'` and reads only the requested
+names from a block bracketed by sentinels. Text a profile prints outside that block
+(banners, instant prompts) is ignored. A complete block is accepted **whatever the
+shell's exit status**; a non-zero exit is kept only as a diagnostic.
+
+- **Asynchronous warm cache.** Desktop probes in the background when a project opens,
+  when its configured names change, and about a minute before a successful result
+  expires. The probe never blocks the server's event loop. Its budget is 10 seconds by
+  default; set `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS` (milliseconds, capped at 120000) to
+  change it. The refresh stops when the project is removed.
+- **Spawn-time reads.** Rail jobs, loop steps and retained runtime controls read the
+  warm cache synchronously. Only a name that was never checked (or whose success
+  expired) gets the short synchronous fallback, bounded at 1.5 seconds. When that
+  fallback fails, the asynchronous probe is started immediately so the next spawn can
+  use its result.
+- **Lifetimes.** Recovered values stay valid for 10 minutes and are refreshed before
+  then; a failed refresh keeps a still-valid value. Failed or empty lookups are retried
+  after 30 seconds. Changing `SHELL`, `HOME` or `ZDOTDIR` discards cached results.
+
+Each configured name has a value-free status, kept in the owning project's memory
+together with the shell used and the time of the check:
+
+| Status | Meaning |
+|--------|---------|
+| `inherited` | Present in the environment Desktop started with. |
+| `recovered` | Read from the login shell. |
+| `not-defined` | The probe succeeded but the shell does not export the name (also used on Windows, where there is no login-shell recovery). |
+| `probe-timeout` | The shell did not print the block within the budget. |
+| `probe-failed` | The shell could not be started, or its output had no complete sentinel block. |
+
+`GET /api/projects/:projectId/env-passthrough/status` returns these statuses
+(`pending` appears only for a name that has never been checked), and
+`POST /api/projects/:projectId/env-passthrough/recheck` probes immediately. The
+Project Settings environment card shows them as chips with a **Check again** action,
+and the MCP `specrails_env` tool exposes them through `get`, `status` and `recheck`.
+When a rail, loop or queued job starts with a configured name unresolved, its run log
+receives one aggregated warning, for example
+`[environment] NODE_AUTH_TOKEN not available (probe-timeout); configure it in the login shell or launch from a terminal`.
+Statuses, logs and MCP output contain names and states only, never values.
 
 A few env vars are read directly by the app. The two most useful operational ones:
 
 | Variable | Description |
 |----------|-------------|
 | `SPECRAILS_TECH_URL` | Fallback specrails-tech base URL. Resolution order is the `specrails_tech_url` app setting **first**, then this env var, then `http://localhost:3000` — so a stored app setting takes precedence over this var. |
+| `SPECRAILS_LOGIN_SHELL_TIMEOUT_MS` | Budget in milliseconds for the asynchronous login-shell probe that recovers configured project environment names (default `10000`, capped at `120000`). The synchronous cold fallback keeps its 1.5 s bound. See [Login-shell recovery](#login-shell-recovery-and-resolution-status). |
 | `WM_ZOMBIE_TIMEOUT_MS` | Zombie-job detection timeout in milliseconds (default `1800000` = 30 min). This is a stuck-job watchdog, **not** a hard "kill after N minutes" cap. |
 
 ### Provider rollback gates
@@ -205,6 +246,40 @@ its native key/config, and Kimi via `kimi login` or user-managed
 `~/.kimi-code/config.toml`. See [Kimi](../kimi.md), [Codex](../codex.md), and
 [Gemini](../gemini.md).
 
+### Core agent sessions (rollout)
+
+| Variable | Effect |
+|----------|--------|
+| `SPECRAILS_CORE_SESSIONS` | `auto` (default) uses Core's agent session host (`specrails-core runtime host`) when the selected Core advertises the `sessions` capability and its session contract is compatible. `on` behaves like `auto` but is reported as forced. `off` keeps conversational features on their legacy transports. It cannot enable sessions on a Core that lacks them, and Desktop logs the reason. |
+
+With sessions enabled, Desktop runs one Core host per project, plus one for
+project-less missions. Session journals live in
+`~/.specrails/sessions/<project>/sessions.sqlite`, owned by Core. Desktop
+stores only a rebuildable projection. See
+[agent sessions](../../server/modules/agent-sessions/README.md).
+
+**Allow sub-agents** is a setting, not a flag, and it is off by default. The
+project setting `allowSubagents` (`config.allow_subagents`) applies to that
+project's conversational agents (missions, explore, refinements). The app
+setting (`agent_allow_subagents` in `desktop_settings`) covers missions without
+a project. Implement pipelines never read it. Desktop sends the resolved value
+to Core as `policy.subagents`. Core enforces it through the provider switch, and
+it also stops any sub-agent a provider starts anyway. A change reaches open
+sessions immediately: idle sessions apply it, and sessions with running
+sub-agents report it as deferred. The setting is read-only over the Specrails
+MCP, so an agent cannot grant itself sub-agents.
+
+**Run sub-agents with** chooses who launches them. The project setting
+`subagentRuntime` (`config.subagent_runtime`, JSON) and the app setting
+(`agent_subagent_runtime` in `desktop_settings`) hold `null` (the default: the
+mission agent's own provider launches native sub-agents) or
+`{ provider, model, effort }`. Missions on that provider keep native sub-agents
+with that model and effort; missions on another provider get sub-agents that
+Core launches on the chosen provider (delegated), at the cost of a cold start
+and no shared prompt cache. The UI asks for confirmation before leaving the
+default. The setting is read-only over the Specrails MCP. See
+[agent sessions](agent-sessions.md#sub-agent-runtime-who-launches-them).
+
 For the full catalogue of feature flags and kill switches (`SPECRAILS_*` server gates, `VITE_FEATURE_*` client flags, `SPECRAILS_CODEX_BETA`, `SPECRAILS_GEMINI_BETA`, `SPECRAILS_EXPLORE_*`), see [../customizing.md](../customizing.md#environment-variables).
 
 ---

package/docs/internals/core-runtime-updates.md

@@ -13,15 +13,22 @@ framework is rejected rather than silently replacing an update.
 
 ## Persistence and publication
 
-The release bundle pins Core 6.4.0 in `desktop-release.yml` and
+The release bundle pins Core 6.5.0 in `desktop-release.yml` and
 `scripts/assemble-bundled-core.lock.json`. Core 6 is the Desktop-only engine: it
 publishes integration contract 5.1 (no standalone `update`) and ships only the
 implement and retry workflows (Batch was folded into implement; Desktop no
 longer requires `batch-implement` but stays compatible with Cores that still ship it). Update both pins together and check compatibility against
 the staged published package; retained runs still use their original runtime.
 
-The paired CI checkout uses the immutable Core 6.4.0 release commit
-`aa00781e962a30c22bbcdecc632bc2abcf3c97d2`. Bundle smoke checks use Node 22.22.3,
+`scripts/assemble-bundled-core.mjs` relocates any pnpm virtual store a
+dependency leaks into its tarball (today `@langchain/langgraph-sdk` ships
+`dist/node_modules/.pnpm/…` and imports it by relative path) to
+`<dir>/_pnpm/<entry>`, rewriting the relative imports that cross it, so the
+module still loads while every staged path stays inside the MSI budget
+(`MAX_STAGED_RELATIVE_PATH`, 120 characters).
+
+The paired CI checkout uses the immutable Core 6.5.0 release commit
+`187f9d24533a99fb1f37c7805b3c5b1375040d25`. Bundle smoke checks use Node 22.22.3,
 matching Core's minimum supported Node version and the Desktop release runtime.
 
 Desktop updates retain the complete npm installation, including dependencies,

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,7 +119,7 @@ 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`. 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.
+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.
 

package/docs/internals/safe-pr-review-flow.md

@@ -133,6 +133,21 @@ Both temporary checkouts use non-force cleanup, including after a Git runner exc
   including proofs for historical misplaced links; symlinked destination ancestors confer no
   authority. Registration paths, frozen manifests and Core scope remain unchanged. A failed run
   keeps its old checkout; after updating Desktop, a fresh Relaunch receives the corrected layout.
+- Warm reuse is gated by dependency freshness. Before preparing a new link for a package
+  directory, Desktop compares its dependency inputs in the base checkout and in the worktree: the
+  nearest lockfile found walking up to the Git top level (first of `pnpm-lock.yaml`, `yarn.lock`,
+  `package-lock.json`, `npm-shrinkwrap.json`, `bun.lock`, at the same relative position) and a
+  canonical digest of the `package.json` dependency, devDependency, optionalDependency and
+  peerDependency fields (scripts and other metadata are ignored). If either input differs, or one
+  cannot be read, the directory gets no `node_modules` and the run reports, on the
+  `rail.overlay_degraded` channel, for example
+  `apps/catalog: yarn.lock differs from the base checkout; dependencies will be installed in the worktree`.
+  Core's environment preparation then installs that directory cold from the worktree's own lockfile.
+  This prevents a base checkout on another branch, or behind the remote, from supplying packages
+  the run's code does not declare. Desktop never checks out, pulls or installs anything in the
+  user's checkout to make warm reuse possible. Links already present for a resumed run keep their
+  authentication; the guard only applies when a link is prepared. `SPECRAILS_WORKTREE_NODE_MODULES=false`
+  still disables warm reuse entirely.
 - Per-unit settlement returns structured execution + delivery results. `onLoopRunFinished` receives
   the engine outcome only; commit/status/ref/provenance/push failures cannot rewrite it.
 - Before staging, settlement blocks active OpenSpec change directories introduced relative to

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 1044 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
@@ -842,7 +848,9 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [generate-icons.mjs](../../scripts/generate-icons.mjs)
 - [generate-mobile-types.mjs](../../scripts/generate-mobile-types.mjs)
 - [generate-source-map.mjs](../../scripts/generate-source-map.mjs) · [test](../../scripts/generate-source-map.test.mjs)
+- [module-references.mjs](../../scripts/module-references.mjs) · [test](../../scripts/module-references.test.mjs)
 - [obfuscate-chromium.mjs](../../scripts/obfuscate-chromium.mjs)
+- [paired-core-shards.mjs](../../scripts/paired-core-shards.mjs) · [test](../../scripts/paired-core-shards.test.mjs)
 - [patch-node-pty.mjs](../../scripts/patch-node-pty.mjs) · [test](../../scripts/patch-node-pty.test.mjs)
 - [recover-desktop-channel.mjs](../../scripts/recover-desktop-channel.mjs) · [test](../../scripts/recover-desktop-channel.test.mjs)
 - [release-policy.mjs](../../scripts/release-policy.mjs) · [test](../../scripts/release-policy.test.mjs)
@@ -1098,6 +1106,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 +1346,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/docs/mcp.md

@@ -48,7 +48,7 @@ reading one description. The tools are:
 | `specrails_loops` | Saved loop workflows |
 | `specrails_code` | File discovery, literal content search, bounded line reads, summaries and provenance; AI summary regeneration is capability-gated |
 | `specrails_git` | Repository/branch/worktree information, status, diffs and PR lookup |
-| `specrails_env` | Project environment readiness and environment-file management |
+| `specrails_env` | Project environment readiness and environment-file management; `get`/`status`/`recheck` report each configured name's value-free resolution status |
 | `specrails_support` | Support triage, local diagnostics and specrails-core update workflows |
 | `specrails_setup` | Add-project setup wizard surface |
 | `specrails_analytics` | Per-project spending analytics + budget |

package/docs/platforms/macos.md

@@ -77,6 +77,8 @@ When the app runs without an active bundle (a runtimes-less build, or `npm run d
 
 2. **Login-shell merge (async)** — right after the HTTP server starts listening, `augmentPathFromLoginShell()` spawns `$SHELL -l -i` once (1500 ms timeout) and merges whatever `PATH` that login + interactive shell exposes. This recovers the segments that Volta, nvm, fnm, asdf, etc. add only inside your interactive shell — whatever your `$SHELL` produces, no specific rc file is assumed. On timeout or non-zero exit, the fast-path `PATH` stays in effect and a single warning is logged.
 
+Project environment names configured in Project Settings (for example `NODE_AUTH_TOKEN`) use a separate, per-project login-shell probe with a 10 s budget (`SPECRAILS_LOGIN_SHELL_TIMEOUT_MS`). It runs in the background, never writes to `process.env`, and reports a status per name. See [configuration](../internals/configuration.md#login-shell-recovery-and-resolution-status).
+
 The resolved `PATH` is stored on `process.env.PATH`, so every downstream spawn inherits it (`QueueManager` → provider CLI, `SetupManager` → `npx specrails-core`, `terminalManager` PTYs, etc.).
 
 ## Broken-symlink detection

package/docs/platforms/windows-parity.md

@@ -6,8 +6,8 @@ This audit covers the `codex/multi-repo-projects` branch, including mission stee
 
 | Feature | Windows implementation and checks |
 | --- | --- |
-| Installation, native runtimes | Native x64/ARM64 NSIS and MSI builds; embedded WebView2 offline provisioning; bundled Node/Git/core/OpenSpec; staged SQLite and full ConPTY/WinPTY dependency validation. |
-| Desktop updates | Installer-specific Tauri targets keep NSIS and MSI separate. Missing, empty or ambiguous artifact/signature pairs fail manifest generation. Generic NSIS entries remain for older clients. Publication is serialized, and previous download installers are retained until the remote manifest matches the new release. |
+| Installation, native runtimes | Native x64/ARM64 NSIS builds; WebView2 provisioning through the embedded bootstrapper; bundled Node/Git/core/OpenSpec; staged SQLite and full ConPTY/WinPTY dependency validation. |
+| Desktop updates | NSIS-specific and generic Tauri targets both reference the NSIS installer; earlier MSI installs fall back to the generic entry and the NSIS installer removes the WiX installation. Missing, empty or ambiguous artifact/signature pairs fail manifest generation. Publication is serialized, and previous download installers are retained until the remote manifest matches the new release. |
 | Startup and project catalog | Recover the actual Windows profile rather than inventing `C:\Users\Default`; SQLite catalog/repository IDs reopen under the same Unicode/spaced profile. |
 | Projects and multi-repo | Repository membership and canonical identity use real paths; junction and case aliases cannot add the same repository twice. Shared backlog and per-repository jobs retain their existing regression coverage. |
 | Core setup and updates | Offline assembly from the shipped core; preserve and restore the previous active framework if Windows junction replacement fails. Installed-package smoke waits for the real workspace marker. |
@@ -28,7 +28,7 @@ This audit covers the `codex/multi-repo-projects` branch, including mission stee
 
 `.github/workflows/windows-parity.yml` runs a `windows-parity` job on `windows-latest` (x64) for every pull request and push to `main`, adding `windows-11-arm` on the `main` pushes. It installs dependencies, checks TypeScript, runs release/PTY helper regression tests, native filesystem/process tests (retried once, they drive real processes), the application build, native host build/tests, and four real native fixtures: WebView2 capture/selection, authentication popups, mission window handoff, and browser multiwindow transfer/parking. It is deliberately a separate workflow from `ci.yml`: `release.yml` waits for CI only, so a slow or flaky Windows run never delays the release PR, while Desktop Release still builds and installs on Windows before publication. The jsdom client suite is not repeated on Windows; it runs on Linux in CI. The bundled-core matrix in `ci.yml` exercises Windows junction/copy relocation for providers.
 
-`.github/workflows/desktop-release.yml` builds the real installers and runs `scripts/smoke-windows-installers.ps1` before publishing artifacts. For each NSIS and MSI package, the script installs into a temporary path containing spaces and drives `scripts/smoke-installed-windows.mjs` with the installed Node runtime. The driver uses an isolated user profile and tests:
+`.github/workflows/desktop-release.yml` builds the real installers and runs `scripts/smoke-windows-installers.ps1` before publishing artifacts. The script fails on any MSI bundle, then installs the NSIS package into a temporary path containing spaces and drives `scripts/smoke-installed-windows.mjs` with the installed Node runtime. The driver uses an isolated user profile and tests:
 
 1. The installed pkg sidecar boots with bundled resources and authenticates API access.
 2. A temporary Git repository is registered and core assembly completes offline.
@@ -53,7 +53,7 @@ The detachable-window implementation has passed native macOS fixtures locally, i
 
 Before claiming complete Windows parity, record successful x64 and ARM64 CI/release runs and exercise the actual installed UI on supported Windows versions:
 
-- Clean NSIS and MSI installs, in-place upgrades from the previous release, relaunch, tray quit and uninstall. Verify one installation entry and preserved projects/logs.
+- Clean NSIS installs, in-place upgrades from the previous release (including an MSI-installed release migrating through the updater), relaunch, tray quit and uninstall. Verify one installation entry and preserved projects/logs.
 - Native browsing and capture at 100%, 150% and 200% display scaling; resize, maximize, multi-monitor movement, keyboard/clipboard, popup/self-close, and the relevant Okta/SSO tenant. Detach two active missions, minimize main independently, move them between monitors, and reattach into a window with its own open browser; verify both sessions and pending inputs remain intact.
 - Provider authentication and one real mission/rail per enabled provider; steering during a tool call; cancellation; multi-repo integration/checkout with clean and conflicting working trees.
 - Long-running frontend/backend processes, immediate startup failure, stopping nested processes, app quit/update during execution, and persisted logs after restart.