specrails-core 6.0.1 → 6.1.0

package/README.md

@@ -6,7 +6,7 @@
 
 The agent workflow engine behind [Specrails Desktop](https://github.com/fjpulidop/specrails-desktop). Core does two things:
 
-1. **Installs** the specrails workflow into a project for Claude Code, Codex CLI, Gemini CLI or Kimi Code: three roles (architect, developer, reviewer), the `implement` / `batch-implement` / `retry` entry points and the official OpenSpec skills.
+1. **Installs** the specrails workflow into a project for Claude Code, Codex CLI, Gemini CLI or Kimi Code: three roles (architect, developer, reviewer), the `implement` and `retry` entry points (`implement` runs one ticket or several tickets as one aggregate run) and the official OpenSpec skills.
 2. **Runs** implementations through the [programmatic agent runtime](docs/agent-runtime.md): a LangGraph workflow (architect → developer → verify → reviewer → archive) with per-role providers, deterministic verification, durable recovery and OpenAI-compatible local models.
 
 Desktop bundles a pinned Core package and owns everything around it: worktrees, commits, pull requests, backlog and the user interface. Core never ships code on its own; it prepares a reviewed candidate for the host.

package/dist/agent-runtime/capabilities.js

@@ -1,3 +1,4 @@
+import { resolveRoleDescriptor, roleIds } from './config.js';
 import { readFileSync, statSync } from 'node:fs';
 import { homedir, tmpdir } from 'node:os';
 import path from 'node:path';
@@ -71,7 +72,8 @@ export async function configuredCapabilities(config, registry) {
         return probes.get(key);
     };
     const roles = [];
-    for (const [role, selected] of Object.entries(config.agents)) {
+    for (const role of roleIds(config)) {
+        const selected = resolveRoleDescriptor(config, role);
         for (const [tier, choice] of [['base', selected], ...(selected.escalation ? [['escalation', selected.escalation]] : [])]) {
             roles.push({ role, tier, provider: selected.provider, model: choice.model ?? null, requestedEffort: choice.effort ?? null, ...await probe(selected.provider, choice.model) });
         }

package/dist/agent-runtime/cli-executor.d.ts

@@ -21,6 +21,9 @@ interface CliInvocationOptions {
  * developer that cannot run tests iterates blind and fails verification.
  */
 export declare function buildCliInvocation(provider: CliProvider, request: AgentRequest, options?: CliInvocationOptions): CliInvocation;
+/** Native commands are data rendered for the selected provider; never shell text. */
+export declare function renderNativeCommand(provider: Exclude<CliProvider, 'kimi'>, command: NonNullable<AgentRequest['nativeCommand']>): string;
+export declare function kimiNativeSkill(id: string): string;
 interface ParsedCliResult extends AgentResult {
     terminal: boolean;
     failed: boolean;

package/dist/agent-runtime/cli-executor.js

@@ -2,13 +2,13 @@ import { codexOutputSchema, restoreOptionalFields } from './codex-schema.js';
 import { assertEffortSupported, cliCapabilities } from './capabilities.js';
 import { providerDiagnostic } from './provider-diagnostic.js';
 import { toolEvent } from './tool-event.js';
-import { openSpecPrompt, writeOpenSpecBridge } from './openspec.js';
+import { openSpecPrompt, openSpecPolicy, writeOpenSpecBridge } from './openspec.js';
 import { existsSync, readFileSync, mkdtempSync, rmSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import { sumCacheUsage } from './efficiency-types.js';
 import { normalizeKimiCliModel } from './kimi-model.js';
-import { AgentExecutionError, unknownUsage, validateAgentRequest } from './executor-types.js';
+import { AgentExecutionError, unknownUsage, normalizeAgentRequest, requestPolicy, isBuiltinRole } from './executor-types.js';
 import { runCliProcess } from './cli-process.js';
 import { canonicalWorkspace } from './workspace-tools.js';
 import { parseStructuredText } from './openai-executor.js';
@@ -23,22 +23,29 @@ const CLAUDE_DEVELOPER_DISALLOWED = 'Agent,Task,Skill';
  * developer that cannot run tests iterates blind and fails verification.
  */
 export function buildCliInvocation(provider, request, options = {}) {
-    const readOnly = request.role !== 'developer';
+    if (!isBuiltinRole(request.role) || request.access !== undefined || request.nativeCommand)
+        request = normalizeAgentRequest(request);
+    if (request.nativeCommand) {
+        if (provider === 'kimi')
+            throw new AgentExecutionError('Kimi commands require skill rendering before invocation', 'native_command_unsupported');
+        request = { ...request, prompt: renderNativeCommand(provider, request.nativeCommand) };
+    }
+    const readOnly = requestPolicy(request).access === 'read';
     // Pin the product alias; explicit IDs remain reproducible across releases.
     const modelId = provider === 'claude' && request.model === 'opus' ? 'claude-opus-5-5' : request.model;
     const model = modelId ? ['--model', modelId] : [];
     const extraRoots = request.allowedRoots.filter(root => root !== request.cwd);
     const resume = request.resumeSessionId;
     switch (provider) {
-        case 'claude': return { command: 'claude', stdin: request.prompt, args: [
-                '-p', '--output-format', 'stream-json', '--verbose', '--max-turns', String(request.maxTurns ?? 100), ...model,
+        case 'claude': return { command: 'claude', ...(request.nativeCommand ? {} : { stdin: request.prompt }), args: [
+                '-p', ...(request.nativeCommand ? [request.prompt] : []), '--output-format', 'stream-json', '--verbose', '--max-turns', String(request.maxTurns ?? 100), ...model,
                 ...(request.effort === undefined ? [] : ['--effort', request.effort]),
                 // Project instructions and rules stay visible; the user's global config,
                 // memory and plugins never leak into an autonomous role.
                 '--setting-sources', 'project,local',
                 ...(readOnly
-                    ? ['--tools', options.mcpConfigFile ? 'Read,Grep,Glob,ToolSearch' : 'Read,Grep,Glob', '--permission-mode', options.mcpConfigFile ? 'dontAsk' : 'plan', '--strict-mcp-config', ...(options.mcpConfigFile ? ['--allowedTools', 'Read,Grep,Glob,ToolSearch,mcp__specrails_openspec__workflow,mcp__specrails_openspec__read_verification_evidence'] : [])]
-                    : ['--tools', 'default', '--disallowedTools', CLAUDE_DEVELOPER_DISALLOWED, '--dangerously-skip-permissions']),
+                    ? ['--tools', request.nativeCommand ? 'Read,Grep,Glob,Skill' : options.mcpConfigFile ? 'Read,Grep,Glob,ToolSearch' : 'Read,Grep,Glob', '--permission-mode', options.mcpConfigFile ? 'dontAsk' : 'plan', '--strict-mcp-config', ...(options.mcpConfigFile ? ['--allowedTools', 'Read,Grep,Glob,ToolSearch,mcp__specrails_openspec__workflow,mcp__specrails_openspec__read_verification_evidence'] : [])]
+                    : ['--tools', 'default', '--disallowedTools', request.nativeCommand ? 'Agent,Task' : CLAUDE_DEVELOPER_DISALLOWED, '--dangerously-skip-permissions']),
                 ...(options.mcpConfigFile ? ['--mcp-config', options.mcpConfigFile] : []),
                 ...(request.outputSchema ? ['--json-schema', JSON.stringify(request.outputSchema)] : []),
                 ...(request.maxCostUsd === undefined ? [] : ['--max-budget-usd', String(request.maxCostUsd)]),
@@ -63,8 +70,8 @@ export function buildCliInvocation(provider, request, options = {}) {
         case 'gemini': {
             if (readOnly && !options.geminiPolicyFile)
                 throw new AgentExecutionError('Gemini architect/reviewer roles require --admin-policy support for an enforced read-only tool allowlist. Upgrade Gemini CLI or select another provider for this role.', 'provider_capability_unsupported');
-            return { command: 'gemini', stdin: request.prompt, args: [
-                    '-p', 'Execute the task supplied on stdin.', '--output-format', 'stream-json', ...model,
+            return { command: 'gemini', ...(request.nativeCommand ? {} : { stdin: request.prompt }), args: [
+                    '-p', request.nativeCommand ? request.prompt : 'Execute the task supplied on stdin.', '--output-format', 'stream-json', ...model,
                     // Headless Gemini cannot answer shell approvals; the developer runs with
                     // auto-approval exactly as the legacy Implement step did.
                     ...(readOnly ? ['--approval-mode', 'plan'] : ['--yolo']),
@@ -86,6 +93,34 @@ export function buildCliInvocation(provider, request, options = {}) {
         }
     }
 }
+/** Native commands are data rendered for the selected provider; never shell text. */
+export function renderNativeCommand(provider, command) {
+    return (provider === 'codex' ? '$' : '/') + command.id + (command.args ? ' ' + command.args : '');
+}
+export function kimiNativeSkill(id) {
+    const openspec = { 'opsx:ff': 'openspec-ff-change', 'opsx:apply': 'openspec-apply-change', 'opsx:verify': 'openspec-verify-change' };
+    const skill = openspec[id] ?? (id.startsWith('specrails:') ? id.replace('specrails:', 'specrails-') : id);
+    if (!/^[a-z][a-z0-9-]{0,63}$/.test(skill))
+        throw new AgentExecutionError('Kimi native command is unsupported', 'native_command_unsupported');
+    return skill;
+}
+async function renderKimiRequest(request, options) {
+    const skill = kimiNativeSkill(request.nativeCommand.id);
+    const runnerPath = path.join(request.cwd, '.kimi-code', 'specrails', 'run-skill.mjs');
+    if (!existsSync(runnerPath))
+        throw new AgentExecutionError('Kimi managed skill runner is not installed', 'native_command_unsupported');
+    const result = await (options.runProcess ?? runCliProcess)({ command: process.execPath, args: [runnerPath, '--skill', skill, '--model', request.model ?? 'kimi-for-coding', '--args', request.nativeCommand.args ?? '', ...(request.resumeSessionId ? ['--session', request.resumeSessionId] : []), '--render-only'] }, { cwd: request.cwd, signal: request.signal, timeoutMs: 10000, env: options.env });
+    if (result.exitCode !== 0)
+        throw new AgentExecutionError('Kimi native skill cannot be rendered', 'native_command_unsupported');
+    let prompt;
+    try {
+        prompt = JSON.parse(result.stdout).prompt;
+    }
+    catch { /* Invalid runner output cannot become a provider prompt. */ }
+    if (typeof prompt !== 'string' || !prompt.trim() || prompt.includes('\0') || Buffer.byteLength(prompt) > 1_048_576)
+        throw new AgentExecutionError('Invalid Kimi native skill prompt', 'native_command_unsupported');
+    return { ...request, prompt, nativeCommand: undefined };
+}
 function object(value) { return value && typeof value === 'object' && !Array.isArray(value) ? value : {}; }
 function number(value) { return typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null; }
 function textBlocks(value) {
@@ -244,7 +279,7 @@ export class CliExecutor {
     capabilities(model) { return cliCapabilities(this.provider, model, this.options); }
     capabilityChecks = new Map();
     async validateOpenSpec(context) {
-        const key = context.role === 'developer' ? 'write' : 'read';
+        const key = openSpecPolicy(context).access;
         let checked = this.capabilityChecks.get(key);
         if (!checked) {
             checked = (async () => {
@@ -266,11 +301,13 @@ export class CliExecutor {
             throw new AgentExecutionError('Kimi does not report authoritative token usage. Remove the token cap or select another provider for this role.', 'usage_unavailable');
     }
     async execute(request) {
-        validateAgentRequest(request);
+        request = normalizeAgentRequest(request);
         if (request.effort !== undefined)
             assertEffortSupported(request, await this.capabilities(request.model));
         this.validateLimits(request);
         const scope = canonicalWorkspace(request.cwd, request.allowedRoots);
+        if (this.provider === 'kimi' && request.nativeCommand)
+            request = await renderKimiRequest(request, this.options);
         const normalized = { ...request, prompt: (request.openspec ? openSpecPrompt(request.openspec) : '') + request.prompt, cwd: scope.cwd, allowedRoots: scope.roots };
         const runner = this.options.runProcess ?? runCliProcess;
         let temporary, kimiAgentFile, geminiPolicyFile, codexSchemaFile, stream = '', turns = 0, observedSession;
@@ -295,7 +332,7 @@ export class CliExecutor {
                 if (this.provider === 'kimi')
                     return await executeKimiReadonlyAcp(normalized, { ...this.options, openspecBridge });
             }
-            if (this.provider === 'gemini' && request.role !== 'developer') {
+            if (this.provider === 'gemini' && requestPolicy(request).access === 'read') {
                 assertGeminiAdminPolicyAvailable();
                 const help = await runner({ command: 'gemini', args: ['--help'] }, { cwd: scope.cwd, signal: request.signal, timeoutMs: 10_000, env: this.options.env });
                 if (help.exitCode !== 0 || !help.stdout.includes('--admin-policy'))
@@ -303,7 +340,7 @@ export class CliExecutor {
                 geminiPolicyFile = path.join(scratch(), 'readonly.toml');
                 writeFileSync(geminiPolicyFile, (openspecBridge ? '[[rule]]\nmcpName = "specrails_openspec"\ntoolName = "workflow"\ndecision = "allow"\npriority = 1000\n\n[[rule]]\nmcpName = "specrails_openspec"\ntoolName = "read_verification_evidence"\ndecision = "allow"\npriority = 1000\n\n' : '') + GEMINI_READONLY_POLICY, { mode: 0o600 });
             }
-            if (this.provider === 'kimi' && request.role !== 'developer') {
+            if (this.provider === 'kimi' && requestPolicy(request).access === 'read') {
                 const help = await runner({ command: 'kimi', args: ['--help'] }, { cwd: scope.cwd, signal: request.signal, timeoutMs: 10_000, env: this.options.env });
                 if (help.exitCode !== 0)
                     throw new AgentExecutionError('Cannot detect Kimi CLI capabilities', 'provider_capability_unsupported');

package/dist/agent-runtime/cli-process.js

@@ -62,6 +62,10 @@ export function cliProcessEnvironment(base, platform = process.platform) {
 export const runCliProcess = async (raw, options) => {
     if (options.signal?.aborted)
         throw new AgentExecutionError('Agent cancelled', 'aborted');
+    for (const value of [options.timeoutMs, options.idleTimeoutMs]) {
+        if (value !== undefined && (!Number.isSafeInteger(value) || value < 0 || value > 2_147_483_647))
+            throw new AgentExecutionError('Invalid process timeout', 'invalid_limit');
+    }
     const env = cliProcessEnvironment(options.env ?? process.env);
     const invocation = process.platform === 'win32' && raw.command === 'kimi' ? windowsKimiInvocation(raw, { env }) : raw;
     return new Promise((resolve, reject) => {
@@ -93,12 +97,12 @@ export const runCliProcess = async (raw, options) => {
         };
         const fail = (error) => { failure ??= error; terminate(); };
         const abort = () => fail(new AgentExecutionError('Agent cancelled', 'aborted'));
-        const timer = setTimeout(() => fail(new AgentExecutionError(`Agent reached the total execution limit (${options.timeoutMs} ms)`, 'timeout')), options.timeoutMs);
+        const timer = options.timeoutMs > 0 ? setTimeout(() => fail(new AgentExecutionError(`Agent reached the total execution limit (${options.timeoutMs} ms)`, 'timeout')), options.timeoutMs) : undefined;
         let idleTimer;
         const activity = () => {
             if (idleTimer)
                 clearTimeout(idleTimer);
-            if (options.idleTimeoutMs !== undefined && !failure)
+            if (options.idleTimeoutMs !== undefined && options.idleTimeoutMs > 0 && !failure)
                 idleTimer = setTimeout(() => fail(new AgentExecutionError(`Agent produced no output for ${options.idleTimeoutMs} ms (idle timeout)`, 'idle_timeout')), options.idleTimeoutMs);
         };
         activity();

package/dist/agent-runtime/cli.d.ts

@@ -1,4 +1,16 @@
 import type { WorkflowState } from './workflow-types.js';
+/** Both runtime entry points emit the same machine-readable fatal result. */
+export declare function runtimeFailure(error: unknown): {
+    type: string;
+    status: string;
+    error: string | {
+        details?: import("./workflow-types.js").JsonValue | undefined;
+        code: string;
+        message: string;
+    };
+};
+/** Machine operations are mirrored in integration-contract.json; help is presentation-only. */
+export declare const RUNTIME_CLI_OPERATIONS: readonly ["api", "validate", "run", "status", "resume", "prompts", "capabilities", "evidence", "recovery", "evaluate", "workflows", "fork", "signal", "cancel", "help"];
 /** The host-facing summary: phase status, pending interrupts and usage without accumulated outputs. */
 export declare function compactState(state: WorkflowState | null): {
     runId: string;
@@ -44,4 +56,7 @@ export declare function compactState(state: WorkflowState | null): {
     }[];
     metrics: import("./efficiency-types.js").RuntimeEfficiency;
 } | null;
+/** Engines this package can launch: the legacy built-in pipeline (1) and workflow definitions (2).
+ * Core 7 advertises [2] so hosts refuse unconverted legacy loops before admission. */
+export declare const RUNTIME_ENGINES: readonly number[];
 export declare function runRuntimeCommand(flags: Record<string, string | boolean>, positionals: string[], emit?: (value: unknown) => void): Promise<number>;

package/dist/agent-runtime/cli.js

@@ -1,3 +1,5 @@
+import { isDefinitionCommand, NODE_KINDS_VERSION, runDefinitionCommand } from './engine/cli.js';
+import { validationPieceRegistry } from './engine/pieces/index.js';
 import { GUARDRAIL_CATALOG } from './guardrails.js';
 import { runEvaluation } from './evaluation.js';
 import { efficiencySummary } from './efficiency-summary.js';
@@ -15,6 +17,15 @@ import { runtimeEfficiency } from './efficiency.js';
 import { configuredCapabilities } from './capabilities.js';
 import { createExecutorRegistry } from './executors.js';
 import { runRecovery } from './recovery.js';
+import { EngineError } from './engine/contracts.js';
+/** Both runtime entry points emit the same machine-readable fatal result. */
+export function runtimeFailure(error) {
+    return { type: 'runtime-result', status: 'failed', error: error instanceof EngineError
+            ? { code: error.code, message: error.message, ...(error.details === undefined ? {} : { details: error.details }) }
+            : error instanceof Error ? error.message : String(error) };
+}
+/** Machine operations are mirrored in integration-contract.json; help is presentation-only. */
+export const RUNTIME_CLI_OPERATIONS = ['api', 'validate', 'run', 'status', 'resume', 'prompts', 'capabilities', 'evidence', 'recovery', 'evaluate', 'workflows', 'fork', 'signal', 'cancel', 'help'];
 function read(file) { return JSON.parse(readFileSync(file, 'utf8')); }
 async function readStdin() {
     const chunks = [];
@@ -87,8 +98,15 @@ function invocationUsage(state, priorCount) {
         ? null : attempts.reduce((total, a) => total + (a.usage?.[key] ?? 0), 0);
     return { costUsd: sum('costUsd'), inputTokens: sum('inputTokens'), outputTokens: sum('outputTokens') };
 }
+/** Engines this package can launch: the legacy built-in pipeline (1) and workflow definitions (2).
+ * Core 7 advertises [2] so hosts refuse unconverted legacy loops before admission. */
+export const RUNTIME_ENGINES = [1, 2];
 export async function runRuntimeCommand(flags, positionals, emit = value => process.stdout.write(JSON.stringify(value) + '\n')) {
     const command = flags.help === true ? 'help' : positionals[0] ?? 'help';
+    if (isDefinitionCommand(flags, command))
+        return runDefinitionCommand(flags, positionals, emit);
+    if (!RUNTIME_CLI_OPERATIONS.some(operation => operation === command))
+        throw new Error('Unknown runtime operation: ' + command);
     if (command === 'prompts') {
         emit({ type: 'runtime-role-prompts', defaults: rolePromptDefaults() });
         return 0;
@@ -105,28 +123,42 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
     if (command === 'evaluate') {
         if (flags.real !== undefined && flags.real !== true)
             throw new Error('--real is a boolean flag');
-        const report = await runEvaluation({ output: stringFlag(flags, 'output'), real: flags.real === true, ...(flags.config === undefined ? {} : { config: validateRuntimeConfig(read(stringFlag(flags, 'config'))) }), ...(flags['max-cost-usd'] === undefined ? {} : { maxCostUsd: Number(stringFlag(flags, 'max-cost-usd')) }), ...(flags.repetitions === undefined ? {} : { repetitions: Number(stringFlag(flags, 'repetitions')) }) });
-        emit({ type: 'runtime-evaluation', mode: report.mode, observations: report.observations.length, output: stringFlag(flags, 'output'), monetaryConclusion: report.monetaryConclusion, correctionPromptTargetMet: report.correctionPromptTargetMet, noObservedQualityDrop: report.noObservedQualityDrop, stopReason: report.stopReason });
-        return report.stopReason || (!flags.real && (!report.noObservedQualityDrop || !report.noExtraInvocations || !report.correctionPromptTargetMet)) ? 1 : 0;
+        const report = await runEvaluation({ output: stringFlag(flags, 'output'), real: flags.real === true,
+            ...(flags.definition === undefined ? {} : { definition: readFileSync(stringFlag(flags, 'definition')) }),
+            ...(flags.config === undefined ? {} : { config: validateRuntimeConfig(read(stringFlag(flags, 'config'))) }), ...(flags['max-cost-usd'] === undefined ? {} : { maxCostUsd: Number(stringFlag(flags, 'max-cost-usd')) }), ...(flags.repetitions === undefined ? {} : { repetitions: Number(stringFlag(flags, 'repetitions')) }) });
+        emit({ type: 'runtime-evaluation', mode: report.mode, observations: report.observations.length, output: stringFlag(flags, 'output'),
+            isDefinitionEvaluation: report.isDefinitionEvaluation, allCasesAccepted: report.allCasesAccepted, acceptedCases: report.acceptedCases,
+            monetaryConclusion: report.monetaryConclusion, correctionPromptTargetMet: report.correctionPromptTargetMet, noObservedQualityDrop: report.noObservedQualityDrop, noExtraInvocations: report.noExtraInvocations, stopReason: report.stopReason });
+        return report.stopReason || !report.allCasesAccepted || (!flags.real && (!report.noObservedQualityDrop || !report.noExtraInvocations || !report.correctionPromptTargetMet)) ? 1 : 0;
     }
     if (command === 'help') {
         emit({ usage: [
                 'specrails-core runtime api',
-                'specrails-core runtime evaluate --output <directory> [--repetitions <1..20>] [--real --config <json> --max-cost-usd <limit>]',
+                'specrails-core runtime evaluate --output <directory> [--definition <json>] [--repetitions <1..20>] [--real --config <json> --max-cost-usd <limit>]',
                 'specrails-core runtime capabilities --config <json>',
                 'specrails-core runtime evidence --context <json> [--id <opaqueId>] [--section summary|stdout|stderr|source] [--source-id <opaqueId>] [--cursor <cursor>] [--limit <1..100>]',
                 'specrails-core runtime prompts',
                 'specrails-core runtime validate --config <json>',
                 'specrails-core runtime validate --stdin',
                 'specrails-core runtime run --context <json> --config <json> --change <kebab-case>',
+                'specrails-core runtime run --context <json> --config <json> --definition <json> [--change <kebab-case>]',
+                'specrails-core runtime workflows list',
+                'specrails-core runtime workflows validate --stdin [--config <json> | --structural]',
                 'specrails-core runtime status --context <json> [--compact]',
                 'specrails-core runtime resume --context <json> [--approve archive] [--answer <text>] [--recover developer] [--invalidate verify]',
                 'specrails-core runtime recovery --context <json> --stdin',
+                'specrails-core runtime fork --context <json> --from <nodePath> --run-id <newRunId> [--scope-id <scope>] [--visit <number>] [--state <json>]',
+                'specrails-core runtime signal --context <json> --stdin [--request-id <id>]',
+                'specrails-core runtime cancel --context <json> [--request-id <id>]',
             ] });
         return 0;
     }
     if (command === 'api') {
-        emit({ type: 'runtime-api', apiVersion: RUNTIME_API_VERSION, coreVersion: CORE_PACKAGE_VERSION, runtimeIdentity: coreRuntimeIdentity(), workflowVersions: [CORE_WORKFLOW_VERSION], capabilities: { scopedRecovery: 1, efficientRoleExecution: 1, reproducibleVerification: 1, implementationEfficiencyMetrics: 1, compactAgentLoop: 1, configurableGuardrails: 1, compactOutputBudget: 1, roleThinkingControl: 1, repositoryScope: 1 }, guardrails: GUARDRAIL_CATALOG });
+        // Engine v2 fields come from the same validation registry that admits definitions; test-only pieces are never registered there.
+        emit({ type: 'runtime-api', apiVersion: RUNTIME_API_VERSION, coreVersion: CORE_PACKAGE_VERSION, runtimeIdentity: coreRuntimeIdentity(), workflowVersions: [CORE_WORKFLOW_VERSION],
+            engineVersion: 2, engines: RUNTIME_ENGINES, nodeKindsVersion: NODE_KINDS_VERSION, nodeKinds: validationPieceRegistry().kinds(),
+            capabilities: { openRoles: 1, scopedRecovery: 1, efficientRoleExecution: 1, reproducibleVerification: 1, implementationEfficiencyMetrics: 1, compactAgentLoop: 1, configurableGuardrails: 1, compactOutputBudget: 1, roleThinkingControl: 1, repositoryScope: 1,
+                engineV2: 1, workflowDefinitions: 1, fanOut: 1, fork: 1, forkIdempotency: 1, steeringInbox: 1 }, guardrails: GUARDRAIL_CATALOG });
         return 0;
     }
     if (command === 'validate') {
@@ -163,8 +195,6 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
             process.off('SIGTERM', abort);
         }
     }
-    if (!['run', 'status', 'resume'].includes(command))
-        throw new Error('Unknown runtime operation: ' + command);
     const context = validatePipelineContext(read(stringFlag(flags, 'context')));
     const directory = path.join(pipelineStateDirectory(context), 'agent-workflow');
     const previous = await readWorkflowState(directory, context.runId);
@@ -178,6 +208,8 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
     const requestFile = path.join(pipelineStateDirectory(context), 'agent-runtime-request.json');
     let request;
     if (command === 'resume') {
+        if (flags.definition !== undefined)
+            throw new EngineError('invalid_arguments', 'Resume uses the frozen definition; start a new run to change it');
         if (!previous)
             throw new Error('No programmatic run exists for this context');
         request = read(requestFile);
@@ -189,7 +221,9 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
     else {
         if (flags.answer !== undefined || flags.approve !== undefined)
             throw new Error('Answers and approvals apply to runtime resume');
-        request = { change: stringFlag(flags, 'change'), config: normalizeRuntimeConfig(read(stringFlag(flags, 'config'))), runtimeIdentity: coreRuntimeIdentity() };
+        // The built-in workflow has no published definition hash; its resume identity is the checkpoint's workflowFingerprint.
+        request = { change: stringFlag(flags, 'change'), config: normalizeRuntimeConfig(read(stringFlag(flags, 'config'))), runtimeIdentity: coreRuntimeIdentity(),
+            workflow: { id: 'specrails-implementation', version: CORE_WORKFLOW_VERSION, source: 'builtin', definitionHash: null, engine: 1 } };
         await preflightCoreWorkflow({ context, change: request.change, config: request.config });
         const serialized = JSON.stringify(request, null, 2) + '\n';
         mkdirSync(path.dirname(requestFile), { recursive: true, mode: 0o700 });
@@ -237,7 +271,7 @@ if (process.argv[1] && existsSync(process.argv[1]) && import.meta.url === pathTo
         process.exitCode = await runRuntimeCommand(flags, [subcommand ?? 'help', ...positionals]);
     }
     catch (error) {
-        process.stdout.write(JSON.stringify({ type: 'runtime-result', status: 'failed', error: error instanceof Error ? error.message : String(error) }) + '\n');
+        process.stdout.write(JSON.stringify(runtimeFailure(error)) + '\n');
         process.exitCode = 1;
     }
 }

package/dist/agent-runtime/compact/chat-client.js

@@ -1,3 +1,4 @@
+import { setTimeout as delay } from 'node:timers/promises';
 import { AgentExecutionError } from '../executor-types.js';
 import { sumCacheUsage } from '../efficiency-types.js';
 /**
@@ -49,7 +50,7 @@ export function patientFetchInit() {
 }
 const RETRY_DELAY_MS = 3000;
 function sleep(ms, signal) {
-    return new Promise((resolve, reject) => { const timer = setTimeout(resolve, ms); signal.addEventListener('abort', () => { clearTimeout(timer); reject(signal.reason); }, { once: true }); });
+    return delay(ms, undefined, { signal });
 }
 export function record(value) {
     return value !== null && typeof value === 'object' && !Array.isArray(value) ? value : undefined;

package/dist/agent-runtime/config.d.ts

@@ -1,4 +1,4 @@
-import type { RuntimeConfig } from './executor-types.js';
+import { type RoleDescriptor, type RuntimeConfig } from './executor-types.js';
 export declare function validateRuntimeConfig(input: unknown, options?: {
     registeredProviderIds?: string[];
 }): RuntimeConfig;
@@ -9,3 +9,6 @@ export declare function loadRuntimeConfig(file: string, options?: {
 export declare function normalizeRuntimeConfig(input: unknown, options?: {
     registeredProviderIds?: string[];
 }): RuntimeConfig;
+/** Built-ins stay ordered and custom roles are declared data, never inferred from a prompt. */
+export declare function roleIds(config: RuntimeConfig): string[];
+export declare function resolveRoleDescriptor(config: RuntimeConfig, id: string): RoleDescriptor;

package/dist/agent-runtime/config.js

@@ -1,7 +1,9 @@
+import { isDeepStrictEqual } from 'node:util';
 import { validateGuardrailSettings } from './guardrails.js';
 import { readFileSync } from 'node:fs';
+import { BUILTIN_ROLES, BUILTIN_ROLE_POLICY, ROLE_ID, isBuiltinRole } from './executor-types.js';
 import { DEFAULT_REVIEW_POLICY, REVIEW_ASPECTS } from './graph/review-policy.js';
-const ROLES = ['architect', 'developer', 'reviewer'];
+const ROLES = [...BUILTIN_ROLES];
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 function fail(field, why) { throw new Error(`Invalid runtime config ${field}: ${why}`); }
 function object(value, field) {
@@ -60,7 +62,7 @@ function score(value, field, floor) {
 }
 export function validateRuntimeConfig(input, options = {}) {
     const config = object(input, '$');
-    keys(config, ['schemaVersion', 'enabled', 'providers', 'agents', 'fixer', 'limits', 'verification', 'approvalBeforeArchive', 'review', 'architect', 'rolePrompts', 'efficiency', 'guardrails'], '$');
+    keys(config, ['schemaVersion', 'enabled', 'providers', 'agents', 'roles', 'fixer', 'limits', 'verification', 'approvalBeforeArchive', 'review', 'architect', 'rolePrompts', 'efficiency', 'guardrails'], '$');
     if (config.schemaVersion !== 1)
         fail('schemaVersion', 'expected 1');
     if (config.enabled !== undefined && typeof config.enabled !== 'boolean')
@@ -141,6 +143,30 @@ export function validateRuntimeConfig(input, options = {}) {
         return structuredClone(agent);
     };
     const agents = Object.fromEntries(ROLES.map(role => [role, validateAgent(rawAgents[role], `agents.${role}`)]));
+    let roles;
+    if (config.roles !== undefined) {
+        const raw = object(config.roles, 'roles');
+        roles = {};
+        for (const [id, value] of Object.entries(raw)) {
+            if (!ROLE_ID.test(id) || id === 'fixer')
+                fail(`roles.${id}`, 'expected a role id; fixer is reserved');
+            const descriptor = object(value, `roles.${id}`);
+            const { access, artifacts, prompt, openspecSkill, ...assignment } = descriptor;
+            const selected = validateAgent(assignment, `roles.${id}`);
+            choices(access, ['read', 'write'], `roles.${id}.access`);
+            choices(artifacts, ['none', 'tasks-checkboxes', 'all'], `roles.${id}.artifacts`);
+            if (prompt !== undefined && string(prompt, `roles.${id}.prompt`).length > 20000)
+                fail(`roles.${id}.prompt`, 'maximum 20000 characters');
+            if (openspecSkill !== undefined)
+                choices(openspecSkill, ['openspec-ff-change', 'openspec-apply-change', 'openspec-verify-change'], `roles.${id}.openspecSkill`);
+            if (isBuiltinRole(id)) {
+                const policy = BUILTIN_ROLE_POLICY[id];
+                if (access !== policy.access || artifacts !== policy.artifacts || openspecSkill !== policy.openspecSkill || prompt !== undefined || !isDeepStrictEqual(selected, agents[id]))
+                    fail(`roles.${id}`, 'built-in descriptors must match their implicit assignment and policy');
+            }
+            roles[id] = { ...selected, access, artifacts, ...(prompt === undefined ? {} : { prompt }), ...(openspecSkill === undefined ? {} : { openspecSkill }) };
+        }
+    }
     // The optional fixer: the engine correction rounds run on (verify failure or
     // review rejection); absent ⇒ the developer corrects its own work.
     const fixer = config.fixer === undefined ? undefined : validateAgent(config.fixer, 'fixer');
@@ -259,7 +285,7 @@ export function validateRuntimeConfig(input, options = {}) {
     let rolePrompts;
     if (config.rolePrompts !== undefined) {
         const raw = object(config.rolePrompts, 'rolePrompts');
-        keys(raw, [...ROLES, 'fixer'], 'rolePrompts');
+        keys(raw, [...ROLES, 'fixer', ...Object.keys(roles ?? {})], 'rolePrompts');
         rolePrompts = {};
         for (const [role, value] of Object.entries(raw)) {
             const text = string(value, `rolePrompts.${role}`);
@@ -269,6 +295,7 @@ export function validateRuntimeConfig(input, options = {}) {
         }
     }
     return { schemaVersion: 1, enabled: true, providers, agents, verification,
+        ...(roles === undefined ? {} : { roles }),
         ...(config.efficiency === undefined ? {} : { efficiency: structuredClone(config.efficiency) }),
         ...(rolePrompts === undefined ? {} : { rolePrompts }),
         ...(config.limits === undefined ? {} : { limits: { ...config.limits } }),
@@ -284,9 +311,20 @@ export function loadRuntimeConfig(file, options) {
 /** New admissions normalize once; validation of a saved document is lossless. */
 export function normalizeRuntimeConfig(input, options) {
     const config = JSON.parse(JSON.stringify(validateRuntimeConfig(input, options)));
+    config.roles = Object.fromEntries(roleIds(config).map(id => { const { id: _id, ...descriptor } = resolveRoleDescriptor(config, id); return [id, descriptor]; }));
     config.efficiency = {
         schemaVersion: 1, contextMode: 'incremental', reviewMode: 'incremental', planning: 'proportional', acceptDeveloperChecks: true,
         ...config.efficiency, verification: { maxConcurrency: 1, ...config.efficiency?.verification },
     };
     return config;
 }
+/** Built-ins stay ordered and custom roles are declared data, never inferred from a prompt. */
+export function roleIds(config) { return [...new Set([...BUILTIN_ROLES, ...Object.keys(config.roles ?? {})])]; }
+export function resolveRoleDescriptor(config, id) {
+    if (isBuiltinRole(id))
+        return { ...config.agents[id], ...BUILTIN_ROLE_POLICY[id], id };
+    const role = Object.hasOwn(config.roles ?? {}, id) ? config.roles[id] : undefined;
+    if (!role)
+        throw new Error(`Unknown runtime role '${id}'`);
+    return { ...role, ...(config.rolePrompts?.[id] === undefined ? {} : { prompt: config.rolePrompts[id] }), id };
+}

package/dist/agent-runtime/core-host.d.ts

@@ -2,8 +2,9 @@ import { type PipelineContext } from '../pipeline/pipeline-state.js';
 import { type ExecutorRegistry } from './executors.js';
 import type { AgentEvent, RuntimeConfig, AgentEventRole } from './executor-types.js';
 import { parseAgentObject } from './graph/artifacts.js';
+import { type CoreNodeId, type CoreStateType } from './graph/state.js';
 import { type RuntimeIdentity } from './runtime-identity.js';
-import type { WorkflowEvent, WorkflowSpan, WorkflowState } from './workflow-types.js';
+import type { WorkflowDefinition, WorkflowEvent, WorkflowNode, WorkflowSpan, WorkflowState } from './workflow-types.js';
 export declare const RUNTIME_API_VERSION = 1;
 export declare const CORE_WORKFLOW_VERSION = "7";
 export declare const CORE_PACKAGE_VERSION: string;
@@ -32,9 +33,14 @@ export declare function preflightCoreWorkflow(options: Pick<CoreWorkflowOptions,
     config: RuntimeConfig;
     registry: ExecutorRegistry;
 }>;
+/** The legacy graph's resume identity; extracting it must never change its fingerprint. */
+export declare function implementationWorkflowDefinition(nodes: Record<CoreNodeId, WorkflowNode<CoreStateType>>, { attempts, compactDeveloper }: {
+    attempts: number;
+    compactDeveloper: boolean;
+}): WorkflowDefinition<CoreStateType>;
 /**
- * Runs the Core implementation graph: architect → developer → verify → review (→ fixer → verify → review on corrections)er → archive,
- * with bounded corrections routed back to the developer, an autonomous investigation pass
+ * Runs the Core implementation graph: architect → developer → verify → reviewer → archive,
+ * with bounded corrections through fixer → verify → reviewer, an autonomous investigation pass
  * before a low-confidence design asks the requester, real verification receipts, acceptance
  * evidence bound to the exact candidate, and an optional approval before archive.
  */

package/dist/agent-runtime/core-host.js

@@ -3,7 +3,7 @@ import { prepareOpenSpec, roleOpenSpecContext } from './openspec.js';
 import { existsSync, readFileSync } from 'node:fs';
 import path from 'node:path';
 import { fingerprintCandidate, initializePipeline, inspectPipeline, pipelineStateDirectory, validatePipelineContext, validateVerificationRequest, } from '../pipeline/pipeline-state.js';
-import { normalizeRuntimeConfig } from './config.js';
+import { normalizeRuntimeConfig, resolveRoleDescriptor, roleIds } from './config.js';
 import { createExecutorRegistry } from './executors.js';
 import { archive, child, journal, parseAgentObject, SLUG } from './graph/artifacts.js';
 import { coreNodes } from './graph/nodes.js';
@@ -18,7 +18,7 @@ export const RUNTIME_API_VERSION = 1;
 export const CORE_WORKFLOW_VERSION = '7';
 export const CORE_PACKAGE_VERSION = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
 export function coreRuntimeIdentity() {
-    return { packageVersion: CORE_PACKAGE_VERSION, workflowVersion: CORE_WORKFLOW_VERSION, instructionsVersion: String(ROLE_INSTRUCTIONS_VERSION), packageIntegrity: runtimePackageIntegrity(), apiVersion: 1 };
+    return { packageVersion: CORE_PACKAGE_VERSION, workflowVersion: CORE_WORKFLOW_VERSION, instructionsVersion: String(ROLE_INSTRUCTIONS_VERSION), packageIntegrity: runtimePackageIntegrity(), apiVersion: RUNTIME_API_VERSION };
 }
 export { parseAgentObject };
 /** Read-only admission: validate scope, limits and actual effort support before freezing a request. */
@@ -36,7 +36,7 @@ export async function preflightCoreWorkflow(options) {
     if (config.verification.length)
         validateVerificationRequest(context, { kind: 'scoped', commands: config.verification });
     const registry = options.registry ?? createExecutorRegistry(config);
-    for (const selected of Object.values(config.agents)) {
+    for (const selected of roleIds(config).map(id => resolveRoleDescriptor(config, id))) {
         registry.validateLimits(selected.provider, config.limits ?? {});
         for (const tier of [selected, ...(selected.escalation ? [selected.escalation] : [])]) {
             if (tier.effort !== undefined)
@@ -45,9 +45,19 @@ export async function preflightCoreWorkflow(options) {
     }
     return { context, config, registry };
 }
+/** The legacy graph's resume identity; extracting it must never change its fingerprint. */
+export function implementationWorkflowDefinition(nodes, { attempts, compactDeveloper }) {
+    return {
+        id: 'specrails-implementation', version: CORE_WORKFLOW_VERSION, schema: CoreState, entry: 'architect',
+        // The compact developer finishes task groups over developer→verify passes
+        // that do not count as corrections (bounded: +2 passes each).
+        maxTransitions: attempts * 3 + 3 + (compactDeveloper ? attempts * 2 * 2 : 0),
+        nodes: Object.fromEntries(CORE_NODE_ORDER.map(id => [id, nodes[id]])),
+    };
+}
 /**
- * Runs the Core implementation graph: architect → developer → verify → review (→ fixer → verify → review on corrections)er → archive,
- * with bounded corrections routed back to the developer, an autonomous investigation pass
+ * Runs the Core implementation graph: architect → developer → verify → reviewer → archive,
+ * with bounded corrections through fixer → verify → reviewer, an autonomous investigation pass
  * before a low-confidence design asks the requester, real verification receipts, acceptance
  * evidence bound to the exact candidate, and an optional approval before archive.
  */
@@ -68,12 +78,12 @@ export async function runCoreWorkflow(options) {
         }
     }
     const prepared = prepareOpenSpec(context.artifactRoot, options.change, directory);
-    const openspec = Object.fromEntries(['architect', 'developer', 'reviewer'].map(role => {
-        const provider = config.providers.find(item => item.id === config.agents[role].provider);
-        return [role, roleOpenSpecContext(prepared, context.artifactRoot, options.change, directory, role, provider?.kind === 'cli' ? provider.cli : 'claude')];
+    const openspec = Object.fromEntries(roleIds(config).filter(role => resolveRoleDescriptor(config, role).openspecSkill).map(role => {
+        const provider = config.providers.find(item => item.id === resolveRoleDescriptor(config, role).provider);
+        return [role, roleOpenSpecContext(prepared, context.artifactRoot, options.change, directory, resolveRoleDescriptor(config, role), provider?.kind === 'cli' ? provider.cli : 'claude')];
     }));
-    for (const role of ['architect', 'developer', 'reviewer'])
-        await registry.get(config.agents[role].provider).validateOpenSpec?.(openspec[role]);
+    for (const role of Object.keys(openspec))
+        await registry.get(resolveRoleDescriptor(config, role).provider).validateOpenSpec?.(openspec[role]);
     const attempts = config.limits?.maxAttempts ?? 3;
     const developerProvider = config.providers.find(item => item.id === config.agents.developer.provider);
     const compactDeveloper = developerProvider?.kind === 'openai-compatible' && (developerProvider.agentLoop ?? 'compact') === 'compact';
@@ -127,13 +137,6 @@ export async function runCoreWorkflow(options) {
                 return inspection.phases.archive.status === 'done';
             return true;
         },
-        workflow: {
-            id: 'specrails-implementation', version: CORE_WORKFLOW_VERSION, schema: CoreState, entry: 'architect',
-            // The compact (small-model) developer finishes its task groups over
-            // several developer→verify passes that do not count as corrections, so
-            // the transition budget must cover them too (bounded: +2 passes each).
-            maxTransitions: attempts * 3 + 3 + (compactDeveloper ? attempts * 2 * 2 : 0),
-            nodes: Object.fromEntries(CORE_NODE_ORDER.map(id => [id, nodes[id]])),
-        },
+        workflow: implementationWorkflowDefinition(nodes, { attempts, compactDeveloper }),
     });
 }

package/dist/agent-runtime/efficiency-summary.d.ts

@@ -13,6 +13,9 @@ export declare function efficiencySummary(state: WorkflowState, context: Pipelin
             notRunEvidenceIds?: string[];
         };
     };
+}, durableEvidence?: {
+    items: Array<Record<string, unknown>>;
+    available: boolean;
 }): {
     schemaVersion: 1;
     currentEvidenceIds: string[];
@@ -24,7 +27,7 @@ export declare function efficiencySummary(state: WorkflowState, context: Pipelin
     archive: import("../pipeline/pipeline-state.js").PhaseStatus;
     delivery: "pending" | "complete" | "pending-host";
     roles: {
-        role: "architect" | "developer" | "reviewer";
+        role: string;
         provider: string | null;
         model: string | null;
         effort: string | null;