specrails-core 6.0.0 → 6.1.0

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 }, 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/compact/environment.d.ts

@@ -5,12 +5,24 @@ interface EnvironmentInstall {
     command: string;
     args: string[];
 }
+/** `precondition`: the install failed for a reason only the host can repair (see hostPreconditionFailure). */
 interface InstallOutcome extends EnvironmentInstall {
     ok: boolean;
     detail: string;
+    precondition?: string;
 }
 /** True when a verification failure looks like a missing toolchain/dependency rather than a code defect. */
 export declare function isEnvironmentFailure(exitCode: number | null | undefined, output: string): boolean;
+/**
+ * Failures that no edit to the change can repair, because the verification
+ * process itself lacks something only the host can grant: an environment
+ * variable a configuration file references, registry credentials, registry
+ * network access, git credentials for a dependency. Feeding them to a fixer
+ * makes it edit package-manager configuration to route around the missing
+ * secret (observed: `.yarnrc.yml` rewritten, reverted by review, rewritten
+ * again). Returns a short host-facing reason, or undefined.
+ */
+export declare function hostPreconditionFailure(output: string): string | undefined;
 /** Packages a failure output names explicitly (`Try \`npm i --save-dev @types/jest\``); the host installs exactly those. */
 export declare function suggestedPackages(output: string): string[];
 /** Dependencies package.json declares that node_modules does not hold (bounded). */

package/dist/agent-runtime/compact/environment.js

@@ -19,6 +19,8 @@ const ENVIRONMENT_SIGNATURES = [
     /jest: not found|vitest: not found|mocha: not found|tsc: not found|pytest: not found/i,
     /TS2582|Do you need to install type definitions|Try `npm i --save-dev @types\//i,
     /Module (?:[\w@./-]+) in the \w+ option was not found|Preset [\w@./-]+ not found|Cannot find module '(?:ts-jest|babel-jest|@swc\/jest|ts-node|tsx)'/i,
+    // Yarn Berry refuses to run scripts in a checkout that was never installed.
+    /doesn't seem to have been installed - running an install there might help|Couldn't find the node_modules state file - running an install might help/i,
 ];
 /** True when a verification failure looks like a missing toolchain/dependency rather than a code defect. */
 export function isEnvironmentFailure(exitCode, output) {
@@ -27,6 +29,33 @@ export function isEnvironmentFailure(exitCode, output) {
     const tail = output.slice(-6000);
     return ENVIRONMENT_SIGNATURES.some(pattern => pattern.test(tail));
 }
+const REGISTRY = String.raw `(?:registry|npmjs\.org|yarnpkg\.com|npm\.pkg\.github\.com|pkgs\.dev\.azure\.com|jfrog|artifactory|nexus|pypi\.org|crates\.io|proxy\.golang\.org)`;
+/**
+ * Failures that no edit to the change can repair, because the verification
+ * process itself lacks something only the host can grant: an environment
+ * variable a configuration file references, registry credentials, registry
+ * network access, git credentials for a dependency. Feeding them to a fixer
+ * makes it edit package-manager configuration to route around the missing
+ * secret (observed: `.yarnrc.yml` rewritten, reverted by review, rewritten
+ * again). Returns a short host-facing reason, or undefined.
+ */
+export function hostPreconditionFailure(output) {
+    const text = output.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, '').slice(-16_000);
+    const variable = /Environment variable not found \(([A-Za-z_][A-Za-z0-9_]*)\)/.exec(text);
+    if (variable)
+        return `the environment variable ${variable[1]} is not available to verification commands, and a package-manager configuration file requires it`;
+    if (/\bYN0041\b/.test(text) || /YN0035[\s\S]{0,400}?Response Code: 40[13]\b/.test(text) || /Response code 40[13] \((?:Unauthorized|Forbidden)\)/i.test(text)
+        || /npm (?:ERR!|error) code (?:E401|E403|ENEEDAUTH)\b/.test(text) || /ERR_PNPM_FETCH_40[13]\b/.test(text)
+        || new RegExp(String.raw `\b40[13] (?:Unauthorized|Forbidden)\b[^\n]{0,80}https?://[^\s]*${REGISTRY}`, 'i').test(text)
+        || /\b(?:401|403) Client Error: (?:Unauthorized|Forbidden) for url/.test(text))
+        return 'the package registry rejected the credentials available to verification commands (HTTP 401/403)';
+    if (/npm (?:ERR!|error) code (?:ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ETIMEDOUT|ECONNRESET)\b/.test(text) || /ERR_PNPM_META_FETCH_FAIL\b/.test(text)
+        || new RegExp(String.raw `\b(?:ENOTFOUND|EAI_AGAIN)\b[^\n]{0,200}${REGISTRY}|${REGISTRY}[^\n]{0,200}\b(?:ENOTFOUND|EAI_AGAIN)\b`, 'i').test(text))
+        return 'the package registry cannot be reached from the verification environment';
+    if (/fatal: could not read (?:Username|Password) for/.test(text) || /Permission denied \(publickey\)/.test(text))
+        return 'git credentials needed to fetch a dependency are not available to verification commands';
+    return undefined;
+}
 /** Packages a failure output names explicitly (`Try \`npm i --save-dev @types/jest\``); the host installs exactly those. */
 export function suggestedPackages(output) {
     const packages = new Set();
@@ -155,7 +184,8 @@ export function installEnvironment(roots, io = {}) {
             const ok = result.status === 0;
             const detail = ok ? `installed ${plan.ecosystem} dependencies in ${path.basename(root)}` : `${plan.command} ${plan.args.join(' ')} failed in ${path.basename(root)}: ${String(result.stderr || result.error?.message || `exit ${result.status}`).trim().slice(0, 400)}`;
             io.onEvent?.({ kind: 'text', text: `Environment: ${detail}` });
-            outcomes.push({ ...plan, ok, detail });
+            const precondition = ok ? undefined : hostPreconditionFailure(`${result.stdout ?? ''}\n${result.stderr ?? ''}`);
+            outcomes.push({ ...plan, ok, detail, ...(precondition ? { precondition } : {}) });
         }
     }
     return outcomes;

package/dist/agent-runtime/compact/test-reachability.js

@@ -98,7 +98,11 @@ function tokenReaches(token, file, root, discovery) {
  * file. Unknown ⇒ true: only an enumerating command can prove absence.
  */
 export function commandReachesTest(root, command, file) {
-    const target = posix(file);
+    // Path arguments are relative to the directory the command runs in (a
+    // package inside a larger checkout), while reported files are relative to
+    // the checkout: compare both from the command's directory.
+    const base = path.resolve(root, command.cwd ?? '.');
+    const target = posix(path.relative(base, path.resolve(root, file)));
     let judged = false;
     for (const tokens of segments(expandCommandText(root, command))) {
         if (!tokens.length)
@@ -117,7 +121,7 @@ export function commandReachesTest(root, command, file) {
         if (!paths.some(token => TEST_FILE_PATTERN.test(posix(token)) || token.includes('*') || token.endsWith('...')))
             continue;
         judged = true;
-        if (paths.some(token => tokenReaches(token, target, root, discovery)))
+        if (paths.some(token => tokenReaches(token, target, base, discovery)))
             return true;
     }
     return !judged;

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,10 +2,11 @@ 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 = "6";
+export declare const CORE_WORKFLOW_VERSION = "7";
 export declare const CORE_PACKAGE_VERSION: string;
 export declare function coreRuntimeIdentity(): RuntimeIdentity;
 export { parseAgentObject };
@@ -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';
@@ -15,10 +15,10 @@ import { assertEffortSupported } from './capabilities.js';
 import { runtimePackageIntegrity } from './runtime-identity.js';
 import { readWorkflowState, runWorkflow } from './workflow.js';
 export const RUNTIME_API_VERSION = 1;
-export const CORE_WORKFLOW_VERSION = '6';
+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;

package/dist/agent-runtime/efficiency-summary.js

@@ -1,36 +1,39 @@
+import { resolveRoleDescriptor, roleIds } from './config.js';
+import { BUILTIN_ROLES } from './executor-types.js';
 import { readVerificationEvidence } from '../pipeline/pipeline-state.js';
 import { runtimeEfficiency } from './efficiency.js';
 /** Compact derived view. Durable invocation/evidence IDs remain the accounting authority. */
-export function efficiencySummary(state, context, config, completion, identity) {
+export function efficiencySummary(state, context, config, completion, identity, durableEvidence) {
     const invocations = state.history.flatMap(attempt => [...(attempt.invocations ?? []), ...(attempt.pendingInvocations ?? [])].map(call => ({ ...call, role: attempt.stepId, attemptId: attempt.id })));
     const kinds = ['initial', 'correction', 'repair', 'deepen', 'session-fallback'];
     const byKind = Object.fromEntries(kinds.map(kind => [kind, invocations.filter(call => call.kind === kind).length]));
-    const measured = state.history.every(attempt => !attempt.pendingInvocations?.length) && state.history.every(attempt => !['architect', 'developer', 'reviewer'].includes(attempt.stepId) || attempt.invocations !== undefined) && invocations.every(call => call.kind !== undefined && call.promptBytes !== undefined);
+    const measured = state.history.every(attempt => !attempt.pendingInvocations?.length) && state.history.every(attempt => !(config ? roleIds(config) : [...BUILTIN_ROLES]).includes(attempt.stepId) || attempt.invocations !== undefined) && invocations.every(call => call.kind !== undefined && call.promptBytes !== undefined);
     const bytes = (key) => invocations.every(call => call[key] !== undefined) ? invocations.reduce((sum, call) => sum + call[key], 0) : null;
     const checkIds = new Set();
-    let checks = [], evidenceAvailable = true;
-    try {
-        let cursor;
-        do {
-            const page = readVerificationEvidence(context, { limit: 100, ...(cursor ? { cursor } : {}) });
-            if (!page.available) {
-                evidenceAvailable = false;
-                break;
-            }
-            for (const row of page.items ?? [])
-                if (typeof row.id === 'string' && !checkIds.has(row.id)) {
-                    checkIds.add(row.id);
-                    checks.push(row);
+    let checks = durableEvidence?.items ?? [], evidenceAvailable = durableEvidence?.available ?? true;
+    if (!durableEvidence)
+        try {
+            let cursor;
+            do {
+                const page = readVerificationEvidence(context, { limit: 100, ...(cursor ? { cursor } : {}) });
+                if (!page.available) {
+                    evidenceAvailable = false;
+                    break;
                 }
-            if (checkIds.size > 10000)
-                throw new Error('Evidence summary limit');
-            cursor = 'nextCursor' in page ? page.nextCursor : undefined;
-        } while (cursor);
-    }
-    catch {
-        checks = [];
-        evidenceAvailable = false;
-    }
+                for (const row of page.items ?? [])
+                    if (typeof row.id === 'string' && !checkIds.has(row.id)) {
+                        checkIds.add(row.id);
+                        checks.push(row);
+                    }
+                if (checkIds.size > 10000)
+                    throw new Error('Evidence summary limit');
+                cursor = 'nextCursor' in page ? page.nextCursor : undefined;
+            } while (cursor);
+        }
+        catch {
+            checks = [];
+            evidenceAvailable = false;
+        }
     const checksComplete = evidenceAvailable && checks.every(check => check.status !== 'interrupted' && typeof check.durationMs === 'number');
     const escalatedRoles = new Set();
     const escalations = invocations.filter(call => { if (call.tier !== 'escalation' || escalatedRoles.has(call.role))
@@ -39,13 +42,13 @@ export function efficiencySummary(state, context, config, completion, identity)
         schemaVersion: 1, currentEvidenceIds: [...(identity?.verification?.receipt?.commands.flatMap(command => command.evidenceId ? [command.evidenceId] : []) ?? []), ...(identity?.verification?.receipt?.notRunEvidenceIds ?? [])].slice(0, 100), planHash: identity?.planHash ?? null, candidateHash: identity?.candidateHash ?? null, runId: state.runId, workflowVersion: state.workflowVersion,
         technicalAcceptance: completion?.validation === 'verified' ? 'validated' : completion?.validation === 'with-exceptions' ? 'with-exceptions' : completion?.validation === 'blocked' ? 'blocked' : 'pending',
         archive: completion?.archive ?? 'pending', delivery: completion?.delivery ?? 'pending',
-        roles: ['architect', 'developer', 'reviewer'].map(role => {
-            const selected = config?.agents[role], latest = invocations.filter(call => call.role === role).at(-1);
+        roles: (config ? roleIds(config) : [...BUILTIN_ROLES]).map(role => {
+            const selected = (config ? resolveRoleDescriptor(config, role) : undefined), latest = invocations.filter(call => call.role === role).at(-1);
             return { role, provider: latest?.provider ?? selected?.provider ?? null, model: latest?.model ?? selected?.model ?? null, effort: latest ? latest.requestedEffort ?? null : selected?.effort ?? null, observedModel: null, observedEffort: null, origin: 'frozen-runtime-config', tier: latest?.tier ?? 'base' };
         }),
         invocations: { byKind, total: invocations.length, complete: measured, promptBytes: bytes('promptBytes'), contextBytes: bytes('contextBytes'), handoffBytes: bytes('handoffBytes'), fullContexts: invocations.filter(call => call.contextMode === 'full').length, incrementalContexts: invocations.filter(call => call.contextMode === 'incremental').length },
         escalations: escalations.slice(-16), escalationsTruncated: escalations.length > 16,
         checks: { invalidated: identity && evidenceAvailable ? checks.filter(check => check.planHash !== identity.planHash || check.candidateHash !== identity.candidateHash || check.reuseReason === 'snapshot-inputs-changed-during-verification').length : null, available: evidenceAvailable, complete: checksComplete, executed: checksComplete ? checks.filter(check => check.disposition === 'executed').length : null, reused: evidenceAvailable ? checks.filter(check => check.disposition === 'reused').length : null, notRun: evidenceAvailable ? checks.filter(check => check.disposition === 'not-run').length : null, durationMs: checksComplete ? checks.reduce((sum, check) => sum + (typeof check.durationMs === 'number' ? check.durationMs : 0), 0) : null },
-        metrics: runtimeEfficiency(state),
+        metrics: runtimeEfficiency(state, config ? roleIds(config) : undefined),
     };
 }

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

@@ -18,10 +18,10 @@ export interface ProviderInvocation {
     provider: string;
     /** Requested model; absent means the provider selected its default. */
     model?: string;
-    status: 'succeeded' | 'failed';
-    /** Entire executor wall time, including its native tools and process startup. */
-    durationMs: number;
-    toolCalls: number;
+    status: 'succeeded' | 'failed' | 'interrupted';
+    /** Entire executor wall time; unknown after losing an executor process. */
+    durationMs: number | null;
+    toolCalls: number | null;
     usage: CacheTokenUsage & {
         inputTokens: number | null;
         outputTokens: number | null;

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

@@ -2,4 +2,4 @@ import type { WorkflowState } from './workflow-types.js';
 import { type RuntimeEfficiency } from './efficiency-types.js';
 export * from './efficiency-types.js';
 /** Read-only projection: failed/superseded attempts remain spend, polling never changes it. */
-export declare function runtimeEfficiency(state: WorkflowState): RuntimeEfficiency;
+export declare function runtimeEfficiency(state: WorkflowState, roleIds?: readonly string[]): RuntimeEfficiency;