specrails-desktop 2.46.0 → 2.48.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.46.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

@@ -3,15 +3,17 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RUNTIME_HOST_ENV_KEYS = void 0;
 exports.runtimeChangeName = runtimeChangeName;
 exports.runAgentRuntimeInvocation = runAgentRuntimeInvocation;
+const agent_runtime_history_1 = require("./agent-runtime-history");
 const agent_runtime_repositories_1 = require("./agent-runtime-repositories");
 const node_util_1 = require("node:util");
-const providers_1 = require("./providers");
+const agent_runtime_effective_config_1 = require("./agent-runtime-effective-config");
 const node_child_process_1 = require("node:child_process");
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_readline_1 = require("node:readline");
 const agent_runtime_loader_1 = require("./agent-runtime-loader");
+const agent_runtime_package_1 = require("./agent-runtime-package");
 const agent_runtime_settings_1 = require("./agent-runtime-settings");
 const core_node_runtime_1 = require("./core-node-runtime");
 const win_spawn_1 = require("./util/win-spawn");
@@ -42,7 +44,8 @@ function saveHostContext(options) {
 /** Core owns the complete agent workflow in one managed process. The existing
  * rail's cancellation and worktree ownership remain in Desktop. */
 async function runAgentRuntimeInvocation(options) {
-    const cli = (0, agent_runtime_loader_1.findCoreAgentRuntimeCli)();
+    const selectedCli = options.resume ? (0, agent_runtime_package_1.resolveRetainedAgentRuntime)(options.contextPath) : (0, agent_runtime_loader_1.findCoreAgentRuntimeCli)();
+    let cli = selectedCli;
     if (!cli)
         throw new Error('Programmatic agent runtime is enabled but its Core CLI is unavailable. Build or bundle the compatible Core runtime.');
     if (!options.resume && (!options.configPath || !options.change))
@@ -50,35 +53,36 @@ async function runAgentRuntimeInvocation(options) {
     const admittedContext = JSON.parse((0, node_fs_1.readFileSync)(options.contextPath, 'utf8'));
     if (typeof admittedContext.runId !== 'string')
         throw new Error('Core context is missing its run identity');
-    if (!options.resume)
-        saveHostContext(options);
     const args = [cli, options.resume ? 'resume' : 'run', '--context', options.contextPath];
     if (!options.resume) {
         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 config = (0, agent_runtime_settings_1.loadRuntimeConfigFile)(options.configPath, options.defaultProvider);
+        const source = (0, node_fs_1.existsSync)(options.configPath) ? 'project-role' : 'default';
+        const { config, origins } = (0, agent_runtime_effective_config_1.resolveEffectiveRuntimeConfig)((0, agent_runtime_settings_1.loadRuntimeConfigFile)(options.configPath, options.defaultProvider), {
+            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)() };
-        if (options.defaultProvider) {
-            const provider = config.providers.find(entry => entry.id === options.defaultProvider);
-            if (!provider)
-                throw new Error(`Selected runtime provider is not configured: ${options.defaultProvider}`);
-            for (const role of Object.values(config.agents)) {
-                if (role.provider !== provider.id) {
-                    role.provider = provider.id;
-                    role.model = options.selectedModel ?? (provider.kind === 'cli' ? (0, providers_1.getAdapter)(provider.cli).defaultModel() : undefined);
-                    if (!role.model)
-                        throw new Error(`Selected runtime provider requires a model: ${provider.id}`);
-                }
-                if (!role.model && provider.kind === 'cli')
-                    role.model = (0, providers_1.getAdapter)(provider.cli).defaultModel();
-            }
-            if (options.selectedModel)
-                config.agents.developer.model = options.selectedModel;
+        // 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);
+        args[0] = cli;
+        saveHostContext(options);
+        const selectionFile = (0, node_path_1.join)((0, node_path_1.dirname)(options.contextPath), 'desktop-runtime-selection.json');
+        const selection = JSON.stringify({ schemaVersion: 1, runId: admittedContext.runId, providerOverride: override ?? null, origins }) + '\n';
+        try {
+            (0, node_fs_1.writeFileSync)(selectionFile, selection, { flag: 'wx', mode: 0o600 });
+        }
+        catch (error) {
+            if (error.code !== 'EEXIST' || (0, node_fs_1.readFileSync)(selectionFile, 'utf8') !== selection)
+                throw new Error('Runtime selection provenance changed; start a new run');
         }
-        const selected = new Set(admittedContext.repositories.map(repo => repo.id));
-        // Project settings cover every repository; a ticket may select only a subset.
-        // Freeze that subset for admission without changing the project settings.
-        config.verification = config.verification.filter(command => selected.has(command.repositoryId));
         const scopedPath = (0, node_path_1.join)((0, node_path_1.dirname)(options.contextPath), 'desktop-runtime-config.json');
         const serialized = JSON.stringify(config, null, 2) + '\n';
         try {
@@ -95,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`);
             }
@@ -112,6 +116,7 @@ async function runAgentRuntimeInvocation(options) {
         args.push('--answer', options.answer);
     }
     const started = Date.now();
+    (0, agent_runtime_history_1.writeRuntimeHistory)(options.contextPath, { status: 'running' });
     return new Promise((resolve) => {
         let result;
         let stderr = '', summary = '', invalidProtocol = false, timedOut = false;
@@ -220,6 +225,10 @@ async function runAgentRuntimeInvocation(options) {
                         ? `Workflow awaits an answer in Agent Runtime settings: ${result.pendingQuestion.question.trim().slice(0, 500)}`
                         : 'Workflow awaits approval in Agent Runtime settings')
                         : failed ? stderr || 'Core exited without a successful programmatic workflow result' : undefined));
+            try {
+                (0, agent_runtime_history_1.writeRuntimeHistory)(options.contextPath, invalidProtocol || timedOut || observerError || !result ? { status: 'failed', error: errorText } : { ...result });
+            }
+            catch { /* Projection failure cannot replay a completed execution. */ }
             resolve({
                 text: summary || (failed ? errorText ?? '' : 'Programmatic implementation verified and archived.'),
                 provider: 'agent-runtime', model: 'per-role', failed, errorText,

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() });
@@ -56,6 +58,14 @@ function registerAgentRuntimeControlRoutes({ router, ctx }) {
             res.status(500).json({ error: 'runtime_status_failed' });
         }
     });
+    router.get('/:projectId/agent-runtime/runs/:runId/evidence', async (req, res) => {
+        try {
+            res.json(await controls(req).evidence(String(req.params.runId), req.query));
+        }
+        catch (error) {
+            res.status(error instanceof agent_runtime_controls_1.RuntimeControlError ? error.statusCode : 503).json({ error: 'evidence_unavailable', message: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.message : 'The original runtime evidence is unavailable' });
+        }
+    });
     router.post('/:projectId/agent-runtime/runs/:runId/resume', async (req, res) => {
         try {
             await controls(req).resume(String(req.params.runId), (0, agent_runtime_controls_1.validateRuntimeResumeInput)(req.body));
@@ -74,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,8 +4,11 @@ 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");
+const agent_runtime_history_1 = require("./agent-runtime-history");
 const agent_runtime_settlement_1 = require("./agent-runtime-settlement");
 const agent_runtime_metrics_1 = require("./agent-runtime-metrics");
 const node_child_process_1 = require("node:child_process");
@@ -13,7 +16,7 @@ const node_crypto_1 = require("node:crypto");
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_util_1 = require("node:util");
-const agent_runtime_loader_1 = require("./agent-runtime-loader");
+const agent_runtime_package_1 = require("./agent-runtime-package");
 const agent_runtime_bridge_1 = require("./agent-runtime-bridge");
 const core_node_runtime_1 = require("./core-node-runtime");
 const win_spawn_1 = require("./util/win-spawn");
@@ -23,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;
@@ -56,7 +74,13 @@ function openQuestion(state) {
 }
 /** Status is a read-only Core CLI operation. It never invokes a provider. */
 async function readAgentRuntimeStatus(contextPath, cwd, env) {
-    const cli = (0, agent_runtime_loader_1.findCoreAgentRuntimeCli)();
+    let cli;
+    try {
+        cli = (0, agent_runtime_package_1.resolveRetainedAgentRuntime)(contextPath);
+    }
+    catch (error) {
+        throw new RuntimeControlError(409, 'original_runtime_unavailable', error instanceof Error ? error.message : 'The original runtime package is unavailable');
+    }
     if (!cli)
         throw new RuntimeControlError(503, 'runtime_unavailable', 'Update Core to inspect or resume agent runtime executions');
     const { stdout } = await (0, node_util_1.promisify)(node_child_process_1.execFile)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), [cli, 'status', '--context', contextPath, '--compact'], {
@@ -65,7 +89,12 @@ async function readAgentRuntimeStatus(contextPath, cwd, env) {
     const result = JSON.parse(stdout);
     if (result.type !== 'runtime-status' || result.state === undefined)
         throw new Error('Core returned an invalid runtime status');
-    return result.state;
+    let selection;
+    try {
+        selection = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(node_path_1.default.dirname(contextPath), 'desktop-runtime-selection.json'), 'utf8'));
+    }
+    catch { /* Original hosts may not record selection origins. */ }
+    return result.state ? { ...result.state, efficiencySummary: (0, agent_runtime_metrics_1.applyRuntimeSelectionOrigins)((0, agent_runtime_metrics_1.readRuntimeEfficiencySummary)(result.efficiencySummary), selection, result.state.runId) } : null;
 }
 /** One controller per ProjectContext; Core's durable lease remains the final
  * cross-process guard. Resume never constructs a new context or worktree. */
@@ -82,7 +111,7 @@ class AgentRuntimeControls {
         this.ctx = ctx;
         this.dependencies = dependencies;
     }
-    context(runId) {
+    context(runId, historical = false) {
         if (!SAFE_ID.test(runId))
             throw new RuntimeControlError(400, 'invalid_run_id', 'Invalid runtime run ID');
         const execution = (0, workspace_resolution_1.resolveProjectExecution)(this.ctx.project);
@@ -98,7 +127,7 @@ class AgentRuntimeControls {
             if (frozen.runId !== runId || node_fs_1.default.realpathSync(frozen.backlogRoot) !== backlogRoot || !Array.isArray(frozen.repositories) || !frozen.repositories.length || !frozen.repositories.some((repository) => repository.path === frozen.artifactRoot))
                 throw new Error();
             for (const root of [frozen.artifactRoot, ...frozen.repositories.map((repository) => repository.path)]) {
-                if (!node_path_1.default.isAbsolute(root) || node_fs_1.default.realpathSync(root) !== root || !node_fs_1.default.statSync(root).isDirectory())
+                if (!node_path_1.default.isAbsolute(root) || (!historical && (node_fs_1.default.realpathSync(root) !== root || !node_fs_1.default.statSync(root).isDirectory())))
                     throw new Error();
             }
         }
@@ -121,6 +150,21 @@ class AgentRuntimeControls {
         Object.assign(env, host.env, { SPECRAILS_EXECUTION_CONTEXT: file });
         return { file, frozen, cwd: host.cwd, env };
     }
+    async evidence(runId, query) {
+        const { file, frozen, env } = this.context(runId, true);
+        const flags = [];
+        for (const [key, value] of Object.entries(query)) {
+            if (!['id', 'section', 'sourceId', 'cursor', 'limit'].includes(key) || typeof value !== 'string' || value.length > 1024)
+                throw new RuntimeControlError(400, 'invalid_evidence_query', 'Invalid evidence query');
+            flags.push('--' + (key === 'sourceId' ? 'source-id' : key), value);
+        }
+        const cli = (0, agent_runtime_package_1.resolveRetainedAgentRuntime)(file);
+        const { stdout } = await (0, node_util_1.promisify)(node_child_process_1.execFile)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), [cli, 'evidence', '--context', file, ...flags], { cwd: frozen.backlogRoot, env: (0, win_spawn_1.windowsSpawnEnv)(env), windowsHide: true, timeout: 15000, maxBuffer: 4 * 1024 * 1024, encoding: 'utf8' });
+        const result = JSON.parse(stdout);
+        if (result.schemaVersion !== 1 || typeof result.available !== 'boolean' || typeof result.truncated !== 'boolean')
+            throw new RuntimeControlError(503, 'evidence_unavailable', 'Core evidence is unavailable or incompatible');
+        return result;
+    }
     async list() {
         const directory = node_path_1.default.join((0, workspace_resolution_1.resolveProjectExecution)(this.ctx.project).specrailsDir, 'pipeline');
         if (!node_fs_1.default.existsSync(directory))
@@ -140,7 +184,7 @@ class AgentRuntimeControls {
             // key, keeping idle settings panes from spawning CLI processes repeatedly.
             const checkpoint = node_path_1.default.join(node_path_1.default.dirname(file), 'agent-workflow', runId, 'checkpoint.json');
             const stat = node_fs_1.default.existsSync(checkpoint) ? node_fs_1.default.statSync(checkpoint) : null;
-            const fingerprint = stat ? `${stat.mtimeMs}:${stat.size}` : null;
+            const fingerprint = stat ? (0, node_crypto_1.createHash)('sha256').update(node_fs_1.default.readFileSync(checkpoint)).digest('hex') : null;
             const cached = this.statusCache.get(runId);
             const state = fingerprint && cached?.fingerprint === fingerprint ? cached.state : await this.dependencies.status(file, cwd, env);
             if (!state || state.runId !== runId)
@@ -149,15 +193,29 @@ class AgentRuntimeControls {
                 this.statusCache.set(runId, { fingerprint, state });
             const parent = (0, loop_runs_store_1.getLoopRun)(this.ctx.db, runId);
             const active = this.active.has(runId) || parent?.status === 'running' || parent?.status === 'paused';
+            let projection = null;
+            try {
+                projection = (0, agent_runtime_history_1.readRuntimeHistory)(file);
+            }
+            catch { /* Invalid advisory history cannot replace live state. */ }
+            const superseding = !active && projection && ['failed', 'cancelled', 'running'].includes(projection.status) && Date.parse(projection.updatedAt) > Date.parse(state.updatedAt ?? '1970-01-01') ? projection : null;
             const recoverableSteps = Object.entries(state.steps).filter(([, step]) => ['running', 'interrupted'].includes(step.status)).map(([id]) => id);
-            return { runId, status: state.status === 'running' && !active ? 'interrupted' : state.status, nextStep: state.nextStep,
-                updatedAt: state.updatedAt, error: this.errors.get(runId) ?? state.error, pendingApproval: state.pendingApproval,
+            return { runId, status: superseding ? (superseding.status === 'running' ? 'interrupted' : superseding.status) : state.status === 'running' && !active ? 'interrupted' : state.status, nextStep: state.nextStep,
+                updatedAt: superseding?.updatedAt ?? state.updatedAt, error: this.errors.get(runId) ?? superseding?.error ?? state.error, pendingApproval: state.pendingApproval,
                 traceId: state.traceId, pendingQuestion: openQuestion(state),
-                metrics: (0, agent_runtime_metrics_1.readRuntimeEfficiency)(state.metrics),
-                canSettle: !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' };
+                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',
+                canDismiss: !active, dismissed: this.isDismissed(runId) };
         }
         catch (error) {
+            try {
+                const { file } = this.context(runId, true);
+                const historical = (0, agent_runtime_history_1.readRuntimeHistory)(file);
+                if (historical)
+                    return { ...historical, runId, status: historical.status === 'running' ? 'interrupted' : historical.status, historical: true, active: this.active.has(runId), canResume: false, canSettle: false, canCancel: this.active.has(runId), recoverableSteps: [], error: error instanceof RuntimeControlError ? error.message : 'Historical result; live runtime verification is unavailable' };
+            }
+            catch { /* No trustworthy historical projection is available. */ }
             return { runId, status: 'unavailable', nextStep: null, active: this.active.has(runId), canResume: false, canCancel: this.active.has(runId), recoverableSteps: [], error: error instanceof RuntimeControlError ? error.message : 'Could not inspect the saved runtime execution' };
         }
     }
@@ -246,6 +304,12 @@ class AgentRuntimeControls {
                             eventType = parsed.type;
                     }
                     catch { /* Keep raw diagnostics available to recovery. */ }
+                    if (eventType === 'runtime-efficiency-event') {
+                        const validated = (0, agent_runtime_events_1.runtimeEfficiencyEventLine)(line, runId);
+                        if (!validated || (0, agent_runtime_events_1.isRecordedRuntimeEfficiencyEvent)(this.ctx.db, runId, validated))
+                            return;
+                        line = validated;
+                    }
                     this.ctx.db.transaction(() => {
                         (0, db_1.appendEvent)(this.ctx.db, runId, ++sequence, { event_type: eventType, source: 'stdout', payload: line });
                         (0, loop_runs_store_1.updateLoopStepActivityCheckpoint)(this.ctx.db, runId, stepKey, undefined, Date.now());
@@ -315,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

@@ -0,0 +1,53 @@
+"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) {
+    const config = structuredClone(input);
+    const override = options.providerOverride;
+    if (override) {
+        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', '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;
+            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;
+        }
+    }
+    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' && !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();
+    }
+    return config;
+}

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

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runtimeEfficiencyEventLine = runtimeEfficiencyEventLine;
+exports.isRecordedRuntimeEfficiencyEvent = isRecordedRuntimeEfficiencyEvent;
+/** Efficiency events are advisory measurements, never workflow or delivery authority. */
+function runtimeEfficiencyEventLine(line, runId) {
+    if (line.length > 16384)
+        return null;
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (event?.type !== 'runtime-efficiency-event' || event.schemaVersion !== 1 || event.runId !== runId || typeof event.eventId !== 'string' || !event.eventId.startsWith(runId + ':') || event.eventId.length > 256 || typeof event.attemptId !== 'string' || event.attemptId.length > 256 || !['role-context', 'role-route', 'check-started', 'check-finished', 'check-reused', 'check-invalidated'].includes(String(event.kind)))
+        return null;
+    if (!event.payload || typeof event.payload !== 'object' || Array.isArray(event.payload))
+        return null;
+    const raw = event.payload, payload = {};
+    for (const key of ['invocationId', 'provider', 'model', 'requestedEffort', 'kind', 'tier', 'routeReason', 'contextMode', 'status', 'executionId', 'repositoryId', 'checkId', 'label', 'reason']) {
+        const value = raw[key];
+        if (value === undefined)
+            continue;
+        if (value !== null && (typeof value !== 'string' || value.length > 256))
+            return null;
+        payload[key] = value;
+    }
+    for (const key of ['ordinal', 'promptBytes', 'contextBytes', 'handoffBytes', 'durationMs', 'toolCalls']) {
+        if (raw[key] === undefined)
+            continue;
+        if (typeof raw[key] !== 'number' || !Number.isFinite(raw[key]) || raw[key] < 0)
+            return null;
+        payload[key] = raw[key];
+    }
+    if (raw.exitCode !== undefined) {
+        if (typeof raw.exitCode !== 'number' || !Number.isSafeInteger(raw.exitCode))
+            return null;
+        payload.exitCode = raw.exitCode;
+    }
+    return JSON.stringify({ type: event.type, schemaVersion: 1, eventId: event.eventId, runId, attemptId: event.attemptId, kind: event.kind, payload });
+}
+function isRecordedRuntimeEfficiencyEvent(db, runId, line) {
+    const event = JSON.parse(line);
+    return Boolean(db.prepare("SELECT 1 FROM events WHERE job_id = ? AND event_type = 'runtime-efficiency-event' AND CASE WHEN json_valid(payload) THEN json_extract(payload, '$.eventId') END = ? LIMIT 1").get(runId, event.eventId));
+}