specrails-core 6.1.0 → 6.2.1

package/dist/agent-runtime/engine/pieces/artifact-contract.js

@@ -0,0 +1,70 @@
+import { readFileSync, readdirSync } from 'node:fs';
+import { artifactPath } from '../../openspec.js';
+import { contentDigest } from '../canonical-json.js';
+import { EngineError } from '../contracts.js';
+import { idSchema, paramsSchema, text } from './shared.js';
+/** A reusable artifact invariant, with no agent roles, phase order or successor policy. */
+export function artifactContractPiece(bindings) {
+    return {
+        descriptor: { kind: 'artifact-contract', paramsSchema: paramsSchema({
+                change: { type: 'string', minLength: 1, maxLength: 128 }, contractId: idSchema, action: { enum: ['freeze', 'check'] },
+                requireCompletedTasks: { type: 'boolean' },
+            }, ['change', 'contractId', 'action']), outcomes: ['pass', 'fail', 'failed'], effect: 'read', requiresAI: false },
+        async execute(params, context) {
+            const deps = bindings(), change = text(params.change);
+            if (!/^[a-z0-9]+(?:-[a-z0-9]+)*$/.test(change) || change.length > 64)
+                throw new EngineError('invalid_arguments', 'Invalid change identifier');
+            const store = deps.artifactContracts?.(context);
+            if (!store)
+                throw new EngineError('artifact_contract_unavailable', 'Scoped artifact contracts are not bound');
+            const directory = 'openspec/changes/' + change;
+            const files = {};
+            let bytes = 0;
+            const read = (relative) => {
+                const source = readFileSync(artifactPath(deps.context.artifactRoot, directory + '/' + relative), 'utf8');
+                bytes += Buffer.byteLength(source);
+                if (bytes > 2 * 1024 * 1024 || Object.keys(files).length >= 200)
+                    throw new EngineError('output_limit', 'Artifact contract exceeds its read limit');
+                return source;
+            };
+            try {
+                for (const name of ['proposal.md', 'design.md', 'tasks.md'])
+                    files[name] = read(name);
+                const walk = (relative) => {
+                    for (const entry of readdirSync(artifactPath(deps.context.artifactRoot, directory + '/' + relative), { withFileTypes: true })) {
+                        const child = relative + '/' + entry.name;
+                        if (entry.isSymbolicLink())
+                            throw new EngineError('artifact_scope_mismatch', 'Artifact contracts reject symlinks');
+                        if (entry.isDirectory())
+                            walk(child);
+                        else if (entry.isFile() && entry.name.endsWith('.md'))
+                            files[child] = read(child);
+                    }
+                };
+                walk('specs');
+            }
+            catch (error) {
+                if (error instanceof EngineError)
+                    throw error;
+                return { outcome: 'fail', output: { reason: 'required_artifacts_missing' } };
+            }
+            if (!Object.keys(files).some(name => name.startsWith('specs/')) || Object.values(files).some(source => !source.trim()))
+                return { outcome: 'fail', output: { reason: 'empty_artifacts' } };
+            const tasks = [...files['tasks.md'].matchAll(/^\s*[-*]\s+\[([ xX])\]\s+(.+)$/gm)];
+            if (!tasks.length)
+                return { outcome: 'fail', output: { reason: 'tasks_missing' } };
+            // Completion may change checkboxes, never the approved task descriptions.
+            files['tasks.md'] = files['tasks.md'].replace(/^(\s*[-*]\s+\[)[ xX](\]\s+)/gm, '$1 $2');
+            const fingerprint = contentDigest(files), key = text(params.contractId);
+            if (params.action === 'freeze')
+                store.set(key, { fingerprint });
+            else {
+                const frozen = store.get(key);
+                if (!frozen || frozen.fingerprint !== fingerprint)
+                    return { outcome: 'fail', output: { reason: frozen ? 'artifacts_changed' : 'contract_missing' } };
+            }
+            const incomplete = tasks.filter(task => task[1] === ' ').length;
+            return { outcome: params.requireCompletedTasks && incomplete ? 'fail' : 'pass', output: { fingerprint, tasks: tasks.length, incomplete } };
+        },
+    };
+}

package/dist/agent-runtime/engine/pieces/control.js

@@ -27,10 +27,14 @@ export function controlPieces(bindings) {
     for (const kind of ['approval', 'question', 'gate']) {
         const field = kind === 'question' ? 'text' : 'reason';
         pieces.push({
-            descriptor: { kind, paramsSchema: paramsSchema({ [field]: { ...stringSchema, minLength: 1 } }, [field]), outcomes: ['next'], effect: 'read', requiresAI: false },
+            descriptor: { kind, paramsSchema: paramsSchema({ [field]: { ...stringSchema, minLength: 1 }, bindCandidate: { type: 'boolean' }, enabled: { type: 'boolean' } }, [field]), outcomes: ['next'], effect: 'read', requiresAI: false },
             async execute(params, context) {
-                const response = context.interrupt({ kind, prompt: text(params[field]), nodePath: context.frame.nodePath, scopeId: context.frame.scope.id, attemptId: context.frame.attemptId });
-                return { outcome: 'next', output: { response }, ...(kind === 'question' ? { answers: [answerEntry(context, response)] } : {}) };
+                const memo = bindings().memo(context);
+                const bound = params.bindCandidate ? memo.get('approval-candidate') ?? bindings().executionSnapshot(context).candidate?.hash ?? null : undefined;
+                if (params.bindCandidate && memo.get('approval-candidate') === undefined)
+                    memo.set('approval-candidate', bound);
+                const response = kind === 'approval' && params.enabled === false ? { approved: true } : context.interrupt({ kind, prompt: text(params[field]), nodePath: context.frame.nodePath, scopeId: context.frame.scope.id, attemptId: context.frame.attemptId });
+                return { outcome: 'next', output: { response, ...(params.bindCandidate ? { candidateHash: bound } : {}) }, ...(kind === 'question' ? { answers: [answerEntry(context, response)] } : {}) };
             },
         });
     }

package/dist/agent-runtime/engine/pieces/implementation-binding.d.ts

@@ -1,6 +1,7 @@
 import { type PipelineContext } from '../../../pipeline/pipeline-state.js';
 import { type PieceExecutionContext } from '../contracts.js';
 export interface ImplementationBinding {
+    shared?: true;
     context: PipelineContext;
     change: string;
     parentRunId: string;

package/dist/agent-runtime/engine/pieces/implementation-step.d.ts

@@ -0,0 +1,5 @@
+import { type Piece } from '../contracts.js';
+import type { PieceDependencyProvider } from './ports.js';
+/** Outcomes are facts, not destinations. Only the host definition chooses the next node. */
+export declare const IMPLEMENTATION_STEP_OUTCOMES: readonly ["next", "incomplete", "rejected", "replan", "reverify", "rereview", "failed"];
+export declare function implementationStepPiece(bindings: PieceDependencyProvider): Piece;

package/dist/agent-runtime/engine/pieces/implementation-step.js

@@ -0,0 +1,47 @@
+import { CoreState } from '../../graph/state.js';
+import { EngineError } from '../contracts.js';
+import { createImplementationAdapter } from './implementation.js';
+import { json, paramsSchema } from './shared.js';
+/** Outcomes are facts, not destinations. Only the host definition chooses the next node. */
+export const IMPLEMENTATION_STEP_OUTCOMES = ['next', 'incomplete', 'rejected', 'replan', 'reverify', 'rereview', 'failed'];
+export function implementationStepPiece(bindings) {
+    return {
+        descriptor: { kind: 'implementation-step', paramsSchema: paramsSchema({
+                phase: { enum: ['architect', 'developer', 'fixer', 'verify', 'reviewer', 'archive'] },
+            }, ['phase']), outcomes: [...IMPLEMENTATION_STEP_OUTCOMES], effect: 'write', requiresAI: true },
+        async execute(params, context) {
+            const deps = bindings(), phase = params.phase;
+            const change = deps.change ?? context.state.$vars.changeId;
+            if (typeof change !== 'string')
+                throw new EngineError('invalid_arguments', 'Implementation operation requires a frozen change');
+            const saved = deps.operationState?.(context);
+            const resumed = [...deps.stepContext(context).checkpoint.events].reverse().find(event => event.type === 'workflow_resumed')?.timestamp ?? '';
+            const adapter = createImplementationAdapter(deps, { change, params: {}, independent: true, revalidate: saved?.operationResume !== resumed, archiveConsent: saved?.operationRunId === deps.context.runId && typeof saved.operationConsent === 'string' ? saved.operationConsent : undefined });
+            const initialized = await adapter.initialize(context);
+            const initial = { plan: [], unverifiedRepositories: [], architecture: null, development: null,
+                verifyResult: null, review: null, answers: [], deepenPasses: 0, archived: null, verifyHistory: [] };
+            const state = { ...initial, ...saved?.operationState,
+                ...(saved?.operationRunId === deps.context.runId ? {} : initialized) };
+            const response = await adapter.runNode(phase, state, context);
+            const updated = { ...state };
+            for (const [key, value] of Object.entries(response.update ?? {})) {
+                const channel = CoreState.spec[key];
+                updated[key] = channel.operator ? channel.operator(state[key], value) : value;
+            }
+            const normal = { architect: 'developer', developer: 'verify', fixer: 'verify', verify: 'reviewer', reviewer: 'archive', archive: null }[phase];
+            const next = response.next === undefined ? normal : response.next;
+            const outcome = response.status !== 'succeeded' ? 'failed' : next === normal ? 'next'
+                : next === 'architect' ? 'replan' : next === 'verify' ? 'reverify' : next === 'reviewer' ? 'rereview'
+                    : next === 'developer' ? 'incomplete' : next === 'fixer' ? 'rejected' : 'failed';
+            // The summary reads host verification receipts and acceptance, never an agent's claim.
+            const evidence = await adapter.summarize(updated, context);
+            return { outcome, status: response.status,
+                ...(response.output === undefined ? {} : { output: json({ ...((response.output && typeof response.output === 'object' && !Array.isArray(response.output)) ? response.output : { value: response.output }), phase }) }),
+                ...(response.error ? { error: { code: response.status === 'blocked' ? 'implementation_blocked' : 'implementation_failed', message: response.error } } : {}),
+                childUpdate: { operationState: json(updated), operationRunId: deps.context.runId, operationResume: resumed, operationConsent: adapter.consentSnapshot?.(context) ?? null, journal: json(adapter.snapshot(context)) },
+                ...(evidence.receipt ? { receipt: evidence.receipt, verified: phase === 'archive' && outcome === 'next' ? evidence.verified : null } : {}),
+                ...(phase === 'archive' && outcome === 'next' ? { completion: evidence.completion } : {}),
+            };
+        },
+    };
+}

package/dist/agent-runtime/engine/pieces/implementation.d.ts

@@ -11,13 +11,17 @@ export interface ImplementationAdapter {
     initialize(context: PieceExecutionContext): Promise<CoreStateUpdate>;
     runNode(id: CoreNodeId, state: CoreStateType, context: PieceExecutionContext): Promise<NodeResult<CoreStateType>>;
     snapshot(context: PieceExecutionContext): ImplementationJournalSnapshot;
+    consentSnapshot?(context: PieceExecutionContext): string | undefined;
     summarize(state: CoreStateType, context: PieceExecutionContext): Promise<PieceResult>;
     validateCompleted(id: CoreNodeId, record: StepRecord, checkpoint: WorkflowState, context: PieceExecutionContext): Promise<boolean>;
 }
 /** Scope the legacy convergence/attempt view without changing durable event attribution. */
-export declare function implementationStepContext(deps: PieceDependencies, context: PieceExecutionContext, id: CoreNodeId): WorkflowStepContext;
+export declare function implementationStepContext(deps: PieceDependencies, context: PieceExecutionContext, id: CoreNodeId, independent?: boolean): WorkflowStepContext;
 /** Reuse every legacy node and quality gate; this factory never runs the legacy JSON workflow host. */
 export declare function createImplementationAdapter(deps: PieceDependencies, input: {
     change: string;
     params: JsonObject;
+    independent?: boolean;
+    revalidate?: boolean;
+    archiveConsent?: string;
 }): ImplementationAdapter;

package/dist/agent-runtime/engine/pieces/implementation.js

@@ -15,9 +15,9 @@ import { json } from './shared.js';
 import { receiptEvidence } from './verify.js';
 import { captureImplementationJournal } from './implementation-journal.js';
 /** Scope the legacy convergence/attempt view without changing durable event attribution. */
-export function implementationStepContext(deps, context, id) {
+export function implementationStepContext(deps, context, id, independent = false) {
     const original = deps.stepContext(context);
-    const prefix = context.frame.nodePath.slice(0, -id.length);
+    const prefix = independent ? '' : context.frame.nodePath.slice(0, -id.length);
     const local = (value) => value.startsWith(prefix) ? value.slice(prefix.length) : value;
     const belongs = (value) => CORE_NODE_ORDER.includes(value) || (value.startsWith(prefix) && !value.slice(prefix.length).includes('/'));
     const checkpoint = original.checkpoint;
@@ -46,7 +46,7 @@ export function createImplementationAdapter(deps, input) {
         ...(params.reviewPolicy ? { review: params.reviewPolicy } : {}) };
     const attempts = params.attempts ?? config.limits?.maxAttempts ?? 3;
     const bindings = new Map();
-    const instanceKey = (context) => context.frame.scope.id + '/' + context.frame.visitId;
+    const instanceKey = (context) => input.independent ? context.frame.scope.id : context.frame.scope.id + '/' + context.frame.visitId;
     const metadata = { context: deps.context, config, change, attempts, policy: resolveReviewPolicy(config), openspec: {}, focusedCorrectionEvidence: true,
         invoke: (() => { throw new EngineError('implementation_not_initialized', 'Implementation metadata nodes must run through the durable adapter'); }), note() { } };
     const refresh = (binding, context) => {
@@ -64,7 +64,7 @@ export function createImplementationAdapter(deps, input) {
         schema: CoreState, nodes: coreNodes(metadata), entry: 'architect',
         async initialize(context) {
             context.signal.throwIfAborted();
-            const binding = deps.bindImplementation(context, change);
+            const binding = deps.bindImplementation(context, change, input.independent);
             const pipeline = binding.context;
             const state = initializePipeline(pipeline, binding.change);
             refresh(binding, context);
@@ -81,7 +81,7 @@ export function createImplementationAdapter(deps, input) {
             }));
             for (const role of Object.keys(openspec))
                 await deps.registry.get(resolveRoleDescriptor(config, role).provider).validateOpenSpec?.(openspec[role]);
-            bindings.set(instanceKey(context), { binding, openspec, resumeChecked: false });
+            bindings.set(instanceKey(context), { binding, openspec, resumeChecked: input.independent === true && input.revalidate === false, archiveConsent: input.archiveConsent });
             if (existsSync(path.join(directory, 'implementation-fork.json'))) {
                 const plan = readVerificationPlan(pipeline);
                 return { ...(plan ? { plan: expandedPlanCommands(pipeline, plan) } : {}), verifyResult: null, review: null, archived: null, verifyHistory: [] };
@@ -94,7 +94,7 @@ export function createImplementationAdapter(deps, input) {
                 throw new EngineError('implementation_not_initialized', 'Initialize this implementation scope before executing its child graph');
             const { binding, openspec } = prepared;
             refresh(binding, context);
-            const step = implementationStepContext(deps, context, id);
+            const step = implementationStepContext(deps, context, id, input.independent);
             if (!prepared.resumeChecked && (step.pending || step.checkpoint.events.some(event => event.type === 'workflow_resumed'))) {
                 // Collect archive consent first, then revalidate completed verification
                 // and review exactly as the legacy host does on explicit resume.
@@ -120,7 +120,7 @@ export function createImplementationAdapter(deps, input) {
                     }
                 }
             }
-            const invoke = createRoleInvoker({ context: binding.context, config, registry: deps.registry, openspec, roleState: deps.roleState(context),
+            const invoke = createRoleInvoker({ context: binding.context, config, registry: deps.registry, openspec, roleState: deps.roleState(context), propagateInterruptions: input.independent,
                 onAgentEvent: (role, event) => context.progress({ type: 'agent-event', payload: json({ role, event }) }) });
             const localConfig = { ...config, verification: config.verification.filter(command => binding.context.repositories.some(repository => repository.id === command.repositoryId)) };
             const nodes = coreNodes({ ...metadata, context: binding.context, config: localConfig, change: binding.change, openspec, invoke,
@@ -130,6 +130,7 @@ export function createImplementationAdapter(deps, input) {
             });
             return nodes[id].run(state, step);
         },
+        consentSnapshot(context) { return bindings.get(instanceKey(context))?.archiveConsent; },
         snapshot(context) {
             const prepared = bindings.get(context.frame.scope.id) ?? bindings.get(instanceKey(context));
             if (!prepared)

package/dist/agent-runtime/engine/pieces/index.js

@@ -1,3 +1,4 @@
+import { artifactContractPiece } from './artifact-contract.js';
 import { PieceRegistry } from '../piece-registry.js';
 import { controlPieces, compositionPieces } from './control.js';
 import { deciderPiece } from './decider.js';
@@ -7,6 +8,7 @@ import { promptPiece } from './prompt.js';
 import { roleTurnPiece } from './role-turn.js';
 import { shellPiece } from './shell.js';
 import { verifyPiece } from './verify.js';
+import { implementationStepPiece } from './implementation-step.js';
 import { assignPiece } from './assign.js';
 /** The composition root binds effects once; definitions can only select this reviewed catalog. */
 export function createPieceRegistry(deps) {
@@ -18,5 +20,5 @@ export function validationPieceRegistry() {
 }
 function registry(bindings) {
     return new PieceRegistry([promptPiece(bindings), roleTurnPiece(bindings), deciderPiece(bindings), verifyPiece(bindings), shellPiece(bindings),
-        ...openSpecPieces(bindings), ...controlPieces(bindings), assignPiece(), ...compositionPieces()]);
+        artifactContractPiece(bindings), ...openSpecPieces(bindings), ...controlPieces(bindings), assignPiece(), implementationStepPiece(bindings), ...compositionPieces()]);
 }

package/dist/agent-runtime/engine/pieces/openspec.js

@@ -42,12 +42,18 @@ export function openSpecPieces(bindings) {
                 return { outcome: exited && item.valid ? 'pass' : 'fail', output: json(report) };
             },
         }, {
-            descriptor: { kind: 'openspec-archive', paramsSchema: schema, outcomes: ['next', 'failed'], effect: 'write', requiresAI: false },
+            descriptor: { kind: 'openspec-archive', paramsSchema: { ...schema, properties: { ...schema.properties, requiresVerified: { type: 'boolean' }, reviewedCandidate: { type: 'string' }, approvedCandidate: { type: 'string' } } }, outcomes: ['next', 'failed'], effect: 'write', requiresAI: false },
             async execute(params, context) {
                 const deps = bindings();
                 if (params.repositoryId !== undefined && params.repositoryId !== deps.context.artifactRepositoryId)
                     throw new EngineError('artifact_scope_mismatch', 'OpenSpec repository must match the frozen artifact repository');
-                const change = changeId(text(params.change)), initial = deps.executionSnapshot(context).candidate?.hash;
+                const snapshot = deps.executionSnapshot(context);
+                const verified = snapshot.verified ?? deps.verifiedBeforeWrite?.(context);
+                if (params.requiresVerified && (!snapshot.candidate || !verified || verified.candidateHash !== snapshot.candidate.hash))
+                    return { outcome: 'failed', output: { reason: 'unverified' } };
+                if ([params.reviewedCandidate, params.approvedCandidate].some(hash => hash !== undefined && hash !== snapshot.candidate?.hash))
+                    return { outcome: 'failed', output: { reason: 'candidate_changed' } };
+                const change = changeId(text(params.change)), initial = snapshot.candidate?.hash;
                 const archived = params.allowArchived === true ? archivedOpenSpecChange(deps.context, change) : undefined;
                 if (archived)
                     return { outcome: 'next', output: { change, archived, skipped: true } };

package/dist/agent-runtime/engine/pieces/ports.d.ts

@@ -15,15 +15,18 @@ export interface PieceStatePort {
 }
 export interface PieceDependencies {
     context: PipelineContext;
+    readonly change?: string;
     config: RuntimeConfig;
     registry: ExecutorRegistry;
     stepContext(context: PieceExecutionContext): WorkflowStepContext;
     roleState(context: PieceExecutionContext): RoleStatePort;
+    artifactContracts?(context: PieceExecutionContext): PieceStatePort;
     memo(context: PieceExecutionContext): PieceStatePort;
     /** Narrow project memory is restricted by the declared piece and namespace capability. */
     memory(context: PieceExecutionContext): ProjectMemory;
     /** Provider settlement and the response needed for interrupt replay share one transaction. */
     settleResult(context: PieceExecutionContext, key: string, value: JsonValue, invocation: ProviderInvocation): void;
+    verifiedBeforeWrite?(context: PieceExecutionContext): VerifiedState | null;
     executionSnapshot(context: PieceExecutionContext): {
         candidate: CandidateState | null;
         verified: VerifiedState | null;
@@ -32,13 +35,15 @@ export interface PieceDependencies {
     /** A scoped adapter directory for recoverable OpenSpec write sets, never state.json. */
     artifactDirectory(context: PieceExecutionContext): string;
     /** Registers parent-owned scoped journals for candidate inspection, recovery and fork. */
-    bindImplementation(context: PieceExecutionContext, change: string): ImplementationBinding;
+    bindImplementation(context: PieceExecutionContext, change: string, shared?: boolean): ImplementationBinding;
     /** Current union of declared implementation artifacts and journals, including the parent run. */
     implementationExclusions?(context: PieceExecutionContext): {
         runtimeExclusions: readonly string[];
         repositoryExclusions: Readonly<Record<string, readonly string[]>>;
     };
     openspec?(context: PieceExecutionContext): Record<string, OpenSpecRoleContext>;
+    /** Committed private operation state, inaccessible to workflow variables or fork patches. */
+    operationState?(context: PieceExecutionContext): JsonValue | undefined;
     policies?: {
         historyMaxChars?: number;
         noProgress?: number;

package/dist/agent-runtime/engine/pieces/prompt.js

@@ -5,7 +5,7 @@ import { contentDigest } from '../canonical-json.js';
 import { EngineError } from '../contracts.js';
 import { answerEntry, boundedText, captures, captureSchema, historyEntry, json, paramsSchema, invocationTimers, stringSchema, text } from './shared.js';
 const sessionFailures = new Set(['session_not_found', 'session_expired', 'session_unsupported']);
-const engineSchema = paramsSchema({ provider: { type: 'string', minLength: 1, maxLength: 128 }, model: { type: 'string', minLength: 1, maxLength: 256 }, effort: { type: 'string', minLength: 1, maxLength: 64 }, thinking: { enum: ['on', 'off'] } }, ['provider']);
+const engineSchema = paramsSchema({ provider: { type: 'string', minLength: 1, maxLength: 128 }, model: { type: 'string', minLength: 1, maxLength: 256 }, effort: { type: 'string', minLength: 1, maxLength: 64 }, thinking: { enum: ['on', 'off'] }, maxTurns: { type: 'integer', minimum: 1 } }, ['provider']);
 const promptSchema = {
     ...paramsSchema({ engine: engineSchema, text: { ...stringSchema, minLength: 1 }, nativeCommand: paramsSchema({ id: { type: 'string', pattern: '^[a-z][a-z0-9:_-]{0,63}$' }, args: stringSchema }, ['id']),
         access: { enum: ['read', 'write'] }, sentinel: { enum: ['verification', 'blocked', 'none'] }, captureVars: captureSchema,
@@ -58,7 +58,7 @@ export function promptPiece(bindings) {
                         prompt: native ? '' : text(params.text) + suffix,
                         ...(native ? { nativeCommand: { id: native.id, args: (native.args ?? '') + suffix } } : {}),
                         cwd: deps.context.artifactRoot, allowedRoots: deps.context.repositories.map(repo => repo.path),
-                        model: engine.model, effort: engine.effort, thinking: engine.thinking,
+                        model: engine.model, effort: engine.effort, thinking: engine.thinking, maxTurns: engine.maxTurns,
                         timeoutMs: params.timeoutMs ?? deps.config.limits?.timeoutMs,
                         idleTimeoutMs: params.idleTimeoutMs ?? deps.config.limits?.idleTimeoutMs,
                         signal: context.signal, resumeSessionId: sessionId,

package/dist/agent-runtime/engine/pieces/role-turn.js

@@ -68,6 +68,6 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
             await memory.put(['review', 'notes'], finalKey, { roleId, candidateHash: before?.hash ?? null,
                 text: boundedText(result.text, 4000), lastAttemptId: context.frame.attemptId });
     });
-    return { outcome: 'next', output: { text: boundedText(result.text), ...(result.value ? { structured: json(result.value) } : {}) },
+    return { outcome: 'next', output: { candidateHash: deps.executionSnapshot(context).candidate?.hash ?? null, text: boundedText(result.text), ...(result.value ? { structured: json(result.value) } : {}) },
         history: [historyEntry(context, result.text)], ...(params.sessionContinuity !== 'none' && session ? { session: { sessionId: session.sessionId, identity: session.identity } } : {}) };
 }

package/dist/agent-runtime/engine/pieces/verify.js

@@ -1,8 +1,59 @@
+import { stripVTControlCharacters } from 'node:util';
 import { contentDigest } from '../canonical-json.js';
 import { advisoryMemory } from './project-memory.js';
 import { executeVerification, validateVerificationRequest } from '../../../pipeline/pipeline-state.js';
 import { withScopeDefault } from '../../change-scope.js';
-import { json, paramsSchema, positiveInteger } from './shared.js';
+import { verificationFailureSummary } from '../../verification-diagnostics.js';
+import { boundedText, json, paramsSchema, positiveInteger } from './shared.js';
+/** Keep real subprocess diagnostics in committed outputs for subsequent agents.
+ * The full command evidence remains in the receipt; prioritize failed checks
+ * when the output budget is exhausted. */
+function verificationDiagnostics(receipt) {
+    let remaining = 32_000;
+    const outputs = new Map();
+    const priority = receipt.commands.map((command, index) => ({ command, index }))
+        .sort((a, b) => Number(b.command.exitCode !== 0) - Number(a.command.exitCode !== 0));
+    for (const { command, index } of priority) {
+        const limit = Math.min(8_000, remaining);
+        const source = stripVTControlCharacters([command.stdout ?? '', command.stderr ?? '', command.output].join('\n'));
+        const lines = source.split('\n');
+        const failures = [];
+        let used = 0;
+        for (let i = 0; command.exitCode !== 0 && i < lines.length && used < 6_000; i++) {
+            if (!/^\s*(?:not ok\b|[✖✗]\s|test at\b|FAIL\b|Error:|AssertionError\b|error:)/.test(lines[i]))
+                continue;
+            const excerpt = lines.slice(Math.max(0, i - 2), i + 28).join('\n').slice(0, 6_000 - used);
+            failures.push(excerpt);
+            used += excerpt.length;
+            i += 27;
+        }
+        const failureText = failures.join('\n').slice(0, Math.min(6_000, limit));
+        const tailBudget = Math.max(0, limit - failureText.length - (failureText ? 1 : 0));
+        const output = failureText + (failureText && tailBudget ? '\n' : '') + (tailBudget ? command.output.slice(-tailBudget) : '');
+        // slice(-0) would include all the original text.
+        outputs.set(index, remaining > 0 ? output : '');
+        remaining -= remaining > 0 ? output.length : 0;
+    }
+    let budget = 64_000;
+    const commands = [];
+    for (const { index, command } of priority) {
+        const output = outputs.get(index) ?? '';
+        const args = command.args.slice(0, 16).map(arg => boundedText(arg, 128));
+        const diagnostic = { repositoryId: command.repositoryId, command: boundedText(command.command, 512),
+            args, cwd: boundedText(command.cwd, 512),
+            exitCode: command.exitCode, durationMs: command.durationMs, output,
+            ...(command.evidenceId ? { evidenceId: boundedText(command.evidenceId, 128) } : {}),
+            ...(command.exitCode !== 0 ? { failureSummary: verificationFailureSummary(command) } : {}),
+            truncated: output.length < command.output.length || command.outputTruncated === true
+                || command.command.length > 512 || command.cwd.length > 512 || command.args.length > 16 || command.args.some(arg => arg.length > 128) };
+        const size = JSON.stringify(diagnostic).length;
+        if (size > budget)
+            break;
+        budget -= size;
+        commands.push(diagnostic);
+    }
+    return { commands, ...(commands.length < receipt.commands.length ? { omittedCommands: receipt.commands.length - commands.length } : {}) };
+}
 export const verificationCommandSchema = paramsSchema({
     repositoryId: { type: 'string', minLength: 1, maxLength: 128 }, command: { type: 'string', minLength: 1, maxLength: 4096 },
     args: { type: 'array', maxItems: 1024, items: { type: 'string', maxLength: 32_000 } }, cwd: { type: 'string', maxLength: 4096 },
@@ -19,10 +70,28 @@ export function verificationDeadline(deps, context) {
 export function verifyPiece(bindings) {
     return {
         descriptor: { kind: 'verify', paramsSchema: paramsSchema({ commands: { oneOf: [{ const: 'configured' }, { type: 'array', maxItems: 100, items: verificationCommandSchema }] },
-                unverified: { type: 'boolean' }, maxConcurrency: { type: 'integer', minimum: 1, maximum: 4 } }, ['commands']), outcomes: ['pass', 'fail', 'failed'], effect: 'write', requiresAI: false, storeAccess: 'write' },
+                additionalCommandsFrom: { type: 'string', minLength: 1, maxLength: 128 }, unverified: { type: 'boolean' }, maxConcurrency: { type: 'integer', minimum: 1, maximum: 4 } }, ['commands']), outcomes: ['pass', 'fail', 'failed'], effect: 'write', requiresAI: false, storeAccess: 'write' },
         async execute(params, context) {
             const deps = bindings();
             const commands = (params.commands === 'configured' ? deps.config.verification : params.commands).map(command => withScopeDefault(deps.context, command));
+            const hostRepositories = new Set(commands.map(command => command.repositoryId));
+            if (typeof params.additionalCommandsFrom === 'string') {
+                const source = context.state.$outputs[params.additionalCommandsFrom];
+                const proposals = source?.structured?.verification;
+                if (!Array.isArray(proposals) || proposals.length > 20)
+                    throw new Error('Verification proposals must be a bounded array from a committed agent output');
+                // Host checks always stay mandatory. The same scoped command validation
+                // applies to these actual subprocesses and to configured checks below.
+                for (const proposal of proposals) {
+                    if (!proposal || typeof proposal !== 'object' || Array.isArray(proposal))
+                        throw new Error('Invalid verification proposal');
+                    const raw = proposal;
+                    if (!deps.context.repositories.some(repository => repository.id === raw.repositoryId))
+                        throw new Error('Unknown verification repository');
+                    if (!hostRepositories.has(raw.repositoryId))
+                        commands.push(withScopeDefault(deps.context, raw));
+                }
+            }
             const coversAll = deps.context.repositories.every(repository => commands.some(command => command.repositoryId === repository.id));
             const request = { kind: coversAll || params.unverified === true ? 'full' : 'scoped', commands, ...(params.unverified === true ? { unverified: true } : {}) };
             validateVerificationRequest(deps.context, request);
@@ -43,9 +112,15 @@ export function verifyPiece(bindings) {
             }));
             const infrastructure = receipt.commands.some(command => command.exitCode === -1 && command.outcome !== 'cancelled');
             const outcome = infrastructure ? 'failed' : receipt.valid ? 'pass' : 'fail';
+            const progressKey = 'verification-' + contentDigest(context.frame.nodePath).slice(0, 20);
+            const fingerprint = contentDigest(json({ candidateHash: identity.candidateHash,
+                failures: receipt.commands.filter(command => command.exitCode !== 0).map(command => ({ repositoryId: command.repositoryId, command: command.command, args: command.args, cwd: command.cwd, exitCode: command.exitCode })) }));
+            const previous = context.state.$vars[progressKey];
+            const count = receipt.valid ? 0 : previous?.fingerprint === fingerprint ? (previous.count ?? 0) + 1 : 1;
+            const stalled = !infrastructure && !receipt.valid && count >= 3;
             const verified = receipt.valid && receipt.commands.length > 0 && !receipt.unverifiedRepositories?.length;
-            return { outcome, ...(infrastructure ? { status: 'failed', error: { code: 'verification_execution_error', message: receipt.reason ?? 'A verification command could not complete' } } : {}),
-                output: { receiptId: receipt.id, valid: receipt.valid, ...(receipt.reason ? { reason: receipt.reason } : {}), commands: receipt.commands.map(command => ({ repositoryId: command.repositoryId, command: command.command, exitCode: command.exitCode })) },
+            return { outcome: stalled ? 'failed' : outcome, vars: { [progressKey]: { fingerprint, count } }, ...(stalled ? { status: 'failed', error: { code: 'verification_no_progress', message: 'Verification failed three times on the same unchanged candidate. Stopping automatic corrections; inspect the failed checks.' } } : {}), ...(infrastructure ? { status: 'failed', error: { code: 'verification_execution_error', message: receipt.reason ?? 'A verification command could not complete' } } : {}),
+                output: { receiptId: receipt.id, valid: receipt.valid, candidateHash: identity.candidateHash, noProgressCount: count, ...(receipt.reason ? { reason: receipt.reason } : {}), ...(stalled ? { reason: 'Verification failed three times without candidate changes' } : {}), ...verificationDiagnostics(receipt) },
                 receipt: receiptEvidence(receipt), ...(verified ? { verified: { receiptId: receipt.id, candidateHash: receipt.candidateHash, atTransition: context.frame.transition, revision: context.frame.transition } } : { verified: null }) };
         },
     };

package/dist/agent-runtime/graph/nodes.js

@@ -1,4 +1,5 @@
 import { guardrailEnabled } from '../guardrails.js';
+import { verificationFailureSummary } from '../verification-diagnostics.js';
 import { addDeveloperChecks, bindPlan, expandedPlanCommands, initializeVerificationPlan, readVerificationPlan, validateProposedChecks } from '../verification-plan.js';
 import { existsSync } from 'node:fs';
 import path from 'node:path';
@@ -410,7 +411,7 @@ function verifyNode(deps) {
             }
             const evidence = {
                 valid: receipt.valid, ...(receipt.reason ? { reason: receipt.reason } : {}), receiptId: receipt.id, unverifiedRepositories: uncovered,
-                commands: receipt.commands.map(({ evidenceId, repositoryId, command, args, exitCode, output }) => ({ ...(evidenceId ? { evidenceId } : {}), repositoryId, command, args, exitCode, output: output.slice(-2000) })),
+                commands: receipt.commands.map(command => ({ ...(command.evidenceId ? { evidenceId: command.evidenceId } : {}), repositoryId: command.repositoryId, command: command.command, args: command.args, cwd: command.cwd, exitCode: command.exitCode, failureSummary: verificationFailureSummary(command), output: command.output.slice(-2000) })),
             };
             const outcome = (passed, finding) => ({ at: new Date().toISOString(), candidateHash: receipt.candidateHash, planHash: effective.planHash, passed, ...(passed ? {} : describeFailure(receipt, roots, finding)) });
             /** Hands a failure to the fixer unless the correction loop has stopped converging. */

package/dist/agent-runtime/graph/roles.d.ts

@@ -42,6 +42,8 @@ export interface RoleInvokerDeps {
     openspec?: Record<AgentRole, import('../openspec.js').OpenSpecRoleContext>;
     /** Engine hosts isolate sessions/routes by scope and node instead of a role-global file. */
     roleState?: RoleStatePort;
+    /** Durable independent operations must recover uncertain effects explicitly. */
+    propagateInterruptions?: boolean;
     /** `fixer` labels the developer step's events during a correction round on the fixer stance, so a log reader sees who is acting. */
     onAgentEvent?: (role: AgentEventRole, event: AgentEvent) => void;
 }

package/dist/agent-runtime/graph/roles.js

@@ -126,7 +126,7 @@ export function createRoleInvoker(deps) {
     return async (role, step, options, accept) => {
         const timers = { timeoutMs: options.timeoutMs, idleTimeoutMs: options.idleTimeoutMs };
         const structured = options.structured === true;
-        const workflow = deps.openspec?.[role] ? new OpenSpecTools(deps.openspec[role]) : undefined;
+        const workflow = deps.openspec?.[role] ? new OpenSpecTools(deps.openspec[role], step.signal) : undefined;
         const cursor = workflow?.participationCursor() ?? 0;
         const evaluate = (result) => {
             let output, parseError;
@@ -147,6 +147,17 @@ export function createRoleInvoker(deps) {
             return { ok: true, value: accept(output, result.text, result), text: result.text, result };
         };
         try {
+            const skill = workflow ? openSpecSkill(workflow.context) : undefined;
+            if (workflow && (skill === 'openspec-apply-change' || skill === 'openspec-verify-change')) {
+                // Apply/verify read-only prerequisites are host-owned, not a probabilistic
+                // provider action. Deliver the actual pinned skill and CLI outputs; all
+                // artifact, task, verification and review gates still run normally.
+                const loaded = await workflow.execute({ action: 'load_skill' }, 'host');
+                const procedure = skill === 'openspec-verify-change' ? 'verify' : 'apply';
+                const context = `\n## Host-loaded official ${procedure} workflow\nCore executed load_skill, status and instructions apply for this turn. Follow the exact skill and planning context below, read its contextFiles, and carry out the remaining procedure. You may refresh these queries through the scoped tool. A pre-existing unrelated test failure remains a verification failure; report its evidence instead of claiming success.\n` + JSON.stringify(loaded);
+                options = { ...options, prompt: options.prompt + context, ...(options.fallbackPrompt ? { fallbackPrompt: options.fallbackPrompt + context } : {}) };
+                note(role, `Core loaded the pinned OpenSpec ${procedure} skill and current planning context for this turn.`);
+            }
             let result;
             if (options.resumeSessionId && options.fallbackPrompt) {
                 // A correction pass continues the role's own session: the work it did and
@@ -179,7 +190,7 @@ export function createRoleInvoker(deps) {
             // complete original role prompt and existing artifacts, never another role.
             const repair = omittedWorkflow ? openSpecRepairPrompt(workflow.context) : repairInstructions(role, problem);
             note(role, omittedWorkflow
-                ? `The ${role} omitted its required OpenSpec workflow; requesting one correction in the same role before accepting the result.`
+                ? `The ${role} omitted its required OpenSpec workflow (${problem}); requesting one correction in the same role before accepting the result.`
                 : `The ${role} reply was not a valid result (${problem}); asking the same session to resend it.`);
             const repaired = await execute(role, step, result.sessionId ? repair : (options.fallbackPrompt ?? options.prompt) + '\n' + repair, structured, { ...timers, kind: 'repair', resumeSessionId: result.sessionId, outputSchema: options.outputSchema,
                 fallbackPrompt: (options.fallbackPrompt ?? options.prompt) + '\nPrevious response (bounded):\n' + result.text.slice(-32_000) + '\n' + repair,
@@ -192,6 +203,8 @@ export function createRoleInvoker(deps) {
             }
         }
         catch (error) {
+            if (deps.propagateInterruptions && error instanceof AgentExecutionError && ['aborted', 'timeout', 'idle_timeout', 'lease_lost'].includes(error.code))
+                throw error;
             return { ok: false, error: error instanceof Error ? error.message : String(error), ...(error instanceof AgentExecutionError ? { code: error.code } : {}) };
         }
     };

package/dist/agent-runtime/graph/state.d.ts

@@ -43,7 +43,9 @@ export interface VerificationRecord {
         repositoryId: string;
         command: string;
         args: string[];
+        cwd?: string;
         exitCode: number | null;
+        failureSummary?: string[];
         output: string;
     }>;
 }

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

@@ -106,7 +106,7 @@ export declare class OpenSpecTools {
         path?: string;
         content?: string;
         progress?: unknown;
-    }): Promise<unknown>;
+    }, origin?: 'agent' | 'host'): Promise<unknown>;
     private participationEvents;
     participationCursor(): number;
     assertParticipation(after?: number): void;

package/dist/agent-runtime/openspec.js

@@ -211,7 +211,7 @@ export class OpenSpecTools {
     }
     async apply() { await this.status(); return await this.call(['instructions', 'apply', '--change', this.context.change, '--json']); }
     async validate() { await this.status(); return this.call(['validate', this.context.change, '--strict', '--json']); }
-    async execute(input) {
+    async execute(input, origin = 'agent') {
         this.signal?.throwIfAborted();
         const { action } = input;
         const log = path.join(this.context.stateDirectory, `openspec-${this.context.role}.jsonl`);
@@ -225,17 +225,25 @@ export class OpenSpecTools {
             if (hash(content) !== this.context.skillHash)
                 throw new Error('OpenSpec skill changed since admission');
             // Both official apply and verify start with these read-only CLI queries.
-            // Execute them as part of the agent's tool request and return their actual
+            // Execute them as part of the skill request and return their actual
             // outputs, so loading a skill cannot omit its required planning context.
-            const planning = openSpecSkill(this.context) === 'openspec-ff-change' ? undefined : {
-                status: await this.status(),
-                apply: await this.call(['instructions', 'apply', '--change', this.context.change, '--json']),
-            };
+            const fastForward = openSpecSkill(this.context) === 'openspec-ff-change';
+            let planning;
+            if (!fastForward)
+                planning = { status: await this.status(), apply: await this.call(['instructions', 'apply', '--change', this.context.change, '--json']) };
+            else if (existsSync(artifactPath(this.context.root, `openspec/changes/${this.context.change}`))) {
+                const status = await this.status();
+                // Reusing complete artifacts still requires the official task context.
+                // Fresh/incomplete changes continue through the ordinary dependency order.
+                if (status.isComplete)
+                    planning = { status, tasks: await this.call(['instructions', 'tasks', '--change', this.context.change, '--json']) };
+            }
+            const artifact = fastForward ? 'tasks' : 'apply';
             if (planning)
-                prerequisites.push({ action: 'status', via: 'load_skill' }, { action: 'instructions', artifact: 'apply', via: 'load_skill' });
+                prerequisites.push({ action: 'status', via: 'load_skill' }, { action: 'instructions', artifact, via: 'load_skill' });
             result = { name: openSpecSkill(this.context), source: this.context.skillPath, version: OPENSPEC_VERSION, content,
-                ...(planning ? { planning, next: 'The official status and instructions apply queries have executed for this request. Read every planning.apply.contextFiles path, then perform the remaining role skill steps. This is planning context, not proof that implementation or review is complete.' } : {}),
-                ...(openSpecSkill(this.context) !== 'openspec-ff-change' ? { savedProgress: readProgress(this.context) } : {}),
+                ...(planning ? { planning, next: `The official status and instructions ${artifact} queries have executed for this request. Read the returned context and current artifacts, reconcile them with the requested change, and perform the remaining role skill steps. Existing artifacts are not proof that the current request is satisfied.` } : {}),
+                ...(!fastForward ? { savedProgress: readProgress(this.context) } : {}),
             };
         }
         else if (action === 'new') {
@@ -290,7 +298,7 @@ export class OpenSpecTools {
         this.signal?.throwIfAborted();
         const timestamp = new Date().toISOString();
         appendFileSync(log, [{ action, artifact: input.artifact, path: input.path }, ...prerequisites]
-            .map(event => JSON.stringify({ ...event, timestamp }) + '\n').join(''), { mode: 0o600 });
+            .map(event => JSON.stringify({ ...event, timestamp, ...(origin === 'host' ? { origin } : {}) }) + '\n').join(''), { mode: 0o600 });
         return result;
     }
     participationEvents() {