specrails-core 6.3.0 → 6.4.0

package/dist/agent-runtime/cli.js

@@ -158,7 +158,7 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
         emit({ type: 'runtime-api', apiVersion: RUNTIME_API_VERSION, coreVersion: CORE_PACKAGE_VERSION, runtimeIdentity: coreRuntimeIdentity(), workflowVersions: [CORE_WORKFLOW_VERSION],
             engineVersion: 2, engines: RUNTIME_ENGINES, nodeKindsVersion: NODE_KINDS_VERSION, nodeKinds: validationPieceRegistry().kinds(),
             capabilities: { openRoles: 1, scopedRecovery: 1, efficientRoleExecution: 1, reproducibleVerification: 1, implementationEfficiencyMetrics: 1, compactAgentLoop: 1, configurableGuardrails: 1, compactOutputBudget: 1, roleThinkingControl: 1, repositoryScope: 1,
-                engineV2: 1, workflowAgentSteps: 1, implementationSteps: 1, workflowDefinitions: 1, fanOut: 1, fork: 1, forkIdempotency: 1, steeringInbox: 1 }, guardrails: GUARDRAIL_CATALOG });
+                engineV2: 1, workflowAgentSteps: 1, implementationSteps: 1, workflowDefinitions: 1, fanOut: 1, fork: 1, forkIdempotency: 1, steeringInbox: 1, hostBlockers: 1, setupCommands: 1 }, guardrails: GUARDRAIL_CATALOG });
         return 0;
     }
     if (command === 'validate') {

package/dist/agent-runtime/compact/environment.d.ts

@@ -1,16 +1,29 @@
 import type { spawnSync } from 'node:child_process';
-interface EnvironmentInstall {
+/** `timeoutMs` overrides the default bound for one plan (a browser download is far larger than a dependency install). */
+export interface EnvironmentInstall {
     ecosystem: 'node' | 'python' | 'go' | 'rust';
     root: string;
     command: string;
     args: string[];
+    timeoutMs?: number;
+    installs?: string;
 }
 /** `precondition`: the install failed for a reason only the host can repair (see hostPreconditionFailure). */
-interface InstallOutcome extends EnvironmentInstall {
+export interface InstallOutcome extends EnvironmentInstall {
     ok: boolean;
     detail: string;
     precondition?: string;
 }
+export type HostPreconditionKind = 'network' | 'credential' | 'environment-variable' | 'toolchain' | 'setup' | 'environment';
+export interface HostPrecondition {
+    kind: HostPreconditionKind;
+    reason: string;
+    requiredAction: string;
+}
+/** True when a verification failure names a missing Playwright browser build. */
+export declare function isPlaywrightBrowserFailure(output: string): boolean;
+/** The browser the missing build path names (`chromium_headless_shell-1243` → `chromium`), undefined when none is parsable. */
+export declare function playwrightBrowser(output: string): 'chromium' | 'firefox' | 'webkit' | undefined;
 /** True when a verification failure looks like a missing toolchain/dependency rather than a code defect. */
 export declare function isEnvironmentFailure(exitCode: number | null | undefined, output: string): boolean;
 /**
@@ -23,6 +36,10 @@ export declare function isEnvironmentFailure(exitCode: number | null | undefined
  * again). Returns a short host-facing reason, or undefined.
  */
 export declare function hostPreconditionFailure(output: string): string | undefined;
+/** The blocker kind the matched precondition belongs to; undefined when the output is not a host precondition. */
+export declare function hostPreconditionKind(output: string): HostPreconditionKind | undefined;
+/** Classifies a host precondition with its kind, host-facing reason and the action that unblocks it. */
+export declare function hostPrecondition(output: string): HostPrecondition | undefined;
 /** Packages a failure output names explicitly (`Try \`npm i --save-dev @types/jest\``); the host installs exactly those. */
 export declare function suggestedPackages(output: string): string[];
 /** Dependencies package.json declares that node_modules does not hold (bounded). */

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

@@ -5,6 +5,27 @@ import path from 'node:path';
 // ENOENT there, which read as an environment failure of its own and sent the
 // install/check round in circles. cross-spawn resolves the shim on every OS.
 const defaultSpawn = crossSpawn.sync;
+// A Playwright test run on a host whose browser cache was never populated (a
+// fresh machine, a new Playwright version): the package is installed, the
+// browser build it pins is not. `playwright install` is the documented fix.
+const PLAYWRIGHT_SIGNATURES = [
+    /browserType\.launch: Executable doesn't exist at/i,
+    /Looks like Playwright was just installed or updated/i,
+    /ms-playwright[\\/](?:chromium|firefox|webkit|chromium_headless_shell)[-_]\d+/i,
+];
+/** True when a verification failure names a missing Playwright browser build. */
+export function isPlaywrightBrowserFailure(output) {
+    const tail = output.slice(-6000);
+    return PLAYWRIGHT_SIGNATURES.some(pattern => pattern.test(tail));
+}
+/** The browser the missing build path names (`chromium_headless_shell-1243` → `chromium`), undefined when none is parsable. */
+export function playwrightBrowser(output) {
+    const match = /ms-playwright[\\/](chromium|firefox|webkit|chromium_headless_shell)[-_]\d+/i.exec(output.slice(-6000));
+    if (!match)
+        return undefined;
+    const name = match[1].toLowerCase();
+    return name === 'chromium_headless_shell' ? 'chromium' : name;
+}
 const ENVIRONMENT_SIGNATURES = [
     /command not found/i,
     /is not recognized as an internal or external command/i,
@@ -21,6 +42,7 @@ const ENVIRONMENT_SIGNATURES = [
     /Module (?:[\w@./-]+) in the \w+ option was not found|Preset [\w@./-]+ not found|Cannot find module '(?:ts-jest|babel-jest|@swc\/jest|ts-node|tsx)'/i,
     // Yarn Berry refuses to run scripts in a checkout that was never installed.
     /doesn't seem to have been installed - running an install there might help|Couldn't find the node_modules state file - running an install might help/i,
+    ...PLAYWRIGHT_SIGNATURES,
 ];
 /** True when a verification failure looks like a missing toolchain/dependency rather than a code defect. */
 export function isEnvironmentFailure(exitCode, output) {
@@ -40,20 +62,39 @@ const REGISTRY = String.raw `(?:registry|npmjs\.org|yarnpkg\.com|npm\.pkg\.githu
  * again). Returns a short host-facing reason, or undefined.
  */
 export function hostPreconditionFailure(output) {
+    return hostPrecondition(output)?.reason;
+}
+/** The blocker kind the matched precondition belongs to; undefined when the output is not a host precondition. */
+export function hostPreconditionKind(output) {
+    return hostPrecondition(output)?.kind;
+}
+const PLAYWRIGHT_CDN = String.raw `(?:cdn\.playwright\.dev|playwright\.azureedge\.net|playwright-akamai\.azureedge\.net|playwright-verizon\.azureedge\.net)`;
+/** Classifies a host precondition with its kind, host-facing reason and the action that unblocks it. */
+export function hostPrecondition(output) {
     const text = output.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, '').slice(-16_000);
     const variable = /Environment variable not found \(([A-Za-z_][A-Za-z0-9_]*)\)/.exec(text);
     if (variable)
-        return `the environment variable ${variable[1]} is not available to verification commands, and a package-manager configuration file requires it`;
+        return { kind: 'environment-variable', reason: `the environment variable ${variable[1]} is not available to verification commands, and a package-manager configuration file requires it`,
+            requiredAction: `Make ${variable[1]} available to Specrails (for example in the login shell profile it loads), then retry the run.` };
     if (/\bYN0041\b/.test(text) || /YN0035[\s\S]{0,400}?Response Code: 40[13]\b/.test(text) || /Response code 40[13] \((?:Unauthorized|Forbidden)\)/i.test(text)
         || /npm (?:ERR!|error) code (?:E401|E403|ENEEDAUTH)\b/.test(text) || /ERR_PNPM_FETCH_40[13]\b/.test(text)
         || new RegExp(String.raw `\b40[13] (?:Unauthorized|Forbidden)\b[^\n]{0,80}https?://[^\s]*${REGISTRY}`, 'i').test(text)
         || /\b(?:401|403) Client Error: (?:Unauthorized|Forbidden) for url/.test(text))
-        return 'the package registry rejected the credentials available to verification commands (HTTP 401/403)';
+        return { kind: 'credential', reason: 'the package registry rejected the credentials available to verification commands (HTTP 401/403)',
+            requiredAction: 'Refresh the registry credentials Specrails can use (for example a new token in the login shell profile it loads), then retry the run.' };
+    // The browser download is checked before registry reachability: its CDN is
+    // not a package registry, and the fix is a different command.
+    if (/Failed to download (?:Chrome for Testing|Chromium|Firefox|WebKit|chromium|firefox|webkit|FFMPEG|ffmpeg)\b/i.test(text)
+        || new RegExp(String.raw `Error: (?:getaddrinfo ENOTFOUND|connect ETIMEDOUT|connect ECONNREFUSED|ECONNRESET|ETIMEDOUT)[^\n]{0,300}${PLAYWRIGHT_CDN}`, 'i').test(text))
+        return { kind: 'network', reason: 'the Playwright browser download cannot reach its CDN from the verification environment',
+            requiredAction: 'Download the Playwright browsers with network access (`npx playwright install`), then retry the run.' };
     if (/npm (?:ERR!|error) code (?:ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ETIMEDOUT|ECONNRESET)\b/.test(text) || /ERR_PNPM_META_FETCH_FAIL\b/.test(text)
         || new RegExp(String.raw `\b(?:ENOTFOUND|EAI_AGAIN)\b[^\n]{0,200}${REGISTRY}|${REGISTRY}[^\n]{0,200}\b(?:ENOTFOUND|EAI_AGAIN)\b`, 'i').test(text))
-        return 'the package registry cannot be reached from the verification environment';
+        return { kind: 'network', reason: 'the package registry cannot be reached from the verification environment',
+            requiredAction: 'Give the verification environment network access to the package registry, then retry the run.' };
     if (/fatal: could not read (?:Username|Password) for/.test(text) || /Permission denied \(publickey\)/.test(text))
-        return 'git credentials needed to fetch a dependency are not available to verification commands';
+        return { kind: 'credential', reason: 'git credentials needed to fetch a dependency are not available to verification commands',
+            requiredAction: 'Make the git credentials that fetch the dependency (an SSH key or credential helper) available to Specrails, then retry the run.' };
     return undefined;
 }
 /** Packages a failure output names explicitly (`Try \`npm i --save-dev @types/jest\``); the host installs exactly those. */
@@ -91,6 +132,22 @@ export function missingNodeDependencies(root) {
     }
     return [...declared].filter(name => !existsSync(path.join(root, 'node_modules', name))).slice(0, 20);
 }
+/** Browser builds are ~150 MB each; the default 5-minute install bound is too short on a slow link. */
+const PLAYWRIGHT_INSTALL_TIMEOUT_MS = 10 * 60_000;
+/** True when package.json declares `@playwright/test` or `playwright`; only those repositories get a browser install plan. */
+function declaresPlaywright(root) {
+    let manifest;
+    try {
+        manifest = JSON.parse(readFileSync(path.join(root, 'package.json'), 'utf8'));
+    }
+    catch {
+        return false;
+    }
+    return ['dependencies', 'devDependencies', 'optionalDependencies'].some(field => {
+        const block = manifest[field];
+        return !!block && typeof block === 'object' && ['@playwright/test', 'playwright'].some(name => Object.hasOwn(block, name));
+    });
+}
 /** The installs a repository root needs, judged from its manifests and the absence of their install output. */
 export function plannedInstalls(root, failureOutput = '') {
     const plans = [];
@@ -107,6 +164,14 @@ export function plannedInstalls(root, failureOutput = '') {
         const runner = has('pnpm-lock.yaml') ? 'pnpm' : has('yarn.lock') ? 'yarn' : 'npm';
         plans.push({ ecosystem: 'node', root, command: runner, args: runner === 'npm' ? ['install', '--no-audit', '--no-fund', '--loglevel=error'] : ['install'] });
     }
+    // After the dependency plan: a fresh worktree needs node_modules before
+    // `playwright install` can run at all.
+    if (isPlaywrightBrowserFailure(failureOutput) && declaresPlaywright(root)) {
+        const runner = has('pnpm-lock.yaml') ? 'pnpm' : has('yarn.lock') ? 'yarn' : 'npx';
+        const browser = playwrightBrowser(failureOutput);
+        plans.push({ ecosystem: 'node', root, command: runner, args: [...(runner === 'pnpm' ? ['exec'] : []), 'playwright', 'install', ...(browser ? [browser] : [])],
+            timeoutMs: PLAYWRIGHT_INSTALL_TIMEOUT_MS, installs: `Playwright ${browser ?? 'browsers'}` });
+    }
     if ((has('requirements.txt') || has('pyproject.toml')) && !has('.venv') && !has('venv')) {
         const python = process.platform === 'win32' ? 'python' : 'python3';
         plans.push({ ecosystem: 'python', root, command: python, args: has('requirements.txt') ? ['-m', 'pip', 'install', '-q', '-r', 'requirements.txt'] : ['-m', 'pip', 'install', '-q', '-e', '.'] });
@@ -152,7 +217,7 @@ export function installEnvironment(roots, io = {}) {
             io.onEvent?.({ kind: 'tool-start', tool: plan.command, detail: `${plan.args.join(' ')} (${path.basename(root)})` });
             const run = () => {
                 try {
-                    return spawn(plan.command, plan.args, { cwd: root, encoding: 'utf8', timeout: io.timeoutMs ?? 5 * 60_000, windowsHide: true, env: process.env });
+                    return spawn(plan.command, plan.args, { cwd: root, encoding: 'utf8', timeout: plan.timeoutMs ?? io.timeoutMs ?? 5 * 60_000, windowsHide: true, env: process.env });
                 }
                 catch (error) {
                     return { status: null, error: error, stdout: '', stderr: '', pid: 0, output: [], signal: null };
@@ -182,7 +247,7 @@ export function installEnvironment(roots, io = {}) {
             }
             io.onEvent?.({ kind: 'tool-end', tool: plan.command });
             const ok = result.status === 0;
-            const detail = ok ? `installed ${plan.ecosystem} dependencies in ${path.basename(root)}` : `${plan.command} ${plan.args.join(' ')} failed in ${path.basename(root)}: ${String(result.stderr || result.error?.message || `exit ${result.status}`).trim().slice(0, 400)}`;
+            const detail = ok ? `installed ${plan.installs ?? `${plan.ecosystem} dependencies`} in ${path.basename(root)}` : `${plan.command} ${plan.args.join(' ')} failed in ${path.basename(root)}: ${String(result.stderr || result.error?.message || `exit ${result.status}`).trim().slice(0, 400)}`;
             io.onEvent?.({ kind: 'text', text: `Environment: ${detail}` });
             const precondition = ok ? undefined : hostPreconditionFailure(`${result.stdout ?? ''}\n${result.stderr ?? ''}`);
             outcomes.push({ ...plan, ok, detail, ...(precondition ? { precondition } : {}) });

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.js

@@ -1,6 +1,7 @@
 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';
@@ -10,7 +11,7 @@ import { boundedText, historyEntry, idSchema, json, paramsSchema, invocationTime
 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)];
@@ -45,7 +46,8 @@ 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 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;
@@ -71,3 +73,34 @@ 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 } } : {}) };
 }
+/** The complete plan the host will run for the repositories in scope: configured checks plus, when `verificationProposalsFrom`
+ * names a committed output, its proposals for repositories without a configured check (the rule the verify piece applies). */
+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));
+    const configured = new Set(commands.map(command => command.repositoryId));
+    const seen = new Set(commands.map(planKey));
+    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) : [];
+        for (const proposal of proposals) {
+            if (!proposal || typeof proposal !== 'object' || Array.isArray(proposal))
+                continue;
+            const raw = proposal;
+            if (typeof raw.repositoryId !== 'string' || typeof raw.command !== 'string' || !Array.isArray(raw.args) || !raw.args.every(arg => typeof arg === 'string'))
+                continue;
+            if (!inScope.has(raw.repositoryId) || configured.has(raw.repositoryId))
+                continue;
+            const command = withScopeDefault(deps.context, { repositoryId: raw.repositoryId, command: raw.command, args: raw.args, ...(typeof raw.cwd === 'string' ? { cwd: raw.cwd } : {}) });
+            const key = planKey(command);
+            if (seen.has(key))
+                continue;
+            seen.add(key);
+            commands.push(command);
+        }
+    }
+    return commands;
+}
+function planKey(command) {
+    return JSON.stringify([command.repositoryId, command.cwd ?? '', command.command, command.args]);
+}

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

@@ -5,6 +5,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 +78,118 @@ 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));
+    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));
+        }
+    }
+    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 +198,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?: {

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

@@ -1,14 +1,14 @@
 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';
 import { OpenSpecTools } from '../openspec.js';
 import { candidateManifest, fingerprintCandidate, frozenAcceptanceCriteria, inspectPipeline, recordAcceptance, transitionPipeline, validateAcceptanceReport, verifyPipeline, } from '../../pipeline/pipeline-state.js';
 import { ARCHITECT_OUTPUT_SCHEMA, DEVELOPER_OUTPUT_SCHEMA, REVIEW_OUTPUT_SCHEMA, correctionInstructions, deepenInstructions, roleInstructions } from '../prompts.js';
 import { archive, child, journal, object, parseArchitecture, proposedVerification, write, writeDesignConfidence } from './artifacts.js';
 import { evaluateReview } from './review-policy.js';
-import { hostPreconditionFailure, installEnvironment, isEnvironmentFailure } from '../compact/environment.js';
+import { isEnvironmentFailure } from '../compact/environment.js';
+import { hostPreconditionMessage, preconditionBlock, repairEnvironment } from '../verification-repair.js';
 import { unreachedTestFiles, unreachedTestsReason } from '../compact/test-reachability.js';
 import { exitCodeContradiction, exitHonestyReason } from '../compact/exit-code-honesty.js';
 import { boundedReviewManifest, reviewChanges } from '../review-context.js';
@@ -287,52 +287,6 @@ function fixerNode(deps) {
         },
     };
 }
-/** Where a missing dependency install belongs: the nearest directory with a lockfile or manifest above the failing command, else the repository root. */
-const INSTALL_MARKERS = ['package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lock', 'bun.lockb', 'requirements.txt', 'pyproject.toml', 'go.mod', 'Cargo.toml'];
-function installRoots(context, commands) {
-    const roots = [];
-    for (const command of commands) {
-        const repository = context.repositories.find(repo => repo.id === command.repositoryId);
-        if (!repository)
-            continue;
-        let directory = command.cwd;
-        let chosen = repository.path;
-        for (;;) {
-            const relative = path.relative(repository.path, directory);
-            if (relative.startsWith('..') || path.isAbsolute(relative))
-                break;
-            if (INSTALL_MARKERS.some(name => existsSync(path.join(directory, name)))) {
-                chosen = directory;
-                break;
-            }
-            if (!relative)
-                break;
-            directory = path.dirname(directory);
-        }
-        roots.push(chosen);
-    }
-    // Every repository root stays a candidate: its plan is a no-op when it is already installed.
-    return [...new Set([...roots, ...context.repositories.map(repository => repository.path)])];
-}
-/** A directory as the log should name it: relative to the checkout that contains it. */
-function checkoutRelative(context, directory) {
-    const repository = context.repositories.find(repo => { const relative = path.relative(repo.path, directory); return !relative.startsWith('..') && !path.isAbsolute(relative); });
-    return repository ? path.relative(repository.path, directory).split(path.sep).join('/') || '.' : directory;
-}
-function hostPreconditionMessage(reason, command, args, directory) {
-    return `Verification cannot run in this environment: ${reason} (\`${[command, ...args].join(' ')}\` in ${directory}). This is not a defect in the change, so no correction round was started. Make it available to Specrails (for example in the login shell profile Specrails loads, or with a refreshed registry token), then resume.`;
-}
-/** A failed check the host must unblock (credentials, registry access, a missing variable): no correction round can repair it. */
-function preconditionBlock(context, receipt) {
-    for (const command of receipt.commands) {
-        if (command.exitCode === 0)
-            continue;
-        const reason = hostPreconditionFailure(command.output);
-        if (reason)
-            return hostPreconditionMessage(reason, command.command, command.args, checkoutRelative(context, command.cwd));
-    }
-    return undefined;
-}
 function verifyNode(deps) {
     const { context, note, config } = deps;
     const roots = context.repositories.map(repository => repository.path);
@@ -388,25 +342,25 @@ function verifyNode(deps) {
                 note('fixer', 'Verification failed on the environment, not on the change; stopping for the host instead of starting a correction round.');
                 return { status: 'blocked', error: reason, usage: NO_SPEND };
             };
+            const blockerMessage = (blocker) => hostPreconditionMessage(blocker.reason, blocker.command, blocker.args, blocker.cwd);
             let precondition = receipt.valid ? undefined : preconditionBlock(context, receipt);
             if (precondition)
-                return hostBlocked(precondition);
+                return hostBlocked(blockerMessage(precondition));
             // A failure that is really a missing toolchain or dependency (exit 127,
             // "command not found", "Cannot find module"…) is the HOST's to fix, not
             // the model's — for every developer: a fresh worktree has no
             // node_modules whatever wrote the code. Install once where the failing
             // command runs and re-verify; only a second failure becomes feedback.
             if (!receipt.valid && guardrailEnabled(config.guardrails, 'environment-repair') && receipt.commands.some(command => isEnvironmentFailure(command.exitCode, command.output))) {
-                const installs = installEnvironment(installRoots(context, receipt.commands.filter(command => command.exitCode !== 0)), { failureOutput: receipt.commands.map(command => command.output).join('\n'), lockfileRepair: guardrailEnabled(config.guardrails, 'lockfile-repair'), onEvent: event => note('developer', event.kind === 'text' ? event.text ?? '' : `[environment] ${event.tool ?? ''} ${event.detail ?? ''}`.trim()) });
-                const refused = installs.find(outcome => outcome.precondition);
-                if (refused)
-                    return hostBlocked(hostPreconditionMessage(`installing its dependencies failed because ${refused.precondition}`, refused.command, refused.args, checkoutRelative(context, refused.root)));
-                if (installs.some(outcome => outcome.ok)) {
+                const repair = repairEnvironment(context, receipt, config.guardrails, text => note('developer', text));
+                if (repair.refused)
+                    return hostBlocked(blockerMessage(repair.refused));
+                if (repair.installs.some(outcome => outcome.ok)) {
                     note('developer', 'Verification failed on the environment (missing dependencies or tools); the host installed them and is verifying again.');
                     receipt = await run();
                     precondition = receipt.valid ? undefined : preconditionBlock(context, receipt);
                     if (precondition)
-                        return hostBlocked(precondition);
+                        return hostBlocked(blockerMessage(precondition));
                 }
             }
             const evidence = {

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

@@ -3,7 +3,7 @@ import type { PipelineContext, VerificationCommand } from '../pipeline/pipeline-
 import { type ReviewPolicy } from './graph/review-policy.js';
 import type { DeveloperRecord } from './graph/state.js';
 /** Bump whenever the wording changes: the version is part of the frozen run identity. */
-export declare const ROLE_INSTRUCTIONS_VERSION = "13";
+export declare const ROLE_INSTRUCTIONS_VERSION = "14";
 export interface RoleFeedback {
     verification?: unknown;
     review?: unknown;

package/dist/agent-runtime/prompts.js

@@ -1,7 +1,7 @@
 import { isBuiltinRole } from './executor-types.js';
 import { DEFAULT_REVIEW_POLICY, REVIEW_ASPECTS } from './graph/review-policy.js';
 /** Bump whenever the wording changes: the version is part of the frozen run identity. */
-export const ROLE_INSTRUCTIONS_VERSION = '13';
+export const ROLE_INSTRUCTIONS_VERSION = '14';
 const OUTPUT_TAIL = 6_000;
 /** One senior engineer, rendered once per role prompt (never repeated inside it): the identity the implement pipeline's roles share. */
 const ENGINEER = 'a T-shaped principal engineer with decades of delivery across web, mobile and backend systems: deep in software design and testing, broad across product, UX, data, security, infrastructure and operations; fluent in hexagonal (ports and adapters) architecture, SOLID, design patterns, Clean Code, The Pragmatic Programmer, refactoring, legacy-code seams and AI-assisted development. You work for the user, the operator and the next maintainer, and you treat AI-generated code, including your own, with the scepticism owed to any untrusted contribution.';
@@ -116,7 +116,7 @@ function boundarySection(role, custom = false) {
         role === 'developer'
             ? [
                 '- Edit only the repositories in scope, and only inside a repository\'s scope when it declares one. Prefer the smallest change that fully satisfies the tasks; do not refactor, reformat, rename or upgrade unrelated code, tests or configuration. On a fixer turn, a failing host test in that scope may receive the minimal compatibility repair described in the correction instructions; preserve its required behavior and assertions. Other unrelated problems belong in your summary.',
-                '- Never edit package-manager, registry, credential, CI or environment configuration (for example `.npmrc`, `.yarnrc*`, `.env*`, CI workflows) to make a command work. A missing credential, environment variable, registry access or tool is the host\'s to fix: report it under `incomplete` with the exact error.',
+                '- Never edit package-manager, registry, credential, CI or environment configuration (for example `.npmrc`, `.yarnrc*`, `.env*`, CI workflows) to make a command work. A missing credential, environment variable, registry access or tool is the host\'s to fix: report it under `incomplete` with the exact error. Installing a documented, idempotent toolchain artifact inside the admitted workspace (for example a Playwright browser with `npx playwright install <browser>`, or a Python virtualenv) is allowed and must be reported under verification; editing package-manager, registry, credential, CI or environment configuration remains forbidden.',
                 '- Check with the narrowest command that covers what you touched (the specific test files or test names), never the whole checkout or every workspace; Core runs the complete verification plan after your turn.',
             ].join('\n')
             : role === 'architect' ? '- Read code without modifying it. Author OpenSpec artifacts only through the supplied scoped workflow tools.' + (custom ? '' : ' Return confidence and verification metadata in JSON.') : '- This role is read-only. Do not create, edit or delete files' + (custom ? '.' : '; return your result as the requested JSON object.'),
@@ -191,7 +191,7 @@ function fixerSection(verification, definition) {
         '4. Fix the cause, not the symptom: a repair that satisfies the assertion while leaving the defect, or that special-cases the test input, is not a fix. Fix incorrect implementation behavior. A failing mandatory host test inside the admitted repository/workspace may also receive a minimal compatibility repair when you prove that its expected behavior is unchanged. For example, a source assertion broken only by formatting may tolerate whitespace while retaining every required operand and guard. This applies even to a pre-existing test outside the current changed-file list. Explain the original expectation and why the repair still rejects the prohibited behavior. Never weaken an assertion, delete or skip a test, hardcode success, change acceptance criteria, add dependencies or widen the repair beyond the diagnosed failure.',
         '5. A test file the host reports as never executed must be wired into the repository\'s test command (the test script or runner configuration) and then made to pass.',
         '6. Confirm the repair with the focused test command and a negative case for any repaired assertion: removing a required safety guard or returning the wrong value must still fail. Preserve the original test exit status; never pipe test execution through grep/head or another command that masks it. Capture stdout/stderr in a temporary log and inspect that log separately. Core runs the complete verification plan after your turn.',
-        '7. Inspect only the reported files, direct dependencies and the evidence needed to establish the cause. Never edit outside the admitted repository/workspace, credentials, environment or unrelated configuration. For an external or unrepairable scope blocker, make no speculative edits and report the exact error, observed evidence and required action. `proposal.md`, `design.md` and the specs remain frozen; only tick completed tasks.',
+        '7. Inspect only the reported files, direct dependencies and the evidence needed to establish the cause. Never edit outside the admitted repository/workspace, credentials, environment or unrelated configuration. When the diagnosed cause is a host precondition or environment blocker (missing network, credentials, environment variable, toolchain, setup command or an out-of-scope repository), make no speculative edits, state in summary that the candidate was intentionally left unchanged, and return `blocker` as {"kind":"network|credential|environment-variable|toolchain|setup|environment|scope","command":"…","cwd":"…","evidence":"exact error","requiredAction":"one imperative sentence the host can act on"}. `proposal.md`, `design.md` and the specs remain frozen; only tick completed tasks.',
         '8. Return the requested JSON contract. Include the diagnosis, exact focused commands and original exit codes, repair and preserved assertion in summary. List every unresolved failure and its reason under incomplete, even when the implementation tasks are already ticked. A failed test remains failed until real host verification passes.',
     ] : [definition, ''];
     return [...lines, ...developerTail(verification)];
@@ -208,7 +208,7 @@ function developerSection(verification, corrections, definition) {
         '1. Load and execute openspec-apply-change through the supplied binding. Consult its status and instructions apply, read the context files OpenSpec returns, then the relevant existing code and tests.',
         '2. Work task by task in order. Use test-driven development: write or extend the test first, make it pass with the smallest correct change, then tidy up. Run only focused tests that cover what you touched while iterating. Core owns the complete verification plan and runs it after your turn; do not duplicate that full run. Fix the precise failures Core returns on a correction pass.',
         '3. Immediately after completing each task, mark it `- [x]` in `tasks.md`; do not postpone all progress updates until the end of the phase. Only mark tasks whose code and tests are complete. Change nothing else in `tasks.md`, and never edit `proposal.md`, `design.md` or the specs: those documents are frozen, and editing them invalidates the run. If a task cannot be completed, leave it `- [ ]` and list it under `incomplete` with the reason.',
-        '4. Keep the implementation consistent with the repository: naming, error handling, import style, formatting and existing utilities. Do not add dependencies unless the design requires them. Change only what the tasks require: the diff should contain the requested change and its tests, nothing else.',
+        '4. Keep the implementation consistent with the repository: naming, error handling, import style, formatting and existing utilities. Do not add dependencies unless the design requires them. Change only what the tasks require: the diff should contain the requested change and its tests, nothing else. Never validate with a temporary configuration, alternate runner or local browser the host verification plan does not use, and never delete such a file to hide it: the host runs the plan as-is. When a required tool is missing, install it through the project\'s documented command or report it as a blocker.',
         'Blast radius: the files design.md and tasks.md name are your boundary. Touch a file outside it only when a task cannot be completed otherwise; keep that edit to the strict need and explain it in summary. Inside a file, change only the lines the task needs: no reformatting, import reordering, renames, type widening, comment rewrites or "while I am here" fixes. Leave an unrelated problem alone and mention it in summary. Keep public signatures, exported contracts, schemas and persisted formats as the design states. Never delete or rewrite a test a task does not name, and never regenerate lockfiles, snapshots or generated files unless the task\'s own change requires it.',
         'Quality bar: write code a senior maintainer would merge unchanged. Intention-revealing names from the domain vocabulary; small functions that do one thing at one level of abstraction; guard clauses over nested conditionals; no boolean flag parameters, magic values or hidden side effects; immutability by default and explicit types at module boundaries; parse and validate at the boundary, trust typed values inside; every error path handled the way neighbouring code handles it (fail fast at the boundary, never swallow, errors carry context); domain logic out of adapters and dependencies pointing inward as the repository already does; comments explain why, never what; no dead code, commented-out code, debug output, TODO placeholders or speculative options.',
         'Engineering judgement: understand before you change and never program by coincidence (if you cannot explain why it works, you are not done); never delete or bypass a guard, branch or workaround you cannot explain. Handle what tests rarely reach: empty, huge and malformed inputs, boundary values, time zones and Unicode, partial failures, retries with idempotency, races, cancellation, timeouts and resource cleanup (handles, listeners, subscriptions, temp files). Security hygiene is non-negotiable: parameterized queries, escaped output, no secrets or personal data in code or logs, least privilege, authorization where the repository enforces it. Logs and metrics follow the repository\'s conventions; migrations and persisted-format changes stay additive and backward compatible. Verify every API, signature and option against the source or installed types, never from memory. Do the simplest thing that fully works, then refactor only inside the blast radius. Tests are the specification: one behavior per test (arrange, act, assert) covering inputs, outputs, side effects and errors; no logic in tests; mock only at real boundaries; deterministic; failing without the change; in the repository\'s existing style. A task is done only when its code, tests and every artifact it makes stale (localized strings in every shipped locale, documentation, schemas, configuration examples) are updated and its focused checks pass.',
@@ -220,14 +220,18 @@ function developerSection(verification, corrections, definition) {
     return [...lines, ...developerTail(verification)];
 }
 /** Verification commands, durable-progress guidance and the output contract shared by the developer and fixer stances. */
+/** The complete host verification plan a write role must see: what Core runs after the turn, so nothing is validated through a bypass the plan does not use. */
+function hostPlanSection(verification) {
+    if (!verification?.length)
+        return [];
+    return [
+        '', 'Core owns these complete verification commands and will run them after your turn. Use focused tests while iterating instead of repeating this plan:',
+        ...verification.map(command => `- repository \`${command.repositoryId}\`${command.cwd ? ' in `' + command.cwd + '`' : ''}: \`${shellWords(command)}\``),
+    ];
+}
 function developerTail(verification) {
-    const lines = [];
-    if (verification?.length) {
-        lines.push('', 'Core owns these complete verification commands and will run them after your turn. Use focused tests while iterating instead of repeating this plan:');
-        for (const command of verification)
-            lines.push(`- repository \`${command.repositoryId}\`${command.cwd ? ' in `' + command.cwd + '`' : ''}: \`${shellWords(command)}\``);
-    }
-    lines.push('', '## Durable implementation progress', '', 'When loading the official apply skill, read its savedProgress handoff before repeating investigation. Reconcile it with the current diff and tasks; it is advisory history, never accepted verification evidence. Preserve completed work and previously discovered test commands or environment blockers. Recheck a blocker only when its relevant condition changed.', 'After each completed task, and whenever the next action or a blocker changes, call the scoped workflow action write_progress with progress: {summary, completedTasks, nextTasks, checks: [{command, outcome}], blockers}. Replace the previous handoff with a concise current account (at most 8 KB); include exact focused test commands, original exit outcomes, relevant paths and the next discriminating action. Keep nextTasks concrete enough for a fresh session to continue unfinished work. Do not include full logs, credentials or claims that old checks authorize acceptance. The host persists this record outside the frozen OpenSpec artifacts. Use read_progress to refresh it. If interrupted, the next session receives it from load_skill; do not write runtime files directly.', '', '## Output contract', '', 'Finish with exactly one JSON object and nothing after it: no prose after the object, no Markdown fence.', '', '```', '{"summary":"What you implemented and how","files":["src/feature.ts"],"tests":["src/feature.test.ts"],"verification":"npm test passed (12 tests)","incomplete":[{"task":"3. …","reason":"why it could not be completed"}]}', '```', '', '- `files` and `tests`: repository-relative paths you created or modified (test files appear in `tests`, other files in `files`).', '- `verification`: the commands you ran and their outcome, or `none` when no shell was available.', '- `incomplete`: every task still `- [ ]` in `tasks.md`, with its reason; an empty array when everything is done.', '- Do not paste full test logs; the reviewer reads the real verification evidence separately.', '');
+    const lines = [...hostPlanSection(verification)];
+    lines.push('', '## Durable implementation progress', '', 'When loading the official apply skill, read its savedProgress handoff before repeating investigation. Reconcile it with the current diff and tasks; it is advisory history, never accepted verification evidence. Preserve completed work and previously discovered test commands or environment blockers. Recheck a blocker only when its relevant condition changed.', 'After each completed task, and whenever the next action or a blocker changes, call the scoped workflow action write_progress with progress: {summary, completedTasks, nextTasks, checks: [{command, outcome}], blockers}. Replace the previous handoff with a concise current account (at most 8 KB); include exact focused test commands, original exit outcomes, relevant paths and the next discriminating action. Keep nextTasks concrete enough for a fresh session to continue unfinished work. Do not include full logs, credentials or claims that old checks authorize acceptance. The host persists this record outside the frozen OpenSpec artifacts. Use read_progress to refresh it. If interrupted, the next session receives it from load_skill; do not write runtime files directly.', '', '## Output contract', '', 'Finish with exactly one JSON object and nothing after it: no prose after the object, no Markdown fence.', '', '```', '{"summary":"What you implemented and how","files":["src/feature.ts"],"tests":["src/feature.test.ts"],"verification":"npm test passed (12 tests)","incomplete":[{"task":"3. …","reason":"why it could not be completed"}],"blocker":{"kind":"toolchain","command":"npx playwright test","cwd":".","evidence":"exact error","requiredAction":"Run npx playwright install chromium"}}', '```', '', '- `files` and `tests`: repository-relative paths you created or modified (test files appear in `tests`, other files in `files`).', '- `verification`: the commands you ran and their outcome, or `none` when no shell was available.', '- `incomplete`: every task still `- [ ]` in `tasks.md`, with its reason; an empty array when everything is done.', '- `blocker`: only when the cause lies outside the change; omit otherwise. The host ends the run with your `requiredAction` instead of starting another correction round.', '- Do not paste full test logs; the reviewer reads the real verification evidence separately.', '');
     return lines;
 }
 function reviewerSection(policy, criteria, definition) {
@@ -388,7 +392,9 @@ export function roleInstructions(roleOrDescriptor, context, change, options = {}
             `Workspace access: ${roleOrDescriptor.access}. OpenSpec artifact permission: ${roleOrDescriptor.artifacts}.`, '',
             'Execute only this assigned role. Traversal, retries, verification, approval, archive and delivery belong to Core. Do not spawn another role or change runtime metadata.',
             ...boundarySection(roleOrDescriptor.access === 'write' ? 'developer' : roleOrDescriptor.artifacts === 'all' ? 'architect' : 'reviewer', true),
-            ...conventionsSection(), ...scopeSection(context, change), ...feedbackSection(options.feedback),
+            ...conventionsSection(), ...scopeSection(context, change),
+            ...(roleOrDescriptor.access === 'write' ? hostPlanSection(options.verification) : []),
+            ...feedbackSection(options.feedback),
         ].join('\n').trimEnd() + '\n';
     }
     const feedback = feedbackSection(options.feedback);

package/dist/agent-runtime/verification-repair.d.ts

@@ -0,0 +1,26 @@
+import type { spawnSync } from 'node:child_process';
+import type { CommandReceipt, PipelineContext, VerificationReceipt } from '../pipeline/pipeline-state.js';
+import { type InstallOutcome } from './compact/environment.js';
+import type { HostBlocker } from './engine/contracts.js';
+import { type GuardrailSettings } from './guardrails.js';
+export type { HostBlocker } from './engine/contracts.js';
+export declare function installRoots(context: PipelineContext, commands: readonly CommandReceipt[]): string[];
+/** A directory as the log should name it: relative to the checkout that contains it. */
+export declare function checkoutRelative(context: PipelineContext, directory: string): string;
+/** The legacy host-facing sentence for a blocker; engine v2 hosts read the structured blocker instead. */
+export declare function hostPreconditionMessage(reason: string, command: string, args: readonly string[], directory: string): string;
+/** A failed check the host must unblock (credentials, registry access, a missing variable): no correction round can repair it. */
+export declare function preconditionBlock(context: PipelineContext, receipt: VerificationReceipt): HostBlocker | undefined;
+export interface EnvironmentRepair {
+    installs: InstallOutcome[];
+    refused?: HostBlocker;
+}
+/**
+ * Runs the planned installs for the failed commands' roots once, narrating each
+ * step through `note` exactly as the legacy graph logs it (`[environment] npm
+ * install (app)`, `Environment: installed …`). An install the host cannot
+ * complete for a precondition reason becomes `refused`.
+ */
+export declare function repairEnvironment(context: PipelineContext, receipt: VerificationReceipt, guardrails: GuardrailSettings | undefined, note: (text: string) => void, spawn?: typeof spawnSync): EnvironmentRepair;
+/** A blocker as a durable JSON value: known kind, bounded strings, at most 16 arguments. */
+export declare function boundedBlocker(value: unknown): HostBlocker | undefined;

package/dist/agent-runtime/verification-repair.js

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { hostPrecondition, installEnvironment } from './compact/environment.js';
+import { guardrailEnabled } from './guardrails.js';
+const BLOCKER_KINDS = new Set(['network', 'credential', 'environment-variable', 'toolchain', 'setup', 'environment', 'scope']);
+const BLOCKER_TEXT_LIMIT = 2_000;
+/** Where a missing dependency install belongs: the nearest directory with a lockfile or manifest above the failing command, else the repository root. */
+const INSTALL_MARKERS = ['package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lock', 'bun.lockb', 'requirements.txt', 'pyproject.toml', 'go.mod', 'Cargo.toml'];
+export function installRoots(context, commands) {
+    const roots = [];
+    for (const command of commands) {
+        const repository = context.repositories.find(repo => repo.id === command.repositoryId);
+        if (!repository)
+            continue;
+        let directory = command.cwd;
+        let chosen = repository.path;
+        for (;;) {
+            const relative = path.relative(repository.path, directory);
+            if (relative.startsWith('..') || path.isAbsolute(relative))
+                break;
+            if (INSTALL_MARKERS.some(name => existsSync(path.join(directory, name)))) {
+                chosen = directory;
+                break;
+            }
+            if (!relative)
+                break;
+            directory = path.dirname(directory);
+        }
+        roots.push(chosen);
+    }
+    // Every repository root stays a candidate: its plan is a no-op when it is already installed.
+    return [...new Set([...roots, ...context.repositories.map(repository => repository.path)])];
+}
+/** A directory as the log should name it: relative to the checkout that contains it. */
+export function checkoutRelative(context, directory) {
+    const repository = context.repositories.find(repo => { const relative = path.relative(repo.path, directory); return !relative.startsWith('..') && !path.isAbsolute(relative); });
+    return repository ? path.relative(repository.path, directory).split(path.sep).join('/') || '.' : directory;
+}
+/** The legacy host-facing sentence for a blocker; engine v2 hosts read the structured blocker instead. */
+export function hostPreconditionMessage(reason, command, args, directory) {
+    return `Verification cannot run in this environment: ${reason} (\`${[command, ...args].join(' ')}\` in ${directory}). This is not a defect in the change, so no correction round was started. Make it available to Specrails (for example in the login shell profile Specrails loads, or with a refreshed registry token), then resume.`;
+}
+/** A failed check the host must unblock (credentials, registry access, a missing variable): no correction round can repair it. */
+export function preconditionBlock(context, receipt) {
+    for (const command of receipt.commands) {
+        if (command.exitCode === 0)
+            continue;
+        const precondition = hostPrecondition(command.output);
+        if (precondition)
+            return boundedBlocker({ kind: precondition.kind, reason: precondition.reason, command: command.command, args: command.args, cwd: checkoutRelative(context, command.cwd),
+                requiredAction: precondition.requiredAction, ...(command.evidenceId ? { evidenceId: command.evidenceId } : {}) });
+    }
+    return undefined;
+}
+/**
+ * Runs the planned installs for the failed commands' roots once, narrating each
+ * step through `note` exactly as the legacy graph logs it (`[environment] npm
+ * install (app)`, `Environment: installed …`). An install the host cannot
+ * complete for a precondition reason becomes `refused`.
+ */
+export function repairEnvironment(context, receipt, guardrails, note, spawn) {
+    const failed = receipt.commands.filter(command => command.exitCode !== 0);
+    const installs = installEnvironment(installRoots(context, failed), { failureOutput: receipt.commands.map(command => command.output).join('\n'), lockfileRepair: guardrailEnabled(guardrails, 'lockfile-repair'),
+        ...(spawn ? { spawn } : {}), onEvent: event => note(event.kind === 'text' ? event.text ?? '' : `[environment] ${event.tool ?? ''} ${event.detail ?? ''}`.trim()) });
+    const refused = installs.find(outcome => outcome.precondition);
+    if (!refused)
+        return { installs };
+    const precondition = hostPrecondition(refused.detail) ?? { kind: 'environment', reason: refused.precondition, requiredAction: 'Repair the verification environment, then retry the run.' };
+    const cwd = checkoutRelative(context, refused.root);
+    const command = [refused.command, ...refused.args].join(' ');
+    return { installs, refused: boundedBlocker({ kind: precondition.kind, reason: `installing its dependencies failed because ${refused.precondition}`, command: refused.command, args: refused.args, cwd,
+            // A network blocker on an install names the exact command to repeat with connectivity; other kinds keep the classifier's action.
+            requiredAction: precondition.kind === 'network' ? `Run \`${command}\` in ${cwd} with network access, then retry the run.` : precondition.requiredAction }) };
+}
+/** A blocker as a durable JSON value: known kind, bounded strings, at most 16 arguments. */
+export function boundedBlocker(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    if (typeof raw.kind !== 'string' || !BLOCKER_KINDS.has(raw.kind))
+        return undefined;
+    const bounded = (field, limit = BLOCKER_TEXT_LIMIT) => typeof field === 'string' ? field.slice(0, limit) : '';
+    const args = Array.isArray(raw.args) ? raw.args.slice(0, 16).map(arg => bounded(arg, 256)) : [];
+    // A correction role reports free-text `evidence` instead of a host reason.
+    const reason = bounded(raw.reason) || bounded(raw.evidence);
+    return { kind: raw.kind, reason, command: bounded(raw.command, 512), args, cwd: bounded(raw.cwd, 512), requiredAction: bounded(raw.requiredAction),
+        ...(typeof raw.evidenceId === 'string' && raw.evidenceId ? { evidenceId: bounded(raw.evidenceId, 128) } : {}) };
+}

package/integration-contract.json

@@ -293,7 +293,7 @@
     "specificationFormat": "Architect specs contain complete main-spec replacements, including unchanged requirements; archive does not merge partial delta snippets.",
     "compatibility": "Additive to integration schema 4 and execution context schema 1. Legacy workflows and profile v1 remain supported. Hosts must check RUNTIME_API_VERSION, not infer runtime support from Core major version.",
     "documentation": "docs/agent-runtime.md",
-    "instructionsVersion": "13",
+    "instructionsVersion": "14",
     "workflowVersion": "7",
     "engines": [
       1,

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-core",
-  "version": "6.3.0",
+  "version": "6.4.0",
   "description": "Agent workflow engine for specrails-desktop: provider-independent installer and programmatic agent runtime for Claude Code and Codex",
   "type": "module",
   "exports": {

package/schemas/agent-runtime.schema.json

@@ -134,13 +134,8 @@
       "maxAttempts": { "$ref": "#/definitions/positiveInteger" }, "maxTokens": { "$ref": "#/definitions/positiveInteger" },
       "maxCostUsd": { "type": "number", "exclusiveMinimum": 0 }, "timeoutMs": { "$ref": "#/definitions/positiveInteger" }
     } },
-    "verification": { "type": "array", "items": { "type": "object", "additionalProperties": false, "required": ["repositoryId", "command", "args"], "properties": {
-      "key": { "$ref": "#/definitions/id" }, "label": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "\\S" }, "policy": { "$ref": "#/definitions/checkPolicy" },
-      "repositoryId": { "$ref": "#/definitions/id" }, "command": { "type": "string", "minLength": 1 },
-      "args": { "type": "array", "items": { "type": "string" } }, "cwd": { "type": "string", "minLength": 1 },
-      "env": { "type": "object", "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "additionalProperties": { "type": "string" } },
-      "timeoutMs": { "$ref": "#/definitions/positiveInteger" }
-    } } },
+    "verification": { "type": "array", "items": { "$ref": "#/definitions/checkCommand" } },
+    "setup": { "type": "array", "description": "Idempotent commands the verify piece runs sequentially in the admitted workspace before each verification plan; a failing setup command blocks the run instead of starting a correction round.", "items": { "$ref": "#/definitions/checkCommand" } },
     "approvalBeforeArchive": { "type": "boolean" },
     "review": { "type": "object", "additionalProperties": false, "description": "Review gate thresholds; unset fields keep Core's defaults (score 70, security 75, other aspects 60).", "properties": {
       "minScore": { "$ref": "#/definitions/score" },
@@ -154,6 +149,13 @@
     } }
   },
   "definitions": {
+    "checkCommand": { "type": "object", "additionalProperties": false, "required": ["repositoryId", "command", "args"], "properties": {
+      "key": { "$ref": "#/definitions/id" }, "label": { "type": "string", "minLength": 1, "maxLength": 256, "pattern": "\\S" }, "policy": { "$ref": "#/definitions/checkPolicy" },
+      "repositoryId": { "$ref": "#/definitions/id" }, "command": { "type": "string", "minLength": 1 },
+      "args": { "type": "array", "items": { "type": "string" } }, "cwd": { "type": "string", "minLength": 1 },
+      "env": { "type": "object", "propertyNames": { "pattern": "^[A-Za-z_][A-Za-z0-9_]*$" }, "additionalProperties": { "type": "string" } },
+      "timeoutMs": { "$ref": "#/definitions/positiveInteger" }
+    } },
     "effort": { "type": "string", "pattern": "^[a-z][a-z0-9_-]{0,31}$" },
     "inputList": { "type": "array", "maxItems": 256, "items": { "type": "string", "minLength": 1, "maxLength": 4096, "pattern": "\\S" } },
     "checkPolicy": { "type": "object", "additionalProperties": false, "properties": {