specrails-desktop 2.59.3 → 2.61.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

@@ -74,6 +74,8 @@ Project settings apply to a single project. Open them from the project's **Setti
 | **Freestyle pre-prompt** | Text prepended to Freestyle-mode launches (Claude and Kimi advertise this 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). |
+| **Verification commands** | Repository checks Core runs after the developer finishes; failures go back to the developer (or the fixer). Stored under `verification` in `.specrails/agent-runtime.json`; an empty list lets the architect propose the project's own checks. |
+| **Setup commands** | Idempotent commands Core runs inside the repository checkout before every verification plan, for example `npx playwright install chromium`. Same entry shape as `verification` (`repositoryId`, `command`, `args`, optional `cwd`, `env`, `timeoutMs`, `key`, `label`), stored under `setup`, no auto-detection. Credential-like `env` keys are refused and `key` values must be unique across `setup` and `verification`. A failing setup command ends the run as blocked by the host environment. The list reaches Core only when the installed Core advertises the `setupCommands` capability; older cores receive the configuration without it and the run log records a one-line note. |
 
 > The project's **provider(s)** — **Claude, Codex, Gemini, Kimi, or any
 > compatible combination** — are chosen when you add the project and are

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

@@ -13,15 +13,15 @@ framework is rejected rather than silently replacing an update.
 
 ## Persistence and publication
 
-The release bundle pins Core 6.2.1 in `desktop-release.yml` and
+The release bundle pins Core 6.4.0 in `desktop-release.yml` and
 `scripts/assemble-bundled-core.lock.json`. Core 6 is the Desktop-only engine: it
 publishes integration contract 5.1 (no standalone `update`) and ships only the
 implement and retry workflows (Batch was folded into implement; Desktop no
 longer requires `batch-implement` but stays compatible with Cores that still ship it). Update both pins together and check compatibility against
 the staged published package; retained runs still use their original runtime.
 
-The paired CI checkout uses the immutable Core 6.2.1 release commit
-`ae52a5ff0ff9dce024008adf16115e7f04d1ef35`. Bundle smoke checks use Node 22.22.3,
+The paired CI checkout uses the immutable Core 6.4.0 release commit
+`aa00781e962a30c22bbcdecc632bc2abcf3c97d2`. Bundle smoke checks use Node 22.22.3,
 matching Core's minimum supported Node version and the Desktop release runtime.
 
 Desktop updates retain the complete npm installation, including dependencies,
@@ -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/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/programmatic-agent-runtime.md

@@ -119,6 +119,8 @@ All routes are under `/api/projects/:projectId`:
 | `POST /agent-runtime/runs/:runId/resume` | Accept `{}`, `{ "approve": ["archive"] }`, `{ "recover": ["developer"] }`, explicit `invalidate` phase IDs, or `{ "answer": "…" }` for a pending question (required while one is open) |
 | `POST /agent-runtime/runs/:runId/cancel` | Cancel a continuation owned by this controller |
 
+Host blockers (Core `hostBlockers: 1` / `setupCommands: 1`): the Implement recipe opts its `verify` nodes into host-owned environment repair and the `blocked` outcome. Core emits `[environment] <command> (<repository>)` and `Environment: installed …` lines on the `verification-output` channel, so they reach the readable job log through the same projection as checks. A precondition Core cannot satisfy (no network for a browser download, registry credentials, a failing `setup` command, a missing toolchain) ends the run at `host-blocked` with `completion.blocker = { kind, reason, command, args, cwd, requiredAction, evidenceId? }`; a fixer-declared `blocker` ends it at `fixer-blocked`. The bridge maps that completion (`ok: false`) to `runtimeStatus: 'blocked'`, the run row shows the blocked badge and the loop log renders "Blocked by the host environment" with the localized kind, the failing command and cwd, the required action and a copy button. Older Core packages receive the pre-blocker definition and no `setup` list.
+
 Resume responds `202` after admission and continues asynchronously. Legacy phase IDs are `architect`, `developer`, `fixer`, `verify`, `reviewer` and `archive`. For engine v2, use `POST /loop-runs/:runId/resume` instead. `recover` contains exact attempt IDs from `GET /loop-runs/:runId/recovery`; approval and answer controls use pending interrupt IDs. Node paths are display context, not recovery identities. The saved-execution panel and job header expose explicit per-attempt selection. Core's lease and Desktop's execution/mount claim jointly prevent competing writers. Resident human pauses keep their original settlement callback; restart recovery reconnects to the frozen delivery allocation and terminal outbox.
 
 Desktop launches `node <Core>/dist/agent-runtime/cli.js` with structured argv (`--approve`, `--recover`, `--invalidate`, `--answer <text>` on resume) and consumes JSON lines for phase events (`workflow-event`), agent output (`agent-event`), verification output, trace spans (`span`: `{ traceId, spanId, name, stepId, attempt, visit, startedAt, endedAt, status, usage?, error? }`) and the terminal `runtime-result`. Spans are stored verbatim as job events for diagnostics and are not narrated in the log. `runtime status --compact` returns `state.traceId`, `pendingApproval`, `pendingQuestion` and per-step `{ status, visits }`. Desktop probes `runtime api` once per executable package content digest; `runtime validate --stdin` runs on every save. The job log shows phase transitions (`[runtime] step_started: developer`), live tool activity per role (`[developer] Read src/app.ts`, `[developer] Bash npm test`) and Core's own phase notes (architecture written, verification passed, review approved or corrections requested); the final JSON of architect and reviewer is not echoed. The narrated view (Relato) derives its milestones from the same events: each runtime phase, the tools used, correction loops and a stopped workflow with Core's structural reason. Accounting uses the invocation's new attempts, so resuming a completed phase does not bill its cumulative history twice. Status queries use `--compact`, are read-only and do not invoke providers; accumulated logs stay in Core's checkpoint instead of overflowing the process status response.

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/source-map.md

@@ -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)

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.3",
+  "version": "2.61.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/mcp/guide.js

@@ -385,9 +385,10 @@ can run Contract Refine require AI-spawn, including Explore conversions.
 - **Plugins** (\`specrails_plugins\`): per-project MCP integrations; \`preview\`
   the diff before \`install\`; a degraded plugin never blocks rail launches.
 - **Profiles** (\`specrails_agents\`): per-project agent chains; the baseline
-  trio \`sr-architect\`/\`sr-developer\`/\`sr-reviewer\` is required; routing rules
-  end in a single terminal \`default: true\` rule; requires specrails-core
-  4.1.0 or newer.
+  trio \`sr-architect\`/\`sr-developer\`/\`sr-reviewer\` are role identifiers
+  defined by the specrails-core runtime (no installed files) and are required
+  in every chain; routing rules end in a single terminal \`default: true\` rule;
+  requires specrails-core 4.1.0 or newer.
 - **Setup** (\`specrails_setup\`): \`prerequisites\` → \`add_project\` →
   \`install_config\` per provider → ONE \`install\` (provisions all chosen
   providers; quick-only, offline) → poll \`checkpoints\` until

package/server/dist/modules/agent-runtime/runtime/agent-runtime-bridge.js

@@ -148,20 +148,36 @@ async function runAgentRuntimeInvocation(options) {
         if (!Array.isArray(admittedContext.repositories) || !admittedContext.repositories.length || admittedContext.repositories.some(repo => !repo || typeof repo.id !== 'string' || !repo.id))
             throw new Error('Core context is missing its repository scope');
         const source = (0, node_fs_1.existsSync)(options.configPath) ? 'project-role' : 'default';
-        const { config, origins } = (0, agent_runtime_effective_config_1.resolveEffectiveRuntimeConfig)(options.loopConfig ? (0, agent_runtime_settings_1.loadLoopRuntimeConfig)(options.configPath, options.loopConfig, options.providerOverride ?? { provider: options.defaultProvider ?? 'claude' }) : (0, agent_runtime_settings_1.loadRuntimeConfigFile)(options.configPath, options.defaultProvider), {
+        // The engine owns the factory role definitions; the user's global overrides sit on top. The Implement
+        // rail merges them under any project text, and loop recipes resolve their `inherit` definitions here.
+        const effectiveRolePrompts = { ...(await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).rolePromptDefaults(), ...(0, agent_runtime_settings_1.loadRuntimeRolePrompts)() };
+        const loopConfig = options.loopConfig && (0, agent_runtime_settings_1.resolveInheritedRolePrompts)(options.loopConfig, effectiveRolePrompts);
+        const { config, origins } = (0, agent_runtime_effective_config_1.resolveEffectiveRuntimeConfig)(loopConfig ? (0, agent_runtime_settings_1.loadLoopRuntimeConfig)(options.configPath, loopConfig, options.providerOverride ?? { provider: options.defaultProvider ?? 'claude' }) : (0, agent_runtime_settings_1.loadRuntimeConfigFile)(options.configPath, options.defaultProvider), {
             repositoryIds: admittedContext.repositories.map(repo => repo.id), source: options.loopConfig ? 'loop-role' : source, providerOverride: options.loopConfig ? undefined : options.providerOverride,
         });
         config.verification = scopedHostChecks(config.verification, admittedContext.repositories);
         if (definitionEngine)
             completeHostChecks(config, admittedContext.repositories);
-        if (!options.loopConfig)
-            config.rolePrompts = { ...(await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).rolePromptDefaults(), ...(0, agent_runtime_settings_1.loadRuntimeRolePrompts)(), ...config.rolePrompts };
+        if (!loopConfig)
+            config.rolePrompts = { ...effectiveRolePrompts, ...config.rolePrompts };
         // Core rejects unknown connection keys: drop the desktop-only local-engine
         // fields (label/defaultModel/rates/supportsReasoningEffort) before Core sees it.
         const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
         config.providers = (0, agent_runtime_settings_1.stripDesktopConnectionFields)(config.providers, (0, agent_runtime_settings_1.coreConnectionFieldGates)(runtime.api?.capabilities));
         if (runtime.api?.capabilities?.configurableGuardrails !== 1)
             delete config.guardrails;
+        // Setup commands are a `setupCommands` capability: an older Core rejects the unknown key, so strip it and say so once in the run log.
+        if (config.setup !== undefined && !(0, agent_runtime_settings_1.coreSupportsSetupCommands)(runtime.api?.capabilities)) {
+            if (config.setup.length) {
+                try {
+                    options.onLine?.(`[runtime] setup commands ignored: the installed Core does not advertise setupCommands (${config.setup.length} configured)\n`);
+                }
+                catch { /* Advisory log observer. */ }
+            }
+            delete config.setup;
+        }
+        else if (config.setup)
+            config.setup = scopedHostChecks(config.setup, admittedContext.repositories);
         if (definitionEngine && (runtime.api?.capabilities?.engineV2 !== 1 || runtime.api?.capabilities?.workflowDefinitions !== 1))
             throw new Error('engine_unsupported: Update Core to run workflow definitions');
         const compilationConfig = structuredClone(config);

package/server/dist/modules/agent-runtime/runtime/agent-runtime-effective-config.js

@@ -76,6 +76,8 @@ function resolveEffectiveRuntimeConfig(input, options) {
         }
     fillDefaultRoleModels(config);
     config.verification = config.verification.filter(check => options.repositoryIds.includes(check.repositoryId));
+    if (config.setup)
+        config.setup = config.setup.filter(check => options.repositoryIds.includes(check.repositoryId));
     return { config, origins: { architect: override ? 'explicit-launch-override' : options.source, developer: override ? 'explicit-launch-override' : options.source, reviewer: override ? 'explicit-launch-override' : options.source } };
 }
 /**

package/server/dist/modules/agent-runtime/runtime/agent-runtime-settings-router.js

@@ -21,6 +21,10 @@ function withDefaultRoleModels(body) {
     return { ...body, agents: filled.agents, ...(filled.roles ? { roles: filled.roles } : {}), ...(filled.fixer ? { fixer: filled.fixer } : {}) };
 }
 const loop_role_engines_1 = require("../../loops/runtime/loop-role-engines");
+/** The settings API always answers `setup` as an array; the file keeps it absent until the user saves one. */
+function withSetupList(config) {
+    return config ? { ...config, setup: config.setup ?? [] } : config;
+}
 function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
     /** Guardrail catalog of the loaded Core (configurable-guardrails): ids + phase; the UI owns labels. `supported:false` on older cores. */
     router.get('/:projectId/agent-runtime/guardrails', async (_req, res) => {
@@ -70,7 +74,7 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
                 openRolesAvailable = capabilities?.openRoles === 1;
             }
             catch { /* Ordinary settings remain readable without capability support. */ }
-            res.json({ configured, config, runtimeAvailable: (0, agent_runtime_loader_1.findCoreAgentRuntimeEntry)() !== null, efficiencyAvailable, openRolesAvailable,
+            res.json({ configured, config: withSetupList(config), runtimeAvailable: (0, agent_runtime_loader_1.findCoreAgentRuntimeEntry)() !== null, efficiencyAvailable, openRolesAvailable,
                 workflowRoleDefaults: openRolesAvailable && config ? (0, agent_runtime_effective_config_1.workflowRoleDefaults)(config) : {} });
         }
         catch (err) {
@@ -147,7 +151,7 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
                 }
             }
             const saved = (0, agent_runtime_settings_1.saveAgentRuntimeConfig)(ctx(req).project, config);
-            res.json({ configured: true, config: saved, runtimeAvailable, efficiencyAvailable, openRolesAvailable });
+            res.json({ configured: true, config: withSetupList(saved), runtimeAvailable, efficiencyAvailable, openRolesAvailable });
         }
         catch (err) {
             const validation = err instanceof agent_runtime_settings_1.AgentRuntimeConfigError;

package/server/dist/modules/agent-runtime/runtime/agent-runtime-settings.js

@@ -3,7 +3,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
     return (mod && mod.__esModule) ? mod : { "default": mod };
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.AgentRuntimeConfigError = exports.REVIEW_THRESHOLD_FLOORS = exports.MAX_OUTPUT_TOKENS_MAX = exports.MAX_OUTPUT_TOKENS_MIN = exports.CONTEXT_WINDOW_TOKENS_MAX = exports.CONTEXT_WINDOW_TOKENS_MIN = exports.RUNTIME_ROLE_ID = void 0;
+exports.INHERIT_ROLE_PROMPT = exports.AgentRuntimeConfigError = exports.REVIEW_THRESHOLD_FLOORS = exports.MAX_OUTPUT_TOKENS_MAX = exports.MAX_OUTPUT_TOKENS_MIN = exports.CONTEXT_WINDOW_TOKENS_MAX = exports.CONTEXT_WINDOW_TOKENS_MIN = exports.RUNTIME_ROLE_ID = void 0;
 exports.stripDesktopConnectionFields = stripDesktopConnectionFields;
 exports.coreConnectionFieldGates = coreConnectionFieldGates;
 exports.validateLoopRuntimeSettings = validateLoopRuntimeSettings;
@@ -18,11 +18,14 @@ exports.saveRuntimeProviders = saveRuntimeProviders;
 exports.loadRuntimeConfigFile = loadRuntimeConfigFile;
 exports.loadAgentRuntimeConfig = loadAgentRuntimeConfig;
 exports.saveAgentRuntimeConfig = saveAgentRuntimeConfig;
+exports.inheritedRolePrompt = inheritedRolePrompt;
+exports.resolveInheritedRolePrompts = resolveInheritedRolePrompts;
 exports.validateRuntimeRolePrompts = validateRuntimeRolePrompts;
 exports.loadRuntimeRolePrompts = loadRuntimeRolePrompts;
 exports.saveRuntimeRolePrompts = saveRuntimeRolePrompts;
 exports.validateRuntimeProviderOverride = validateRuntimeProviderOverride;
 exports.forCoreRuntime = forCoreRuntime;
+exports.coreSupportsSetupCommands = coreSupportsSetupCommands;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
@@ -134,17 +137,18 @@ function validateLoopRuntimeSettings(input, providers = loadRuntimeProviders())
     const config = validateAgentRuntimeConfig({ ...input, enabled: true, providers: portableProviders, verification: [] });
     if (['architect', 'developer', 'reviewer', 'fixer'].some(role => !config.rolePrompts?.[role]?.trim()))
         throw new AgentRuntimeConfigError('Loop agents require an explicit definition for architect, developer, reviewer and fixer');
-    const { enabled: _enabled, providers: _providers, verification: _checks, ...settings } = config;
+    const { enabled: _enabled, providers: _providers, verification: _checks, setup: _setup, ...settings } = config;
     return settings;
 }
 /** Read only repository checks from the old project file. Role migration is explicit. */
 function loadLoopRuntimeConfig(file, input, selection = { provider: 'claude' }) {
-    let verification = [];
+    let verification = [], setup = undefined;
     try {
         const saved = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
         if (!saved || typeof saved !== 'object' || Array.isArray(saved))
             throw new AgentRuntimeConfigError('Saved runtime configuration must be an object');
         verification = saved.verification ?? [];
+        setup = saved.setup;
     }
     catch (error) {
         if (error.code !== 'ENOENT')
@@ -161,7 +165,7 @@ function loadLoopRuntimeConfig(file, input, selection = { provider: 'claude' })
         settings.fixer = inherit(settings.fixer);
     for (const [role, agent] of Object.entries(settings.roles ?? {}))
         settings.roles[role] = inherit(agent);
-    return validateAgentRuntimeConfig({ ...settings, providers, enabled: true, verification });
+    return validateAgentRuntimeConfig({ ...settings, providers, enabled: true, verification, ...(setup !== undefined ? { setup } : {}) });
 }
 const CLI_PROVIDERS = ['claude', 'codex', 'gemini', 'kimi'];
 const ROLES = ['architect', 'developer', 'reviewer'];
@@ -258,10 +262,12 @@ function validateAgentRuntimeConfig(input) {
         if (!Number.isFinite(value) || (key !== 'maxCostUsd' && !Number.isSafeInteger(value)))
             throw new AgentRuntimeConfigError('Workflow limits must be finite, safe numbers');
     }
-    const keys = config.verification.flatMap(command => command.key ? [command.key] : []);
+    // `setup` entries share the verification entry shape and rules (Core validates both with one validator; keys are unique across the two lists).
+    const hostCommands = [...config.verification, ...(config.setup ?? [])];
+    const keys = hostCommands.flatMap(command => command.key ? [command.key] : []);
     if (new Set(keys).size !== keys.length)
         throw new AgentRuntimeConfigError('Verification check keys must be unique');
-    for (const command of config.verification) {
+    for (const command of hostCommands) {
         for (const value of [command.label, ...(command.policy?.inputs ?? []), ...(command.policy?.toolchainInputs ?? []), ...(command.policy?.resources ?? [])])
             if (value !== undefined && (!value.trim() || value.includes('\0')))
                 throw new AgentRuntimeConfigError('Invalid verification label or policy input');
@@ -419,6 +425,27 @@ function saveAgentRuntimeConfig(project, input) {
     return config;
 }
 const PROMPT_ROLES = [...ROLES, 'fixer'];
+/** A loop recipe definition that follows the engine: resolved at launch to the selected Core's factory definition plus the user's global override. */
+exports.INHERIT_ROLE_PROMPT = 'inherit';
+const INHERITED_ROLE_PROMPT = /^inherit:(architect|developer|reviewer|fixer)$/;
+/** The prompt a declared recipe role carries when it follows a built-in definition (`inherit:<role>`), or the recipe's own text. */
+function inheritedRolePrompt(prompts, role) {
+    const value = prompts?.[role];
+    return value === undefined || value === exports.INHERIT_ROLE_PROMPT ? `${exports.INHERIT_ROLE_PROMPT}:${role}` : value;
+}
+/** Replace `inherit` definitions (built-in roles) and `inherit:<role>` prompts (declared roles) with the effective engine definitions. Explicit recipe text is kept verbatim. */
+function resolveInheritedRolePrompts(settings, effective) {
+    // A Core predating the fixer stance has no fixer default: the fixer then follows the developer definition.
+    const resolved = { ...effective, fixer: effective.fixer ?? effective.developer };
+    const lookup = (role) => resolved[role];
+    const rolePrompts = settings.rolePrompts && Object.fromEntries(Object.entries(settings.rolePrompts).map(([role, text]) => [role, text === exports.INHERIT_ROLE_PROMPT ? lookup(role) ?? text : text]));
+    const roles = settings.roles && Object.fromEntries(Object.entries(settings.roles).map(([id, role]) => {
+        const inherited = role.prompt?.match(INHERITED_ROLE_PROMPT);
+        const text = inherited ? lookup(inherited[1]) : undefined;
+        return [id, text ? { ...role, prompt: text } : role];
+    }));
+    return { ...settings, ...(rolePrompts ? { rolePrompts } : {}), ...(roles ? { roles } : {}) };
+}
 function validateRuntimeRolePrompts(input, extraRoles = []) {
     if (!input || typeof input !== 'object' || Array.isArray(input))
         throw new AgentRuntimeConfigError('Role prompts must be an object');
@@ -459,7 +486,7 @@ function validateRuntimeProviderOverride(value) {
         throw new AgentRuntimeConfigError('Invalid runtime provider override effort');
     return structuredClone(raw);
 }
-/** Older Core runtimes reject unknown top-level keys: drop `guardrails` unless the loaded Core advertises `configurableGuardrails`. */
+/** Older Core runtimes reject unknown top-level keys: drop `guardrails` unless the loaded Core advertises `configurableGuardrails`, and `setup` unless it advertises `setupCommands`. */
 function forCoreRuntime(config, capabilities) {
     let out = config;
     if (capabilities?.openRoles !== 1 && out.roles !== undefined) {
@@ -472,6 +499,10 @@ function forCoreRuntime(config, capabilities) {
         const { guardrails: _dropped, ...rest } = out;
         out = rest;
     }
+    if (!coreSupportsSetupCommands(capabilities) && out.setup !== undefined) {
+        const { setup: _dropped, ...rest } = out;
+        out = rest;
+    }
     // The per-role thinking switch is known only to cores advertising `roleThinkingControl`.
     if (capabilities?.roleThinkingControl !== 1 && ([...Object.values(out.agents ?? {}), ...Object.values(out.roles ?? {})].some(agent => agent?.thinking !== undefined) || out.fixer?.thinking !== undefined)) {
         const strip = (agent) => { const { thinking: _t, ...rest } = agent; return rest; };
@@ -479,3 +510,7 @@ function forCoreRuntime(config, capabilities) {
     }
     return out;
 }
+/** Core advertises `setupCommands: 1` when its verify piece runs `RuntimeConfig.setup` before each verification plan. */
+function coreSupportsSetupCommands(capabilities) {
+    return (capabilities?.setupCommands ?? 0) >= 1;
+}

package/server/dist/modules/agents/runtime/profiles-router.js

@@ -18,6 +18,8 @@ const providers_1 = require("../../../providers");
 const kimi_skill_prompt_1 = require("../../../providers/kimi-skill-prompt");
 const profile_manager_1 = require("./profile-manager");
 const workspace_resolution_1 = require("../../../workspace-resolution");
+const agent_runtime_loader_1 = require("../../agent-runtime/runtime/agent-runtime-loader");
+const agent_runtime_settings_1 = require("../../agent-runtime/runtime/agent-runtime-settings");
 const project_router_helpers_1 = require("../../../project-router-helpers");
 /**
  * Relocate-artifacts gate: the dir whose `.specrails/{profiles,specrails-version}`
@@ -70,6 +72,30 @@ function agentsCatalogDir(project, provider) {
 function listAgentFiles(project, provider) {
     return (0, agent_catalog_1.listNativeAgentFiles)(specRoot(project), provider ?? project.provider ?? 'claude');
 }
+/**
+ * The baseline roles are identifiers of runtime-defined roles: specrails-core
+ * never reads an `sr-*` file for them. Their read-only catalog body is the Core
+ * runtime definition (defaults merged with the global Settings overrides).
+ */
+const BASELINE_RUNTIME_ROLES = {
+    'sr-architect': 'architect',
+    'sr-developer': 'developer',
+    'sr-reviewer': 'reviewer',
+};
+const RUNTIME_DEFINED_DESCRIPTION = 'Runtime-defined by specrails-core: the implement pipeline runs this role from the Core runtime definition below, not from an installed file.';
+async function loadRuntimeRoleDefinitions() {
+    try {
+        const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
+        return { prompts: { ...runtime.rolePromptDefaults(), ...(0, agent_runtime_settings_1.loadRuntimeRolePrompts)() } };
+    }
+    catch (error) {
+        return { prompts: {}, error: error instanceof Error ? error.message : 'Core role prompt catalog is unavailable' };
+    }
+}
+function runtimeRoleBody(definitions, agentId) {
+    const role = BASELINE_RUNTIME_ROLES[agentId];
+    return role ? definitions.prompts[role] : undefined;
+}
 const AGENTS_SECTION_ENABLED = process.env.SPECRAILS_AGENTS_SECTION !== 'false';
 function handleError(res, err) {
     if (err instanceof profile_manager_1.ProfileValidationError) {
@@ -175,12 +201,11 @@ function createProfilesRouter() {
                 ? new Map((0, project_router_helpers_1.readAgentModels)({ ...project, provider })
                     .map((entry) => [entry.name, entry.model]))
                 : null;
-            const agentsDir = agentsCatalogDir(project, provider);
-            if (!fs_1.default.existsSync(agentsDir)) {
-                res.status(400).json({ error: `no ${adapter.projectDirName} roles catalog found` });
-                return;
-            }
+            const baseline = [...adapter.baselineAgents()];
             const agents = [];
+            // Role files are optional: Core >= 6.3 defines the baseline roles in its
+            // runtime. Read `model:` only from `sr-*` files that still exist (older
+            // installs); every other baseline id is seeded with the adapter default.
             for (const entry of listAgentFiles(project, provider)) {
                 if (!entry.id.startsWith('sr-'))
                     continue;
@@ -202,13 +227,10 @@ function createProfilesRouter() {
                 }
                 agents.push({ id, model });
             }
-            const baseline = [...adapter.baselineAgents()];
-            const missing = baseline.filter((id) => !agents.some((a) => a.id === id));
-            if (missing.length > 0) {
-                res.status(400).json({
-                    error: `missing baseline agents in this project: ${missing.join(', ')}. Run 'npx specrails-core@latest update' first.`,
-                });
-                return;
+            for (const id of baseline) {
+                if (agents.some((a) => a.id === id))
+                    continue;
+                agents.push({ id, model: projectedKimiModels?.get(id) ?? adapter.defaultModel() });
             }
             // Order: baseline trio first (architect, developer, reviewer), optional
             // agents in the middle. sr-merge-resolver is no longer a baseline agent;
@@ -379,39 +401,44 @@ function createProfilesRouter() {
         }
     });
     // GET /api/projects/:projectId/profiles/catalog
-    // List all roles in the selected provider-native catalog (sr-* + custom-*).
-    router.get('/catalog', (req, res) => {
+    // List the selected provider's roles: the runtime-defined baseline (upstream,
+    // synthesized from the adapter) plus the native `custom-*` catalog.
+    router.get('/catalog', async (req, res) => {
         try {
             const { project } = ctx(req);
             const provider = requestedProvider(req, project);
-            const files = listAgentFiles(project, provider);
-            if (files.length === 0) {
-                res.json({ agents: [] });
-                return;
-            }
+            const adapter = projectAdapter(project, provider);
             const agents = [];
-            for (const entry of files) {
+            // Baseline roles never depend on `sr-*` files; a missing roles directory
+            // still yields the three runtime-defined entries.
+            const definitions = await loadRuntimeRoleDefinitions();
+            for (const id of adapter.baselineAgents()) {
+                agents.push({
+                    id,
+                    kind: 'upstream',
+                    description: RUNTIME_DEFINED_DESCRIPTION,
+                    body: runtimeRoleBody(definitions, id) ?? '',
+                    roleId: BASELINE_RUNTIME_ROLES[id],
+                    ...(definitions.error ? { runtimeRoleError: definitions.error } : {}),
+                });
+            }
+            for (const entry of listAgentFiles(project, provider)) {
                 const id = entry.id;
-                const kind = id.startsWith('sr-')
-                    ? 'upstream'
-                    : id.startsWith('custom-')
-                        ? 'custom'
-                        : null;
-                if (!kind)
+                // Stale `sr-*` files from older Cores are not catalog entries anymore.
+                if (!id.startsWith('custom-'))
                     continue;
+                const kind = 'custom';
                 let description;
                 let model;
                 let projected = {};
                 try {
                     const body = fs_1.default.readFileSync(entry.file, 'utf8');
-                    if (kind === 'custom') {
-                        try {
-                            const result = (0, agent_role_descriptor_1.projectCustomAgentRole)({ id, content: body }, { provider });
-                            projected = { roleId: result.id, runtimeRoleDefaults: result.role };
-                        }
-                        catch (error) {
-                            projected = { runtimeRoleError: error instanceof Error ? error.message : 'Invalid Core role descriptor' };
-                        }
+                    try {
+                        const result = (0, agent_role_descriptor_1.projectCustomAgentRole)({ id, content: body }, { provider });
+                        projected = { roleId: result.id, runtimeRoleDefaults: result.role };
+                    }
+                    catch (error) {
+                        projected = { runtimeRoleError: error instanceof Error ? error.message : 'Invalid Core role descriptor' };
                     }
                     if (provider === 'kimi') {
                         // Use the same js-yaml metadata parser as validation/execution so
@@ -468,8 +495,9 @@ function createProfilesRouter() {
         }
     });
     // GET /api/projects/:projectId/profiles/catalog/:agentId
-    // Return the full .md body of a single agent file (read-only for sr-*, editable for custom-*)
-    router.get('/catalog/:agentId', (req, res) => {
+    // Return the full body of a single agent: the Core runtime definition for a
+    // baseline role (read-only), the native file for custom-* (editable).
+    router.get('/catalog/:agentId', async (req, res) => {
         try {
             const { project } = ctx(req);
             const provider = requestedProvider(req, project);
@@ -480,6 +508,16 @@ function createProfilesRouter() {
             }
             const file = agentFile(project, agentId, provider);
             if (!fs_1.default.existsSync(file)) {
+                if (projectAdapter(project, provider).baselineAgents().includes(agentId)) {
+                    const definitions = await loadRuntimeRoleDefinitions();
+                    const body = runtimeRoleBody(definitions, agentId);
+                    if (body !== undefined) {
+                        res.json({ id: agentId, body, runtimeDefined: true });
+                        return;
+                    }
+                    res.status(503).json({ error: definitions.error ?? 'Core role prompt catalog is unavailable' });
+                    return;
+                }
                 res.status(404).json({ error: 'agent not found' });
                 return;
             }