specrails-core 6.2.2 → 6.4.0

package/README.md

@@ -6,7 +6,7 @@
 
 The agent workflow engine behind [Specrails Desktop](https://github.com/fjpulidop/specrails-desktop). Core does two things:
 
-1. **Installs** the specrails workflow into a project for Claude Code or Codex CLI: three roles (architect, developer, reviewer), the `implement` and `retry` entry points (`implement` runs one ticket or several tickets as one aggregate run) and the official OpenSpec skills.
+1. **Installs** the specrails workflow into a project for Claude Code, Codex CLI, Gemini CLI or Kimi Code: the `implement` and `retry` entry points (`implement` runs one ticket or several tickets as one aggregate run), provider settings and the official OpenSpec skills. The architect, developer and reviewer roles are defined by the runtime itself; no role file is installed.
 2. **Executes** Desktop-owned workflow definitions through the [programmatic agent runtime](docs/agent-runtime.md): independent agent and implementation operations, per-role providers, deterministic verification, durable recovery and OpenAI-compatible local models. Desktop owns workflow composition and editable loop agents; Core retains the old builtin for saved runs.
 
 Desktop bundles a pinned Core package and owns everything around it: worktrees, commits, pull requests, backlog and the user interface. Core never ships code on its own; it prepares a reviewed candidate for the host.
@@ -31,7 +31,7 @@ bin/specrails-core.mjs     npm bin shim → dist/installer/cli.js
 src/installer/             CLI, framework lifecycle, provider rendering
 src/pipeline/              pipeline journal, gates and verification receipts
 src/agent-runtime/         programmatic runtime: graph, executors, compact loop, recovery
-templates/                 role definitions, workflow commands, provider settings
+templates/                 workflow commands, provider settings, Kimi runner
 schemas/                   runtime configuration schema and fixtures
 integration-contract.json  Desktop ⇄ Core contract
 ```

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;