specrails-desktop 2.55.0 → 2.56.0

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

@@ -12,6 +12,11 @@ framework is rejected rather than silently replacing an update.
 
 ## Persistence and publication
 
+The release bundle pins Core 5.6.0 in `desktop-release.yml` and
+`scripts/assemble-bundled-core.lock.json`. This includes scoped runtime recovery
+and the Opus 5.5 alias. Update both pins together and check compatibility against
+the staged published package; retained runs still use their original runtime.
+
 Desktop updates retain the complete npm installation, including dependencies,
 under `~/.specrails/core/<version>/`. The registry home override applies to this
 directory. Only the managed package corresponding to the active framework is

package/docs/internals/embedded-browser-native-webview-evaluation.md

@@ -4,8 +4,8 @@
 
 > Status: **implemented (phases 0–1 + devtools/zoom from phase 2)** — researched
 > 2026-07-26, shipped via OpenSpec change `native-embedded-browser`. As-built:
-> `src-tauri/src/browser.rs`, `client/src/lib/native-browser.ts`,
-> `client/src/components/browser-capture/NativeBrowserPane.tsx`, router in
+> `src-tauri/src/browser.rs`, `client/src/features/browser/lib/native-browser.ts`,
+> `client/src/features/browser/components/browser-capture/NativeBrowserPane.tsx`, router in
 > `WebViewModal.tsx`. Open follow-ups: Windows z-order QA on a real build
 > (tauri #9798), localhost-preview affordance (port detection), agent
 > observability (phase 3).
@@ -21,9 +21,9 @@ headless Chromium (Playwright, server)  ──CDP Page.startScreencast──▶
      input WS  ◀────────────────────────────────  <canvas> + createImageBitmap (client)
 ```
 
-- `server/browser-playwright.ts` — CDP screencast (JPEG, quality 70, `everyNthFrame: 1`).
-- `server/browser-context-pool.ts` — one persistent headless Chromium resident for the app.
-- `client/src/components/browser-capture/useBrowserCaptureSession.ts` — WS → bitmap → canvas pipeline, newest-frame-wins.
+- `server/modules/browser/runtime/browser-playwright.ts` — CDP screencast (JPEG, quality 70, `everyNthFrame: 1`).
+- `server/modules/browser/runtime/browser-context-pool.ts` — one persistent headless Chromium resident for the app.
+- `client/src/features/browser/components/browser-capture/useBrowserCaptureSession.ts` — WS → bitmap → canvas pipeline, newest-frame-wins.
 - The app **bundles a full Chromium** in the installer (`server/chromium-resolver.ts`, XOR blob `chromium.pak`) just to power this.
 
 Consequences: a second full Chromium process tree resident; continuous JPEG

package/docs/internals/gemini-mcp-registration.md

@@ -15,7 +15,7 @@ empirically against **gemini-cli 0.49.0**.
   `chat-manager` / `queue-manager` / `util/cli-prompt.ts` already use for every gemini spawn.
 - **Gemini exposes MCP tools under an FQN prefix**: `mcp_<server>_<tool>` — for the Specrails
   server, `mcp_specrails_<canonical name>` (e.g. `mcp_specrails_specrails_specs`). The agent-chat
-  operator prompt (`server/agent-operator-prompt.ts`) notes this so the model calls the right
+  operator prompt (`server/modules/missions/runtime/agent-operator-prompt.ts`) notes this so the model calls the right
   names on gemini.
 
 ## What works today: agent chat
@@ -38,7 +38,7 @@ loads** for gemini:
 |---|---|---|
 | Plugins on rails (`server/plugin-manager.ts`, e.g. Serena) | surgical merge into `<project>/.mcp.json` for `project-json` providers | plugin installs "successfully", MCP server never loads in gemini rail spawns |
 | Workspace MCP (`server/agent-mcp-config.ts` `mergeSpecrailsIntoWorkspaceMcp`, via `workspace-manager.ts`) | writes `<workspace>/.mcp.json` | not read by gemini |
-| Explore `context_scope.mcp` (`server/chat-manager.ts`) | spawns from the relocation-aware artifact cwd (workspace when relocated, `<project.path>` when legacy) so `.mcp.json` loads | loads nothing on gemini |
+| Explore `context_scope.mcp` (`server/modules/conversations/runtime/chat-manager.ts`) | spawns from the relocation-aware artifact cwd (workspace when relocated, `<project.path>` when legacy) so `.mcp.json` loads | loads nothing on gemini |
 
 Fixing these means writing into the repo's / workspace's `.gemini/settings.json`, which
 intersects the **pristine-repo / artifact-relocation policy** (the app must not mutate the

package/docs/internals/global-artifacts-alignment-contract.md

@@ -377,7 +377,7 @@ El lado desktop ya tiene el precedente load-bearing en producción (`explore-cwd
 - **claude**: autodescubre `.claude/{agents,commands,skills}` + `CLAUDE.md` + `.mcp.json` desde cwd — **sin flags nuevos en el happy path**. Añade `--add-dir <workspace>/project` para que las tools file alcancen el repo por path absoluto. Conserva `--setting-sources project,local`.
 - **codex**: conserva `CODEX_HOME=~/.specrails/projects/<slug>/codex-home` (ya $HOME). Añade `-c project_root_markers=[]` (defensivo) para que no camine ancestros a un `AGENTS.md` repo-side.
   - **⚠️ Sandbox writable-roots (bug de loops, corregido):** el sandbox de codex solo permite **escribir** en su cwd de spawn. Bajo relocalización el cwd es el **workspace**, no el repo → escrituras al código fuente (alcanzado vía `./project`) fallan con `Operation not permitted`. Los rails de codex no lo sufren porque `rail-job` usa `--sandbox danger-full-access`; pero las **iteraciones de loop resume** (`chat-resume`) corren bajo `workspace-write` y quedaban sin acceso de escritura al repo, haciendo girar el ciclo verify→fix sin fin (12 iteraciones, 0 cambios). `--add-dir` es **claude-only** y codex ni siquiera lo soporta. **Fix** (`loop-executors.ts`): para codex relocalizado inyecta `-c sandbox_workspace_write.writable_roots=["<repoDir>", "<cwd>"]` en `extraArgs` (no-op inocuo bajo `danger-full-access` en la iteración 1).
-  - **Smoke check (manual):** en un proyecto relocalizado con provider=codex, lanzar un loop "Implement" cuyo paso de fix deba editar una fuente del repo; confirmar en el transcript que (a) `apply_patch`/edit a `<repoDir>/...` **NO** devuelve `Operation not permitted`, y (b) `npm run build`/`tsc -b` puede escribir `node_modules/.tmp/*.tsbuildinfo`. Reproducción del fallo: revertir el `extraArgs` de codex → la edición del repo en la iteración ≥2 vuelve a fallar con `Operation not permitted`. Cubierto por `server/loop-executors.test.ts` (assert del arg `writable_roots`).
+  - **Smoke check (manual):** en un proyecto relocalizado con provider=codex, lanzar un loop "Implement" cuyo paso de fix deba editar una fuente del repo; confirmar en el transcript que (a) `apply_patch`/edit a `<repoDir>/...` **NO** devuelve `Operation not permitted`, y (b) `npm run build`/`tsc -b` puede escribir `node_modules/.tmp/*.tsbuildinfo`. Reproducción del fallo: revertir el `extraArgs` de codex → la edición del repo en la iteración ≥2 vuelve a fallar con `Operation not permitted`. Cubierto por `server/modules/loops/runtime/loop-executors.test.ts` (assert del arg `writable_roots`).
 - **gemini**: inyecta `GEMINI_CLI_TRUST_WORKSPACE=true` (ancla el root confiable al workspace). **Re-keya** `~/.gemini/acknowledgments/agents.json` al workspace.
 - Los tres: el workspace **estrictamente fuera del repo** y el discovery no debe seguir `./project` (mitiga la fuga por ancestor-walk de codex/gemini).
 - **Caso especial Explore `mcp=true` (implementado):** `ChatManager` resuelve el cwd mediante la misma puerta de relocalización: workspace cuando el proyecto está relocalizado, `project.path` en legacy. Las rutas persistent-stdin, crash-respawn y Contract Refine conservan esa misma pareja cwd/env. Una sesión anterior creada bajo el cwd del repo que devuelve exactamente `No conversation found with session ID` se invalida y reintenta fresh una sola vez desde el workspace (transcript persistido acotado para Explore; ticket sembrado y tools deshabilitadas para Contract Refine), nunca volviendo al repo. `SPECRAILS_EXPLORE_LEGACY_CWD=1` sigue forzando `project.path`.

package/docs/internals/global-artifacts-relocation-evaluation.md

@@ -11,7 +11,7 @@
 
 ## 1. Resumen ejecutivo
 
-El objetivo es **parcialmente alcanzable, no plenamente**, y la frontera entre lo alcanzable y lo irreductible es nítida y está bien fundamentada en la evidencia. La pieza maestra es un hecho confirmado en código y en los CLIs vivos: **los tres CLIs (claude, codex, gemini) anclan su "project scope" — agentes, comandos, skills, settings, archivo de instrucciones, `.mcp.json` — al directorio de trabajo (CWD), no al repo de git.** No existe ningún `--project-dir` en ninguno de los tres. Por tanto, si cada spawn se ejecuta desde un directorio anclado en `$HOME` (con el repo accesible mediante un symlink hijo `./project`), ese directorio pasa a ser el "proyecto" para el CLI y **cero archivos de config aterrizan en el repo**. Este patrón ya está probado y en producción en `server/explore-cwd-manager.ts`.
+El objetivo es **parcialmente alcanzable, no plenamente**, y la frontera entre lo alcanzable y lo irreductible es nítida y está bien fundamentada en la evidencia. La pieza maestra es un hecho confirmado en código y en los CLIs vivos: **los tres CLIs (claude, codex, gemini) anclan su "project scope" — agentes, comandos, skills, settings, archivo de instrucciones, `.mcp.json` — al directorio de trabajo (CWD), no al repo de git.** No existe ningún `--project-dir` en ninguno de los tres. Por tanto, si cada spawn se ejecuta desde un directorio anclado en `$HOME` (con el repo accesible mediante un symlink hijo `./project`), ese directorio pasa a ser el "proyecto" para el CLI y **cero archivos de config aterrizan en el repo**. Este patrón ya está probado y en producción en `server/modules/conversations/runtime/explore-cwd-manager.ts`.
 
 La recomendación es **adoptar el "workspace gestionado por la app" (Opción 1) como modelo arquitectónico de destino**, porque convierte la inmunidad a colisiones en una **propiedad estructural** (no en supresión por-flag), pero **ejecutarlo por fases empezando por el alcance de la Opción 3 (Híbrido Pragmático)** para los flujos de lectura/interactivos, que ya son relocalizables hoy con cambios solo en desktop y cero cambios en contratos congelados. El panel de jueces se reparte de forma honesta: **la lente de feasibilidad CLI y la de goal-fit/UX eligen la Opción 1** (es la única que usa el único mecanismo universal, CWD-relocation, sin depender de flags que el CLI no soporta); **la lente de blast-radius/contratos elige la Opción 3** (menor superficie de cambio, cero contratos en riesgo).
 

package/docs/internals/interactive-jobs.md

@@ -5,10 +5,10 @@ agent-style composer while the job runs. This doc is the as-built record of the
 behind it: the transport, the two settle modes, the loop-step ownership design, the accounting
 reconciliation, and the failure interplay. User-facing behaviour: the in-app guide's
 [Job Detail view](../guide/en/pipeline/2-the-job-detail-view.md) page. Code:
-`server/interactive-job-session.ts`, `server/queue-manager.ts` (the interactive branch of
-`_startJob`), `server/loop-executors.ts` `planInteractiveAiStep`, `server/loop-run-manager.ts`
+`server/modules/execution/runtime/interactive-job-session.ts`, `server/modules/execution/runtime/queue-manager.ts` (the interactive branch of
+`_startJob`), `server/modules/loops/runtime/loop-executors.ts` `planInteractiveAiStep`, `server/modules/loops/runtime/loop-run-manager.ts`
 `_runInteractiveAiStep`, `server/project-router-jobs.ts` (the two manager-agnostic routes),
-`client/src/components/InteractiveJobComposer.tsx`.
+`client/src/features/jobs/components/InteractiveJobComposer.tsx`.
 
 ## Session model
 
@@ -33,7 +33,7 @@ The original interactive path was freestyle-only because freestyle sends prose,
 command. Spike-verified 2026-07-03 against **claude 2.1.198**: the claude CLI expands slash
 commands arriving as stream-json stdin user frames **exactly like the argv `-p "/cmd"` path**
 (evidence pointer: the dated comment block above the interactive gate in
-`server/queue-manager.ts` `_startJob`, and `loop-executors.ts` `planInteractiveAiStep`). That
+`server/modules/execution/runtime/queue-manager.ts` `_startJob`, and `loop-executors.ts` `planInteractiveAiStep`). That
 makes every job — `/specrails:implement`, `/specrails:batch-implement`, distilled loop commands,
 custom commands — transport-compatible, so the default flipped to interactive for every
 persistent-stdin-capable provider.
@@ -63,7 +63,7 @@ spawnInteractive = isInteractiveJobsEnabled()            // SPECRAILS_INTERACTIV
 | Who gets it | freestyle/Freestyle QueueManager jobs (claude) | every other interactive job + ALL loop ai-steps |
 | End of session | explicit human **Finalize** only (SIGTERM → 2s → SIGKILL) | **quiescence**: a turn `result` arrived, nothing queued, no write in flight — torn down GRACEFULLY: stdin EOF (the CLI exits itself, flushing its session transcript so the next loop step can `--resume`), SIGTERM only after a grace window (`quiescentEofGraceMs`, default 5s) or when stdin is already gone |
 | Idle between turns | by design (awaiting the human) | only transiently (microtask window) |
-| Wedge detector | never armed | the queue's zombie-timeout budget (QueueManager) / the loop-step idle budget (loop ai-steps — `server/loop-step-idle.ts`, default 30 min, `SPECRAILS_LOOP_STEP_IDLE_TIMEOUT_MS`), reset on any raw child output; silence for the whole budget → fold in-flight turn, settle `crashed` (loop steps: tagged `stalled`, retried once by resume) |
+| Wedge detector | never armed | the queue's zombie-timeout budget (QueueManager) / the loop-step idle budget (loop ai-steps — `server/modules/loops/runtime/loop-step-idle.ts`, default 30 min, `SPECRAILS_LOOP_STEP_IDLE_TIMEOUT_MS`), reset on any raw child output; silence for the whole budget → fold in-flight turn, settle `crashed` (loop steps: tagged `stalled`, retried once by resume) |
 | Composer action | **Finalize Job** | **Wrap up now** (QueueManager) / **Settle this step** (loop step) |
 
 **Quiescence detail:** the auto-settle is deferred to a microtask after the `result` so anything
@@ -106,7 +106,7 @@ persistent stdin, each claude **ai-step** runs as its own `InteractiveJobSession
   SAME step once by resuming the captured session (`loop_step { attempt: 2 }`); a second stall
   settles the run `stalled` (tickets → `todo`, delivery row auto-closes). The one-shot loop path
   arms the same bound through `runAiCliInvocation`'s `inactivityTimeoutMs`. Contract:
-  `server/loop-step-idle.ts` — `SPECRAILS_LOOP_STEP_IDLE_TIMEOUT_MS` (default 30 min; `0|false|off`
+  `server/modules/loops/runtime/loop-step-idle.ts` — `SPECRAILS_LOOP_STEP_IDLE_TIMEOUT_MS` (default 30 min; `0|false|off`
   disables; clamped ≥ the stuck-notification threshold so `job.stuck` always precedes teardown).
 
 ## Accounting reconciliation
@@ -141,7 +141,7 @@ factory loop then "succeeded" via verify/fix without implementing). Strictness r
 command didn't actually run, the settle is FAILED.**
 
 - **The predicate is shared and whole-life.** `isZeroWorkSettle` (exported from
-  `server/interactive-job-session.ts`) judges the session/step's WHOLE accumulated life: it is
+  `server/modules/execution/runtime/interactive-job-session.ts`) judges the session/step's WHOLE accumulated life: it is
   zero-work when `num_turns === 0` accumulated AND no assistant-derived event was ever observed
   (`isModelWorkEvent`: text-delta / tool-use / assistant frames / usage-carrying events; `result`
   frames do NOT count — the synthetic no-op IS a result frame) AND all four token counters are
@@ -312,7 +312,7 @@ dashboard — identical worktree isolation and ask-first PR flow. Without this,
 implement landed in the bare QueueManager branch: shared cwd, `SPECRAILS_GIT_AUTO=false`, no
 delivery row — stranded uncommitted work. Loops disabled ⇒ the legacy QueueManager path,
 unchanged. Relatedly, the agent-chat operator prompt gained the ask-confirmation-once
-turn-discipline rule (`server/agent-operator-prompt.ts`): a confirmation question is asked
+turn-discipline rule (`server/modules/missions/runtime/agent-operator-prompt.ts`): a confirmation question is asked
 exactly once and ends the reply — the answer arrives as the next user message.
 
 ## Decider starved by its own tool budget (2026-09-07)