specrails-desktop 2.45.0 → 2.47.0

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

@@ -6,12 +6,16 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.AgentRuntimeControls = exports.RuntimeControlError = void 0;
 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");
 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");
@@ -54,7 +58,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'], {
@@ -63,22 +73,29 @@ 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. */
 class AgentRuntimeControls {
     ctx;
     dependencies;
+    isActive(runId) { return this.active.has(runId); }
+    activeRunIds() { return [...this.active.keys()]; }
     active = new Map();
     errors = new Map();
     statusCache = new Map();
     disposed = false;
-    constructor(ctx, dependencies = { status: readAgentRuntimeStatus, execute: agent_runtime_bridge_1.runAgentRuntimeInvocation, kill: win_spawn_1.treeKillSafe }) {
+    constructor(ctx, dependencies = { status: readAgentRuntimeStatus, execute: agent_runtime_bridge_1.runAgentRuntimeInvocation, kill: win_spawn_1.treeKillSafe, settle: agent_runtime_settlement_1.settleRuntimeContinuation }) {
         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);
@@ -94,7 +111,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();
             }
         }
@@ -117,6 +134,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))
@@ -136,7 +168,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)
@@ -145,13 +177,28 @@ 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)(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' };
         }
         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' };
         }
     }
@@ -161,6 +208,8 @@ class AgentRuntimeControls {
         const parent = (0, loop_runs_store_1.getLoopRun)(this.ctx.db, runId);
         if (!parent || parent.status !== 'completed' || this.active.has(runId))
             throw new RuntimeControlError(409, 'runtime_run_active', 'Wait for the original Desktop execution to settle before resuming');
+        if (parent.rail_index != null && [...(this.ctx.railLoopRuns?.values() ?? []), ...(this.ctx.railJobs?.values() ?? [])].some(meta => meta.railIndex === parent.rail_index))
+            throw new RuntimeControlError(409, 'runtime_rail_active', 'Wait for the implementation card to finish its active job before resuming');
         const context = this.context(runId);
         // Reserve before awaiting status so concurrent resume requests cannot race.
         const active = { cancelled: false };
@@ -172,6 +221,8 @@ class AgentRuntimeControls {
             const state = await this.dependencies.status(context.file, context.cwd, context.env);
             if (!state || state.runId !== runId || state.status === 'succeeded')
                 throw new RuntimeControlError(409, 'runtime_not_resumable', 'This execution has no resumable workflow');
+            if (parent.rail_index != null && [...(this.ctx.railLoopRuns?.values() ?? []), ...(this.ctx.railJobs?.values() ?? [])].some(meta => meta.railIndex === parent.rail_index))
+                throw new RuntimeControlError(409, 'runtime_rail_active', 'The implementation card became active while checking the saved execution');
             // A pending question resumes the architect only with the operator's answer.
             if (openQuestion(state) && !input.answer)
                 throw new RuntimeControlError(400, 'answer_required', 'This execution is waiting for an answer to the architect\'s question');
@@ -206,7 +257,20 @@ class AgentRuntimeControls {
                     (0, db_1.appendEvent)(this.ctx.db, runId, ++sequence, { event_type: 'log', source, payload: JSON.stringify({ line: line.replace(/\n$/, '') }) });
                 }
                 catch { /* events table best-effort */ }
+                try {
+                    this.ctx.broadcast?.({ type: 'log', source, line, timestamp: new Date().toISOString(), processId: runId });
+                }
+                catch { /* persisted log remains authoritative */ }
+            };
+            if (parent.rail_index != null)
+                this.ctx.railLoopRuns?.set(runId, { railIndex: parent.rail_index, ticketIds, requiresTerminalIntent: true });
+            const publishActivity = (running) => {
+                try {
+                    this.ctx.broadcast?.({ type: 'runtime.continuation', projectId: this.ctx.project.id, jobId: runId, railIndex: parent.rail_index, active: running });
+                }
+                catch { /* durable log remains available */ }
             };
+            publishActivity(true);
             const requested = [...(input.approve?.length ? ['approve ' + input.approve.join(',')] : []), ...(input.recover?.length ? ['recover ' + input.recover.join(',')] : []), ...(input.invalidate?.length ? ['invalidate ' + input.invalidate.join(',')] : []), ...(input.answer ? ['answered question'] : [])];
             logLine(`[runtime] continuation started from phase ${state.nextStep ?? 'end'}${requested.length ? ' (' + requested.join('; ') + ')' : ''}; the original worktree and frozen scope are reused`);
             void this.dependencies.execute({
@@ -223,10 +287,20 @@ 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());
                     })();
+                    try {
+                        this.ctx.broadcast?.({ type: 'event', jobId: runId, event_type: eventType, source: 'stdout', payload: line, seq: sequence, timestamp: new Date().toISOString() });
+                    }
+                    catch { /* persisted event remains authoritative */ }
                 },
                 onSpawn: (child) => {
                     active.child = child;
@@ -235,7 +309,7 @@ class AgentRuntimeControls {
                     else if (active.cancelled)
                         this.cancel(runId);
                 },
-            }).then((result) => {
+            }).then(async (result) => {
                 if (this.disposed)
                     return;
                 logLine(result.failed ? `[runtime] continuation ended: ${result.errorText ?? 'failed'}` : '[runtime] continuation completed', result.failed ? 'stderr' : 'stdout');
@@ -243,14 +317,51 @@ class AgentRuntimeControls {
                 (0, loop_run_manager_1.recoverOrphanLoopStepAccounting)(this.ctx.db, new Date().toISOString(), runId);
                 if (result.errorText)
                     this.errors.set(runId, result.errorText);
-            }).catch(() => { this.errors.set(runId, 'Runtime continuation failed. Inspect the saved phase state before retrying.'); })
-                .finally(() => { clearTimeout(active.forceKillTimer); this.active.delete(runId); });
+                if (!result.failed && !active.cancelled)
+                    await this.dependencies.settle?.({ db: this.ctx.db, projectId: this.ctx.project.id, runId, contextPath: context.file, cwd: context.cwd, env: context.env, broadcast: this.ctx.broadcast });
+            }).catch(() => {
+                if (this.disposed)
+                    return;
+                const message = 'Runtime continuation failed. Inspect the saved phase state before retrying.';
+                this.errors.set(runId, message);
+                logLine(`[runtime] ${message}`, 'stderr');
+            })
+                .finally(() => {
+                clearTimeout(active.forceKillTimer);
+                this.active.delete(runId);
+                this.ctx.railLoopRuns?.delete(runId);
+                this.statusCache.delete(runId);
+                publishActivity(false);
+            });
         }
         catch (error) {
             this.active.delete(runId);
+            this.ctx.railLoopRuns?.delete(runId);
+            try {
+                this.ctx.broadcast?.({ type: 'runtime.continuation', projectId: this.ctx.project.id, jobId: runId, railIndex: parent.rail_index, active: false });
+            }
+            catch { /* admission failed */ }
             throw error;
         }
     }
+    async settle(runId) {
+        if (this.active.has(runId) || (0, loop_runs_store_1.getLoopRun)(this.ctx.db, runId)?.status !== 'completed')
+            throw new RuntimeControlError(409, 'runtime_run_active', 'Wait for the execution to settle');
+        const context = this.context(runId);
+        this.active.set(runId, { cancelled: false });
+        try {
+            await (this.dependencies.settle ?? agent_runtime_settlement_1.settleRuntimeContinuation)({ db: this.ctx.db, projectId: this.ctx.project.id, runId, contextPath: context.file, cwd: context.cwd, env: context.env, broadcast: this.ctx.broadcast });
+            this.errors.delete(runId);
+        }
+        catch (error) {
+            throw new RuntimeControlError(409, 'runtime_settlement_blocked', error instanceof Error ? error.message : 'Could not prepare the recovered delivery');
+        }
+        finally {
+            this.active.delete(runId);
+            this.statusCache.delete(runId);
+            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 });
+        }
+    }
     cancel(runId) {
         const active = this.active.get(runId);
         if (!active)

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

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveEffectiveRuntimeConfig = resolveEffectiveRuntimeConfig;
+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']) {
+            const current = config.agents[role];
+            const changedProvider = current.provider !== provider.id;
+            const changedModel = override.model !== undefined && override.model !== current.model;
+            config.agents[role] = {
+                ...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,
+            };
+        }
+    }
+    for (const agent of Object.values(config.agents)) {
+        const provider = config.providers.find(entry => entry.id === agent.provider);
+        if (!agent.model && provider?.kind === 'cli')
+            agent.model = (0, providers_1.getAdapter)(provider.cli).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 } };
+}

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));
+}

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

@@ -0,0 +1,47 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.writeRuntimeHistory = writeRuntimeHistory;
+exports.readRuntimeHistory = readRuntimeHistory;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_crypto_1 = require("node:crypto");
+const agent_runtime_metrics_1 = require("./agent-runtime-metrics");
+const hash = (value) => (0, node_crypto_1.createHash)('sha256').update(value).digest('hex');
+/** A replaceable projection, not an authority to resume, accept or deliver code. */
+function writeRuntimeHistory(contextPath, input) {
+    const contextText = node_fs_1.default.readFileSync(contextPath, 'utf8'), context = JSON.parse(contextText);
+    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 { /* Old hosts have no explicit provenance. */ }
+    const result = { runId: context.runId, status: typeof input.status === 'string' ? input.status : 'failed', nextStep: typeof input.nextStep === 'string' ? input.nextStep : null,
+        updatedAt: new Date().toISOString(), ...(typeof input.error === 'string' ? { error: input.error.slice(0, 4000) } : {}),
+        metrics: (0, agent_runtime_metrics_1.readRuntimeEfficiency)(input.metrics), efficiencySummary: (0, agent_runtime_metrics_1.applyRuntimeSelectionOrigins)((0, agent_runtime_metrics_1.readRuntimeEfficiencySummary)(input.efficiencySummary), selection, context.runId), steps: {} };
+    const payload = JSON.stringify({ schemaVersion: 1, contextHash: hash(contextText), result });
+    const file = node_path_1.default.join(node_path_1.default.dirname(contextPath), 'desktop-runtime-history.json'), temporary = file + '.' + (0, node_crypto_1.randomUUID)() + '.tmp';
+    try {
+        node_fs_1.default.writeFileSync(temporary, JSON.stringify({ payload, integrity: hash(payload) }), { mode: 0o600, flag: 'wx' });
+        node_fs_1.default.renameSync(temporary, file);
+    }
+    finally {
+        node_fs_1.default.rmSync(temporary, { force: true });
+    }
+}
+function readRuntimeHistory(contextPath) {
+    const file = node_path_1.default.join(node_path_1.default.dirname(contextPath), 'desktop-runtime-history.json');
+    if (!node_fs_1.default.existsSync(file))
+        return null;
+    if (node_fs_1.default.lstatSync(file).isSymbolicLink() || node_fs_1.default.statSync(file).size > 128 * 1024)
+        throw new Error('Historical runtime projection is invalid');
+    const envelope = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+    if (typeof envelope.payload !== 'string' || hash(envelope.payload) !== envelope.integrity)
+        throw new Error('Historical runtime projection integrity failed');
+    const value = JSON.parse(envelope.payload), contextText = node_fs_1.default.readFileSync(contextPath, 'utf8');
+    if (value.schemaVersion !== 1 || value.contextHash !== hash(contextText) || value.result?.runId !== JSON.parse(contextText).runId || !['running', 'succeeded', 'paused', 'failed', 'blocked', 'cancelled'].includes(value.result.status))
+        throw new Error('Historical runtime projection scope changed');
+    return { ...value.result, metrics: (0, agent_runtime_metrics_1.readRuntimeEfficiency)(value.result.metrics), efficiencySummary: (0, agent_runtime_metrics_1.readRuntimeEfficiencySummary)(value.result.efficiencySummary), steps: {} };
+}

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

@@ -3,6 +3,9 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.findCoreAgentRuntimeEntry = findCoreAgentRuntimeEntry;
 exports.resetCoreAgentRuntimeApiCache = resetCoreAgentRuntimeApiCache;
 exports.loadCoreAgentRuntime = loadCoreAgentRuntime;
+exports.requireRuntimeCapabilities = requireRuntimeCapabilities;
+exports.validateRoleCapabilities = validateRoleCapabilities;
+exports.validateRequestedRoleEfforts = validateRequestedRoleEfforts;
 exports.findCoreAgentRuntimeCli = findCoreAgentRuntimeCli;
 const node_fs_1 = require("node:fs");
 const node_child_process_1 = require("node:child_process");
@@ -11,6 +14,7 @@ const node_path_1 = require("node:path");
 const core_runtime_1 = require("./core-runtime");
 const core_node_runtime_1 = require("./core-node-runtime");
 const win_spawn_1 = require("./util/win-spawn");
+const agent_runtime_package_1 = require("./agent-runtime-package");
 /** An explicit or bundled installation is authoritative: never silently replace
  * a broken production bundle with a developer's checkout. */
 function findCoreAgentRuntimeEntry() {
@@ -42,7 +46,7 @@ function findCoreAgentRuntimeEntry() {
     }
     return null;
 }
-/** The api probe is stable for a given CLI file; repeated settings saves need not respawn it.
+/** The api probe is stable for executable package content; settings saves need not respawn it.
  * Validation stays uncached because its answer depends on the submitted configuration. */
 const apiProbeCache = new Map();
 function resetCoreAgentRuntimeApiCache() { apiProbeCache.clear(); }
@@ -57,18 +61,42 @@ async function loadCoreAgentRuntime() {
         cwd: (0, node_path_1.dirname)(cli), env: (0, win_spawn_1.windowsSpawnEnv)(process.env), input, encoding: 'utf8',
         timeout: 15_000, maxBuffer: 2 * 1024 * 1024, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'],
     });
-    const stat = (0, node_fs_1.statSync)(cli);
+    const fingerprint = (0, agent_runtime_package_1.runtimeEntryFingerprint)(cli);
     const cached = apiProbeCache.get(cli);
-    if (!cached || cached.mtimeMs !== stat.mtimeMs || cached.size !== stat.size) {
-        const api = JSON.parse(invoke(['api']));
+    let api = cached?.fingerprint === fingerprint ? cached.api : undefined;
+    if (!api) {
+        api = JSON.parse(invoke(['api']));
         if (api.type !== 'runtime-api' || api.apiVersion !== 1) {
             throw new Error('Incompatible Core agent runtime API; expected version 1. Update the paired Core bundle.');
         }
-        apiProbeCache.set(cli, { mtimeMs: stat.mtimeMs, size: stat.size });
+        if (api.capabilities !== undefined && (!api.capabilities || typeof api.capabilities !== 'object' || Array.isArray(api.capabilities) || Object.values(api.capabilities).some(value => !Number.isSafeInteger(value) || value < 1)))
+            throw new Error('Core returned malformed runtime capabilities');
+        if (api.workflowVersions !== undefined && (!Array.isArray(api.workflowVersions) || !api.workflowVersions.every(value => typeof value === 'string' && /^\d+$/.test(value))))
+            throw new Error('Core returned malformed workflow versions');
+        if (api.runtimeIdentity !== undefined) {
+            const identity = api.runtimeIdentity;
+            if (!identity || identity.apiVersion !== 1 || !['packageVersion', 'workflowVersion', 'instructionsVersion', 'packageIntegrity'].every(key => typeof identity[key] === 'string') || !/^sha256:[a-f0-9]{64}$/.test(identity.packageIntegrity))
+                throw new Error('Core returned malformed runtime identity');
+        }
+        apiProbeCache.set(cli, { fingerprint, api });
     }
     return {
         RUNTIME_API_VERSION: 1,
+        api,
+        capabilities(input) {
+            if (api.capabilities?.efficientRoleExecution !== 1)
+                throw new Error('Installed Core does not support role capability introspection. Update the paired Core package.');
+            const result = JSON.parse(invoke(['capabilities', '--stdin'], JSON.stringify(input)));
+            return { ...validateRoleCapabilities(result, input), runtimeIdentity: api.runtimeIdentity };
+        },
+        rolePromptDefaults() {
+            const result = JSON.parse(invoke(['prompts']));
+            if (result.type !== 'runtime-role-prompts' || !['architect', 'developer', 'reviewer'].every(role => typeof result.defaults?.[role] === 'string' && result.defaults[role].trim()))
+                throw new Error('Core role prompt catalog is unavailable. Update the paired Core bundle.');
+            return result.defaults;
+        },
         validateRuntimeConfig(input) {
+            requireRuntimeCapabilities(api, input);
             const result = JSON.parse(invoke(['validate', '--stdin'], JSON.stringify(input)));
             if (result.type !== 'runtime-config-valid')
                 throw new Error('Core did not validate the runtime configuration');
@@ -76,6 +104,63 @@ async function loadCoreAgentRuntime() {
         },
     };
 }
+function requireRuntimeCapabilities(api, input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        return;
+    const config = input;
+    if ((config.efficiency !== undefined || Object.values(config.agents ?? {}).some(role => role?.effort !== undefined || role?.escalation !== undefined)) && api.capabilities?.efficientRoleExecution !== 1)
+        throw new Error('Requested role efficiency policy is unsupported by this Core runtime. Update the paired Core package.');
+    if (Array.isArray(config.verification) && config.verification.some(check => check?.policy !== undefined || check?.key !== undefined || check?.label !== undefined) && api.capabilities?.reproducibleVerification !== 1)
+        throw new Error('Requested verification policy is unsupported by this Core runtime. Update the paired Core package.');
+}
+/** Validate transport evidence against the exact submitted role selections. */
+function validateRoleCapabilities(value, input) {
+    const invalid = () => { throw new Error('Core returned malformed role capabilities'); };
+    const object = (value) => value && typeof value === 'object' && !Array.isArray(value) ? value : invalid();
+    const result = object(value), config = object(input);
+    const choices = Object.entries(object(config.agents));
+    if (result.type !== 'runtime-capabilities' || result.schemaVersion !== 1 || !Array.isArray(result.roles) || result.roles.length > 6)
+        return invalid();
+    const expected = choices.flatMap(([role, value]) => {
+        const selected = object(value);
+        return [['base', selected], ...(selected.escalation ? [['escalation', object(selected.escalation)]] : [])].map(([tier, choice]) => {
+            const model = choice;
+            return { role, tier: String(tier), provider: selected.provider, model: model.model ?? null, requestedEffort: model.effort ?? null };
+        });
+    });
+    if (expected.length !== result.roles.length || expected.length < 3)
+        return invalid();
+    const seen = new Set();
+    const roles = result.roles.map(value => {
+        const row = object(value);
+        const selected = expected.find(item => Object.entries(item).every(([key, value]) => row[key] === value));
+        if (!selected)
+            return invalid();
+        const key = String(row.role) + ':' + String(row.tier);
+        if (seen.has(key))
+            return invalid();
+        seen.add(key);
+        if (typeof row.transport !== 'string' || !row.transport || row.transport.length > 128 || !['supported', 'unsupported', 'unknown'].includes(String(row.continuation)) || !['supported', 'unsupported', 'unknown'].includes(String(row.effortSupport)) || typeof row.observedModel !== 'boolean' || typeof row.observedEffort !== 'boolean')
+            return invalid();
+        if (row.supportedEfforts !== null && (!Array.isArray(row.supportedEfforts) || row.supportedEfforts.length > 32 || !row.supportedEfforts.every((level) => typeof level === 'string' && /^[a-z][a-z0-9_-]{0,31}$/.test(level))))
+            return invalid();
+        const levels = row.supportedEfforts;
+        if (row.effortSupport === 'supported' && !levels?.length || row.effortSupport === 'unknown' && levels !== null || row.effortSupport === 'unsupported' && levels?.length !== 0)
+            return invalid();
+        return { ...selected, transport: row.transport, continuation: row.continuation, effortSupport: row.effortSupport, supportedEfforts: levels, observedModel: row.observedModel, observedEffort: row.observedEffort };
+    });
+    return { type: 'runtime-capabilities', schemaVersion: 1, roles };
+}
+function validateRequestedRoleEfforts(runtime, config) {
+    if (!Object.values(config.agents).some(role => role.effort !== undefined || role.escalation?.effort !== undefined))
+        return;
+    if (!runtime.capabilities)
+        throw new Error('Installed Core cannot validate requested role effort');
+    const result = validateRoleCapabilities(runtime.capabilities(config), config);
+    for (const row of result.roles)
+        if (row.requestedEffort !== null && (row.effortSupport !== 'supported' || !row.supportedEfforts?.includes(String(row.requestedEffort))))
+            throw new Error(`${row.role} (${row.tier}): effort '${row.requestedEffort}' is not confirmed for ${row.transport}. Select provider default or a supported effort.`);
+}
 function findCoreAgentRuntimeCli() {
     const entry = findCoreAgentRuntimeEntry();
     if (!entry)