specrails-desktop 2.57.0 → 2.58.0

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

@@ -3,10 +3,15 @@ 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.AgentRuntimeControls = exports.RuntimeControlError = exports.STEERING_TEXT_LIMIT = void 0;
+exports.readRuntimeSteering = readRuntimeSteering;
 exports.pinsRailCard = pinsRailCard;
+exports.stepIdsFor = stepIdsFor;
 exports.validateRuntimeResumeInput = validateRuntimeResumeInput;
 exports.readAgentRuntimeStatus = readAgentRuntimeStatus;
+const agent_runtime_retention_1 = require("./agent-runtime-retention");
+const agent_runtime_retention_host_1 = require("./agent-runtime-retention-host");
+const agent_runtime_retention_records_1 = require("./agent-runtime-retention-records");
 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");
@@ -27,8 +32,32 @@ const db_1 = require("../../../db");
 const loop_run_manager_1 = require("../../loops/runtime/loop-run-manager");
 const agent_runtime_recovery_1 = require("./agent-runtime-recovery");
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
-const STEP_IDS = ['architect', 'developer', 'fixer', 'verify', 'reviewer', 'archive'];
+const LEGACY_STEP_IDS = ['architect', 'developer', 'fixer', 'verify', 'reviewer', 'archive'];
+const NODE_PATH = /^[A-Za-z0-9][A-Za-z0-9_-]{0,119}(\/[A-Za-z0-9][A-Za-z0-9_-]{0,119}){0,3}$/;
+function isNodePath(value) {
+    return NODE_PATH.test(value) && value.split('/').every(id => !['START', 'END', '__start__', '__end__', 'next'].includes(id));
+}
 const ANSWER_LIMIT = 20_000;
+/** Core contract (engine/steering/inbox.ts): 1–20,000 UTF-16 code units per message. Its 80,000-byte cap cannot be reached below that length. */
+exports.STEERING_TEXT_LIMIT = 20_000;
+const STEERING_PREVIEW_LENGTH = 240;
+const STEERING_RECEIPT_LIMIT = 512;
+const STEERING_REQUEST_ID = /^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/;
+/** Core owns receipt durability; Desktop never infers consumption from process state. */
+function readRuntimeSteering(value) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        throw new Error('Core returned invalid steering receipts');
+    const state = value;
+    const timestamp = (value) => typeof value === 'string' && Number.isFinite(Date.parse(value));
+    if (state.consumptionReported !== true || !Number.isSafeInteger(state.pending) || state.pending < 0 || !Number.isSafeInteger(state.consumed) || state.consumed < 0 || typeof state.truncated !== 'boolean' ||
+        !Array.isArray(state.receipts) || state.receipts.length > STEERING_RECEIPT_LIMIT || state.receipts.some(item => !item || typeof item.id !== 'string' || !item.id || item.id.length > 256 || !timestamp(item.acceptedAt) || typeof item.preview !== 'string' || item.preview.length > STEERING_PREVIEW_LENGTH || !Number.isSafeInteger(item.length) || item.length < item.preview.length || item.length > exports.STEERING_TEXT_LIMIT || !['pending', 'consumed'].includes(item.status) ||
+        (item.status === 'consumed' && (typeof item.consumedAttemptId !== 'string' || !item.consumedAttemptId || !timestamp(item.consumedAt))) ||
+        (item.status === 'pending' && (item.consumedAt !== undefined || item.consumedAttemptId !== undefined))))
+        throw new Error('Core returned invalid steering receipts');
+    return { receipts: state.receipts.map(({ id, acceptedAt, preview, length, status, consumedAttemptId, consumedAt }) => ({ id, acceptedAt, preview, length, status, ...(consumedAttemptId ? { consumedAttemptId, consumedAt } : {}) })), pending: state.pending, consumed: state.consumed, truncated: state.truncated, consumptionReported: true };
+}
 /**
  * Whether a continuation still deserves the rail card. Anything that needs a
  * human (blocked, failed, interrupted, a pending question or approval, a
@@ -38,7 +67,7 @@ const ANSWER_LIMIT = 20_000;
  * kept a "Completed" card with only Dismiss on it after every green run.
  */
 function pinsRailCard(summary) {
-    if (summary.dismissed)
+    if (summary.dismissed || summary.status === 'expired')
         return false;
     if (summary.active || summary.canResume || summary.canSettle || summary.canCancel || summary.pendingQuestion || summary.pendingApproval || summary.recoverableSteps.length)
         return true;
@@ -54,18 +83,41 @@ class RuntimeControlError extends Error {
     }
 }
 exports.RuntimeControlError = RuntimeControlError;
-function validateRuntimeResumeInput(input) {
+function stepIdsFor(state) {
+    return state.engineVersion === 2 ? Object.keys(state.steps) : [...LEGACY_STEP_IDS];
+}
+function metricsCatalogFor(state) {
+    return state.engineVersion === 2 ? { stepIds: stepIdsFor(state), roleIds: state.roleIds } : undefined;
+}
+/** Open roles belong to the original run, even after project settings change. */
+function frozenRoleIds(contextPath) {
+    try {
+        const config = JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(node_path_1.default.dirname(contextPath), 'desktop-runtime-config.json'), 'utf8'));
+        const catalogs = [config.agents, config.roles].filter(value => value !== undefined);
+        if (!catalogs.length || catalogs.some(value => !value || typeof value !== 'object' || Array.isArray(value)))
+            return undefined;
+        const ids = [...new Set(catalogs.flatMap(value => Object.keys(value)))];
+        return ids.every(id => /^[a-z][a-z0-9-]{0,63}$/.test(id)) ? ids : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function validateRuntimeResumeInput(input, state) {
     if (!input || typeof input !== 'object' || Array.isArray(input))
         throw new RuntimeControlError(400, 'invalid_resume_request', 'Resume request must be an object');
     const body = input;
+    const stepIds = state ? new Set(stepIdsFor(state)) : undefined;
     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');
+        if (!['approve', 'recover', 'invalidate'].includes(key) || !Array.isArray(value) || value.length > 10_000 || !value.every((id) => typeof id === 'string' && isNodePath(id)) || new Set(value).size !== value.length)
+            throw new RuntimeControlError(400, 'invalid_resume_request', 'Only approve, recover and invalidate arrays of safe node paths are allowed');
+        if (stepIds && value.some(id => !stepIds.has(id)))
+            throw new RuntimeControlError(400, 'invalid_resume_request', 'Resume node paths must belong to the saved workflow');
     }
     return body;
 }
@@ -90,12 +142,46 @@ 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');
+    if (result.engineVersion !== undefined && (!Number.isSafeInteger(result.engineVersion) || result.engineVersion < 1))
+        throw new Error('Core returned an invalid runtime engine version');
+    if (!result.state)
+        return null;
+    const state = { ...result.state, ...(result.engineVersion === undefined ? {} : { engineVersion: result.engineVersion }) };
+    if (state.engineVersion === 2) {
+        if (!state.steps || typeof state.steps !== 'object' || Array.isArray(state.steps) || !Object.entries(state.steps).every(([id, step]) => isNodePath(id) && step && typeof step.status === 'string'))
+            throw new Error('Core returned an invalid runtime step catalog');
+        if (state.nextNodePath !== null && (typeof state.nextNodePath !== 'string' || !Object.hasOwn(state.steps, state.nextNodePath)))
+            throw new Error('Core returned an invalid next node path');
+        if (state.recoverableSteps !== undefined && (!Array.isArray(state.recoverableSteps) || state.recoverableSteps.some(step => !step || typeof step.attemptId !== 'string' || !step.attemptId || typeof step.nodePath !== 'string' || typeof step.scopeId !== 'string')))
+            throw new Error('Core returned invalid recovery attempt identities');
+        if (state.lease !== undefined && state.lease !== null && (typeof state.lease !== 'object' || typeof state.lease.active !== 'boolean'))
+            throw new Error('Core returned an invalid execution lease');
+        if (state.pendingInterrupts !== undefined && (!Array.isArray(state.pendingInterrupts) || state.pendingInterrupts.some(item => !item || typeof item.id !== 'string' || !item.id || typeof item.nodePath !== 'string' || !['question', 'approval', 'gate'].includes(item.kind))))
+            throw new Error('Core returned invalid pending interrupts');
+        // Legacy display fields use node paths. Controls must use an exact pending
+        // interrupt, including when parallel branches pause at the same node.
+        if (state.pendingApproval) {
+            const approval = state.pendingInterrupts?.find(item => item.nodePath === state.pendingApproval.stepId && item.kind !== 'question');
+            state.pendingApproval = approval ? { ...state.pendingApproval, stepId: approval.id } : undefined;
+        }
+        if (state.pendingQuestion) {
+            const question = state.pendingInterrupts?.find(item => item.nodePath === state.pendingQuestion.stepId && item.kind === 'question');
+            state.pendingQuestion = question ? { ...state.pendingQuestion, stepId: question.id } : undefined;
+        }
+        state.nextStep = state.nextNodePath;
+        state.roleIds = frozenRoleIds(contextPath);
+        state.steering = readRuntimeSteering(state.steering);
+        if (result.completion !== undefined && result.completion !== null && (typeof result.completion !== 'object' || typeof result.completion.ok !== 'boolean' || typeof result.completion.verified !== 'boolean' || !Array.isArray(result.completion.reasons) || result.completion.reasons.some(reason => typeof reason !== 'string')))
+            throw new Error('Core returned invalid completion evidence');
+        state.completion = result.completion;
+    }
     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, inspection: result.pipeline, efficiencySummary: (0, agent_runtime_metrics_1.applyRuntimeSelectionOrigins)((0, agent_runtime_metrics_1.readRuntimeEfficiencySummary)(result.efficiencySummary), selection, result.state.runId) } : null;
+    const catalog = metricsCatalogFor(state);
+    return { ...state, inspection: result.pipeline, metrics: (0, agent_runtime_metrics_1.readRuntimeEfficiency)(result.metrics ?? state.metrics, catalog), efficiencySummary: (0, agent_runtime_metrics_1.applyRuntimeSelectionOrigins)((0, agent_runtime_metrics_1.readRuntimeEfficiencySummary)(result.efficiencySummary, catalog), selection, state.runId) };
 }
 /** One controller per ProjectContext; Core's durable lease remains the final
  * cross-process guard. Resume never constructs a new context or worktree. */
@@ -108,13 +194,91 @@ class AgentRuntimeControls {
     errors = new Map();
     statusCache = new Map();
     disposed = false;
+    collectingRetention = false;
     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;
+        // Startup recovery never blocks runtime controls; unrecovered entries stay in
+        // quarantine, where they also block package collection until reviewed.
+        try {
+            const recovered = (0, agent_runtime_retention_host_1.recoverHostRuntimeRetention)({ db: ctx.db, pipelineRoot: node_path_1.default.join((0, workspace_resolution_1.resolveProjectExecution)(ctx.project).specrailsDir, 'pipeline'), active: runId => this.active.has(runId) });
+            for (const error of recovered.errors)
+                console.warn('[agent-runtime] retention recovery kept quarantine:', error);
+        }
+        catch (error) {
+            console.warn('[agent-runtime] retention recovery unavailable:', error instanceof Error ? error.message : error);
+        }
+    }
+    retentionPolicy() { return (0, agent_runtime_retention_records_1.readRuntimeRetentionPolicy)(this.ctx.db); }
+    configureRetention(input) {
+        try {
+            return (0, agent_runtime_retention_records_1.saveRuntimeRetentionPolicy)(this.ctx.db, input);
+        }
+        catch {
+            throw new RuntimeControlError(400, 'invalid_retention_policy', 'Retention days must be null or an integer from 1 to 3650');
+        }
+    }
+    async collectRetention(input) {
+        const body = input;
+        if (!body || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).some(key => key !== 'dryRun') || body.dryRun !== undefined && typeof body.dryRun !== 'boolean')
+            throw new RuntimeControlError(400, 'invalid_retention_request', 'Retention accepts only a boolean dryRun');
+        if (this.disposed || this.collectingRetention)
+            throw new RuntimeControlError(409, 'runtime_retention_busy', 'Runtime retention is already active or shutting down');
+        this.collectingRetention = true;
+        try {
+            const policy = this.retentionPolicy(), now = Date.now();
+            const host = { db: this.ctx.db, projectId: this.ctx.project.id,
+                pipelineRoot: node_path_1.default.join((0, workspace_resolution_1.resolveProjectExecution)(this.ctx.project).specrailsDir, 'pipeline'), active: (runId) => this.active.has(runId),
+                scope: (runId) => {
+                    const context = this.context(runId, true);
+                    return { repositoryMounts: context.frozen.repositories.map(repository => repository.path),
+                        inspect: () => this.dependencies.status(context.file, node_fs_1.default.existsSync(context.cwd) ? context.cwd : context.frozen.backlogRoot, context.env) };
+                },
+            };
+            const recovery = body.dryRun === false ? (0, agent_runtime_retention_host_1.recoverHostRuntimeRetention)(host).errors : [];
+            const report = await (0, agent_runtime_retention_1.collectRuntimeRetention)((0, agent_runtime_retention_host_1.runtimeRetentionHostPorts)(host, policy, now), policy, { dryRun: body.dryRun !== false, now });
+            return recovery.length ? { ...report, errors: [...recovery, ...report.errors] } : report;
+        }
+        finally {
+            this.collectingRetention = false;
+            this.statusCache.clear();
+        }
+    }
+    async signal(runId, input) {
+        if (this.disposed)
+            throw new RuntimeControlError(503, 'runtime_shutting_down', 'Project runtime is shutting down');
+        const body = input;
+        if (!body || typeof body !== 'object' || Array.isArray(body) || Object.keys(body).some(key => !['text', 'requestId'].includes(key)) || typeof body.text !== 'string' || !body.text.trim() || body.text.length > exports.STEERING_TEXT_LIMIT || typeof body.requestId !== 'string' || !STEERING_REQUEST_ID.test(body.requestId))
+            throw new RuntimeControlError(400, 'invalid_steering_request', 'Steering requires text of 1–20,000 characters and a stable requestId');
+        const { file, cwd, env } = this.context(runId);
+        this.assertSteeringOwner(runId);
+        const state = await this.dependencies.status(file, cwd, env);
+        this.assertSteeringOwner(runId);
+        if (!state || state.runId !== runId || state.engineVersion !== 2)
+            throw new RuntimeControlError(409, 'steering_unsupported', 'This retained run does not support engine v2 steering');
+        try {
+            const accepted = await (this.dependencies.control ?? agent_runtime_bridge_1.runAgentRuntimeControl)({ kind: 'signal', contextPath: file, cwd, env, runId, text: body.text, requestId: body.requestId });
+            this.statusCache.delete(runId);
+            return { id: accepted.id, acceptedAt: accepted.acceptedAt };
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : 'Could not send operator steering';
+            const code = /^(control_conflict|run_terminal|inbox_full|invalid_arguments):/.exec(message)?.[1];
+            throw new RuntimeControlError(code === 'invalid_arguments' ? 400 : code ? 409 : 503, code ?? 'runtime_steering_failed', message);
+        }
+    }
+    assertSteeringOwner(runId) {
+        if ((0, loop_runs_store_1.readDefinitionForkTarget)(this.ctx.db, runId)) {
+            throw new RuntimeControlError(409, 'runtime_fork_pending', 'This run has a pending or adopted fork; send steering to the child after adoption');
+        }
     }
     context(runId, historical = false) {
         if (!SAFE_ID.test(runId))
             throw new RuntimeControlError(400, 'invalid_run_id', 'Invalid runtime run ID');
+        if ((0, agent_runtime_retention_records_1.readRuntimeExpiration)(this.ctx.db, runId))
+            throw new RuntimeControlError(410, 'runtime_history_expired', 'Runtime history has expired under the project retention policy');
+        if (!historical && (0, loop_runs_store_1.readDefinitionExecutionClaim)(this.ctx.db, runId)?.owner.startsWith('retention'))
+            throw new RuntimeControlError(409, 'runtime_retention_busy', 'Runtime history is reserved for retention');
         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);
@@ -259,23 +423,30 @@ class AgentRuntimeControls {
     }
     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')))
+        const entries = (node_fs_1.default.existsSync(directory) ? 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;
+        const expired = this.ctx.db.prepare('SELECT run_id FROM runtime_retention_records ORDER BY expired_at DESC LIMIT 20').all();
+        for (const row of expired)
+            if (!runs.some(run => run.runId === row.run_id))
+                runs.push(await this.summary(row.run_id));
+        return runs.sort((a, b) => Number(b.active) - Number(a.active) || (b.updatedAt ?? '').localeCompare(a.updatedAt ?? '')).slice(0, 20);
     }
     async summary(runId) {
+        const expired = (0, agent_runtime_retention_records_1.readRuntimeExpiration)(this.ctx.db, runId);
+        if (expired)
+            return { runId, status: 'expired', expiredAt: expired.expiredAt, updatedAt: expired.expiredAt, nextStep: null, historical: true, active: false, canResume: false, canCancel: false, canSettle: false, recoverableSteps: [] };
         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;
+            // A v2 run can also contain a legacy implementation journal; that file
+            // cannot invalidate the SQLite/WAL status, so leave v2 inspection uncached.
+            const stat = !node_fs_1.default.existsSync(node_path_1.default.join(node_path_1.default.dirname(file), 'agent-workflow', 'run.sqlite')) && node_fs_1.default.existsSync(checkpoint) ? node_fs_1.default.statSync(checkpoint) : 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);
@@ -284,20 +455,26 @@ class AgentRuntimeControls {
             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 definition = state.engineVersion === 2 && parent?.engine_version === 2;
+            const forkSuccessor = definition ? (0, loop_runs_store_1.readDefinitionSuccessor)(this.ctx.db, runId) : undefined;
+            const forkReserved = definition && !!(0, loop_runs_store_1.readDefinitionForkTarget)(this.ctx.db, runId);
+            const active = definition ? state.lease?.active === true : 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: 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',
+            const recoverableSteps = state.engineVersion === 2 ? (state.recoverableSteps ?? []).map(step => step.attemptId) : Object.entries(state.steps).filter(([, step]) => ['running', 'interrupted'].includes(step.status)).map(([id]) => id);
+            const catalog = metricsCatalogFor(state);
+            return { runId, engineVersion: state.engineVersion, 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: forkReserved ? undefined : state.pendingApproval,
+                traceId: state.traceId, pendingQuestion: forkReserved ? undefined : openQuestion(state), steering: state.steering, completion: state.completion, ...(forkSuccessor ? { forkSuccessor } : {}),
+                metrics: (0, agent_runtime_metrics_1.readRuntimeEfficiency)(superseding ? superseding.metrics : state.metrics, catalog), efficiencySummary: (0, agent_runtime_metrics_1.readRuntimeEfficiencySummary)(superseding ? superseding.efficiencySummary : state.efficiencySummary, catalog),
+                canSettle: forkReserved ? false : definition
+                    ? !active && parent.status === 'completed' && state.status === 'succeeded' && !!this.ctx.db.prepare(`SELECT 1 FROM definition_delivery_settlements s JOIN rail_pr_deliveries d ON d.id=s.delivery_id WHERE s.project_id=? AND s.run_id=? AND d.decision IN ('building','pr_failed','implementation_failed') LIMIT 1`).get(this.ctx.project.id, runId)
+                    : !superseding && !active && state.status === 'succeeded' && this.ctx.db.prepare('SELECT status FROM jobs WHERE id = ?').get(runId)?.status !== 'completed',
+                recoverableSteps: forkReserved ? [] : recoverableSteps, ...(state.engineVersion === 2 ? { recoveryAttempts: forkReserved ? [] : state.recoverableSteps ?? [] } : {}), active, canCancel: !forkReserved && (definition ? !state.completion && !['succeeded', 'cancelled'].includes(state.status) : this.active.has(runId)), canResume: !forkReserved && (state.engineVersion === 2 ? definition && !active && parent.status !== 'completed' && state.status !== 'cancelled' : !active && parent?.status === 'completed' && state.status !== 'succeeded'),
                 canDismiss: !active, dismissed: this.isDismissed(runId) };
         }
         catch (error) {
@@ -315,6 +492,8 @@ class AgentRuntimeControls {
         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?.engine_version === 2)
+            throw new RuntimeControlError(409, 'definition_lifecycle_required', 'Resume this workflow through its definition lifecycle');
         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))
@@ -326,10 +505,13 @@ class AgentRuntimeControls {
         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?.engineVersion === 2)
+                throw new RuntimeControlError(409, 'definition_lifecycle_required', 'Resume this workflow through its definition lifecycle');
+            (0, loop_run_manager_1.recoverOrphanLoopStepAccounting)(this.ctx.db, new Date().toISOString(), runId);
             if (!state || state.runId !== runId || state.status === 'succeeded')
                 throw new RuntimeControlError(409, 'runtime_not_resumable', 'This execution has no resumable workflow');
+            validateRuntimeResumeInput(input, state);
             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.

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

@@ -1,8 +1,48 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.workflowRoleDefaults = workflowRoleDefaults;
+exports.bindWorkflowRoleSelections = bindWorkflowRoleSelections;
+exports.bindWorkflowRoleDefaults = bindWorkflowRoleDefaults;
 exports.resolveEffectiveRuntimeConfig = resolveEffectiveRuntimeConfig;
 exports.fillDefaultRoleModels = fillDefaultRoleModels;
 const providers_1 = require("../../../providers");
+/** The loop decision role uses the selected review engine, but has no OpenSpec
+ * workflow obligation. Native implementation's reviewer keeps its own policy. */
+function workflowRoleDefaults(config) {
+    return { 'loop-decider': { ...config.agents.reviewer, access: 'read', artifacts: 'none' } };
+}
+/** Explicit launch-owned roles, used when a converted workflow has a different
+ * decision engine from the project's reviewer. Validate the complete selection
+ * before applying it; project settings and caller descriptors remain untouched. */
+function bindWorkflowRoleSelections(config, definition, selections) {
+    if (!selections || !Object.keys(selections).length)
+        return {};
+    const declared = definition?.roles;
+    const names = Object.keys(selections);
+    if (!Array.isArray(declared) || names.some(id => !declared.includes(id) ||
+        !/^[a-z][a-z0-9-]{0,63}$/.test(id) ||
+        ['architect', 'developer', 'reviewer', 'fixer', 'constructor', 'prototype'].includes(id))) {
+        throw new Error('Workflow role selections must name declared custom roles');
+    }
+    config.roles = { ...config.roles, ...structuredClone(selections) };
+    fillDefaultRoleModels(config);
+    return Object.fromEntries(names.map(id => [id, 'explicit-workflow-selection']));
+}
+/** Bind only roles referenced by the frozen definition; preserve explicit
+ * project assignments and never persist generated defaults into project files. */
+function bindWorkflowRoleDefaults(config, definition) {
+    const roles = definition?.roles;
+    if (!Array.isArray(roles) || !roles.includes('loop-decider'))
+        return {};
+    const existing = config.roles?.['loop-decider'];
+    if (existing) {
+        if (existing.access !== 'read' || existing.artifacts !== 'none' || existing.openspecSkill)
+            throw new Error('loop-decider requires read access, no artifact writes and no OpenSpec skill');
+        return { 'loop-decider': 'project-role' };
+    }
+    config.roles = { ...config.roles, ...workflowRoleDefaults(config) };
+    return { 'loop-decider': 'inherited-reviewer-engine' };
+}
 /** A pure admission resolver; only deliberate launch intent overrides a project role. */
 function resolveEffectiveRuntimeConfig(input, options) {
     const config = structuredClone(input);
@@ -29,6 +69,11 @@ function resolveEffectiveRuntimeConfig(input, options) {
                 config.agents[role] = next;
         }
     }
+    if (override && config.roles)
+        for (const [id, current] of Object.entries(config.roles)) {
+            const changed = current.provider !== override.provider || (override.model !== undefined && override.model !== current.model);
+            config.roles[id] = { ...current, provider: override.provider, model: override.model ?? (current.provider !== override.provider ? undefined : current.model), effort: override.effort ?? (changed ? undefined : current.effort), escalation: changed ? undefined : current.escalation };
+        }
     fillDefaultRoleModels(config);
     config.verification = config.verification.filter(check => options.repositoryIds.includes(check.repositoryId));
     return { config, origins: { architect: override ? 'explicit-launch-override' : options.source, developer: override ? 'explicit-launch-override' : options.source, reviewer: override ? 'explicit-launch-override' : options.source } };
@@ -42,7 +87,7 @@ function resolveEffectiveRuntimeConfig(input, options) {
  * "Role architect requires a model for its API provider".
  */
 function fillDefaultRoleModels(config, options = {}) {
-    for (const agent of [...Object.values(config.agents), ...(config.fixer ? [config.fixer] : [])]) {
+    for (const agent of [...Object.values(config.agents), ...Object.values(config.roles ?? {}), ...(config.fixer ? [config.fixer] : [])]) {
         const provider = config.providers.find(entry => entry.id === agent.provider);
         if (!agent.model && provider?.kind === 'cli' && !options.localOnly)
             agent.model = (0, providers_1.getAdapter)(provider.cli).defaultModel();

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

@@ -0,0 +1,10 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportedEngines = supportedEngines;
+/** Engines the active Core can launch. Cores released before the `engines`
+ * field still run the legacy engine, plus definitions when they advertise engine v2. */
+function supportedEngines(api) {
+    if (api?.engines)
+        return [...api.engines];
+    return api?.capabilities?.engineV2 === 1 ? [1, 2] : [1];
+}

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

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.readWorkflowCatalog = readWorkflowCatalog;
 exports.findCoreAgentRuntimeEntry = findCoreAgentRuntimeEntry;
 exports.resetCoreAgentRuntimeApiCache = resetCoreAgentRuntimeApiCache;
 exports.loadCoreAgentRuntime = loadCoreAgentRuntime;
@@ -15,6 +16,35 @@ 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");
+function readWorkflowCatalog(value) {
+    if (!object(value) || value.type !== 'runtime-workflows' || !object(value.definitionSchema) || !Number.isSafeInteger(value.nodeKindsVersion) || Number(value.nodeKindsVersion) < 1 ||
+        !Array.isArray(value.nodeKinds) || value.nodeKinds.length > 128 || !Array.isArray(value.builtins) ||
+        !value.nodeKinds.every(piece => object(piece) && typeof piece.kind === 'string' && /^[a-z][a-z0-9-]{0,63}$/.test(piece.kind) && object(piece.paramsSchema) &&
+            Array.isArray(piece.outcomes) && piece.outcomes.every(label => typeof label === 'string' && /^[a-z][a-z0-9-]{0,31}$/.test(label)) &&
+            new Set(piece.outcomes).size === piece.outcomes.length && ['read', 'write', 'derived'].includes(String(piece.effect)) && typeof piece.requiresAI === 'boolean') ||
+        new Set(value.nodeKinds.map(piece => piece.kind)).size !== value.nodeKinds.length ||
+        !value.builtins.every(item => object(item) && typeof item.id === 'string' && typeof item.version === 'string' && typeof item.deprecated === 'boolean')) {
+        throw new Error('Core returned malformed workflow catalog');
+    }
+    return value;
+}
+function object(value) {
+    return value !== null && typeof value === 'object' && !Array.isArray(value);
+}
+/** Validation is a protocol result even when Core exits 1 for an invalid definition. */
+function readDefinitionValidation(value) {
+    const invalid = () => { throw new Error('Core returned malformed workflow definition validation'); };
+    if (!object(value) || value.type !== 'runtime-definition-validated')
+        return invalid();
+    if (value.ok === true) {
+        if (typeof value.version !== 'string' || !/^[a-f0-9]{64}$/.test(value.version) || !object(value.definition) || value.definition.version !== value.version || !object(value.graph) || !Array.isArray(value.graph.nodes) || !Array.isArray(value.graph.edges))
+            return invalid();
+        return { ok: true, version: value.version, definition: value.definition, graph: { nodes: value.graph.nodes, edges: value.graph.edges } };
+    }
+    if (value.ok !== false || !Array.isArray(value.errors) || !value.errors.length || !value.errors.every(error => object(error) && typeof error.code === 'string' && error.code.length > 0 && typeof error.message === 'string' && ['nodeId', 'path'].every(key => error[key] === undefined || typeof error[key] === 'string')))
+        return invalid();
+    return { ok: false, errors: value.errors };
+}
 /** An explicit or bundled installation is authoritative: never silently replace
  * a broken production bundle with a developer's checkout. */
 function findCoreAgentRuntimeEntry() {
@@ -73,6 +103,17 @@ async function loadCoreAgentRuntime() {
             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');
+        for (const key of ['engineVersion', 'nodeKindsVersion']) {
+            const value = api[key];
+            if (value !== undefined && (!Number.isSafeInteger(value) || value < (key === 'engineVersion' ? 1 : 0)))
+                throw new Error(`Core returned malformed ${key}`);
+        }
+        if (api.engines !== undefined && (!Array.isArray(api.engines) || !api.engines.length || !api.engines.every(value => Number.isSafeInteger(value) && value >= 1) || new Set(api.engines).size !== api.engines.length))
+            throw new Error('Core returned malformed engines');
+        if (api.nodeKinds !== undefined && (!Array.isArray(api.nodeKinds) || !api.nodeKinds.every(value => typeof value === 'string' && /^[a-z][a-z0-9-]{0,63}$/.test(value)) || new Set(api.nodeKinds).size !== api.nodeKinds.length))
+            throw new Error('Core returned malformed node kinds');
+        if (api.builtins !== undefined && (!Array.isArray(api.builtins) || !api.builtins.every(value => object(value) && typeof value.id === 'string' && /^[a-z0-9][a-z0-9-]{0,63}$/.test(value.id) && typeof value.version === 'string' && value.version.length > 0 && value.version.length <= 128 && typeof value.deprecated === 'boolean') || new Set(api.builtins.map(value => value.id)).size !== api.builtins.length))
+            throw new Error('Core returned malformed builtins');
         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))
@@ -89,6 +130,11 @@ async function loadCoreAgentRuntime() {
             const result = JSON.parse(invoke(['capabilities', '--stdin'], JSON.stringify(input)));
             return { ...validateRoleCapabilities(result, input), runtimeIdentity: api.runtimeIdentity };
         },
+        listWorkflows() {
+            if (api.capabilities?.workflowDefinitions !== 1 || api.capabilities?.engineV2 !== 1)
+                throw new Error('Installed Core does not support workflow definitions. Update the paired Core package.');
+            return readWorkflowCatalog(JSON.parse(invoke(['workflows', 'list'])));
+        },
         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()))
@@ -102,6 +148,25 @@ async function loadCoreAgentRuntime() {
                 throw new Error('Core did not validate the runtime configuration');
             return input;
         },
+        validateWorkflowDefinition(input, options) {
+            if (api.capabilities?.workflowDefinitions !== 1)
+                throw new Error('Installed Core does not support workflow definitions. Update the paired Core package.');
+            const args = ['workflows', 'validate', '--stdin', ...(options?.configPath ? ['--config', options.configPath] : []), ...(options?.structural !== false && !options?.configPath ? ['--structural'] : [])];
+            let output;
+            try {
+                output = invoke(args, JSON.stringify(input));
+            }
+            catch (error) {
+                const failure = error;
+                if (failure.status !== 1 || typeof failure.stdout !== 'string')
+                    throw error;
+                const result = readDefinitionValidation(JSON.parse(failure.stdout));
+                if (result.ok)
+                    throw error;
+                return result;
+            }
+            return readDefinitionValidation(JSON.parse(output));
+        },
     };
 }
 function requireRuntimeCapabilities(api, input) {
@@ -118,8 +183,8 @@ 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)
+    const choices = Object.entries({ ...object(config.agents), ...(config.roles === undefined ? {} : object(config.roles)) });
+    if (result.type !== 'runtime-capabilities' || result.schemaVersion !== 1 || !Array.isArray(result.roles))
         return invalid();
     const expected = choices.flatMap(([role, value]) => {
         const selected = object(value);
@@ -152,7 +217,7 @@ function validateRoleCapabilities(value, input) {
     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))
+    if (![...Object.values(config.agents), ...Object.values(config.roles ?? {})].some(role => role.effort !== undefined || role.escalation?.effort !== undefined))
         return;
     if (!runtime.capabilities)
         throw new Error('Installed Core cannot validate requested role effort');

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

@@ -6,6 +6,7 @@ exports.applyRuntimeSelectionOrigins = applyRuntimeSelectionOrigins;
 const COUNTS = ['attempts', 'measuredAttempts', 'providerCalls', 'toolCalls', 'inputTokens', 'outputTokens', 'uncachedInputTokens', 'cacheReadInputTokens', 'cacheWriteInputTokens'];
 const KEYS = [...COUNTS, 'durationMs', 'agentDurationMs', 'costUsd'];
 const PHASES = ['architect', 'developer', 'fixer', 'verify', 'reviewer', 'archive'];
+const ROLES = ['architect', 'developer', 'reviewer'];
 function object(value) { return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null; }
 function counters(value) {
     const input = object(value);
@@ -27,28 +28,32 @@ function counters(value) {
     return output;
 }
 /** Older Core versions omit metrics; malformed/unknown versions do not break run controls. */
-function readRuntimeEfficiency(value) {
+function readRuntimeEfficiency(value, catalog) {
     const input = object(value);
-    if (input?.schemaVersion !== 1 || !Array.isArray(input.phases) || input.phases.length > PHASES.length)
+    const stepIds = catalog?.stepIds ?? PHASES;
+    if (input?.schemaVersion !== 1 || !Array.isArray(input.phases) || input.phases.length > stepIds.length)
         return undefined;
     const total = counters(input.total);
     if (!total)
         return undefined;
+    const allowedSteps = new Set(stepIds), seenSteps = new Set();
     const phases = [];
     for (const raw of input.phases) {
         const phase = object(raw), count = counters(phase);
-        if (!phase || !count || typeof phase.stepId !== 'string' || !PHASES.includes(phase.stepId) || phases.some(item => item.stepId === phase.stepId))
+        if (!phase || !count || typeof phase.stepId !== 'string' || !allowedSteps.has(phase.stepId) || seenSteps.has(phase.stepId))
             return undefined;
         for (const key of ['providers', 'models'])
             if (!Array.isArray(phase[key]) || phase[key].length > 50 || !phase[key].every((item) => typeof item === 'string' && item.length > 0 && item.length <= 256))
                 return undefined;
         phases.push({ ...count, stepId: phase.stepId, providers: [...phase.providers], models: [...phase.models] });
+        seenSteps.add(phase.stepId);
     }
     return { schemaVersion: 1, total, phases };
 }
-function readRuntimeEfficiencySummary(value) {
+function readRuntimeEfficiencySummary(value, catalog) {
     const input = object(value), invocations = object(input?.invocations), checks = object(input?.checks);
-    if (!input || input.schemaVersion !== 1 || typeof input.runId !== 'string' || input.runId.length > 128 || typeof input.workflowVersion !== 'string' || input.workflowVersion.length > 16 || !['pending', 'validated', 'with-exceptions', 'blocked'].includes(String(input.technicalAcceptance)) || !invocations || !checks || !Array.isArray(input.roles) || input.roles.length > 3)
+    const roleIds = catalog?.roleIds ?? ROLES;
+    if (!input || input.schemaVersion !== 1 || typeof input.runId !== 'string' || input.runId.length > 128 || typeof input.workflowVersion !== 'string' || input.workflowVersion.length > (catalog ? 64 : 16) || !['pending', 'validated', 'with-exceptions', 'blocked'].includes(String(input.technicalAcceptance)) || !invocations || !checks || !Array.isArray(input.roles) || input.roles.length > roleIds.length)
         return undefined;
     if (typeof input.archive !== 'string' || input.archive.length > 32 || typeof input.delivery !== 'string' || input.delivery.length > 32 || typeof invocations.complete !== 'boolean' || typeof checks.available !== 'boolean')
         return undefined;
@@ -77,7 +82,7 @@ function readRuntimeEfficiencySummary(value) {
     const roles = [];
     for (const raw of input.roles) {
         const role = object(raw);
-        if (!role || !['architect', 'developer', 'reviewer'].includes(String(role.role)) || roles.some(item => item.role === role.role))
+        if (!role || !roleIds.includes(String(role.role)) || roles.some(item => item.role === role.role))
             return undefined;
         const row = { role: String(role.role) };
         for (const key of ['provider', 'model', 'effort', 'observedModel', 'observedEffort', 'origin', 'tier']) {
@@ -96,7 +101,7 @@ function readRuntimeEfficiencySummary(value) {
         escalations = [];
         for (const item of input.escalations) {
             const raw = object(item);
-            if (!raw || !['architect', 'developer', 'reviewer'].includes(String(raw.role)))
+            if (!raw || !roleIds.includes(String(raw.role)))
                 return undefined;
             const row = { role: String(raw.role) };
             for (const key of ['attemptId', 'provider', 'model', 'effort', 'reason']) {
@@ -118,5 +123,8 @@ function applyRuntimeSelectionOrigins(summary, selection, runId) {
         return summary;
     if (!['architect', 'developer', 'reviewer'].every(role => ['project-role', 'default', ...(role === 'developer' ? ['explicit-launch-override'] : [])].includes(String(origins[role]))))
         return summary;
-    return { ...summary, roles: summary.roles.map(role => ({ ...role, origin: String(origins[role.role]) })) };
+    return { ...summary, roles: summary.roles.map(role => {
+            const origin = origins[role.role];
+            return { ...role, origin: typeof origin === 'string' ? origin : role.origin };
+        }) };
 }