specrails-desktop 2.25.0 → 2.26.0

package/docs/gemini-cli-provider-study.md

@@ -14,7 +14,7 @@ Gemini supera a Codex en dos capacidades clave verificadas:
 
 **Entra en v1 (PR-B beta-gated):** jobs/rails básicos, Explore Spec multi-turno (spawn-per-turn con `--resume`), Quick spec, Analytics/coste vía rate-card, OTEL nativo, terminal CLI launch, detección + prerequisitos, selección de modelo, multi-provider per project.
 
-**NO entra en v1 (paridad Codex, se ocultan por intersección de capacidades):** Agent Profiles, SMASH, Contract Refine, Ultracode (+interactivo), plugins/Serena, persistent-stdin de Explore. Gemini se comporta byte-idéntico a Codex en estas superficies **siempre que declare las capacidades correctas y se ensanchen los tipos** — cero código nuevo en esas superficies.
+**NO entra en v1 (paridad Codex, se ocultan por intersección de capacidades):** Agent Profiles, SMASH, Contract Refine, Freestyle (+interactivo), plugins/Serena, persistent-stdin de Explore. Gemini se comporta byte-idéntico a Codex en estas superficies **siempre que declare las capacidades correctas y se ensanchen los tipos** — cero código nuevo en esas superficies.
 
 **Diferido a follow-up explícito (decisiones tomadas, no implementadas en v1):** generalizar `provider-capabilities.ts` para *otorgar* a Gemini features hoy claude-only; bridge Windows multi-line argv; traducción slash-command para rails funcionales en Gemini (esto último es **bloqueante para rails reales**, ver §6).
 
@@ -238,7 +238,7 @@ Mergeable independiente, no cambia comportamiento observable.
 | **Integrations/plugins (MCP/Serena)** | **Bloqueado (paridad codex)** | Manifest Serena omite `providerSupport` → claude-only. Paridad: añadir `'gemini'` a `providerSupport` + entry MCP bajo `.gemini/settings.json`. |
 | **SMASH** | **Bloqueado (paridad codex)** | `isSmashCapable→'claude'`. `smash-runner.ts` spawnea `claude` directo sin adapter. Paridad: reescribir runner sobre `getAdapter()` + prompt/parser Gemini + flip del gate. |
 | **Contract Refine** | **Bloqueado (inherentemente anthropic en su forma actual)** | `--resume` a sesión Claude + slash `/specrails:contract-refine`. Paridad parcial vía el path no-resume (re-seed por system prompt, como `runContractRefineForQuick`) + de-hardcodear `getAdapter('claude')`. |
-| **Ultracode interactivo** | **Bloqueado (paridad codex)** | `mode==='ultracode' && provider!=='claude'→400`; `isUltracode=adapter.id==='claude'`. Paridad: quitar el 400 para gemini, generalizar el branch ultracode-prompt, `persistentStdin:true` para el interactivo. Mecanismo no-anthropic; factible. |
+| **Freestyle interactivo** | **Bloqueado (paridad codex)** | `mode==='freestyle' && provider!=='claude'→400`; `isFreestyle=adapter.id==='claude'`. Paridad: quitar el 400 para gemini, generalizar el branch freestyle-prompt, `persistentStdin:true` para el interactivo. Mecanismo no-anthropic; factible. |
 | **Analytics/coste** | **Nativo (estimado)** | `nativeCostUsd:false` + filas pricing → coste estimado, `estimated=true`. Filtros engine ya data-driven. |
 | **OTEL/telemetry** | **Nativo (MEJOR que codex)** | `nativeOtelEnv:true` → env-injection (no bridge). Solo parametrizar el enable-var en `buildTelemetryEnv`. Caveat correlación (§4). |
 | **Terminal CLI launch** | **Nativo** | `CliLaunchMenu` itera providers; aparece tras ensanchar union + wiring binario. |

package/docs/guide/de/pipeline/3-batch-implement-and-multi-feature.md

@@ -81,4 +81,4 @@ Es gibt kein globales Parallelitäts-Limit, das du einstellen musst. Öffne die
 
 - [Rails & Jobs](rails-and-jobs) — das Queue-Modell im Detail.
 - [Die Job-Detail-Ansicht](the-job-detail-view) — einem Batch-Lauf live zusehen.
-- [Engine pro Rail wählen](picking-an-engine-per-rail) — beachte: Batch läuft auf jedem Provider; Ultra gibt es nur bei Claude.
+- [Engine pro Rail wählen](picking-an-engine-per-rail) — beachte: Batch läuft auf jedem Provider; Freestyle gibt es nur bei Claude.

package/docs/guide/en/pipeline/3-batch-implement-and-multi-feature.md

@@ -83,4 +83,4 @@ There's no global concurrency limit to tune. Open the projects or rails you need
 
 - [Rails & jobs](rails-and-jobs) — the queue model in depth.
 - [The Job Detail view](the-job-detail-view) — watch a batch run live.
-- [Picking an engine per rail](picking-an-engine-per-rail) — note that Batch runs on any provider; Ultra is Claude-only.
+- [Picking an engine per rail](picking-an-engine-per-rail) — note that Batch runs on any provider; Freestyle is Claude-only.

package/docs/guide/es/pipeline/3-batch-implement-and-multi-feature.md

@@ -81,4 +81,4 @@ No hay límite global de concurrencia que ajustar. Abre los proyectos o rails qu
 
 - [Rails y jobs](rails-and-jobs) — el modelo de cola en profundidad.
 - [La vista de detalle del job](the-job-detail-view) — mira un batch ejecutarse en vivo.
-- [Elegir un motor por rail](picking-an-engine-per-rail) — ten en cuenta que Batch corre en cualquier proveedor; Ultra es solo de Claude.
+- [Elegir un motor por rail](picking-an-engine-per-rail) — ten en cuenta que Batch corre en cualquier proveedor; Freestyle es solo de Claude.

package/docs/guide/fr/pipeline/3-batch-implement-and-multi-feature.md

@@ -81,4 +81,4 @@ Il n'y a aucune limite globale de concurrence à régler. Ouvrez les projets ou
 
 - [Rails et jobs](rails-and-jobs) — le modèle de file d'attente en détail.
 - [La vue détaillée du job](the-job-detail-view) — regarder un batch s'exécuter en direct.
-- [Choisir un moteur par rail](picking-an-engine-per-rail) — notez que Batch fonctionne sur n'importe quel fournisseur ; Ultra est réservé à Claude.
+- [Choisir un moteur par rail](picking-an-engine-per-rail) — notez que Batch fonctionne sur n'importe quel fournisseur ; Freestyle est réservé à Claude.

package/docs/guide/it/pipeline/3-batch-implement-and-multi-feature.md

@@ -81,4 +81,4 @@ Non c'è alcun limite globale di concorrenza da regolare. Apri i progetti o i ra
 
 - [Rail e job](rails-and-jobs) — il modello della coda in dettaglio.
 - [La vista Dettaglio job](the-job-detail-view) — guarda un batch in esecuzione dal vivo.
-- [Scegliere un engine per ogni rail](picking-an-engine-per-rail) — nota che il Batch gira su qualsiasi provider; Ultra è solo Claude.
+- [Scegliere un engine per ogni rail](picking-an-engine-per-rail) — nota che il Batch gira su qualsiasi provider; Freestyle è solo Claude.

package/docs/guide/ja/pipeline/3-batch-implement-and-multi-feature.md

@@ -81,4 +81,4 @@ Batch モードは、関連するスペックを*順番に処理する*一番す
 
 - [レールとジョブ](rails-and-jobs) — キューモデルを掘り下げて。
 - [ジョブ詳細ビュー](the-job-detail-view) — バッチ実行をライブで見守る。
-- [レールごとのエンジン選択](picking-an-engine-per-rail) — Batch はどのプロバイダーでも動きますが、Ultra は Claude 専用である点に注意。
+- [レールごとのエンジン選択](picking-an-engine-per-rail) — Batch はどのプロバイダーでも動きますが、Freestyle は Claude 専用である点に注意。

package/docs/guide/pt/pipeline/3-batch-implement-and-multi-feature.md

@@ -81,4 +81,4 @@ Não há limite global de concorrência para ajustar. Abra os projetos ou rails
 
 - [Rails e jobs](rails-and-jobs) — o modelo da fila em detalhe.
 - [A vista de detalhe do job](the-job-detail-view) — ver um batch a correr ao vivo.
-- [Escolher um motor por rail](picking-an-engine-per-rail) — note que o Batch corre em qualquer fornecedor; o Ultra é só Claude.
+- [Escolher um motor por rail](picking-an-engine-per-rail) — note que o Batch corre em qualquer fornecedor; o Freestyle é só Claude.

package/docs/guide/pt/pipeline/5-the-loop-builder.md

@@ -57,7 +57,7 @@ Um loop que nunca para queimaria dinheiro para sempre, então toda execução te
 |-------|--------------|
 | **Max iterations** | Teto rígido de quantas vezes o Decider pode voltar atrás, independentemente do seu veredito. |
 | **Timeout (min)** | Limite de tempo de relógio para toda a execução. |
-| **Max cost ($)** | *Opcional.* Para o loop quando o custo acumulado cruza o seu orçamento. Verificado **entre passos** (o custo de um passo só é conhecido quando ele termina), então pode ultrapassar em um passo. No Claude o custo é exato; no Codex e no Gemini é uma estimativa. Deixe vazio para não ter teto. |
+| **Max cost ($)** | *Opcional.* Para o loop quando o custo acumulado cruza o seu orçamento. Verificado **entre passos** (o custo de um passo só é conhecido quando ele termina), então pode freestylepassar em um passo. No Claude o custo é exato; no Codex e no Gemini é uma estimativa. Deixe vazio para não ter teto. |
 
 ## Construindo com confiança
 

package/docs/guide/zh/pipeline/3-batch-implement-and-multi-feature.md

@@ -81,4 +81,4 @@ Project B   ▶ Rail running feature Y   ┘
 
 - [Rail 与任务](rails-and-jobs)——深入理解队列模型。
 - [任务详情视图](the-job-detail-view)——实时观看一次批量运行。
-- [为每条 rail 选择引擎](picking-an-engine-per-rail)——注意 Batch 可在任意提供方上运行；Ultra 仅限 Claude。
+- [为每条 rail 选择引擎](picking-an-engine-per-rail)——注意 Batch 可在任意提供方上运行；Freestyle 仅限 Claude。

package/docs/internals/api-reference.md

@@ -199,7 +199,7 @@ Example — queue a command on a specific provider:
 | `POST` | `/jobs/:id/finalize` | Finalize a running interactive job (SIGTERM the resident child; final totals + terminal status are stamped when it closes). For a loop run this settles the **current step** and the loop advances. `202` scheduled, `403` interactive jobs disabled, `409` not an active interactive session |
 | `GET` | `/jobs/:jobId/diagnostic` | Stream a diagnostic ZIP (telemetry + profile + plugins snapshots) |
 
-The two interactive endpoints back the in-job chat that is **on by default for every Claude job** — QueueManager jobs (implement / batch / Freestyle / custom commands) and the loop engine's claude ai-steps alike. Two settle modes: Freestyle/ultracode jobs idle until an explicit finalize (`'finalize'`); everything else settles itself on quiescence (`'auto'` — a turn result with nothing queued), where finalize acts as "wrap up now" / "settle this step". Providers without persistent stdin (Codex, Gemini) run one-shot as before and 409 here. Both endpoints 403 when the server has `SPECRAILS_INTERACTIVE_JOBS=false`. As-built detail: [interactive-jobs.md](interactive-jobs.md).
+The two interactive endpoints back the in-job chat that is **on by default for every Claude job** — QueueManager jobs (implement / batch / Freestyle / custom commands) and the loop engine's claude ai-steps alike. Two settle modes: Freestyle/freestyle jobs idle until an explicit finalize (`'finalize'`); everything else settles itself on quiescence (`'auto'` — a turn result with nothing queued), where finalize acts as "wrap up now" / "settle this step". Providers without persistent stdin (Codex, Gemini) run one-shot as before and 409 here. Both endpoints 403 when the server has `SPECRAILS_INTERACTIVE_JOBS=false`. As-built detail: [interactive-jobs.md](interactive-jobs.md).
 
 Example — fetch one job:
 
@@ -435,7 +435,7 @@ A non-developer-friendly file tree + Monaco viewer with plain-language AI summar
 | `PUT` | `/:railIndex/profile` | Set the rail's default profile |
 | `PUT` | `/:railIndex/engine` | Set the rail's AI engine override. Body `{ aiEngine }` (string — one of the project's providers — or `null` to clear) |
 | `PUT` | `/:railIndex/name` | Set the rail's display name. Body `{ name }` (string or `null` to clear back to the default label); 400 if longer than 60 characters |
-| `POST` | `/:railIndex/launch` | Launch the rail. Body `{ mode?, loopId?, profileName?, aiEngine?, model?, reasoning_effort?, originConversationId?, originSurface?, interactive? }`. `mode` is `implement` / `batch-implement` / `ultracode` / `loop`; a factory `loopId` (`factory:implement` etc.) maps to its legacy mode, and a **bare legacy mode with no `loopId`** (MCP / mobile / direct REST) derives the matching factory loop when Loops are enabled, so every launch door gets the same isolation + ask-first PR flow as the dashboard. `model` (haiku/sonnet/opus/fable) applies to ultracode only. The in-job chat is **on by default for every Claude job** — the legacy `interactive` param is accepted and **ignored** (wire compat; the spawn-time gate decides). Returns `202 { jobId, railIndex, mode }`; **`503`** when the Claude or Codex CLI binary is not found (a missing Gemini/other binary surfaces as `500`) |
+| `POST` | `/:railIndex/launch` | Launch the rail. Body `{ mode?, loopId?, profileName?, aiEngine?, model?, reasoning_effort?, originConversationId?, originSurface?, interactive? }`. `mode` is `implement` / `batch-implement` / `freestyle` / `loop`; a factory `loopId` (`factory:implement` etc.) maps to its canonical rail mode, and a **bare mode with no `loopId`** (MCP / mobile / direct REST) derives the matching factory loop when Loops are enabled, so every launch door gets the same isolation + ask-first PR flow as the dashboard. `model` (haiku/sonnet/opus/fable) applies to freestyle only. The in-job chat is **on by default for every Claude job** — the `interactive` param is accepted and **ignored** (wire compat; the spawn-time gate decides). Returns `202 { jobId, railIndex, mode }`; **`503`** when the Claude or Codex CLI binary is not found (a missing Gemini/other binary surfaces as `500`) |
 | `POST` | `/:railIndex/stop` | Stop the rail's running job (cancels every job the rail registered) |
 
 ---
@@ -444,7 +444,7 @@ A non-developer-friendly file tree + Monaco viewer with plain-language AI summar
 
 Gated by `SPECRAILS_AGENTS_SECTION !== 'false'`. Rails force legacy (no-profile) mode whenever the chosen engine is not Claude, and the Agents section is hidden in multi-provider projects; profile env-injection itself works for any provider whose adapter advertises `profileEnvSupport`.
 
-> **Provider capability notes.** A few behaviours are not the same across all three providers: **Contract Refine** is Claude-only; **rails force legacy (no-profile) mode** for any non-Claude engine; **Ultracode rails** are Claude-only; the **Serena plugin** (and other `project-json` plugins) work for Claude and Gemini but are filtered out for Codex; and **cost is exact only for Claude** (estimated from a rate card for Codex and Gemini). See the [Codex guide](../codex.md) and [Gemini guide](../gemini.md).
+> **Provider capability notes.** A few behaviours are not the same across all three providers: **Contract Refine** is Claude-only; **rails force no-profile mode** for any non-Claude engine; **Freestyle rails** are Claude-only; the **Serena plugin** (and other `project-json` plugins) work for Claude and Gemini but are filtered out for Codex; and **cost is exact only for Claude** (estimated from a rate card for Codex and Gemini). See the [Codex guide](../codex.md) and [Gemini guide](../gemini.md).
 
 ### Profile CRUD
 

package/docs/internals/companion-rails-as-loops-contract.md

@@ -45,10 +45,10 @@ The companion is a **light-control mirror**. It has no typed `Rail` model: rails
 
 ## 2. What rails-as-loops changed — the divergence list
 
-- **`loopId` is the new primary launch verb.** `POST /rails/:i/launch` now accepts `{mode='implement', profileName, aiEngine, model, interactive, loopId, reasoning_effort}` (`rails-router.ts:214-215`). `VALID_MODES` is now `{implement, batch-implement, ultracode, loop}` (`rails-router.ts:25`).
+- **`loopId` is the new primary launch verb.** `POST /rails/:i/launch` now accepts `{mode='implement', profileName, aiEngine, model, interactive, loopId, reasoning_effort}` (`rails-router.ts:214-215`). `VALID_MODES` is now `{implement, batch-implement, freestyle, loop}` (`rails-router.ts:25`).
 - **The mode segmented-control was removed** from the desktop UI and replaced by `RailLoopSelector` (`RailControls.tsx:51-53` comment; `RailRow.tsx:414-421, 597-604`). `RailMode` still exists but is now **derived** from the loop via `deriveRailMode()` (`rail-loops.ts:34-39`), not user-picked.
-- **Factory→mode mapping (the compat layer).** Client factory ids `factory:implement|factory:batch|factory:ultracode` (`rail-loops.ts:8-25`); server mirror `loop-factory.ts:33-55`. `factoryLoopMode()` maps `factory:implement→implement`, `factory:batch→batch-implement`, `factory:ultracode→ultracode` (`rails-router.ts:220-224`); any custom loop → `mode='loop'`.
-- **Loop runs are NOT job-queue jobs.** When `isLoopsEnabled()` (default ON, `feature-flags.ts:51-52`, `!== 'false'`) AND a `loopId` is present (factory OR custom), the launch routes through **`LoopRunManager`**, not `QueueManager` (`rails-router.ts:301-381`). It returns `202 {loopRunIds, railIndex, mode}` with **no `jobId`** (`rails-router.ts:379`), and rows live in a **separate `loop_runs` table** (`loop-runs-store.ts:12-32`) keyed by `loopRunId`. The legacy ultracode/implement paths still return `{jobId, ...}` (`rails-router.ts:428, 453`).
+- **Factory→mode mapping (the compat layer).** Client factory ids `factory:implement|factory:batch|factory:freestyle` (`rail-loops.ts:8-25`); server mirror `loop-factory.ts:33-55`. `factoryLoopMode()` maps `factory:implement→implement`, `factory:batch→batch-implement`, `factory:freestyle→freestyle` (`rails-router.ts:220-224`); any custom loop → `mode='loop'`.
+- **Loop runs are NOT job-queue jobs.** When `isLoopsEnabled()` (default ON, `feature-flags.ts:51-52`, `!== 'false'`) AND a `loopId` is present (factory OR custom), the launch routes through **`LoopRunManager`**, not `QueueManager` (`rails-router.ts:301-381`). It returns `202 {loopRunIds, railIndex, mode}` with **no `jobId`** (`rails-router.ts:379`), and rows live in a **separate `loop_runs` table** (`loop-runs-store.ts:12-32`) keyed by `loopRunId`. QueueManager fallback freestyle/implement paths still return `{jobId, ...}` (`rails-router.ts:428, 453`).
 - **New WS lifecycle family.** `loop.run_started`/`loop.run_progress`/`loop.run_stopped`/`loop.run_completed` (`types.ts:756-790`), emitted by `LoopRunManager` (`loop-run-manager.ts:469`), NOT by the `project-registry.ts:543` `onJobFinished` path that emits `rail.job_completed`. Keying: `loop.run_started`/`loop.run_stopped`/`loop.run_completed` carry `railIndex` + `loopRunId`; **`loop.run_progress` carries only `loopRunId`/`iteration`/`activeNode`/`reasoning` — NO `railIndex`** (`types.ts:756-790`). `loop.run_completed.status ∈ {success, max-iterations, stopped, failed, blocked, stalled}` — `max-iterations` is a **successful** terminal state, not a failure; **`blocked`** (the Loop Decider flagged the run needs a human decision it can't make) and **`stalled`** (the non-convergence guard aborted after consecutive iterations left the working tree unchanged) are controlled HALTS: NOT in the success set, and the settle maps them to job status `canceled` (tickets revert to todo, no PR delivery). A naive `ok = status=='success'` already treats them as non-success — correct.
 - **`GET /rails` gained `activeLoopRuns`** → `{rails, activeJobs:{[idx]:{jobId,mode}}, activeLoopRuns:{[idx]:{loopRunId}}}` (`rails-router.ts:78-82`).
 - **`loopId`/`effort` are NOT persisted on the rail row.** `RailState` is still `{railIndex, ticketIds, mode, profileName, aiEngine, name}` (`rails-store.ts:3-13`); rails table cols are `rail_index, ticket_id, position, mode, profile_name, ai_engine` (`db.ts:236`), `name` in `rail_meta` (migration 28). `loopId` is purely a per-launch param; `reasoning_effort` persists only on `loop_runs.reasoning_effort`.
@@ -73,7 +73,7 @@ The list fetch never crashes (untyped maps, tolerant parsers). But a rail runnin
 Loop runs have a `loopRunId`, never a `jobId`, and are **not in the jobs/queue tables** (`loop-runs-store.ts:12-32`). The companion's "View running job log" routes by `jobId` (`rails_zone.dart:271-281`); `watch_job`/`log_batch`/`job_event` key on `jobId` (`mobile-ws.ts:196-243`). With no `jobId`, the job-tail surface never populates and the run is absent from Execution History (`JobHistoryScreen` reads queue jobs only). **Critically, a loop run produces NO tailable log at all** — its sole live heartbeat is `loop.run_progress` (`iteration`/`activeNode`), which is dropped at `topicFor()`. So even discounting the job-log routing, there is **no live-progress channel** for a running loop rail today: the running surface is a binary running/idle black box. For legacy non-loop launches the job-tail still WORKS.
 
 **(c) LAUNCH a rail — WORKS (factory/legacy only) / BROKEN (custom loops).**
-The companion sends bare `{mode}` (`rails_zone.dart:317` picker = `implement|batch-implement|ultracode`; `desktop_repository.dart:116-123`). This still validates server-side (`VALID_MODES` includes the three; default `mode='implement'` at `rails-router.ts:214`). Crucially, the gateway narrowing **strips `loopId`** (`mobile-router.ts:191-196`), so even a future companion that sent `loopId` would be silently ignored. Custom loops are unreachable (`mode='loop'` without `loopId` → 400, `rails-router.ts:385-386`). **Caveat:** the *running-state feedback* after launch is broken per (a)/(b) when the launch resolves to a `LoopRunManager` run (default-ON factory loops emit `loop.run_*`, no `rail.job_started`) — so the launch HTTP call succeeds (202) but the phone sees no live activity, no progress, and no completion notification.
+The companion sends bare `{mode}` (`rails_zone.dart:317` picker = `implement|batch-implement|freestyle`; `desktop_repository.dart:116-123`). This still validates server-side (`VALID_MODES` includes the three; default `mode='implement'` at `rails-router.ts:214`). Crucially, the gateway narrowing **strips `loopId`** (`mobile-router.ts:191-196`), so even a future companion that sent `loopId` would be silently ignored. Custom loops are unreachable (`mode='loop'` without `loopId` → 400, `rails-router.ts:385-386`). **Caveat:** the *running-state feedback* after launch is broken per (a)/(b) when the launch resolves to a `LoopRunManager` run (default-ON factory loops emit `loop.run_*`, no `rail.job_started`) — so the launch HTTP call succeeds (202) but the phone sees no live activity, no progress, and no completion notification.
 
 **(d) Stop / assign tickets / engine — DEGRADED (stop) / WORKS (tickets) / WORKS-with-display-drift (engine).**
 - **Engine:** `PUT /rails/:i/engine {aiEngine}` WORKS end-to-end for *setting* the override (`desktop_repository.dart:127`; `mobile-router.ts:199-206`); `rail.updated` carries `aiEngine` (`types.ts:749`). The mutation needs no change. **But** the *displayed* engine drifts for loop-backed runs as noted in (a): the rail config `aiEngine` may be null while the actual run used the resolved provider/model from `loop_runs`, which is never forwarded.
@@ -133,7 +133,7 @@ Extending `Job.fromJson` tolerance (`models.dart:73-85`) is unnecessary (loop ru
 - Tile subtitle (`:73-74, :87`) and sheet "Mode:" line (`:151, :218`): render `rail['loopName'] ?? rail['mode']` so a loop-running rail shows the loop identity, not stale `implement`. For engine, prefer the forwarded `rail['provider']`/`rail['model']` (4.3) over the possibly-null config `aiEngine`.
 - Running detection (`:72`): include `rail['loopRunId'] != null` so loop-running rails show Cancel, not Launch.
 - **Live-progress view:** for loop-backed rails, render `iteration`/`activeNode` from `loop.run_progress` (forwarded per 4.4) and/or poll `GET /v1/.../loop-runs/:id` (4.2) — this is the replacement for the `jobId` log tail that loop runs will never have. Do NOT route "View running job log" (`:271-281`) to `JobDetailScreen` by a null `jobId`; disable it or route to the loop-run progress view.
-- Launch picker (`confirmLaunchRail`, `:308-354, :317`): replace the hardcoded `implement|batch-implement|ultracode` bottom-sheet with a **Loop picker** populated from the new loop-catalog endpoint (4.2). Send `loopId` (factory or custom). Keep a fallback to bare `mode` for old-desktop compat (see phasing). For factory loops, the picker can offer the three factory ids (`factory:implement|factory:batch|factory:ultracode`).
+- Launch picker (`confirmLaunchRail`, `:308-354, :317`): replace the hardcoded `implement|batch-implement|freestyle` bottom-sheet with a **Loop picker** populated from the new loop-catalog endpoint (4.2). Send `loopId` (factory or custom). Keep a fallback to bare `mode` for old-desktop compat (see phasing). For factory loops, the picker can offer the three factory ids (`factory:implement|factory:batch|factory:freestyle`).
 
 **5.4 WS handlers for loop runs — `lib/features/project/project_shell.dart`.**
 `project_shell.dart:62-80` handles `rail.*` only. Add a `startsWith('loop.run_')` branch **inside** the existing inbound guard (`:62`, the `projectId`-filter) — loop runs ARE `projectId`-scoped (carried via `boundBroadcast`) so they pass the filter; read `m['projectId']` consistently so the branch isn't accidentally gated. The branch must: (a) invalidate `railsProvider`/`jobsProvider` (same as `rail.*` at `:67`); (b) on `loop.run_completed`, fire `NotificationService.jobOutcome` mapping the **success set `{success, max-iterations}`** → success (note `max-iterations` is a *successful* terminal state, NOT a failure — a naive `ok = status=='success'` mislabels it), mirroring the `rail.job_completed`/`status=='completed'` path at `:70-77`, using `loopRunId`/`ticketIds`.
@@ -196,4 +196,4 @@ Add the loop-catalog/loop-run read routes (4.2/5.5), the Loop picker UI (5.3), a
 
 - **Job-history blindness persists.** Loop runs live in `loop_runs`, not `jobs`/`queue` (`loop-runs-store.ts:12-32`), so they will not appear in the companion's Execution History or `Job`-model cost surfacing from WS fixes alone. The `GET /loop-runs/:id` read route (4.2) feeds the *running* surface; full history parity additionally needs a list route + a `LoopRun` model — flag as a follow-up beyond the mirror passes.
 
-- **Single point holding mobile launch alive.** The factory→legacy-mode mapping (`rails-router.ts:220-224`) plus the bare-`mode` default (`:214`) is the only thing keeping the v1 companion's launch working. If desktop ever removes bare-`mode` acceptance, the companion's `{mode}`-only `launchRail` (`desktop_repository.dart:116-123`) 400s. Treat bare-`mode` acceptance as frozen.
+- **Single point holding mobile launch alive.** The factory→legacy-mode mapping (`rails-router.ts:220-224`) plus the bare-`mode` default (`:214`) is the only thing keeping the v1 companion's launch working. If desktop ever removes bare-`mode` acceptance, the companion's `{mode}`-only `launchRail` (`desktop_repository.dart:116-123`) 400s. Treat bare-`mode` acceptance as frozen.

package/docs/internals/configuration.md

@@ -66,7 +66,7 @@ Project settings apply to a single project. Open them from the project's **Setti
 |---------|------------------|
 | **Pipeline Telemetry** | Opt-in toggle that injects OpenTelemetry env vars into pipeline job spawns so they emit OTLP signals back to the app. Off by default. |
 | **Rail Pre-prompt** | Text prepended to every rail launch for this project. |
-| **Ultracode pre-prompt** | Text prepended to Ultracode-mode launches (the Claude-only autonomous rail mode). |
+| **Freestyle pre-prompt** | Text prepended to Freestyle-mode launches (the Claude-only autonomous rail mode). |
 | **Budget** | Per-project daily spend cap (with queue auto-pause) and a per-job cost alert threshold. |
 | **Terminal Settings** | Per-project overrides for the terminal panel defaults (project override → app default → built-in). |
 

package/docs/internals/interactive-jobs.md

@@ -29,7 +29,7 @@ duplicate `result` frame can never be folded into the next turn's totals (BUG-IN
 
 ### The spike that unlocked the flip
 
-The original interactive path was ultracode-only because ultracode sends prose, not a slash
+The original interactive path was freestyle-only because freestyle sends prose, not a slash
 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
@@ -60,7 +60,7 @@ spawnInteractive = isInteractiveJobsEnabled()            // SPECRAILS_INTERACTIV
 
 | | `'finalize'` | `'auto'` |
 |---|---|---|
-| Who gets it | ultracode/Freestyle QueueManager jobs (claude) | every other interactive job + ALL loop ai-steps |
+| 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 |
 | Idle between turns | by design (awaiting the human) | only transiently (microtask window) |
 | Wedge detector | never armed | the queue's zombie-timeout budget, reset on any raw child output; silence for the whole budget → fold in-flight turn, settle `crashed` |
@@ -148,7 +148,7 @@ command didn't actually run, the settle is FAILED.**
   so the synthetic text would otherwise never appear in the log.
 - **QueueManager** (`_settleInteractiveJob`): a zero-work `'finalized'` settle stamps the job
   `'failed'` (exit code 1, failed `ai_invocations` row, dependents skipped) — **in both settle
-  modes**, so an ultracode Finalize after only the synthetic frame is also a failure. A canceled
+  modes**, so an freestyle Finalize after only the synthetic frame is also a failure. A canceled
   job stays `'canceled'`.
 - **LoopRunManager** (ai-steps): a zero-work settle makes the step's `AiStepResult` `failed` and
   its `loop_step_end` `status:'failed'`, and it **routes exactly like a crashed step** — the run

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

@@ -247,7 +247,7 @@ EVERY completed job/run promotes its tickets `todo|in_progress → on_review`, n
   "Per-run settle" above) — covering shared-cwd rail launches, standalone loop runs, and the
   isolation-unavailable fallback.
 - **QueueManager jobs** (`project-registry.ts` `onJobFinished`): bare-mode launches, MCP
-  `/spawn` jobs, ultracode Finalize, interactive auto-settles. `QueueManager._startJob` reads
+  `/spawn` jobs, freestyle Finalize, interactive auto-settles. `QueueManager._startJob` reads
   `isRailPrDeliveryEnabled()` ONCE per job at spawn — the SAME read that injects
   `SPECRAILS_GIT_AUTO=false` — records it in the in-memory `_jobPrDelivery` map (restart-durable
   by construction, like the interactive gate: a queued job surviving a restart recomputes at its

package/docs/internals/visual-design-audit.md

@@ -100,7 +100,7 @@ Prereq (fix #1): `npm i tw-animate-css` + `@import "tw-animate-css";` in `global
 6. `components/ProjectHealthWidget.tsx:51,92,110-124,141` + `components/HealthIndicatorBadge.tsx:28-31` — `#50fa7b/#f1fa8c/#ff5555` → `text-accent-success/text-accent-warning/text-destructive` (`var(--color-*)` for Recharts fills); ProjectHealthWidget:124 `AlertCircle` → `Ban`.
 7. `components/terminal/TerminalSearchOverlay.tsx:94,105-138` — `#f8f8f2/#6272a4/#44475a` → `text-foreground/bg-accent-primary/40/bg-muted`; `:107,115,126` `size={14}` → `className="w-3.5 h-3.5"`.
 8. `types/context-scope.ts:51-54` — `text-white` ×4 in `submitAccentForTier` → `text-background` (white on pastel accent-warning is unreadable).
-9. `components/UltracodeLaunchDialog.tsx:91` — `bg-emerald-500 text-white hover:bg-emerald-400 focus-visible:ring-emerald-400` → `bg-accent-success text-background hover:bg-accent-success/90 focus-visible:ring-accent-success`; `:58` `h-4.5 w-4.5` → `h-4 w-4` (only off-scale icon in the app).
+9. `components/FreestyleLaunchDialog.tsx:91` — `bg-emerald-500 text-white hover:bg-emerald-400 focus-visible:ring-emerald-400` → `bg-accent-success text-background hover:bg-accent-success/90 focus-visible:ring-accent-success`; `:58` `h-4.5 w-4.5` → `h-4 w-4` (only off-scale icon in the app).
 10. `components/RailControls.tsx:78-85` — raw red/emerald/amber + `aurora-light:` → `text-destructive/text-accent-success/text-accent-warning`; `:42` `hsl(191_97%_77%/0.22)` → `color-mix(in srgb, var(--color-accent-info) 22%, transparent)`; `:88` add `disabled:opacity-40`; bump button `h-5 w-5`→`h-7 w-7`, icon `w-2.5`→`w-3.5`.
 11. `components/RailsBoard.tsx:167` — `text-emerald-400 bg-emerald-400/10` → `text-accent-success bg-accent-success/10`.
 12. `components/ActiveJobCard.tsx:78,83` — `border-blue-500/30 bg-blue-500/5` / `text-blue-400` → `border-accent-info/30 bg-accent-info/5` / `text-accent-info` (copy JobStatusPanel:189).
@@ -171,7 +171,7 @@ A single idle rail exposes **13 controls, six of them 10px native `<select>`s ex
 **Stop guard:** Stop cancels N billed jobs — replace bare kill with a 5s undo toast (`ThemedToaster` action pattern, `App.tsx:434`) or a one-line confirm; no new component needed.
 
 ## 3.4 Reused components (nothing new except one popover)
-`ui/select.tsx` + `ui/tooltip.tsx` + `ui/dropdown` primitives (Radix, already shipped) · `PipelineProgress` (add a `variant="mini"` — h-1.5 bar + phase label) · `Badge` (post fix #3, for ticket/status chips) · `AgentActivityChip` crossfade pattern (copy verbatim for phase/status text) · `glow-*` utilities (`globals.css:345-350`) · `TicketDetailModalProvider` (compact ticket-pill clicks, unchanged) · `MoveToRailPopover`, `UltracodeLaunchDialog` (kept as-is, minus emerald CTA per fix #9) · existing WS events + `GET /rails` enrichment (`activeLoopRuns.loopName/provider/model/iteration` — zero server work to show run identity) · shared `<EmptyState>` (new, but mandated app-wide by §1.5). Compact density is **retired as a separate design system**: it becomes the same card with the body collapsed — the compact branch is already the token-correct one, so normal density adopts its token language rather than maintaining two.
+`ui/select.tsx` + `ui/tooltip.tsx` + `ui/dropdown` primitives (Radix, already shipped) · `PipelineProgress` (add a `variant="mini"` — h-1.5 bar + phase label) · `Badge` (post fix #3, for ticket/status chips) · `AgentActivityChip` crossfade pattern (copy verbatim for phase/status text) · `glow-*` utilities (`globals.css:345-350`) · `TicketDetailModalProvider` (compact ticket-pill clicks, unchanged) · `MoveToRailPopover`, `FreestyleLaunchDialog` (kept as-is, minus emerald CTA per fix #9) · existing WS events + `GET /rails` enrichment (`activeLoopRuns.loopName/provider/model/iteration` — zero server work to show run identity) · shared `<EmptyState>` (new, but mandated app-wide by §1.5). Compact density is **retired as a separate design system**: it becomes the same card with the body collapsed — the compact branch is already the token-correct one, so normal density adopts its token language rather than maintaining two.
 
 ## 3.5 Phased plan
 

package/docs/running-pipelines.md

@@ -80,7 +80,7 @@ In plain terms: the project's **agent profile** decides which AI agent handles e
 
 ### Freestyle
 
-`Freestyle` (mode value `ultracode` on the API — its original name) is a Claude-only loop that skips the Architect → Developer → Reviewer → Ship pipeline entirely. Instead of orchestrating the agent chain, it hands Claude a configurable pre-prompt plus the full spec text and lets it work autonomously with its native tools.
+`Freestyle` (mode value `freestyle` on the API — its original name) is a Claude-only loop that skips the Architect → Developer → Reviewer → Ship pipeline entirely. Instead of orchestrating the agent chain, it hands Claude a configurable pre-prompt plus the full spec text and lets it work autonomously with its native tools.
 
 - **One job per spec.** If the rail has three specs, `Freestyle` launches three independent jobs.
 - **Variable cost.** Because the run is open-ended, pressing Play opens a confirmation dialog before anything spawns.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.25.0",
+  "version": "2.26.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/agent-chat-manager.js

@@ -15,6 +15,7 @@ const agent_operator_prompt_1 = require("./agent-operator-prompt");
 const agent_mcp_config_1 = require("./agent-mcp-config");
 const agent_tier_1 = require("./agent-tier");
 const attachment_manager_1 = require("./attachment-manager");
+const agent_context_resolver_1 = require("./agent-context-resolver");
 const agent_store_1 = require("./agent-store");
 const explore_draft_title_1 = require("./explore-draft-title");
 const types_1 = require("./mcp/tools/types");
@@ -22,6 +23,7 @@ class AgentChatManager {
     _broadcast;
     _db;
     _port;
+    _registry;
     _active = new Map();
     /** Conversations with a turn in-flight but not yet spawned. Closes the TOCTOU
      *  window the attachment-extraction await opens between the busy guard and
@@ -37,10 +39,11 @@ class AgentChatManager {
      *  shutdown() can tree-kill them instead of orphaning them. Self-removed on
      *  'close'/'error'. */
     _auxProcesses = new Set();
-    constructor(broadcast, db, port) {
+    constructor(broadcast, db, port, registry) {
         this._broadcast = broadcast;
         this._db = db;
         this._port = port;
+        this._registry = registry ?? null;
     }
     /** True while a turn is streaming for this conversation. */
     isStreaming(conversationId) {
@@ -76,6 +79,7 @@ class AgentChatManager {
                 conversationId,
                 queueId,
                 text: userText,
+                contextRefs: options.contextRefs ?? [],
                 position: pending.length,
                 timestamp: new Date().toISOString(),
             });
@@ -101,6 +105,7 @@ class AgentChatManager {
                     conversationId,
                     queueId: next.queueId,
                     text: next.text,
+                    contextRefs: next.options.contextRefs ?? [],
                     timestamp: new Date().toISOString(),
                 });
                 await this._runTurnSafely(conv, next.text, next.options);
@@ -164,11 +169,19 @@ class AgentChatManager {
                 console.error(`[agent-chat] attachment extraction failed (${conversationId}):`, err);
             }
         }
+        const contextBlock = (0, agent_context_resolver_1.buildResolvedAgentContextBlock)(options.contextRefs ?? [], {
+            desktopDb: this._db,
+            registry: this._registry,
+            fallbackProjectId: conversation.pinned_project_id ?? null,
+        });
+        if (contextBlock) {
+            userWithAttachments = `${userWithAttachments}\n\n${contextBlock}`;
+        }
         // The conversation may have been deleted while attachments were extracting
         // (DELETE aborts the child and drops the row) — inserting would violate the FK.
         if (!(0, agent_store_1.getAgentConversation)(this._db, conversationId))
             return;
-        (0, agent_store_1.addAgentMessage)(this._db, { conversationId, role: 'user', content: userText, attachmentIds });
+        (0, agent_store_1.addAgentMessage)(this._db, { conversationId, role: 'user', content: userText, attachmentIds, contextRefs: options.contextRefs });
         this._autoTitle(conversationId, conversation.title);
         // Providers WITHOUT a --system-prompt flag (codex, gemini) drop opts.systemPrompt
         // for chat turns, so the attachment prompt-injection note would never reach them —
@@ -583,6 +596,7 @@ class AgentChatManager {
             conversationId,
             queueId,
             text,
+            contextRefs: item.options.contextRefs ?? [],
             timestamp: new Date().toISOString(),
         });
         return true;

package/server/dist/agent-chat-router.js

@@ -26,6 +26,70 @@ function validProvider(provider) {
         return null;
     }
 }
+const CONTEXT_KINDS = new Set(['project', 'spec', 'job', 'trace', 'conversation', 'file', 'alias', 'pr', 'action']);
+function cleanContextString(value, max) {
+    if (typeof value !== 'string')
+        return null;
+    const clean = value.replace(/[\r\n"]/g, ' ').trim().slice(0, max);
+    return clean || null;
+}
+function cleanContextMetadata(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const clean = {};
+    for (const [key, raw] of Object.entries(value).slice(0, 16)) {
+        const safeKey = cleanContextString(key, 80);
+        if (!safeKey)
+            continue;
+        if (raw === null || typeof raw === 'number' || typeof raw === 'boolean') {
+            clean[safeKey] = raw;
+        }
+        else if (typeof raw === 'string') {
+            const safeValue = cleanContextString(raw, 500);
+            if (safeValue !== null)
+                clean[safeKey] = safeValue;
+        }
+        else if (Array.isArray(raw)) {
+            clean[safeKey] = raw
+                .slice(0, 16)
+                .map((item) => (typeof item === 'string' ? cleanContextString(item, 240) :
+                typeof item === 'number' || typeof item === 'boolean' || item === null ? item :
+                    undefined))
+                .filter((item) => item !== undefined);
+        }
+    }
+    return Object.keys(clean).length ? clean : undefined;
+}
+function sanitizeContextRefs(value) {
+    if (!Array.isArray(value))
+        return [];
+    const refs = [];
+    for (const raw of value.slice(0, 16)) {
+        if (!raw || typeof raw !== 'object')
+            continue;
+        const row = raw;
+        const kind = cleanContextString(row.kind, 40);
+        const id = cleanContextString(row.id, 160);
+        const label = cleanContextString(row.label, 220);
+        const token = cleanContextString(row.token, 120);
+        if (!kind || !CONTEXT_KINDS.has(kind) || !id || !label || !token)
+            continue;
+        const scopeRaw = row.scope && typeof row.scope === 'object' ? row.scope : null;
+        const projectId = cleanContextString(scopeRaw?.projectId, 160);
+        const projectName = cleanContextString(scopeRaw?.projectName, 180);
+        const status = cleanContextString(row.status, 80);
+        refs.push({
+            kind,
+            id,
+            label,
+            token,
+            scope: projectId || projectName ? { projectId, projectName } : undefined,
+            status,
+            metadata: cleanContextMetadata(row.metadata),
+        });
+    }
+    return refs;
+}
 const attachmentUpload = (0, multer_1.default)({
     storage: multer_1.default.memoryStorage(),
     limits: { fileSize: 25 * 1024 * 1024 },
@@ -296,6 +360,7 @@ function createAgentChatRouter(deps) {
             attachmentIds = (rawAtt.ids).filter((x) => typeof x === 'string');
         }
         const queueId = typeof body.queueId === 'string' ? body.queueId : null;
+        const contextRefs = sanitizeContextRefs(body.contextRefs);
         // Fire-and-forget: the turn streams over WS. Persist the chosen tier first so
         // a refresh mid-turn restores the right level.
         if (tierLevel !== undefined)
@@ -304,7 +369,7 @@ function createAgentChatRouter(deps) {
         // synchronous frame (the enqueue happens before sendMessage's first await),
         // so the flag the client gets always matches what actually happened.
         const queued = manager.isBusy(conversation.id);
-        void manager.sendMessage(conversation.id, text, { tierLevel, model, attachmentIds, queueId }).catch((e) => console.error('[agent-chat] send failed:', e));
+        void manager.sendMessage(conversation.id, text, { tierLevel, model, attachmentIds, queueId, contextRefs }).catch((e) => console.error('[agent-chat] send failed:', e));
         res.status(202).json({ accepted: true, queued });
     });
     // Edit a still-queued (not yet dispatched) message in place. 409 when the