specrails-core 6.3.0 → 6.5.0

package/dist/agent-runtime/config.js

@@ -60,9 +60,66 @@ function score(value, field, floor) {
         fail(field, `must be at least ${floor}, Core's own review gate`);
     return value;
 }
+/** `verification` and `setup` share one command shape and one set of rules, including the credential refusal. */
+function validateCommandList(value, list) {
+    if (!Array.isArray(value))
+        fail(list, 'expected an array of verification commands');
+    return value.map((item, i) => {
+        const field = `${list}[${i}]`, command = object(item, field);
+        keys(command, ['repositoryId', 'command', 'args', 'cwd', 'env', 'timeoutMs', 'key', 'label', 'policy'], field);
+        if (command.key !== undefined)
+            identifier(command.key, `${field}.key`);
+        if (command.label !== undefined && string(command.label, `${field}.label`).length > 256)
+            fail(`${field}.label`, 'maximum 256 characters');
+        if (command.policy !== undefined) {
+            const policy = object(command.policy, `${field}.policy`);
+            keys(policy, ['reuse', 'inputs', 'deterministic', 'readOnly', 'toolchainInputs', 'independentGroup', 'resources'], `${field}.policy`);
+            if (policy.reuse !== undefined)
+                choices(policy.reuse, ['never', 'snapshot-local'], `${field}.policy.reuse`);
+            for (const key of ['deterministic', 'readOnly'])
+                if (policy[key] !== undefined)
+                    boolean(policy[key], `${field}.policy.${key}`);
+            if (policy.independentGroup !== undefined)
+                identifier(policy.independentGroup, `${field}.policy.independentGroup`);
+            for (const key of ['inputs', 'toolchainInputs', 'resources']) {
+                const values = policy[key];
+                if (values === undefined)
+                    continue;
+                if (!Array.isArray(values) || values.length > 256)
+                    fail(`${field}.policy.${key}`, 'expected at most 256 entries');
+                for (const value of values)
+                    if (string(value, `${field}.policy.${key}`).length > 4096)
+                        fail(`${field}.policy.${key}`, 'entry exceeds 4096 characters');
+            }
+        }
+        identifier(command.repositoryId, `${field}.repositoryId`);
+        string(command.command, `${field}.command`);
+        if (!Array.isArray(command.args) || !command.args.every(arg => typeof arg === 'string' && !arg.includes('\0')))
+            fail(`${field}.args`, 'expected a string array');
+        if (command.cwd !== undefined)
+            string(command.cwd, `${field}.cwd`);
+        if (command.timeoutMs !== undefined)
+            positive(command.timeoutMs, `${field}.timeoutMs`);
+        if (command.env !== undefined) {
+            const env = object(command.env, `${field}.env`);
+            for (const [key, value] of Object.entries(env)) {
+                if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || typeof value !== 'string' || value.includes('\0'))
+                    fail(`${field}.env`, 'expected environment names and string values');
+                if (/(?:token|secret|password|api_?key|credential)/i.test(key))
+                    fail(`${field}.env.${key}`, 'credentials must be inherited from the process environment, never saved');
+            }
+        }
+        return structuredClone(command);
+    });
+}
+function uniqueKeys(commands, list) {
+    const checkKeys = commands.flatMap(check => check.key ? [check.key] : []);
+    if (new Set(checkKeys).size !== checkKeys.length)
+        fail(list, 'duplicate check key');
+}
 export function validateRuntimeConfig(input, options = {}) {
     const config = object(input, '$');
-    keys(config, ['schemaVersion', 'enabled', 'providers', 'agents', 'roles', 'fixer', 'limits', 'verification', 'approvalBeforeArchive', 'review', 'architect', 'rolePrompts', 'efficiency', 'guardrails'], '$');
+    keys(config, ['schemaVersion', 'enabled', 'providers', 'agents', 'roles', 'fixer', 'limits', 'verification', 'setup', 'approvalBeforeArchive', 'review', 'architect', 'rolePrompts', 'efficiency', 'guardrails'], '$');
     if (config.schemaVersion !== 1)
         fail('schemaVersion', 'expected 1');
     if (config.enabled !== undefined && typeof config.enabled !== 'boolean')
@@ -176,58 +233,15 @@ export function validateRuntimeConfig(input, options = {}) {
         for (const [key, value] of Object.entries(limits))
             positive(value, `limits.${key}`, key !== 'maxCostUsd');
     }
-    if (!Array.isArray(config.verification))
-        fail('verification', 'expected an array of verification commands');
-    const verification = config.verification.map((item, i) => {
-        const field = `verification[${i}]`, command = object(item, field);
-        keys(command, ['repositoryId', 'command', 'args', 'cwd', 'env', 'timeoutMs', 'key', 'label', 'policy'], field);
-        if (command.key !== undefined)
-            identifier(command.key, `${field}.key`);
-        if (command.label !== undefined && string(command.label, `${field}.label`).length > 256)
-            fail(`${field}.label`, 'maximum 256 characters');
-        if (command.policy !== undefined) {
-            const policy = object(command.policy, `${field}.policy`);
-            keys(policy, ['reuse', 'inputs', 'deterministic', 'readOnly', 'toolchainInputs', 'independentGroup', 'resources'], `${field}.policy`);
-            if (policy.reuse !== undefined)
-                choices(policy.reuse, ['never', 'snapshot-local'], `${field}.policy.reuse`);
-            for (const key of ['deterministic', 'readOnly'])
-                if (policy[key] !== undefined)
-                    boolean(policy[key], `${field}.policy.${key}`);
-            if (policy.independentGroup !== undefined)
-                identifier(policy.independentGroup, `${field}.policy.independentGroup`);
-            for (const key of ['inputs', 'toolchainInputs', 'resources']) {
-                const values = policy[key];
-                if (values === undefined)
-                    continue;
-                if (!Array.isArray(values) || values.length > 256)
-                    fail(`${field}.policy.${key}`, 'expected at most 256 entries');
-                for (const value of values)
-                    if (string(value, `${field}.policy.${key}`).length > 4096)
-                        fail(`${field}.policy.${key}`, 'entry exceeds 4096 characters');
-            }
-        }
-        identifier(command.repositoryId, `${field}.repositoryId`);
-        string(command.command, `${field}.command`);
-        if (!Array.isArray(command.args) || !command.args.every(arg => typeof arg === 'string' && !arg.includes('\0')))
-            fail(`${field}.args`, 'expected a string array');
-        if (command.cwd !== undefined)
-            string(command.cwd, `${field}.cwd`);
-        if (command.timeoutMs !== undefined)
-            positive(command.timeoutMs, `${field}.timeoutMs`);
-        if (command.env !== undefined) {
-            const env = object(command.env, `${field}.env`);
-            for (const [key, value] of Object.entries(env)) {
-                if (!/^[A-Za-z_][A-Za-z0-9_]*$/.test(key) || typeof value !== 'string' || value.includes('\0'))
-                    fail(`${field}.env`, 'expected environment names and string values');
-                if (/(?:token|secret|password|api_?key|credential)/i.test(key))
-                    fail(`${field}.env.${key}`, 'credentials must be inherited from the process environment, never saved');
-            }
-        }
-        return structuredClone(command);
-    });
-    const checkKeys = verification.flatMap(check => check.key ? [check.key] : []);
-    if (new Set(checkKeys).size !== checkKeys.length)
-        fail('verification', 'duplicate check key');
+    const verification = validateCommandList(config.verification, 'verification');
+    const setup = config.setup === undefined ? undefined : validateCommandList(config.setup, 'setup');
+    uniqueKeys(verification, 'verification');
+    if (setup) {
+        uniqueKeys(setup, 'setup');
+        // A key names one check in receipts and host UIs: it cannot be both a setup command and a verification check.
+        if (setup.some(command => command.key && verification.some(check => check.key === command.key)))
+            fail('setup', 'duplicate check key shared with verification');
+    }
     if (config.efficiency !== undefined) {
         const policy = object(config.efficiency, 'efficiency');
         keys(policy, ['schemaVersion', 'contextMode', 'reviewMode', 'planning', 'acceptDeveloperChecks', 'verification'], 'efficiency');
@@ -295,6 +309,7 @@ export function validateRuntimeConfig(input, options = {}) {
         }
     }
     return { schemaVersion: 1, enabled: true, providers, agents, verification,
+        ...(setup === undefined ? {} : { setup }),
         ...(roles === undefined ? {} : { roles }),
         ...(config.efficiency === undefined ? {} : { efficiency: structuredClone(config.efficiency) }),
         ...(rolePrompts === undefined ? {} : { rolePrompts }),

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

@@ -85,7 +85,7 @@ export function compileWorkflowDefinition(definition, registry, execution, optio
                         if (!exit)
                             throw new EngineError('component_exit_missing', `Component ${nodePath} did not produce an exit`);
                         childEvidence = { $candidate: completed.$candidate, $verified: completed.$verified };
-                        result = { outcome: exit.outcome, status: exit.status, output: { outputs: completed.$outputs, completion: { ...exit.completion } },
+                        result = { outcome: exit.outcome, status: exit.status, output: { outputs: completed.$outputs, completion: completionOutput(exit.completion) },
                             usage: completed.$usage, completion: exit.completion,
                             ...(exit.error ? { error: exit.error } : {}) };
                     }
@@ -156,7 +156,7 @@ export function compileWorkflowDefinition(definition, registry, execution, optio
                         throw new EngineError('component_exit_missing', 'Map body did not produce an exit');
                     return { $branches: { [id]: { total: task.total, visitId: task.frame.visitId, transition: task.frame.transition,
                                 results: [{ id: task.frame.visitId + ':' + task.index, transition: task.frame.transition, attempt: task.frame.attempt, ordinal: task.index,
-                                        index: task.index, outcome: completed.$exit.completion.ok ? 'next' : 'failed', output: boundPieceOutput({ outputs: completed.$outputs, completion: { ...completed.$exit.completion } }) }] } } };
+                                        index: task.index, outcome: completed.$exit.completion.ok ? 'next' : 'failed', output: boundPieceOutput({ outputs: completed.$outputs, completion: completionOutput(completed.$exit.completion) }) }] } } };
                 }, { subgraphs: [child] });
             }
         }
@@ -236,6 +236,14 @@ function componentInput(state, frame, mapping, body) {
     input.$usage = state.$usage;
     return input;
 }
+/** A completion as committed output: the optional blocker is present only when set, so the value stays plain JSON. */
+function completionOutput(completion) {
+    const { blocker, ...rest } = completion;
+    if (!blocker)
+        return { ...rest };
+    const { evidenceId, ...fields } = blocker;
+    return { ...rest, blocker: { ...fields, ...(evidenceId === undefined ? {} : { evidenceId }) } };
+}
 function implicitCompletion(result, state) {
     const candidate = result.candidate ?? state.$candidate;
     const verified = Object.hasOwn(result, 'verified') ? result.verified : state.$verified;

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

@@ -97,10 +97,26 @@ export interface ReceiptEvidence {
     scope: 'full' | 'scoped';
     evidence: JsonValue;
 }
+/**
+ * A failure only the host can repair, reported structurally so hosts render the
+ * action instead of parsing prose. `cwd` is relative to the checkout. `scope`
+ * is reserved for a correction role that diagnoses the cause outside the change.
+ */
+export interface HostBlocker {
+    kind: 'network' | 'credential' | 'environment-variable' | 'toolchain' | 'setup' | 'environment' | 'scope';
+    reason: string;
+    command: string;
+    args: string[];
+    cwd: string;
+    requiredAction: string;
+    evidenceId?: string;
+}
 export interface EngineCompletion {
     ok: boolean;
     reasons: string[];
     verified: boolean;
+    /** Copied by an `end` piece from the node named in `blockerFrom`, when that output carries one. */
+    blocker?: HostBlocker;
 }
 export interface EngineAnswer {
     id: string;

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

@@ -1,6 +1,14 @@
 import { EngineError } from '../contracts.js';
 import { parseExpression } from '../expressions.js';
+import { boundedBlocker } from '../../verification-repair.js';
 import { answerEntry, idSchema, paramsSchema, positiveInteger, stringSchema, text } from './shared.js';
+/** A host blocker committed by `verify` (`output.blocker`) or by a correction role's structured JSON (`output.structured.blocker`). */
+function committedBlocker(output) {
+    if (!output || typeof output !== 'object' || Array.isArray(output))
+        return undefined;
+    const structured = output.structured;
+    return boundedBlocker(output.blocker) ?? (structured && typeof structured === 'object' && !Array.isArray(structured) ? boundedBlocker(structured.blocker) : undefined);
+}
 export function controlPieces(bindings) {
     const pieces = [{
             descriptor: { kind: 'condition', paramsSchema: paramsSchema({ expr: { ...stringSchema, minLength: 1, maxLength: 4096 } }, ['expr']), outcomes: ['true', 'false'], effect: 'read', requiresAI: false },
@@ -14,14 +22,15 @@ export function controlPieces(bindings) {
                 }
             },
         }, {
-            descriptor: { kind: 'end', paramsSchema: paramsSchema({ outcome: { enum: ['success', 'failure'] }, requiresVerified: { type: 'boolean' }, reason: stringSchema, exit: idSchema }, ['outcome']), outcomes: [], effect: 'read', requiresAI: false },
+            descriptor: { kind: 'end', paramsSchema: paramsSchema({ outcome: { enum: ['success', 'failure'] }, requiresVerified: { type: 'boolean' }, reason: stringSchema, exit: idSchema, blockerFrom: idSchema }, ['outcome']), outcomes: [], effect: 'read', requiresAI: false },
             async execute(params, context) {
                 const { candidate, verified } = bindings().executionSnapshot(context);
                 const current = verified !== null && candidate !== null && verified.candidateHash === candidate.hash;
                 const reasons = typeof params.reason === 'string' && params.reason ? [params.reason] : [];
                 if (params.requiresVerified && !current)
                     reasons.push('unverified');
-                return { outcome: text(params.outcome), completion: { ok: params.outcome === 'success' && !(params.requiresVerified && !current), verified: current, reasons } };
+                const blocker = typeof params.blockerFrom === 'string' ? committedBlocker(context.state.$outputs[params.blockerFrom]) : undefined;
+                return { outcome: text(params.outcome), completion: { ok: params.outcome === 'success' && !(params.requiresVerified && !current), verified: current, reasons, ...(blocker ? { blocker } : {}) } };
             },
         }];
     for (const kind of ['approval', 'question', 'gate']) {

package/dist/agent-runtime/engine/pieces/role-turn.d.ts

@@ -1,7 +1,12 @@
+import { type InstallOutcome } from '../../compact/environment.js';
 import { type JsonObject, type Piece, type PieceExecutionContext, type PieceResult } from '../contracts.js';
 import type { PieceDependencies, PieceDependencyProvider } from './ports.js';
 export declare function roleTurnPiece(bindings: PieceDependencyProvider): Piece;
 /** One invocation path for configured roles, including routing and exactly one repair. */
 export declare function executeRoleTurn(deps: PieceDependencies, params: JsonObject, context: PieceExecutionContext, options?: {
     normalizeStructuredOutput?: (output: Record<string, unknown> | undefined, text: string) => Record<string, unknown> | undefined;
+    /** Set on the single rerun after the host repaired an environment blocker the agent reported. */
+    environmentRetry?: {
+        installs: InstallOutcome[];
+    };
 }): Promise<PieceResult>;

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

@@ -1,16 +1,20 @@
 import { contentDigest } from '../canonical-json.js';
 import { advisoryMemory } from './project-memory.js';
 import { Ajv2020 } from 'ajv/dist/2020.js';
+import { withScopeDefault } from '../../change-scope.js';
 import { resolveRoleDescriptor } from '../../config.js';
 import { AgentExecutionError } from '../../executor-types.js';
 import { createRoleInvoker } from '../../graph/roles.js';
+import { admitVerificationProposals } from '../../verification-proposals.js';
+import { guardrailEnabled } from '../../guardrails.js';
+import { installEnvironment, prepareEnvironment } from '../../compact/environment.js';
 import { roleInstructions } from '../../prompts.js';
 import { EngineError } from '../contracts.js';
 import { boundedText, historyEntry, idSchema, json, paramsSchema, invocationTimers, stringSchema, text } from './shared.js';
 const ajv = new Ajv2020({ allErrors: true, strict: true, validateFormats: false, ownProperties: true });
 export function roleTurnPiece(bindings) {
     return {
-        descriptor: { kind: 'role-turn', paramsSchema: paramsSchema({ ...invocationTimers, roleId: idSchema, prompt: { ...stringSchema, minLength: 1 }, structuredOutput: { type: 'object' }, sessionContinuity: { enum: ['run', 'none'] } }, ['roleId', 'prompt']), outcomes: ['next', 'invalid', 'failed'], effect: 'derived', requiresAI: true, storeAccess: 'write' },
+        descriptor: { kind: 'role-turn', paramsSchema: paramsSchema({ ...invocationTimers, roleId: idSchema, prompt: { ...stringSchema, minLength: 1 }, structuredOutput: { type: 'object' }, sessionContinuity: { enum: ['run', 'none'] }, verificationProposalsFrom: { type: 'string', minLength: 1, maxLength: 128 } }, ['roleId', 'prompt']), outcomes: ['next', 'invalid', 'failed'], effect: 'derived', requiresAI: true, storeAccess: 'write' },
         getOutcomes: params => params.structuredOutput ? ['next', 'invalid', 'failed'] : ['next', 'failed'],
         getEffect: (params, roles) => {
             const role = roles[text(params.roleId)];
@@ -24,6 +28,14 @@ export function roleTurnPiece(bindings) {
 /** One invocation path for configured roles, including routing and exactly one repair. */
 export async function executeRoleTurn(deps, params, context, options = {}) {
     const roleId = text(params.roleId), descriptor = resolveRoleDescriptor(deps.config, roleId);
+    // Agents run sandboxed and cannot install what the repository needs (Codex
+    // cannot even write the Playwright browser cache): the host prepares it
+    // before any writer turn and says so in the task.
+    const hostRepairs = descriptor.access === 'write' && guardrailEnabled(deps.config.guardrails, 'environment-repair');
+    const note = (line) => context.progress({ type: 'verification-output', payload: { text: line } });
+    const environment = options.environmentRetry
+        ? environmentNote(options.environmentRetry.installs, 'retry')
+        : hostRepairs ? environmentNote(prepareEnvironment(deps.context.repositories.map(repository => repository.path), environmentIo(deps, note)), 'prepared') : '';
     const schema = params.structuredOutput;
     const validate = schema ? ajv.compile(schema) : undefined;
     const roleState = deps.roleState(context);
@@ -44,8 +56,9 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
     });
     const priorNote = !previous && descriptor.access === 'read' && saved?.session && typeof saved.notes?.value.text === 'string'
         ? saved.notes.value.text.slice(0, 4000) : '';
-    const task = text(params.prompt) + (priorNote ? '\n\n## Prior project review note\nTreat this bounded note as prior evidence to check against the current task; frozen requirements remain authoritative.\n' + JSON.stringify(priorNote) : '');
-    const full = roleInstructions(descriptor, deps.context, openspec?.[roleId]?.change, { definition: descriptor.prompt }) + '\n## Current workflow task\n' + task;
+    const task = text(params.prompt) + environment + (priorNote ? '\n\n## Prior project review note\nTreat this bounded note as prior evidence to check against the current task; frozen requirements remain authoritative.\n' + JSON.stringify(priorNote) : '');
+    const verification = descriptor.access === 'write' ? hostVerificationPlan(deps, context, params) : undefined;
+    const full = roleInstructions(descriptor, deps.context, openspec?.[roleId]?.change, { definition: descriptor.prompt, verification }) + '\n## Current workflow task\n' + task;
     const result = await invoke(roleId, deps.stepContext(context), { prompt: previous ? task : full, ...(previous ? { resumeSessionId: previous, fallbackPrompt: full } : {}),
         structured: schema !== undefined, lenient: options.normalizeStructuredOutput !== undefined, outputSchema: schema, timeoutMs: params.timeoutMs, idleTimeoutMs: params.idleTimeoutMs }, (output, responseText) => {
         const normalized = options.normalizeStructuredOutput ? options.normalizeStructuredOutput(output, responseText) : output;
@@ -58,6 +71,19 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
             throw new AgentExecutionError(result.error, result.code);
         return { outcome: schema ? 'invalid' : 'failed', status: 'failed', output: { error: boundedText(result.error) }, error: { code: schema ? 'invalid_role_output' : 'role_failed', message: result.error } };
     }
+    // A writer that still hit a missing tool reports a structured blocker. When
+    // the host can install it, it does so and reruns the turn once instead of
+    // ending the run on something it can fix itself.
+    const blocker = hostRepairs && !options.environmentRetry ? repairableBlocker(result.value) : undefined;
+    if (blocker) {
+        const roots = deps.context.repositories.map(repository => repository.path);
+        const io = environmentIo(deps, note);
+        const installs = [...installEnvironment(roots, { ...io, failureOutput: blocker }), ...prepareEnvironment(roots, io)];
+        if (installs.some(install => install.ok)) {
+            note('[environment] The agent reported a missing dependency or tool; the host installed it and runs the turn again.');
+            return executeRoleTurn(deps, params, context, { ...options, environmentRetry: { installs } });
+        }
+    }
     const currentState = roleState.read(), session = currentState.sessions[roleId];
     const finalIdentity = { ...memoryIdentity, tier: currentState.routes[roleId]?.tier ?? 'base' }, finalKey = contentDigest(finalIdentity);
     await advisoryMemory(context, async () => {
@@ -71,3 +97,43 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
     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 } } : {}) };
 }
+const REPAIRABLE_BLOCKERS = new Set(['toolchain', 'setup', 'environment']);
+/** The text of a structured `blocker` the host may be able to install away; undefined for other kinds (credentials, network, scope). */
+function repairableBlocker(value) {
+    const blocker = value?.blocker;
+    if (!blocker || typeof blocker !== 'object' || !REPAIRABLE_BLOCKERS.has(String(blocker.kind)))
+        return undefined;
+    return ['evidence', 'reason', 'command', 'requiredAction'].map(field => typeof blocker[field] === 'string' ? blocker[field] : '').join('\n').slice(0, 8_000);
+}
+function environmentIo(deps, note) {
+    return { lockfileRepair: guardrailEnabled(deps.config.guardrails, 'lockfile-repair'),
+        onEvent: (event) => note(event.kind === 'text' ? event.text ?? '' : `[environment] ${event.tool ?? ''} ${event.detail ?? ''}`.trim()) };
+}
+/** What the host installed (or could not) for this turn, as task context; empty when nothing was needed. */
+function environmentNote(installs, when) {
+    if (!installs.length)
+        return '';
+    const done = installs.filter(install => install.ok).map(install => install.installs ?? `${install.ecosystem} dependencies`);
+    const failed = installs.filter(install => !install.ok).map(install => install.detail);
+    return '\n\n## Host environment\n' + (when === 'retry' ? 'Your previous turn reported an environment blocker. ' : '')
+        + (done.length ? `The host installed ${done.join('; ')} for this workspace${when === 'retry' ? ': continue the remaining work and rerun the checks that were blocked.' : ' before this turn.'} ` : '')
+        + (failed.length ? `It could not install: ${failed.join('; ')}. ` : '')
+        + 'Do not install these yourself; if something is still missing, return the structured blocker.';
+}
+/** The complete plan the host will run for the repositories in scope: configured checks plus, when `verificationProposalsFrom`
+ * names a committed output, the proposals the verify piece admits (see admitVerificationProposals). */
+function hostVerificationPlan(deps, context, params) {
+    const inScope = new Set(deps.context.repositories.map(repository => repository.id));
+    const commands = deps.config.verification.filter(command => inScope.has(command.repositoryId)).map(command => withScopeDefault(deps.context, command));
+    if (typeof params.verificationProposalsFrom === 'string') {
+        const source = context.state.$outputs[params.verificationProposalsFrom];
+        const proposals = (Array.isArray(source?.structured?.verification) ? source.structured.verification.slice(0, 20) : []).filter((proposal) => {
+            if (!proposal || typeof proposal !== 'object' || Array.isArray(proposal))
+                return false;
+            const raw = proposal;
+            return typeof raw.repositoryId === 'string' && inScope.has(raw.repositoryId) && typeof raw.command === 'string' && Array.isArray(raw.args) && raw.args.every(arg => typeof arg === 'string');
+        });
+        commands.push(...admitVerificationProposals(deps.context, commands, proposals, raw => withScopeDefault(deps.context, { repositoryId: raw.repositoryId, command: raw.command, args: raw.args, ...(typeof raw.cwd === 'string' ? { cwd: raw.cwd } : {}) })));
+    }
+    return commands;
+}

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

@@ -1,7 +1,14 @@
-import { type VerificationReceipt } from '../../../pipeline/pipeline-state.js';
-import type { Piece, PieceExecutionContext, ReceiptEvidence } from '../contracts.js';
+import { type VerificationCommand, type VerificationReceipt } from '../../../pipeline/pipeline-state.js';
+import type { JsonObject, Piece, PieceExecutionContext, ReceiptEvidence } from '../contracts.js';
 import type { PieceDependencies, PieceDependencyProvider } from './ports.js';
-export declare const verificationCommandSchema: import("../contracts.js").JsonObject;
+export declare const verificationCommandSchema: JsonObject;
 export declare function receiptEvidence(receipt: VerificationReceipt): ReceiptEvidence;
 export declare function verificationDeadline(deps: PieceDependencies, context: PieceExecutionContext): number | undefined;
+/**
+ * The complete host plan for a `verify` node: configured checks (or the inline
+ * list) plus the proposals of the node named in `additionalCommandsFrom` for
+ * repositories without a configured check. Role turns show write roles this
+ * same list, so the developer never passes a check the host does not run.
+ */
+export declare function resolveVerificationPlan(deps: PieceDependencies, context: PieceExecutionContext, params: JsonObject): VerificationCommand[];
 export declare function verifyPiece(bindings: PieceDependencyProvider): Piece;

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

@@ -1,3 +1,4 @@
+import { admitVerificationProposals } from '../../verification-proposals.js';
 import { stripVTControlCharacters } from 'node:util';
 import { contentDigest } from '../canonical-json.js';
 import { advisoryMemory } from './project-memory.js';
@@ -5,6 +6,9 @@ import { executeVerification, validateVerificationRequest } from '../../../pipel
 import { withScopeDefault } from '../../change-scope.js';
 import { verificationDiagnosticPriority, verificationFailureSummary } from '../../verification-diagnostics.js';
 import { boundedText, json, paramsSchema, positiveInteger } from './shared.js';
+import { isEnvironmentFailure } from '../../compact/environment.js';
+import { guardrailEnabled } from '../../guardrails.js';
+import { checkoutRelative, preconditionBlock, repairEnvironment } from '../../verification-repair.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. */
@@ -75,50 +79,115 @@ export function verificationDeadline(deps, context) {
     const budget = deps.stepContext(context).remainingBudget();
     return budget.maxDurationMs === undefined ? undefined : Date.now() + Math.max(0, budget.maxDurationMs);
 }
+const VERIFY_OUTCOMES = ['pass', 'fail', 'failed'];
+const verificationCommandList = { type: 'array', maxItems: 100, items: verificationCommandSchema };
+/**
+ * The complete host plan for a `verify` node: configured checks (or the inline
+ * list) plus the proposals of the node named in `additionalCommandsFrom` for
+ * repositories without a configured check. Role turns show write roles this
+ * same list, so the developer never passes a check the host does not run.
+ */
+export function resolveVerificationPlan(deps, context, params) {
+    const configured = params.commands === undefined || params.commands === 'configured' ? deps.config.verification : params.commands;
+    const commands = configured.map(command => withScopeDefault(deps.context, command));
+    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');
+            if (!deps.context.repositories.some(repository => repository.id === proposal.repositoryId))
+                throw new Error('Unknown verification repository');
+        }
+        commands.push(...admitVerificationProposals(deps.context, commands, proposals, raw => withScopeDefault(deps.context, raw)));
+    }
+    return commands;
+}
+/** A setup command that exited non-zero: the host declared it, so only the host can fix or remove it. */
+function setupBlocker(deps, command) {
+    const cwd = checkoutRelative(deps.context, command.cwd);
+    return { kind: 'setup', reason: `the setup command \`${[command.command, ...command.args].join(' ')}\` failed in ${cwd} (exit ${command.exitCode})`, command: command.command, args: command.args, cwd,
+        requiredAction: `Fix or remove the setup command \`${[command.command, ...command.args].join(' ')}\` in the runtime configuration, then retry the run.`, ...(command.evidenceId ? { evidenceId: command.evidenceId } : {}) };
+}
 export function verifyPiece(bindings) {
     return {
-        descriptor: { kind: 'verify', paramsSchema: paramsSchema({ commands: { oneOf: [{ const: 'configured' }, { type: 'array', maxItems: 100, items: verificationCommandSchema }] },
-                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' },
+        descriptor: { kind: 'verify', paramsSchema: paramsSchema({ commands: { oneOf: [{ const: 'configured' }, verificationCommandList] },
+                additionalCommandsFrom: { type: 'string', minLength: 1, maxLength: 128 }, unverified: { type: 'boolean' }, maxConcurrency: { type: 'integer', minimum: 1, maximum: 4 },
+                setup: { oneOf: [{ const: 'configured' }, verificationCommandList] }, hostBlockers: { type: 'boolean' } }, ['commands']), outcomes: [...VERIFY_OUTCOMES, 'blocked'], effect: 'write', requiresAI: false, storeAccess: 'write' },
+        // `blocked` is opt-in so definitions published before host blockers keep their exact `ends`.
+        getOutcomes: params => params.hostBlockers === true ? [...VERIFY_OUTCOMES, 'blocked'] : VERIFY_OUTCOMES,
         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 commands = resolveVerificationPlan(deps, context, params);
             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);
+            // Setup is validated before anything runs: a setup entry escaping the workspace fails exactly like a check would.
+            const setupCommands = (params.setup === 'configured' ? deps.config.setup ?? [] : params.setup ?? [])
+                .map(({ policy: _policy, ...command }) => withScopeDefault(deps.context, command));
+            const setupRequest = { kind: 'scoped', commands: setupCommands };
+            if (setupCommands.length)
+                validateVerificationRequest(deps.context, setupRequest);
+            const progress = (text) => context.progress({ type: 'verification-output', payload: { text } });
+            const concurrency = params.maxConcurrency ?? deps.config.efficiency?.verification?.maxConcurrency;
+            const run = (plan, maxConcurrency) => executeVerification(deps.context, plan, deps.verification(context), progress, context.signal, {
+                deadline: verificationDeadline(deps, context), maxConcurrency, idleTimeoutMs: deps.config.guardrails?.['verify-idle-timeout'] === false ? 0 : undefined,
+                onEvidence: async (kind, payload) => context.progress({ type: 'runtime-efficiency-event', payload: { kind, ...payload } }),
+            });
             const identity = { candidateHash: deps.executionSnapshot(context).candidate?.hash ?? null, scopeId: context.frame.scope.id,
                 repositories: deps.context.repositories.map(repository => ({ id: repository.id, path: repository.path })),
-                planHash: contentDigest(json(request)), concurrency: params.maxConcurrency ?? deps.config.efficiency?.verification?.maxConcurrency ?? 1 };
+                planHash: contentDigest(json(request)), concurrency: concurrency ?? 1 };
+            const infrastructureFailure = (receipt) => receipt.commands.some(command => command.exitCode === -1 && command.outcome !== 'cancelled');
+            const executionError = (receipt) => ({ status: 'failed', error: { code: 'verification_execution_error', message: receipt.reason ?? 'A verification command could not complete' } });
+            const blocked = (blocker, output) => ({
+                outcome: params.hostBlockers === true ? 'blocked' : 'fail',
+                ...(params.hostBlockers === true ? { status: 'blocked', error: { code: 'verification_host_precondition', message: `${blocker.reason} ${blocker.requiredAction}` } } : {}),
+                output: { ...output, valid: false, candidateHash: identity.candidateHash, blocker: json(blocker) }, verified: null,
+            });
+            // Setup never installs a verified candidate or feeds the no-progress
+            // fingerprint: it prepares the workspace, it does not judge the change.
+            let setup;
+            if (setupCommands.length) {
+                const receipt = await run(setupRequest, 1);
+                setup = verificationDiagnostics(receipt);
+                if (infrastructureFailure(receipt))
+                    return { outcome: 'failed', ...executionError(receipt), output: { valid: false, candidateHash: identity.candidateHash, reason: receipt.reason ?? 'A setup command could not complete', setup }, verified: null };
+                const failed = receipt.commands.find(command => command.exitCode !== 0);
+                if (failed)
+                    return blocked(setupBlocker(deps, failed), { reason: 'A setup command failed', setup });
+            }
             const memoryKey = contentDigest(identity);
             const known = await advisoryMemory(context, () => deps.memory(context).get(['verification', 'known-commands'], memoryKey));
-            const receipt = await executeVerification(deps.context, request, deps.verification(context), output => context.progress({ type: 'verification-output', payload: { text: output } }), context.signal, {
-                deadline: verificationDeadline(deps, context), maxConcurrency: params.maxConcurrency ?? deps.config.efficiency?.verification?.maxConcurrency,
-                idleTimeoutMs: deps.config.guardrails?.['verify-idle-timeout'] === false ? 0 : undefined,
-                onEvidence: async (kind, payload) => context.progress({ type: 'runtime-efficiency-event', payload: { kind, ...payload } }),
-            });
+            let receipt = await run(request, concurrency);
+            let blocker = receipt.valid ? undefined : preconditionBlock(deps.context, receipt);
+            // A missing toolchain or dependency (exit 127, "command not found", a
+            // Playwright browser build) is the host's to fix, not the fixer's: a
+            // fresh worktree has no node_modules whatever wrote the code. Install
+            // once where the failing command runs and verify again; only the second
+            // receipt becomes feedback.
+            let environmentRepair;
+            if (!blocker && !receipt.valid && guardrailEnabled(deps.config.guardrails, 'environment-repair') && receipt.commands.some(command => isEnvironmentFailure(command.exitCode, command.output))) {
+                const repair = repairEnvironment(deps.context, receipt, deps.config.guardrails, progress);
+                environmentRepair = { attempted: true, reverified: false, installs: repair.installs.map(install => ({ command: install.command, args: install.args, root: checkoutRelative(deps.context, install.root), ok: install.ok, detail: boundedText(install.detail, 1_000) })) };
+                if (repair.refused)
+                    blocker = repair.refused;
+                else if (repair.installs.some(install => install.ok)) {
+                    progress('[environment] Verification failed on the environment (missing dependencies or tools); the host installed them and is verifying again.');
+                    receipt = await run(request, concurrency);
+                    environmentRepair.reverified = true;
+                    blocker = receipt.valid ? undefined : preconditionBlock(deps.context, receipt);
+                }
+            }
             await advisoryMemory(context, () => deps.memory(context).put(['verification', 'known-commands'], memoryKey, {
                 ...identity, observations: Math.min(1_000_000, typeof known?.value.observations === 'number' ? known.value.observations + 1 : 1),
                 lastAttemptId: context.frame.attemptId, lastReceiptId: receipt.id, lastValid: receipt.valid,
                 commands: receipt.commands.map(command => ({ repositoryId: command.repositoryId, command: command.command, exitCode: command.exitCode })),
             }));
-            const infrastructure = receipt.commands.some(command => command.exitCode === -1 && command.outcome !== 'cancelled');
+            const infrastructure = infrastructureFailure(receipt);
             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,
@@ -127,8 +196,14 @@ export function verifyPiece(bindings) {
             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: 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) },
+            const 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' } : {}),
+                ...(setup ? { setup } : {}), ...(environmentRepair ? { environmentRepair } : {}), ...verificationDiagnostics(receipt) };
+            const vars = { [progressKey]: { fingerprint, count } };
+            // Without the opt-in outcome a blocker still travels in the output, and the no-progress stop keeps bounding the loop.
+            if (blocker && (params.hostBlockers === true || !stalled))
+                return { ...blocked(blocker, output), vars, receipt: receiptEvidence(receipt) };
+            return { outcome: stalled ? 'failed' : outcome, vars, ...(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 ? executionError(receipt) : {}),
+                output: { ...output, ...(blocker ? { blocker: json(blocker) } : {}) },
                 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/executor-types.d.ts

@@ -109,6 +109,8 @@ export interface RuntimeConfig {
         idleTimeoutMs?: number;
     };
     verification: VerificationCommand[];
+    /** Idempotent commands the `verify` piece runs sequentially before each verification plan (same shape as `verification`; `policy` is ignored). */
+    setup?: VerificationCommand[];
     approvalBeforeArchive?: boolean;
     /** Review gate thresholds (0–100); unset fields keep Core's defaults. */
     review?: {