specrails-core 6.6.5 → 6.7.0

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

@@ -2,8 +2,11 @@ import { type CliProcessRunner } from './cli-process.js';
 import { type CliProvider, type ExecutorCapabilities, type RuntimeAgentConfig, type RuntimeConfig } from './executor-types.js';
 import type { ExecutorRegistry } from './executors.js';
 export declare function unknownCapabilities(transport: string): ExecutorCapabilities;
-/** Introspection never calls an inference endpoint. Only the explicit Codex
- * exec-resume contract is recognized; its possible cold fallback needs full context. */
+/** Introspection never calls an inference endpoint. Two resume contracts are
+ * recognized: Codex `exec resume`, whose possible cold fallback needs full
+ * context, and Claude `-p --resume <id>`, which either continues the stored
+ * conversation of that ID or fails with "No conversation found" (mapped to
+ * `session_not_found`, so the role falls back to a fresh full turn). */
 export declare function cliCapabilities(provider: CliProvider, model: string | undefined, options?: {
     runProcess?: CliProcessRunner;
     env?: NodeJS.ProcessEnv;

package/dist/agent-runtime/capabilities.js

@@ -7,8 +7,11 @@ import { AgentExecutionError } from './executor-types.js';
 export function unknownCapabilities(transport) {
     return { transport, continuation: 'unknown', effortSupport: 'unknown', supportedEfforts: null, observedModel: false, observedEffort: false };
 }
-/** Introspection never calls an inference endpoint. Only the explicit Codex
- * exec-resume contract is recognized; its possible cold fallback needs full context. */
+/** Introspection never calls an inference endpoint. Two resume contracts are
+ * recognized: Codex `exec resume`, whose possible cold fallback needs full
+ * context, and Claude `-p --resume <id>`, which either continues the stored
+ * conversation of that ID or fails with "No conversation found" (mapped to
+ * `session_not_found`, so the role falls back to a fresh full turn). */
 export async function cliCapabilities(provider, model, options = {}) {
     const result = unknownCapabilities(provider === 'kimi' ? 'kimi-acp' : `${provider}-cli`);
     if (provider === 'kimi')
@@ -30,6 +33,9 @@ export async function cliCapabilities(provider, model, options = {}) {
             }
         }
         if (provider === 'claude') {
+            // Claude Code 2.1.309 (recorded): an unknown ID fails before inference with "No conversation found"; it never starts cold.
+            if (/^\s*(?:-r, )?--resume\b/m.test(help.stdout))
+                result.continuation = 'supported';
             const section = /--effort\s+<[^>]+>([\s\S]*?)(?=\n\s+--|$)/.exec(help.stdout)?.[1];
             const levels = section?.match(/\(([^)]+)\)/)?.[1].split(',').map(value => value.trim());
             if (levels?.length && levels.every(value => /^[a-z][a-z0-9_-]{0,31}$/.test(value)))

package/dist/agent-runtime/change-scope.d.ts

@@ -27,6 +27,8 @@ export declare function assertProposalInScope(context: PipelineContext, command:
 }, what?: string): void;
 /** Base commit per repository id; the first call records it. */
 export declare function changeBases(context: PipelineContext): Record<string, string>;
+/** The commit HEAD names in a repository checkout, or null when it has none. */
+export declare function repositoryHead(root: string): string | null;
 /** Every path that differs from the base: tracked edits (staged or not), deletions and new untracked files. */
 export declare function repositoryChanges(context: PipelineContext, repository: PipelineRepository, base: string, change?: string): ChangedFile[];
 /** What this run changed, per repository and bounded: untracked files that predate the run are not part of it. */

package/dist/agent-runtime/change-scope.js

@@ -119,6 +119,11 @@ function baseRecords(context) {
 export function changeBases(context) {
     return Object.fromEntries(Object.entries(baseRecords(context)).map(([id, record]) => [id, record.base]));
 }
+/** The commit HEAD names in a repository checkout, or null when it has none. */
+export function repositoryHead(root) {
+    const head = git(root, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], true);
+    return head.ok && /^[a-f0-9]{40,64}$/.test(head.stdout.trim()) ? head.stdout.trim() : null;
+}
 /** Host and runtime state, the change's own OpenSpec artifacts and generated trees are never part of the code change. */
 function ignored(context, repository, change, file, fresh) {
     if (file === '.specrails' || file.startsWith('.specrails/'))

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

@@ -14,6 +14,8 @@ import { canonicalWorkspace } from './workspace-tools.js';
 import { parseStructuredText } from './openai-executor.js';
 import { executeKimiReadonlyAcp } from './kimi-acp.js';
 import { assertGeminiAdminPolicyAvailable, GEMINI_READONLY_POLICY } from './gemini-policy.js';
+/** Claude's print-mode answer to `--resume <id>` when no transcript exists for that ID in this project. */
+const CLAUDE_SESSION_MISSING = /No conversation found with session ID/i;
 /** Tools a Claude developer may not use: nested agents and platform skills would start a second, unobserved workflow. */
 const CLAUDE_DEVELOPER_DISALLOWED = 'Agent,Task,Skill';
 /**
@@ -419,6 +421,11 @@ export class CliExecutor {
                 throw new AgentExecutionError(message, parsed.failureKind, parsed.usage);
             }
             if (result.exitCode !== 0 || parsed.failed) {
+                // A resumed Claude session whose transcript is gone fails before any
+                // inference; the role layer then starts a fresh full turn.
+                if (this.provider === 'claude' && request.resumeSessionId && CLAUDE_SESSION_MISSING.test(result.stdout + '\n' + result.stderr)) {
+                    throw new AgentExecutionError('claude has no stored conversation for the resumed session', 'session_not_found', parsed.usage);
+                }
                 const diagnostic = providerDiagnostic(result.stdout, result.stderr, { ...process.env, ...this.options.env });
                 throw new AgentExecutionError(`${this.provider} execution failed${result.exitCode !== 0 ? ` (exit ${result.exitCode})` : ''}.${diagnostic ? ' ' + diagnostic : ' The provider did not report a diagnostic.'}`, 'provider_execution_error', parsed.usage);
             }

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

@@ -1,3 +1,4 @@
+import { type FailureClassification } from './failure-classification.js';
 import type { WorkflowState } from './workflow-types.js';
 /** Both runtime entry points emit the same machine-readable fatal result. */
 export declare function runtimeFailure(error: unknown): {
@@ -10,7 +11,11 @@ export declare function runtimeFailure(error: unknown): {
     };
 };
 /** 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', 'host', 'help'];
+export declare const RUNTIME_CLI_OPERATIONS: readonly ['api', 'validate', 'run', 'status', 'resume', 'prompts', 'capabilities', 'evidence', 'recovery', 'evaluate', 'workflows', 'fork', 'signal', 'cancel', 'pause', 'host', 'help'];
+/** `failure` (contract 5.8): the structured classification of a failed or blocked engine 1 run; absent otherwise. */
+export declare function failureField(state: WorkflowState | null): {
+    failure?: FailureClassification;
+};
 /** The host-facing summary: phase status, pending interrupts and usage without accumulated outputs. */
 export declare function compactState(state: WorkflowState | null): {
     runId: string;

package/dist/agent-runtime/cli.js

@@ -1,3 +1,4 @@
+import { classifyFailure } from './failure-classification.js';
 import { isDefinitionCommand, NODE_KINDS_VERSION, runDefinitionCommand } from './engine/cli.js';
 import { validationPieceRegistry } from './engine/pieces/index.js';
 import { GUARDRAIL_CATALOG } from './guardrails.js';
@@ -14,6 +15,10 @@ import { CORE_PACKAGE_VERSION, CORE_WORKFLOW_VERSION, RUNTIME_API_VERSION, coreR
 import { sameRuntimeIdentity } from './runtime-identity.js';
 import { readWorkflowState } from './workflow.js';
 import { runtimeEfficiency } from './efficiency.js';
+import { readReviewBriefRecord } from './graph/review-brief-record.js';
+import { readClarificationsRecord } from './graph/clarifications.js';
+import { readSpecTraceReport } from './graph/spec-trace-record.js';
+import { readBaselineRecord } from './graph/baseline.js';
 import { configuredCapabilities } from './capabilities.js';
 import { createExecutorRegistry } from './executors.js';
 import { runRecovery } from './recovery.js';
@@ -69,7 +74,7 @@ export function runtimeFailure(error) {
                 : 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', 'host', 'help'];
+export const RUNTIME_CLI_OPERATIONS = ['api', 'validate', 'run', 'status', 'resume', 'prompts', 'capabilities', 'evidence', 'recovery', 'evaluate', 'workflows', 'fork', 'signal', 'cancel', 'pause', 'host', 'help'];
 function read(file) { return JSON.parse(readFileSync(file, 'utf8')); }
 async function readStdin() {
     const chunks = [];
@@ -83,6 +88,11 @@ async function readStdin() {
     }
     return JSON.parse(Buffer.concat(chunks).toString('utf8'));
 }
+/** `failure` (contract 5.8): the structured classification of a failed or blocked engine 1 run; absent otherwise. */
+export function failureField(state) {
+    const failure = state ? classifyFailure({ status: state.status, error: state.error, steps: state.steps, nextStep: state.nextStep }) : undefined;
+    return failure ? { failure } : {};
+}
 /** The host-facing summary: phase status, pending interrupts and usage without accumulated outputs. */
 export function compactState(state) {
     if (!state)
@@ -194,6 +204,7 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
                 '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>]',
+                'specrails-core runtime pause --context <json> [--request-id <id>] [--reason requested|budget|<token>]',
                 'specrails-core runtime host --stdio [--scope <projectKey|global>]',
             ] });
         return 0;
@@ -203,7 +214,7 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
         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, workflowAgentSteps: 1, implementationSteps: 1, workflowDefinitions: 1, fanOut: 1, fork: 1, forkIdempotency: 1, steeringInbox: 1, hostBlockers: 1, setupCommands: 1, sessions: 1 }, guardrails: GUARDRAIL_CATALOG });
+                engineV2: 1, workflowAgentSteps: 1, implementationSteps: 1, workflowDefinitions: 1, fanOut: 1, fork: 1, forkIdempotency: 1, steeringInbox: 1, hostBlockers: 1, setupCommands: 1, sessions: 1, flowSessions: 1, reviewBrief: 1, deriveChange: 1, architectClarifications: 1, specTrace: 1, baselineOnTouch: 1, rulesInventory: 1, pauseRuns: 1, failureClassification: 1, findingLocations: 1 }, guardrails: GUARDRAIL_CATALOG });
         return 0;
     }
     if (command === 'host')
@@ -249,7 +260,7 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
         const pipeline = previous ? inspectPipeline(context) : null;
         const requestPath = path.join(pipelineStateDirectory(context), 'agent-runtime-request.json');
         const config = existsSync(requestPath) ? read(requestPath).config : undefined;
-        emit({ type: 'runtime-status', state: flags.compact ? compactState(previous) : previous, pipeline: flags.compact ? compactPipeline(pipeline) : pipeline, ...(previous ? { metrics: runtimeEfficiency(previous), efficiencySummary: efficiencySummary(previous, context, config, pipeline?.completion, pipeline ?? undefined) } : {}) });
+        emit({ type: 'runtime-status', ...failureField(previous), state: flags.compact ? compactState(previous) : previous, pipeline: flags.compact ? compactPipeline(pipeline) : pipeline, ...(previous ? { metrics: runtimeEfficiency(previous), efficiencySummary: efficiencySummary(previous, context, config, pipeline?.completion, pipeline ?? undefined) } : {}) });
         return 0;
     }
     const requestFile = path.join(pipelineStateDirectory(context), 'agent-runtime-request.json');
@@ -304,7 +315,7 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
             inspection = inspectPipeline(context);
         }
         catch { /* A failed scope inspection must not erase recorded spend. */ }
-        emit({ type: 'runtime-result', runId: state.runId, traceId: state.traceId, status: state.status, nextStep: state.nextStep, error: state.error, pendingApproval: state.pendingApproval, pendingQuestion: state.pendingQuestion, usage: state.usage, invocationUsage: invocationUsage(state, previous?.history.length ?? 0), metrics: runtimeEfficiency(state), efficiencySummary: efficiencySummary(state, context, request.config, inspection?.completion, inspection) });
+        emit({ type: 'runtime-result', runId: state.runId, traceId: state.traceId, status: state.status, nextStep: state.nextStep, error: state.error, pendingApproval: state.pendingApproval, pendingQuestion: state.pendingQuestion, usage: state.usage, invocationUsage: invocationUsage(state, previous?.history.length ?? 0), metrics: runtimeEfficiency(state), efficiencySummary: efficiencySummary(state, context, request.config, inspection?.completion, inspection), reviewBrief: readReviewBriefRecord(context), clarifications: readClarificationsRecord(context), specTrace: readSpecTraceReport(context), baseline: readBaselineRecord(context), ...failureField(state) });
         return state.status === 'succeeded' ? 0 : state.status === 'paused' ? 2 : 1;
     }
     finally {

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

@@ -171,7 +171,9 @@ export async function runCompactReviewer(env, options = {}) {
         approved: (raw.approved === true || resolved) && !uncertified && issues.length === 0,
         summary: text(raw.summary).slice(0, 8000), issues, score: lift(raw.score, gate?.minScore),
         aspects: Object.fromEntries(REVIEW_ASPECTS.map(name => [name, lift(aspectsRaw[name], gate?.aspects[name])])),
-        acceptance: { criteria: certified, checks: [], findings: strings(acceptanceRaw.findings, 50, 1000) },
+        acceptance: { criteria: certified, checks: [], findings: strings(acceptanceRaw.findings, 50, 1000), ...(Array.isArray(acceptanceRaw.findingLocations) ? { findingLocations: acceptanceRaw.findingLocations } : {}) },
+        // The optional risk brief passes through untouched; the reviewer node validates it.
+        ...(raw.brief !== undefined && raw.brief !== null ? { brief: raw.brief } : {}),
     };
     return { text: JSON.stringify(structured), usage: env.client.usage, structured };
 }

package/dist/agent-runtime/config.js

@@ -1,7 +1,7 @@
 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 { BUILTIN_ROLES, BUILTIN_ROLE_POLICY, ENGINE_ROLE_POLICY, ROLE_ID, isBuiltinRole, isEngineRole } from './executor-types.js';
 import { DEFAULT_REVIEW_POLICY, REVIEW_ASPECTS } from './graph/review-policy.js';
 const ROLES = [...BUILTIN_ROLES];
 const ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
@@ -119,7 +119,7 @@ function uniqueKeys(commands, list) {
 }
 export function validateRuntimeConfig(input, options = {}) {
     const config = object(input, '$');
-    keys(config, ['schemaVersion', 'enabled', 'providers', 'agents', 'roles', 'fixer', 'limits', 'verification', 'setup', 'approvalBeforeArchive', 'review', 'architect', 'rolePrompts', 'efficiency', 'guardrails'], '$');
+    keys(config, ['schemaVersion', 'enabled', 'providers', 'agents', 'roles', 'fixer', 'limits', 'verification', 'setup', 'approvalBeforeArchive', 'baselineOnTouch', 'review', 'architect', 'rolePrompts', 'efficiency', 'guardrails'], '$');
     if (config.schemaVersion !== 1)
         fail('schemaVersion', 'expected 1');
     if (config.enabled !== undefined && typeof config.enabled !== 'boolean')
@@ -205,8 +205,8 @@ export function validateRuntimeConfig(input, options = {}) {
         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');
+            if (!ROLE_ID.test(id) || id === 'fixer' || isEngineRole(id))
+                fail(`roles.${id}`, 'expected a role id; fixer and Core engine roles (deriver) are reserved');
             const descriptor = object(value, `roles.${id}`);
             const { access, artifacts, prompt, openspecSkill, ...assignment } = descriptor;
             const selected = validateAgent(assignment, `roles.${id}`);
@@ -272,6 +272,8 @@ export function validateRuntimeConfig(input, options = {}) {
     }
     if (config.approvalBeforeArchive !== undefined && typeof config.approvalBeforeArchive !== 'boolean')
         fail('approvalBeforeArchive', 'expected boolean');
+    if (config.baselineOnTouch !== undefined && typeof config.baselineOnTouch !== 'boolean')
+        fail('baselineOnTouch', 'expected boolean');
     let review;
     if (config.review !== undefined) {
         const raw = object(config.review, 'review');
@@ -288,13 +290,18 @@ export function validateRuntimeConfig(input, options = {}) {
     let architect;
     if (config.architect !== undefined) {
         const raw = object(config.architect, 'architect');
-        keys(raw, ['onLowConfidence'], 'architect');
+        keys(raw, ['onLowConfidence', 'clarifications'], 'architect');
         architect = {};
         if (raw.onLowConfidence !== undefined) {
             if (raw.onLowConfidence !== 'ask' && raw.onLowConfidence !== 'proceed')
                 fail('architect.onLowConfidence', 'expected "ask" or "proceed"');
             architect.onLowConfidence = raw.onLowConfidence;
         }
+        if (raw.clarifications !== undefined) {
+            if (raw.clarifications !== 'ask-on-high' && raw.clarifications !== 'always-proceed')
+                fail('architect.clarifications', 'expected "ask-on-high" or "always-proceed"');
+            architect.clarifications = raw.clarifications;
+        }
     }
     let rolePrompts;
     if (config.rolePrompts !== undefined) {
@@ -315,6 +322,7 @@ export function validateRuntimeConfig(input, options = {}) {
         ...(rolePrompts === undefined ? {} : { rolePrompts }),
         ...(config.limits === undefined ? {} : { limits: { ...config.limits } }),
         ...(config.approvalBeforeArchive === undefined ? {} : { approvalBeforeArchive: config.approvalBeforeArchive }),
+        ...(config.baselineOnTouch === undefined ? {} : { baselineOnTouch: config.baselineOnTouch }),
         ...(review === undefined ? {} : { review }),
         ...(architect === undefined ? {} : { architect }),
         ...(guardrails === undefined ? {} : { guardrails }),
@@ -338,6 +346,9 @@ export function roleIds(config) { return [...new Set([...BUILTIN_ROLES, ...Objec
 export function resolveRoleDescriptor(config, id) {
     if (isBuiltinRole(id))
         return { ...config.agents[id], ...BUILTIN_ROLE_POLICY[id], id };
+    // Engine roles reuse the architect's assignment; their instructions are Core's (prompts.ts), never configuration.
+    if (isEngineRole(id))
+        return { ...config.agents.architect, ...ENGINE_ROLE_POLICY[id], id };
     const role = Object.hasOwn(config.roles ?? {}, id) ? config.roles[id] : undefined;
     if (!role)
         throw new Error(`Unknown runtime role '${id}'`);

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

@@ -48,6 +48,13 @@ export declare function efficiencySummary(state: WorkflowState, context: Pipelin
         fullContexts: number;
         incrementalContexts: number;
     };
+    baseline: {
+        invocations: number;
+        roles: string[];
+        costUsd: number | null;
+        inputTokens: number | null;
+        outputTokens: number | null;
+    };
     escalations: {
         role: string;
         attemptId: string;

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

@@ -5,7 +5,7 @@ import { runtimeEfficiency } from './efficiency.js';
 /** Compact derived view. Durable invocation/evidence IDs remain the accounting authority. */
 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 kinds = ['initial', 'correction', 'repair', 'deepen', 'session-fallback', 'baseline'];
     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 => !(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;
@@ -47,8 +47,14 @@ export function efficiencySummary(state, context, config, completion, identity,
             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 },
+        baseline: baselineSpend(invocations.filter(call => call.kind === 'baseline')),
         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, config ? roleIds(config) : undefined),
     };
 }
+/** Spend of the baseline-on-touch turns, kept apart from the change's own cost; unknown values stay unknown. */
+function baselineSpend(calls) {
+    const sum = (key) => calls.some(call => call.usage?.[key] == null) ? null : calls.reduce((total, call) => total + call.usage[key], 0);
+    return { invocations: calls.length, roles: [...new Set(calls.map(call => call.role))], costUsd: sum('costUsd'), inputTokens: sum('inputTokens'), outputTokens: sum('outputTokens') };
+}

package/dist/agent-runtime/engine/__fixtures__/implementation-fixture.js

@@ -34,7 +34,7 @@ export function implementationFixture(approval = false) {
                 await tools.execute({ action: 'new' });
                 const files = [
                     ['proposal', 'proposal.md', '# Why\nReturn two.\n# What Changes\nUpdate the function.\n# Capabilities\n## New Capabilities\n- feature: Return the required value.\n# Impact\nOne function.'],
-                    ['design', 'design.md', '# Design\nUpdate code.cjs and verify the return value.'],
+                    ['design', 'design.md', '# Design\nUpdate code.cjs and verify the return value.\n## Non-Goals\n- Nothing outside code.cjs.\n'],
                     ['specs', `specs/${capability}/spec.md`, '## ADDED Requirements\n### Requirement: Return the required value\nThe function SHALL return 2.\n#### Scenario: Calling the function\n- **WHEN** code.cjs is loaded\n- **THEN** it returns 2\n'],
                     ['tasks', 'tasks.md', '- [ ] 1. Implement the return value and verify behavior\n'],
                 ];

package/dist/agent-runtime/engine/checkpoint/database.d.ts

@@ -22,6 +22,8 @@ declare const keys: {
     readonly writes: readonly ['thread_id', 'checkpoint_ns', 'checkpoint_id', 'task_id', 'idx'];
 };
 export type RevisionTable = keyof typeof keys;
+/** Current run database schema. Version 1 lacks the 'pause' control kind and stays readable. */
+export declare const RUN_DATABASE_SCHEMA = 2;
 /** Short synchronous transactions own graph writes and ledger evidence together. */
 export declare class RunDatabase {
     readonly filename: string;
@@ -34,6 +36,13 @@ export declare class RunDatabase {
         create?: boolean;
         readOnly?: boolean;
     }): Promise<RunDatabase>;
+    get schemaVersion(): number;
+    /**
+     * Upgrades a version 1 database in place. Only callers that already proved the
+     * run belongs to this Core package call it: a retained older Core must keep
+     * opening the databases of its own runs.
+     */
+    upgradeSchema(): void;
     get revision(): number;
     get transactionRevision(): number;
     /** Undefined reason is reserved for leases/read reservations, which do not change graph history. */

package/dist/agent-runtime/engine/checkpoint/database.js

@@ -61,7 +61,7 @@ CREATE TABLE interrupts (
  attempt_id TEXT NOT NULL REFERENCES attempts(attempt_id), node_path TEXT NOT NULL, scope_id TEXT NOT NULL, branch_id TEXT,
  kind TEXT NOT NULL, requested_at TEXT NOT NULL, payload_json TEXT NOT NULL, answered_at TEXT, answer_json TEXT);
 CREATE TABLE control_inbox (
- request_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES runs(run_id), kind TEXT NOT NULL CHECK(kind IN ('cancel','steer')),
+ request_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES runs(run_id), kind TEXT NOT NULL CHECK(kind IN ('cancel','steer','pause')),
  payload_json TEXT NOT NULL, created_at TEXT NOT NULL, received_sequence INTEGER NOT NULL DEFAULT 0, consumed_by_attempt_id TEXT, consumed_at TEXT);
 CREATE TABLE role_sessions (
  session_key TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES runs(run_id), scope_id TEXT NOT NULL, node_path TEXT NOT NULL,
@@ -95,7 +95,22 @@ CREATE INDEX visits_run ON visits(run_id,node_path,scope_id,local_visit);
 CREATE INDEX attempts_visit ON attempts(visit_id,attempt);
 CREATE INDEX events_cursor ON events(run_id,sequence);
 CREATE INDEX revisions_cut ON row_versions(revision,table_name);
-PRAGMA user_version=1;
+PRAGMA user_version=2;
+`;
+/** Current run database schema. Version 1 lacks the 'pause' control kind and stays readable. */
+export const RUN_DATABASE_SCHEMA = 2;
+/**
+ * Version 1 → 2 only widens the control_inbox kind CHECK to admit 'pause'.
+ * SQLite cannot alter a CHECK constraint, so the table is rebuilt in place.
+ */
+const migrateV1ToV2 = `
+CREATE TABLE control_inbox_v2 (
+ request_id TEXT PRIMARY KEY, run_id TEXT NOT NULL REFERENCES runs(run_id), kind TEXT NOT NULL CHECK(kind IN ('cancel','steer','pause')),
+ payload_json TEXT NOT NULL, created_at TEXT NOT NULL, received_sequence INTEGER NOT NULL DEFAULT 0, consumed_by_attempt_id TEXT, consumed_at TEXT);
+INSERT INTO control_inbox_v2 SELECT request_id,run_id,kind,payload_json,created_at,received_sequence,consumed_by_attempt_id,consumed_at FROM control_inbox;
+DROP TABLE control_inbox;
+ALTER TABLE control_inbox_v2 RENAME TO control_inbox;
+PRAGMA user_version=2;
 `;
 function encodeRow(row) {
     return JSON.stringify(Object.fromEntries(Object.entries(row).map(([key, value]) => [key,
@@ -137,7 +152,7 @@ export class RunDatabase {
                     throw error;
                 }
             }
-            else if (version !== 1)
+            else if (version !== 1 && version !== RUN_DATABASE_SCHEMA)
                 throw new PersistenceError('resume_incompatible', `Unsupported run database schema ${version}`);
             return new RunDatabase(target, sqlite);
         }
@@ -146,6 +161,28 @@ export class RunDatabase {
             throw error;
         }
     }
+    get schemaVersion() { return Number(this.sqlite.prepare('PRAGMA user_version').get()?.user_version); }
+    /**
+     * Upgrades a version 1 database in place. Only callers that already proved the
+     * run belongs to this Core package call it: a retained older Core must keep
+     * opening the databases of its own runs.
+     */
+    upgradeSchema() {
+        if (this.schemaVersion === RUN_DATABASE_SCHEMA)
+            return;
+        if (this.inTransaction)
+            throw new PersistenceError('internal', 'Schema upgrades cannot run inside a transaction');
+        this.sqlite.exec('BEGIN IMMEDIATE');
+        try {
+            if (this.schemaVersion === 1)
+                this.sqlite.exec(migrateV1ToV2);
+            this.sqlite.exec('COMMIT');
+        }
+        catch (error) {
+            this.sqlite.exec('ROLLBACK');
+            throw error;
+        }
+    }
     get revision() { return Number(this.sqlite.prepare('SELECT COALESCE(MAX(revision),0) AS value FROM durable_revisions').get().value); }
     get transactionRevision() {
         if (this.activeRevision === undefined)

package/dist/agent-runtime/engine/checkpoint/ledger.d.ts

@@ -33,6 +33,7 @@ export declare class RunLedger {
     private event;
     /** Public node namespace differs from the parent saver namespace; never parse opaque namespace strings. */
     private bindPendingTask;
+    /** `pause` only at attempt admission: an admitted attempt finishes all of its invocations. */
     private checkAdmission;
     enter(input: NodeAdmission): AttemptFrame;
     resultFor(frame: AttemptFrame): PieceResult | undefined;

package/dist/agent-runtime/engine/checkpoint/ledger.js

@@ -70,10 +70,15 @@ export class RunLedger {
             this.db.put('visits', { ...visit, saver_checkpoint_ns: task.taskCheckpointNs });
         return visit;
     }
-    checkAdmission() {
+    /** `pause` only at attempt admission: an admitted attempt finishes all of its invocations. */
+    checkAdmission(options = {}) {
         const row = this.run(), budget = this.db.get('budget', { run_id: this.runId });
         if (this.db.sqlite.prepare("SELECT 1 FROM control_inbox WHERE run_id=? AND kind='cancel' AND consumed_at IS NULL").get(this.runId))
             throw new EngineError('aborted', 'Cancellation requested');
+        // A cooperative pause lets the current attempts settle and refuses the next one.
+        const pause = options.pause ? new ControlInbox(this.db, this.runId).pauseRequested() : undefined;
+        if (pause)
+            throw new EngineError('paused', 'Pause requested', { requestId: pause.requestId, reason: pause.reason });
         if (this.options.failFast && Number(row.consecutive_failures) >= this.options.failFast)
             throw new EngineError('fail_fast', 'Consecutive AI failure limit reached');
         const duration = this.activeDurationMs();
@@ -112,7 +117,7 @@ export class RunLedger {
                 this.db.put('runs', { ...this.run(), status: 'running', active_started_at: this.run().active_started_at ?? at });
                 return frame;
             }
-            this.checkAdmission();
+            this.checkAdmission({ pause: true });
             if (prior?.status === 'running' && prior.lease_epoch === this.token.epoch && !prior.inherited)
                 throw new EngineError('attempt_running', 'The task is already executing');
             if (prior && (prior.status === 'running' || prior.status === 'interrupted') && input.effect === 'write' && !prior.recovery_authorized)

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

@@ -7,4 +7,16 @@ type Flags = Record<string, string | boolean>;
  * created before its request was materialized) still resolves to this engine.
  */
 export declare function isDefinitionCommand(flags: Flags, command: string): boolean;
+/** `failure` (contract 5.8): the structured classification of a failed or blocked definition run; absent otherwise. */
+export declare function definitionFailure(state: {
+    status: string;
+    steps?: unknown;
+    recentFailures?: unknown;
+    nextStep?: unknown;
+    error?: unknown;
+}): {
+    failure: import("../failure-classification.js").FailureClassification;
+} | {
+    failure?: undefined;
+};
 export declare function runDefinitionCommand(flags: Flags, positionals: string[], emit: (value: unknown) => void): Promise<number>;

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

@@ -12,8 +12,9 @@ import { validateWorkflowDefinition } from './definition-validator.js';
 import { configuredRoles } from './preflight.js';
 import { validationPieceRegistry } from './pieces/index.js';
 import { NODE_KINDS_VERSION } from './piece-registry.js';
-import { cancelRun, createRun, definitionRunDirectory, freezeRunRequest, frozenRequestEngine, frozenRequestFile, resumeRun, signalRun } from './runs.js';
+import { cancelRun, createRun, pauseRun, definitionRunDirectory, freezeRunRequest, frozenRequestEngine, frozenRequestFile, resumeRun, signalRun } from './runs.js';
 import { statusRun } from './run-status.js';
+import { classifyFailure } from '../failure-classification.js';
 import { forkRun } from './fork.js';
 export { NODE_KINDS_VERSION };
 const required = (flags, key) => {
@@ -48,7 +49,7 @@ function directory(flags) {
  * created before its request was materialized) still resolves to this engine.
  */
 export function isDefinitionCommand(flags, command) {
-    if (['workflows', 'fork', 'signal', 'cancel'].includes(command) || flags.definition !== undefined && command === 'run')
+    if (['workflows', 'fork', 'signal', 'cancel', 'pause'].includes(command) || flags.definition !== undefined && command === 'run')
         return true;
     if (!['resume', 'status'].includes(command))
         return false;
@@ -63,6 +64,11 @@ export function isDefinitionCommand(flags, command) {
 }
 /** Public workflow identity carried by status and results, matching the frozen request block. */
 const workflowIdentity = (workflow) => ({ ...workflow, definitionHash: workflow.version, engine: 2 });
+/** `failure` (contract 5.8): the structured classification of a failed or blocked definition run; absent otherwise. */
+export function definitionFailure(state) {
+    const failure = classifyFailure({ status: state.status, error: state.error, steps: state.steps, recentFailures: state.recentFailures, nextStep: state.nextStep });
+    return failure ? { failure } : {};
+}
 export async function runDefinitionCommand(flags, positionals, emit) {
     const command = positionals[0];
     if (command === 'workflows') {
@@ -82,7 +88,7 @@ export async function runDefinitionCommand(flags, positionals, emit) {
     }
     if (command === 'status') {
         const status = await statusRun(directory(flags), flags.compact === true);
-        emit({ ...status, workflow: workflowIdentity(status.workflow) });
+        emit({ ...status, ...definitionFailure(status.state), workflow: workflowIdentity(status.workflow) });
         return 0;
     }
     if (command === 'signal') {
@@ -93,6 +99,11 @@ export async function runDefinitionCommand(flags, positionals, emit) {
         emit({ type: 'runtime-signal-accepted', id: message.id, acceptedAt: message.createdAt });
         return 0;
     }
+    if (command === 'pause') {
+        // Exit 0 for every outcome: a terminal or already stopped run is a reported no-op.
+        emit({ type: 'runtime-pause-result', ...await pauseRun(directory(flags), { requestId: optional(flags, 'request-id'), reason: optional(flags, 'reason') }) });
+        return 0;
+    }
     if (command === 'cancel') {
         emit({ type: 'runtime-cancellation-accepted', ...await cancelRun(directory(flags), optional(flags, 'request-id')) });
         return 0;
@@ -160,7 +171,7 @@ export async function runDefinitionCommand(flags, positionals, emit) {
             const current = result.state.usage[key], prior = previous ? previous.state.usage[key] : 0;
             return current === null || prior === null ? null : Math.max(0, current - prior);
         };
-        emit({ type: 'runtime-result', engineVersion: 2, ...result.state, revision: result.revision, eventCursor: result.eventCursor, workflow: workflowIdentity(result.workflow), completion: result.completion,
+        emit({ type: 'runtime-result', engineVersion: 2, ...result.state, ...definitionFailure({ ...result.state, ...('error' in result ? { error: result.error } : {}) }), revision: result.revision, eventCursor: result.eventCursor, workflow: workflowIdentity(result.workflow), completion: result.completion,
             ...('forkOf' in result ? { forkOf: result.forkOf } : {}), ...('error' in result ? { error: result.error } : {}),
             usage: result.state.usage, invocationUsage: { costUsd: delta('costUsd'), inputTokens: delta('inputTokens'), outputTokens: delta('outputTokens') }, metrics: result.metrics, efficiencySummary: result.efficiencySummary });
         return result.state.status === 'succeeded' ? 0 : result.state.status === 'paused' ? 2 : 1;

package/dist/agent-runtime/engine/definition-schema.d.ts

@@ -192,7 +192,7 @@ export declare const workflowDefinitionSchema: {
             readonly required: readonly ["kind", "params", "ends"];
             readonly properties: {
                 readonly kind: {
-                    readonly enum: readonly ["prompt", "role-turn", "decider", "condition", "assign", "verify", "shell", "openspec-validate", "openspec-archive", "approval", "question", "gate", "map", "join", "component", "implementation", "implementation-step", "artifact-contract", "end"];
+                    readonly enum: readonly ["prompt", "role-turn", "decider", "condition", "assign", "verify", "shell", "openspec-validate", "openspec-archive", "approval", "question", "gate", "map", "join", "component", "implementation", "implementation-step", "derive-change", "artifact-contract", "end"];
                 };
                 readonly params: {
                     readonly type: "object";

package/dist/agent-runtime/engine/definition-schema.js

@@ -252,6 +252,7 @@ export const workflowDefinitionSchema = {
                         "component",
                         "implementation",
                         "implementation-step",
+                        "derive-change",
                         "artifact-contract",
                         "end"
                     ]

package/dist/agent-runtime/engine/definition-types.d.ts

@@ -1,5 +1,5 @@
 import type { EngineEffect, JsonObject, WorkflowBudget } from './contracts.js';
-export declare const PIECE_KINDS: readonly ['prompt', 'role-turn', 'decider', 'condition', 'assign', 'verify', 'shell', 'artifact-contract', 'openspec-validate', 'openspec-archive', 'approval', 'question', 'gate', 'map', 'join', 'component', 'implementation', 'implementation-step', 'end'];
+export declare const PIECE_KINDS: readonly ['prompt', 'role-turn', 'decider', 'condition', 'assign', 'verify', 'shell', 'artifact-contract', 'openspec-validate', 'openspec-archive', 'approval', 'question', 'gate', 'map', 'join', 'component', 'implementation', 'implementation-step', 'end', 'derive-change'];
 export type PieceKind = typeof PIECE_KINDS[number];
 export interface DefinitionNode {
     kind: PieceKind;

package/dist/agent-runtime/engine/definition-types.js

@@ -1,3 +1,3 @@
 export const PIECE_KINDS = ['prompt', 'role-turn', 'decider', 'condition', 'assign', 'verify', 'shell',
     'artifact-contract', 'openspec-validate', 'openspec-archive', 'approval', 'question', 'gate', 'map', 'join',
-    'component', 'implementation', 'implementation-step', 'end'];
+    'component', 'implementation', 'implementation-step', 'end', 'derive-change'];

package/dist/agent-runtime/engine/definition-validator.js

@@ -116,6 +116,14 @@ export function validateWorkflowDefinition(input, registry, roles = {}, options
                             add('role_not_found', path + '/params/roleId', 'Used role is not configured');
                         if (node.kind === 'decider' && typeof roleId === 'string' && roles[roleId]?.access !== 'read')
                             add('invalid_role_access', path + '/params/roleId', 'Decider role must be read-only');
+                        // A correction round edits code. Portable (structural) validation cannot know an unresolved role's access; execution validates again.
+                        if (node.kind === 'role-turn' && node.params.stance === 'fixer' && typeof roleId === 'string' && Object.hasOwn(roles, roleId) && !unresolved.includes(roleId) && roles[roleId]?.access !== 'write')
+                            add('invalid_role_access', path + '/params/stance', 'The fixer stance requires a role with write access');
+                    }
+                    // derive-change always invokes Core's engine role `deriver`.
+                    if (node.kind === 'derive-change') {
+                        if (!definition.roles.includes('deriver'))
+                            add('role_undeclared', path, 'derive-change requires the deriver role in definition.roles');
                     }
                     const effect = effectOf(node);
                     writes ||= effect === 'write';

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

@@ -33,6 +33,13 @@ export declare function definitionEfficiencySummary(ledger: RunLedger, state: Wo
         fullContexts: number;
         incrementalContexts: number;
     };
+    baseline: {
+        invocations: number;
+        roles: string[];
+        costUsd: number | null;
+        inputTokens: number | null;
+        outputTokens: number | null;
+    };
     escalations: {
         role: string;
         attemptId: string;