specrails-desktop 2.36.0 → 2.42.2

package/docs/internals/startup-recovery-audit.md

@@ -0,0 +1,58 @@
+# Startup and update recovery audit
+
+Date: 2026-09-05. Branch: `feat/codex-gpt-6-astra`.
+
+The reported symptom was an intermittently disconnected desktop with no visible
+projects after an update or a cold start. Source inspection found several paths
+that produce this symptom without deleting project data. The local sidecar log
+also contains an older project hydration failure (an unavailable provider), but
+does not establish which path caused every reported incident. No SQLite
+corruption was found in that log. User databases were not modified.
+
+## Causes and corrections
+
+| Failure | Correction |
+| --- | --- |
+| Authentication gave up after 20 attempts spaced 300 ms apart; a later healthy server never repaired the cached missing token. | Share bounded token refreshes between failed API authentication and WebSocket reconnects. Refresh a rejected credential and replay the rejected request at most once, preserving its body, headers and cancellation. |
+| Failed initial project requests were treated as a successful empty database. | Preserve the last authoritative catalog and loading state, retry with bounded backoff, and refresh on reconnect, focus and network recovery. |
+| Views opened during a database lock could remain empty after that project recovered. | Retry only explicit `project_unavailable` reads for a bounded window; consume the recovery event in specs, rails, pipeline and mission views to refetch without discarding conversation drafts. Both WebSocket hooks recover after an extended outage. |
+| An older REST response could overwrite a newer WebSocket project list. | Track catalog revisions and discard responses captured before a newer catalog event. A real browser regression reproduced the original failure. |
+| Windows `http://tauri.localhost` could be mistaken for a normal website before the IPC bridge appeared. | Recognize the Tauri virtual hostname when choosing API and WebSocket origins. |
+| The native host treated any response from the authenticated `/api/state` endpoint as proof of readiness and terminated the app after a 30-second timeout. | Verify the public `/api/health` contract over direct IPv4 loopback. Keep a live slow-starting sidecar running and retry readiness; report an actual process exit separately. |
+| Update restart proceeded even when the previous server still occupied port 4200. | Wait for port release, deduplicate restart requests, and report a delayed restart instead of launching into a known conflict. Validate sidecar process identity before termination. |
+| The initial WebSocket catalog contained only successfully hydrated project contexts, unlike REST's persistent registry. | Use the durable catalog for WebSocket initialization and health counts. A registered but temporarily unavailable project returns 503 instead of a misleading 404. |
+| A transient SQLite write lock during project startup prevented that project from loading for the entire process lifetime. | Retry failed DB opens after 1, 2 and 5 seconds, then every 30 seconds while the error remains BUSY/LOCKED. Cancel retries on removal or shutdown; corruption and failures after context construction starts are not blindly retried. |
+| Two startups could read the same old migration version before either obtained SQLite's write lock. | Acquire the write lock with `BEGIN IMMEDIATE` and recheck each version inside the same transaction as its migration and version record. Close failed initialization handles. |
+| A failed legacy `hub.sqlite` rename was logged and ignored, allowing a new empty `desktop.sqlite` to be created. | Fail explicitly and retain the existing data for a later retry; do not replace an inaccessible catalog with an empty one. |
+
+## Validation
+
+- Server/CLI/MCP coverage: 273 files, 7,274 passing tests. Statements 85.45%,
+  branches 77.63%, functions 89.52%, lines 87.83%; all configured thresholds pass.
+- Client coverage: 348 files, 4,335 passing tests. Statements/lines 89.14%,
+  branches 82.87%, functions 74.36%; all configured thresholds pass.
+- Native host: `cargo test --lib --offline`, 20 passing tests covering false
+  health responses, slow readiness, occupied ports, process identity and expected
+  versus unexpected shutdown.
+- `npm run typecheck`, `npm run build`, `npm run check-core-compat` and
+  `git diff --check` pass. The build retains the existing Vite chunk-size advisory.
+- Final Chromium smoke: all three startup/restart/stale-response scenarios pass,
+  with no uncaught page errors.
+
+Total: 11,629 passing automated tests plus the three browser smoke scenarios.
+
+SQLite regressions use temporary databases, including a real WAL write lock and
+two connections sharing a migration. The native tests do not terminate the user's
+server. An installed-app update was not executed as part of this validation.
+
+## Reproducible browser check
+
+Run `node scripts/smoke-startup-recovery.mjs` from the repository root. It bundles
+the actual auth, shared WebSocket and desktop project providers and exercises
+them in Chromium against a temporary loopback fixture. It never opens the
+installed app or a user database. Playwright's Chromium must already be installed;
+`SPECRAILS_SMOKE_BROWSER` can select an existing Chromium executable.
+
+The check covers an eight-second startup, a restarted server with a replacement
+credential, saved project selection, and an old REST response arriving after a
+newer WebSocket catalog. All three scenarios passed after the corrections.

package/docs/mcp.md

@@ -2,25 +2,25 @@
 
 Specrails Desktop can expose itself to **any MCP client** — Claude Desktop,
 Claude Code, Cursor, or your own agent — as a local
-[Model Context Protocol](https://modelcontextprotocol.io) server. Turn it on
-and an external LLM can drive the whole dashboard: list your projects, read and
+[Model Context Protocol](https://modelcontextprotocol.io) server. A connected
+agent can drive the whole dashboard: list your projects, read and
 create specs, launch the AI pipeline, watch jobs settle, inspect analytics, and
-more — through ~18 well-described tools instead of clicking around the UI.
+more — through 22 tools with discoverable action schemas.
 
-> **Just want to get going?** Open **Settings ▸ MCP**, flip **Enable MCP** on,
-> click **Copy client config**, and paste it into your MCP client. By default
-> only **read** actions are allowed; turn on the **Write** / **AI-spawn** /
-> **Destructive** tiers when you want the agent to actually change things or
-> spend money. Everything below is detail for when you need it.
+> **Just want to get going?** Open **Settings ▸ MCP**, click **Copy client
+> config**, and paste it into your MCP client. MCP and all four permission tiers
+> are on by default. Disable **Write**, **AI-spawn**, or **Destructive** there
+> to restrict external clients. Existing disabled settings survive upgrades.
 
 This is the **app talking to an outside agent** — the opposite direction from
 the [Serena plugin](running-pipelines.md#plugins) or
 `codex mcp add`, where Specrails *consumes* an MCP server. Here Specrails *is*
 the server.
 
-The MCP server is **off by default** and entirely local: it listens only on
-loopback (`127.0.0.1`), is authenticated by a token separate from the app's
-master token, and serves nothing until you explicitly enable it in Settings.
+The MCP server is **on by default** and entirely local: it listens only on
+loopback (`127.0.0.1`) and is authenticated by a token separate from the app's
+master token, so nothing off your machine can reach it. You can switch it off
+at any time in Settings — an explicit off stays off across upgrades.
 
 ## What the MCP exposes
 
@@ -28,7 +28,7 @@ When enabled, the server registers a compact catalog of **domain-facade tools**
 plus a few **meta tools**, a set of read-only **resources**, and a self-contained
 **guide** an LLM can read to learn the platform with no prior knowledge.
 
-### Tools (~18)
+### Tools (22)
 
 Each domain is a single tool with an `action` enum, rather than dozens of
 narrow tools — so the catalog stays small and an agent discovers actions by
@@ -37,26 +37,44 @@ reading one description. The tools are:
 | Tool | What it covers |
 |---|---|
 | `specrails_projects` | List / resolve projects; unregister (destructive) |
+| `specrails_context` | Compact live briefing: project/providers, backlog, rails/runs/deliveries, Git/worktrees, blueprint; source and availability per section |
 | `specrails_specs` | The spec/ticket backlog: list, get, create, update, delete, drafts, AI generate, AI-edit, Contract Refine, SMASH, per-ticket spend |
-| `specrails_rails` | Assign tickets to a rail, configure it, and launch the pipeline — rails are dynamic (`create_rail`, up to 12) and `launch_all` starts every ready rail in parallel (worktree-isolated) |
-| `specrails_jobs` | Inspect, stream, and stop pipeline jobs |
+| `specrails_rails` | Configure/launch dynamic rails (`create_rail`, up to 12), inspect PR candidates/review packets; `launch_all` reports outcomes and isolation availability per rail |
+| `specrails_jobs` | Inspect paginated job events, phase breakdowns, queues and background processes; stop jobs |
 | `specrails_chat` | Explore / sidebar chat conversations and turns |
-| `specrails_agents` | Provider-scoped agent profiles and catalog (Claude and Kimi execution; Kimi manual roles only) |
+| `specrails_agents` | Provider-scoped agent profiles and catalog; explicit profiles are validated for the selected provider |
 | `specrails_plugins` | The per-project plugin marketplace (install / verify / uninstall) |
 | `specrails_jira` | The Jira integration (connect, sync, outbox) |
 | `specrails_loops` | Saved loop workflows |
-| `specrails_code` | The code explorer (tree/file/provenance are provider-neutral; AI transforms are capability-gated) |
+| `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_support` | Support triage, local diagnostics and specrails-core update workflows |
 | `specrails_setup` | Add-project setup wizard surface |
 | `specrails_analytics` | Per-project spending analytics + budget |
 | `specrails_settings` | App-level settings |
 | `specrails_watch` | Await the real result of an async (cost-incurring) action |
 | `specrails_guide` | Returns the platform guide — read this first |
-| `specrails_search` | Find the right tool/action for an intent |
-| `specrails_describe` | Full description + input schema for a named tool |
-| `specrails_select_project` | Set an active project so later calls can omit `projectId` |
+| `specrails_search` | Find tools/actions by English or Spanish intent, including current permission previews |
+| `specrails_describe` | Complete nested JSON schema and action tiers; optionally validate proposed arguments without execution |
+| `specrails_select_project` | Set this session's active project so later calls can omit `projectId` |
 
 Almost every domain tool is **project-scoped** and takes a `projectId`. Calling
-`specrails_select_project` first lets later calls omit it.
+`specrails_select_project` first lets later calls omit it. Each external MCP
+session has its own selection. Mission calls default to the conversation's
+project pin; change that pin in the mission UI or use an explicit `projectId`
+for an intentional operation in another project. Selecting an MCP default
+cannot silently override the mission pin.
+
+`specrails_projects` includes registered projects whose databases are temporarily
+unavailable and marks their `available` state. Their absence from the live
+execution registry does not mean the project was deleted. `specrails_context`
+reports unavailable sections explicitly rather than presenting empty data.
+
+For investigation, fetch the relevant context sections, search source text with
+`specrails_code(search)`, and read the returned file ranges. Refresh state after
+mutations and inspect `specrails_rails(review_packet)` before assessing a
+delivery. Context summaries and truncated searches are partial evidence.
 
 ### Resources
 
@@ -77,6 +95,11 @@ app's WebSocket bus. An agent gets the actual outcome by calling
 returns the final result. Don't assume success from the acceptance alone — this
 is spelled out in `specrails_guide`.
 
+For jobs and loop runs, watch checks stored state before waiting; a completed
+run returns immediately even if its completion event preceded the call. Use
+`kind: "loop_run"` with a loop-run id. Timeouts do not establish success or
+failure; inspect `specrails_jobs(get)` or `specrails_loops(run_get)` for evidence.
+
 Provider membership does not bypass capability checks. With Kimi, agentic
 chat/Explore/Quick Launcher/rails/loops without Decider/profiles are
 available, while Quick Spec, AI Edit, Contract Refine, SMASH/Re-SMASH,
@@ -88,37 +111,46 @@ before any mutation.
 
 Every tool declares one tier. The server refuses any tool whose tier is not
 enabled, and the refusal **names the tier the user must turn on** so the agent
-can relay it rather than retrying blindly. The tiers are **opt-in and
-cumulative** — read is always on, the rest are off until you enable them in
-**Settings ▸ MCP**:
+can relay it rather than retrying blindly. The tiers are **on by default and
+opt-out** — read is always on, and the other three are granted on a fresh
+install so a connected assistant can drive the whole app out of the box; untick
+any of them in **Settings ▸ MCP** to restrict clients:
 
 | Tier | Default | What it allows |
 |---|---|---|
 | **Read** | Always on | Queries + resources (list specs, read analytics, inspect jobs) |
-| **Write** | Off | Mutating but non-destructive, non-spawn: create/edit specs, change settings, configure a rail |
-| **AI-spawn** | Off | Actions that spawn an AI CLI and **cost money**: launch a rail, generate a spec, send a chat turn |
-| **Destructive** | Off | Delete data, kill processes, or mutate an external system (e.g. unregister a project, `smash_undo`, Jira writes) |
+| **Write** | On | Mutating but non-destructive, non-spawn: create/edit specs, change settings, configure a rail |
+| **AI-spawn** | On | Actions that spawn an AI CLI and **cost money**: launch a rail, generate a spec, send a chat turn |
+| **Destructive** | On | Delete data, kill processes, or mutate an external system (e.g. unregister a project, `smash_undo`, Jira writes) |
+
+`specrails_specs(commit_draft)` requires AI-spawn when it can append a Contract
+Layer. A fresh direct insert with `contractRefine: false` and no Explore/draft
+ids remains Write. `specrails_describe` can preview the tier for specific
+arguments; its shared-schema validation does not replace action-specific or
+backend state checks.
+
+The split is deliberate: a client you only half-trust can be dropped to
+read-only with three unticks, and **destructive and cost-incurring actions can
+be withheld independently**. A tool's tier is dynamic per action — e.g.
+`specrails_specs(list)` is read while `specrails_specs(delete)` is destructive —
+so the same tool exposes different actions at different trust levels.
 
-The split is deliberate: a client you only half-trust can be left read-only;
-**destructive and cost-incurring actions are opt-in** and never happen by
-accident. A tool's tier is dynamic per action — e.g. `specrails_specs(list)` is
-read while `specrails_specs(delete)` is destructive — so the same tool exposes
-different actions at different trust levels.
+## Setting it up
 
-## Enabling it
+It is already running — the app persists `mcp_enabled` as on and serves
+`/api/mcp` from the first launch, and the scoped token is minted at boot so the
+bridge finds it immediately.
 
 1. Open the app and go to **Settings ▸ MCP**.
-2. Toggle **Enable MCP**. This boots the embedded transport immediately — no
-   app restart. (Behind the scenes it persists `mcp_enabled` and starts serving
-   `/api/mcp`.)
-3. Enable the permission tiers you want (**Write** / **AI-spawn** /
-   **Destructive**). Leave them off to keep the agent read-only.
-4. Click **Copy client config** to grab a ready-to-paste configuration, or
+2. Review the permission tiers (**Write** / **AI-spawn** / **Destructive**).
+   Untick the ones you don't want an external client to have; untick all three
+   to keep the agent read-only.
+3. Click **Copy client config** to grab a ready-to-paste configuration, or
    **Copy token** if your client needs the raw token (for the direct-HTTP path
    below).
 
-Toggling the enable switch off again tears down all open MCP sessions
-immediately.
+Toggling the enable switch off tears down all open MCP sessions immediately;
+toggling it back on boots the transport again — no app restart either way.
 
 ## Connecting a client
 
@@ -213,7 +245,8 @@ codex mcp add specrails -- <bridge command from Settings ▸ MCP>
   (`/api/mcp-admin`) require the request to come from `127.0.0.1`. There is no
   network ingress; an MCP client must run on the same machine.
 - **Tiers, not blanket access.** Even with a valid token, an agent can only do
-  what the enabled tiers allow (read by default). High-risk actions stay opt-in.
+  what the enabled tiers allow. All four are on by default so a fresh install
+  works out of the box; high-risk actions can be withheld per tier at any time.
 - **Loopback is not identity.** The scoped MCP token identifies an external local
   client; it cannot impersonate the embedded Agent Mode by adding tier, project,
   or conversation headers. For each Agent Mode turn, Specrails mints a private,

package/docs/mission-processes.md

@@ -0,0 +1,59 @@
+# Aplicaciones y procesos de las misiones
+
+El agente arranca aplicaciones, servidores de desarrollo y watchers mediante `specrails_jobs(background_start)`. El proceso queda ligado a la misión, al proyecto y al repositorio elegido, y aparece como una pastilla sobre el compositor. En proyectos con varios repositorios, el agente indica `repositoryId` para arrancar cada aplicación en la carpeta correcta.
+
+El comando debe mantener el servidor en primer plano, por ejemplo `npm run dev`. No necesita `nohup` ni un `&` final: Specrails ya se encarga de ejecutarlo en segundo plano y conservar su control.
+
+Antes de lanzar otra copia, el agente consulta `background_list`. El arranque devuelve `pid` y `processId`: este último identifica la ejecución aunque el sistema operativo reutilice el PID más adelante. Aceptar un comando no demuestra que la aplicación esté lista; consultar sus logs para identificar la URL o un error de arranque forma parte de la petición de lanzamiento y no necesita otra confirmación para leerlos.
+
+## Detener una aplicación
+
+La X de la pastilla solicita la parada directamente. Mientras se confirma, aparece «Deteniendo» y el proceso sigue visible. Specrails intenta cerrar el grupo o árbol de procesos, da un plazo a la terminación normal y fuerza la parada si la aplicación no responde. La salida del shell por sí sola no cuenta como aplicación detenida.
+
+Si la petición o la parada falla, la interfaz muestra el error y permite reintentar. Las peticiones repetidas conservan la identidad de la ejecución y no se dirigen a otro proceso que tenga el mismo PID. La interfaz vuelve a consultar el estado durante la parada, al recuperar la conexión y al regresar a la ventana.
+
+Al cerrar un proyecto o Specrails se aplica el mismo cierre de procesos. El servidor espera un plazo limitado para que termine la limpieza antes de salir; la aplicación de escritorio deja margen para esa espera.
+
+## Explorar los logs
+
+Al pulsar el cuerpo de la pastilla se abre el inspector. La X de parada y el botón que abre el inspector son controles separados, también accesibles con el teclado.
+
+El botón **Procesos** del compositor abre el historial de la misión, aunque las pastillas de ejecuciones terminadas ya hayan desaparecido. Permite buscar por comando, carpeta, repositorio, PID o estado. Seleccionar una ejecución abre sus logs; volver al historial conserva la búsqueda. La reconexión y la recarga recuperan este historial del servidor.
+
+El modal muestra comando, carpeta, repositorio, estado, duración y resultado de salida. Incluye:
+
+- Salida estándar y errores, incluso si el proceso todavía no ha escrito un salto de línea.
+- Búsqueda de texto y filtro por `stdout` o `stderr`.
+- Pausa de la actualización y seguimiento de las últimas líneas. Desplazarse hacia arriba desactiva el seguimiento para poder leer.
+- Copia y descarga de la vista filtrada.
+- Avisos de errores de lectura y de truncamiento, con reintento.
+
+Los logs se consultan únicamente mientras el inspector está abierto y actualizándose. Las secuencias de terminal se convierten en texto; no se ejecuta HTML ni se abren enlaces de control incluidos en la salida. Un inspector abierto conserva su última captura aunque desaparezca la pastilla del proceso terminado.
+
+## Retención y alcance
+
+El servidor guarda el historial en `~/.specrails/background-processes.sqlite`, junto al catálogo de proyectos, usando una base separada para el tráfico de logs. Conserva hasta 10.000 líneas de 4.000 caracteres por ejecución, durante 30 días, con un máximo de 1.000 ejecuciones terminadas y 256 MiB de texto retenido en total. Cuando se alcanzan los límites, elimina primero el historial más antiguo. SQLite reutiliza las páginas liberadas; el tamaño del archivo puede superar el texto retenido por sus índices y metadatos.
+
+La captura en memoria mantiene las últimas 2.000 líneas y hasta 32 ejecuciones terminadas durante diez minutos, pero su caducidad no borra el historial persistente. El inspector limita la vista a 2.000 líneas y 512 KiB de texto para mantenerla ágil; indica cualquier truncamiento. La búsqueda dentro del log y su exportación abarcan la vista disponible. MCP devuelve una cola más pequeña para no saturar el contexto del agente, y permite paginar los metadatos del historial con `limit` y `offset`.
+
+Los cambios de estado se guardan en sus transiciones y la salida se escribe en lotes cada 250 ms. El cierre normal de un proceso y de Specrails vacía los lotes pendientes. Un cierre brusco puede perder la última fracción de segundo aún sin escribir; un fallo de almacenamiento se muestra como aviso independiente y permite seguir deteniendo los procesos. Borrar una misión o un proyecto elimina también su historial. Una segunda instancia no puede apropiarse del historial de un servidor de Specrails que siga activo.
+
+Después de reiniciar, las ejecuciones que no habían confirmado su final aparecen como **Desconectadas**. Esto significa que Specrails perdió su supervisión: no demuestra que su proceso del sistema esté detenido. Sus logs siguen siendo consultables, pero la aplicación no intenta señalizar un PID antiguo. Las lecturas y paradas mantienen el aislamiento por misión, proyecto e identidad de ejecución.
+
+Los logs que una versión anterior ya descartó al guardarlos sólo en memoria no pueden recuperarse retrospectivamente.
+
+El cierre controla los grupos o árboles que Specrails ha creado. Aplicaciones que se desasocien deliberadamente y creen un servicio externo requieren la gestión propia de ese servicio. Esta función no sustituye a un supervisor del sistema operativo ni detiene procesos ajenos por coincidir en un puerto.
+
+## Implementación y referencia
+
+`transient-children.ts` mantiene el ciclo de vida y los lotes; `background-process-store.ts` guarda el historial y `background-process-control.ts` encapsula el control del sistema operativo. REST y MCP comparten `background-process-service.ts`. El contexto del cliente reconcilia las ejecuciones y los modales de historial y logs presentan las capturas.
+
+## Puertos de las aplicaciones y conexión de la misión
+
+Specrails escucha su API en `127.0.0.1:4200` por defecto. Otro servidor puede ocupar `[::1]:4200` simultáneamente: comparten el número de puerto, pero pertenecen a familias de direcciones diferentes. Por eso el proxy de desarrollo, la autenticación y el WebSocket usan IPv4 explícito para llegar a Specrails y evitar que un `localhost` ambiguo devuelva el HTML de un proyecto.
+
+`SPECRAILS_DEV_SERVER_PORT` configura la API de desarrollo, con `SPECRAILS_PORT` como alternativa. `SPECRAILS_DEV_CLIENT_PORT` configura el cliente; ambos deben ser distintos. Vite informa de un puerto ocupado en lugar de cambiarlo silenciosamente. Conviene usar puertos de aplicación distintos de los reservados por Specrails, que el agente puede consultar mediante `background_list`.
+
+Si una petición de misión recibe HTML, una respuesta inválida o ninguna confirmación de admisión, muestra un error traducido y conserva el borrador con sus referencias, adjuntos e identidad de envío. No reenvía automáticamente una operación cuyo resultado pueda ser incierto.
+
+La separación entre shell, descendientes y eventos de salida se basa en los contratos de [procesos hijos de Node.js](https://nodejs.org/api/child_process.html#optionsdetached) y [señales de proceso](https://nodejs.org/api/process.html#processkillpid-signal), y se verifica con procesos locales desechables.

package/docs/multi-repo-projects.md

@@ -0,0 +1,51 @@
+# Projects with several repositories
+
+A Specrails project can contain a frontend, backend, libraries and other local repositories. They share one board, spec numbering, missions, Jira connection and project settings. A spec can select several repositories and describe the contract between them.
+
+## Add repositories
+
+When adding a project, choose its primary folder and use **Add folder** for additional folders. On desktop, the folder picker also accepts several additional selections. In a web development session, enter their local paths.
+
+For an existing project, open **Project settings → General → Repositories and folders**. Add repositories there, give them descriptive names, and optionally set their integration branches. The primary folder continues to own the existing project identity and backlog; adding a repository preserves the existing specs, history and Jira configuration.
+
+Folder paths must exist. Specrails resolves symbolic links and rejects duplicate or nested roots within the same project. A secondary checkout can belong to several logical projects, each with its own backlog. Git operations on a shared checkout use the same repository lock.
+
+A folder without Git can provide read-only context. It cannot be selected as an additional implementation target. A previously registered project with one non-Git primary folder retains its existing behavior.
+
+## Scope a shared spec
+
+Use **Affected repositories** when creating or editing a spec. Select every repository that needs implementation changes. The selection is retained through Quick and Explore authoring, parked drafts, edits and Jira refreshes.
+
+Older specs without a selection continue to target the primary repository. Jira imports use that same default until you choose a different scope. A batch targets the union of its specs' repositories. An explicit launch selection may add repositories but cannot omit a repository required by a spec. A standalone loop has a repository selector in its Run dialog.
+
+The mission agent can discover every registered repository. Code and Git views have a repository picker, and file references retain repository identity even when several repos contain `src/index.ts`. Reading a repository does not add it to a spec's implementation scope.
+
+## Run and review
+
+Multi-repository launches prepare isolated Git worktrees for all selected repositories before starting the provider. One coordinated implementation can edit the selected worktrees and verify changes across their boundaries. Preparation failures stop the launch and preserve an actionable error.
+
+OpenSpec artifacts belong to the selected primary repository, or to the first selected repository when the primary is outside the scope. Custom shell nodes must choose a repository explicitly for multi-repository runs. Built-in archive steps use the artifact repository.
+
+The delivery card contains one section per repository with its branch, commit and delivery status. Review evidence by repository, then create or publish a PR, integrate locally, or check out the work for that repository. Checkout moves a verified review branch into that repository's local folder; it does not mark the shared spec complete.
+
+The shared spec and Jira issue finish only after every required repository is accepted, including explicit acceptance of repositories with no changes. If one integration succeeds and another fails, the successful result is retained. Resolve the reported problem and retry the outstanding repository. Git cannot make commits or merges atomic across separate repositories.
+
+Revisions preserve the repository scope and build on the previous delivery commits. An already integrated repository starts from its verified integration head, preserving subsequent local work. Sequential milestone chunks use the latest delivered head for each repository, including repositories unchanged by an intermediate chunk. Their local integration destination remains the configured integration branch.
+
+## Change or detach a repository
+
+Names and integration branches can be edited without moving a checkout. Changing a secondary folder path or detaching it is blocked while specs or active execution records still refer to that membership. Update those specs and resolve the pending work first. Detaching a member never deletes its local files.
+
+An unavailable folder remains visible with an error. Specrails does not redirect an explicit repository selection to the primary folder. Frozen execution records keep their original paths so that recovery and review cannot follow a later membership edit into a different checkout.
+
+## MCP and API
+
+`specrails_projects` and `specrails_context` expose repository inventories. Individual code and Git operations accept `repositoryId`; on a multi-repository project the agent must identify the member. Code find/search can discover across members and reports truncation when its shared budget is exhausted.
+
+Specs and launches accept `repositoryIds`. IDs belong to the selected logical project. Unknown, removed or foreign IDs produce an error before implementation starts.
+
+Use `specrails_rails` to implement a shared spec and `specrails_loops` for coordinated standalone work. Direct `specrails_jobs(spawn)` is a primary-repository operation; in a multi-repository project it requires that primary member's explicit ID and rejects secondary targets before enqueueing.
+
+To start a development server through the mission agent, use `specrails_jobs` with `action: "background_start"`, the intended `repositoryId`, and a command such as `npm run dev`. An optional `cwd` stays inside that repository. This keeps the existing Autonomous permission level and explicit command confirmation; selecting or reading a repository does not start a process.
+
+REST membership lives at `/api/projects/:projectId/repositories`. Repository code and Git routes live under `/api/projects/:projectId/repositories/:repositoryId`; existing unscoped routes retain primary-repository behavior. Grouped delivery decisions retain the parent delivery ID and optionally specify `repositoryId`. Review packets accept a `repositoryId` query parameter.

package/docs/platforms/windows-parity.md

@@ -0,0 +1,70 @@
+# Windows feature parity audit
+
+This audit covers the `codex/multi-repo-projects` branch, including mission steering, multiple repositories, persistent process logs and the code explorer. It is a compatibility and regression audit, not a certificate that every Windows configuration or third-party login has been tested.
+
+## Feature coverage
+
+| 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. |
+| 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. |
+| Missions and live messages | Claude streaming keeps stdin open and puts system context in prompt files on Windows; Codex and Gemini large prompts avoid command-line limits. Edit/delete/steer UI behavior remains shared. |
+| Rails and built-in/custom loops | Windows-safe process wrappers, environment and cwd handling; stop flows terminate owned process trees. User-authored shell commands still need syntax supported by their configured shell. |
+| Background applications and logs | A Windows Job Object owns the application before command admission and retains descendants after launchers exit. Stop waits for the contained processes to terminate. Graceful host shutdown drains processes and logs before force-stop fallback. |
+| Terminal | Bundled ConPTY helper forks the bundled Node instead of recursively launching the pkg sidecar. Native package smoke checks input, output and descendant cleanup. File drops quote for the session's actual shell. |
+| Git and worktrees | Existing repository-scoped integration/checkout protections remain; Windows process and path helpers are exercised by native regression fixtures. Conflict decisions remain deliberate user-visible outcomes. |
+| Files and observability | Same read-only tree/search/activity/diff/summary interfaces; Windows watcher root deletion degrades and retries instead of reporting a dead native watcher as healthy. |
+| MCP and plugins | Core and project/repository scope remain explicit. Serena's app-managed Codex MCP configuration is injected into the actual provider spawns without replacing the user's authentication home. |
+| Native browser | WebView2 browsing, capture and selector support share the host API; remote pages do not receive privileged desktop IPC. Browser/popup ownership and events are scoped to the calling app window. Reparenting retains the live session; occupied destinations park their previous browser and restore it on rollback. |
+| Detached mission windows | Independent native windows share the original backend and active agent invocation. Versioned draft/workspace handoffs require destination acknowledgement; stale acknowledgements cannot close the source. Native mission close reintegrates, main close hides to tray, and popup close destroys only its own window. |
+| File reveal, save, notifications | Supported native host commands replace dynamic imports that could be rejected by the production CSP or refer to missing plugins. |
+| Keyboard, layouts, language | Ctrl+Enter works for feature exploration/refinement, shortcut hints display Windows modifiers, and terminal errors have translations in all eight locales. Shared client suites cover remaining UI behavior. |
+| Mobile companion, analytics, settings, tickets/integrations | Shared Node/React implementations and existing regression suites; Windows startup, profile and subprocess fixes also apply to these callers. External services require their own credentials/network access. |
+
+## Automated gates
+
+`.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:
+
+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.
+3. A source file can be read through the project API.
+4. A real PTY executes a Node helper in the correct cwd and streams its output.
+5. Closing the terminal terminates that helper, including the packaged ConPTY cleanup path.
+6. A background wrapper exits and leaves a descendant alive; its card remains running and Stop terminates the descendant before confirming completion.
+7. Authenticated host shutdown exits cleanly; restarting retains the same project ID.
+8. The temporary package is uninstalled and its fixture is removed.
+
+Release-manifest and staged-helper tests can also run locally:
+
+```sh
+node --test scripts/build-updater-manifest.test.mjs scripts/stage-windows-pty.test.mjs
+```
+
+The current local audit results and any unexecuted checks are recorded in `openspec/changes/windows-feature-parity/verification.md`. A workflow definition is not evidence of a successful Windows run. The `native-macos` job compiles the same host and runs the four fixtures against WebKit, without a sidecar or packaged runtime resources.
+
+The detachable-window implementation has passed native macOS fixtures locally, including independent mission windows, draft/revision rollback, browser session transfer, destination display scale, popup ownership and parked-session restoration. Windows x64/ARM64 execution of the new gates remains pending until CI results are recorded; a macOS pass does not establish WebView2 parity. See [Detachable mission windows](../features/detachable-mission-windows.md) for the behavior and test matrix.
+
+## Real-device release acceptance
+
+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.
+- 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.
+- File selection/reveal/save and desktop notifications under normal user permissions. Test corporate security or network-drive policies where these are part of the supported customer environment.
+
+Installers remain unsigned with Authenticode, so SmartScreen behavior described in the [Windows guide](./windows.md) still applies. The app cannot bypass OS or identity-provider policies.
+
+## Platform references
+
+- [Tauri Windows installers and WebView2 provisioning](https://v2.tauri.app/distribute/windows-installer/)
+- [Tauri updater](https://v2.tauri.app/plugin/updater/); the pinned updater 2.10.1 selects `OS-ARCH-installer` before `OS-ARCH` in `get_urls`.
+- [Node filesystem watcher caveats](https://nodejs.org/api/fs.html#caveats)
+- [Microsoft WebView2 runtime distribution](https://learn.microsoft.com/microsoft-edge/webview2/concepts/distribution)
+- [Microsoft Windows Job Objects](https://learn.microsoft.com/en-us/windows/win32/procthread/job-objects)

package/docs/platforms/windows.md

@@ -4,9 +4,10 @@
 
 ## Supported configurations
 
-- **Windows 10** (1809 or newer) and **Windows 11**.
+- **Windows 10 x64** (1809 or newer) and **Windows 11 x64/ARM64**.
 - Both **x64** and **ARM64** are first-class targets — each release publishes native installers for both architectures.
-- The terminal panel uses ConPTY, which requires **Windows 10 1809+** (always available on Windows 11).
+- The terminal panel uses ConPTY on supported Windows builds and ships the node-pty WinPTY fallback for older Windows 10 builds.
+- The installer embeds the evergreen WebView2 offline installer, so provisioning the app webview does not require a network connection.
 
 ## Installation
 
@@ -65,18 +66,15 @@ user-managed. See [Kimi](../kimi.md), [Codex](../codex.md), and
 
 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.
 
-Note that updates are delivered as the **MSI** (verified by an embedded **minisign** signature the updater checks before applying), not the NSIS `-setup.exe` used for first install. Because the installers are not Authenticode-signed, an applied update may still surface the same SmartScreen prompt; click **More info → Run anyway** as during the first install.
+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.
 
-## Setup wizard
-
-When you add a project, the setup wizard runs `npx specrails-core@^4.12.0 init --from-config` under the hood (the full spawn is `npx --yes --prefer-online specrails-core@^4.12.0 init --yes --from-config <tempPath>`, with the app writing a temporary `install-config.yaml`). The wizard has three steps — **Configure / Install / Done**.
+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.
 
-There are two distinct version floors to be aware of:
+## Setup wizard
 
-- The app **installs** `specrails-core@^4.12.0` — the major-pinned range it ships (4.12.0 is the release that adds the Kimi provider target). The exact package spec is the `CORE_PACKAGE_SPEC` constant in `server/core-package.ts`, so it stays verifiable in one place. You need internet access at install time so `npx` can resolve it.
-- The minimum it will **accept** at runtime is **specrails-core ≥ 4.1.0** — the Node-native installer floor (`MIN_NODE_NATIVE_CORE_VERSION`). Anything below that is a legacy bash/python3 installer and cannot run on Windows without WSL.
+Adding a project assembles the framework from the bundled or newer compatible activated core. The installed app includes the Node-native core and OpenSpec resources, so normal project setup does not require a separate core installation. Core updates preserve the previous active framework if switching the Windows junction fails.
 
-You can point the app at a local or linked build with the `SPECRAILS_CORE_BIN` environment variable (it overrides the `npx` spec above).
+Online fallback uses the range in `server/core-package.ts` (currently `specrails-core@^5.0.0`). Runtime selection and the activated version are shared with the Settings view so a restart cannot silently downgrade a newer working core. `SPECRAILS_CORE_BIN` remains available for a deliberately selected local core executable. Legacy pre-4.1 bash/Python installers are not used for Windows setup.
 
 Reserved paths (`.specrails/profiles/**`, `.claude/agents/custom-*.md`) are preserved across re-runs per the contract documented in [specrails-core's README](https://github.com/fjpulidop/specrails-core#reserved-paths).
 
@@ -87,7 +85,7 @@ Reserved paths (`.specrails/profiles/**`, `.claude/agents/custom-*.md`) are pres
 
 ## Known limitations
 
-- **Terminal panel shell**: the bottom terminal panel auto-prefers **PowerShell 7 (`pwsh.exe`)** when it is on your `PATH`, then falls back to Windows PowerShell (`powershell.exe`), and finally `COMSPEC`/`cmd.exe`. Set the `SHELL` environment variable to override the platform default with any shell you prefer. Per-session shell selection is not yet exposed in the UI.
+- **Terminal panel shell**: the bottom terminal panel auto-prefers **PowerShell 7 (`pwsh.exe`)** when it is on your `PATH`, then falls back to Windows PowerShell (`powershell.exe`), and finally `COMSPEC`/`cmd.exe`. Unix `SHELL` values inherited from Git Bash are ignored on Windows. Per-session shell selection is not yet exposed in the UI. File drops use the actual session shell; paths that cmd.exe would expand cannot be pasted as if they were literal paths.
 - **Port 4200** must be free on launch. The app binds `127.0.0.1:4200` for its API + WebSocket. If another process holds it, the app shows a native **Specrails — Port Conflict** dialog and exits. When you need to investigate, two files under `%USERPROFILE%\.specrails\` help: `desktop.log` (the embedded server's log output) and `manager.pid` (the running server's process ID).
 - **Custom window chrome**: the app uses a frameless window with a custom titlebar; the min/max/close controls are rendered by the app.
 - **Code signing**: Windows builds are unsigned in v1 (see SmartScreen above). Authenticode signing is deferred to a later release.
@@ -98,3 +96,7 @@ Reserved paths (`.specrails/profiles/**`, `.claude/agents/custom-*.md`) are pres
 - [Getting started](../getting-started.md) — first run, adding a project, the dashboard tour.
 - [Codex provider setup](../codex.md), [Gemini provider setup](../gemini.md), and [Kimi provider setup](../kimi.md) — installing and configuring the provider CLIs.
 - [CLI reference](../cli.md) — driving Specrails from the command line.
+
+## Verification
+
+See [Windows parity audit](./windows-parity.md) for coverage, automated release gates and the real-device checks still required before making a compatibility claim. The source checks run on Windows x64 for every change and on ARM64 for pushes to `main` (`windows-parity.yml`, separate from the release-gating CI). Desktop Release installs both NSIS and MSI packages in temporary paths with spaces and exercises the installed server, database, repository browsing, PTY input/output/stop, graceful shutdown and restart.

package/docs/running-pipelines.md

@@ -68,6 +68,20 @@ boundary, so Kimi + Decider is rejected before the loop starts.
 
 ### Pipeline phases
 
+Core versions that declare the shared execution runtime also keep a durable
+journal for each run. Desktop freezes the selected specs, repository roots and
+ownership in `.specrails/pipeline/<runId>/desktop-context.json`; Core owns the
+separate normalized context, phase state and verification receipts. Retries keep
+valid completed work and resume the first incomplete or invalid phase. A batch
+uses one aggregate change, retaining each ticket's requirements and repository
+scope.
+
+Verification can reuse an actual successful command receipt only when its scope,
+candidate files and environment remain current. Acceptance and security review
+are still required, and confidence must pass before archive. A new verification
+step checks receipt freshness again before reporting success. Older Core versions
+continue through the ordinary verification path.
+
 `Implement` and `Batch` run the pipeline phases defined by the slash command's frontmatter — by default:
 
 ```