specrails-desktop 2.59.2 → 2.60.0

package/docs/internals/adding-a-provider.md

@@ -61,7 +61,7 @@ export const exampleAdapter: ProviderAdapter = {
   buildArgs: (action: SpawnAction, opts: SpawnOptions): string[] => { /* per-action argv */ },
   parseStreamLine: (line: string): AdapterEvent | null => { /* line → canonical event */ },
   extractResult: (events): NormalisedResult => { /* events → tokens/cost/session */ },
-  baselineAgents: () => ['sr-architect', 'sr-developer', 'sr-reviewer'],
+  baselineAgents: () => ['sr-architect', 'sr-developer', 'sr-reviewer'], // role identifiers, not installed files
   detectInstalled: async (): Promise<DetectionResult> => { /* `which` + `--version` */ },
   // Optional — see "(Optional) prepareHeadlessSpawn" below. Gemini uses it to
   // pre-acknowledge project subagents so they load in headless `gemini -p` rails.
@@ -79,11 +79,12 @@ the optional
 `prepareHeadlessSpawn` hook, `systemPromptArg: false` system-prompt folding
 (via the `GEMINI_SYSTEM_MD` env), native OTEL with `nativeCostUsd: false`,
 and a per-action `buildArgs` switch that throws defensively on the
-`chat-stream` action it doesn't support. Note the shipped baseline is the
-three-agent trio `['sr-architect', 'sr-developer', 'sr-reviewer']`;
-`ProfileManager` validation requires exactly your `baselineAgents()` to
-be present in every profile chain, so don't add agents your scaffold
-won't actually create.
+`chat-stream` action it doesn't support. Note the baseline is the
+three role identifiers `['sr-architect', 'sr-developer', 'sr-reviewer']`;
+they name roles the Core runtime defines, not files your scaffold installs,
+and installation detection is never derived from them. `ProfileManager`
+validation requires exactly your `baselineAgents()` to be present in every
+profile chain, so don't add identifiers the runtime won't actually route.
 
 The `SpawnAction` union also includes **`chat-stream`** — used by the
 Explore persistent-stdin fast-path and interactive jobs. Only providers

package/docs/internals/configuration.md

@@ -82,6 +82,31 @@ Project settings apply to a single project. Open them from the project's **Setti
 
 ---
 
+## Jira status mapping and pending updates
+
+In the project's Jira connector, map **To Do**, **In Progress**, **On Review**,
+**Done** and **Cancelled** to the real Jira statuses you want to use. Automatic
+uses Jira's status categories; an explicit selection uses the selected status
+identity, even when its category differs. The API accepts status names or status
+IDs, never transition IDs. Both
+outbound transitions and inbound polling honor the mapping. When several logical
+states share a destination, On Review retains precedence; other ambiguities use
+the category-derived state. Prefer distinct destinations when possible.
+
+The pending-updates panel identifies the issue and requested destination. After
+correcting a mapping or a Jira workflow restriction, retry the current failed
+operation. A failed transition replaced by a later status intention is retained
+as `superseded` history and removed from attention counts; retrying it cannot
+revert newer work. Comments and field updates remain independently retryable.
+Older pending retries are also suppressed when a newer status transition has
+already completed. Normal pending operations retain their per-issue FIFO order.
+
+Jira still determines which transitions the signed-in account can apply. A
+missing reverse transition cannot be bypassed by selecting a target, and the
+connector does not move through arbitrary statuses to discover possible paths.
+If loading the status list fails, the connector preserves the saved mapping and
+offers a retry instead of silently reducing the picker to Automatic.
+
 ## CLI
 
 The `specrails-desktop` CLI is documented in full in [../cli.md](../cli.md). Quick reference:
@@ -134,6 +159,26 @@ specrails-desktop --port 5000 implement "#42"
 
 ## Environment variables
 
+### Project execution environment
+
+Project Settings stores the **names** of environment variables to pass through,
+such as `NODE_AUTH_TOKEN`; it never stores their values. One parent project setting
+applies to every repository and workspace admitted to its rails, including isolated
+worktrees. The same policy is applied to retained runtime controls and recovery.
+
+Non-empty values already inherited by Desktop take precedence. For missing configured names
+on macOS/Linux, Desktop probes the login shell, using `SHELL` or the account's login
+shell when a GUI launch does not supply it. A zsh login shell reads `~/.zprofile`
+(and interactive configuration); configure the real credential there rather than
+adding it to tracked repository files. Windows uses its inherited environment.
+
+Recovered values stay in a project-owned in-memory overlay, not the server's global
+environment, SQLite or runtime snapshots. Each project's lookup cache expires after
+30 seconds, including failed/empty results, so a repaired profile or rotated shell
+credential can be picked up without restarting Desktop. Removing a configured name
+drops its recovered value immediately. A missing value remains absent: Desktop never
+substitutes a dummy credential or treats a blocked package-manager command as passed.
+
 A few env vars are read directly by the app. The two most useful operational ones:
 
 | Variable | Description |

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

@@ -68,6 +68,25 @@ all workspace refreshes and the final recovery-state write succeed.
 Core 6 registry updates and same-version runtime repairs are offered using the
 same supported-major policy as runtime selection.
 
+## Role definitions follow the engine
+
+Core owns how the implement roles think: `rolePromptDefaults()` returns the
+factory architect, developer, reviewer and fixer definitions (one shared senior
+engineer identity, blast-radius discipline, quality bar and the mandatory
+OpenSpec binding). Desktop owns the workflows that use those roles, and never
+keeps a copy of those definitions.
+
+- The Implement rail (engine 1) reads the defaults from the selected Core at
+  launch, merged with the user's global overrides from Settings.
+- Loop recipes store `inherit` for the built-in definitions (and
+  `inherit:<role>` for declared recipe roles such as `plan`/`build`). The
+  launch bridge resolves them to the same Core defaults plus global overrides
+  and freezes the result with the run, so every loop follows the installed
+  Core automatically. Text the user edits in the loop editor is stored verbatim
+  and stays frozen with the loop; "Use the Core definition" returns a role to
+  `inherit`. `/api/loop-agent-defaults` returns `rolePromptDefaults` so the
+  editor can preview what `inherit` resolves to today.
+
 ## Version reporting
 
 Global status distinguishes the selected runtime and its source, the active

package/docs/internals/loop-step-log-explorer.md

@@ -147,6 +147,33 @@ One chip per graph node, states `pending → running → ok / failed / interrupt
 - **Filtering** searches every section: while the filter is non-empty, all sections are treated as expanded; clearing it restores the previous mode.
 - **Copy**: each step header carries its own copy button (per-step lines only; the control lives outside the toggle so the header stays a valid button), and the toolbar copy grabs the whole log with `── Step N · title ──` separators.
 
+### Verbose verification and retained display
+
+Desktop compacts verification output before publishing readable log lines. Passing
+cases and repeated console stacks no longer flood the rail; bounded diagnostic
+context, final test totals and recorded command outcomes remain visible. Omission
+notices distinguish a concise display from the original runtime evidence. This
+changes presentation only, including when tests print warnings or errors but exit
+successfully; recorded exit codes and workflow completion remain authoritative.
+
+Both job detail surfaces omit invisible raw `verification-output` events from
+their in-memory display buffer and preserve lifecycle markers when bounding
+ordinary output. A translated notice indicates when earlier readable output was
+removed and that Copy contains only the retained view. Initial history and live
+updates use the same retention rules. Persisted events are unchanged.
+
+For detailed verification output, expand **Details → Verification evidence** and
+open a check's stdout or stderr, using the next-page control as needed. These are
+the retained Core artifacts: currently up to 1 MiB per stream, with truncation
+reported explicitly. They follow the configured runtime retention policy and are
+not an unlimited archive. Compaction does not rewrite historical logs in storage.
+
+Readable runtime lines preserve an optional recorded `attemptId` in both stored
+log payloads and live WebSocket frames. The existing attempt map uses it to attach
+buffered verification summaries to their originating step, including parallel
+attempts. Older lines without that identity retain their existing arrival-order
+fallback; Desktop does not invent an attempt ID.
+
 ## Performance
 
 - **Collapsed sections render nothing** — the body subtree is not mounted, so a 10k-line settled step costs one header row.

package/docs/internals/mission-rail-cards.md

@@ -48,6 +48,13 @@ with allocation rollback and the original failed checkout retained. A synchronou
 click guard prevents duplicate submissions; accepted relaunches stay disabled
 until the new card appears, and rejected admission details remain inline.
 
+Workspace narrowing is optional: when a delivery manifest has no explicit
+workspace selections, Relaunch omits `workspaceSelection` and uses registered
+defaults for its recorded repositories. Partial selections remain partial and
+saved explicit selections take precedence; invalid selections still fail normal
+admission. Removing the last repository with a workspace override from a launch
+card also omits the property, instead of sending an invalid empty map.
+
 ```rail-launch
 {
   "version": 1,

package/docs/internals/profiles.md

@@ -21,20 +21,22 @@ Dashboard/Jobs/Analytics/Settings).
 - **Profiles** tab — create and edit profiles.
 - **Usage** tab — see which profiles are actually being used (backed by
   the `/analytics` endpoint covered in section 8).
-- **Catalog** tab — read the upstream `sr-*` agents or author custom
-  `custom-*` ones via the Studio.
+- **Catalog** tab — read the runtime-defined baseline roles (`sr-architect`,
+  `sr-developer`, `sr-reviewer`, shown read-only with the definition the Core
+  runtime executes) or author custom `custom-*` ones via the Studio.
 
 When the project has no profiles yet, the empty state offers two entry
 points:
 
-- **Migrate from current agents** — reads the primary provider's native role
-  catalog (`.claude/agents/` or `.kimi-code/skills/`) and creates a
-  `default` profile mirroring today's behavior. It requires the baseline trio
-  `sr-architect`, `sr-developer`, and `sr-reviewer` to be present — the
-  server rejects the migration if any is missing. Provider-specific model
-  identifiers are retained only when they are in that provider's catalog;
-  otherwise migration uses its default and stamps the provider into the saved
-  profile.
+- **Migrate from current agents** — seeds the baseline trio `sr-architect`,
+  `sr-developer` and `sr-reviewer` as role identifiers with the provider's
+  default model, reads the primary provider's native role catalog
+  (`.claude/agents/` or `.kimi-code/skills/`) for custom roles and creates a
+  `default` profile mirroring today's behavior. No `sr-*` file has to exist:
+  a `model:` is read only from role files an older install still carries.
+  Provider-specific model identifiers are retained only when they are in that
+  provider's catalog; otherwise migration uses its default and stamps the
+  provider into the saved profile.
 - **Blank profile** — start from scratch.
 
 ## 2. Saved profiles vs selection
@@ -128,6 +130,11 @@ template/duplicate/edit and rail execution remain available.
   `sr-developer`. Fix the listed issues and Save re-enables.
 - **"agent 'xyz' already exists" (409)** — the name collides with an
   existing provider role. Pick a different name.
+- **No `.claude/agents/sr-*.md` in the project** — expected. The baseline
+  roles are defined by the Core runtime, not installed as files; read them in
+  the Catalog tab and edit their definitions, provider and model in
+  **Settings → Agent runtime**. Files left behind by an older Core are
+  tolerated until Core prunes them.
 - **The whole Agents section is missing** — it can be disabled server-side
   with `SPECRAILS_AGENTS_SECTION=false`, which 404s the entire
   `/profiles` router. Unset it (or leave it at its default) to restore the

package/docs/internals/review-packet.md

@@ -140,7 +140,7 @@ one-active-generation-per-rail all come free from the shipped machinery.
 
 **The loop.** `factory:revision` is the fourth factory loop: `{{cmd:revise}}` (a
 distilled step that applies the one requested change on top of the branch and
-then runs `sr-reviewer` over the resulting diff, so packet v2 keeps its reviewer
+then runs the reviewer role (`sr-reviewer`) over the resulting diff, so packet v2 keeps its reviewer
 tier) followed by the standard `{{cmd:verify}}`. No Architect step — the plan and
 the code already exist. It is resolvable by id but deliberately NOT listed in the
 public catalog: its prompt consumes `{{const:REVISION_REQUEST}}`, which only a

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

@@ -124,6 +124,15 @@ Both temporary checkouts use non-force cleanup, including after a Git runner exc
   recording the failed replacement id so every client can safely undo its tombstone for that pair.
 - Isolation units remain `per-ticket` or one `all`-scope batch unit. Initial/final SHAs plus commit
   verification distinguish changed, resumed, and no-change results.
+- Warm dependency preparation preserves a registered directory's position inside its Git checkout.
+  For example, registering `apps/catalog` prepares its installed packages and Yarn state beneath
+  `worktree/apps/catalog/node_modules`. Discovery stays relative to the registered directory
+  (depth at most two); unrelated root and sibling installations are not selected. Package entries
+  link to the source installation, while tool caches remain local. Existing real installations and
+  foreign links are preserved. Live cleanup uses the same projection and exact target fingerprints,
+  including proofs for historical misplaced links; symlinked destination ancestors confer no
+  authority. Registration paths, frozen manifests and Core scope remain unchanged. A failed run
+  keeps its old checkout; after updating Desktop, a fresh Relaunch receives the corrected layout.
 - Per-unit settlement returns structured execution + delivery results. `onLoopRunFinished` receives
   the engine outcome only; commit/status/ref/provenance/push failures cannot rewrite it.
 - Before staging, settlement blocks active OpenSpec change directories introduced relative to

package/docs/internals/source-map.md

@@ -5,7 +5,7 @@ architectural dependency declaration. Search a heading or filename and read only
 the relevant source and tests. Feature prefixes group the legacy server files;
 new bounded modules live under `server/modules/`.
 
-Includes 1014 source/build files. Nearby tests are linked where names
+Includes 1018 source/build files. Nearby tests are linked where names
 match; integration suites may live elsewhere. Use `rg` to find other consumers.
 
 ## cli
@@ -79,7 +79,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 
 - [AgentRoleFields.tsx](../../client/src/features/agents/components/AgentRoleFields.tsx) · [test](../../client/src/features/agents/components/__tests__/AgentRoleFields.test.tsx)
 - [AgentStudio.tsx](../../client/src/features/agents/components/AgentStudio.tsx)
-- [AgentsCatalogTab.tsx](../../client/src/features/agents/components/AgentsCatalogTab.tsx)
+- [AgentsCatalogTab.tsx](../../client/src/features/agents/components/AgentsCatalogTab.tsx) · [test](../../client/src/features/agents/components/__tests__/AgentsCatalogTab.test.tsx)
 - [AiRefineOverlay.tsx](../../client/src/features/agents/components/AiRefineOverlay.tsx)
 - [ProfileAnalyticsCard.tsx](../../client/src/features/agents/components/ProfileAnalyticsCard.tsx)
 - [ProfileEditor.tsx](../../client/src/features/agents/components/ProfileEditor.tsx) · [test](../../client/src/features/agents/components/__tests__/ProfileEditor.test.tsx)
@@ -317,6 +317,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [DiscardSpecDialog.tsx](../../client/src/features/integrations/components/jira/DiscardSpecDialog.tsx) · [test](../../client/src/features/integrations/components/jira/__tests__/DiscardSpecDialog.test.tsx)
 - [JiraConnectWizard.tsx](../../client/src/features/integrations/components/jira/JiraConnectWizard.tsx) · [test](../../client/src/features/integrations/components/jira/__tests__/JiraConnectWizard.test.tsx)
 - [JiraConnectedCard.tsx](../../client/src/features/integrations/components/jira/JiraConnectedCard.tsx)
+- [JiraOutboxPanel.tsx](../../client/src/features/integrations/components/jira/JiraOutboxPanel.tsx) · [test](../../client/src/features/integrations/components/jira/__tests__/JiraOutboxPanel.test.tsx)
 - [JiraSpecDetailsPanel.tsx](../../client/src/features/integrations/components/jira/JiraSpecDetailsPanel.tsx) · [test](../../client/src/features/integrations/components/jira/__tests__/JiraSpecDetailsPanel.test.tsx)
 
 ## client/src/features/integrations/context
@@ -365,6 +366,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 ## client/src/features/jobs/lib
 
 - [cancel-job.ts](../../client/src/features/jobs/lib/cancel-job.ts) · [test](../../client/src/features/jobs/lib/__tests__/cancel-job.test.ts)
+- [job-event-buffer.ts](../../client/src/features/jobs/lib/job-event-buffer.ts) · [test](../../client/src/features/jobs/lib/__tests__/job-event-buffer.test.ts)
 - [job-log-mode.ts](../../client/src/features/jobs/lib/job-log-mode.ts)
 - [job-time.ts](../../client/src/features/jobs/lib/job-time.ts)
 
@@ -1093,6 +1095,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 - [agent-runtime-settings-router.ts](../../server/modules/agent-runtime/runtime/agent-runtime-settings-router.ts)
 - [agent-runtime-settings.ts](../../server/modules/agent-runtime/runtime/agent-runtime-settings.ts) · [test](../../server/modules/agent-runtime/runtime/agent-runtime-settings.test.ts)
 - [agent-runtime-settlement.ts](../../server/modules/agent-runtime/runtime/agent-runtime-settlement.ts) · [test](../../server/modules/agent-runtime/runtime/agent-runtime-settlement.test.ts)
+- [agent-runtime-verification-log.ts](../../server/modules/agent-runtime/runtime/agent-runtime-verification-log.ts)
 - [agent-runtime-verification-suggestions.ts](../../server/modules/agent-runtime/runtime/agent-runtime-verification-suggestions.ts) · [test](../../server/modules/agent-runtime/runtime/agent-runtime-verification-suggestions.test.ts)
 
 ## server/modules/agents/runtime
@@ -1424,6 +1427,7 @@ match; integration suites may live elsewhere. Use `rg` to find other consumers.
 
 ## server/util
 
+- [checkout-path.ts](../../server/util/checkout-path.ts)
 - [cli-prompt.ts](../../server/util/cli-prompt.ts) · [test](../../server/util/cli-prompt.test.ts)
 - [distribute-int.ts](../../server/util/distribute-int.ts)
 - [secure-fs.ts](../../server/util/secure-fs.ts) · [test](../../server/util/secure-fs.test.ts)

package/docs/jira-integration-plan.md

@@ -190,16 +190,18 @@ Por qué token‑paste y no OAuth en v1:
 
 ## 6. Ciclo de vida y mapeo de estados (la parte difícil)
 
-Los issues de Jira **no tienen un campo `status` asignable** — hay que **transicionar**, y las transiciones están **gateadas por el workflow** del cliente (que es arbitrario). Las 4 lógicas de Specrails (`todo/in_progress/done/cancelled`) deben caer sobre N estados de cliente repartidos en solo **3 categorías estables**: `new` / `indeterminate` / `done` (`statusCategory.key`).
+Los issues de Jira **no tienen un campo `status` asignable** — hay que **transicionar**, y las transiciones están **gateadas por el workflow** del cliente (que es arbitrario). Las 5 lógicas de Specrails (`todo/in_progress/on_review/done/cancelled`) deben caer sobre N estados de cliente repartidos en solo **3 categorías estables**: `new` / `indeterminate` / `done` (`statusCategory.key`).
 
 ### Resolver de dos niveles
 
 1. **Mapa explícito por proyecto gana siempre.** En Settings el usuario elige, de la **lista real de estados** de su proyecto (fetched en vivo), el target para cada estado lógico. Esto resuelve la ambigüedad (p.ej. dos estados sobre categoría `done`: `Released` vs `Won't Do`).
 2. **Fallback por categoría** cuando no hay mapa: anclar en `statusCategory.key` (nunca en el **nombre** localizable del estado). Para `cancelled`, preferir un *cancel‑lexicon* (`won't do`, `cancelled`, `rejected`, `abandoned`, `invalid`, `duplicate`) y fijar `resolution`; para `done`/éxito, preferir un *ship‑lexicon* (`done`, `closed`, `released`, `resolved`, `complete`) y **alejarse** del cancel‑lexicon.
 
-### Camino de transición — BFS por saltos
+El mapa también se respeta al materializar Jira en la caché local para los cinco estados lógicos. Si varios estados comparten destino, `on_review` mantiene su prioridad histórica; para otras ambigüedades se conserva la interpretación por categoría.
 
-Como solo ves las transiciones salientes del estado **actual**, un workflow `Backlog → Selected for Dev → In Progress → Done` no ofrece arista directa a `Done`. Algoritmo: `GET /transitions` del issue vivo → aplicar la arista que reduce la distancia a la categoría objetivo (orden `new < indeterminate < done`) → re‑`GET` → repetir. Cap ~5 saltos, dedup de estados visitados (evitar bucles), parar si ninguna transición reduce distancia. **Idempotency‑first**: si la categoría actual ya es la objetivo, **no‑op**. Si no hay camino en N saltos → **dead‑letter** no‑fatal ("mover estado manualmente en Jira") y **jamás** se hace error del rail.
+### Camino de transición — recorrido acotado por categorías
+
+Como solo ves las transiciones salientes del estado **actual**, un workflow `Backlog → Selected for Dev → In Progress → Done` no ofrece arista directa a `Done`. Algoritmo: `GET /transitions` del issue vivo → aplicar la arista que reduce la distancia a la categoría objetivo (orden `new < indeterminate < done`) → re‑`GET` → repetir. Cap ~5 saltos, dedup de estados visitados (evitar bucles), parar si ninguna transición reduce distancia. **Idempotency‑first**: si hay destino explícito, comparar primero su ID/nombre con el estado actual, incluso si pertenece a otra categoría. Sin destino explícito, la categoría objetivo permite el **no‑op**. Un estado intermedio de la categoría esperada no completa un destino explícito diferente. Este recorrido no explora estados laterales modificando Jira a ciegas. Si no hay camino en N saltos → **dead‑letter** no‑fatal ("mover estado manualmente en Jira") y **jamás** se hace error del rail.
 
 ### Pantallas de transición / campos requeridos
 
@@ -238,10 +240,11 @@ Diseño de poll:
 ### Outbound — outbox durable
 
 - Drenaje en worker de fondo: **FIFO por‑issue** (una transición debe aterrizar antes que el comentario que la describe), **paralelo entre issues distintos**, con cap de concurrencia.
-- **Idempotencia:** transiciones por no‑op‑si‑ya‑en‑categoría; **comentarios** con un *self‑marker* invisible embebido en el body ADF (`[specrails:job-<id>]`) — Jira no tiene idempotencia nativa de comentarios, así que antes de re‑postear se hace `GET .../comment` y se salta si el marker ya existe. El marker dobla como filtro de auto‑eco en el poll.
+- **Idempotencia:** transiciones por identidad explícita ID/nombre y, sin mapa, por categoría; **comentarios** con un *self‑marker* invisible embebido en el body ADF (`[specrails:job-<id>]`) — Jira no tiene idempotencia nativa de comentarios, así que antes de re‑postear se hace `GET .../comment` y se salta si el marker ya existe. El marker dobla como filtro de auto‑eco en el poll.
 - **Rate limits:** honrar `Retry-After` en 429 exacto; si ausente, backoff exponencial con jitter (base 2s, cap 30s, ~4 reintentos); respetar el techo ~20 writes/2s por issue. Token‑bucket por debajo de los burst caps.
 - **Clasificación de errores:** `401` = credencial → **pausar** outbox del proyecto + banner re‑auth (no reintentar en bucle); `403` = permiso de operación concreta → dead‑letter nombrando la operación ("tu cuenta no puede transicionar en PROJ"), sin inferir fallo global; `404` sobre issue conocido = terminal (issue borrado/movido) → marcar link `orphaned`, parar la op; solo `429/5xx/timeout` son reintentables.
 - **Dead‑letter visible** con reintento manual: `GET /jira/outbox`, `POST /jira/outbox/:id/retry`, indicador `JiraSyncIndicator` en UI. Un workflow‑gap o un 403 **nunca** es un drop silencioso.
+- **Operaciones reemplazadas:** las transiciones fallidas con una intención posterior para el mismo issue se conservan como `superseded`, fuera del contador de atención y sin reintento. Un reintento antiguo ya encolado tampoco se aplica si una transición posterior ya terminó. Se conservan el FIFO normal y los comentarios/ediciones independientes. El panel identifica el issue y el destino, y muestra errores al cargar los estados con una acción de reintento.
 
 ---
 

package/docs/running-pipelines.md

@@ -173,9 +173,9 @@ Without profiles, every rail uses the project's frontmatter-baked models. With p
 Open **Agents** in the project's right sidebar. Two sub-tabs:
 
 - **Profiles** — full CRUD over `.specrails/profiles/*.json`. The live validator enforces the baseline trio and routing ordering — Save is disabled with an "N issues to resolve" hint while the profile is broken.
-- **Agents Catalog** — read-only viewer of upstream `sr-*` agents and your `custom-*` agents.
+- **Agents Catalog** — read-only viewer of the runtime-defined baseline roles (`sr-architect`, `sr-developer`, `sr-reviewer`, shown with the definition the Core runtime actually executes) and your `custom-*` agents.
 
-The empty state offers **Migrate from current agents**: one click creates a `default` profile mirroring today's frontmatter.
+The empty state offers **Migrate from current agents**: one click creates a `default` profile from the baseline roles and your existing custom agents — no role file has to exist for it to work.
 
 Each profile gets a per-profile analytics card showing usage for the last 7 / 30 / 90 days: jobs, success rate, avg tokens, avg duration.
 

package/package.json

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

package/server/dist/core-compat.js

@@ -19,8 +19,8 @@ const bundled_core_1 = require("./bundled-core");
 const core_runtime_1 = require("./core-runtime");
 // Windows has no `which`; probe PATH via `where` instead.
 const WHICH_CMD = process.platform === 'win32' ? 'where' : 'which';
-/** Paired development target; older supported contracts remain compatible. */
-exports.EXPECTED_CORE_CONTRACT_SCHEMA_VERSION = '5.1';
+/** Paired development target; older supported contracts (5.1) remain compatible. */
+exports.EXPECTED_CORE_CONTRACT_SCHEMA_VERSION = '5.2';
 // These must mirror KNOWN_VERBS in cli/specrails-desktop.ts
 const DESKTOP_KNOWN_COMMANDS = new Set([
     'implement',
@@ -29,6 +29,10 @@ const DESKTOP_KNOWN_COMMANDS = new Set([
 // Commands older Cores still ship that Desktop no longer invokes. They are
 // tolerated (not drift) but never required: Batch was folded into implement.
 const DESKTOP_TOLERATED_LEGACY_COMMANDS = new Set(['batch-implement']);
+// Checkpoints that contract 5.1 still declares but Desktop retired: role agents
+// are runtime-defined since contract 5.2, so `agent_generation` is tolerated
+// (not drift) and never required.
+const DESKTOP_TOLERATED_LEGACY_CHECKPOINTS = new Set(['agent_generation']);
 function isRecord(value) {
     return typeof value === 'object' && value !== null && !Array.isArray(value);
 }
@@ -233,7 +237,7 @@ async function checkCoreCompat() {
         : (contract.checkpoints && typeof contract.checkpoints === 'object'
             ? Object.keys(contract.checkpoints)
             : []);
-    const missingCheckpoints = contractCheckpoints.filter((c) => !desktopCheckpointKeys.includes(c));
+    const missingCheckpoints = contractCheckpoints.filter((c) => !desktopCheckpointKeys.includes(c) && !DESKTOP_TOLERATED_LEGACY_CHECKPOINTS.has(c));
     const deterministic = contract.lifecycle?.mode === 'deterministic' && contract.lifecycle.requiresEnrich === false;
     // Supporting legacy installation checkpoints is compatible with Core 5;
     // demanding them from a deterministic installer would recreate enrich.

package/server/dist/core-execution.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.checkoutSubdirectory = checkoutSubdirectory;
+exports.checkoutSubdirectory = void 0;
 exports.prepareCoreExecution = prepareCoreExecution;
 exports.coreVerificationContext = coreVerificationContext;
 exports.checkCoreCompletion = checkCoreCompletion;
@@ -10,6 +10,9 @@ const node_path_1 = require("node:path");
 const core_node_runtime_1 = require("./core-node-runtime");
 const core_update_state_1 = require("./core-update-state");
 const agent_runtime_loader_1 = require("./modules/agent-runtime/runtime/agent-runtime-loader");
+const checkout_path_1 = require("./util/checkout-path");
+var checkout_path_2 = require("./util/checkout-path");
+Object.defineProperty(exports, "checkoutSubdirectory", { enumerable: true, get: function () { return checkout_path_2.checkoutSubdirectory; } });
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 // Resolve existing ancestors too: the tickets file may not exist yet, and macOS
 // exposes temporary directories through both /var and /private/var.
@@ -26,22 +29,6 @@ function canonicalPath(path) {
         return (0, node_path_1.join)(canonicalPath(parent), (0, node_path_1.basename)(path));
     }
 }
-/** Where a directory sits inside its git checkout: '' for the checkout root or a directory outside git. */
-function checkoutSubdirectory(directory) {
-    let start;
-    try {
-        start = (0, node_fs_1.realpathSync)(directory);
-    }
-    catch {
-        return '';
-    }
-    for (let current = start;; current = (0, node_path_1.dirname)(current)) {
-        if ((0, node_fs_1.existsSync)((0, node_path_1.join)(current, '.git')))
-            return (0, node_path_1.relative)(current, start).split(node_path_1.sep).join('/');
-        if ((0, node_path_1.dirname)(current) === current)
-            return '';
-    }
-}
 /**
  * A registered repository may be one package of a larger git checkout (a
  * monorepo app). An isolated worktree always mounts the whole checkout, so the
@@ -54,7 +41,7 @@ function registeredScope(checkout, sourcePath) {
     (0, node_fs_1.realpathSync)(sourcePath);
     const local = (0, node_path_1.relative)(checkout, sourcePath).split(node_path_1.sep).join('/');
     const contained = local && local !== '..' && !local.startsWith('../') && !(0, node_path_1.isAbsolute)(local);
-    const prefix = checkoutSubdirectory(checkout) ? (contained ? local : '') : checkoutSubdirectory(sourcePath) || (contained ? local : '');
+    const prefix = (0, checkout_path_1.checkoutSubdirectory)(checkout) ? (contained ? local : '') : (0, checkout_path_1.checkoutSubdirectory)(sourcePath) || (contained ? local : '');
     if (!prefix)
         return undefined;
     if (!(0, node_fs_1.statSync)((0, node_path_1.join)(checkout, ...prefix.split('/'))).isDirectory())

package/server/dist/jira/jira-db.js

@@ -33,6 +33,7 @@ exports.markOutboxDone = markOutboxDone;
 exports.markOutboxRetry = markOutboxRetry;
 exports.markOutboxDead = markOutboxDead;
 exports.resetInflight = resetInflight;
+exports.reconcileSupersededTransitions = reconcileSupersededTransitions;
 exports.retryDeadOutbox = retryDeadOutbox;
 exports.listOutbox = listOutbox;
 exports.countOutboxByState = countOutboxByState;
@@ -328,12 +329,38 @@ function resetInflight(db) {
         .run(new Date().toISOString());
     return info.changes;
 }
-/** Re-queue a dead-lettered op for a manual retry. */
+/**
+ * Preserve obsolete failed status intentions as terminal history rather than
+ * offering a retry that could revert a newer intention. Ordinary pending and
+ * inflight operations retain FIFO ownership. A pending row with a newer DONE
+ * transition is an old retry (normal FIFO cannot produce that ordering).
+ * Comments and field edits are independent operations and never superseded.
+ */
+function reconcileSupersededTransitions(db) {
+    return db.prepare(`UPDATE jira_outbox AS candidate
+        SET state = 'superseded', next_attempt_at = NULL, updated_at = ?
+      WHERE candidate.op_type = 'transition'
+        AND candidate.state IN ('dead', 'pending')
+        AND EXISTS (
+          SELECT 1 FROM jira_outbox AS newer
+           WHERE newer.jira_issue_id = candidate.jira_issue_id
+             AND newer.op_type = 'transition'
+             AND newer.id > candidate.id
+             AND (candidate.state = 'dead' OR newer.state = 'done')
+        )`).run(new Date().toISOString()).changes;
+}
+/** Reconcile and re-queue atomically, so an obsolete intention is never revived. */
 function retryDeadOutbox(db, id) {
-    const info = db
-        .prepare("UPDATE jira_outbox SET state = 'pending', next_attempt_at = NULL, dead_reason = NULL, last_error = NULL, updated_at = ? WHERE id = ? AND state = 'dead'")
-        .run(new Date().toISOString(), id);
-    return info.changes > 0;
+    return db.transaction(() => {
+        reconcileSupersededTransitions(db);
+        const row = db.prepare('SELECT state FROM jira_outbox WHERE id = ?').get(id);
+        if (row?.state === 'superseded')
+            return 'superseded';
+        if (row?.state !== 'dead')
+            return null;
+        db.prepare("UPDATE jira_outbox SET state = 'pending', next_attempt_at = NULL, dead_reason = NULL, last_error = NULL, updated_at = ? WHERE id = ? AND state = 'dead'").run(new Date().toISOString(), id);
+        return 'pending';
+    })();
 }
 function listOutbox(db, opts = {}) {
     const limit = Math.min(opts.limit ?? 200, 1000);
@@ -344,7 +371,7 @@ function listOutbox(db, opts = {}) {
 }
 function countOutboxByState(db) {
     const rows = db.prepare('SELECT state, COUNT(*) AS n FROM jira_outbox GROUP BY state').all();
-    const out = { pending: 0, inflight: 0, done: 0, dead: 0 };
+    const out = { pending: 0, inflight: 0, done: 0, dead: 0, superseded: 0 };
     for (const r of rows) {
         if (r.state in out)
             out[r.state] = r.n;

package/server/dist/jira/jira-materializer.js

@@ -37,19 +37,21 @@ function issueStatusCategory(issue) {
     return k === 'new' || k === 'done' ? k : 'indeterminate';
 }
 /**
- * Map a Jira issue's status to a Specrails ticket status. When the connection
- * has an explicit `statusMap.on_review` and the issue's status NAME equals it
- * (case-insensitive), the inbound status is preserved as `on_review` — the
- * category fallback alone would flatten it to `in_progress` and silently revert
- * a ticket parked at on_review once its outbox transition drains (the frozen
- * guard only protects the pending window). Unconfigured ⇒ byte-identical
- * category mapping.
+ * Explicit status identities apply in both sync directions, even when a
+ * customer's category differs from the logical state's default. Preserve the
+ * historical on_review precedence for shared mappings; other ambiguous targets
+ * retain category fallback rather than choosing by configuration object order.
  */
 function mapStatus(issue, statusMap) {
     const name = (issue.fields.status?.name ?? '').toLowerCase();
-    const onReviewTarget = statusMap?.on_review;
-    if (onReviewTarget && name && name === onReviewTarget.toLowerCase())
+    const matches = (target) => Boolean(target
+        && (issue.fields.status?.id === target || (name && name === target.toLowerCase())));
+    if (matches(statusMap?.on_review))
         return 'on_review';
+    const states = ['todo', 'in_progress', 'done', 'cancelled'];
+    const mapped = states.filter((state) => matches(statusMap?.[state]));
+    if (mapped.length === 1)
+        return mapped[0];
     const cat = issueStatusCategory(issue);
     if (cat === 'new')
         return 'todo';