specrails-core 6.6.1 → 6.6.3

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

@@ -755,7 +755,7 @@ export async function runCompactDeveloper(env, options = {}) {
                 files.add(file);
             // Manifests written by this group get their dependencies installed by the host, so verify checks the code and not the environment.
             if (on(env, 'environment-repair') && [...groupFiles].some(file => /(?:^|[\\/])(?:package\.json|requirements\.txt|pyproject\.toml|go\.mod|Cargo\.toml)$/.test(file)))
-                for (const outcome of installEnvironment(env.toolset.roots, { onEvent: env.onEvent, lockfileRepair: on(env, 'lockfile-repair') }))
+                for (const outcome of await installEnvironment(env.toolset.roots, { onEvent: env.onEvent, lockfileRepair: on(env, 'lockfile-repair') }))
                     verification.push(outcome.detail);
             for (const file of strings(result.tests, 100, 500))
                 tests.add(file);
@@ -765,7 +765,7 @@ export async function runCompactDeveloper(env, options = {}) {
             // SAME group fix a failure while its context is fresh (one bounded round),
             // instead of discovering five broken suites at the end of the step.
             if (on(env, 'verify-per-group') && groupFiles.size && !correction) {
-                const check = runGroupCheck(env.toolset.roots, { onEvent: env.onEvent });
+                const check = await runGroupCheck(env.toolset.roots, { onEvent: env.onEvent });
                 if (check.ran && !check.ok) {
                     env.onEvent?.({ kind: 'text', text: `Group ${group.index} check failed (${check.command}); fixing in place before the next group.` });
                     const fixed = await fixGroupInPlace(env, group, check.output, budget, evidence, extraTools, languages);
@@ -773,7 +773,7 @@ export async function runCompactDeveloper(env, options = {}) {
                         files.add(file);
                         groupFiles.add(file);
                     }
-                    const again = runGroupCheck(env.toolset.roots, { onEvent: env.onEvent });
+                    const again = await runGroupCheck(env.toolset.roots, { onEvent: env.onEvent });
                     env.onEvent?.({ kind: 'text', text: again.ok ? `Group ${group.index} check passed after the fix.` : `Group ${group.index} check still failing (${again.command}); the host verify will report it.` });
                     verification.push(`group ${group.index} check ${again.ok ? 'passed' : 'failed'}: ${again.command ?? ''}`);
                 }
@@ -793,7 +793,7 @@ export async function runCompactDeveloper(env, options = {}) {
                                 files.add(file);
                                 groupFiles.add(file);
                             }
-                            const again = runGroupCheck(env.toolset.roots, { onEvent: env.onEvent });
+                            const again = await runGroupCheck(env.toolset.roots, { onEvent: env.onEvent });
                             const still = unreachedGroupTests(env.toolset.roots, unreached);
                             env.onEvent?.({ kind: 'text', text: still.length ? `Group ${group.index}: ${still.join(', ')} still not run by the test command; the host verify will report it.` : again.ok ? `Group ${group.index}: tests wired in and the check passed.` : `Group ${group.index}: tests wired in but the check now fails (${again.command}); the host verify will report it.` });
                             verification.push(`group ${group.index} test reachability ${still.length ? `unresolved: ${still.join(', ')}` : 'ok'}${again.ran && !again.ok ? `; check failed: ${again.command ?? ''}` : ''}`);

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

@@ -1,4 +1,20 @@
-import type { spawnSync } from 'node:child_process';
+import type { SpawnSyncOptionsWithStringEncoding, SpawnSyncReturns } from 'node:child_process';
+/** The parts of a finished host command the environment logic reads. */
+export interface HostRun {
+    status: number | null;
+    signal: NodeJS.Signals | null;
+    stdout: string;
+    stderr: string;
+    error?: Error;
+}
+/** Runs one host command. Injectable for tests; a synchronous result is accepted too. */
+export type HostSpawn = (command: string, args: readonly string[], options: SpawnSyncOptionsWithStringEncoding) => HostRun | SpawnSyncReturns<string> | Promise<HostRun>;
+/**
+ * Async counterpart of `spawnSync` with the same result shape: `status` null
+ * and an `ETIMEDOUT` error after `timeout` (the child is sent `killSignal`),
+ * stdout/stderr kept as bounded tails instead of failing with ENOBUFS.
+ */
+export declare const hostSpawn: HostSpawn;
 /** `timeoutMs` overrides the default bound for one plan (a browser download is far larger than a dependency install). `drift`: installed direct dependencies the install must bring back inside their declared ranges. */
 export interface EnvironmentInstall {
     ecosystem: 'node' | 'python' | 'go' | 'rust';
@@ -66,7 +82,7 @@ export declare function describeDrift(drift: readonly DriftedDependency[]): stri
 export declare function plannedInstalls(root: string, failureOutput?: string): EnvironmentInstall[];
 /** Runs each planned install once, bounded; never throws. */
 export interface InstallIo {
-    spawn?: typeof spawnSync;
+    spawn?: HostSpawn;
     timeoutMs?: number;
     failureOutput?: string;
     lockfileRepair?: boolean;
@@ -79,7 +95,7 @@ export interface InstallIo {
     /** The installs for one root; the failure-driven plan by default. */
     plan?: (root: string) => EnvironmentInstall[];
 }
-export declare function installEnvironment(roots: readonly string[], io?: InstallIo): InstallOutcome[];
+export declare function installEnvironment(roots: readonly string[], io?: InstallIo): Promise<InstallOutcome[]>;
 type PlaywrightBrowser = 'chromium' | 'firefox' | 'webkit';
 /** Browsers the repository's Playwright config runs (by project names, devices or browserName); chromium when it names none. */
 export declare function configuredPlaywrightBrowsers(root: string): PlaywrightBrowser[];
@@ -89,7 +105,7 @@ export declare function configuredPlaywrightBrowsers(root: string): PlaywrightBr
  * locations without downloading; an unreadable answer means "unknown", never
  * an install.
  */
-export declare function missingPlaywrightBrowsers(root: string, spawn?: typeof spawnSync): PlaywrightBrowser[];
+export declare function missingPlaywrightBrowsers(root: string, spawn?: HostSpawn): Promise<PlaywrightBrowser[]>;
 /**
  * Host preparation before an agent edits a repository: the dependencies its
  * manifest declares but are not installed, then the browser builds its
@@ -98,7 +114,7 @@ export declare function missingPlaywrightBrowsers(root: string, spawn?: typeof s
  * idempotent, project-local work happens here; other ecosystems keep their
  * failure-driven repair at verification.
  */
-export declare function prepareEnvironment(roots: readonly string[], io?: Omit<InstallIo, 'plan' | 'failureOutput'>): InstallOutcome[];
+export declare function prepareEnvironment(roots: readonly string[], io?: Omit<InstallIo, 'plan' | 'failureOutput'>): Promise<InstallOutcome[]>;
 /**
  * A Node preload that answers IPv6 lookups with nothing when the host has an
  * IPv4 address, so dual-stack clients connect over IPv4. Written once to the
@@ -124,7 +140,7 @@ interface GroupCheckOutcome {
  * still fresh instead of surfacing as five failed suites at the end.
  */
 export declare function runGroupCheck(roots: readonly string[], io?: {
-    spawn?: typeof spawnSync;
+    spawn?: HostSpawn;
     timeoutMs?: number;
     onEvent?: (event: {
         kind: 'tool-start' | 'tool-end' | 'text';
@@ -132,5 +148,5 @@ export declare function runGroupCheck(roots: readonly string[], io?: {
         detail?: string;
         text?: string;
     }) => void;
-}): GroupCheckOutcome;
+}): Promise<GroupCheckOutcome>;
 export {};

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

@@ -3,10 +3,62 @@ import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
 import { tmpdir } from 'node:os';
 import path from 'node:path';
 import semver from 'semver';
-// npm/pnpm/yarn are `.cmd` shims on Windows: a bare `spawnSync('npm')` is
-// ENOENT there, which read as an environment failure of its own and sent the
-// install/check round in circles. cross-spawn resolves the shim on every OS.
-const defaultSpawn = crossSpawn.sync;
+/** Bytes of each stream retained (the tail): installs can print far more than any caller reads. */
+const OUTPUT_TAIL_BYTES = 4 * 1024 * 1024;
+/**
+ * Async counterpart of `spawnSync` with the same result shape: `status` null
+ * and an `ETIMEDOUT` error after `timeout` (the child is sent `killSignal`),
+ * stdout/stderr kept as bounded tails instead of failing with ENOBUFS.
+ */
+export const hostSpawn = (command, args, options) => new Promise(resolve => {
+    let settled = false, timedOut = false, stdout = '', stderr = '';
+    const limit = options.maxBuffer ?? OUTPUT_TAIL_BYTES;
+    const finish = (result) => {
+        if (settled)
+            return;
+        settled = true;
+        if (timer)
+            clearTimeout(timer);
+        resolve(result);
+    };
+    let child;
+    try {
+        child = crossSpawn(command, [...args], { cwd: options.cwd, env: options.env, windowsHide: options.windowsHide ?? true, stdio: ['ignore', 'pipe', 'pipe'] });
+    }
+    catch (error) {
+        resolve({ status: null, signal: null, stdout: '', stderr: '', error: error });
+        return;
+    }
+    const timer = options.timeout ? setTimeout(() => {
+        timedOut = true;
+        try {
+            child.kill(options.killSignal ?? 'SIGTERM');
+        }
+        catch { /* already gone */ }
+    }, options.timeout) : undefined;
+    const tail = (current, chunk) => {
+        const next = current + chunk;
+        return next.length > limit ? next.slice(next.length - limit) : next;
+    };
+    child.stdout?.setEncoding('utf8').on('data', (chunk) => { stdout = tail(stdout, chunk); });
+    child.stderr?.setEncoding('utf8').on('data', (chunk) => { stderr = tail(stderr, chunk); });
+    child.on('error', error => finish({ status: null, signal: null, stdout, stderr, error }));
+    child.on('close', (code, signal) => finish({
+        status: timedOut ? null : code, signal, stdout, stderr,
+        ...(timedOut ? { error: Object.assign(new Error(`spawn ${command} ETIMEDOUT`), { code: 'ETIMEDOUT' }) } : {}),
+    }));
+});
+const defaultSpawn = hostSpawn;
+const failedRun = (error) => ({ status: null, signal: null, stdout: '', stderr: '', error: error });
+async function runHost(spawn, command, args, options) {
+    try {
+        const result = await spawn(command, args, options);
+        return { status: result.status, signal: result.signal, stdout: String(result.stdout ?? ''), stderr: String(result.stderr ?? ''), ...(result.error ? { error: result.error } : {}) };
+    }
+    catch (error) {
+        return failedRun(error);
+    }
+}
 // A Playwright test run on a host whose browser cache was never populated (a
 // fresh machine, a new Playwright version): the package is installed, the
 // browser build it pins is not. `playwright install` is the documented fix.
@@ -263,21 +315,14 @@ function relaxManifestPin(root, name, version) {
         writeFileSync(file, JSON.stringify(manifest, null, 2) + '\n');
     return changed;
 }
-export function installEnvironment(roots, io = {}) {
+export async function installEnvironment(roots, io = {}) {
     const spawn = io.spawn ?? defaultSpawn;
     const outcomes = [];
     for (const root of roots) {
         for (const plan of io.plan ? io.plan(root) : plannedInstalls(root, io.failureOutput ?? '')) {
             io.onEvent?.({ kind: 'tool-start', tool: plan.command, detail: `${plan.args.join(' ')} (${path.basename(root)})` });
-            const run = () => {
-                try {
-                    return spawn(plan.command, plan.args, { cwd: root, encoding: 'utf8', timeout: plan.timeoutMs ?? io.timeoutMs ?? 5 * 60_000, windowsHide: true, env: process.env });
-                }
-                catch (error) {
-                    return { status: null, error: error, stdout: '', stderr: '', pid: 0, output: [], signal: null };
-                }
-            };
-            let result = run();
+            const run = () => runHost(spawn, plan.command, plan.args, { cwd: root, encoding: 'utf8', timeout: plan.timeoutMs ?? io.timeoutMs ?? 5 * 60_000, windowsHide: true, env: process.env });
+            let result = await run();
             // A model that writes package-lock.json by hand invents integrity hashes
             // (npm EINTEGRITY) or pins versions that never existed (ETARGET/E404 on a
             // locked entry). The lock is not candidate content: drop it and let npm
@@ -289,7 +334,7 @@ export function installEnvironment(roots, io = {}) {
                 }
                 catch { /* the retry below then repeats the failure honestly */ }
                 io.onEvent?.({ kind: 'text', text: `Environment: ${path.basename(lock)} did not match the registry; removed it and retrying ${plan.command} ${plan.args.join(' ')}` });
-                result = run();
+                result = await run();
             }
             // A pin the registry has never published ("No matching version found for
             // @babel/preset-env@7.23.0"): the model invented the version. Relax that
@@ -297,7 +342,7 @@ export function installEnvironment(roots, io = {}) {
             const unpublished = plan.ecosystem === 'node' && result.status !== 0 ? /No matching version found for ((?:@[\w.-]+\/)?[\w.-]+)@([^\s.]+(?:\.[^\s.]+)*)\.?(?:\n|$)/.exec(String(result.stderr)) : null;
             if (unpublished && relaxManifestPin(root, unpublished[1], unpublished[2])) {
                 io.onEvent?.({ kind: 'text', text: `Environment: ${unpublished[1]}@${unpublished[2]} is not published; relaxed the pin in package.json and retrying ${plan.command} ${plan.args.join(' ')}` });
-                result = run();
+                result = await run();
             }
             // Playwright's downloader tries IPv6 first; on a host whose DNS returns
             // an AAAA record without an IPv6 route, Node's family auto-selection
@@ -306,12 +351,7 @@ export function installEnvironment(roots, io = {}) {
                 const preload = ipv4FirstPreload();
                 if (preload) {
                     io.onEvent?.({ kind: 'text', text: `Environment: the browser download timed out; retrying ${plan.command} ${plan.args.join(' ')} over IPv4` });
-                    try {
-                        result = spawn(plan.command, plan.args, { cwd: root, encoding: 'utf8', timeout: plan.timeoutMs ?? io.timeoutMs ?? 5 * 60_000, windowsHide: true, env: { ...process.env, NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ''} --require ${JSON.stringify(preload)}`.trim() } });
-                    }
-                    catch (error) {
-                        result = { status: null, error: error, stdout: '', stderr: '', pid: 0, output: [], signal: null };
-                    }
+                    result = await runHost(spawn, plan.command, plan.args, { cwd: root, encoding: 'utf8', timeout: plan.timeoutMs ?? io.timeoutMs ?? 5 * 60_000, windowsHide: true, env: { ...process.env, NODE_OPTIONS: `${process.env.NODE_OPTIONS ?? ''} --require ${JSON.stringify(preload)}`.trim() } });
                 }
             }
             io.onEvent?.({ kind: 'tool-end', tool: plan.command });
@@ -365,20 +405,14 @@ function playwrightCli(root) {
  * locations without downloading; an unreadable answer means "unknown", never
  * an install.
  */
-export function missingPlaywrightBrowsers(root, spawn = defaultSpawn) {
+export async function missingPlaywrightBrowsers(root, spawn = defaultSpawn) {
     if (!declaresPlaywright(root))
         return [];
     const cli = playwrightCli(root);
     if (!cli)
         return [];
     const browsers = configuredPlaywrightBrowsers(root);
-    let result;
-    try {
-        result = spawn(cli.command, [...cli.args, 'install', '--dry-run', ...browsers], { cwd: root, encoding: 'utf8', timeout: 30_000, windowsHide: true, env: process.env });
-    }
-    catch {
-        return [];
-    }
+    const result = await runHost(spawn, cli.command, [...cli.args, 'install', '--dry-run', ...browsers], { cwd: root, encoding: 'utf8', timeout: 30_000, windowsHide: true, env: process.env });
     if (result.status !== 0)
         return [];
     const locations = [...String(result.stdout ?? '').matchAll(/Install location:\s+(.+?)\s*$/gm)].map(match => match[1]);
@@ -392,14 +426,17 @@ export function missingPlaywrightBrowsers(root, spawn = defaultSpawn) {
  * idempotent, project-local work happens here; other ecosystems keep their
  * failure-driven repair at verification.
  */
-export function prepareEnvironment(roots, io = {}) {
+export async function prepareEnvironment(roots, io = {}) {
     const spawn = io.spawn ?? defaultSpawn;
-    const dependencies = installEnvironment(roots, { ...io, plan: root => plannedInstalls(root).filter(plan => plan.ecosystem === 'node') });
-    const browsers = installEnvironment(roots, { ...io, plan: root => {
-            const missing = missingPlaywrightBrowsers(root, spawn);
-            const cli = missing.length ? playwrightCli(root) : undefined;
-            return cli ? [{ ecosystem: 'node', root, command: cli.command, args: [...cli.args, 'install', ...missing], timeoutMs: PLAYWRIGHT_INSTALL_TIMEOUT_MS, installs: `Playwright ${missing.join(', ')}` }] : [];
-        } });
+    const dependencies = await installEnvironment(roots, { ...io, plan: root => plannedInstalls(root).filter(plan => plan.ecosystem === 'node') });
+    // The browser plan needs the async dry-run, so it is resolved per root first.
+    const browserPlans = new Map();
+    for (const root of roots) {
+        const missing = await missingPlaywrightBrowsers(root, spawn);
+        const cli = missing.length ? playwrightCli(root) : undefined;
+        browserPlans.set(root, cli ? [{ ecosystem: 'node', root, command: cli.command, args: [...cli.args, 'install', ...missing], timeoutMs: PLAYWRIGHT_INSTALL_TIMEOUT_MS, installs: `Playwright ${missing.join(', ')}` }] : []);
+    }
+    const browsers = await installEnvironment(roots, { ...io, plan: root => browserPlans.get(root) ?? [] });
     return [...dependencies, ...browsers];
 }
 const NETWORK_TIMEOUT = /timed out after \d+ ?ms|ETIMEDOUT|ENETUNREACH|EHOSTUNREACH/i;
@@ -460,7 +497,7 @@ export function detectCheckCommand(root) {
  * groups (`verify-per-group`) so a broken group is fixed while its context is
  * still fresh instead of surfacing as five failed suites at the end.
  */
-export function runGroupCheck(roots, io = {}) {
+export async function runGroupCheck(roots, io = {}) {
     const spawn = io.spawn ?? defaultSpawn;
     for (const root of roots) {
         const check = detectCheckCommand(root);
@@ -468,13 +505,7 @@ export function runGroupCheck(roots, io = {}) {
             continue;
         const label = `${check.command} ${check.args.join(' ')}`;
         io.onEvent?.({ kind: 'tool-start', tool: check.command, detail: `${check.args.join(' ')} (${path.basename(root)}, group check)` });
-        let result;
-        try {
-            result = spawn(check.command, check.args, { cwd: root, encoding: 'utf8', timeout: io.timeoutMs ?? 3 * 60_000, killSignal: 'SIGKILL', windowsHide: true, env: { ...process.env, CI: '1', FORCE_COLOR: '0' }, maxBuffer: 8 * 1024 * 1024 });
-        }
-        catch (error) {
-            result = { status: null, error: error, stdout: '', stderr: '', pid: 0, output: [], signal: null };
-        }
+        const result = await runHost(spawn, check.command, check.args, { cwd: root, encoding: 'utf8', timeout: io.timeoutMs ?? 3 * 60_000, killSignal: 'SIGKILL', windowsHide: true, env: { ...process.env, CI: '1', FORCE_COLOR: '0' }, maxBuffer: 8 * 1024 * 1024 });
         io.onEvent?.({ kind: 'tool-end', tool: check.command });
         const timedOut = result.error?.message?.includes('ETIMEDOUT') || result.signal === 'SIGKILL';
         const output = `${result.stdout ?? ''}\n${result.stderr ?? ''}`.replace(/\u001b\[[0-9;]*m/g, '').trim().slice(-6000);

package/dist/agent-runtime/engine/pieces/openspec.js

@@ -1,4 +1,5 @@
 import { archivedOpenSpecChange, archiveOpenSpecChange } from '../../graph/artifacts.js';
+import { describeArchivePreflight, previewOpenSpecArchive } from '../../graph/archive-preflight.js';
 import { OpenSpecCommandError, resolveOpenSpecCli, runOpenSpec } from '../../openspec.js';
 import { EngineError } from '../contracts.js';
 import { boundedText, json, paramsSchema, text } from './shared.js';
@@ -39,7 +40,16 @@ export function openSpecPieces(bindings) {
                 const item = report.items?.find(entry => entry.id === change && entry.type === 'change');
                 if (!item || typeof item.valid !== 'boolean')
                     throw new EngineError('openspec_invalid_output', 'OpenSpec validation did not report the requested change');
-                return { outcome: exited && item.valid ? 'pass' : 'fail', output: json(report) };
+                // The planning role only learns why it was sent back through history.
+                const note = (suffix, value) => [{ id: context.frame.attemptId + ':' + suffix, transition: context.frame.transition, attempt: context.frame.attempt, ordinal: 0, nodePath: context.frame.nodePath, text: boundedText(value) }];
+                if (!exited || !item.valid) {
+                    const issues = (item.issues ?? []).filter(issue => issue.level === 'ERROR').slice(0, 20).map(issue => `- ${issue.path ? issue.path + ': ' : ''}${issue.message ?? 'invalid'}`);
+                    return { outcome: 'fail', output: json(report), history: note('validate', [`OpenSpec validation failed for change ${change}.`, ...issues].join('\n')) };
+                }
+                const preflight = await previewOpenSpecArchive(deps.context.artifactRoot, change, context.signal);
+                if (!preflight.valid)
+                    return { outcome: 'fail', output: json({ ...report, archivePreflight: preflight }), history: note('archive-preflight', describeArchivePreflight(change, preflight)) };
+                return { outcome: 'pass', output: json(report) };
             },
         }, {
             descriptor: { kind: 'openspec-archive', paramsSchema: { ...schema, properties: { ...schema.properties, requiresVerified: { type: 'boolean' }, reviewedCandidate: { type: 'string' }, approvedCandidate: { type: 'string' } } }, outcomes: ['next', 'failed'], effect: 'write', requiresAI: false },

package/dist/agent-runtime/engine/pieces/role-turn.js

@@ -35,7 +35,7 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
     const note = (line) => context.progress({ type: 'verification-output', payload: { text: line } });
     const environment = options.environmentRetry
         ? environmentNote(options.environmentRetry.installs, 'retry')
-        : hostRepairs ? environmentNote(prepareEnvironment(deps.context.repositories.map(repository => repository.path), environmentIo(deps, note)), 'prepared') : '';
+        : hostRepairs ? environmentNote(await prepareEnvironment(deps.context.repositories.map(repository => repository.path), environmentIo(deps, note)), 'prepared') : '';
     const schema = params.structuredOutput;
     const validate = schema ? ajv.compile(schema) : undefined;
     const roleState = deps.roleState(context);
@@ -79,7 +79,7 @@ export async function executeRoleTurn(deps, params, context, options = {}) {
     if (blocker) {
         const roots = deps.context.repositories.map(repository => repository.path);
         const io = environmentIo(deps, note);
-        const installs = [...installEnvironment(roots, { ...io, failureOutput: blocker }), ...prepareEnvironment(roots, io)];
+        const installs = [...await installEnvironment(roots, { ...io, failureOutput: blocker }), ...await prepareEnvironment(roots, io)];
         if (installs.some(install => install.ok)) {
             note('[environment] The agent reported a missing dependency or tool; the host installed it and runs the turn again.');
             return executeRoleTurn(deps, params, context, { ...options, environmentRetry: { installs } });

package/dist/agent-runtime/engine/pieces/verify.js

@@ -177,7 +177,7 @@ export function verifyPiece(bindings) {
                 const drift = environment.drift.flatMap(item => item.drift.map(entry => ({ root: checkoutRelative(deps.context, item.root), ...entry }))).slice(0, 20);
                 if (drift.length)
                     progress(`[environment] Installed dependencies do not satisfy their declared ranges (${describeDrift(drift)}); the host reinstalls them before judging the failure.`);
-                const repair = repairEnvironment(deps.context, receipt, deps.config.guardrails, progress);
+                const repair = await repairEnvironment(deps.context, receipt, deps.config.guardrails, progress);
                 environmentRepair = { attempted: true, reverified: false, installs: repair.installs.map(install => ({ command: install.command, args: install.args, root: checkoutRelative(deps.context, install.root), ok: install.ok, detail: boundedText(install.detail, 1_000) })), ...(drift.length ? { drift } : {}) };
                 if (repair.refused)
                     blocker = repair.refused;

package/dist/agent-runtime/graph/archive-preflight.d.ts

@@ -0,0 +1,32 @@
+export interface ArchiveRequirementFinding {
+    path: string;
+    line: number;
+    requirement: string;
+}
+export type ArchivePreflight = {
+    valid: true;
+} | {
+    valid: false;
+    reason: string;
+    findings: ArchiveRequirementFinding[];
+};
+/**
+ * Requirements OpenSpec rejects when it rebuilds a main spec on archive: its spec parser reads only
+ * the first non-empty body line before any heading and needs SHALL or MUST there. Delta validation
+ * skips `**Key**:` metadata lines, so a delta (or a pre-existing main-spec requirement) can pass
+ * `openspec validate` and still abort the archive.
+ */
+export declare function requirementsWithoutKeyword(markdown: string): Array<{
+    line: number;
+    requirement: string;
+}>;
+/**
+ * Dry-runs `openspec archive` on a disposable copy of `openspec/`, so a change that validates but
+ * cannot be archived is caught while its author can still edit the plan. Nothing in the
+ * artifact root is written.
+ */
+export declare function previewOpenSpecArchive(artifactRoot: string, change: string, signal?: AbortSignal): Promise<ArchivePreflight>;
+/** Plain-text guidance for the planning role's history. */
+export declare function describeArchivePreflight(change: string, preflight: Extract<ArchivePreflight, {
+    valid: false;
+}>): string;

package/dist/agent-runtime/graph/archive-preflight.js

@@ -0,0 +1,98 @@
+import { cpSync, existsSync, lstatSync, mkdtempSync, readdirSync, readFileSync, rmSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { artifactPath, OpenSpecCommandError, resolveOpenSpecCli, runOpenSpec } from '../openspec.js';
+const ANSI = new RegExp(String.fromCharCode(27) + '\\[[0-9;]*m', 'g');
+/**
+ * Requirements OpenSpec rejects when it rebuilds a main spec on archive: its spec parser reads only
+ * the first non-empty body line before any heading and needs SHALL or MUST there. Delta validation
+ * skips `**Key**:` metadata lines, so a delta (or a pre-existing main-spec requirement) can pass
+ * `openspec validate` and still abort the archive.
+ */
+export function requirementsWithoutKeyword(markdown) {
+    const lines = markdown.split('\n'), findings = [];
+    for (let index = 0; index < lines.length; index++) {
+        const header = lines[index].match(/^###\s+Requirement:\s*(.*)$/);
+        if (!header)
+            continue;
+        let body;
+        for (let next = index + 1; next < lines.length; next++) {
+            const text = lines[next].trim();
+            if (text.startsWith('#'))
+                break;
+            if (text) {
+                body = next;
+                break;
+            }
+        }
+        const text = body === undefined ? header[1] : lines[body];
+        if (!text.includes('SHALL') && !text.includes('MUST'))
+            findings.push({ line: (body ?? index) + 1, requirement: header[1].trim() });
+    }
+    return findings;
+}
+function assertNoSymlinks(root) {
+    for (const entry of readdirSync(root, { withFileTypes: true })) {
+        if (entry.isSymbolicLink())
+            throw new Error('OpenSpec archive refuses symlink trees');
+        if (entry.isDirectory())
+            assertNoSymlinks(path.join(root, entry.name));
+    }
+}
+function capabilityFindings(artifactRoot, change) {
+    const deltas = path.join(artifactRoot, 'openspec/changes', change, 'specs');
+    if (!existsSync(deltas))
+        return [];
+    const findings = [];
+    for (const capability of readdirSync(deltas).sort()) {
+        for (const relative of [`openspec/changes/${change}/specs/${capability}/spec.md`, `openspec/specs/${capability}/spec.md`]) {
+            const file = path.join(artifactRoot, relative);
+            if (!existsSync(file) || !lstatSync(file).isFile())
+                continue;
+            for (const finding of requirementsWithoutKeyword(readFileSync(file, 'utf8')))
+                findings.push({ path: relative, ...finding });
+        }
+    }
+    return findings;
+}
+/**
+ * Dry-runs `openspec archive` on a disposable copy of `openspec/`, so a change that validates but
+ * cannot be archived is caught while its author can still edit the plan. Nothing in the
+ * artifact root is written.
+ */
+export async function previewOpenSpecArchive(artifactRoot, change, signal) {
+    const source = artifactPath(artifactRoot, 'openspec');
+    assertNoSymlinks(source);
+    const staging = mkdtempSync(path.join(os.tmpdir(), 'specrails-archive-preflight-'));
+    try {
+        cpSync(source, path.join(staging, 'openspec'), { recursive: true });
+        let output;
+        try {
+            output = await runOpenSpec(resolveOpenSpecCli(), staging, ['archive', change, '--yes'], signal);
+        }
+        catch (error) {
+            if (!(error instanceof OpenSpecCommandError) || error.exitCode === undefined || error.exitCode < 1)
+                throw error;
+            output = `${error.stdout}\n${error.message}`;
+        }
+        const archiveRoot = path.join(staging, 'openspec/changes/archive');
+        const archived = existsSync(archiveRoot) && readdirSync(archiveRoot).some(name => name.endsWith('-' + change));
+        if (archived && !existsSync(path.join(staging, 'openspec/changes', change)))
+            return { valid: true };
+        const reason = output.replace(ANSI, '').split('\n').map(line => line.trimEnd()).filter(Boolean).join('\n').slice(-2000);
+        return { valid: false, reason, findings: capabilityFindings(artifactRoot, change) };
+    }
+    finally {
+        rmSync(staging, { recursive: true, force: true });
+    }
+}
+/** Plain-text guidance for the planning role's history. */
+export function describeArchivePreflight(change, preflight) {
+    const located = preflight.findings.map(finding => `- ${finding.path}:${finding.line} "${finding.requirement}"`).join('\n');
+    return [
+        `OpenSpec validates change ${change}, but archiving it would fail. OpenSpec's archive output:`,
+        preflight.reason,
+        ...(located ? ['Requirements whose first body line has no SHALL or MUST (OpenSpec reads only that line when it rebuilds a main spec):', located,
+            'Put the SHALL/MUST statement on the line right after "### Requirement: …". For a requirement that only exists in openspec/specs, restate it under "## MODIFIED Requirements" in this change\'s delta with the corrected first line.'] : []),
+    ].join('\n');
+}

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

@@ -356,7 +356,7 @@ function verifyNode(deps) {
                 const drift = environment.drift.flatMap(item => item.drift);
                 if (drift.length)
                     note('developer', `Installed dependencies do not satisfy their declared ranges (${describeDrift(drift)}); the host reinstalls them before judging the failure.`);
-                const repair = repairEnvironment(context, receipt, config.guardrails, text => note('developer', text));
+                const repair = await repairEnvironment(context, receipt, config.guardrails, text => note('developer', text));
                 if (repair.refused)
                     return hostBlocked(blockerMessage(repair.refused));
                 if (repair.installs.some(outcome => outcome.ok)) {

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

@@ -1,6 +1,5 @@
-import type { spawnSync } from 'node:child_process';
 import { type CommandReceipt, type PipelineContext, type VerificationReceipt, type VerificationSelfMutation } from '../pipeline/pipeline-state.js';
-import { type DriftedDependency, type InstallOutcome } from './compact/environment.js';
+import { type DriftedDependency, type HostSpawn, type InstallOutcome } from './compact/environment.js';
 import type { HostBlocker } from './engine/contracts.js';
 import { type GuardrailSettings } from './guardrails.js';
 export type { HostBlocker } from './engine/contracts.js';
@@ -50,6 +49,6 @@ export interface EnvironmentRepair {
  * install (app)`, `Environment: installed …`). An install the host cannot
  * complete for a precondition reason becomes `refused`.
  */
-export declare function repairEnvironment(context: PipelineContext, receipt: VerificationReceipt, guardrails: GuardrailSettings | undefined, note: (text: string) => void, spawn?: typeof spawnSync): EnvironmentRepair;
+export declare function repairEnvironment(context: PipelineContext, receipt: VerificationReceipt, guardrails: GuardrailSettings | undefined, note: (text: string) => void, spawn?: HostSpawn): Promise<EnvironmentRepair>;
 /** A blocker as a durable JSON value: known kind, bounded strings, at most 16 arguments. */
 export declare function boundedBlocker(value: unknown): HostBlocker | undefined;

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

@@ -1,3 +1,11 @@
+// Host-owned repair of a failed verification, shared by the legacy graph
+// (`graph/nodes.ts`) and the engine v2 `verify` piece.
+//
+// A failed check is not always a defect in the change: a fresh worktree has no
+// node_modules, a new machine has no Playwright browser, a registry token has
+// expired. The host classifies the failure first (a precondition it cannot
+// satisfy becomes a structured blocker), installs what it can once, and only a
+// failure that survives that becomes correction feedback.
 import { existsSync } from 'node:fs';
 import path from 'node:path';
 import { describeModifiedFiles } from '../pipeline/pipeline-state.js';
@@ -112,10 +120,10 @@ export function adoptedOutputNote(mutation) {
  * install (app)`, `Environment: installed …`). An install the host cannot
  * complete for a precondition reason becomes `refused`.
  */
-export function repairEnvironment(context, receipt, guardrails, note, spawn) {
+export async function repairEnvironment(context, receipt, guardrails, note, spawn) {
     const failed = receipt.commands.filter(command => command.exitCode !== 0);
     const roots = [...new Set([...installRoots(context, failed), ...driftedFailureRoots(context, receipt).map(item => item.root)])];
-    const installs = installEnvironment(roots, { failureOutput: receipt.commands.map(command => command.output).join('\n'), lockfileRepair: guardrailEnabled(guardrails, 'lockfile-repair'),
+    const installs = await installEnvironment(roots, { failureOutput: receipt.commands.map(command => command.output).join('\n'), lockfileRepair: guardrailEnabled(guardrails, 'lockfile-repair'),
         ...(spawn ? { spawn } : {}), onEvent: event => note(event.kind === 'text' ? event.text ?? '' : `[environment] ${event.tool ?? ''} ${event.detail ?? ''}`.trim()) });
     const refused = installs.find(outcome => outcome.precondition);
     if (!refused)

package/package.json

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