specrails-desktop 2.44.2 → 2.45.0

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

@@ -0,0 +1,183 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RUNTIME_HOST_ENV_KEYS = void 0;
+exports.selectAgentRuntime = selectAgentRuntime;
+exports.runtimeChangeName = runtimeChangeName;
+exports.runAgentRuntimeInvocation = runAgentRuntimeInvocation;
+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_settings_1 = require("./agent-runtime-settings");
+const core_node_runtime_1 = require("./core-node-runtime");
+const win_spawn_1 = require("./util/win-spawn");
+/** The stored admission wins over configuration changes for an existing run. */
+function selectAgentRuntime(configPath, contextPath) {
+    if (contextPath && (0, node_fs_1.existsSync)((0, node_path_1.join)((0, node_path_1.dirname)(contextPath), 'agent-runtime-request.json')))
+        return true;
+    if (!(0, node_fs_1.existsSync)(configPath))
+        return false;
+    return (0, agent_runtime_settings_1.validateAgentRuntimeConfig)(JSON.parse((0, node_fs_1.readFileSync)(configPath, 'utf8'))).enabled;
+}
+function runtimeChangeName(runId) {
+    return 'runtime-' + (0, node_crypto_1.createHash)('sha256').update(runId).digest('hex').slice(0, 20);
+}
+exports.RUNTIME_HOST_ENV_KEYS = [
+    'SPECRAILS_REPO_DIR', 'SPECRAILS_GIT_AUTO', 'SPECRAILS_REPO_MAP_PATH',
+    'SPECRAILS_EXECUTION_CONTEXT', 'SPECRAILS_EXECUTION_MANIFEST', 'SPECRAILS_REPOSITORIES',
+    'SPECRAILS_WORKSPACE_DIR', 'SPECRAILS_TICKETS_PATH', 'SPECRAILS_STATE_DIR',
+    'SPECRAILS_BACKLOG_CONFIG_PATH', 'SPECRAILS_PROFILES_DIR',
+    'SPECRAILS_PROFILE_PATH',
+];
+function saveHostContext(options) {
+    const file = (0, node_path_1.join)((0, node_path_1.dirname)(options.contextPath), 'desktop-runtime-host.json');
+    const serialized = JSON.stringify({ schemaVersion: 1, cwd: (0, node_fs_1.realpathSync)(options.cwd), env: Object.fromEntries(exports.RUNTIME_HOST_ENV_KEYS.filter(key => options.env[key] !== undefined).map(key => [key, options.env[key]])) }, null, 2) + '\n';
+    (0, node_fs_1.mkdirSync)((0, node_path_1.dirname)(file), { recursive: true, mode: 0o700 });
+    try {
+        (0, node_fs_1.writeFileSync)(file, serialized, { flag: 'wx', mode: 0o600 });
+    }
+    catch (error) {
+        if (error.code !== 'EEXIST')
+            throw error;
+        if ((0, node_fs_1.readFileSync)(file, 'utf8') !== serialized)
+            throw new Error('Desktop runtime scope changed; resume using its frozen host context');
+    }
+}
+/** 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)();
+    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))
+        throw new Error('New programmatic runs require configuration and a change name');
+    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)
+        args.push('--config', options.configPath, '--change', options.change);
+    for (const [flag, values] of [['approve', options.approve], ['recover', options.recover], ['invalidate', options.invalidate]]) {
+        if (values?.length)
+            args.push('--' + flag, values.join(','));
+    }
+    if (options.answer !== undefined) {
+        if (!options.resume)
+            throw new Error('Answers apply to runtime resume');
+        args.push('--answer', options.answer);
+    }
+    const started = Date.now();
+    return new Promise((resolve) => {
+        let result;
+        let stderr = '', summary = '', invalidProtocol = false, timedOut = false;
+        let timer;
+        const child = (0, node_child_process_1.spawn)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), args, {
+            cwd: options.cwd, env: (0, win_spawn_1.windowsSpawnEnv)(options.env), shell: false, windowsHide: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        // Always leave a terminal result, including synchronous observer failures.
+        let observerError;
+        try {
+            options.onSpawn?.(child);
+        }
+        catch (error) {
+            observerError = error instanceof Error ? error.message : String(error);
+            if (child.pid)
+                (0, win_spawn_1.treeKillSafe)(child.pid, 'SIGKILL');
+        }
+        const observe = (callback) => { try {
+            callback?.();
+        }
+        catch { /* Logging cannot replay a workflow. */ } };
+        const lines = (0, node_readline_1.createInterface)({ input: child.stdout });
+        lines.on('line', line => {
+            if (line.length > 2_000_000) {
+                invalidProtocol = true;
+                if (child.pid)
+                    (0, win_spawn_1.treeKillSafe)(child.pid, 'SIGKILL');
+                return;
+            }
+            let event;
+            try {
+                event = JSON.parse(line);
+            }
+            catch {
+                invalidProtocol = true;
+                return;
+            }
+            if (!event || typeof event !== 'object') {
+                invalidProtocol = true;
+                return;
+            }
+            observe(() => options.onRawLine?.(line));
+            if (event.type === 'runtime-result') {
+                if (result)
+                    invalidProtocol = true;
+                result = event;
+            }
+            else if (event.type === 'workflow-event') {
+                const payload = event.event;
+                if (payload?.type)
+                    observe(() => options.onLine?.(`[runtime] ${payload.type}${payload.stepId ? ': ' + payload.stepId : ''}${payload.message ? ' — ' + payload.message : ''}\n`));
+            }
+            else if (event.type === 'agent-event') {
+                const payload = event.event;
+                const role = typeof event.role === 'string' ? event.role : 'agent';
+                if (payload?.kind === 'text' && typeof payload.text === 'string') {
+                    summary = (summary + payload.text).slice(-32_000);
+                    observe(() => options.onLine?.(payload.text + '\n'));
+                }
+                else if (payload?.kind === 'tool-start' && typeof payload.tool === 'string') {
+                    // Live tool activity keeps a long developer turn from looking hung.
+                    observe(() => options.onLine?.(`[${role}] ${payload.tool}${payload.detail ? ' ' + payload.detail : ''}\n`));
+                }
+            }
+            else if (event.type === 'verification-output' && typeof event.text === 'string') {
+                observe(() => options.onLine?.(String(event.text)));
+            }
+            else if (event.type === 'span') {
+                // Trace spans are telemetry; the raw line is already recorded for diagnostics.
+            }
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr = (stderr + chunk.toString('utf8')).slice(-32_000);
+            observe(() => options.onLine?.(chunk.toString('utf8'), 'stderr'));
+        });
+        child.on('error', error => { stderr = error.message; });
+        if (options.timeoutMs && options.timeoutMs > 0) {
+            timer = setTimeout(() => {
+                timedOut = true;
+                if (child.pid)
+                    (0, win_spawn_1.treeKillSafe)(child.pid, 'SIGKILL');
+            }, options.timeoutMs);
+            timer.unref?.();
+        }
+        child.on('close', code => {
+            if (timer)
+                clearTimeout(timer);
+            lines.close();
+            const usage = result?.invocationUsage;
+            const known = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : undefined;
+            const cost = known(usage?.costUsd), tokensIn = known(usage?.inputTokens), tokensOut = known(usage?.outputTokens);
+            if (result?.status === 'succeeded' && result.runId !== admittedContext.runId)
+                invalidProtocol = true;
+            const failed = code !== 0 || result?.status !== 'succeeded' || invalidProtocol || timedOut || Boolean(observerError);
+            const errorText = observerError ?? (timedOut ? 'Programmatic workflow timed out; inspect its checkpoint before recovery'
+                : invalidProtocol ? 'Core returned an invalid runtime event stream'
+                    : result?.error ?? (result?.status === 'paused' ? (typeof result.pendingQuestion?.question === 'string' && result.pendingQuestion.question.trim()
+                        ? `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));
+            resolve({
+                text: summary || (failed ? errorText ?? '' : 'Programmatic implementation verified and archived.'),
+                provider: 'agent-runtime', model: 'per-role', failed, errorText,
+                cost, tokensIn, tokensOut, tokens: tokensIn === undefined || tokensOut === undefined ? undefined : tokensIn + tokensOut,
+                estimated: cost === undefined, durationMs: Date.now() - started,
+            });
+        });
+    });
+}

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

@@ -0,0 +1,44 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.shutdownAgentRuntimeControls = shutdownAgentRuntimeControls;
+exports.registerAgentRuntimeControlRoutes = registerAgentRuntimeControlRoutes;
+const agent_runtime_controls_1 = require("./agent-runtime-controls");
+const controllers = new WeakMap();
+function shutdownAgentRuntimeControls(context) { controllers.get(context)?.shutdown(); }
+function registerAgentRuntimeControlRoutes({ router, ctx }) {
+    function controls(request) {
+        const context = ctx(request);
+        let controller = controllers.get(context);
+        if (!controller) {
+            controller = new agent_runtime_controls_1.AgentRuntimeControls(context);
+            controllers.set(context, controller);
+        }
+        return controller;
+    }
+    router.get('/:projectId/agent-runtime/runs', async (req, res) => {
+        try {
+            res.json({ runs: await controls(req).list() });
+        }
+        catch {
+            res.status(500).json({ error: 'runtime_status_failed', message: 'Could not read runtime executions' });
+        }
+    });
+    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));
+            res.status(202).json({ accepted: 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_resume_failed', message: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.message : 'Could not resume runtime execution' });
+        }
+    });
+    router.post('/:projectId/agent-runtime/runs/:runId/cancel', (req, res) => {
+        try {
+            controls(req).cancel(String(req.params.runId));
+            res.status(202).json({ accepted: 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_cancel_failed', message: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.message : 'Could not cancel runtime execution' });
+        }
+    });
+}

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

@@ -0,0 +1,277 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRuntimeControls = exports.RuntimeControlError = void 0;
+exports.validateRuntimeResumeInput = validateRuntimeResumeInput;
+exports.readAgentRuntimeStatus = readAgentRuntimeStatus;
+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_bridge_1 = require("./agent-runtime-bridge");
+const core_node_runtime_1 = require("./core-node-runtime");
+const win_spawn_1 = require("./util/win-spawn");
+const workspace_resolution_1 = require("./workspace-resolution");
+const loop_runs_store_1 = require("./loop-runs-store");
+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 ANSWER_LIMIT = 20_000;
+class RuntimeControlError extends Error {
+    statusCode;
+    code;
+    constructor(statusCode, code, message) {
+        super(message);
+        this.statusCode = statusCode;
+        this.code = code;
+    }
+}
+exports.RuntimeControlError = RuntimeControlError;
+function validateRuntimeResumeInput(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new RuntimeControlError(400, 'invalid_resume_request', 'Resume request must be an object');
+    const body = input;
+    for (const [key, value] of Object.entries(body)) {
+        if (key === 'answer') {
+            if (typeof value !== 'string' || !value.trim() || value.length > ANSWER_LIMIT)
+                throw new RuntimeControlError(400, 'invalid_resume_request', `An answer must be a nonempty string of at most ${ANSWER_LIMIT} characters`);
+            continue;
+        }
+        if (!['approve', 'recover', 'invalidate'].includes(key) || !Array.isArray(value) || value.length > STEP_IDS.length || !value.every((id) => typeof id === 'string' && STEP_IDS.includes(id)) || new Set(value).size !== value.length)
+            throw new RuntimeControlError(400, 'invalid_resume_request', 'Only approve, recover and invalidate arrays of known phase IDs are allowed');
+    }
+    return body;
+}
+/** A question stays pending until Core records its answer. */
+function openQuestion(state) {
+    return state.pendingQuestion && state.pendingQuestion.answeredAt === undefined ? state.pendingQuestion : undefined;
+}
+/** 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)();
+    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'], {
+        cwd, env: (0, win_spawn_1.windowsSpawnEnv)(env), windowsHide: true, timeout: 15000, maxBuffer: 4 * 1024 * 1024, encoding: 'utf8',
+    });
+    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;
+}
+/** 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;
+    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 }) {
+        this.ctx = ctx;
+        this.dependencies = dependencies;
+    }
+    context(runId) {
+        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);
+        const backlogRoot = node_fs_1.default.realpathSync(node_path_1.default.dirname(execution.specrailsDir));
+        const directory = node_path_1.default.join(execution.specrailsDir, 'pipeline', runId);
+        const file = node_path_1.default.join(directory, 'desktop-context.json');
+        if (!node_fs_1.default.existsSync(file))
+            throw new RuntimeControlError(404, 'runtime_run_not_found', 'Runtime execution context is unavailable');
+        if (node_fs_1.default.realpathSync(file) !== node_path_1.default.join(node_fs_1.default.realpathSync(execution.specrailsDir), 'pipeline', runId, 'desktop-context.json'))
+            throw new RuntimeControlError(409, 'runtime_scope_changed', 'Runtime context path no longer matches its project');
+        const frozen = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+        try {
+            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())
+                    throw new Error();
+            }
+        }
+        catch {
+            throw new RuntimeControlError(409, 'runtime_scope_unavailable', 'The original runtime worktree or project scope is unavailable. Start a new implementation.');
+        }
+        const stored = this.ctx.db.prepare('SELECT execution_manifest FROM loop_runs WHERE id = ?').get(runId);
+        const manifest = (0, multi_repo_execution_store_1.readExecutionManifest)(stored?.execution_manifest);
+        if (manifest && (manifest.projectId !== this.ctx.project.id || manifest.repositories.length !== frozen.repositories.length || !manifest.repositories.every((repository) => frozen.repositories.some((item) => item.id === repository.repositoryId && item.path === repository.worktreePath))))
+            throw new RuntimeControlError(409, 'runtime_scope_changed', 'The saved worktree manifest differs from the frozen runtime scope');
+        const hostFile = node_path_1.default.join(directory, 'desktop-runtime-host.json');
+        if (!node_fs_1.default.existsSync(hostFile))
+            throw new RuntimeControlError(409, 'runtime_host_unavailable', 'The original runtime host settings are missing. Start a new implementation.');
+        const host = JSON.parse(node_fs_1.default.readFileSync(hostFile, 'utf8'));
+        if (host.schemaVersion !== 1 || typeof host.cwd !== 'string' || ![frozen.backlogRoot, ...frozen.repositories.map((repository) => repository.path)].includes(host.cwd) || !host.env || typeof host.env !== 'object' || Array.isArray(host.env) || Object.entries(host.env).some(([key, value]) => !agent_runtime_bridge_1.RUNTIME_HOST_ENV_KEYS.includes(key) || typeof value !== 'string'))
+            throw new RuntimeControlError(409, 'runtime_host_invalid', 'The saved runtime host settings are invalid');
+        const env = { ...(0, workspace_resolution_1.resolveLoopBaseEnv)(this.ctx.project) };
+        for (const key of agent_runtime_bridge_1.RUNTIME_HOST_ENV_KEYS)
+            delete env[key];
+        Object.assign(env, host.env, { SPECRAILS_EXECUTION_CONTEXT: file });
+        return { file, frozen, cwd: host.cwd, env };
+    }
+    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))
+            return [];
+        const entries = node_fs_1.default.readdirSync(directory, { withFileTypes: true }).filter((entry) => entry.isDirectory() && SAFE_ID.test(entry.name) && node_fs_1.default.existsSync(node_path_1.default.join(directory, entry.name, 'agent-runtime-request.json')))
+            .sort((a, b) => node_fs_1.default.statSync(node_path_1.default.join(directory, b.name)).mtimeMs - node_fs_1.default.statSync(node_path_1.default.join(directory, a.name)).mtimeMs).slice(0, 20);
+        const runs = [];
+        // Bounded sequential reads avoid spawning one Node process per historical run at once.
+        for (const entry of entries)
+            runs.push(await this.summary(entry.name));
+        return runs;
+    }
+    async summary(runId) {
+        try {
+            const { file, cwd, env } = this.context(runId);
+            // Core owns checkpoint parsing. Its atomic file revision is only a cache
+            // 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 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)
+                throw new Error('No saved workflow state is available');
+            if (fingerprint)
+                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';
+            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,
+                traceId: state.traceId, pendingQuestion: openQuestion(state),
+                recoverableSteps, active, canCancel: this.active.has(runId), canResume: !active && parent?.status === 'completed' && state.status !== 'succeeded' };
+        }
+        catch (error) {
+            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' };
+        }
+    }
+    async resume(runId, input) {
+        if (this.disposed)
+            throw new RuntimeControlError(503, 'runtime_shutting_down', 'Project runtime is shutting down');
+        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');
+        const context = this.context(runId);
+        // Reserve before awaiting status so concurrent resume requests cannot race.
+        const active = { cancelled: false };
+        this.active.set(runId, active);
+        try {
+            // Accounting from a prior continuation must settle even when Core now
+            // reports success and correctly refuses any further execution.
+            (0, loop_run_manager_1.recoverOrphanLoopStepAccounting)(this.ctx.db, new Date().toISOString(), runId);
+            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');
+            // 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');
+            this.errors.delete(runId);
+            this.statusCache.delete(runId);
+            const startedAt = new Date().toISOString();
+            const invocationId = (0, node_crypto_1.randomUUID)();
+            const stepKey = `runtime-resume:${invocationId}`;
+            // Both live settlement and restart use the existing loop ledger.
+            const previous = (0, loop_runs_store_1.getLoopRun)(this.ctx.db, runId);
+            let sequence = this.ctx.db.prepare('SELECT COALESCE(MAX(seq), -1) AS seq FROM events WHERE job_id = ?').get(runId).seq;
+            const startedAtMs = Date.parse(startedAt);
+            let ticketIds = [];
+            try {
+                const ids = JSON.parse(previous.ticket_ids_json ?? '[]');
+                if (Array.isArray(ids))
+                    ticketIds = ids.filter((id) => typeof id === 'number' && Number.isSafeInteger(id));
+            }
+            catch { /* Older loop records can lack a ticket scope. */ }
+            (0, loop_runs_store_1.stageLoopStepRecovery)(this.ctx.db, {
+                version: 1, runId, stepKey, invocationId, projectId: this.ctx.project.id,
+                provider: 'agent-runtime', model: 'per-role', surfaceRefId: stepKey,
+                ticketIds, startedAt, baseline: (0, loop_runs_store_1.readLoopJobUsage)(this.ctx.db, runId),
+                completedEventSeq: sequence, providerCostBaseline: 0, providerTurnsBaseline: 0,
+                loopDurationBaseline: previous.total_duration_ms, completedDurationMs: 0,
+                iterationCount: previous.iteration_count, activeTurnStartedAtMs: startedAtMs, lastActivityAtMs: startedAtMs,
+            });
+            const logLine = (line, source = 'stdout') => {
+                if (this.disposed)
+                    return;
+                try {
+                    (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 */ }
+            };
+            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({
+                contextPath: context.file, cwd: context.cwd, env: context.env, resume: true, ...input,
+                // Readable progress lands in the same job log as the original rail run.
+                onLine: logLine,
+                onRawLine: (line) => {
+                    if (this.disposed)
+                        return;
+                    let eventType = 'agent-runtime';
+                    try {
+                        const parsed = JSON.parse(line);
+                        if (typeof parsed.type === 'string')
+                            eventType = parsed.type;
+                    }
+                    catch { /* Keep raw diagnostics available to recovery. */ }
+                    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());
+                    })();
+                },
+                onSpawn: (child) => {
+                    active.child = child;
+                    if (this.disposed && child.pid)
+                        this.dependencies.kill(child.pid, 'SIGKILL');
+                    else if (active.cancelled)
+                        this.cancel(runId);
+                },
+            }).then((result) => {
+                if (this.disposed)
+                    return;
+                logLine(result.failed ? `[runtime] continuation ended: ${result.errorText ?? 'failed'}` : '[runtime] continuation completed', result.failed ? 'stderr' : 'stdout');
+                (0, loop_runs_store_1.setLoopStepSettledResult)(this.ctx.db, runId, stepKey, { ...result, provider: 'agent-runtime', model: 'per-role', failed: active.cancelled || result.failed });
+                (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); });
+        }
+        catch (error) {
+            this.active.delete(runId);
+            throw error;
+        }
+    }
+    cancel(runId) {
+        const active = this.active.get(runId);
+        if (!active)
+            throw new RuntimeControlError(409, 'runtime_not_active', 'Only a continuation started here can be cancelled here; stop active rail runs from their job controls');
+        active.cancelled = true;
+        if (active.child?.pid) {
+            this.dependencies.kill(active.child.pid, this.disposed ? 'SIGKILL' : 'SIGTERM');
+            if (!this.disposed && !active.forceKillTimer) {
+                const pid = active.child.pid;
+                active.forceKillTimer = setTimeout(() => {
+                    if (this.active.get(runId) === active)
+                        this.dependencies.kill(pid, 'SIGKILL');
+                }, 3000);
+                active.forceKillTimer.unref?.();
+            }
+        }
+    }
+    shutdown() {
+        this.disposed = true;
+        for (const runId of this.active.keys())
+            this.cancel(runId);
+    }
+}
+exports.AgentRuntimeControls = AgentRuntimeControls;

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

@@ -0,0 +1,85 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.findCoreAgentRuntimeEntry = findCoreAgentRuntimeEntry;
+exports.resetCoreAgentRuntimeApiCache = resetCoreAgentRuntimeApiCache;
+exports.loadCoreAgentRuntime = loadCoreAgentRuntime;
+exports.findCoreAgentRuntimeCli = findCoreAgentRuntimeCli;
+const node_fs_1 = require("node:fs");
+const node_child_process_1 = require("node:child_process");
+const node_module_1 = require("node:module");
+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");
+/** An explicit or bundled installation is authoritative: never silently replace
+ * a broken production bundle with a developer's checkout. */
+function findCoreAgentRuntimeEntry() {
+    const explicit = process.env.SPECRAILS_CORE_RUNTIME_PATH;
+    if (explicit) {
+        const entry = (0, node_path_1.resolve)(explicit);
+        return (0, node_fs_1.existsSync)(entry) ? entry : null;
+    }
+    const selected = (0, core_runtime_1.getCoreRuntimeStatus)();
+    if (selected.error)
+        return null;
+    if (selected.runtime) {
+        const entry = (0, node_path_1.join)(selected.runtime.root, 'dist', 'agent-runtime', 'index.js');
+        if ((0, node_fs_1.existsSync)(entry))
+            return entry;
+        // Match Desktop's activated Core package, including managed upgrades. A
+        // missing API must never load an older bundle behind an active framework.
+        if (process.env.NODE_ENV === 'production' || ['managed', 'override', 'bundled'].includes(selected.runtime.source))
+            return null;
+    }
+    try {
+        return (0, node_module_1.createRequire)((0, node_path_1.join)(process.cwd(), 'package.json')).resolve('specrails-core/agent-runtime');
+    }
+    catch { /* A source checkout can use the sibling Core build. */ }
+    if (process.env.NODE_ENV !== 'production') {
+        const entry = (0, node_path_1.resolve)(process.cwd(), '..', 'specrails-core', 'dist', 'agent-runtime', 'index.js');
+        if ((0, node_fs_1.existsSync)(entry))
+            return entry;
+    }
+    return null;
+}
+/** The api probe is stable for a given CLI file; repeated 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(); }
+async function loadCoreAgentRuntime() {
+    const cli = findCoreAgentRuntimeCli();
+    if (!cli)
+        throw new Error('Programmatic agent runtime is unavailable. Build or bundle a compatible specrails-core release.');
+    // Core is ESM. Desktop ships both CJS and a pkg sidecar; importing external
+    // ESM from either depends on host-loader details. The bundled ordinary Node
+    // process is the same portable boundary used for execution and inspection.
+    const invoke = (args, input) => (0, node_child_process_1.execFileSync)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), [cli, ...args], {
+        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 cached = apiProbeCache.get(cli);
+    if (!cached || cached.mtimeMs !== stat.mtimeMs || cached.size !== stat.size) {
+        const 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 });
+    }
+    return {
+        RUNTIME_API_VERSION: 1,
+        validateRuntimeConfig(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');
+            return input;
+        },
+    };
+}
+function findCoreAgentRuntimeCli() {
+    const entry = findCoreAgentRuntimeEntry();
+    if (!entry)
+        return null;
+    const cli = (0, node_path_1.join)((0, node_path_1.dirname)(entry), 'cli.js');
+    return (0, node_fs_1.existsSync)(cli) ? cli : null;
+}

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

@@ -0,0 +1,12 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.hasAgentRuntimeRequest = hasAgentRuntimeRequest;
+const node_fs_1 = require("node:fs");
+const node_path_1 = require("node:path");
+const workspace_resolution_1 = require("./workspace-resolution");
+function hasAgentRuntimeRequest(project, runId) {
+    if (!/^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/.test(runId))
+        return false;
+    const file = (0, node_path_1.join)((0, workspace_resolution_1.resolveProjectExecution)(project).specrailsDir, 'pipeline', runId, 'agent-runtime-request.json');
+    return (0, node_fs_1.existsSync)(file);
+}