specrails-desktop 2.64.1 → 2.65.0

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

@@ -1,10 +1,14 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.RUNTIME_HOST_ENV_KEYS = void 0;
+exports.BASELINE_CHARACTERIZATION_FAILED = exports.RUNTIME_HOST_ENV_KEYS = void 0;
 exports.runtimeChangeName = runtimeChangeName;
 exports.scopedHostChecks = scopedHostChecks;
 exports.readFrozenRuntimeHost = readFrozenRuntimeHost;
+exports.coreProviderEnv = coreProviderEnv;
+exports.runtimeErrorText = runtimeErrorText;
+exports.applyPhase3RuntimeSwitches = applyPhase3RuntimeSwitches;
 exports.runAgentRuntimeInvocation = runAgentRuntimeInvocation;
+exports.retainedRuntimeSupportsPause = retainedRuntimeSupportsPause;
 exports.assertRetainedForkSupport = assertRetainedForkSupport;
 exports.runAgentRuntimeControl = runAgentRuntimeControl;
 const agent_runtime_verification_suggestions_1 = require("./agent-runtime-verification-suggestions");
@@ -129,6 +133,50 @@ function readFrozenRuntimeHost(contextPath, baseEnv, runId) {
         delete env[key];
     return { cwd: host.cwd, env: { ...env, ...host.env, SPECRAILS_EXECUTION_CONTEXT: contextPath } };
 }
+/** Provider CLIs that Core spawns inherit this environment. Gemini CLI refuses
+ * headless runs in a folder the user never trusted interactively (exit 55), and
+ * rail worktrees and fresh projects never are. Every other Desktop Gemini spawn
+ * already trusts its admitted workspace the same way; an explicit value wins. */
+function coreProviderEnv(env) {
+    return env.GEMINI_CLI_TRUST_WORKSPACE === undefined ? { ...env, GEMINI_CLI_TRUST_WORKSPACE: 'true' } : env;
+}
+/** Core's blocker when characterization tests fail on the unchanged code (baseline on touch). */
+exports.BASELINE_CHARACTERIZATION_FAILED = 'baseline_characterization_failed';
+/**
+ * Human-readable text of a structured runtime error. The baseline blocker is
+ * spelled out: the run stopped BEFORE the module was edited because the tests
+ * that describe today's behaviour do not pass on today's code.
+ */
+function runtimeErrorText(error) {
+    if (!error)
+        return undefined;
+    if (error.code === exports.BASELINE_CHARACTERIZATION_FAILED) {
+        const detail = error.message?.trim();
+        return `Baseline blocked: the characterization tests do not pass on the unchanged code, so the run stopped before editing the module. Fix the tests (or the verification plan) so they describe today's behaviour, then resume.${detail ? ` Core: ${detail}` : ''}`;
+    }
+    return error.message;
+}
+/**
+ * Phase-3 config keys (Core contract 5.7). An older Core rejects unknown
+ * keys, so `baselineOnTouch` and `architect.clarifications` reach Core only
+ * when it announces `baselineOnTouch: 1` / `architectClarifications: 1`; the
+ * project's `baselineOnTouch` setting turns the switch on. Mutates `config`.
+ */
+function applyPhase3RuntimeSwitches(config, capabilities, project) {
+    if (capabilities?.baselineOnTouch === 1) {
+        if (project?.baselineOnTouch)
+            config.baselineOnTouch = true;
+    }
+    else
+        delete config.baselineOnTouch;
+    if (capabilities?.architectClarifications !== 1 && config.architect?.clarifications !== undefined) {
+        const { clarifications: _dropped, ...architect } = config.architect;
+        if (Object.keys(architect).length)
+            config.architect = architect;
+        else
+            delete config.architect;
+    }
+}
 /** Core owns the complete agent workflow in one managed process. The existing
  * rail's cancellation and worktree ownership remain in Desktop. */
 async function runAgentRuntimeInvocation(options) {
@@ -179,6 +227,7 @@ async function runAgentRuntimeInvocation(options) {
         }
         else if (config.setup)
             config.setup = scopedHostChecks(config.setup, admittedContext.repositories);
+        applyPhase3RuntimeSwitches(config, runtime.api?.capabilities, options.projectRuntime);
         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);
@@ -304,7 +353,7 @@ async function runAgentRuntimeInvocation(options) {
         const stepFailures = new Map();
         let timer;
         const child = (0, node_child_process_1.spawn)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), args, {
-            cwd: options.cwd, env: (0, win_spawn_1.windowsSpawnEnv)(options.env), shell: false, windowsHide: true,
+            cwd: options.cwd, env: (0, win_spawn_1.windowsSpawnEnv)(coreProviderEnv(options.env)), shell: false, windowsHide: true,
             stdio: ['ignore', 'pipe', 'pipe'],
         });
         // Always leave a terminal result, including synchronous observer failures.
@@ -446,14 +495,15 @@ async function runAgentRuntimeInvocation(options) {
                 invalidProtocol = true;
             const acceptanceBlocked = definitionEngine && result?.status === 'succeeded' && result.completion && (!result.completion.ok || requiresVerified && !result.completion.verified);
             const validPause = definitionEngine && code === 2 && result?.status === 'paused';
+            const hostPause = validPause ? readHostPause(result?.pause) : undefined;
             const failed = (!validPause && (code !== 0 || result?.status !== 'succeeded')) || invalidProtocol || timedOut || Boolean(observerError) || Boolean(acceptanceBlocked);
-            const runtimeError = typeof result?.error === 'string' ? result.error : result?.error?.message;
+            const runtimeError = typeof result?.error === 'string' ? result.error : runtimeErrorText(result?.error);
             const completionError = Array.isArray(result?.completion?.reasons) ? result.completion.reasons.filter(reason => typeof reason === 'string' && reason.trim()).join('; ').slice(0, 4_000) : '';
             const runtimeStatus = invalidProtocol || timedOut || observerError || (result?.status === 'paused' && !validPause) || (result?.status === 'succeeded' && code !== 0) ? 'failed' : acceptanceBlocked ? 'blocked' : ['succeeded', 'paused', 'failed', 'blocked', 'cancelled'].includes(result?.status ?? '') ? result.status : 'failed';
             const errorText = observerError ?? (timedOut ? 'Programmatic workflow timed out; inspect its checkpoint before recovery'
                 : invalidProtocol ? 'Core returned an invalid runtime event stream'
                     : acceptanceBlocked ? result?.completion?.reasons.join('; ') || 'Core workflow acceptance or required verification is not satisfied'
-                        : runtimeError ?? (result?.status === 'paused' ? (typeof result.pendingQuestion?.question === 'string' && result.pendingQuestion.question.trim()
+                        : runtimeError ?? (result?.status === 'paused' ? hostPause ? `Workflow paused by the host (${hostPause.reason})` : (typeof result.pendingQuestion?.question === 'string' && result.pendingQuestion.question.trim()
                             ? `Workflow awaits an answer in Agent Runtime settings: ${result.pendingQuestion.question.trim().slice(0, 500)}`
                             : 'Workflow awaits approval in Agent Runtime settings')
                             : failed ? completionError || [...stepFailures.values()].at(-1) || stderr || 'Core exited without a successful programmatic workflow result' : undefined));
@@ -464,13 +514,29 @@ async function runAgentRuntimeInvocation(options) {
             resolve({
                 text: summary || (failed ? errorText ?? '' : definitionEngine ? 'Workflow execution completed.' : 'Programmatic implementation verified and archived.'),
                 provider: 'agent-runtime', model: 'per-role', failed, errorText,
-                ...(definitionEngine ? { runtimeStatus, completion: result?.completion, pendingInterrupts: result?.pendingInterrupts, pendingQuestion: result?.pendingQuestion, pendingApproval: result?.pendingApproval, graph } : {}),
+                ...(definitionEngine ? { runtimeStatus, ...(result?.failure !== undefined ? { failure: result.failure } : {}), completion: result?.completion, pendingInterrupts: result?.pendingInterrupts, pendingQuestion: result?.pendingQuestion, pendingApproval: result?.pendingApproval, ...(hostPause ? { pause: hostPause } : {}), graph } : {}),
                 cost, tokensIn, tokensOut, tokens: tokensIn === undefined || tokensOut === undefined ? undefined : tokensIn + tokensOut,
                 estimated: cost === undefined, durationMs: definitionEngine ? known(result?.usage?.durationMs) : Date.now() - started,
             });
         });
     });
 }
+const PAUSE_OUTCOMES = ['requested', 'paused', 'already-paused', 'not-running', 'terminal'];
+const PAUSE_REASON = /^[a-z][a-z0-9_-]{0,63}$/;
+function readHostPause(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const pause = value;
+    return typeof pause.requestId === 'string' && typeof pause.reason === 'string' && typeof pause.at === 'string'
+        ? { requestId: pause.requestId, reason: pause.reason, at: pause.at } : undefined;
+}
+/** True when the run's retained Core announces cooperative pause (`pauseRuns`). */
+async function retainedRuntimeSupportsPause(options) {
+    const cli = (0, agent_runtime_package_1.resolveRetainedAgentRuntime)(options.contextPath);
+    const events = await runControlProcess([cli, 'api'], options);
+    const capabilities = events.find(event => event.type === 'runtime-api')?.capabilities;
+    return capabilities?.pauseRuns === 1;
+}
 const CONTROL_RUN_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const CONTROL_TIMEOUT_MS = 60_000;
 /** Check the retained package before recording a host operation that requires
@@ -609,6 +675,21 @@ async function runAgentRuntimeControl(options) {
             throw new Error('Core did not acknowledge the steering request');
         return { kind: 'signal', id: accepted.id, acceptedAt: accepted.acceptedAt };
     }
+    if (options.kind === 'pause') {
+        if (typeof options.requestId !== 'string' || !options.requestId.trim() || options.requestId.length > 256 || options.requestId.includes('\0'))
+            throw new Error('invalid_arguments: Pause requires a request id of 1–256 characters');
+        if (!PAUSE_REASON.test(options.reason))
+            throw new Error('invalid_arguments: Pause reason must be a lowercase token');
+        // An older retained Core has no pause verb: say so instead of failing the spawn.
+        if (!await retainedRuntimeSupportsPause(options))
+            throw new Error('engine_unsupported: Retained Core does not support cooperative pause');
+        args.push('--request-id', options.requestId, '--reason', options.reason);
+        const events = await runControlProcess(args, options);
+        const paused = events.find(event => event.type === 'runtime-pause-result');
+        if (paused?.requestId !== options.requestId || paused.runId !== options.runId || !PAUSE_OUTCOMES.includes(paused.outcome))
+            throw new Error('Core did not acknowledge the pause request');
+        return { kind: 'pause', requestId: options.requestId, reason: options.reason, outcome: paused.outcome, status: typeof paused.status === 'string' ? paused.status : 'unknown' };
+    }
     if (options.kind === 'cancel') {
         if (typeof options.requestId !== 'string' || !options.requestId.trim() || options.requestId.length > 256 || options.requestId.includes('\0'))
             throw new Error('invalid_arguments: Cancellation requires a request id of 1–256 characters');

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

@@ -27,11 +27,15 @@ const core_node_runtime_1 = require("../../../core-node-runtime");
 const win_spawn_1 = require("../../../util/win-spawn");
 const workspace_resolution_1 = require("../../../workspace-resolution");
 const project_env_1 = require("../../../project-env");
+const registry_1 = require("../../../providers/registry");
+const runtime_1 = require("../../../providers/runtime");
 const loop_runs_store_1 = require("../../loops/runtime/loop-runs-store");
 const multi_repo_execution_store_1 = require("../../delivery/runtime/multi-repo-execution-store");
 const db_1 = require("../../../db");
 const loop_run_manager_1 = require("../../loops/runtime/loop-run-manager");
 const agent_runtime_recovery_1 = require("./agent-runtime-recovery");
+const run_review_diagnosis_1 = require("../../delivery/runtime/run-review-diagnosis");
+const loop_definition_recovery_1 = require("../../loops/runtime/loop-definition-recovery");
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 const LEGACY_STEP_IDS = ['architect', 'developer', 'fixer', 'verify', 'reviewer', 'archive'];
 const NODE_PATH = /^[A-Za-z0-9][A-Za-z0-9_-]{0,119}(\/[A-Za-z0-9][A-Za-z0-9_-]{0,119}){0,3}$/;
@@ -310,7 +314,8 @@ class AgentRuntimeControls {
         const host = JSON.parse(node_fs_1.default.readFileSync(hostFile, 'utf8'));
         if (host.schemaVersion !== 1 || typeof host.cwd !== 'string' || ![frozen.backlogRoot, ...frozen.repositories.map((repository) => repository.path)].includes(host.cwd) || !host.env || typeof host.env !== 'object' || Array.isArray(host.env) || Object.entries(host.env).some(([key, value]) => !agent_runtime_bridge_1.RUNTIME_HOST_ENV_KEYS.includes(key) || typeof value !== 'string'))
             throw new RuntimeControlError(409, 'runtime_host_invalid', 'The saved runtime host settings are invalid');
-        const env = { ...(0, workspace_resolution_1.resolveLoopBaseEnv)(this.ctx.project, undefined, (0, project_env_1.applyWorktreeEnvPassthrough)(this.ctx.db, process.env)) };
+        // Core may resume any role provider: minimal mode passes every adapter's names.
+        const env = { ...(0, workspace_resolution_1.resolveLoopBaseEnv)(this.ctx.project, undefined, (0, project_env_1.resolveProjectAgentEnv)(this.ctx.db, { providerAllowlist: (0, runtime_1.providerEnvAllowlist)((0, registry_1.listAdapters)()) })) };
         for (const key of agent_runtime_bridge_1.RUNTIME_HOST_ENV_KEYS)
             delete env[key];
         Object.assign(env, host.env, { SPECRAILS_EXECUTION_CONTEXT: file });
@@ -329,8 +334,26 @@ class AgentRuntimeControls {
         const result = JSON.parse(stdout);
         if (result.schemaVersion !== 1 || typeof result.available !== 'boolean' || typeof result.truncated !== 'boolean')
             throw new RuntimeControlError(503, 'evidence_unavailable', 'Core evidence is unavailable or incompatible');
+        // The overview page also answers "why did the review say no".
+        if (query.id === undefined && query.cursor === undefined)
+            return { ...result, reviewer: await this.reviewer(runId) };
         return result;
     }
+    /** The reviewer's latest verdict for the run (settle evidence, else the retained run, read-only). Never throws. */
+    async reviewer(runId) {
+        try {
+            if (this.dependencies.reviewer)
+                return await this.dependencies.reviewer(runId);
+            return await (0, run_review_diagnosis_1.readRunReviewDiagnosis)({
+                db: this.ctx.db, runId,
+                pipelineDir: node_path_1.default.join((0, workspace_resolution_1.resolveProjectExecution)(this.ctx.project).specrailsDir, 'pipeline'),
+                probe: (runIds) => (0, loop_definition_recovery_1.probeDefinitionRuns)({ db: this.ctx.db, cwd: this.ctx.project.path, env: process.env }, runIds, true),
+            });
+        }
+        catch {
+            return null;
+        }
+    }
     async recovery(runId, input) {
         const parsed = agent_runtime_recovery_1.recoveryRequestSchema.safeParse(input);
         if (!parsed.success)
@@ -401,11 +424,12 @@ class AgentRuntimeControls {
                 reason: 'The run was rejected before Core started, so there is no runtime state or evidence. Fix the reported precondition (or change the launch settings) before launching again; Resume is not possible.',
                 launchError, repeatFailureCount: null, recentFailures: [],
             };
+        const reviewer = await this.reviewer(runId);
         if (summary.historical || summary.status === 'unavailable')
             return {
                 runId, summary, recommendation: 'inspect_saved_evidence',
                 reason: 'Live original runtime scope is unavailable. Preserve saved work and inspect the missing scope before proposing a fresh run.',
-                repeatFailureCount: null, recentFailures: [],
+                repeatFailureCount: null, recentFailures: [], reviewer,
             };
         const { file, frozen, cwd, env } = this.context(runId);
         const state = await this.dependencies.status(file, cwd, env);
@@ -440,10 +464,12 @@ class AgentRuntimeControls {
             verification: state.inspection?.verification ? { valid: state.inspection.verification.valid, reasons: state.inspection.verification.reasons } : null,
             acceptance: state.inspection?.acceptance ? { valid: state.inspection.acceptance.valid, reasons: state.inspection.acceptance.reasons } : null,
             resumePhase: state.inspection?.resumePhase ?? null,
+            reviewer,
             limitations: [
                 'Recent failure history is bounded to eight attempts; null means the retained Core does not expose it.',
                 'Completed steps are historical outcomes. Resume revalidates receipts and may repeat verification/review after changes; do not promise zero cost.',
                 'This diagnostic does not execute repairs, resume, relaunch, publish or discard work.',
+                'reviewer is the latest recorded verdict (AI-reported, bounded); failingChecks are host-run. null means no review attempt recorded one.',
             ],
         };
     }

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

@@ -1,6 +1,7 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readRuntimeEfficiency = readRuntimeEfficiency;
+exports.readRuntimeBaselineSpend = readRuntimeBaselineSpend;
 exports.readRuntimeEfficiencySummary = readRuntimeEfficiencySummary;
 exports.applyRuntimeSelectionOrigins = applyRuntimeSelectionOrigins;
 const COUNTS = ['attempts', 'measuredAttempts', 'providerCalls', 'toolCalls', 'inputTokens', 'outputTokens', 'uncachedInputTokens', 'cacheReadInputTokens', 'cacheWriteInputTokens'];
@@ -50,6 +51,15 @@ function readRuntimeEfficiency(value, catalog) {
     }
     return { schemaVersion: 1, total, phases };
 }
+/** Tolerant read of `efficiencySummary.baseline`; undefined when absent or malformed. */
+function readRuntimeBaselineSpend(value) {
+    const raw = object(value);
+    if (!raw || typeof raw.invocations !== 'number' || !Number.isSafeInteger(raw.invocations) || raw.invocations < 0)
+        return undefined;
+    const amount = (input, integer) => typeof input === 'number' && Number.isFinite(input) && input >= 0 && (!integer || Number.isSafeInteger(input)) ? input : null;
+    const roles = Array.isArray(raw.roles) ? raw.roles.filter((role) => typeof role === 'string' && role.length > 0 && role.length <= 64).slice(0, 16) : [];
+    return { invocations: raw.invocations, roles, costUsd: amount(raw.costUsd, false), inputTokens: amount(raw.inputTokens, true), outputTokens: amount(raw.outputTokens, true) };
+}
 function readRuntimeEfficiencySummary(value, catalog) {
     const input = object(value), invocations = object(input?.invocations), checks = object(input?.checks);
     const roleIds = catalog?.roleIds ?? ROLES;
@@ -77,7 +87,9 @@ function readRuntimeEfficiencySummary(value, catalog) {
     if (!Array.isArray(input.currentEvidenceIds) || input.currentEvidenceIds.length > 100 || !input.currentEvidenceIds.every(id => typeof id === 'string' && /^[a-f0-9]{64}$/.test(id)))
         return undefined;
     const kinds = object(invocations.byKind);
-    if (!kinds || Object.keys(kinds).length !== 5 || !['initial', 'correction', 'repair', 'deepen', 'session-fallback'].every(key => count(kinds[key], false)))
+    // Contract 5.7 adds the `baseline` kind; earlier Cores report exactly five.
+    const kindKeys = Object.keys(kinds ?? {});
+    if (!kinds || kindKeys.length !== 5 + (kindKeys.includes('baseline') ? 1 : 0) || !['initial', 'correction', 'repair', 'deepen', 'session-fallback'].every(key => count(kinds[key], false)) || kindKeys.includes('baseline') && !count(kinds.baseline, false))
         return undefined;
     const roles = [];
     for (const raw of input.roles) {
@@ -112,7 +124,8 @@ function readRuntimeEfficiencySummary(value, catalog) {
             escalations.push(row);
         }
     }
-    return { ...(escalations ? { escalations, escalationsTruncated: input.escalationsTruncated } : {}), schemaVersion: 1, currentEvidenceIds: [...input.currentEvidenceIds], planHash: input.planHash, candidateHash: input.candidateHash, runId: input.runId, workflowVersion: input.workflowVersion, technicalAcceptance: input.technicalAcceptance, archive: input.archive, delivery: input.delivery, roles,
+    const baseline = readRuntimeBaselineSpend(input.baseline);
+    return { ...(escalations ? { escalations, escalationsTruncated: input.escalationsTruncated } : {}), ...(baseline ? { baseline } : {}), schemaVersion: 1, currentEvidenceIds: [...input.currentEvidenceIds], planHash: input.planHash, candidateHash: input.candidateHash, runId: input.runId, workflowVersion: input.workflowVersion, technicalAcceptance: input.technicalAcceptance, archive: input.archive, delivery: input.delivery, roles,
         invocations: { total: invocations.total, complete: invocations.complete, byKind: { ...kinds }, promptBytes: invocations.promptBytes, contextBytes: invocations.contextBytes, handoffBytes: invocations.handoffBytes, fullContexts: invocations.fullContexts, incrementalContexts: invocations.incrementalContexts },
         checks: { ...(checks.complete === undefined ? {} : { complete: checks.complete }), ...(checks.invalidated === undefined ? {} : { invalidated: checks.invalidated }), available: checks.available, executed: checks.executed, reused: checks.reused, notRun: checks.notRun, durationMs: checks.durationMs } };
 }

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

@@ -1,11 +1,22 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
+exports.rulesGateSuggestions = rulesGateSuggestions;
 exports.registerAgentRuntimeSettingsRoutes = registerAgentRuntimeSettingsRoutes;
 const node_fs_1 = require("node:fs");
 const agent_runtime_loader_1 = require("./agent-runtime-loader");
 const agent_runtime_settings_1 = require("./agent-runtime-settings");
 const agent_runtime_settings_2 = require("./agent-runtime-settings");
 const agent_runtime_verification_suggestions_1 = require("./agent-runtime-verification-suggestions");
+const core_capabilities_1 = require("./core-capabilities");
+const rules_store_1 = require("../../project-rules/runtime/rules-store");
+const domain_1 = require("../../project-rules/domain");
+/** The inventory's gates as verification suggestions (plain commands only). */
+function rulesGateSuggestions(inventory, repositoryId) {
+    return (inventory?.gates ?? []).flatMap((gate) => {
+        const command = (0, domain_1.gateToVerificationCommand)(gate);
+        return command ? [{ repositoryId, ...command, reason: `project rules gate "${gate.id}" (${gate.kind})` }] : [];
+    });
+}
 const project_repositories_1 = require("../../../project-repositories");
 const agent_runtime_effective_config_1 = require("./agent-runtime-effective-config");
 /** Raw request body → same body with every local role's missing model filled (validation then passes). */
@@ -85,11 +96,19 @@ function registerAgentRuntimeSettingsRoutes({ router, ctx }) {
     /** Offline detection of each repository's own checks; never invokes a model.
      *  Verification stays optional: the architect proposes commands for uncovered
      *  repositories at run time, and Core admits repositories without any check. */
-    router.get('/:projectId/agent-runtime/verification-suggestions', (req, res) => {
+    router.get('/:projectId/agent-runtime/verification-suggestions', async (req, res) => {
         try {
             const project = ctx(req).project;
             const repositories = (0, project_repositories_1.getProjectRepositories)(project).map((repository) => ({ id: repository.id, name: repository.name, path: repository.path, workspacePath: repository.workspacePath, workspacePaths: repository.workspacePaths }));
-            res.json({ repositories: repositories.map(({ id, name }) => ({ id, name })), suggestions: (0, agent_runtime_verification_suggestions_1.suggestVerificationCommands)(repositories) });
+            // Project rules (task 4.4): the gates Core's inventory discovered come
+            // first, so they become the default plan of a project with no checks.
+            const primary = (0, project_repositories_1.getProjectRepositories)(project).find((repository) => repository.isPrimary) ?? repositories[0];
+            const gates = primary && (await (0, core_capabilities_1.corePhase3Capabilities)()).rulesInventory
+                ? rulesGateSuggestions((0, rules_store_1.readProjectRulesInventory)(project), primary.id) : [];
+            const detected = (0, agent_runtime_verification_suggestions_1.suggestVerificationCommands)(repositories);
+            const key = (item) => JSON.stringify([item.repositoryId, item.command, item.args]);
+            const seen = new Set(gates.map(key));
+            res.json({ repositories: repositories.map(({ id, name }) => ({ id, name })), suggestions: [...gates, ...detected.filter((item) => !seen.has(key(item)))] });
         }
         catch {
             res.status(500).json({ error: 'verification_suggestions_failed', message: 'Could not inspect the project repositories' });

package/server/dist/modules/agent-runtime/runtime/core-capabilities.js

@@ -0,0 +1,55 @@
+"use strict";
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.NO_PHASE3_CAPABILITIES = void 0;
+exports.phase3CapabilitiesFrom = phase3CapabilitiesFrom;
+exports.corePhase3Capabilities = corePhase3Capabilities;
+exports.NO_PHASE3_CAPABILITIES = Object.freeze({
+    architectClarifications: false, specTrace: false, baselineOnTouch: false, rulesInventory: false,
+});
+/** Pure projection of a `runtime api` capability map. */
+function phase3CapabilitiesFrom(capabilities) {
+    const on = (key) => capabilities?.[key] === 1;
+    return { architectClarifications: on('architectClarifications'), specTrace: on('specTrace'), baselineOnTouch: on('baselineOnTouch'), rulesInventory: on('rulesInventory') };
+}
+async function corePhase3Capabilities() {
+    try {
+        const { loadCoreAgentRuntime } = await Promise.resolve().then(() => __importStar(require('./agent-runtime-loader')));
+        return phase3CapabilitiesFrom((await loadCoreAgentRuntime()).api?.capabilities);
+    }
+    catch {
+        return { ...exports.NO_PHASE3_CAPABILITIES };
+    }
+}

package/server/dist/modules/agent-sessions/adapters/host-process.js

@@ -22,7 +22,7 @@ class CoreHostLauncher {
         const cli = (this.options.cli ?? agent_runtime_loader_1.findCoreAgentRuntimeCli)();
         if (!cli)
             throw new errors_1.SessionRequestError('The selected Core runtime does not include the agent runtime CLI', { code: 'driver_unavailable', retryable: false });
-        const env = (0, win_spawn_1.windowsSpawnEnv)(this.options.env ?? process.env);
+        const env = (0, win_spawn_1.windowsSpawnEnv)((typeof this.options.env === 'function' ? this.options.env(scope) : this.options.env) ?? process.env);
         const args = [cli, 'host', '--stdio', '--scope', scope];
         const command = (this.options.node ?? core_node_runtime_1.resolveCoreNodeRuntime)();
         const child = (this.options.spawnProcess ?? ((cmd, argv, opts) => (0, node_child_process_1.spawn)(cmd, argv, { env: opts.env, shell: false, windowsHide: true, stdio: ['pipe', 'pipe', 'pipe'] })))(command, args, { env });

package/server/dist/modules/agent-sessions/domain/availability.js

@@ -3,6 +3,7 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.DEFAULT_CORE_SESSIONS_FLAG = void 0;
 exports.parseCoreSessionsFlag = parseCoreSessionsFlag;
 exports.resolveCoreSessionsAvailability = resolveCoreSessionsAvailability;
+exports.resolveFlowAvailability = resolveFlowAvailability;
 exports.DEFAULT_CORE_SESSIONS_FLAG = 'auto';
 function parseCoreSessionsFlag(raw) {
     const value = raw?.trim().toLowerCase();
@@ -23,3 +24,18 @@ function resolveCoreSessionsAvailability(flag, capabilities, contractCompatible
         return { enabled: false, flag, reason: 'The selected Core session contract is not compatible with this Desktop; using legacy transports' };
     return { enabled: true, flag, reason: flag === 'on' ? 'Core sessions forced on' : 'Core sessions available' };
 }
+function resolveFlowAvailability(sessions, capabilities) {
+    const missing = [];
+    if (!sessions.enabled)
+        missing.push('sessions');
+    if ((capabilities?.flowSessions ?? 0) < 1)
+        missing.push('flowSessions');
+    if ((capabilities?.deriveChange ?? 0) < 1)
+        missing.push('deriveChange');
+    if (missing.length === 0)
+        return { available: true, reason: 'Flow is available', missing };
+    const reason = !sessions.enabled
+        ? `Flow needs Core agent sessions: ${sessions.reason}`
+        : `Flow needs a Core that advertises ${missing.join(' and ')}; update Core to use Flow`;
+    return { available: false, reason, missing };
+}

package/server/dist/modules/agent-sessions/domain/protocol.js

@@ -9,6 +9,7 @@
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.KNOWN_EVENT_TYPES = exports.SUPPORTED_PROTOCOL_VERSIONS = void 0;
 exports.checkSessionContract = checkSessionContract;
+exports.hostSupportsFlowSessions = hostSupportsFlowSessions;
 exports.SUPPORTED_PROTOCOL_VERSIONS = Object.freeze([1]);
 /** Event types this Desktop understands; newer Cores may send more (ignored). */
 exports.KNOWN_EVENT_TYPES = Object.freeze([
@@ -37,7 +38,7 @@ exports.KNOWN_EVENT_TYPES = Object.freeze([
 /** Compare a Core contract block with what this Desktop speaks. Pure. */
 function checkSessionContract(block) {
     if (!block)
-        return { compatible: false, protocolVersion: null, unknownEventTypes: [], missingEventTypes: [], reasons: ['Core does not declare agentRuntime.sessions'] };
+        return { compatible: false, protocolVersion: null, unknownEventTypes: [], missingEventTypes: [], flowSessions: false, reasons: ['Core does not declare agentRuntime.sessions'] };
     const common = block.protocolVersions.filter((version) => exports.SUPPORTED_PROTOCOL_VERSIONS.includes(version));
     const declared = new Set(block.eventTypes);
     const known = new Set(exports.KNOWN_EVENT_TYPES);
@@ -54,6 +55,12 @@ function checkSessionContract(block) {
         protocolVersion: common.length ? Math.max(...common) : null,
         unknownEventTypes: block.eventTypes.filter((type) => !known.has(type)),
         missingEventTypes,
+        // Additive and tolerant: older contracts omit both fields and stay compatible.
+        flowSessions: (block.capabilities ?? []).includes('flowSessions') && (block.deliveries ?? []).includes('interrupt'),
         reasons,
     };
 }
+/** True when this session host accepts `delivery: 'interrupt'` (initialize `flowSessions: 1`). */
+function hostSupportsFlowSessions(initialize) {
+    return (initialize?.capabilities?.flowSessions ?? 0) >= 1;
+}

package/server/dist/modules/agent-sessions/index.js

@@ -1,6 +1,6 @@
 "use strict";
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.SessionEventPump = exports.resolveCoreSessionsAvailability = exports.parseCoreSessionsFlag = exports.DEFAULT_CORE_SESSIONS_FLAG = exports.acceptsSessions = exports.DEFAULT_SUPERVISION = exports.resolveSubagentRuntime = exports.resolveSubagentPolicy = exports.reduceEnvelope = exports.liveSubagentCount = exports.initialProjection = exports.isSessionRequestError = exports.SessionRequestError = exports.checkSessionContract = exports.KNOWN_EVENT_TYPES = exports.SUPPORTED_PROTOCOL_VERSIONS = void 0;
+exports.SessionEventPump = exports.resolveFlowAvailability = exports.resolveCoreSessionsAvailability = exports.parseCoreSessionsFlag = exports.DEFAULT_CORE_SESSIONS_FLAG = exports.acceptsSessions = exports.DEFAULT_SUPERVISION = exports.resolveSubagentRuntime = exports.resolveSubagentPolicy = exports.reduceEnvelope = exports.liveSubagentCount = exports.initialProjection = exports.isSessionRequestError = exports.SessionRequestError = exports.hostSupportsFlowSessions = exports.checkSessionContract = exports.KNOWN_EVENT_TYPES = exports.SUPPORTED_PROTOCOL_VERSIONS = void 0;
 /**
  * Agent sessions: Desktop as the host of Core's agent session runtime.
  * Public API for conversational features (missions first). Adapters and the
@@ -10,6 +10,7 @@ var protocol_1 = require("./domain/protocol");
 Object.defineProperty(exports, "SUPPORTED_PROTOCOL_VERSIONS", { enumerable: true, get: function () { return protocol_1.SUPPORTED_PROTOCOL_VERSIONS; } });
 Object.defineProperty(exports, "KNOWN_EVENT_TYPES", { enumerable: true, get: function () { return protocol_1.KNOWN_EVENT_TYPES; } });
 Object.defineProperty(exports, "checkSessionContract", { enumerable: true, get: function () { return protocol_1.checkSessionContract; } });
+Object.defineProperty(exports, "hostSupportsFlowSessions", { enumerable: true, get: function () { return protocol_1.hostSupportsFlowSessions; } });
 var errors_1 = require("./domain/errors");
 Object.defineProperty(exports, "SessionRequestError", { enumerable: true, get: function () { return errors_1.SessionRequestError; } });
 Object.defineProperty(exports, "isSessionRequestError", { enumerable: true, get: function () { return errors_1.isSessionRequestError; } });
@@ -27,5 +28,6 @@ var availability_1 = require("./domain/availability");
 Object.defineProperty(exports, "DEFAULT_CORE_SESSIONS_FLAG", { enumerable: true, get: function () { return availability_1.DEFAULT_CORE_SESSIONS_FLAG; } });
 Object.defineProperty(exports, "parseCoreSessionsFlag", { enumerable: true, get: function () { return availability_1.parseCoreSessionsFlag; } });
 Object.defineProperty(exports, "resolveCoreSessionsAvailability", { enumerable: true, get: function () { return availability_1.resolveCoreSessionsAvailability; } });
+Object.defineProperty(exports, "resolveFlowAvailability", { enumerable: true, get: function () { return availability_1.resolveFlowAvailability; } });
 var session_event_pump_1 = require("./application/session-event-pump");
 Object.defineProperty(exports, "SessionEventPump", { enumerable: true, get: function () { return session_event_pump_1.SessionEventPump; } });

package/server/dist/modules/agent-sessions/runtime/core-sessions-availability.js

@@ -5,6 +5,7 @@ var __importDefault = (this && this.__importDefault) || function (mod) {
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.readSelectedSessionContract = readSelectedSessionContract;
 exports.coreSessionsAvailability = coreSessionsAvailability;
+exports.flowAvailability = flowAvailability;
 const node_fs_1 = __importDefault(require("node:fs"));
 const node_path_1 = __importDefault(require("node:path"));
 const agent_runtime_loader_1 = require("../../agent-runtime/runtime/agent-runtime-loader");
@@ -41,3 +42,18 @@ async function coreSessionsAvailability(env = process.env) {
         return { enabled: false, flag, reason: `Core runtime probe failed: ${error.message}` };
     }
 }
+/**
+ * Whether Flow mode can be offered with the selected Core: Core sessions are
+ * usable and the runtime advertises `flowSessions` and `deriveChange`.
+ */
+async function flowAvailability(env = process.env) {
+    const sessions = await coreSessionsAvailability(env);
+    let capabilities;
+    try {
+        capabilities = (await (0, agent_runtime_loader_1.loadCoreAgentRuntime)()).api?.capabilities;
+    }
+    catch {
+        capabilities = undefined;
+    }
+    return (0, availability_1.resolveFlowAvailability)(sessions, capabilities);
+}

package/server/dist/modules/agents/runtime/agent-refine-manager.js

@@ -18,6 +18,8 @@ const ai_invocations_1 = require("../../accounting/runtime/ai-invocations");
 const result_event_1 = require("../../accounting/runtime/result-event");
 const spawn_lifecycle_1 = require("../../execution/runtime/spawn-lifecycle");
 const workspace_resolution_1 = require("../../../workspace-resolution");
+const project_env_1 = require("../../../project-env");
+const runtime_1 = require("../../../providers/runtime");
 const providers_1 = require("../../../providers");
 const agent_refine_db_1 = require("./agent-refine-db");
 const CUSTOM_PREFIX = /^custom-[a-z0-9][a-z0-9-]*$/;
@@ -322,7 +324,7 @@ class AgentRefineManager {
             action,
             buildOpts,
             cwd: refineExec.cwd,
-            env: (0, providers_1.buildProviderEnv)(this._adapter, buildOpts, refineEnv),
+            env: (0, providers_1.buildProviderEnv)(this._adapter, buildOpts, (0, project_env_1.projectAgentSourceEnv)(this._db, (0, runtime_1.providerEnvAllowlist)(this._adapter), refineEnv)),
             onSpawn: (child) => this._activeProcesses.set(refineId, child),
             onSpawnError: (err) => { spawnState.err = err; },
             onEvent: (ev) => {