specrails-desktop 2.47.0 → 2.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.47.0",
+  "version": "2.48.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -17,6 +17,7 @@
     "server/dist",
     "client/dist",
     "mcp-bridge/dist",
+    "local-runner/dist",
     "docs",
     ".claude/commands/specrails"
   ],
@@ -25,20 +26,21 @@
     "dev:server": "tsx watch server/index.ts",
     "dev:client": "cd client && npm run dev",
     "dev:desktop": "tauri dev",
-    "dev:desktop:prepare": "npm run build:sidecar && npm run build:mcp-bridge && npm run dev:client",
+    "dev:desktop:prepare": "npm run build:sidecar && npm run build:mcp-bridge && npm run build:local-runner && npm run dev:client",
     "build:server": "node -e \"require('fs').rmSync('server/dist',{recursive:true,force:true})\" && tsc --project tsconfig.build.json --noCheck && node scripts/copy-server-assets.mjs",
     "build:cli": "tsc --project tsconfig.cli.json",
-    "build": "npm run build:server && npm run build --prefix client && npm run build:cli && npm run build:mcp-bridge",
+    "build": "npm run build:server && npm run build --prefix client && npm run build:cli && npm run build:mcp-bridge && npm run build:local-runner",
     "prepack": "npm run build",
     "test:scripts": "node scripts/test-scripts.mjs",
     "check:package": "node scripts/check-package.mjs",
     "build:sidecar": "node scripts/build-sidecar.mjs",
     "build:mcp-bridge": "node scripts/build-mcp-bridge.mjs",
-    "build:desktop": "npm run build:server && cd client && npm run build && cd .. && npm run build:sidecar && npm run build:mcp-bridge && tauri build",
+    "build:local-runner": "node scripts/build-local-runner.mjs",
+    "build:desktop": "npm run build:server && cd client && npm run build && cd .. && npm run build:sidecar && npm run build:mcp-bridge && npm run build:local-runner && tauri build",
     "assemble-runtimes": "node scripts/assemble-runtimes-local.mjs",
     "build:desktop:local": "npm run assemble-runtimes && npm run build:desktop",
     "generate-icons": "tauri icon src-tauri/icons/icon.svg",
-    "typecheck": "tsc --noEmit && tsc -p tsconfig.cli.json --noEmit && tsc -p mcp-bridge/tsconfig.json --noEmit && cd client && tsc --noEmit",
+    "typecheck": "tsc --noEmit && tsc -p tsconfig.cli.json --noEmit && tsc -p mcp-bridge/tsconfig.json --noEmit && tsc -p local-runner/tsconfig.json --noEmit && cd client && tsc --noEmit",
     "check-core-compat": "tsx scripts/check-core-compat.ts",
     "test": "vitest run && tsx scripts/check-core-compat.ts",
     "test:watch": "vitest",

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

@@ -13,6 +13,7 @@ const promises_1 = require("node:fs/promises");
 const win_spawn_1 = require("./util/win-spawn");
 const providers_1 = require("./providers");
 const runtime_1 = require("./providers/runtime");
+const registry_1 = require("./providers/registry");
 const spawn_lifecycle_1 = require("./spawn-lifecycle");
 const live_session_1 = require("./providers/live-session");
 const live_session_types_1 = require("./providers/live-session-types");
@@ -415,7 +416,13 @@ class AgentChatManager {
         // Per-turn dynamic context (pinned project, permission level, provider) rides
         // the USER turn, never the system prompt — byte-stability contract (see
         // agent-operator-prompt.ts).
-        const turnSettings = `Permission level: ${tierLevel} (${['observe', 'edit', 'operate', 'autonomous'][tierLevel]}) | Provider: ${adapter.id} | Model: ${model}${reasoningEffort ? ` | Reasoning effort: ${reasoningEffort}` : ''}`;
+        // Local (OpenAI-compatible) engines are usually small models that drop the
+        // exact fence tags and ask the user for the #noframe waiver — restate the
+        // two rules they break most, on the USER turn (system prompt stays byte-stable).
+        const localProtocolNote = (0, registry_1.isLocalAdapterId)(adapter.id)
+            ? ' | Protocol: fenced protocol blocks MUST be tagged exactly problem-frame, spec-draft or options (never json); never ask the user to type #noframe'
+            : '';
+        const turnSettings = `Permission level: ${tierLevel} (${['observe', 'edit', 'operate', 'autonomous'][tierLevel]}) | Provider: ${adapter.id} | Model: ${model}${reasoningEffort ? ` | Reasoning effort: ${reasoningEffort}` : ''}${localProtocolNote}`;
         const contextPrefix = conversation.pinned_project_id
             ? `[Active project: projectId="${conversation.pinned_project_id}" | ${turnSettings}. Use this project for project-scoped tools; changing the execution target requires changing the conversation pin.]`
             : `[No project pinned (Home) | ${turnSettings}]`;

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

@@ -9,6 +9,7 @@ const fs_1 = __importDefault(require("fs"));
 const multer_1 = __importDefault(require("multer"));
 const express_1 = require("express");
 const providers_1 = require("./providers");
+const provider_selection_1 = require("./provider-selection");
 const agent_tier_1 = require("./agent-tier");
 const attachment_manager_1 = require("./attachment-manager");
 const agent_store_1 = require("./agent-store");
@@ -121,7 +122,7 @@ function createAgentChatRouter(deps) {
     });
     // Per-provider model catalog for the header model selector.
     router.get('/models', (req, res) => {
-        const provider = validProvider(req.query.provider) ?? 'claude';
+        const provider = validProvider(req.query.provider) ?? (0, provider_selection_1.defaultMachineProvider)();
         const adapter = (0, providers_1.getAdapter)(provider);
         const requestedModel = (0, providers_1.isModelAvailableForAdapter)(adapter, req.query.model)
             ? req.query.model
@@ -171,7 +172,9 @@ function createAgentChatRouter(deps) {
     });
     router.post('/conversations', (req, res) => {
         const body = (req.body ?? {});
-        let provider = 'claude';
+        // No explicit provider ⇒ the machine's primary (a local-only machine lands
+        // on its local engine, never on an uninstalled claude).
+        let provider = (0, provider_selection_1.defaultMachineProvider)();
         if (body.provider !== undefined) {
             const v = validProvider(body.provider);
             if (!v) {

package/server/dist/agent-fence-promotion.js

@@ -0,0 +1,53 @@
+"use strict";
+// ─── Protocol fence promotion (small-model tolerance) ─────────────────────────
+// The operator protocol asks for fenced blocks tagged EXACTLY `options`,
+// `problem-frame` and `spec-draft`. Small / local models routinely emit the
+// right JSON under a generic ```json (or bare ```) fence instead, which the
+// strict parsers ignore — so no chips, no framing card, and commit_draft then
+// refuses because no frame was ever registered. This pass re-tags a CLOSED
+// generic fence whose body unambiguously has one protocol shape. Anything
+// ambiguous is left untouched; fences already carrying a protocol tag are
+// never rewritten. Mirror: server/agent-fence-promotion.ts (keep in sync).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.detectProtocolShape = detectProtocolShape;
+exports.promoteAgentProtocolFences = promoteAgentProtocolFences;
+const GENERIC_FENCE_RE = /```(?:json|jsonc|JSON)?[^\S\n]*\n([\s\S]*?)\n[^\S\n]*```/g;
+function isRecord(v) {
+    return !!v && typeof v === 'object' && !Array.isArray(v);
+}
+/** Detect which protocol block a parsed JSON body is, or null. */
+function detectProtocolShape(value) {
+    if (Array.isArray(value)) {
+        if (value.length < 2 || value.length > 8)
+            return null;
+        return value.every((s) => typeof s === 'string' && s.trim() && s.trim().length <= 80) ? 'options' : null;
+    }
+    if (!isRecord(value))
+        return null;
+    if (isRecord(value.restated) && isRecord(value.alternative) && typeof value.discriminator === 'string')
+        return 'problem-frame';
+    if (typeof value.title === 'string' && typeof value.description === 'string'
+        && ('acceptanceCriteria' in value || 'labels' in value || 'priority' in value))
+        return 'spec-draft';
+    return null;
+}
+/** Re-tag generic fences that carry a protocol-shaped JSON body. */
+function promoteAgentProtocolFences(text) {
+    if (!text || !text.includes('```'))
+        return text ?? '';
+    GENERIC_FENCE_RE.lastIndex = 0;
+    return text.replace(GENERIC_FENCE_RE, (whole, body, offset) => {
+        // A fence preceded by another backtick is a quoted/long fence — never touch.
+        if (offset > 0 && text[offset - 1] === '`')
+            return whole;
+        let parsed;
+        try {
+            parsed = JSON.parse(body);
+        }
+        catch {
+            return whole;
+        }
+        const shape = detectProtocolShape(parsed);
+        return shape ? '```' + shape + '\n' + body + '\n```' : whole;
+    });
+}

package/server/dist/agent-mcp-config.js

@@ -306,7 +306,10 @@ function codexExternalOverrides(server) {
 function prepareAgentMcp(opts) {
     const adapter = (0, providers_1.getAdapter)(opts.adapterId);
     const external = (opts.external ?? []).filter((s) => s.name !== 'specrails');
-    if (adapter.id === 'claude') {
+    // claude AND local (OpenAI-compatible) runners take the per-conversation
+    // `--mcp-config <file>` (design D8): the bundled runner starts the same
+    // stdio servers and exposes their tools as `mcp__<server>__<tool>`.
+    if (adapter.id === 'claude' || (0, providers_1.isLocalAdapterId)(adapter.id)) {
         const extraArgs = buildAgentMcpArgs(opts);
         if (!extraArgs.length)
             throw new Error('The bundled Specrails MCP bridge is unavailable.');

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

@@ -62,8 +62,13 @@ async function runAgentRuntimeInvocation(options) {
             repositoryIds: admittedContext.repositories.map(repo => repo.id), source, providerOverride: options.providerOverride,
         });
         config.rolePrompts = { ...(await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).rolePromptDefaults(), ...(0, agent_runtime_settings_1.loadRuntimeRolePrompts)() };
-        const override = options.providerOverride;
+        // 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;
+        const override = options.providerOverride;
         runtime.validateRuntimeConfig(JSON.parse(JSON.stringify(config)));
         (0, agent_runtime_loader_1.validateRequestedRoleEfforts)(runtime, config);
         cli = (0, agent_runtime_package_1.retainAgentRuntime)(cli, options.contextPath);
@@ -94,7 +99,7 @@ async function runAgentRuntimeInvocation(options) {
     const frozenPath = (0, node_path_1.join)((0, node_path_1.dirname)(options.contextPath), 'desktop-runtime-config.json');
     if ((0, node_fs_1.existsSync)(frozenPath)) {
         const frozen = JSON.parse((0, node_fs_1.readFileSync)(frozenPath, 'utf8'));
-        for (const [role, assignment] of Object.entries(frozen.agents)) {
+        for (const [role, assignment] of [...Object.entries(frozen.agents), ...(frozen.fixer ? [['fixer', frozen.fixer]] : [])]) {
             try {
                 options.onLine?.(`[runtime] ${role}: ${assignment.provider}/${assignment.model ?? 'provider default'}\n`);
             }

package/server/dist/agent-runtime-controls-router.js

@@ -38,7 +38,9 @@ function registerAgentRuntimeControlRoutes({ router, ctx }) {
                 }
                 const context = ctx(req);
                 const latest = context.db.prepare('SELECT id FROM loop_runs WHERE rail_index = ? ORDER BY started_at DESC, rowid DESC LIMIT 1').get(railIndex);
-                res.json({ runs: latest && (0, agent_runtime_paths_1.hasAgentRuntimeRequest)(context.project, latest.id) ? [await controls(req).summary(latest.id)] : [] });
+                // A dismissed continuation — or a green one with nothing left to decide — leaves the rail card (the run stays in the history list below).
+                const summary = latest && (0, agent_runtime_paths_1.hasAgentRuntimeRequest)(context.project, latest.id) ? await controls(req).summary(latest.id) : undefined;
+                res.json({ runs: summary && (0, agent_runtime_controls_1.pinsRailCard)(summary) ? [summary] : [] });
                 return;
             }
             res.json({ runs: await controls(req).list() });
@@ -82,6 +84,15 @@ function registerAgentRuntimeControlRoutes({ router, ctx }) {
             res.status(error instanceof agent_runtime_controls_1.RuntimeControlError ? error.statusCode : 500).json({ message: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.message : 'Could not prepare delivery' });
         }
     });
+    router.post('/:projectId/agent-runtime/runs/:runId/dismiss', (req, res) => {
+        try {
+            controls(req).dismiss(String(req.params.runId));
+            res.json({ dismissed: true });
+        }
+        catch (error) {
+            res.status(error instanceof agent_runtime_controls_1.RuntimeControlError ? error.statusCode : 500).json({ error: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.code : 'runtime_dismiss_failed', message: error instanceof Error ? error.message : 'Could not dismiss the execution' });
+        }
+    });
     router.post('/:projectId/agent-runtime/runs/:runId/cancel', (req, res) => {
         try {
             controls(req).cancel(String(req.params.runId));

package/server/dist/agent-runtime-controls.js

@@ -4,6 +4,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentRuntimeControls = exports.RuntimeControlError = void 0;
+exports.pinsRailCard = pinsRailCard;
 exports.validateRuntimeResumeInput = validateRuntimeResumeInput;
 exports.readAgentRuntimeStatus = readAgentRuntimeStatus;
 const agent_runtime_events_1 = require("./agent-runtime-events");
@@ -25,8 +26,23 @@ const multi_repo_execution_store_1 = require("./multi-repo-execution-store");
 const db_1 = require("./db");
 const loop_run_manager_1 = require("./loop-run-manager");
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const STEP_IDS = ['architect', 'developer', 'verify', 'reviewer', 'archive'];
+const STEP_IDS = ['architect', 'developer', 'fixer', 'verify', 'reviewer', 'archive'];
 const ANSWER_LIMIT = 20_000;
+/**
+ * Whether a continuation still deserves the rail card. Anything that needs a
+ * human (blocked, failed, interrupted, a pending question or approval, a
+ * settle still owed) pins the rail; a run that SUCCEEDED and offers no action
+ * does not — its evidence lives in the job log and the Settings history, and
+ * the delivery decision (when one exists) has its own strip. Observed: a rail
+ * kept a "Completed" card with only Dismiss on it after every green run.
+ */
+function pinsRailCard(summary) {
+    if (summary.dismissed)
+        return false;
+    if (summary.active || summary.canResume || summary.canSettle || summary.canCancel || summary.pendingQuestion || summary.pendingApproval || summary.recoverableSteps.length)
+        return true;
+    return summary.status !== 'succeeded';
+}
 class RuntimeControlError extends Error {
     statusCode;
     code;
@@ -189,7 +205,8 @@ class AgentRuntimeControls {
                 traceId: state.traceId, pendingQuestion: openQuestion(state),
                 metrics: (0, agent_runtime_metrics_1.readRuntimeEfficiency)(superseding ? superseding.metrics : state.metrics), efficiencySummary: (0, agent_runtime_metrics_1.readRuntimeEfficiencySummary)(superseding ? superseding.efficiencySummary : state.efficiencySummary),
                 canSettle: !superseding && !active && state.status === 'succeeded' && this.ctx.db.prepare('SELECT status FROM jobs WHERE id = ?').get(runId)?.status !== 'completed',
-                recoverableSteps, active, canCancel: this.active.has(runId), canResume: !active && parent?.status === 'completed' && state.status !== 'succeeded' };
+                recoverableSteps, active, canCancel: this.active.has(runId), canResume: !active && parent?.status === 'completed' && state.status !== 'succeeded',
+                canDismiss: !active, dismissed: this.isDismissed(runId) };
         }
         catch (error) {
             try {
@@ -362,6 +379,24 @@ class AgentRuntimeControls {
             this.ctx.broadcast?.({ type: 'runtime.continuation', projectId: this.ctx.project.id, jobId: runId, railIndex: (0, loop_runs_store_1.getLoopRun)(this.ctx.db, runId)?.rail_index ?? null, active: false });
         }
     }
+    /** Marker next to the frozen context: the rail card stops showing this run; history/log stay intact. */
+    dismissMarker(runId) { return node_path_1.default.join(node_path_1.default.dirname(this.context(runId).file), 'desktop-runtime-dismissed'); }
+    isDismissed(runId) { try {
+        return node_fs_1.default.existsSync(this.dismissMarker(runId));
+    }
+    catch {
+        return false;
+    } }
+    dismiss(runId) {
+        if (this.active.has(runId))
+            throw new RuntimeControlError(409, 'runtime_run_active', 'Stop the execution before dismissing it');
+        const parent = (0, loop_runs_store_1.getLoopRun)(this.ctx.db, runId);
+        if (parent && (parent.status === 'running' || parent.status === 'paused'))
+            throw new RuntimeControlError(409, 'runtime_run_active', 'Stop the rail run before dismissing it');
+        node_fs_1.default.writeFileSync(this.dismissMarker(runId), new Date().toISOString() + '\n', { mode: 0o600 });
+        this.statusCache.delete(runId);
+        this.ctx.broadcast?.({ type: 'runtime.continuation', projectId: this.ctx.project.id, jobId: runId, railIndex: parent?.rail_index ?? null, active: false });
+    }
     cancel(runId) {
         const active = this.active.get(runId);
         if (!active)

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.resolveEffectiveRuntimeConfig = resolveEffectiveRuntimeConfig;
+exports.fillDefaultRoleModels = fillDefaultRoleModels;
 const providers_1 = require("./providers");
 /** A pure admission resolver; only deliberate launch intent overrides a project role. */
 function resolveEffectiveRuntimeConfig(input, options) {
@@ -10,23 +11,43 @@ function resolveEffectiveRuntimeConfig(input, options) {
         const provider = config.providers.find(entry => entry.id === override.provider);
         if (!provider)
             throw new Error(`Selected runtime provider is not configured: ${override.provider}`);
-        for (const role of ['architect', 'developer', 'reviewer']) {
-            const current = config.agents[role];
+        for (const role of ['architect', 'developer', 'reviewer', 'fixer']) {
+            const current = role === 'fixer' ? config.fixer : config.agents[role];
+            if (!current)
+                continue;
             const changedProvider = current.provider !== provider.id;
             const changedModel = override.model !== undefined && override.model !== current.model;
-            config.agents[role] = {
+            const next = {
                 ...current, provider: provider.id,
                 model: override.model ?? (changedProvider ? undefined : current.model),
                 effort: override.effort ?? (changedProvider || changedModel ? undefined : current.effort),
                 escalation: changedProvider || changedModel ? undefined : current.escalation,
             };
+            if (role === 'fixer')
+                config.fixer = next;
+            else
+                config.agents[role] = next;
         }
     }
-    for (const agent of Object.values(config.agents)) {
+    fillDefaultRoleModels(config);
+    config.verification = config.verification.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 } };
+}
+/**
+ * Every role gets a concrete model: CLI roles the adapter default, local
+ * (OpenAI-compatible) roles the connection's default (stored `defaultModel`,
+ * else the first discovered model). Core requires a model on API providers, so
+ * this runs before launch AND before the compatibility check — otherwise
+ * picking a local engine with "provider default" failed the check with
+ * "Role architect requires a model for its API provider".
+ */
+function fillDefaultRoleModels(config, options = {}) {
+    for (const agent of [...Object.values(config.agents), ...(config.fixer ? [config.fixer] : [])]) {
         const provider = config.providers.find(entry => entry.id === agent.provider);
-        if (!agent.model && provider?.kind === 'cli')
+        if (!agent.model && provider?.kind === 'cli' && !options.localOnly)
             agent.model = (0, providers_1.getAdapter)(provider.cli).defaultModel();
+        if (!agent.model && provider?.kind === 'openai-compatible' && (0, providers_1.hasAdapter)(provider.id) && (0, providers_1.isLocalAdapterId)(provider.id))
+            agent.model = (0, providers_1.getAdapter)(provider.id).defaultModel();
     }
-    config.verification = config.verification.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 } };
+    return config;
 }

package/server/dist/agent-runtime-metrics.js

@@ -5,7 +5,7 @@ exports.readRuntimeEfficiencySummary = readRuntimeEfficiencySummary;
 exports.applyRuntimeSelectionOrigins = applyRuntimeSelectionOrigins;
 const COUNTS = ['attempts', 'measuredAttempts', 'providerCalls', 'toolCalls', 'inputTokens', 'outputTokens', 'uncachedInputTokens', 'cacheReadInputTokens', 'cacheWriteInputTokens'];
 const KEYS = [...COUNTS, 'durationMs', 'agentDurationMs', 'costUsd'];
-const PHASES = ['architect', 'developer', 'verify', 'reviewer', 'archive'];
+const PHASES = ['architect', 'developer', 'fixer', 'verify', 'reviewer', 'archive'];
 function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null; }
 function counters(value) {
     const input = object(value);

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

@@ -4,9 +4,59 @@ exports.registerAgentRuntimeSettingsRoutes = registerAgentRuntimeSettingsRoutes;
 const node_fs_1 = require("node:fs");
 const agent_runtime_loader_1 = require("./agent-runtime-loader");
 const agent_runtime_settings_1 = require("./agent-runtime-settings");
+const agent_runtime_settings_2 = require("./agent-runtime-settings");
 const agent_runtime_verification_suggestions_1 = require("./agent-runtime-verification-suggestions");
 const project_repositories_1 = require("./project-repositories");
+const agent_runtime_effective_config_1 = require("./agent-runtime-effective-config");
+/** Raw request body → same body with every local role's missing model filled (validation then passes). */
+function withDefaultRoleModels(body) {
+    const agents = body.agents;
+    const providers = body.providers;
+    if (!agents || typeof agents !== 'object' || !Array.isArray(providers))
+        return body;
+    // Only LOCAL roles: a CLI role saved without a model keeps meaning "provider default" (never frozen into the file).
+    const fixer = body.fixer && typeof body.fixer === 'object' ? structuredClone(body.fixer) : undefined;
+    const filled = (0, agent_runtime_effective_config_1.fillDefaultRoleModels)({ agents: structuredClone(agents), providers: providers, ...(fixer ? { fixer: fixer } : {}) }, { localOnly: true });
+    return { ...body, agents: filled.agents, ...(filled.fixer ? { fixer: filled.fixer } : {}) };
+}
+const loop_role_engines_1 = require("./loop-role-engines");
 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) => {
+        try {
+            const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
+            const supported = runtime.api?.capabilities?.configurableGuardrails === 1;
+            const catalog = supported && Array.isArray(runtime.api?.guardrails) ? runtime.api.guardrails.filter((item) => item && typeof item.id === 'string' && typeof item.phase === 'string') : [];
+            res.json({ supported, catalog });
+        }
+        catch {
+            res.json({ supported: false, catalog: [] });
+        }
+    });
+    /** Loop-side role engines (verifier / decider) for `roles` rail launches — hybrid-role-engines. */
+    router.get('/:projectId/agent-runtime/loop-roles', (req, res) => {
+        try {
+            res.json({ roles: (0, loop_role_engines_1.loadLoopRoleEngines)(ctx(req).project) });
+        }
+        catch {
+            res.status(500).json({ error: 'loop_roles_read_failed' });
+        }
+    });
+    router.put('/:projectId/agent-runtime/loop-roles', (req, res) => {
+        try {
+            const project = ctx(req).project;
+            const roles = (0, loop_role_engines_1.validateLoopRoleEngines)(req.body?.roles ?? req.body ?? {}, project);
+            (0, loop_role_engines_1.saveLoopRoleEngines)(project, roles);
+            res.json({ roles });
+        }
+        catch (error) {
+            if (error instanceof loop_role_engines_1.LoopRoleEnginesError) {
+                res.status(400).json({ error: 'invalid_loop_roles', message: error.message });
+                return;
+            }
+            res.status(500).json({ error: 'loop_roles_write_failed' });
+        }
+    });
     router.get('/:projectId/agent-runtime/config', async (_req, res) => {
         try {
             const project = ctx(_req).project;
@@ -39,19 +89,38 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
     });
     router.post('/:projectId/agent-runtime/capabilities', async (req, res) => {
         try {
-            const config = (0, agent_runtime_settings_1.validateAgentRuntimeConfig)({ ...req.body, providers: (0, agent_runtime_settings_1.loadRuntimeProviders)(), enabled: true });
+            const config = (0, agent_runtime_settings_1.validateAgentRuntimeConfig)(withDefaultRoleModels({ ...req.body, providers: (0, agent_runtime_settings_1.loadRuntimeProviders)(), enabled: true }));
             const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
             if (!runtime.capabilities)
                 throw new Error('Installed Core does not support capability introspection');
-            res.json(await runtime.capabilities(config));
+            // Core's schema is additionalProperties:false — strip the desktop-only
+            // connection fields (label/defaultModel/rates/supportsReasoningEffort) first.
+            res.json(await runtime.capabilities({ ...(0, agent_runtime_settings_2.forCoreRuntime)(config, runtime.api?.capabilities), providers: (0, agent_runtime_settings_2.stripDesktopConnectionFields)(config.providers, (0, agent_runtime_settings_1.coreConnectionFieldGates)(runtime.api?.capabilities)) }));
         }
         catch (error) {
-            res.status(error instanceof agent_runtime_settings_1.AgentRuntimeConfigError ? 400 : 503).json({ error: 'runtime_capabilities_unavailable', message: error instanceof agent_runtime_settings_1.AgentRuntimeConfigError ? error.message : 'Update the paired Core runtime to inspect model capabilities' });
+            // Core prints its verdict (`{"type":"runtime-result","status":"failed","error":…}`) before exiting non-zero: show that, not the generic "update Core" line.
+            const coreMessage = (() => { const out = error.stdout; if (typeof out !== 'string')
+                return undefined; try {
+                const parsed = JSON.parse(out.trim().split('\n').pop() ?? '');
+                return typeof parsed.error === 'string' ? parsed.error : undefined;
+            }
+            catch {
+                return undefined;
+            } })();
+            res.status(error instanceof agent_runtime_settings_1.AgentRuntimeConfigError || coreMessage ? 400 : 503).json({ error: 'runtime_capabilities_unavailable', message: error instanceof agent_runtime_settings_1.AgentRuntimeConfigError ? error.message : coreMessage ?? 'Update the paired Core runtime to inspect model capabilities' });
         }
     });
     router.put('/:projectId/agent-runtime/config', async (req, res) => {
         try {
-            (0, agent_runtime_settings_1.validateAgentRuntimeConfig)(req.body);
+            // A local role saved as "provider default" carries no model; fill the
+            // connection default (the launch rule) before the model-required check.
+            // The raw body is validated first (its own providers included — a
+            // credential in a submitted URL must be refused), then the stored
+            // connections replace them and the missing local-role models are filled
+            // from each connection's default before the model-required check.
+            // Saved WITHOUT filling local-role models: "provider default" stays a
+            // live reference to the connection's default (resolved at launch).
+            (0, agent_runtime_settings_1.validateAgentRuntimeConfig)({ ...req.body, providers: Array.isArray(req.body?.providers) ? req.body.providers : (0, agent_runtime_settings_1.loadRuntimeProviders)() });
             const config = (0, agent_runtime_settings_1.validateAgentRuntimeConfig)({ ...req.body, enabled: true, providers: (0, agent_runtime_settings_1.loadRuntimeProviders)() });
             const runtimeAvailable = (0, agent_runtime_loader_1.findCoreAgentRuntimeEntry)() !== null;
             if (config.enabled && !runtimeAvailable) {
@@ -62,8 +131,9 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
             if (config.enabled && runtimeAvailable) {
                 try {
                     const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
-                    runtime.validateRuntimeConfig(config);
-                    (0, agent_runtime_loader_1.validateRequestedRoleEfforts)(runtime, config);
+                    const coreConfig = { ...(0, agent_runtime_settings_2.forCoreRuntime)((0, agent_runtime_effective_config_1.fillDefaultRoleModels)(structuredClone(config), { localOnly: true }), runtime.api?.capabilities), providers: (0, agent_runtime_settings_2.stripDesktopConnectionFields)(config.providers, (0, agent_runtime_settings_1.coreConnectionFieldGates)(runtime.api?.capabilities)) };
+                    runtime.validateRuntimeConfig(coreConfig);
+                    (0, agent_runtime_loader_1.validateRequestedRoleEfforts)(runtime, coreConfig);
                     efficiencyAvailable = runtime.api?.capabilities?.efficientRoleExecution === 1;
                 }
                 catch {