specrails-desktop 2.57.1 → 2.58.0

package/server/dist/mcp/tools/jobs.js

@@ -41,6 +41,7 @@ function jobsTools() {
                 'runtime_runs (read the programmatic runtime state of jobId — or every run when omitted — status, nextStep, canResume, recoverableSteps, pendingApproval, pendingQuestion; THIS is how you learn why a run failed and what recovery it offers), ' +
                 'runtime_diagnose (read-only recovery assessment for jobId: original scope, completed steps, repeated failures and verification invalidation reasons; use before recommending retry or relaunch), ' +
                 'runtime_evidence (read the durable runtime evidence of jobId; page with evidenceId/section/sourceId/cursor/limit), ' +
+                'runtime_steer (write — queue steeringText in an engine v2 run with a stable requestId; acceptance is not consumption; inspect runtime_runs steering receipts), ' +
                 'runtime_resume (ai-spawn — continue a resumable run: optional approve/recover/invalidate step-id lists + answer for a pending question; act ONLY after the user confirmed on the card), ' +
                 'runtime_recover (ai-spawn — shorthand for runtime_resume with recover:[stepIds] over the recoverable steps), ' +
                 'runtime_approve (write — shorthand for runtime_resume with approve:[stepId] for a pending approval), ' +
@@ -53,7 +54,7 @@ function jobsTools() {
                     return 'destructive';
                 if (['spawn', 'interactive_turn', 'runtime_resume', 'runtime_recover'].includes(action))
                     return 'ai-spawn';
-                if (['pause', 'resume', 'reorder', 'priority', 'finalize', 'runtime_approve', 'runtime_settle', 'runtime_dismiss'].includes(action))
+                if (['pause', 'resume', 'reorder', 'priority', 'finalize', 'runtime_approve', 'runtime_settle', 'runtime_dismiss', 'runtime_steer'].includes(action))
                     return 'write';
                 return 'read';
             },
@@ -89,6 +90,7 @@ function jobsTools() {
                     'runtime_runs',
                     'runtime_diagnose',
                     'runtime_evidence',
+                    'runtime_steer',
                     'runtime_resume',
                     'runtime_recover',
                     'runtime_approve',
@@ -148,6 +150,8 @@ function jobsTools() {
                 provider: zod_1.z.string().optional().describe('Provider to resolve the default spec model for (default_spec_model)'),
                 // ── runtime_* (mission-rail-cards: the agent's eyes + hands on a failed run) ──
                 railIndex: zod_1.z.number().int().nonnegative().optional().describe('runtime_runs: only the latest continuation of this rail (0-based)'),
+                steeringText: zod_1.z.string().min(1).max(20_000).optional().describe('runtime_steer: operator instruction consumed at the next eligible AI attempt'),
+                requestId: zod_1.z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/).optional().describe('runtime_steer: stable idempotency key; reuse only with identical text'),
                 approve: zod_1.z.array(zod_1.z.string()).optional().describe('runtime_resume/runtime_approve: step ids to approve'),
                 recover: zod_1.z.array(zod_1.z.string()).optional().describe('runtime_resume/runtime_recover: step ids to recover (default for runtime_recover: every recoverableStep)'),
                 invalidate: zod_1.z.array(zod_1.z.string()).optional().describe('runtime_resume: step ids whose results must be discarded before continuing'),
@@ -374,6 +378,15 @@ function jobsTools() {
                                 query.set(key, String(args[key]));
                         return (0, types_1.apiCall)(ctx, 'GET', `${base}/agent-runtime/runs/${encodeURIComponent(id)}/evidence${query.size ? '?' + query.toString() : ''}`);
                     }
+                    case 'runtime_steer': {
+                        const id = args.jobId;
+                        if (!id)
+                            throw new Error('runtime_steer requires a "jobId".');
+                        if (typeof args.steeringText !== 'string' || !args.steeringText.trim() || args.steeringText.length > 20_000 || typeof args.requestId !== 'string' || !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(args.requestId))
+                            throw new Error('runtime_steer requires steeringText and a stable requestId.');
+                        const result = await (0, types_1.apiCall)(ctx, 'POST', `${base}/agent-runtime/runs/${encodeURIComponent(id)}/steer`, { text: args.steeringText, requestId: args.requestId });
+                        return { ...result, hint: 'Accepted into the durable inbox; consumption happens at the next eligible AI attempt. Inspect runtime_runs steering receipts.' };
+                    }
                     case 'runtime_resume':
                     case 'runtime_recover':
                     case 'runtime_approve': {

package/server/dist/mcp/tools/loops.js

@@ -15,7 +15,7 @@ const types_1 = require("./types");
  *   - read:        list, get, templates, factory, commands, constants_list,
  *                  preview, run_get
  *   - write:       constant_create, constant_update, import, create, from_template,
- *                  fork, update, publish, unpublish, duplicate
+ *                  fork, update, publish, unpublish, duplicate, restore_builtin
  *   - ai-spawn:    run (spawns an AI CLI, incurs cost, async 202)
  *   - destructive: constant_delete, delete
  */
@@ -32,7 +32,8 @@ function loopsTools() {
                 'list (all saved loops), ' +
                 'get (one loop by id), ' +
                 'templates (built-in template catalog with graphs), ' +
-                'factory (built-in locked factory loops), ' +
+                'factory (the built-in loops — factory:implement, factory:freestyle, factory:sdd-quick-openspec — with the graph a rail launch runs; ' +
+                'built-ins are ordinary editable loops whose loopId IS the factory id: change them with update + publish and the change applies to every rail, chat launch and companion that uses that built-in), ' +
                 'commands (magic-command catalog for the builder palette), ' +
                 'constants_list (global cross-loop constants), ' +
                 'constant_create (write), constant_update (write), constant_delete (destructive), ' +
@@ -40,11 +41,12 @@ function loopsTools() {
                 'import (import loops from an export envelope), ' +
                 'create (new Draft loop), ' +
                 'from_template (instantiate from a template), ' +
-                'fork (fork a factory loop into an editable Draft), ' +
-                'update (name/description/graph — reverts to Draft, 409 while running), ' +
-                'publish (graph-validated), unpublish (409 while running), ' +
+                'fork (same as duplicate for a built-in: copies it into a separate Draft; kept for back-compat), ' +
+                'update (name/description/graph — reverts to Draft; 409 while running except for built-ins, whose rails keep using the last published version until you publish), ' +
+                'publish (graph-validated), unpublish (409 while running; 409 builtin_loop for built-ins), ' +
                 'duplicate (copy a loop), ' +
-                'delete (destructive — 409 while running), ' +
+                'restore_builtin (reset a built-in to its original default, Published — 409 while running), ' +
+                'delete (destructive — 409 while running; built-ins cannot be deleted: 409 builtin_loop, use restore_builtin), ' +
                 'run (ai-spawn — standalone ticket-less run of a Published loop against a project: spawns an AI CLI, incurs token cost, returns 202 with loopRunId), ' +
                 'run_get (read one loop run\'s live/terminal state — the post-timeout recovery read).',
             hintTier: 'read',
@@ -65,6 +67,7 @@ function loopsTools() {
                     'publish',
                     'unpublish',
                     'duplicate',
+                    'restore_builtin',
                 ].includes(action)) {
                     return 'write';
                 }
@@ -91,6 +94,7 @@ function loopsTools() {
                     'publish',
                     'unpublish',
                     'duplicate',
+                    'restore_builtin',
                     'delete',
                     'run',
                     'run_get',
@@ -100,12 +104,12 @@ function loopsTools() {
                     .string()
                     .optional()
                     .describe('Project id (run / run_get only — defaults to the active project; ignored by every other action)'),
-                loopId: zod_1.z.string().optional().describe('Loop id (for get / update / publish / unpublish / duplicate / delete / run — must be Published for run)'),
+                loopId: zod_1.z.string().optional().describe('Loop id (for get / update / publish / unpublish / duplicate / restore_builtin / delete / run — must be Published for run). Built-ins use their factory id, e.g. factory:implement'),
                 repositoryIds: zod_1.z.array(zod_1.z.string().min(1)).min(1).max(50).optional().describe('run only: repository memberships to include in one coordinated standalone execution; omission retains primary-only behavior.'),
                 loopRunId: zod_1.z.string().optional().describe('Loop run id (for run_get — returned by run)'),
                 constantId: zod_1.z.string().optional().describe('Constant id (for constant_update / constant_delete)'),
                 templateId: zod_1.z.string().optional().describe('Template id (for from_template)'),
-                factoryId: zod_1.z.string().optional().describe('Factory loop id (for fork)'),
+                factoryId: zod_1.z.string().optional().describe('Built-in (factory) loop id (for fork, e.g. factory:implement)'),
                 name: zod_1.z
                     .string()
                     .optional()
@@ -246,6 +250,11 @@ function loopsTools() {
                             ...(args.name !== undefined ? { name: args.name } : {}),
                         });
                     }
+                    case 'restore_builtin': {
+                        if (!loopId)
+                            throw new Error('restore_builtin requires a "loopId" (a built-in id such as factory:implement).');
+                        return (0, types_1.apiCall)(ctx, 'POST', `/loops/${encodeURIComponent(loopId)}/restore-builtin`);
+                    }
                     // ── Standalone runs (project-scoped) ────────────────────────────────
                     case 'run': {
                         if (!loopId)

package/server/dist/mcp/tools/rails.js

@@ -47,7 +47,7 @@ function railsTools() {
                 'stop (destructive — kills all active jobs and loop runs for the rail). ' +
                 'For on_review tickets with an already-open GitHub PR (including a published pr_ready delivery), launch automatically tries to continue that PR head branch; Jira-linked in_progress tickets can do the same when the PR match is explicit; fresh tickets still start from the project integration branch. ' +
                 'When launched from the in-app agent chat without an explicit aiEngine, the engine defaults to your conversation\'s provider. On that same provider, an omitted model inherits the conversation model; an explicit model wins (pass aiEngine to override; launch_all always uses each rail\'s stored engine). ' +
-                'For Implement and Batch Implement, the selected launch provider applies to ALL runtime roles (architect, developer, reviewer); an explicit launch model/effort also applies to each role. Resuming an existing execution keeps its original frozen role configuration; start a new launch to change providers. ' +
+                'For Implement, the selected launch provider applies to ALL runtime roles (architect, developer, reviewer); an explicit launch model/effort also applies to each role. Resuming an existing execution keeps its original frozen role configuration; start a new launch to change providers. ' +
                 'User-facing naming: call the free-form autonomous mode "Freestyle"; use "freestyle" as the canonical API enum value for that same capability. ' +
                 'For small OpenSpec-governed work, recommend "SDD Quick (OpenSpec)" and launch with mode "loop" plus loopId "factory:sdd-quick-openspec"; keep Freestyle for ticket-local implementation-only work. ' +
                 'NAMING: railIndex is the 0-BASED internal identity; the dashboard shows rails 1-based ("Rail N" = railIndex N-1). When talking to the user, ALWAYS say "Rail <railIndex + 1>" (or the rail\'s custom name) — results include railLabel with the correct user-facing label.',
@@ -101,9 +101,9 @@ function railsTools() {
                     .describe('Rail display label (<=60 chars); null/empty clears to default (set_name). Also the optional initial name for create_rail.'),
                 // launch
                 mode: zod_1.z
-                    .enum(['implement', 'batch-implement', 'freestyle', 'loop'])
+                    .enum(['implement', 'freestyle', 'loop'])
                     .optional()
-                    .describe('Launch mode (launch; default "implement"). Use "freestyle" as the canonical API enum value for Freestyle. It invokes the selected provider\'s native free-form autonomous workflow (currently Claude and Kimi), one job per ticket. In prose, call it "Freestyle". Loop runs an app-driven loop per ticket.'),
+                    .describe('Launch mode (launch; default "implement"). Implement runs all of the rail\'s tickets in one aggregate run; propose at most 3 specs per rail and split larger sets across rails. Use "freestyle" as the canonical API enum value for Freestyle. It invokes the selected provider\'s native free-form autonomous workflow (currently Claude and Kimi), one job per ticket. In prose, call it "Freestyle". Loop runs an app-driven loop per ticket.'),
                 model: zod_1.z
                     .string()
                     .optional()

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

@@ -3,7 +3,10 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.RUNTIME_HOST_ENV_KEYS = void 0;
 exports.runtimeChangeName = runtimeChangeName;
 exports.scopedHostChecks = scopedHostChecks;
+exports.readFrozenRuntimeHost = readFrozenRuntimeHost;
 exports.runAgentRuntimeInvocation = runAgentRuntimeInvocation;
+exports.assertRetainedForkSupport = assertRetainedForkSupport;
+exports.runAgentRuntimeControl = runAgentRuntimeControl;
 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");
@@ -11,6 +14,7 @@ const agent_runtime_effective_config_1 = require("./agent-runtime-effective-conf
 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_os_1 = require("node:os");
 const node_path_1 = require("node:path");
 const node_readline_1 = require("node:readline");
 const agent_runtime_loader_1 = require("./agent-runtime-loader");
@@ -58,9 +62,26 @@ function saveHostContext(options) {
             throw new Error('Desktop runtime scope changed; resume using its frozen host context');
     }
 }
+/** Recover the original host scope; project settings may have changed since admission. */
+function readFrozenRuntimeHost(contextPath, baseEnv, runId) {
+    const context = JSON.parse((0, node_fs_1.readFileSync)(contextPath, 'utf8'));
+    const roots = [context.backlogRoot, ...(context.repositories ?? []).map(repository => repository.path)];
+    if (context.runId !== runId || !context.repositories?.length || !context.repositories.some(repository => repository.path === context.artifactRoot) || roots.some(root => typeof root !== 'string' || !(0, node_path_1.isAbsolute)(root) || (0, node_fs_1.realpathSync)(root) !== root))
+        throw new Error('runtime_scope_changed: Original workflow scope is unavailable');
+    const host = JSON.parse((0, node_fs_1.readFileSync)((0, node_path_1.join)((0, node_path_1.dirname)(contextPath), 'desktop-runtime-host.json'), 'utf8'));
+    if (host.schemaVersion !== 1 || typeof host.cwd !== 'string' || !roots.includes(host.cwd) || !host.env || typeof host.env !== 'object' || Array.isArray(host.env) || Object.entries(host.env).some(([key, value]) => !exports.RUNTIME_HOST_ENV_KEYS.includes(key) || typeof value !== 'string') || host.env.SPECRAILS_GIT_AUTO !== 'false')
+        throw new Error('runtime_host_invalid: Original workflow host settings are invalid');
+    const env = { ...baseEnv };
+    for (const key of exports.RUNTIME_HOST_ENV_KEYS)
+        delete env[key];
+    return { cwd: host.cwd, env: { ...env, ...host.env, SPECRAILS_EXECUTION_CONTEXT: contextPath } };
+}
 /** 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 definitionEngine = options.engineVersion === 2 || options.definitionPath !== undefined || options.prepareDefinition !== undefined;
+    if (options.resume && (options.definitionPath || options.prepareDefinition || options.workflowRoleBindings))
+        throw new Error('Resume must use the frozen workflow definition and role bindings');
     const selectedCli = options.resume ? (0, agent_runtime_package_1.resolveRetainedAgentRuntime)(options.contextPath) : (0, agent_runtime_loader_1.findCoreAgentRuntimeCli)();
     let cli = selectedCli;
     if (!cli)
@@ -79,13 +100,27 @@ async function runAgentRuntimeInvocation(options) {
             repositoryIds: admittedContext.repositories.map(repo => repo.id), source, providerOverride: options.providerOverride,
         });
         config.verification = scopedHostChecks(config.verification, admittedContext.repositories);
-        config.rolePrompts = { ...(await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).rolePromptDefaults(), ...(0, agent_runtime_settings_1.loadRuntimeRolePrompts)() };
+        config.rolePrompts = { ...(await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).rolePromptDefaults(), ...(0, agent_runtime_settings_1.loadRuntimeRolePrompts)(), ...config.rolePrompts };
         // Core rejects unknown connection keys: drop the desktop-only local-engine
         // fields (label/defaultModel/rates/supportsReasoningEffort) before Core sees it.
         const runtime = await (0, agent_runtime_loader_1.loadCoreAgentRuntime)();
         config.providers = (0, agent_runtime_settings_1.stripDesktopConnectionFields)(config.providers, (0, agent_runtime_settings_1.coreConnectionFieldGates)(runtime.api?.capabilities));
         if (runtime.api?.capabilities?.configurableGuardrails !== 1)
             delete config.guardrails;
+        if (definitionEngine && (runtime.api?.capabilities?.engineV2 !== 1 || runtime.api?.capabilities?.workflowDefinitions !== 1))
+            throw new Error('engine_unsupported: Update Core to run workflow definitions');
+        const compilationConfig = structuredClone(config);
+        if (options.workflowRoleBindings) {
+            compilationConfig.roles = { ...compilationConfig.roles, ...structuredClone(options.workflowRoleBindings) };
+            (0, agent_runtime_effective_config_1.fillDefaultRoleModels)(compilationConfig);
+        }
+        const draft = definitionEngine ? options.prepareDefinition
+            ? options.prepareDefinition(compilationConfig)
+            : options.definitionPath ? JSON.parse((0, node_fs_1.readFileSync)(options.definitionPath, 'utf8')) : undefined : undefined;
+        if (definitionEngine && !draft)
+            throw new Error('A new Core workflow requires a definition');
+        const selectedOrigins = (0, agent_runtime_effective_config_1.bindWorkflowRoleSelections)(config, draft, options.workflowRoleBindings);
+        const workflowOrigins = { ...(0, agent_runtime_effective_config_1.bindWorkflowRoleDefaults)(config, draft), ...selectedOrigins };
         const override = options.providerOverride;
         runtime.validateRuntimeConfig(JSON.parse(JSON.stringify(config)));
         (0, agent_runtime_loader_1.validateRequestedRoleEfforts)(runtime, config);
@@ -93,7 +128,7 @@ async function runAgentRuntimeInvocation(options) {
         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';
+        const selection = JSON.stringify({ schemaVersion: 1, runId: admittedContext.runId, providerOverride: override ?? null, origins: { ...origins, ...workflowOrigins } }) + '\n';
         try {
             (0, node_fs_1.writeFileSync)(selectionFile, selection, { flag: 'wx', mode: 0o600 });
         }
@@ -112,8 +147,27 @@ async function runAgentRuntimeInvocation(options) {
             if ((0, node_fs_1.readFileSync)(scopedPath, 'utf8') !== serialized)
                 throw new Error('Desktop runtime configuration changed; start a new run');
         }
+        if (definitionEngine) {
+            const validation = runtime.validateWorkflowDefinition(draft, { configPath: scopedPath, structural: false });
+            if (!validation.ok)
+                throw new Error('definition_invalid: ' + validation.errors.map(error => `${error.path ?? error.nodeId ?? 'graph'}: ${error.message}`).join('; '));
+            const definitionPath = (0, node_path_1.join)((0, node_path_1.dirname)(options.contextPath), 'desktop-workflow-definition.json');
+            const serializedDefinition = JSON.stringify(validation.definition, null, 2) + '\n';
+            try {
+                (0, node_fs_1.writeFileSync)(definitionPath, serializedDefinition, { flag: 'wx', mode: 0o600 });
+            }
+            catch (error) {
+                if (error.code !== 'EEXIST' || (0, node_fs_1.readFileSync)(definitionPath, 'utf8') !== serializedDefinition)
+                    throw new Error('Frozen workflow definition changed; start a new run');
+            }
+            const pinPath = (0, node_path_1.join)((0, node_path_1.dirname)(options.contextPath), 'desktop-runtime-package.json');
+            options.onPrepared?.({ contextPath: options.contextPath, runtimeDirectory: (0, node_path_1.dirname)(options.contextPath), definitionPath, configPath: scopedPath, definitionHash: validation.version, definition: validation.definition, context: admittedContext, ...((0, node_fs_1.existsSync)(pinPath) ? { runtimeIdentity: JSON.parse((0, node_fs_1.readFileSync)(pinPath, 'utf8')) } : {}) });
+            args.push('--definition', definitionPath);
+        }
         args.push('--config', scopedPath, '--change', options.change);
     }
+    const definitionFile = (0, node_path_1.join)((0, node_path_1.dirname)(options.contextPath), 'desktop-workflow-definition.json');
+    const requiresVerified = definitionEngine && JSON.parse((0, node_fs_1.readFileSync)(definitionFile, 'utf8')).delivery?.requiresVerified === true;
     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'));
@@ -133,10 +187,16 @@ async function runAgentRuntimeInvocation(options) {
             throw new Error('Answers apply to runtime resume');
         args.push('--answer', options.answer);
     }
+    if (options.interruptId) {
+        if (!options.resume)
+            throw new Error('Interrupt selection applies to resume');
+        args.push('--interrupt-id', options.interruptId);
+    }
     const started = Date.now();
     (0, agent_runtime_history_1.writeRuntimeHistory)(options.contextPath, { status: 'running' });
     return new Promise((resolve) => {
         let result;
+        let graph;
         let stderr = '', summary = '', invalidProtocol = false, timedOut = false;
         let timer;
         const child = (0, node_child_process_1.spawn)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), args, {
@@ -182,6 +242,23 @@ async function runAgentRuntimeInvocation(options) {
                 if (repositories.length)
                     event.repositories = repositories.map(repo => ({ id: repo.id, name: repo.name || repo.id }));
             }
+            if (definitionEngine && ((typeof event.runId === 'string' && event.runId !== admittedContext.runId) || (event.type === 'workflow-event' && event.event?.runId !== admittedContext.runId))) {
+                invalidProtocol = true;
+                if (child.pid)
+                    (0, win_spawn_1.treeKillSafe)(child.pid, 'SIGKILL');
+                return;
+            }
+            try {
+                options.onRuntimeEvent?.(event);
+            }
+            catch (error) {
+                observerError = error instanceof Error ? error.message : String(error);
+                if (child.pid)
+                    (0, win_spawn_1.treeKillSafe)(child.pid, 'SIGKILL');
+                return;
+            }
+            if (event.type === 'runtime-graph')
+                graph = event;
             observe(() => options.onRawLine?.(event.repositories ? JSON.stringify(event) : line));
             if (event.type === 'runtime-result') {
                 if (result)
@@ -236,23 +313,232 @@ async function runAgentRuntimeInvocation(options) {
             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);
+            if (definitionEngine && result?.status === 'succeeded' && (!result.completion || typeof result.completion.ok !== 'boolean' || typeof result.completion.verified !== 'boolean' || (!Array.isArray(result.completion.reasons) || result.completion.reasons.some(reason => typeof reason !== 'string'))))
+                invalidProtocol = true;
+            if (definitionEngine && result?.status === 'paused' && result.runId !== admittedContext.runId)
+                invalidProtocol = true;
+            const acceptanceBlocked = definitionEngine && result?.status === 'succeeded' && result.completion && (!result.completion.ok || requiresVerified && !result.completion.verified);
+            const validPause = definitionEngine && code === 2 && result?.status === 'paused';
+            const failed = (!validPause && (code !== 0 || result?.status !== 'succeeded')) || invalidProtocol || timedOut || Boolean(observerError) || Boolean(acceptanceBlocked);
+            const runtimeError = typeof result?.error === 'string' ? result.error : result?.error?.message;
+            const runtimeStatus = invalidProtocol || timedOut || observerError || (result?.status === 'paused' && !validPause) || (result?.status === 'succeeded' && code !== 0) ? 'failed' : acceptanceBlocked ? 'blocked' : ['succeeded', 'paused', 'failed', 'blocked', 'cancelled'].includes(result?.status ?? '') ? result.status : 'failed';
             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));
+                    : acceptanceBlocked ? result?.completion?.reasons.join('; ') || 'Core workflow acceptance or required verification is not satisfied'
+                        : runtimeError ?? (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));
             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.'),
+                text: summary || (failed ? errorText ?? '' : definitionEngine ? 'Workflow execution completed.' : 'Programmatic implementation verified and archived.'),
                 provider: 'agent-runtime', model: 'per-role', failed, errorText,
+                ...(definitionEngine ? { runtimeStatus, completion: result?.completion, pendingInterrupts: result?.pendingInterrupts, pendingQuestion: result?.pendingQuestion, pendingApproval: result?.pendingApproval, graph } : {}),
                 cost, tokensIn, tokensOut, tokens: tokensIn === undefined || tokensOut === undefined ? undefined : tokensIn + tokensOut,
-                estimated: cost === undefined, durationMs: Date.now() - started,
+                estimated: cost === undefined, durationMs: definitionEngine ? known(result?.usage?.durationMs) : Date.now() - started,
             });
         });
     });
 }
+const CONTROL_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
+const CONTROL_TIMEOUT_MS = 60_000;
+/** Check the retained package before recording a host operation that requires
+ * recoverable publication. Older forks cannot safely retry a lost receipt. */
+async function assertRetainedForkSupport(options) {
+    const cli = (0, agent_runtime_package_1.resolveRetainedAgentRuntime)(options.contextPath);
+    const events = await runControlProcess([cli, 'api'], options);
+    const api = events.find(event => event.type === 'runtime-api');
+    const capabilities = api?.capabilities;
+    if (capabilities?.forkIdempotency !== 1)
+        throw new Error('engine_unsupported: Retained Core does not support recoverable fork publication');
+}
+function controlError(event, fallback) {
+    const error = event?.error;
+    if (typeof error === 'string')
+        return new Error(error);
+    if (error && typeof error === 'object')
+        return new Error([error.code, error.message].filter(Boolean).join(': ') || fallback);
+    return new Error(fallback);
+}
+function runControlProcess(args, options, input) {
+    return new Promise((resolve, reject) => {
+        const events = [];
+        let stderr = '', invalid = false, timedOut = false;
+        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: ['pipe', 'pipe', 'pipe'] });
+        child.stdin.on('error', () => { });
+        child.stdin.end(input);
+        let bytes = 0;
+        child.stdout.on('data', (chunk) => {
+            bytes += chunk.length;
+            if (bytes > 4 * 1024 * 1024) {
+                invalid = true;
+                if (child.pid)
+                    (0, win_spawn_1.treeKillSafe)(child.pid, 'SIGKILL');
+            }
+        });
+        const lines = (0, node_readline_1.createInterface)({ input: child.stdout });
+        lines.on('line', line => {
+            if (invalid || !line.trim())
+                return;
+            try {
+                const event = JSON.parse(line);
+                if (!event || typeof event !== 'object' || Array.isArray(event)) {
+                    invalid = true;
+                    return;
+                }
+                events.push(event);
+            }
+            catch {
+                invalid = true;
+            }
+        });
+        child.stderr?.on('data', (chunk) => {
+            stderr = (stderr + chunk.toString('utf8')).slice(-32_000);
+            try {
+                options.onLine?.(chunk.toString('utf8'), 'stderr');
+            }
+            catch { /* advisory */ }
+        });
+        child.on('error', error => { stderr = error.message; });
+        const timer = setTimeout(() => { timedOut = true; if (child.pid)
+            (0, win_spawn_1.treeKillSafe)(child.pid, 'SIGKILL'); }, options.timeoutMs && options.timeoutMs > 0 ? options.timeoutMs : CONTROL_TIMEOUT_MS);
+        timer.unref?.();
+        child.on('close', code => {
+            clearTimeout(timer);
+            lines.close();
+            const failure = events.find(event => event.type === 'runtime-result' && event.status === 'failed');
+            if (timedOut)
+                return reject(new Error('timeout: Core control command did not finish in time'));
+            if (failure)
+                return reject(controlError(failure, 'Core control command failed'));
+            if (invalid)
+                return reject(new Error('Core returned an invalid control event stream'));
+            if (code !== 0)
+                return reject(new Error(stderr.trim() || `Core control command exited with code ${code}`));
+            resolve(events);
+        });
+    });
+}
+function swapRunId(file, runId) {
+    const parsed = JSON.parse((0, node_fs_1.readFileSync)(file, 'utf8'));
+    return JSON.stringify({ ...parsed, runId }, null, 2) + '\n';
+}
+/** Freeze the child's Desktop-side files from the SOURCE run's frozen files, never from live project settings. */
+function materializeForkedRun(sourceContextPath, childRunId, childContextPath) {
+    const source = (0, node_path_1.dirname)(sourceContextPath), target = (0, node_path_1.dirname)(childContextPath);
+    (0, node_fs_1.mkdirSync)(target, { recursive: true, mode: 0o700 });
+    const write = (name, content) => {
+        const file = (0, node_path_1.join)(target, name);
+        if ((0, node_fs_1.existsSync)(file)) {
+            if ((0, node_fs_1.readFileSync)(file, 'utf8') !== content)
+                throw new Error(`Fork frozen input conflicts: ${name}`);
+        }
+        else
+            (0, node_fs_1.writeFileSync)(file, content, { flag: 'wx', mode: 0o600 });
+        return file;
+    };
+    const copy = (name, required = false) => {
+        const from = (0, node_path_1.join)(source, name);
+        if (!(0, node_fs_1.existsSync)(from)) {
+            if (required)
+                throw new Error(`Source run is missing ${name}`);
+            return undefined;
+        }
+        return write(name, (0, node_fs_1.readFileSync)(from, 'utf8'));
+    };
+    const context = swapRunId(sourceContextPath, childRunId);
+    write('desktop-context.json', context);
+    copy('desktop-runtime-package.json', true);
+    const hostFile = (0, node_path_1.join)(source, 'desktop-runtime-host.json');
+    if ((0, node_fs_1.existsSync)(hostFile)) {
+        const host = JSON.parse((0, node_fs_1.readFileSync)(hostFile, 'utf8'));
+        if (host.env && typeof host.env === 'object' && host.env.SPECRAILS_EXECUTION_CONTEXT !== undefined)
+            host.env = { ...host.env, SPECRAILS_EXECUTION_CONTEXT: childContextPath };
+        write('desktop-runtime-host.json', JSON.stringify(host, null, 2) + '\n');
+    }
+    const configPath = copy('desktop-runtime-config.json') ?? (0, node_path_1.join)(target, 'desktop-runtime-config.json');
+    const definitionPath = copy('desktop-workflow-definition.json') ?? (0, node_path_1.join)(target, 'desktop-workflow-definition.json');
+    if ((0, node_fs_1.existsSync)((0, node_path_1.join)(source, 'desktop-runtime-selection.json')))
+        write('desktop-runtime-selection.json', swapRunId((0, node_path_1.join)(source, 'desktop-runtime-selection.json'), childRunId));
+    return { contextPath: childContextPath, runtimeDirectory: target, definitionPath, configPath, context: JSON.parse(context) };
+}
+async function runAgentRuntimeControl(options) {
+    const cli = (0, agent_runtime_package_1.resolveRetainedAgentRuntime)(options.contextPath);
+    const admitted = JSON.parse((0, node_fs_1.readFileSync)(options.contextPath, 'utf8'));
+    if (typeof admitted.runId !== 'string' || admitted.runId !== options.runId)
+        throw new Error('runtime_scope_changed: Frozen context belongs to another run');
+    const args = [cli, options.kind, '--context', options.contextPath];
+    if (options.kind === 'signal') {
+        if (!/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(options.requestId) || typeof options.text !== 'string' || !options.text.trim() || options.text.length > 20_000)
+            throw new Error('invalid_arguments: Steering requires a safe request id and 1–20,000 characters');
+        args.push('--request-id', options.requestId, '--stdin');
+        const events = await runControlProcess(args, options, options.text);
+        const accepted = events.find(event => event.type === 'runtime-signal-accepted');
+        if (accepted?.id !== options.requestId || typeof accepted.acceptedAt !== 'string' || !Number.isFinite(Date.parse(accepted.acceptedAt)))
+            throw new Error('Core did not acknowledge the steering request');
+        return { kind: 'signal', id: accepted.id, acceptedAt: accepted.acceptedAt };
+    }
+    if (options.kind === 'cancel') {
+        if (typeof options.requestId !== 'string' || !options.requestId.trim() || options.requestId.length > 256 || options.requestId.includes('\0'))
+            throw new Error('invalid_arguments: Cancellation requires a request id of 1–256 characters');
+        args.push('--request-id', options.requestId);
+        const events = await runControlProcess(args, options);
+        const accepted = events.find(event => event.type === 'runtime-cancellation-accepted');
+        if (accepted?.requestId !== options.requestId || typeof accepted.createdAt !== 'string' || !Number.isFinite(Date.parse(accepted.createdAt)))
+            throw new Error('Core did not acknowledge the cancellation request');
+        return { kind: 'cancel', requestId: options.requestId, accepted };
+    }
+    if (!CONTROL_RUN_ID.test(options.childRunId) || options.childRunId === options.runId)
+        throw new Error('invalid_arguments: Fork requires a distinct child run id');
+    if (typeof options.fromNodePath !== 'string' || !options.fromNodePath.trim())
+        throw new Error('invalid_arguments: Fork requires a node path');
+    if (options.visit !== undefined && (!Number.isSafeInteger(options.visit) || options.visit < 1))
+        throw new Error('invalid_arguments: Fork visit must be a positive integer');
+    if (options.scopeId !== undefined && (typeof options.scopeId !== 'string' || !options.scopeId))
+        throw new Error('invalid_arguments: Fork scope must be a non-empty string');
+    const childContextPath = (0, node_path_1.join)((0, node_path_1.dirname)((0, node_path_1.dirname)(options.contextPath)), options.childRunId, 'desktop-context.json');
+    const childRuntimeDirectory = (0, node_path_1.dirname)(childContextPath);
+    if (options.requestId !== undefined && !/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/.test(options.requestId))
+        throw new Error('invalid_arguments: Fork requires a safe request id');
+    if (options.requestId)
+        await assertRetainedForkSupport(options);
+    if ((0, node_fs_1.existsSync)(childRuntimeDirectory) && !options.requestId)
+        throw new Error('run_exists: A run directory already exists for the fork child');
+    args.push('--from', options.fromNodePath, '--run-id', options.childRunId);
+    if (options.requestId)
+        args.push('--request-id', options.requestId);
+    if (options.scopeId !== undefined)
+        args.push('--scope-id', options.scopeId);
+    if (options.visit !== undefined)
+        args.push('--visit', String(options.visit));
+    let staged;
+    if (options.state !== undefined) {
+        if (!options.state || typeof options.state !== 'object' || Array.isArray(options.state))
+            throw new Error('invalid_arguments: Fork state must be an object');
+        staged = (0, node_fs_1.mkdtempSync)((0, node_path_1.join)((0, node_os_1.tmpdir)(), 'specrails-fork-'));
+        const stateFile = (0, node_path_1.join)(staged, 'state.json');
+        (0, node_fs_1.writeFileSync)(stateFile, JSON.stringify(options.state), { mode: 0o600 });
+        args.push('--state', stateFile);
+    }
+    try {
+        const events = await runControlProcess(args, options);
+        const forked = events.find(event => event.type === 'runtime-forked');
+        if (!forked || forked.runId !== options.childRunId || forked.forkOf !== options.runId || typeof forked.directory !== 'string')
+            throw new Error('Core returned an invalid fork result');
+        if (!(0, node_fs_1.existsSync)((0, node_path_1.join)(forked.directory, 'run.sqlite')) || (0, node_fs_1.realpathSync)((0, node_path_1.dirname)(forked.directory)) !== (0, node_fs_1.realpathSync)(childRuntimeDirectory))
+            throw new Error('Core placed the fork outside the expected run directory');
+        const frozen = materializeForkedRun(options.contextPath, options.childRunId, childContextPath);
+        return { kind: 'fork', runId: options.childRunId, forkOf: options.runId, fromNodePath: options.fromNodePath,
+            scopeId: typeof forked.scopeId === 'string' ? forked.scopeId : null, visit: typeof forked.visit === 'number' ? forked.visit : null,
+            revision: typeof forked.revision === 'number' ? forked.revision : null, directory: forked.directory, ...frozen };
+    }
+    finally {
+        // Core owns publication/cleanup. A lost acknowledgement or host-file error
+        // must preserve a published child for the same idempotent request to retry.
+        if (staged)
+            (0, node_fs_1.rmSync)(staged, { recursive: true, force: true });
+    }
+}

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

@@ -6,6 +6,7 @@ exports.cancelRuntimeContinuation = cancelRuntimeContinuation;
 exports.shutdownAgentRuntimeControls = shutdownAgentRuntimeControls;
 exports.runtimeRunSummary = runtimeRunSummary;
 exports.registerAgentRuntimeControlRoutes = registerAgentRuntimeControlRoutes;
+const agent_runtime_retention_records_1 = require("./agent-runtime-retention-records");
 const agent_runtime_paths_1 = require("./agent-runtime-paths");
 const agent_runtime_controls_1 = require("./agent-runtime-controls");
 const controllers = new WeakMap();
@@ -45,6 +46,30 @@ function registerAgentRuntimeControlRoutes({ router, ctx }) {
         }
         return controller;
     }
+    router.get('/:projectId/agent-runtime/retention', (req, res) => {
+        try {
+            res.json({ policy: controls(req).retentionPolicy() });
+        }
+        catch {
+            res.status(503).json({ error: 'runtime_retention_unavailable' });
+        }
+    });
+    router.put('/:projectId/agent-runtime/retention', (req, res) => {
+        try {
+            res.json({ policy: controls(req).configureRetention(req.body) });
+        }
+        catch (error) {
+            res.status(error instanceof agent_runtime_controls_1.RuntimeControlError ? error.statusCode : 503).json({ error: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.code : 'runtime_retention_unavailable' });
+        }
+    });
+    router.post('/:projectId/agent-runtime/retention/collect', async (req, res) => {
+        try {
+            res.json(await controls(req).collectRetention(req.body ?? {}));
+        }
+        catch (error) {
+            res.status(error instanceof agent_runtime_controls_1.RuntimeControlError ? error.statusCode : 503).json({ error: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.code : 'runtime_retention_failed', message: error instanceof Error ? error.message : 'Retention could not inspect runtime storage' });
+        }
+    });
     router.get('/:projectId/agent-runtime/runs', async (req, res) => {
         try {
             if (req.query.railIndex !== undefined) {
@@ -69,7 +94,7 @@ function registerAgentRuntimeControlRoutes({ router, ctx }) {
     router.get('/:projectId/agent-runtime/runs/:runId', async (req, res) => {
         try {
             const context = ctx(req), runId = String(req.params.runId);
-            res.json({ runs: (0, agent_runtime_paths_1.hasAgentRuntimeRequest)(context.project, runId) ? [await controls(req).summary(runId)] : [] });
+            res.json({ runs: (0, agent_runtime_paths_1.hasAgentRuntimeRequest)(context.project, runId) || (0, agent_runtime_retention_records_1.readRuntimeExpiration)(context.db, runId) ? [await controls(req).summary(runId)] : [] });
         }
         catch {
             res.status(500).json({ error: 'runtime_status_failed' });
@@ -100,6 +125,14 @@ function registerAgentRuntimeControlRoutes({ router, ctx }) {
             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/steer', async (req, res) => {
+        try {
+            res.status(202).json(await controls(req).signal(String(req.params.runId), req.body));
+        }
+        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_steering_failed', message: error instanceof agent_runtime_controls_1.RuntimeControlError ? error.message : 'Could not send operator steering' });
+        }
+    });
     router.post('/:projectId/agent-runtime/runs/:runId/recovery', async (req, res) => {
         try {
             res.json(await controls(req).recovery(String(req.params.runId), req.body));