specrails-desktop 2.44.2 → 2.46.0

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

@@ -0,0 +1,239 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AgentRuntimeConfigError = exports.REVIEW_THRESHOLD_FLOORS = void 0;
+exports.validateAgentRuntimeConfig = validateAgentRuntimeConfig;
+exports.defaultAgentRuntimeConfig = defaultAgentRuntimeConfig;
+exports.agentRuntimeConfigPath = agentRuntimeConfigPath;
+exports.runtimeProvidersPath = runtimeProvidersPath;
+exports.loadRuntimeProviders = loadRuntimeProviders;
+exports.validateRuntimeProviders = validateRuntimeProviders;
+exports.saveRuntimeProviders = saveRuntimeProviders;
+exports.loadRuntimeConfigFile = loadRuntimeConfigFile;
+exports.loadAgentRuntimeConfig = loadAgentRuntimeConfig;
+exports.saveAgentRuntimeConfig = saveAgentRuntimeConfig;
+exports.validateRuntimeRolePrompts = validateRuntimeRolePrompts;
+exports.loadRuntimeRolePrompts = loadRuntimeRolePrompts;
+exports.saveRuntimeRolePrompts = saveRuntimeRolePrompts;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const node_os_1 = __importDefault(require("node:os"));
+const node_crypto_1 = require("node:crypto");
+const ajv_1 = __importDefault(require("ajv"));
+const agent_runtime_schema_json_1 = __importDefault(require("./schemas/agent-runtime.schema.json"));
+const workspace_resolution_1 = require("./workspace-resolution");
+/** Core's own review gate. Configured thresholds may only tighten it (mirrors Core's config.ts). */
+exports.REVIEW_THRESHOLD_FLOORS = {
+    minScore: 70,
+    aspects: { type_correctness: 60, pattern_adherence: 60, test_coverage: 60, security: 75, architectural_alignment: 60 },
+};
+const CLI_PROVIDERS = ['claude', 'codex', 'gemini', 'kimi'];
+const ROLES = ['architect', 'developer', 'reviewer'];
+const schemaValidator = new ajv_1.default({ allErrors: true }).compile(agent_runtime_schema_json_1.default);
+class AgentRuntimeConfigError extends Error {
+    constructor(message) { super(message); this.name = 'AgentRuntimeConfigError'; }
+}
+exports.AgentRuntimeConfigError = AgentRuntimeConfigError;
+/** Vendored from Core's schema; parity tests keep offline configuration aligned.
+ *  Semantic checks mirror Core because JSON Schema cannot check provider refs. */
+function validateAgentRuntimeConfig(input) {
+    if (!schemaValidator(input)) {
+        const error = schemaValidator.errors?.[0];
+        throw new AgentRuntimeConfigError(`Invalid runtime configuration at ${error?.instancePath || '/'}: ${error?.message ?? 'invalid value'}`);
+    }
+    const config = input;
+    if (config.rolePrompts !== undefined)
+        validateRuntimeRolePrompts(config.rolePrompts);
+    if (new Set(config.providers.map(({ id }) => id)).size !== config.providers.length)
+        throw new AgentRuntimeConfigError('Provider IDs must be unique');
+    for (const provider of config.providers) {
+        if (provider.kind !== 'openai-compatible')
+            continue;
+        let url;
+        try {
+            url = new URL(provider.baseUrl);
+        }
+        catch {
+            throw new AgentRuntimeConfigError('Provider base URL must be an absolute HTTP(S) URL');
+        }
+        if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password || url.search || url.hash || provider.baseUrl.includes('\0'))
+            throw new AgentRuntimeConfigError('Provider URLs must use HTTP(S) without credentials, query parameters or fragments');
+    }
+    for (const role of ROLES) {
+        const agent = config.agents[role];
+        const provider = config.providers.find(({ id }) => id === agent.provider);
+        if (!provider)
+            throw new AgentRuntimeConfigError(`Role ${role} references a provider that is not configured`);
+        if (provider.kind === 'openai-compatible' && !agent.model)
+            throw new AgentRuntimeConfigError(`Role ${role} requires a model for its API provider`);
+        if (agent.model !== undefined && !agent.model.trim())
+            throw new AgentRuntimeConfigError(`Role ${role} requires a nonempty model identifier`);
+        if (agent.maxTurns !== undefined && !Number.isSafeInteger(agent.maxTurns))
+            throw new AgentRuntimeConfigError(`Role ${role} maxTurns must be a safe integer`);
+    }
+    for (const [key, value] of Object.entries(config.limits ?? {})) {
+        if (!Number.isFinite(value) || (key !== 'maxCostUsd' && !Number.isSafeInteger(value)))
+            throw new AgentRuntimeConfigError('Workflow limits must be finite, safe numbers');
+    }
+    for (const command of config.verification) {
+        if (![command.command, ...command.args, ...(command.cwd === undefined ? [] : [command.cwd])].every((value) => !value.includes('\0')) || !command.command.trim() || (command.cwd !== undefined && !command.cwd.trim()))
+            throw new AgentRuntimeConfigError('Verification command contains an empty or invalid value');
+        if (command.timeoutMs !== undefined && !Number.isSafeInteger(command.timeoutMs))
+            throw new AgentRuntimeConfigError('Verification timeout must be a safe integer');
+        for (const [key, value] of Object.entries(command.env ?? {})) {
+            if (/(?:token|secret|password|api_?key|credential)/i.test(key))
+                throw new AgentRuntimeConfigError('Verification credentials must be inherited from environment variables, never saved');
+            if (value.includes('\0'))
+                throw new AgentRuntimeConfigError('Verification environment contains an invalid value');
+        }
+    }
+    if (config.review?.minScore !== undefined && config.review.minScore < exports.REVIEW_THRESHOLD_FLOORS.minScore)
+        throw new AgentRuntimeConfigError(`Review threshold review.minScore must be at least ${exports.REVIEW_THRESHOLD_FLOORS.minScore} (Core's own review gate)`);
+    for (const [aspect, value] of Object.entries(config.review?.aspects ?? {})) {
+        if (value < exports.REVIEW_THRESHOLD_FLOORS.aspects[aspect])
+            throw new AgentRuntimeConfigError(`Review threshold review.aspects.${aspect} must be at least ${exports.REVIEW_THRESHOLD_FLOORS.aspects[aspect]} (Core's own review gate)`);
+    }
+    return structuredClone(config);
+}
+function defaultAgentRuntimeConfig(project) {
+    const provider = CLI_PROVIDERS.includes(project.provider) ? project.provider : 'claude';
+    return {
+        schemaVersion: 1, enabled: true,
+        providers: CLI_PROVIDERS.map((cli) => ({ id: cli, kind: 'cli', cli })),
+        agents: { architect: { provider }, developer: { provider }, reviewer: { provider } },
+        verification: [],
+    };
+}
+function agentRuntimeConfigPath(project) {
+    return node_path_1.default.join((0, workspace_resolution_1.resolveProjectExecution)(project).specrailsDir, 'agent-runtime.json');
+}
+/** Global connections are resolved for new runs; admitted runs keep their snapshot. */
+function runtimeProvidersPath() { return node_path_1.default.join(node_os_1.default.homedir(), '.specrails', 'runtime-providers.json'); }
+function atomicJson(file, value) {
+    node_fs_1.default.mkdirSync(node_path_1.default.dirname(file), { recursive: true });
+    const temporary = `${file}.${(0, node_crypto_1.randomUUID)()}.tmp`;
+    try {
+        node_fs_1.default.writeFileSync(temporary, `${JSON.stringify(value, null, 2)}\n`, { encoding: 'utf8', mode: 0o600, flag: 'wx' });
+        node_fs_1.default.renameSync(temporary, file);
+    }
+    finally {
+        node_fs_1.default.rmSync(temporary, { force: true });
+    }
+}
+function loadRuntimeProviders() {
+    try {
+        return validateRuntimeProviders(JSON.parse(node_fs_1.default.readFileSync(runtimeProvidersPath(), 'utf8')));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return defaultAgentRuntimeConfig({ path: '' }).providers;
+        throw error;
+    }
+}
+function validateRuntimeProviders(input) {
+    if (!Array.isArray(input) || !input.length)
+        throw new AgentRuntimeConfigError('At least one provider connection is required');
+    const first = input[0];
+    const role = { provider: first?.id, ...(first?.kind === 'openai-compatible' ? { model: 'validation' } : {}) };
+    return validateAgentRuntimeConfig({ schemaVersion: 1, enabled: true, providers: input, agents: { architect: role, developer: role, reviewer: role }, verification: [] }).providers;
+}
+function saveRuntimeProviders(input) {
+    const providers = validateRuntimeProviders(input);
+    atomicJson(runtimeProvidersPath(), providers);
+    return providers;
+}
+/** Migrate embedded connections once. Conflicting IDs receive a stable ID so
+ *  two projects with different endpoints never silently share a connection. */
+function loadRuntimeConfigFile(file, fallbackProvider) {
+    let parsed;
+    let text;
+    try {
+        text = node_fs_1.default.readFileSync(file, 'utf8');
+    }
+    catch (error) {
+        if (error.code !== 'ENOENT')
+            throw error;
+    }
+    if (text !== undefined) {
+        try {
+            parsed = JSON.parse(text);
+        }
+        catch {
+            throw new AgentRuntimeConfigError('Saved runtime configuration is not valid JSON');
+        }
+        if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed))
+            throw new AgentRuntimeConfigError('Saved runtime configuration must be an object');
+    }
+    const providers = loadRuntimeProviders();
+    if (!parsed) {
+        const config = defaultAgentRuntimeConfig({ path: '', provider: fallbackProvider });
+        const selected = providers.find(item => item.id === config.agents.architect.provider) ?? providers.find(item => item.kind === 'cli');
+        if (!selected || selected.kind !== 'cli')
+            throw new AgentRuntimeConfigError('Configure project role models before using API-only connections');
+        for (const role of ROLES)
+            config.agents[role].provider = selected.id;
+        return validateAgentRuntimeConfig({ ...config, providers });
+    }
+    if (Array.isArray(parsed.providers)) {
+        const legacy = validateAgentRuntimeConfig(parsed);
+        for (const original of legacy.providers) {
+            let connection = providers.find(item => item.id === original.id);
+            if (connection && JSON.stringify(connection) !== JSON.stringify(original)) {
+                const id = `${original.id.slice(0, 117)}-${(0, node_crypto_1.createHash)('sha256').update(JSON.stringify(original)).digest('hex').slice(0, 10)}`;
+                for (const role of ROLES)
+                    if (legacy.agents[role].provider === original.id)
+                        legacy.agents[role].provider = id;
+                connection = providers.find(item => item.id === id);
+                if (!connection)
+                    providers.push({ ...original, id });
+            }
+            else if (!connection)
+                providers.push(original);
+        }
+        saveRuntimeProviders(providers);
+        const { providers: _embedded, enabled: _enabled, ...settings } = legacy;
+        atomicJson(file, settings);
+        parsed = settings;
+    }
+    return validateAgentRuntimeConfig({ ...parsed, enabled: true, providers });
+}
+/** Missing settings use the programmatic engine. Malformed files fail closed. */
+function loadAgentRuntimeConfig(project) {
+    return loadRuntimeConfigFile(agentRuntimeConfigPath(project), project.provider);
+}
+/** Atomic replacement works on macOS and Windows, with no partial file on errors. */
+function saveAgentRuntimeConfig(project, input) {
+    const config = validateAgentRuntimeConfig({ ...input, enabled: true, providers: loadRuntimeProviders() });
+    const file = agentRuntimeConfigPath(project);
+    const { providers: _providers, enabled: _enabled, ...settings } = config;
+    atomicJson(file, settings);
+    return config;
+}
+function validateRuntimeRolePrompts(input) {
+    if (!input || typeof input !== 'object' || Array.isArray(input))
+        throw new AgentRuntimeConfigError('Role prompts must be an object');
+    const prompts = {};
+    for (const [role, text] of Object.entries(input)) {
+        if (!ROLES.includes(role) || typeof text !== 'string' || !text.trim() || text.length > 20000 || text.includes('\0'))
+            throw new AgentRuntimeConfigError('Role prompts must use architect, developer or reviewer with 1–20000 nonblank characters and no null bytes');
+        prompts[role] = text;
+    }
+    return prompts;
+}
+function loadRuntimeRolePrompts() {
+    try {
+        return validateRuntimeRolePrompts(JSON.parse(node_fs_1.default.readFileSync(node_path_1.default.join(node_os_1.default.homedir(), '.specrails', 'runtime-role-prompts.json'), 'utf8')));
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return {};
+        throw error;
+    }
+}
+function saveRuntimeRolePrompts(input) {
+    const prompts = validateRuntimeRolePrompts(input);
+    atomicJson(node_path_1.default.join(node_os_1.default.homedir(), '.specrails', 'runtime-role-prompts.json'), prompts);
+    return prompts;
+}

package/server/dist/agent-runtime-settlement.js

@@ -0,0 +1,133 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.settleRuntimeContinuation = settleRuntimeContinuation;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_crypto_1 = require("node:crypto");
+const db_1 = require("./db");
+const core_execution_1 = require("./core-execution");
+const core_completion_1 = require("./core-completion");
+const worktree_manager_1 = require("./worktree-manager");
+const rail_pr_store_1 = require("./rail-pr-store");
+const multi_repo_execution_1 = require("./multi-repo-execution");
+/** Complete the host's local settlement after Core recovery. Never pushes or merges. */
+async function settleRuntimeContinuation(input, dependencies = { verify: core_execution_1.checkCoreCompletion, git: worktree_manager_1.defaultGitRunner, commit: worktree_manager_1.commitWorktreeAndVerify }) {
+    const { db, runId } = input;
+    const verified = dependencies.verify(input.contextPath, input.cwd, input.env, runId);
+    if (!verified.valid)
+        throw new Error(verified.reason ?? 'Core completion is not verified');
+    const frozen = JSON.parse(node_fs_1.default.readFileSync(input.contextPath, 'utf8'));
+    if (frozen.runId !== runId)
+        throw new Error('Runtime identity changed');
+    const all = db.prepare('SELECT * FROM rail_pr_deliveries').all().filter(row => (0, rail_pr_store_1.toPrDeliverySnapshot)(row).runIds.includes(runId));
+    const parents = new Set(all.map(row => row.parent_delivery_id).filter((id) => !!id));
+    const rows = all.filter(row => !parents.has(row.id) && row.decision === 'implementation_failed');
+    if (all.some(row => parents.has(row.id) && ['discarded', 'superseded', 'merged', 'completed'].includes(row.decision)))
+        throw new Error('Delivery is no longer available for recovery');
+    const token = (0, node_crypto_1.randomUUID)(), claimed = [];
+    const updates = [];
+    const gitText = async (args, cwd) => {
+        const result = await dependencies.git.run(args, cwd);
+        if (result.code !== 0)
+            throw new Error(`Cannot inspect recovered worktree: ${result.stderr}`);
+        return result.stdout.trim();
+    };
+    try {
+        // Claim the entire group before Git effects; a concurrent discard must win or lose atomically.
+        db.transaction(() => {
+            for (const row of all.filter(row => parents.has(row.id) || rows.includes(row))) {
+                if (!(0, rail_pr_store_1.claimPrDeliveryOperation)(db, row.id, row.decision, 'recover-and-retry', token))
+                    throw new Error('Delivery is busy; retry settlement after its current operation');
+                claimed.push(row);
+            }
+        })();
+        for (const row of rows) {
+            if (row.pr_url)
+                throw new Error('An existing PR requires explicit delivery recovery');
+            if (!(0, rail_pr_store_1.toPrDeliverySnapshot)(row).branches.some(unit => unit.runId === runId))
+                throw new Error('Delivery has no branch recorded for this runtime');
+            for (const unit of (0, rail_pr_store_1.toPrDeliverySnapshot)(row).branches.filter(unit => unit.runId === runId)) {
+                if (!unit.worktreePath || !frozen.repositories.some(repo => repo.path === unit.worktreePath) || node_fs_1.default.realpathSync(unit.worktreePath) !== unit.worktreePath)
+                    throw new Error('Recovered worktree no longer matches the frozen runtime scope');
+                if (await gitText(['branch', '--show-current'], unit.worktreePath) !== unit.branch)
+                    throw new Error('Recovered worktree branch changed');
+            }
+        }
+        for (const row of rows) {
+            const branches = (0, rail_pr_store_1.toPrDeliverySnapshot)(row).branches;
+            for (const unit of branches.filter(unit => unit.runId === runId)) {
+                const result = await dependencies.commit(dependencies.git, unit.worktreePath, `specrails: ticket-${unit.ticketId} recovered (run ${runId})`, unit.overlayExcludes ?? []);
+                if (!result.clean || result.error)
+                    throw new Error(result.error ?? 'Recovered worktree still contains uncommitted changes');
+                const sha = await gitText(['rev-parse', 'HEAD'], unit.worktreePath);
+                if (!/^[a-f0-9]{40,64}$/i.test(sha))
+                    throw new Error('Invalid recovered commit');
+                Object.assign(unit, { succeeded: true, implementationOutcome: 'succeeded', deliveryOutcome: sha !== unit.initialSha ? 'ready' : 'no_changes', finalSha: sha, changed: sha !== unit.initialSha, failureCode: null });
+            }
+            updates.push({ row, branches });
+        }
+        const finalCheck = dependencies.verify(input.contextPath, input.cwd, input.env, runId);
+        if (!finalCheck.valid)
+            throw new Error(finalCheck.reason ?? 'Candidate changed during settlement');
+        const core = await (0, core_completion_1.readCoreCompletion)(input);
+        db.transaction(() => {
+            for (const { row, branches } of updates) {
+                const ready = branches.every(unit => unit.succeeded);
+                const noChanges = ready && branches.every(unit => unit.changed === false);
+                if (!(0, rail_pr_store_1.transitionClaimedDecision)(db, row.id, row.decision, noChanges ? 'no_changes' : 'on_review', token, {
+                    branches, implementationOutcome: ready ? 'succeeded' : 'partially_succeeded', deliveryOutcome: noChanges ? 'no_changes' : 'ready',
+                    statusCode: noChanges ? 'no_changes' : ready ? 'ready_for_review' : 'partial_success', statusDetail: null,
+                    ...(branches.length === 1 ? { deliverySha: branches[0].finalSha } : {}),
+                }))
+                    throw new Error('Delivery changed during runtime settlement');
+                for (const unit of branches.filter(unit => unit.runId === runId))
+                    db.prepare("UPDATE rail_worktrees SET merge_state = 'built', updated_at = datetime('now') WHERE run_id = ? AND worktree_path = ?").run(runId, unit.worktreePath);
+            }
+            for (const parentId of parents)
+                (0, multi_repo_execution_1.refreshRepositoryDeliveryGroup)(db, parentId);
+            db.prepare("UPDATE jobs SET status = 'completed', exit_code = 0 WHERE id = ?").run(runId);
+            db.prepare("UPDATE loop_runs SET status = 'completed', final_outcome = 'success' WHERE id = ?").run(runId);
+            let seq = db.prepare('SELECT COALESCE(MAX(seq), -1) + 1 AS seq FROM events WHERE job_id = ?').get(runId).seq;
+            const lastStep = db.prepare("SELECT payload FROM events WHERE job_id = ? AND event_type = 'loop_step' ORDER BY seq DESC LIMIT 1").get(runId);
+            const lastEnd = db.prepare("SELECT payload FROM events WHERE job_id = ? AND event_type = 'loop_step_end' ORDER BY seq DESC LIMIT 1").get(runId);
+            if (lastStep && lastEnd) {
+                const step = JSON.parse(lastStep.payload), end = JSON.parse(lastEnd.payload);
+                // Supersede only this implementation step, never an unrelated shell/decider failure.
+                if (step.kind === 'ai-step' && step.template === '{{cmd:implement}}' && end.index === step.index && end.nodeId === step.nodeId && end.status === 'failed') {
+                    const job = db.prepare('SELECT duration_ms FROM jobs WHERE id = ?').get(runId);
+                    (0, db_1.appendEvent)(db, runId, seq++, { event_type: 'loop_step_end', source: 'stdout', payload: JSON.stringify({ index: step.index, nodeId: step.nodeId, status: 'ok', exitCode: 0, durationMs: job.duration_ms ?? end.durationMs, recovered: true }) });
+                }
+            }
+            const oldCompletion = db.prepare("SELECT payload FROM events WHERE job_id = ? AND event_type = 'loop_completion' ORDER BY seq DESC LIMIT 1").get(runId);
+            let previous = {};
+            try {
+                previous = oldCompletion ? JSON.parse(oldCompletion.payload) : {};
+            }
+            catch { /* old event format */ }
+            const usage = db.prepare('SELECT total_cost_usd,num_turns FROM jobs WHERE id = ?').get(runId);
+            (0, db_1.appendEvent)(db, runId, seq, { event_type: 'loop_completion', source: 'stdout', payload: JSON.stringify({ ...previous, version: 1, execution: 'success', core, turns: usage.num_turns, costUsd: usage.total_cost_usd, recovered: true }) });
+            (0, db_1.appendEvent)(db, runId, seq + 1, { event_type: 'log', source: 'stdout', payload: JSON.stringify({ line: '[runtime] Recovery verified and local delivery prepared for review. The original failed attempt remains in history. No PR was published.' }) });
+        })();
+    }
+    finally {
+        for (const row of claimed)
+            (0, rail_pr_store_1.releasePrDeliveryOperation)(db, row.id, token);
+    }
+    for (const id of new Set([...updates.map(update => update.row.id), ...parents])) {
+        const row = (0, rail_pr_store_1.getPrDelivery)(db, id);
+        try {
+            if (row)
+                input.broadcast?.((0, rail_pr_store_1.toRailPrStateMessage)(input.projectId, (0, rail_pr_store_1.toPrDeliverySnapshot)(row)));
+        }
+        catch { /* durable state remains authoritative */ }
+    }
+    const events = db.prepare('SELECT seq,event_type,source,payload,timestamp FROM events WHERE job_id = ? ORDER BY seq DESC LIMIT 3').all(runId);
+    for (const event of events.reverse()) {
+        try {
+            input.broadcast?.({ type: 'event', projectId: input.projectId, jobId: runId, ...event });
+        }
+        catch { /* replay remains available */ }
+    }
+}

package/server/dist/agent-runtime-verification-suggestions.js

@@ -0,0 +1,119 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.suggestVerificationCommands = suggestVerificationCommands;
+const node_fs_1 = __importDefault(require("node:fs"));
+const node_path_1 = __importDefault(require("node:path"));
+const NPM_TEST_PLACEHOLDER = /no test specified/i;
+/** Script names worth running as verification, in priority order. Only scripts
+ *  that exist in the repository are proposed; nothing is invented. */
+const SCRIPT_CANDIDATES = [
+    { names: ['test', 'test:unit', 'test:ci'], label: 'test script' },
+    { names: ['typecheck', 'type-check', 'types', 'check-types'], label: 'type check script' },
+    { names: ['lint'], label: 'lint script' },
+];
+const BUILD_SCRIPTS = ['build', 'compile'];
+function exists(root, ...parts) {
+    try {
+        return node_fs_1.default.existsSync(node_path_1.default.join(root, ...parts));
+    }
+    catch {
+        return false;
+    }
+}
+function readJson(file) {
+    try {
+        const parsed = JSON.parse(node_fs_1.default.readFileSync(file, 'utf8'));
+        return parsed && typeof parsed === 'object' && !Array.isArray(parsed) ? parsed : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function packageManager(root) {
+    if (exists(root, 'pnpm-lock.yaml'))
+        return 'pnpm';
+    if (exists(root, 'yarn.lock'))
+        return 'yarn';
+    if (exists(root, 'bun.lockb') || exists(root, 'bun.lock'))
+        return 'bun';
+    return 'npm';
+}
+function runScript(manager, script) {
+    // `npm test` and `npm run <x>` are the portable forms; on Windows the npm
+    // shim is resolved by Core's verification runner, never through a shell.
+    if (script === 'test')
+        return { command: manager, args: ['test'] };
+    return { command: manager, args: ['run', script] };
+}
+function nodeSuggestions(repository) {
+    const pkg = readJson(node_path_1.default.join(repository.path, 'package.json'));
+    if (!pkg)
+        return [];
+    const scripts = pkg.scripts && typeof pkg.scripts === 'object' && !Array.isArray(pkg.scripts) ? pkg.scripts : {};
+    const manager = packageManager(repository.path);
+    const out = [];
+    for (const candidate of SCRIPT_CANDIDATES) {
+        const name = candidate.names.find((script) => typeof scripts[script] === 'string' && String(scripts[script]).trim() && !NPM_TEST_PLACEHOLDER.test(String(scripts[script])));
+        if (name)
+            out.push({ repositoryId: repository.id, ...runScript(manager, name), reason: `package.json ${candidate.label} "${name}"` });
+    }
+    if (!out.length) {
+        const build = BUILD_SCRIPTS.find((script) => typeof scripts[script] === 'string' && String(scripts[script]).trim());
+        if (build)
+            out.push({ repositoryId: repository.id, ...runScript(manager, build), reason: `package.json build script "${build}" (no test or type check script found)` });
+    }
+    return out;
+}
+function otherSuggestions(repository) {
+    const root = repository.path;
+    const windows = process.platform === 'win32';
+    const out = [];
+    const add = (command, args, reason) => out.push({ repositoryId: repository.id, command, args, reason });
+    if (exists(root, 'Cargo.toml'))
+        add('cargo', ['test'], 'Cargo.toml');
+    if (exists(root, 'go.mod'))
+        add('go', ['test', './...'], 'go.mod');
+    if (exists(root, 'pyproject.toml') || exists(root, 'pytest.ini') || exists(root, 'setup.cfg') || exists(root, 'tox.ini')) {
+        if (exists(root, 'tests') || exists(root, 'test') || exists(root, 'pytest.ini'))
+            add(windows ? 'python' : 'python3', ['-m', 'pytest'], 'Python project with a tests directory');
+    }
+    if (exists(root, 'mix.exs'))
+        add('mix', ['test'], 'mix.exs');
+    if (exists(root, 'Package.swift'))
+        add('swift', ['test'], 'Package.swift');
+    if (exists(root, 'Gemfile') && exists(root, 'spec'))
+        add('bundle', ['exec', 'rspec'], 'Gemfile with a spec directory');
+    if (exists(root, 'pom.xml'))
+        add(exists(root, windows ? 'mvnw.cmd' : 'mvnw') ? (windows ? 'mvnw.cmd' : './mvnw') : 'mvn', ['-q', 'test'], 'pom.xml');
+    if (exists(root, 'build.gradle') || exists(root, 'build.gradle.kts'))
+        add(exists(root, windows ? 'gradlew.bat' : 'gradlew') ? (windows ? 'gradlew.bat' : './gradlew') : 'gradle', ['test'], 'Gradle build');
+    try {
+        if (node_fs_1.default.readdirSync(root).some((name) => /\.(sln|csproj|fsproj)$/i.test(name)))
+            add('dotnet', ['test'], '.NET solution or project');
+    }
+    catch { /* unreadable root: nothing to suggest */ }
+    if (!out.length && !windows && exists(root, 'Makefile')) {
+        try {
+            if (/^test\s*:/m.test(node_fs_1.default.readFileSync(node_path_1.default.join(root, 'Makefile'), 'utf8')))
+                add('make', ['test'], 'Makefile test target');
+        }
+        catch { /* ignore */ }
+    }
+    return out;
+}
+/** Deterministic, offline detection of a repository's own checks. Repositories
+ *  with nothing recognisable produce no entry: the architect proposes commands
+ *  at run time, and Core admits repositories that have no automated check. */
+function suggestVerificationCommands(repositories) {
+    const out = [];
+    for (const repository of repositories) {
+        if (!repository.path || !node_fs_1.default.existsSync(repository.path))
+            continue;
+        const node = nodeSuggestions(repository);
+        out.push(...(node.length ? node : otherSuggestions(repository)));
+    }
+    return out;
+}

package/server/dist/contract-refine-runner.js

@@ -2,7 +2,7 @@
 /**
  * Contract Refine Runner
  *
- * Standalone runner that spawns a single Claude turn to produce the
+ * Standalone runner that spawns a single provider turn to produce the
  * Contract Layer for a just-committed Explore Spec ticket. Lives outside the
  * ChatManager lifecycle for now (design.md D3 — "thin sibling helper" option):
  * the refine is fire-and-forget with a 60 s budget per invocation and no
@@ -82,12 +82,12 @@ function buildRefineArgs(adapter, model, systemPrompt, sessionId) {
         model,
         systemPrompt: foldForResume ? undefined : systemPrompt,
         sessionId,
-        toolPolicy: 'none',
+        toolPolicy: (0, runtime_1.pureOutputToolPolicy)(adapter) ?? (0, runtime_1.requireToolPolicy)(adapter, 'none'),
         maxTurns: 1,
     };
     return { args: adapter.buildArgs(action, options), options };
 }
-/** Build the pure-output, no-resume invocation used by Quick Refine and by the
+/** Build the restricted pure-output, no-resume invocation used by Quick Refine and by the
  * one-time compatibility recovery for cwd-scoped Explore sessions. */
 function buildFreshRefineArgs(adapter, model, title, description) {
     const systemPrompt = [
@@ -105,7 +105,7 @@ function buildFreshRefineArgs(adapter, model, title, description) {
         prompt: explore_contract_refine_1.CONTRACT_MARKER_USER_MESSAGE,
         model,
         systemPrompt,
-        toolPolicy: 'none',
+        toolPolicy: (0, runtime_1.pureOutputToolPolicy)(adapter) ?? (0, runtime_1.requireToolPolicy)(adapter, 'none'),
         maxTurns: 1,
     };
     return { args: adapter.buildArgs('spec-gen', options), options };
@@ -362,8 +362,8 @@ async function runContractRefine(deps, conversationId, ticketId) {
         return { ok: false, reason: 'not-explore', ticketId, conversationId };
     }
     const adapter = (0, providers_1.getAdapter)(conversation.provider ?? deps.providerId ?? 'claude');
-    if (adapter.capabilities.structuredActions !== true) {
-        console.log(`[contract-refine-runner] skip: provider '${adapter.id}' does not support structured actions`);
+    if (!(0, runtime_1.supportsContractRefine)(adapter)) {
+        console.log(`[contract-refine-runner] skip: provider '${adapter.id}' does not support contract refinement`);
         return { ok: false, reason: 'provider-unsupported', ticketId, conversationId };
     }
     // Per-conversation gating: contractRefine on the conversation's stored
@@ -602,7 +602,7 @@ async function runContractRefineForQuick(deps, ticketId, generatedTitle, generat
     }
     const admission = (0, process_admission_1.captureProcessAdmission)(deps.projectId);
     const adapter = (0, providers_1.getAdapter)(deps.providerId ?? 'claude');
-    if (adapter.capabilities.structuredActions !== true) {
+    if (!(0, runtime_1.supportsContractRefine)(adapter)) {
         return { ok: false, reason: 'provider-unsupported', ticketId, conversationId: '' };
     }
     const resolvedModel = model ?? adapter.defaultModel();

package/server/dist/core-completion.js

@@ -6,7 +6,8 @@ const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
 const node_util_1 = require("node:util");
-const path_resolver_1 = require("./path-resolver");
+const core_node_runtime_1 = require("./core-node-runtime");
+const agent_runtime_loader_1 = require("./agent-runtime-loader");
 const obj = (value) => value !== null && typeof value === 'object' && !Array.isArray(value) ? value : null;
 const strings = (value) => Array.isArray(value) && value.every(item => typeof item === 'string');
 const count = (value) => typeof value === 'number' && Number.isFinite(value) && value >= 0 ? value : null;
@@ -43,14 +44,16 @@ function parseCoreCompletion(value, runId) {
         }), };
 }
 async function readCoreCompletion(input) {
-    const runtime = (0, node_path_1.join)(input.cwd, '.specrails', 'runtime', 'pipeline.mjs');
-    if (!(0, node_fs_1.existsSync)(runtime))
+    const programmatic = (0, node_fs_1.existsSync)((0, node_path_1.join)((0, node_path_1.dirname)(input.contextPath), 'agent-runtime-request.json'));
+    const runtime = programmatic ? (0, agent_runtime_loader_1.findCoreAgentRuntimeCli)() : (0, node_path_1.join)(input.cwd, '.specrails', 'runtime', 'pipeline.mjs');
+    if (!runtime || !(0, node_fs_1.existsSync)(runtime))
         return null;
     try {
-        const { stdout } = await (0, node_util_1.promisify)(node_child_process_1.execFile)((0, path_resolver_1.resolveBundledNodeExe)() ?? process.execPath, [runtime, 'status', '--context', input.contextPath], {
+        const { stdout } = await (0, node_util_1.promisify)(node_child_process_1.execFile)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), [runtime, 'status', '--context', input.contextPath], {
             cwd: input.cwd, env: input.env, encoding: 'utf8', timeout: 15_000, maxBuffer: 4 * 1024 * 1024, windowsHide: true,
         });
-        return parseCoreCompletion(JSON.parse(stdout), input.runId);
+        const payload = JSON.parse(stdout);
+        return parseCoreCompletion(programmatic ? payload.pipeline : payload, input.runId);
     }
     catch {
         return null;

package/server/dist/core-execution.js

@@ -6,8 +6,9 @@ exports.checkCoreCompletion = checkCoreCompletion;
 const node_child_process_1 = require("node:child_process");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
-const path_resolver_1 = require("./path-resolver");
+const core_node_runtime_1 = require("./core-node-runtime");
 const core_update_state_1 = require("./core-update-state");
+const agent_runtime_loader_1 = require("./agent-runtime-loader");
 const SAFE_ID = /^[A-Za-z0-9][A-Za-z0-9._-]{0,127}$/;
 // Resolve existing ancestors too: the tickets file may not exist yet, and macOS
 // exposes temporary directories through both /var and /private/var.
@@ -35,7 +36,7 @@ function prepareCoreExecution(input) {
     (0, core_update_state_1.assertWorkspaceCoreReady)(cwd);
     const repositories = manifest
         ? manifest.repositories.map(repo => ({ id: repo.repositoryId, name: repo.name, path: (0, node_fs_1.realpathSync)(repo.worktreePath), baseSha: repo.baseSha }))
-        : [{ id: run.repositoryId ?? (run.spec?.repositoryIds?.length === 1 ? run.spec.repositoryIds[0] : 'primary'), name: (0, node_path_1.basename)(input.repoDir ?? cwd), path: (0, node_fs_1.realpathSync)(input.repoDir ?? cwd) }];
+        : [{ id: run.repositoryId ?? (run.spec?.repositoryIds?.length === 1 ? run.spec.repositoryIds[0] : run.projectId ? `primary-${run.projectId}` : 'primary'), name: (0, node_path_1.basename)(input.repoDir ?? cwd), path: (0, node_fs_1.realpathSync)(input.repoDir ?? cwd) }];
     if (!repositories.length || repositories.some(repo => !SAFE_ID.test(repo.id)))
         throw new Error('Invalid Core repository scope');
     const artifactRepositoryId = manifest?.artifactRepositoryId ?? repositories[0].id;
@@ -91,7 +92,7 @@ function coreVerificationContext(contextPath, cwd, env, runId) {
     if (!(0, node_fs_1.existsSync)(helper))
         return '';
     try {
-        const stdout = (0, node_child_process_1.execFileSync)((0, path_resolver_1.resolveBundledNodeExe)() ?? process.execPath, [helper, 'status', '--context', contextPath], {
+        const stdout = (0, node_child_process_1.execFileSync)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), [helper, 'status', '--context', contextPath], {
             cwd, env, encoding: 'utf8', timeout: 15_000, maxBuffer: 4 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
         });
         const status = JSON.parse(stdout);
@@ -115,14 +116,18 @@ function coreVerificationContext(contextPath, cwd, env, runId) {
  * revalidate the journal on disk before Desktop accepts the implementation step,
  * including when an agent claims PASS after its final receipt went stale. */
 function checkCoreCompletion(contextPath, cwd, env, runId) {
-    const helper = (0, node_path_1.join)(cwd, '.specrails', 'runtime', 'pipeline.mjs');
-    if (!(0, node_fs_1.existsSync)(helper))
+    const programmatic = (0, node_fs_1.existsSync)((0, node_path_1.join)((0, node_path_1.dirname)(contextPath), 'agent-runtime-request.json'));
+    const helper = programmatic ? (0, agent_runtime_loader_1.findCoreAgentRuntimeCli)() : (0, node_path_1.join)(cwd, '.specrails', 'runtime', 'pipeline.mjs');
+    if (!helper || !(0, node_fs_1.existsSync)(helper))
         return { valid: false, reason: 'Core completion cannot be validated: pipeline runtime is missing' };
     try {
-        const stdout = (0, node_child_process_1.execFileSync)((0, path_resolver_1.resolveBundledNodeExe)() ?? process.execPath, [helper, 'status', '--context', contextPath], {
+        const stdout = (0, node_child_process_1.execFileSync)((0, core_node_runtime_1.resolveCoreNodeRuntime)(), [helper, 'status', '--context', contextPath, ...(programmatic ? ['--compact'] : [])], {
             cwd, env, encoding: 'utf8', timeout: 15_000, maxBuffer: 4 * 1024 * 1024, stdio: ['ignore', 'pipe', 'pipe'],
         });
-        const status = JSON.parse(stdout);
+        const payload = JSON.parse(stdout);
+        if (programmatic && payload.state?.status !== 'succeeded')
+            return { valid: false, reason: 'Programmatic workflow has not completed successfully' };
+        const status = (programmatic ? payload.pipeline : payload);
         if (status.schemaVersion !== 1 || status.runId !== runId)
             return { valid: false, reason: 'Core completion returned an invalid or mismatched run identity' };
         const reasons = [];
@@ -146,7 +151,11 @@ function checkCoreCompletion(contextPath, cwd, env, runId) {
         if (status.resumePhase && ['architect', 'developer', 'reviewer', 'archive'].includes(status.resumePhase))
             reasons.push(`resume from ${status.resumePhase}`);
         const receipt = status.verification?.receipt;
-        if (status.verification?.valid !== true || receipt?.kind !== 'full' || !receipt.commands?.length || receipt.commands.some(command => command.exitCode !== 0)) {
+        // A full receipt may explicitly record repositories without any automated
+        // check (the runtime admits them); an empty command list without that record
+        // is still no evidence.
+        const admittedWithoutCommands = Array.isArray(receipt?.unverifiedRepositories) && receipt.unverifiedRepositories.length > 0;
+        if (status.verification?.valid !== true || receipt?.kind !== 'full' || !Array.isArray(receipt.commands) || (!receipt.commands.length && !admittedWithoutCommands) || receipt.commands.some(command => command.exitCode !== 0)) {
             reasons.push(...(status.verification?.reasons?.length ? status.verification.reasons : ['No valid full verification receipt']));
         }
         return reasons.length ? { valid: false, reason: `Core completion blocked: ${[...new Set(reasons)].join('; ')}` } : { valid: true };