specrails-desktop 2.60.0 → 2.61.0

package/client/dist/index.html

@@ -204,7 +204,7 @@
         .specrails-splash__mark .pill { opacity: 1; }
       }
     </style>
-    <script type="module" crossorigin src="/assets/index-g8S62tpS.js"></script>
+    <script type="module" crossorigin src="/assets/index-lTGJJTuk.js"></script>
     <link rel="modulepreload" crossorigin href="/assets/rolldown-runtime-CNC7AqOf.js">
     <link rel="modulepreload" crossorigin href="/assets/jsx-runtime-zu2_FqZY.js">
     <link rel="modulepreload" crossorigin href="/assets/react-dom-DiWzBDP9.js">
@@ -214,7 +214,7 @@
     <link rel="modulepreload" crossorigin href="/assets/activity-DiyjsgQV.js">
     <link rel="modulepreload" crossorigin href="/assets/addspec-BOvgmcgk.js">
     <link rel="modulepreload" crossorigin href="/assets/agent-Z5s_GTP0.js">
-    <link rel="modulepreload" crossorigin href="/assets/agentRuntime-BHVw9orA.js">
+    <link rel="modulepreload" crossorigin href="/assets/agentRuntime-C_yLPKDy.js">
     <link rel="modulepreload" crossorigin href="/assets/agents-Doe1sHY5.js">
     <link rel="modulepreload" crossorigin href="/assets/agentstudio-BzugqB_N.js">
     <link rel="modulepreload" crossorigin href="/assets/aiedit-iIjz2_Qk.js">
@@ -231,9 +231,9 @@
     <link rel="modulepreload" crossorigin href="/assets/integrations-Dwl9KQp0.js">
     <link rel="modulepreload" crossorigin href="/assets/jira-FXr7u2lh.js">
     <link rel="modulepreload" crossorigin href="/assets/jobs-De3EqaO0.js">
-    <link rel="modulepreload" crossorigin href="/assets/loops--KWr0X-w.js">
+    <link rel="modulepreload" crossorigin href="/assets/loops-WyWDkhok.js">
     <link rel="modulepreload" crossorigin href="/assets/mcp-CUAN6ORK.js">
-    <link rel="modulepreload" crossorigin href="/assets/narration-n3hOA7LY.js">
+    <link rel="modulepreload" crossorigin href="/assets/narration-DbHnz0qV.js">
     <link rel="modulepreload" crossorigin href="/assets/nav--u7iPYlS.js">
     <link rel="modulepreload" crossorigin href="/assets/packet-B0H15elv.js">
     <link rel="modulepreload" crossorigin href="/assets/settings-Dbyd6gmj.js">
@@ -243,15 +243,15 @@
     <link rel="modulepreload" crossorigin href="/assets/terminal-BAzpHtpY.js">
     <link rel="modulepreload" crossorigin href="/assets/tickets-D41ZMQpf.js">
     <link rel="modulepreload" crossorigin href="/assets/createLucideIcon-Bjbbp_KS.js">
-    <link rel="modulepreload" crossorigin href="/assets/useSharedWebSocket-BZxKaVNT.js">
-    <link rel="modulepreload" crossorigin href="/assets/Trans-wmTUDVyC.js">
-    <link rel="modulepreload" crossorigin href="/assets/useDesktop-DpiS8Uov.js">
+    <link rel="modulepreload" crossorigin href="/assets/useSharedWebSocket-DaWuiO0S.js">
+    <link rel="modulepreload" crossorigin href="/assets/Trans-D5eOjfvG.js">
+    <link rel="modulepreload" crossorigin href="/assets/useDesktop-DKNbOF0u.js">
     <link rel="modulepreload" crossorigin href="/assets/provider-capabilities-lePfeT_Y.js">
     <link rel="modulepreload" crossorigin href="/assets/save-OsUqVn99.js">
-    <link rel="modulepreload" crossorigin href="/assets/spending-Oov7p52A.js">
+    <link rel="modulepreload" crossorigin href="/assets/spending-DQDNtM8q.js">
     <link rel="modulepreload" crossorigin href="/assets/sparkles-DrY8hb0X.js">
     <link rel="modulepreload" crossorigin href="/assets/x-CBMI9ejn.js">
-    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-BD2bsRBe.js">
+    <link rel="modulepreload" crossorigin href="/assets/MinimizedChatsContext-CroAs6Kh.js">
     <link rel="modulepreload" crossorigin href="/assets/zap-CUOlvtT1.js">
     <link rel="modulepreload" crossorigin href="/assets/file-text-BcLCfcWZ.js">
     <link rel="modulepreload" crossorigin href="/assets/circle-x-CMYsN4ZH.js">
@@ -266,20 +266,20 @@
     <link rel="modulepreload" crossorigin href="/assets/search-Cq_gE3Ik.js">
     <link rel="modulepreload" crossorigin href="/assets/trash-2-BOU3WdZZ.js">
     <link rel="modulepreload" crossorigin href="/assets/triangle-alert-H9T4jAmh.js">
-    <link rel="modulepreload" crossorigin href="/assets/jira-api-CLrIvXFm.js">
+    <link rel="modulepreload" crossorigin href="/assets/jira-api-Bp0zXwjg.js">
     <link rel="modulepreload" crossorigin href="/assets/clsx-CjueKrWZ.js">
     <link rel="modulepreload" crossorigin href="/assets/utils-BC4DHlz2.js">
     <link rel="modulepreload" crossorigin href="/assets/dialog-CMgps2MY.js">
     <link rel="modulepreload" crossorigin href="/assets/lib-CGdyxIWg.js">
-    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-dpIo42JZ.js">
-    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-Dax4zqPF.js">
+    <link rel="modulepreload" crossorigin href="/assets/getTimezoneOffsetInMilliseconds-9JiGlFrx.js">
+    <link rel="modulepreload" crossorigin href="/assets/formatDistanceToNow-DZ3VWsHq.js">
     <link rel="modulepreload" crossorigin href="/assets/button-D1xExSTF.js">
-    <link rel="modulepreload" crossorigin href="/assets/project-repositories-BkyT8AjU.js">
-    <link rel="modulepreload" crossorigin href="/assets/RepositoryScopeSelector-D-jb4bI_.js">
-    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModalContext-BHmtj1As.js">
+    <link rel="modulepreload" crossorigin href="/assets/project-repositories-CadLZOnr.js">
+    <link rel="modulepreload" crossorigin href="/assets/RepositoryScopeSelector-CeCr6Jz-.js">
+    <link rel="modulepreload" crossorigin href="/assets/TicketDetailModalContext-YBJX3RmP.js">
     <link rel="modulepreload" crossorigin href="/assets/core-B3mKBIh5.js">
-    <link rel="modulepreload" crossorigin href="/assets/RepositoryDeliveries-NNorcGzT.js">
-    <link rel="modulepreload" crossorigin href="/assets/useRuntimeRuns-DBm1mul0.js">
+    <link rel="modulepreload" crossorigin href="/assets/RepositoryDeliveries-DJCm1pZr.js">
+    <link rel="modulepreload" crossorigin href="/assets/useRuntimeRuns-D3YMw9qx.js">
     <link rel="modulepreload" crossorigin href="/assets/event-Bt7f3wXe.js">
     <link rel="stylesheet" crossorigin href="/assets/index-Bfunvi6w.css">
   </head>

package/docs/internals/configuration.md

@@ -74,6 +74,8 @@ Project settings apply to a single project. Open them from the project's **Setti
 | **Freestyle pre-prompt** | Text prepended to Freestyle-mode launches (Claude and Kimi advertise this autonomous rail mode). |
 | **Budget** | Per-project daily spend cap (with queue auto-pause) and a per-job cost alert threshold. |
 | **Terminal Settings** | Per-project overrides for the terminal panel defaults (project override → app default → built-in). |
+| **Verification commands** | Repository checks Core runs after the developer finishes; failures go back to the developer (or the fixer). Stored under `verification` in `.specrails/agent-runtime.json`; an empty list lets the architect propose the project's own checks. |
+| **Setup commands** | Idempotent commands Core runs inside the repository checkout before every verification plan, for example `npx playwright install chromium`. Same entry shape as `verification` (`repositoryId`, `command`, `args`, optional `cwd`, `env`, `timeoutMs`, `key`, `label`), stored under `setup`, no auto-detection. Credential-like `env` keys are refused and `key` values must be unique across `setup` and `verification`. A failing setup command ends the run as blocked by the host environment. The list reaches Core only when the installed Core advertises the `setupCommands` capability; older cores receive the configuration without it and the run log records a one-line note. |
 
 > The project's **provider(s)** — **Claude, Codex, Gemini, Kimi, or any
 > compatible combination** — are chosen when you add the project and are

package/docs/internals/core-runtime-updates.md

@@ -13,15 +13,15 @@ framework is rejected rather than silently replacing an update.
 
 ## Persistence and publication
 
-The release bundle pins Core 6.2.1 in `desktop-release.yml` and
+The release bundle pins Core 6.4.0 in `desktop-release.yml` and
 `scripts/assemble-bundled-core.lock.json`. Core 6 is the Desktop-only engine: it
 publishes integration contract 5.1 (no standalone `update`) and ships only the
 implement and retry workflows (Batch was folded into implement; Desktop no
 longer requires `batch-implement` but stays compatible with Cores that still ship it). Update both pins together and check compatibility against
 the staged published package; retained runs still use their original runtime.
 
-The paired CI checkout uses the immutable Core 6.2.1 release commit
-`ae52a5ff0ff9dce024008adf16115e7f04d1ef35`. Bundle smoke checks use Node 22.22.3,
+The paired CI checkout uses the immutable Core 6.4.0 release commit
+`aa00781e962a30c22bbcdecc632bc2abcf3c97d2`. Bundle smoke checks use Node 22.22.3,
 matching Core's minimum supported Node version and the Desktop release runtime.
 
 Desktop updates retain the complete npm installation, including dependencies,

package/docs/internals/programmatic-agent-runtime.md

@@ -119,6 +119,8 @@ All routes are under `/api/projects/:projectId`:
 | `POST /agent-runtime/runs/:runId/resume` | Accept `{}`, `{ "approve": ["archive"] }`, `{ "recover": ["developer"] }`, explicit `invalidate` phase IDs, or `{ "answer": "…" }` for a pending question (required while one is open) |
 | `POST /agent-runtime/runs/:runId/cancel` | Cancel a continuation owned by this controller |
 
+Host blockers (Core `hostBlockers: 1` / `setupCommands: 1`): the Implement recipe opts its `verify` nodes into host-owned environment repair and the `blocked` outcome. Core emits `[environment] <command> (<repository>)` and `Environment: installed …` lines on the `verification-output` channel, so they reach the readable job log through the same projection as checks. A precondition Core cannot satisfy (no network for a browser download, registry credentials, a failing `setup` command, a missing toolchain) ends the run at `host-blocked` with `completion.blocker = { kind, reason, command, args, cwd, requiredAction, evidenceId? }`; a fixer-declared `blocker` ends it at `fixer-blocked`. The bridge maps that completion (`ok: false`) to `runtimeStatus: 'blocked'`, the run row shows the blocked badge and the loop log renders "Blocked by the host environment" with the localized kind, the failing command and cwd, the required action and a copy button. Older Core packages receive the pre-blocker definition and no `setup` list.
+
 Resume responds `202` after admission and continues asynchronously. Legacy phase IDs are `architect`, `developer`, `fixer`, `verify`, `reviewer` and `archive`. For engine v2, use `POST /loop-runs/:runId/resume` instead. `recover` contains exact attempt IDs from `GET /loop-runs/:runId/recovery`; approval and answer controls use pending interrupt IDs. Node paths are display context, not recovery identities. The saved-execution panel and job header expose explicit per-attempt selection. Core's lease and Desktop's execution/mount claim jointly prevent competing writers. Resident human pauses keep their original settlement callback; restart recovery reconnects to the frozen delivery allocation and terminal outbox.
 
 Desktop launches `node <Core>/dist/agent-runtime/cli.js` with structured argv (`--approve`, `--recover`, `--invalidate`, `--answer <text>` on resume) and consumes JSON lines for phase events (`workflow-event`), agent output (`agent-event`), verification output, trace spans (`span`: `{ traceId, spanId, name, stepId, attempt, visit, startedAt, endedAt, status, usage?, error? }`) and the terminal `runtime-result`. Spans are stored verbatim as job events for diagnostics and are not narrated in the log. `runtime status --compact` returns `state.traceId`, `pendingApproval`, `pendingQuestion` and per-step `{ status, visits }`. Desktop probes `runtime api` once per executable package content digest; `runtime validate --stdin` runs on every save. The job log shows phase transitions (`[runtime] step_started: developer`), live tool activity per role (`[developer] Read src/app.ts`, `[developer] Bash npm test`) and Core's own phase notes (architecture written, verification passed, review approved or corrections requested); the final JSON of architect and reviewer is not echoed. The narrated view (Relato) derives its milestones from the same events: each runtime phase, the tools used, correction loops and a stopped workflow with Core's structural reason. Accounting uses the invocation's new attempts, so resuming a completed phase does not bill its cumulative history twice. Status queries use `--compact`, are read-only and do not invoke providers; accumulated logs stay in Core's checkpoint instead of overflowing the process status response.

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "specrails-desktop",
-  "version": "2.60.0",
+  "version": "2.61.0",
   "license": "MIT",
   "repository": {
     "type": "git",

package/server/dist/modules/agent-runtime/runtime/agent-runtime-bridge.js

@@ -166,6 +166,18 @@ async function runAgentRuntimeInvocation(options) {
         config.providers = (0, agent_runtime_settings_1.stripDesktopConnectionFields)(config.providers, (0, agent_runtime_settings_1.coreConnectionFieldGates)(runtime.api?.capabilities));
         if (runtime.api?.capabilities?.configurableGuardrails !== 1)
             delete config.guardrails;
+        // Setup commands are a `setupCommands` capability: an older Core rejects the unknown key, so strip it and say so once in the run log.
+        if (config.setup !== undefined && !(0, agent_runtime_settings_1.coreSupportsSetupCommands)(runtime.api?.capabilities)) {
+            if (config.setup.length) {
+                try {
+                    options.onLine?.(`[runtime] setup commands ignored: the installed Core does not advertise setupCommands (${config.setup.length} configured)\n`);
+                }
+                catch { /* Advisory log observer. */ }
+            }
+            delete config.setup;
+        }
+        else if (config.setup)
+            config.setup = scopedHostChecks(config.setup, admittedContext.repositories);
         if (definitionEngine && (runtime.api?.capabilities?.engineV2 !== 1 || runtime.api?.capabilities?.workflowDefinitions !== 1))
             throw new Error('engine_unsupported: Update Core to run workflow definitions');
         const compilationConfig = structuredClone(config);

package/server/dist/modules/agent-runtime/runtime/agent-runtime-effective-config.js

@@ -76,6 +76,8 @@ function resolveEffectiveRuntimeConfig(input, options) {
         }
     fillDefaultRoleModels(config);
     config.verification = config.verification.filter(check => options.repositoryIds.includes(check.repositoryId));
+    if (config.setup)
+        config.setup = config.setup.filter(check => options.repositoryIds.includes(check.repositoryId));
     return { config, origins: { architect: override ? 'explicit-launch-override' : options.source, developer: override ? 'explicit-launch-override' : options.source, reviewer: override ? 'explicit-launch-override' : options.source } };
 }
 /**

package/server/dist/modules/agent-runtime/runtime/agent-runtime-settings-router.js

@@ -21,6 +21,10 @@ function withDefaultRoleModels(body) {
     return { ...body, agents: filled.agents, ...(filled.roles ? { roles: filled.roles } : {}), ...(filled.fixer ? { fixer: filled.fixer } : {}) };
 }
 const loop_role_engines_1 = require("../../loops/runtime/loop-role-engines");
+/** The settings API always answers `setup` as an array; the file keeps it absent until the user saves one. */
+function withSetupList(config) {
+    return config ? { ...config, setup: config.setup ?? [] } : config;
+}
 function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
     /** Guardrail catalog of the loaded Core (configurable-guardrails): ids + phase; the UI owns labels. `supported:false` on older cores. */
     router.get('/:projectId/agent-runtime/guardrails', async (_req, res) => {
@@ -70,7 +74,7 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
                 openRolesAvailable = capabilities?.openRoles === 1;
             }
             catch { /* Ordinary settings remain readable without capability support. */ }
-            res.json({ configured, config, runtimeAvailable: (0, agent_runtime_loader_1.findCoreAgentRuntimeEntry)() !== null, efficiencyAvailable, openRolesAvailable,
+            res.json({ configured, config: withSetupList(config), runtimeAvailable: (0, agent_runtime_loader_1.findCoreAgentRuntimeEntry)() !== null, efficiencyAvailable, openRolesAvailable,
                 workflowRoleDefaults: openRolesAvailable && config ? (0, agent_runtime_effective_config_1.workflowRoleDefaults)(config) : {} });
         }
         catch (err) {
@@ -147,7 +151,7 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
                 }
             }
             const saved = (0, agent_runtime_settings_1.saveAgentRuntimeConfig)(ctx(req).project, config);
-            res.json({ configured: true, config: saved, runtimeAvailable, efficiencyAvailable, openRolesAvailable });
+            res.json({ configured: true, config: withSetupList(saved), runtimeAvailable, efficiencyAvailable, openRolesAvailable });
         }
         catch (err) {
             const validation = err instanceof agent_runtime_settings_1.AgentRuntimeConfigError;

package/server/dist/modules/agent-runtime/runtime/agent-runtime-settings.js

@@ -25,6 +25,7 @@ exports.loadRuntimeRolePrompts = loadRuntimeRolePrompts;
 exports.saveRuntimeRolePrompts = saveRuntimeRolePrompts;
 exports.validateRuntimeProviderOverride = validateRuntimeProviderOverride;
 exports.forCoreRuntime = forCoreRuntime;
+exports.coreSupportsSetupCommands = coreSupportsSetupCommands;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const node_os_1 = __importDefault(require("node:os"));
@@ -136,17 +137,18 @@ function validateLoopRuntimeSettings(input, providers = loadRuntimeProviders())
     const config = validateAgentRuntimeConfig({ ...input, enabled: true, providers: portableProviders, verification: [] });
     if (['architect', 'developer', 'reviewer', 'fixer'].some(role => !config.rolePrompts?.[role]?.trim()))
         throw new AgentRuntimeConfigError('Loop agents require an explicit definition for architect, developer, reviewer and fixer');
-    const { enabled: _enabled, providers: _providers, verification: _checks, ...settings } = config;
+    const { enabled: _enabled, providers: _providers, verification: _checks, setup: _setup, ...settings } = config;
     return settings;
 }
 /** Read only repository checks from the old project file. Role migration is explicit. */
 function loadLoopRuntimeConfig(file, input, selection = { provider: 'claude' }) {
-    let verification = [];
+    let verification = [], setup = undefined;
     try {
         const saved = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
         if (!saved || typeof saved !== 'object' || Array.isArray(saved))
             throw new AgentRuntimeConfigError('Saved runtime configuration must be an object');
         verification = saved.verification ?? [];
+        setup = saved.setup;
     }
     catch (error) {
         if (error.code !== 'ENOENT')
@@ -163,7 +165,7 @@ function loadLoopRuntimeConfig(file, input, selection = { provider: 'claude' })
         settings.fixer = inherit(settings.fixer);
     for (const [role, agent] of Object.entries(settings.roles ?? {}))
         settings.roles[role] = inherit(agent);
-    return validateAgentRuntimeConfig({ ...settings, providers, enabled: true, verification });
+    return validateAgentRuntimeConfig({ ...settings, providers, enabled: true, verification, ...(setup !== undefined ? { setup } : {}) });
 }
 const CLI_PROVIDERS = ['claude', 'codex', 'gemini', 'kimi'];
 const ROLES = ['architect', 'developer', 'reviewer'];
@@ -260,10 +262,12 @@ function validateAgentRuntimeConfig(input) {
         if (!Number.isFinite(value) || (key !== 'maxCostUsd' && !Number.isSafeInteger(value)))
             throw new AgentRuntimeConfigError('Workflow limits must be finite, safe numbers');
     }
-    const keys = config.verification.flatMap(command => command.key ? [command.key] : []);
+    // `setup` entries share the verification entry shape and rules (Core validates both with one validator; keys are unique across the two lists).
+    const hostCommands = [...config.verification, ...(config.setup ?? [])];
+    const keys = hostCommands.flatMap(command => command.key ? [command.key] : []);
     if (new Set(keys).size !== keys.length)
         throw new AgentRuntimeConfigError('Verification check keys must be unique');
-    for (const command of config.verification) {
+    for (const command of hostCommands) {
         for (const value of [command.label, ...(command.policy?.inputs ?? []), ...(command.policy?.toolchainInputs ?? []), ...(command.policy?.resources ?? [])])
             if (value !== undefined && (!value.trim() || value.includes('\0')))
                 throw new AgentRuntimeConfigError('Invalid verification label or policy input');
@@ -482,7 +486,7 @@ function validateRuntimeProviderOverride(value) {
         throw new AgentRuntimeConfigError('Invalid runtime provider override effort');
     return structuredClone(raw);
 }
-/** Older Core runtimes reject unknown top-level keys: drop `guardrails` unless the loaded Core advertises `configurableGuardrails`. */
+/** Older Core runtimes reject unknown top-level keys: drop `guardrails` unless the loaded Core advertises `configurableGuardrails`, and `setup` unless it advertises `setupCommands`. */
 function forCoreRuntime(config, capabilities) {
     let out = config;
     if (capabilities?.openRoles !== 1 && out.roles !== undefined) {
@@ -495,6 +499,10 @@ function forCoreRuntime(config, capabilities) {
         const { guardrails: _dropped, ...rest } = out;
         out = rest;
     }
+    if (!coreSupportsSetupCommands(capabilities) && out.setup !== undefined) {
+        const { setup: _dropped, ...rest } = out;
+        out = rest;
+    }
     // The per-role thinking switch is known only to cores advertising `roleThinkingControl`.
     if (capabilities?.roleThinkingControl !== 1 && ([...Object.values(out.agents ?? {}), ...Object.values(out.roles ?? {})].some(agent => agent?.thinking !== undefined) || out.fixer?.thinking !== undefined)) {
         const strip = (agent) => { const { thinking: _t, ...rest } = agent; return rest; };
@@ -502,3 +510,7 @@ function forCoreRuntime(config, capabilities) {
     }
     return out;
 }
+/** Core advertises `setupCommands: 1` when its verify piece runs `RuntimeConfig.setup` before each verification plan. */
+function coreSupportsSetupCommands(capabilities) {
+    return (capabilities?.setupCommands ?? 0) >= 1;
+}

package/server/dist/modules/loops/runtime/loop-core-factory.js

@@ -4,9 +4,9 @@ exports.coreFactoryGraph = coreFactoryGraph;
 const loop_implement_recipe_1 = require("./loop-implement-recipe");
 const loop_agents_1 = require("./loop-agents");
 /** App-owned definition graphs. Core supplies schemas, execution and canonical versions. */
-function coreFactoryGraph(mode, independent = false, configurable = false) {
+function coreFactoryGraph(mode, independent = false, configurable = false, capabilities) {
     if (mode === 'implement' && configurable)
-        return (0, loop_implement_recipe_1.configurableImplementGraph)();
+        return (0, loop_implement_recipe_1.configurableImplementGraph)(capabilities);
     const nodes = [{ id: 'start', type: 'start', position: { x: 0, y: 0 } }];
     const edges = [];
     const config = { maxIterations: 12, maxTransitions: 120, timeoutMinutes: 0, aiStepTimeoutMinutes: 0,

package/server/dist/modules/loops/runtime/loop-definition.js

@@ -41,6 +41,7 @@ function compileLoopToDefinition(graph, launch) {
                         : {}),
                     ...(typeof node.data?.exit === 'string' ? { exit: node.data.exit } : {}),
                     ...(typeof node.data?.reason === 'string' ? { reason: node.data.reason } : {}),
+                    ...(typeof node.data?.blockerFrom === 'string' ? { blockerFrom: node.data.blockerFrom } : {}),
                 }
                 : node.data.params;
             const promptRole = node.id === 'fix' ? 'fixer' : node.id === 'prepare' ? 'architect' : rawParams.access === 'read' ? 'reviewer' : 'developer';

package/server/dist/modules/loops/runtime/loop-factory.js

@@ -94,7 +94,7 @@ const FACTORY_BY_ID = new Map([
 function factoryLoopsForCapabilities(capabilities) {
     if (capabilities?.engineV2 !== 1 || capabilities.workflowDefinitions !== 1)
         return exports.FACTORY_LOOPS;
-    return exports.FACTORY_LOOPS.map(factory => ({ ...factory, graph: (0, loop_core_factory_1.coreFactoryGraph)(factory.id === 'factory:implement' ? 'implement' : factory.id === 'factory:freestyle' ? 'freestyle' : 'quick-sdd', capabilities.implementationSteps === 1, capabilities.workflowAgentSteps === 1) }));
+    return exports.FACTORY_LOOPS.map(factory => ({ ...factory, graph: (0, loop_core_factory_1.coreFactoryGraph)(factory.id === 'factory:implement' ? 'implement' : factory.id === 'factory:freestyle' ? 'freestyle' : 'quick-sdd', capabilities.implementationSteps === 1, capabilities.workflowAgentSteps === 1, capabilities) }));
 }
 function getFactoryLoop(id, capabilities) {
     const legacy = FACTORY_BY_ID.get(id);

package/server/dist/modules/loops/runtime/loop-graph.js

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.CORE_NODE_KINDS = void 0;
+exports.effectivePieceOutcomes = effectivePieceOutcomes;
 exports.isDefinitionReviewerPath = isDefinitionReviewerPath;
 exports.isDefinitionGraph = isDefinitionGraph;
 exports.assertDefinitionGraph = assertDefinitionGraph;
@@ -16,6 +17,12 @@ exports.interpolateSpec = interpolateSpec;
 exports.CORE_NODE_KINDS = ['prompt', 'role-turn', 'decider', 'condition', 'assign', 'verify', 'shell',
     'artifact-contract', 'openspec-validate', 'openspec-archive', 'approval', 'question', 'gate', 'map', 'join',
     'component', 'implementation', 'implementation-step', 'end'];
+/** Mirror of Core's `getOutcomes(params)`: `verify` advertises `blocked` only when the node opts into host blockers. */
+function effectivePieceOutcomes(descriptor, params) {
+    if (descriptor.kind === 'verify' && params?.hostBlockers !== true)
+        return descriptor.outcomes.filter(outcome => outcome !== 'blocked');
+    return descriptor.outcomes;
+}
 function isDefinitionReviewerPath(graph, value) {
     if (typeof value !== 'string' || !value || value.length > 2048)
         return false;
@@ -201,7 +208,7 @@ function validateLoopGraph(graph, catalog) {
             const labels = new Set();
             for (const edge of out) {
                 if (typeof edge.label !== 'string' || !/^[a-z][a-z0-9-]{0,31}$/.test(edge.label) || labels.has(edge.label) ||
-                    (descriptor && !descriptor.outcomes.includes(edge.label))) {
+                    (descriptor && !effectivePieceOutcomes(descriptor, node.data?.params).includes(edge.label))) {
                     errors.push({ code: 'INVALID_BRANCH', nodeId: node.id, edgeId: edge.id, message: 'Core outcome edges need unique labels advertised by the piece.' });
                 }
                 if (edge.label)

package/server/dist/modules/loops/runtime/loop-implement-recipe.js

@@ -1,5 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.supportsHostBlockers = exports.HOST_BLOCKER_KINDS = void 0;
 exports.configurableImplementGraph = configurableImplementGraph;
 const agent_runtime_settings_1 = require("../../agent-runtime/runtime/agent-runtime-settings");
 const loop_agents_1 = require("./loop-agents");
@@ -9,8 +10,17 @@ const strings = { type: 'array', items: string, maxItems: 100 };
 const score = { type: 'number', minimum: 0, maximum: 100 };
 const aspects = { type_correctness: 60, pattern_adherence: 60, test_coverage: 60, security: 75, architectural_alignment: 60 };
 const reviewPolicy = 'approved == true; issues must be empty; score >= 70; ' + Object.entries(aspects).map(([aspect, threshold]) => `${aspect} >= ${threshold}`).join('; ');
-/** The recipe, roles, schemas and decisions are Desktop data, never Core phases. */
-function configurableImplementGraph() {
+exports.HOST_BLOCKER_KINDS = ['network', 'credential', 'environment-variable', 'toolchain', 'setup', 'environment', 'scope'];
+/** Fixer/developer structured `blocker`: the host ends the run on it instead of counting a correction round. */
+const blocker = objectSchema({ kind: { enum: [...exports.HOST_BLOCKER_KINDS] }, command: string, cwd: string, evidence: string, requiredAction: string }, ['kind', 'requiredAction']);
+/** Host-owned environment repair and structured blockers need the paired Core generation. */
+const supportsHostBlockers = (capabilities) => capabilities?.hostBlockers === 1;
+exports.supportsHostBlockers = supportsHostBlockers;
+/** The recipe, roles, schemas and decisions are Desktop data, never Core phases.
+ *  `capabilities` are the installed Core's advertised runtime capabilities: without `hostBlockers`
+ *  the verify nodes compile exactly as before (no `setup`, no `blocked` edge, no `blockerFrom`). */
+function configurableImplementGraph(capabilities) {
+    const hostBlockers = (0, exports.supportsHostBlockers)(capabilities);
     const agents = (0, loop_agents_1.defaultLoopAgents)();
     agents.roles = {
         plan: { ...agents.agents.architect, access: 'read', artifacts: 'all', openspecSkill: 'openspec-ff-change', prompt: (0, agent_runtime_settings_1.inheritedRolePrompt)(agents.rolePrompts, 'architect') },
@@ -24,7 +34,11 @@ function configurableImplementGraph() {
         for (const [outcome, target] of Object.entries(outcomes))
             edges.push({ id: `e-${id}-${outcome}`, source: id, target, label: outcome });
     };
-    const turn = (id, label, roleId, prompt, schema, next) => node(id, label, 'role-turn', { roleId, prompt, structuredOutput: schema, sessionContinuity: 'none' }, { next, invalid: 'failed', failed: 'failed' });
+    const turn = (id, label, roleId, prompt, schema, next, extra = {}) => node(id, label, 'role-turn', { roleId, prompt, structuredOutput: schema, sessionContinuity: 'none', ...extra }, { next, invalid: 'failed', failed: 'failed' });
+    const verifyParams = { commands: 'configured', additionalCommandsFrom: 'architect', ...(hostBlockers ? { setup: 'configured', hostBlockers: true } : {}) };
+    const verifyEnds = (passed, failed, blockedEnd) => ({ pass: passed, fail: failed, failed: 'failed', ...(hostBlockers ? { blocked: blockedEnd } : {}) });
+    // Same Core generation as host blockers: older role-turn schemas reject unknown params.
+    const writes = hostBlockers ? { verificationProposalsFrom: 'architect' } : {};
     const change = '{{run.changeId}}';
     turn('architect', 'Architect', 'plan', `Plan the frozen ticket requirements for OpenSpec change ${change}. Use the bound official fast-forward skill. Author complete proposal, design, delta specs and actionable tasks. Propose existing repository verification commands for repositories with no configured checks. Return confidence, question (empty when none), and verification [{repositoryId,command,args,cwd?}]. When revisiting low confidence, investigate the missing repository evidence before asking again. Context and human answers: {{history.text}}`, objectSchema({ confidence: { enum: ['high', 'medium', 'low'] }, question: string, verification: { type: 'array', maxItems: 20, items: objectSchema({ repositoryId: string, command: string, args: strings, cwd: string }, ['repositoryId', 'command', 'args']) } }), 'confidence');
     node('confidence', 'Planning confidence', 'condition', { expr: '$outputs.architect.structured.confidence != "low"' }, { true: 'validate', false: 'investigate' });
@@ -35,10 +49,10 @@ function configurableImplementGraph() {
     node('validate', 'Validate OpenSpec', 'openspec-validate', { change }, { pass: 'freeze', fail: 'architect', failed: 'failed' });
     node('freeze', 'Freeze approved artifacts', 'artifact-contract', { change, contractId: 'plan', action: 'freeze' }, { pass: 'initialize-corrections', fail: 'architect', failed: 'failed' });
     node('initialize-corrections', 'Initialize automatic correction budget', 'assign', { set: { correctionAttempts: 0, correctionLimit: 3 } }, { next: 'developer', failed: 'failed' });
-    const implementation = objectSchema({ summary: string, incomplete: strings });
-    turn('developer', 'Developer', 'build', `Implement every approved task for change ${change} using the bound official apply skill. Preserve proposal, design and specs; only tick tasks you completed. Report summary and incomplete task descriptions. Prior execution evidence and human answers: {{history.text}}`, implementation, 'tasks');
+    const implementation = objectSchema({ summary: string, incomplete: strings, blocker }, ['summary', 'incomplete']);
+    turn('developer', 'Developer', 'build', `Implement every approved task for change ${change} using the bound official apply skill. Preserve proposal, design and specs; only tick tasks you completed. Report summary and incomplete task descriptions. Prior execution evidence and human answers: {{history.text}}`, implementation, 'tasks', writes);
     node('tasks', 'Check artifacts and completed tasks', 'artifact-contract', { change, contractId: 'plan', action: 'check', requireCompletedTasks: true }, { pass: 'verify', fail: 'developer', failed: 'failed' });
-    node('verify', 'Verify candidate', 'verify', { commands: 'configured', additionalCommandsFrom: 'architect' }, { pass: 'reviewer', fail: 'correction-context', failed: 'failed' });
+    node('verify', 'Verify candidate', 'verify', verifyParams, verifyEnds('reviewer', 'correction-context', 'host-blocked'));
     turn('reviewer', 'Reviewer', 'assess', `Review change ${change} read-only against all approved artifacts and frozen ticket acceptance criteria. Inspect real code and the host verification evidence: {{outputs.verify}}. Return approved, summary, issues, score (0-100), and aspects. Acceptance policy: ${reviewPolicy}. For any rejection or below-threshold score, explain the concrete unmet requirement and actionable repair in summary and issues; passing commands do not prove every acceptance obligation. Prior execution: {{history.text}}`, objectSchema({ approved: { type: 'boolean' }, summary: string, issues: strings, score, aspects: objectSchema(Object.fromEntries(Object.keys(aspects).map(aspect => [aspect, score]))) }), 'review-policy');
     node('review-policy', 'Review acceptance policy', 'condition', { expr: ['$outputs.reviewer.structured.approved == true', '$outputs.reviewer.structured.issues.length == 0', '$outputs.reviewer.structured.score >= 70', ...Object.entries(aspects).map(([aspect, threshold]) => `$outputs.reviewer.structured.aspects.${aspect} >= ${threshold}`)].join(' && ') }, { true: 'approve', false: 'correction-context' });
     node('correction-context', 'Select current review findings', 'condition', { expr: '$outputs.verify.valid == true && exists($outputs.reviewer.candidateHash) && $outputs.reviewer.candidateHash == $outputs.verify.candidateHash' }, { true: 'capture-review', false: 'clear-review' });
@@ -46,13 +60,18 @@ function configurableImplementGraph() {
     node('clear-review', 'Clear outdated review findings', 'assign', { set: { latestReview: 'No reviewer findings for the current verified candidate. Diagnose the current host verification failure first.' } }, { next: 'correction-budget', failed: 'failed' });
     node('correction-budget', 'Check automatic correction budget', 'condition', { expr: '$vars.correctionAttempts < $vars.correctionLimit' }, { true: 'begin-correction', false: 'correction-exhausted' });
     node('begin-correction', 'Count automatic correction attempt', 'assign', { increment: { correctionAttempts: 1 } }, { next: 'fixer', failed: 'failed' });
-    turn('fixer', 'Fixer', 'correct', `Correct the reported implementation, test or review failure for change ${change} using the bound apply skill and preserving approved artifacts. Read failureSummary, command, cwd, exitCode and evidenceId first; use read_verification_evidence for truncated evidence. If Host verification is valid, repair the concrete rejected review obligation or below-threshold aspect instead of only rerunning green commands. Acceptance policy: ${reviewPolicy}. Reproduce the exact focused failure, inspect the assertion and tested code, then apply the smallest repair that preserves the required behavior. An unchanged filename does not prove an unrelated failure. A mandatory test inside the admitted workspace may receive a proven formatting/compatibility repair while retaining every required guard. Report diagnosis, focused commands with original exit codes, repair and unresolved failures in summary and incomplete. If the cause cannot be repaired within scope, explain the evidence and required action; any unchanged correction stops this run even when host checks pass. Do not make unrelated edits merely to change the candidate hash. Host verification: {{outputs.verify}}. Latest review findings for this candidate: {{run.latestReview}}. Prior execution: {{history.text}}`, implementation, 'correction-progress');
+    turn('fixer', 'Fixer', 'correct', `Correct the reported implementation, test or review failure for change ${change} using the bound apply skill and preserving approved artifacts. Read failureSummary, command, cwd, exitCode and evidenceId first; use read_verification_evidence for truncated evidence. If Host verification is valid, repair the concrete rejected review obligation or below-threshold aspect instead of only rerunning green commands. Acceptance policy: ${reviewPolicy}. Reproduce the exact focused failure, inspect the assertion and tested code, then apply the smallest repair that preserves the required behavior. An unchanged filename does not prove an unrelated failure. A mandatory test inside the admitted workspace may receive a proven formatting/compatibility repair while retaining every required guard. Report diagnosis, focused commands with original exit codes, repair and unresolved failures in summary and incomplete. If the cause is a host precondition or environment blocker outside this change, make no edits and return the structured blocker (kind, command, cwd, evidence, requiredAction): the host ends the run with your required action. Any other unchanged correction stops this run even when host checks pass. Do not make unrelated edits merely to change the candidate hash. Host verification: {{outputs.verify}}. Latest review findings for this candidate: {{run.latestReview}}. Prior execution: {{history.text}}`, implementation, 'correction-blocker', writes);
+    node('correction-blocker', 'Fixer reported a host blocker', 'condition', { expr: 'exists($outputs.fixer.structured.blocker) && $outputs.fixer.structured.blocker != null' }, { true: 'fixer-blocked', false: 'correction-progress' });
     node('correction-progress', 'Check correction progress', 'condition', { expr: 'exists($outputs.fixer.candidateHash) && $outputs.fixer.candidateHash != null && $outputs.fixer.candidateHash != $outputs.verify.candidateHash' }, { true: 'tasks', false: 'correction-stalled' });
     node('approve', 'Approve archive', 'approval', { reason: `Approve archiving the reviewed and verified candidate for change ${change}.`, bindCandidate: true, enabled: agents.approvalBeforeArchive === true }, { next: 'approval-policy' });
     node('approval-policy', 'Approval decision', 'condition', { expr: '$outputs.approve.response.approved == true' }, { true: 'archive', false: 'failed' });
     node('archive', 'Archive OpenSpec', 'openspec-archive', { change, allowArchived: true, requiresVerified: true, reviewedCandidate: '{{outputs.reviewer.candidateHash}}', approvedCandidate: '{{outputs.approve.candidateHash}}' }, { next: 'verify-archive', failed: 'verify' });
-    node('verify-archive', 'Verify archived candidate', 'verify', { commands: 'configured', additionalCommandsFrom: 'architect' }, { pass: 'done', fail: 'failed', failed: 'failed' });
-    nodes.push({ id: 'done', type: 'end', position: { x: 0, y: nodes.length * 140 }, data: { outcome: 'success', requiresVerified: true } }, { id: 'failed', type: 'end', position: { x: 360, y: nodes.length * 140 }, data: { outcome: 'failure' } }, { id: 'correction-stalled', type: 'end', position: { x: 720, y: nodes.length * 140 }, data: { outcome: 'failure', reason: `Automatic correction made no candidate changes. Host verification is valid: {{outputs.verify.valid}}. Acceptance policy: ${reviewPolicy}. Latest review findings: {{run.latestReview}}. Fixer diagnosis: {{outputs.fixer.structured.summary}}` } }, { id: 'correction-exhausted', type: 'end', position: { x: 1080, y: nodes.length * 140 }, data: { outcome: 'failure', reason: `Automatic correction limit reached ({{run.correctionAttempts}}/{{run.correctionLimit}}). Acceptance policy: ${reviewPolicy}. Latest review findings: {{run.latestReview}}. Fixer diagnosis: {{outputs.fixer.structured.summary}}. Host verification: {{outputs.verify}}` } });
+    node('verify-archive', 'Verify archived candidate', 'verify', verifyParams, verifyEnds('done', 'failed', 'host-blocked-archive'));
+    nodes.push({ id: 'done', type: 'end', position: { x: 0, y: nodes.length * 140 }, data: { outcome: 'success', requiresVerified: true } }, { id: 'failed', type: 'end', position: { x: 360, y: nodes.length * 140 }, data: { outcome: 'failure' } }, { id: 'correction-stalled', type: 'end', position: { x: 720, y: nodes.length * 140 }, data: { outcome: 'failure', reason: `Automatic correction made no candidate changes. Host verification is valid: {{outputs.verify.valid}}. Acceptance policy: ${reviewPolicy}. Latest review findings: {{run.latestReview}}. Fixer diagnosis: {{outputs.fixer.structured.summary}}` } }, { id: 'correction-exhausted', type: 'end', position: { x: 1080, y: nodes.length * 140 }, data: { outcome: 'failure', reason: `Automatic correction limit reached ({{run.correctionAttempts}}/{{run.correctionLimit}}). Acceptance policy: ${reviewPolicy}. Latest review findings: {{run.latestReview}}. Fixer diagnosis: {{outputs.fixer.structured.summary}}. Host verification: {{outputs.verify}}` } }, { id: 'fixer-blocked', type: 'end', position: { x: 1440, y: nodes.length * 140 }, data: { outcome: 'failure', reason: 'Fixer reported a host blocker ({{outputs.fixer.structured.blocker.kind}}): {{outputs.fixer.structured.blocker.requiredAction}} Evidence: {{outputs.fixer.structured.blocker.evidence}}', ...(hostBlockers ? { blockerFrom: 'fixer' } : {}) } });
+    if (hostBlockers) {
+        const hostBlocked = (id, source) => ({ id, type: 'end', position: { x: 1800, y: nodes.length * 140 }, data: { outcome: 'failure', blockerFrom: source, reason: `Host blocker ({{outputs.${source}.blocker.kind}}): {{outputs.${source}.blocker.reason}} Required action: {{outputs.${source}.blocker.requiredAction}}` } });
+        nodes.push(hostBlocked('host-blocked', 'verify'), hostBlocked('host-blocked-archive', 'verify-archive'));
+    }
     edges.unshift({ id: 'e-start', source: 'start', target: 'architect' });
     return { nodes, edges, config: { maxIterations: 12, maxTransitions: 200, timeoutMinutes: 0, aiStepTimeoutMinutes: 0, change: 'new', journal: 'ledger-only', ticketScope: 'all', agents, reviewerStepId: 'reviewer' } };
 }

package/server/dist/modules/loops/runtime/loop-templates.js

@@ -341,10 +341,10 @@ const CORE_STARTER_SHAPES = {
 };
 /** Core definition graph for one of the eight starters. Deterministic: same id ⇒
  *  structurally identical graph (positions included). */
-function coreStarterGraph(id, independent = false, configurable = false) {
+function coreStarterGraph(id, independent = false, configurable = false, capabilities) {
     const shape = CORE_STARTER_SHAPES[id];
     if (shape === 'ship' && configurable)
-        return (0, loop_core_factory_1.coreFactoryGraph)('implement', true, true);
+        return (0, loop_core_factory_1.coreFactoryGraph)('implement', true, true, capabilities);
     const { prompt, goal, maxIterations } = STARTER_TEXT[id];
     const nodes = [{ id: 'start', type: 'start', position: { x: COL_X, y: 0 } }];
     const edges = [];
@@ -438,7 +438,7 @@ function loopTemplatesForCapabilities(capabilities) {
             ...template,
             description: CORE_STARTER_DESCRIPTIONS[template.id],
             ...(readOnly ? { readOnly: true } : {}),
-            graph: coreStarterGraph(template.id, capabilities?.implementationSteps === 1, capabilities?.workflowAgentSteps === 1),
+            graph: coreStarterGraph(template.id, capabilities?.implementationSteps === 1, capabilities?.workflowAgentSteps === 1, capabilities),
         };
     });
 }

package/server/dist/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": {