specrails-core 6.0.0 → 6.0.1

package/dist/agent-runtime/change-scope.d.ts

@@ -0,0 +1,63 @@
+import { type PipelineContext, type PipelineRepository } from '../pipeline/pipeline-state.js';
+export interface ChangedFile {
+    path: string;
+    status: 'added' | 'modified' | 'deleted';
+}
+export interface RepositoryChangeSet {
+    repositoryId: string;
+    scope?: string[];
+    files: ChangedFile[];
+    truncated: boolean;
+}
+/** An out-of-scope edit Core undid after a role turn. */
+export interface DiscardedEdit {
+    repositoryId: string;
+    path: string;
+    restored: 'base' | 'previous' | 'removed';
+}
+/** A command without `cwd` runs in its repository's scope directory, never at the root of a larger checkout. */
+export declare function withScopeDefault<T extends {
+    repositoryId: string;
+    cwd?: string;
+}>(context: PipelineContext, command: T): T;
+/** Model-proposed checks stay inside the repository scope: they prove the change, not the whole checkout. */
+export declare function assertProposalInScope(context: PipelineContext, command: {
+    repositoryId: string;
+    cwd?: string;
+}, what?: string): void;
+/** Base commit per repository id; the first call records it. */
+export declare function changeBases(context: PipelineContext): Record<string, string>;
+/** Every path that differs from the base: tracked edits (staged or not), deletions and new untracked files. */
+export declare function repositoryChanges(context: PipelineContext, repository: PipelineRepository, base: string, change?: string): ChangedFile[];
+/** What this run changed, per repository and bounded: untracked files that predate the run are not part of it. */
+export declare function changeSet(context: PipelineContext, change?: string, limit?: number): RepositoryChangeSet[];
+/** Changes outside the repository scope (none when the whole checkout is the repository). */
+export declare function outOfScope(repository: PipelineRepository, files: readonly ChangedFile[]): ChangedFile[];
+interface SavedState {
+    fingerprint: string;
+    content?: Buffer;
+    mode?: number;
+    link?: string;
+}
+/** The out-of-scope state before a role turn: the host undoes only what that turn did. */
+export interface ScopeGuard {
+    change?: string;
+    repositories: Array<{
+        id: string;
+        base: string;
+        before: Map<string, SavedState>;
+    }>;
+}
+export declare function captureOutOfScope(context: PipelineContext, change?: string): ScopeGuard;
+/**
+ * Undoes every out-of-scope edit made since `guard` was captured. A path the
+ * turn changed outside the scope returns to its state before the turn: its
+ * base content, its earlier out-of-scope content, or absence. In-scope work,
+ * ignored files and out-of-scope state that predates the turn stay untouched.
+ */
+export declare function discardOutOfScopeEdits(context: PipelineContext, guard: ScopeGuard): DiscardedEdit[];
+/** Bounded prompt lines for a change set; repository ids prefix the paths only when several repositories are in scope. */
+export declare function renderChangeSet(sets: readonly RepositoryChangeSet[], limit?: number): string[];
+/** One human line naming discarded edits, bounded. */
+export declare function describeDiscarded(edits: readonly DiscardedEdit[], multiple: boolean, limit?: number): string;
+export {};

package/dist/agent-runtime/change-scope.js

@@ -0,0 +1,297 @@
+// The change a run makes, measured by the host from git rather than taken from
+// a role's own summary, and the boundary it must stay inside.
+//
+// Observed (a monorepo app registered as the repository, busuu-courses inside
+// busuu-web): the configured `yarn test` ran at the checkout root and fanned
+// out to every workspace; the fixer then "repaired" .yarnrc.yml, the root
+// package.json and two other apps, the reviewer rejected those unrelated
+// edits, the fixer reverted them, verification failed again — a loop that
+// never converged. A repository scope makes the boundary explicit: commands
+// default to the package, reviews see the exact change set, and edits outside
+// the scope are undone by the host before anyone verifies or reviews them.
+import { spawnSync } from 'node:child_process';
+import { createHash, randomUUID } from 'node:crypto';
+import { lstatSync, mkdirSync, readFileSync, readlinkSync, renameSync, rmSync, symlinkSync, writeFileSync } from 'node:fs';
+import path from 'node:path';
+import { pipelineStateDirectory, withinRepositoryScope } from '../pipeline/pipeline-state.js';
+/** Git's empty tree: the base of a repository without commits. */
+const EMPTY_TREE = '4b825dc642cb6eb9a060e54bf8d69288fbee4904';
+/** Files whose change inside the scope legitimately refreshes a lockfile of an enclosing workspace. */
+const MANIFESTS = new Set(['package.json', 'Cargo.toml', 'go.mod', 'pyproject.toml', 'Pipfile', 'Gemfile', 'composer.json', 'requirements.txt']);
+const LOCKFILES = new Set(['package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lock', 'bun.lockb', 'Cargo.lock', 'go.sum', 'go.work.sum', 'poetry.lock', 'uv.lock', 'Pipfile.lock', 'Gemfile.lock', 'composer.lock', '.pnp.cjs', '.pnp.loader.mjs', '.pnp.data.json']);
+const AGENT_MEMORY = ['.claude', '.codex', '.gemini', '.kimi-code'].map(root => root + '/agent-memory');
+const GENERATED = new Set(['node_modules', 'coverage', '.nyc_output', '.jest-cache', '__pycache__', '.pytest_cache', '.mypy_cache', '.ruff_cache', '.venv', 'venv', '.tox', '.gradle', '.cache', '.turbo']);
+/** Bounded memory for restoring a previous out-of-scope state byte for byte; beyond it the base is restored. */
+const RESTORE_FILE_LIMIT = 8 * 1024 * 1024;
+const RESTORE_TOTAL_LIMIT = 64 * 1024 * 1024;
+/** Untracked files present when the run started are host/user state (overlays, local files), not the change. */
+const PREEXISTING_LIMIT = 20_000;
+function gitEnv() {
+    // An inherited GIT_DIR/GIT_WORK_TREE/GIT_INDEX_FILE must not redirect the inspection.
+    const env = Object.fromEntries(Object.entries(process.env).filter(([key]) => !key.toUpperCase().startsWith('GIT_')));
+    return { ...env, GIT_OPTIONAL_LOCKS: '0', GIT_LITERAL_PATHSPECS: '1', GIT_TERMINAL_PROMPT: '0' };
+}
+function git(root, args, allowFailure = false) {
+    const result = spawnSync('git', ['-c', 'core.quotePath=false', '-c', 'core.fsmonitor=false', '-C', root, ...args], { env: gitEnv(), encoding: 'utf8', maxBuffer: 64 * 1024 * 1024, windowsHide: true });
+    const overflow = result.error?.code === 'ENOBUFS';
+    const ok = !result.error && result.status === 0;
+    if (!ok && !allowFailure)
+        throw new Error(`git ${args[0]} failed in ${root}: ${String(result.error?.message ?? result.stderr ?? '').trim().slice(0, 400)}`);
+    return { ok, stdout: result.stdout ?? '', overflow };
+}
+const posix = (file) => file.split(path.sep).join('/');
+/** A command without `cwd` runs in its repository's scope directory, never at the root of a larger checkout. */
+export function withScopeDefault(context, command) {
+    if (command.cwd !== undefined)
+        return command;
+    const scope = context.repositories.find(repo => repo.id === command.repositoryId)?.scope;
+    return scope?.length ? { ...command, cwd: scope[0] } : command;
+}
+/** Model-proposed checks stay inside the repository scope: they prove the change, not the whole checkout. */
+export function assertProposalInScope(context, command, what = 'verification proposal') {
+    const repository = context.repositories.find(repo => repo.id === command.repositoryId);
+    if (!repository?.scope?.length || command.cwd === undefined)
+        return;
+    const relative = posix(path.relative(repository.path, path.resolve(repository.path, command.cwd)));
+    if (relative === '..' || relative.startsWith('../') || path.isAbsolute(relative) || !withinRepositoryScope(repository, relative)) {
+        throw new Error(`Invalid ${what} cwd ${JSON.stringify(command.cwd)}: it runs outside the repository scope (${repository.scope.join(', ')}). Omit cwd to run in ${repository.scope[0]}, or name a directory inside the scope.`);
+    }
+}
+/** Untracked, non-ignored paths; a checkout with an enormous untracked tree reports directories instead of files. */
+function untracked(root) {
+    const files = git(root, ['ls-files', '--others', '--exclude-standard', '-z'], true);
+    if (files.ok)
+        return files.stdout.split('\0').filter(Boolean);
+    if (!files.overflow)
+        git(root, ['ls-files', '--others', '--exclude-standard', '-z']);
+    return git(root, ['ls-files', '--others', '--exclude-standard', '--directory', '-z']).stdout.split('\0').filter(Boolean);
+}
+function baseFile(context) { return path.join(pipelineStateDirectory(context), 'change-base.json'); }
+/**
+ * The commit each repository's change is measured against — the host's frozen
+ * base when it declared one, otherwise HEAD the first time Core asks (before
+ * any role edits) — plus the untracked files that already existed then.
+ * Recorded once, so every later turn measures the same change.
+ */
+function baseRecords(context) {
+    const file = baseFile(context);
+    let recorded = {};
+    try {
+        const value = JSON.parse(readFileSync(file, 'utf8'));
+        if (value.schemaVersion === 1 && value.repositories && typeof value.repositories === 'object')
+            recorded = value.repositories;
+    }
+    catch { /* first use */ }
+    let changed = false;
+    for (const repository of context.repositories) {
+        const known = recorded[repository.id];
+        if (known && typeof known.base === 'string' && /^[a-f0-9]{40,64}$/.test(known.base))
+            continue;
+        let base = repository.baseSha;
+        if (!base) {
+            const head = git(repository.path, ['rev-parse', '--verify', '--quiet', 'HEAD^{commit}'], true);
+            base = head.ok && /^[a-f0-9]{40,64}$/.test(head.stdout.trim()) ? head.stdout.trim() : EMPTY_TREE;
+        }
+        let present;
+        try {
+            present = untracked(repository.path);
+        }
+        catch { /* not a git checkout: the change cannot be measured */ }
+        recorded[repository.id] = { base, ...(present && present.length <= PREEXISTING_LIMIT ? { preexisting: present } : {}) };
+        changed = true;
+    }
+    if (changed) {
+        mkdirSync(path.dirname(file), { recursive: true, mode: 0o700 });
+        const temp = file + '.' + randomUUID() + '.tmp';
+        try {
+            writeFileSync(temp, JSON.stringify({ schemaVersion: 1, repositories: recorded }) + '\n', { flag: 'wx', mode: 0o600 });
+            renameSync(temp, file);
+        }
+        finally {
+            rmSync(temp, { force: true });
+        }
+    }
+    return recorded;
+}
+/** Base commit per repository id; the first call records it. */
+export function changeBases(context) {
+    return Object.fromEntries(Object.entries(baseRecords(context)).map(([id, record]) => [id, record.base]));
+}
+/** Host and runtime state, the change's own OpenSpec artifacts and generated trees are never part of the code change. */
+function ignored(context, repository, change, file, fresh) {
+    if (file === '.specrails' || file.startsWith('.specrails/'))
+        return true;
+    if (repository.id === context.artifactRepositoryId && change && (file === 'openspec/changes/' + change || file.startsWith('openspec/changes/' + change + '/')))
+        return true;
+    if (!fresh)
+        return false;
+    return AGENT_MEMORY.some(root => file === root || file.startsWith(root + '/')) || file.split('/').some(segment => GENERATED.has(segment));
+}
+/** Every path that differs from the base: tracked edits (staged or not), deletions and new untracked files. */
+export function repositoryChanges(context, repository, base, change) {
+    const files = new Map();
+    const diff = git(repository.path, ['diff', '--name-status', '-z', '--no-renames', '--ignore-submodules=all', base, '--']).stdout.split('\0');
+    for (let i = 0; i + 1 < diff.length; i += 2) {
+        const status = diff[i], file = diff[i + 1];
+        if (!status || !file || ignored(context, repository, change, file, false))
+            continue;
+        files.set(file, status.startsWith('A') ? 'added' : status.startsWith('D') ? 'deleted' : 'modified');
+    }
+    for (const file of untracked(repository.path)) {
+        const relative = file.replace(/\/$/, '');
+        if (!files.has(relative) && !ignored(context, repository, change, relative, true))
+            files.set(file, 'added');
+    }
+    return [...files].map(([file, status]) => ({ path: file, status })).sort((a, b) => a.path.localeCompare(b.path));
+}
+/** What this run changed, per repository and bounded: untracked files that predate the run are not part of it. */
+export function changeSet(context, change, limit = 5000) {
+    const records = baseRecords(context);
+    return context.repositories.map(repository => {
+        const record = records[repository.id];
+        const preexisting = new Set(record.preexisting ?? []);
+        const files = repositoryChanges(context, repository, record.base, change).filter(file => !(file.status === 'added' && preexisting.has(file.path)));
+        return { repositoryId: repository.id, ...(repository.scope ? { scope: repository.scope } : {}), files: files.slice(0, limit), truncated: files.length > limit };
+    });
+}
+function dependencyFileForScope(repository, file) {
+    // A dependency change in the package legitimately refreshes the lockfile (or
+    // Yarn's install artifacts) of a workspace that encloses the scope.
+    const enclosing = (directory) => (repository.scope ?? []).some(scope => directory === '.' || directory === '' || scope === directory || scope.startsWith(directory + '/'));
+    if (LOCKFILES.has(path.posix.basename(file)))
+        return enclosing(path.posix.dirname(file));
+    const yarn = /^(?:(.*)\/)?\.yarn\/(?:cache\/|install-state\.gz$)/.exec(file);
+    return yarn !== null && enclosing(yarn[1] ?? '.');
+}
+/** Changes outside the repository scope (none when the whole checkout is the repository). */
+export function outOfScope(repository, files) {
+    if (!repository.scope?.length)
+        return [];
+    const manifestChanged = files.some(file => withinRepositoryScope(repository, file.path) && MANIFESTS.has(path.posix.basename(file.path)));
+    return files.filter(file => !withinRepositoryScope(repository, file.path.replace(/\/$/, '')) && !(manifestChanged && dependencyFileForScope(repository, file.path)));
+}
+function fingerprintOf(file) {
+    const stat = lstatSync(file, { throwIfNoEntry: false });
+    if (!stat)
+        return { fingerprint: 'missing' };
+    if (stat.isSymbolicLink()) {
+        const link = readlinkSync(file);
+        return { fingerprint: 'link:' + link, link };
+    }
+    if (!stat.isFile())
+        return { fingerprint: 'other' };
+    const content = readFileSync(file);
+    return { fingerprint: `file:${stat.mode & 0o777}:${createHash('sha256').update(content).digest('hex')}`, content, mode: stat.mode & 0o777 };
+}
+export function captureOutOfScope(context, change) {
+    const scoped = context.repositories.filter(repository => repository.scope?.length);
+    if (!scoped.length)
+        return { change, repositories: [] };
+    const bases = changeBases(context);
+    let budget = 0;
+    return {
+        change,
+        repositories: scoped.map(repository => {
+            const base = bases[repository.id];
+            const before = new Map();
+            for (const file of outOfScope(repository, repositoryChanges(context, repository, base, change))) {
+                const { content, ...saved } = fingerprintOf(path.join(repository.path, file.path));
+                const keep = content && content.length <= RESTORE_FILE_LIMIT && budget + content.length <= RESTORE_TOTAL_LIMIT;
+                if (keep)
+                    budget += content.length;
+                before.set(file.path, keep ? { ...saved, content } : saved);
+            }
+            return { id: repository.id, base, before };
+        }),
+    };
+}
+function restoreFromBase(repository, base, files) {
+    const restored = [];
+    for (let i = 0; i < files.length; i += 100) {
+        const batch = files.slice(i, i + 100);
+        const tracked = base === EMPTY_TREE ? new Set() : new Set(git(repository.path, ['ls-tree', '-r', '-z', '--name-only', '--full-tree', base, '--', ...batch.map(file => file.replace(/\/$/, ''))]).stdout.split('\0').filter(Boolean));
+        const existing = batch.filter(file => tracked.has(file));
+        if (existing.length)
+            git(repository.path, ['restore', '--source=' + base, '--staged', '--worktree', '--', ...existing]);
+        const added = batch.filter(file => !tracked.has(file));
+        if (added.length)
+            git(repository.path, ['rm', '-r', '-q', '--cached', '--ignore-unmatch', '--', ...added.map(file => file.replace(/\/$/, ''))], true);
+        for (const file of added)
+            rmSync(path.join(repository.path, file), { recursive: true, force: true });
+        restored.push(...existing.map(file => ({ repositoryId: repository.id, path: file, restored: 'base' })), ...added.map(file => ({ repositoryId: repository.id, path: file.replace(/\/$/, ''), restored: 'removed' })));
+    }
+    return restored;
+}
+function restorePrevious(repository, file, saved) {
+    const target = path.join(repository.path, file);
+    rmSync(target, { recursive: true, force: true });
+    if (saved.fingerprint === 'missing')
+        return;
+    mkdirSync(path.dirname(target), { recursive: true });
+    if (saved.link !== undefined)
+        symlinkSync(saved.link, target);
+    else
+        writeFileSync(target, saved.content, { mode: saved.mode ?? 0o644 });
+}
+/**
+ * Undoes every out-of-scope edit made since `guard` was captured. A path the
+ * turn changed outside the scope returns to its state before the turn: its
+ * base content, its earlier out-of-scope content, or absence. In-scope work,
+ * ignored files and out-of-scope state that predates the turn stay untouched.
+ */
+export function discardOutOfScopeEdits(context, guard) {
+    const discarded = [];
+    for (const entry of guard.repositories) {
+        const repository = context.repositories.find(repo => repo.id === entry.id);
+        const now = outOfScope(repository, repositoryChanges(context, repository, entry.base, guard.change)).map(file => file.path);
+        const changedNow = new Set(now);
+        // A tracked file the turn returned to its base content leaves the change smaller: that clean-up stays.
+        const settled = [...entry.before.keys()].filter(file => !changedNow.has(file));
+        const tracked = settled.length && entry.base !== EMPTY_TREE ? new Set(git(repository.path, ['ls-tree', '-r', '-z', '--name-only', '--full-tree', entry.base, '--', ...settled]).stdout.split('\0').filter(Boolean)) : new Set();
+        const toBase = [];
+        for (const file of new Set([...now, ...entry.before.keys()])) {
+            const saved = entry.before.get(file);
+            if (!saved) {
+                toBase.push(file);
+                continue;
+            }
+            if (saved.fingerprint === fingerprintOf(path.join(repository.path, file)).fingerprint)
+                continue;
+            if (!changedNow.has(file) && tracked.has(file))
+                continue;
+            if (saved.fingerprint === 'missing' || saved.link !== undefined || saved.content) {
+                restorePrevious(repository, file, saved);
+                discarded.push({ repositoryId: repository.id, path: file, restored: 'previous' });
+            }
+            else
+                toBase.push(file);
+        }
+        discarded.push(...restoreFromBase(repository, entry.base, toBase));
+    }
+    return discarded.sort((a, b) => a.repositoryId.localeCompare(b.repositoryId) || a.path.localeCompare(b.path));
+}
+/** Bounded prompt lines for a change set; repository ids prefix the paths only when several repositories are in scope. */
+export function renderChangeSet(sets, limit = 150) {
+    const multiple = sets.length > 1;
+    const lines = [];
+    let hidden = 0;
+    for (const set of sets) {
+        for (const file of set.files) {
+            if (lines.length >= limit) {
+                hidden++;
+                continue;
+            }
+            lines.push(`- ${multiple ? '`' + set.repositoryId + '` ' : ''}\`${file.path}\` (${file.status})`);
+        }
+        if (set.truncated)
+            hidden++;
+    }
+    if (hidden)
+        lines.push(`- … ${hidden}${sets.some(set => set.truncated) ? '+' : ''} more not listed; compare against the base with git to see them.`);
+    return lines;
+}
+/** One human line naming discarded edits, bounded. */
+export function describeDiscarded(edits, multiple, limit = 12) {
+    const names = edits.map(edit => (multiple ? edit.repositoryId + ':' : '') + edit.path);
+    return names.slice(0, limit).join(', ') + (names.length > limit ? ` and ${names.length - limit} more` : '');
+}

package/dist/agent-runtime/cli.js

@@ -126,7 +126,7 @@ export async function runRuntimeCommand(flags, positionals, emit = value => proc
         return 0;
     }
     if (command === 'api') {
-        emit({ type: 'runtime-api', apiVersion: RUNTIME_API_VERSION, coreVersion: CORE_PACKAGE_VERSION, runtimeIdentity: coreRuntimeIdentity(), workflowVersions: [CORE_WORKFLOW_VERSION], capabilities: { scopedRecovery: 1, efficientRoleExecution: 1, reproducibleVerification: 1, implementationEfficiencyMetrics: 1, compactAgentLoop: 1, configurableGuardrails: 1, compactOutputBudget: 1, roleThinkingControl: 1 }, guardrails: GUARDRAIL_CATALOG });
+        emit({ type: 'runtime-api', apiVersion: RUNTIME_API_VERSION, coreVersion: CORE_PACKAGE_VERSION, runtimeIdentity: coreRuntimeIdentity(), workflowVersions: [CORE_WORKFLOW_VERSION], capabilities: { scopedRecovery: 1, efficientRoleExecution: 1, reproducibleVerification: 1, implementationEfficiencyMetrics: 1, compactAgentLoop: 1, configurableGuardrails: 1, compactOutputBudget: 1, roleThinkingControl: 1, repositoryScope: 1 }, guardrails: GUARDRAIL_CATALOG });
         return 0;
     }
     if (command === 'validate') {

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

@@ -5,12 +5,24 @@ interface EnvironmentInstall {
     command: string;
     args: string[];
 }
+/** `precondition`: the install failed for a reason only the host can repair (see hostPreconditionFailure). */
 interface InstallOutcome extends EnvironmentInstall {
     ok: boolean;
     detail: string;
+    precondition?: string;
 }
 /** True when a verification failure looks like a missing toolchain/dependency rather than a code defect. */
 export declare function isEnvironmentFailure(exitCode: number | null | undefined, output: string): boolean;
+/**
+ * Failures that no edit to the change can repair, because the verification
+ * process itself lacks something only the host can grant: an environment
+ * variable a configuration file references, registry credentials, registry
+ * network access, git credentials for a dependency. Feeding them to a fixer
+ * makes it edit package-manager configuration to route around the missing
+ * secret (observed: `.yarnrc.yml` rewritten, reverted by review, rewritten
+ * again). Returns a short host-facing reason, or undefined.
+ */
+export declare function hostPreconditionFailure(output: string): string | undefined;
 /** Packages a failure output names explicitly (`Try \`npm i --save-dev @types/jest\``); the host installs exactly those. */
 export declare function suggestedPackages(output: string): string[];
 /** Dependencies package.json declares that node_modules does not hold (bounded). */

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

@@ -19,6 +19,8 @@ const ENVIRONMENT_SIGNATURES = [
     /jest: not found|vitest: not found|mocha: not found|tsc: not found|pytest: not found/i,
     /TS2582|Do you need to install type definitions|Try `npm i --save-dev @types\//i,
     /Module (?:[\w@./-]+) in the \w+ option was not found|Preset [\w@./-]+ not found|Cannot find module '(?:ts-jest|babel-jest|@swc\/jest|ts-node|tsx)'/i,
+    // Yarn Berry refuses to run scripts in a checkout that was never installed.
+    /doesn't seem to have been installed - running an install there might help|Couldn't find the node_modules state file - running an install might help/i,
 ];
 /** True when a verification failure looks like a missing toolchain/dependency rather than a code defect. */
 export function isEnvironmentFailure(exitCode, output) {
@@ -27,6 +29,33 @@ export function isEnvironmentFailure(exitCode, output) {
     const tail = output.slice(-6000);
     return ENVIRONMENT_SIGNATURES.some(pattern => pattern.test(tail));
 }
+const REGISTRY = String.raw `(?:registry|npmjs\.org|yarnpkg\.com|npm\.pkg\.github\.com|pkgs\.dev\.azure\.com|jfrog|artifactory|nexus|pypi\.org|crates\.io|proxy\.golang\.org)`;
+/**
+ * Failures that no edit to the change can repair, because the verification
+ * process itself lacks something only the host can grant: an environment
+ * variable a configuration file references, registry credentials, registry
+ * network access, git credentials for a dependency. Feeding them to a fixer
+ * makes it edit package-manager configuration to route around the missing
+ * secret (observed: `.yarnrc.yml` rewritten, reverted by review, rewritten
+ * again). Returns a short host-facing reason, or undefined.
+ */
+export function hostPreconditionFailure(output) {
+    const text = output.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, '').slice(-16_000);
+    const variable = /Environment variable not found \(([A-Za-z_][A-Za-z0-9_]*)\)/.exec(text);
+    if (variable)
+        return `the environment variable ${variable[1]} is not available to verification commands, and a package-manager configuration file requires it`;
+    if (/\bYN0041\b/.test(text) || /YN0035[\s\S]{0,400}?Response Code: 40[13]\b/.test(text) || /Response code 40[13] \((?:Unauthorized|Forbidden)\)/i.test(text)
+        || /npm (?:ERR!|error) code (?:E401|E403|ENEEDAUTH)\b/.test(text) || /ERR_PNPM_FETCH_40[13]\b/.test(text)
+        || new RegExp(String.raw `\b40[13] (?:Unauthorized|Forbidden)\b[^\n]{0,80}https?://[^\s]*${REGISTRY}`, 'i').test(text)
+        || /\b(?:401|403) Client Error: (?:Unauthorized|Forbidden) for url/.test(text))
+        return 'the package registry rejected the credentials available to verification commands (HTTP 401/403)';
+    if (/npm (?:ERR!|error) code (?:ENOTFOUND|EAI_AGAIN|ECONNREFUSED|ETIMEDOUT|ECONNRESET)\b/.test(text) || /ERR_PNPM_META_FETCH_FAIL\b/.test(text)
+        || new RegExp(String.raw `\b(?:ENOTFOUND|EAI_AGAIN)\b[^\n]{0,200}${REGISTRY}|${REGISTRY}[^\n]{0,200}\b(?:ENOTFOUND|EAI_AGAIN)\b`, 'i').test(text))
+        return 'the package registry cannot be reached from the verification environment';
+    if (/fatal: could not read (?:Username|Password) for/.test(text) || /Permission denied \(publickey\)/.test(text))
+        return 'git credentials needed to fetch a dependency are not available to verification commands';
+    return undefined;
+}
 /** Packages a failure output names explicitly (`Try \`npm i --save-dev @types/jest\``); the host installs exactly those. */
 export function suggestedPackages(output) {
     const packages = new Set();
@@ -155,7 +184,8 @@ export function installEnvironment(roots, io = {}) {
             const ok = result.status === 0;
             const detail = ok ? `installed ${plan.ecosystem} dependencies in ${path.basename(root)}` : `${plan.command} ${plan.args.join(' ')} failed in ${path.basename(root)}: ${String(result.stderr || result.error?.message || `exit ${result.status}`).trim().slice(0, 400)}`;
             io.onEvent?.({ kind: 'text', text: `Environment: ${detail}` });
-            outcomes.push({ ...plan, ok, detail });
+            const precondition = ok ? undefined : hostPreconditionFailure(`${result.stdout ?? ''}\n${result.stderr ?? ''}`);
+            outcomes.push({ ...plan, ok, detail, ...(precondition ? { precondition } : {}) });
         }
     }
     return outcomes;

package/dist/agent-runtime/compact/test-reachability.js

@@ -98,7 +98,11 @@ function tokenReaches(token, file, root, discovery) {
  * file. Unknown ⇒ true: only an enumerating command can prove absence.
  */
 export function commandReachesTest(root, command, file) {
-    const target = posix(file);
+    // Path arguments are relative to the directory the command runs in (a
+    // package inside a larger checkout), while reported files are relative to
+    // the checkout: compare both from the command's directory.
+    const base = path.resolve(root, command.cwd ?? '.');
+    const target = posix(path.relative(base, path.resolve(root, file)));
     let judged = false;
     for (const tokens of segments(expandCommandText(root, command))) {
         if (!tokens.length)
@@ -117,7 +121,7 @@ export function commandReachesTest(root, command, file) {
         if (!paths.some(token => TEST_FILE_PATTERN.test(posix(token)) || token.includes('*') || token.endsWith('...')))
             continue;
         judged = true;
-        if (paths.some(token => tokenReaches(token, target, root, discovery)))
+        if (paths.some(token => tokenReaches(token, target, base, discovery)))
             return true;
     }
     return !judged;

package/dist/agent-runtime/core-host.d.ts

@@ -5,7 +5,7 @@ import { parseAgentObject } from './graph/artifacts.js';
 import { type RuntimeIdentity } from './runtime-identity.js';
 import type { WorkflowEvent, WorkflowSpan, WorkflowState } from './workflow-types.js';
 export declare const RUNTIME_API_VERSION = 1;
-export declare const CORE_WORKFLOW_VERSION = "6";
+export declare const CORE_WORKFLOW_VERSION = "7";
 export declare const CORE_PACKAGE_VERSION: string;
 export declare function coreRuntimeIdentity(): RuntimeIdentity;
 export { parseAgentObject };

package/dist/agent-runtime/core-host.js

@@ -15,7 +15,7 @@ import { assertEffortSupported } from './capabilities.js';
 import { runtimePackageIntegrity } from './runtime-identity.js';
 import { readWorkflowState, runWorkflow } from './workflow.js';
 export const RUNTIME_API_VERSION = 1;
-export const CORE_WORKFLOW_VERSION = '6';
+export const CORE_WORKFLOW_VERSION = '7';
 export const CORE_PACKAGE_VERSION = JSON.parse(readFileSync(new URL('../../package.json', import.meta.url), 'utf8')).version;
 export function coreRuntimeIdentity() {
     return { packageVersion: CORE_PACKAGE_VERSION, workflowVersion: CORE_WORKFLOW_VERSION, instructionsVersion: String(ROLE_INSTRUCTIONS_VERSION), packageIntegrity: runtimePackageIntegrity(), apiVersion: 1 };

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

@@ -3,6 +3,7 @@ import { randomUUID } from 'node:crypto';
 import { cpSync, existsSync, lstatSync, mkdirSync, mkdtempSync, readFileSync, readdirSync, renameSync, rmSync, writeFileSync } from 'node:fs';
 import path from 'node:path';
 import { checkArchive, pipelineStateDirectory, transitionPipeline, validateVerificationRequest, } from '../../pipeline/pipeline-state.js';
+import { assertProposalInScope, withScopeDefault } from '../change-scope.js';
 export const SLUG = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
 export function object(value) {
     if (!value || typeof value !== 'object' || Array.isArray(value))
@@ -105,8 +106,10 @@ export function proposedVerification(context, configured, verification) {
             throw new Error('Invalid proposed verification command');
         return { repositoryId: command.repositoryId, command: command.command, args: command.args, ...(typeof command.cwd === 'string' && command.cwd ? { cwd: command.cwd } : {}) };
     }).filter(command => !covered.has(command.repositoryId) && context.repositories.some(repository => repository.id === command.repositoryId));
+    for (const command of proposed)
+        assertProposalInScope(context, command, 'proposed verification command');
     if (proposed.length)
-        validateVerificationRequest(context, { kind: 'scoped', commands: proposed });
+        validateVerificationRequest(context, { kind: 'scoped', commands: proposed.map(command => withScopeDefault(context, command)) });
     return proposed;
 }
 /** Publish an archive prepared by the real CLI. The durable write set makes a

package/dist/agent-runtime/graph/convergence.d.ts

@@ -0,0 +1,26 @@
+import type { VerificationReceipt } from '../../pipeline/pipeline-state.js';
+import type { WorkflowState } from '../workflow-types.js';
+/** One verify visit, as the convergence guard remembers it. */
+export interface VerifyOutcome {
+    at: string;
+    candidateHash: string;
+    planHash: string;
+    passed: boolean;
+    /** Normalized identity of the first failure: the command plus its output with volatile details removed. */
+    signature?: string;
+    summary?: string;
+}
+/** Verify visits since the latest explicit resume: a human continuing a blocked run grants a fresh budget, as for attempts. */
+export declare function outcomesSinceResume(history: readonly VerifyOutcome[], checkpoint: WorkflowState): VerifyOutcome[];
+/** Identity and one-line description of a failed receipt (or of a host finding that failed a green receipt). */
+export declare function describeFailure(receipt: Pick<VerificationReceipt, 'commands' | 'reason'>, roots: readonly string[], finding?: string): {
+    signature: string;
+    summary: string;
+};
+/**
+ * Why the failure just recorded (`current`, not yet in `history`) proves the
+ * correction loop is not converging, or undefined when another round can help.
+ */
+export declare function divergence(history: readonly VerifyOutcome[], current: VerifyOutcome): string | undefined;
+/** The same test for a candidate that has not been verified again yet: an unchanged failed candidate is not worth a new run. */
+export declare function unchangedFailure(history: readonly VerifyOutcome[], candidateHash: string, planHash: string): VerifyOutcome | undefined;

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

@@ -0,0 +1,62 @@
+import { fingerprint } from '../durable-store.js';
+/** Verify visits since the latest explicit resume: a human continuing a blocked run grants a fresh budget, as for attempts. */
+export function outcomesSinceResume(history, checkpoint) {
+    const resumed = [...checkpoint.events].reverse().find(event => event.type === 'workflow_resumed');
+    return history.filter(entry => !resumed || entry.at >= resumed.timestamp);
+}
+function normalized(output, roots) {
+    let text = output.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, '');
+    for (const root of [...roots].sort((a, b) => b.length - a.length))
+        text = text.split(root).join('<repo>');
+    return text.split(/\r?\n/)
+        .map(line => line.replace(/\b[0-9a-f]{7,64}\b/gi, '#').replace(/\d+(?:[.,]\d+)*/g, '0').replace(/\s+/g, ' ').trim())
+        .filter(Boolean).slice(-40).join('\n');
+}
+/** The last line that says what went wrong, bounded. */
+function headline(output) {
+    const lines = output.replace(/\u001b\[[0-9;?]*[A-Za-z]/g, '').split(/\r?\n/).map(line => line.trim()).filter(Boolean);
+    const telling = [...lines].reverse().find(line => /error|fail|✕|×|not found|cannot|denied|refused|forbidden|unauthori[sz]ed/i.test(line));
+    return (telling ?? lines.at(-1) ?? '').slice(0, 300);
+}
+/** Identity and one-line description of a failed receipt (or of a host finding that failed a green receipt). */
+export function describeFailure(receipt, roots, finding) {
+    if (finding)
+        return { signature: fingerprint({ finding: normalized(finding, roots) }), summary: finding.slice(0, 300) };
+    const failed = receipt.commands.find(command => command.exitCode !== 0);
+    if (!failed)
+        return { signature: fingerprint({ reason: receipt.reason ?? 'verification failed' }), summary: receipt.reason ?? 'verification failed' };
+    const name = failed.label ?? [failed.command, ...failed.args].join(' ');
+    const detail = headline(failed.output);
+    return {
+        signature: fingerprint({ check: failed.key ?? [failed.command, ...failed.args, failed.cwd], exitCode: failed.exitCode, output: normalized(failed.output, roots) }),
+        summary: `${name} exited ${failed.exitCode}${detail ? `: ${detail}` : ''}`.slice(0, 400),
+    };
+}
+/**
+ * Why the failure just recorded (`current`, not yet in `history`) proves the
+ * correction loop is not converging, or undefined when another round can help.
+ */
+export function divergence(history, current) {
+    if (current.passed || !current.signature)
+        return undefined;
+    const cycle = history.find(entry => !entry.passed && entry.candidateHash === current.candidateHash && entry.planHash === current.planHash);
+    if (cycle)
+        return `The correction round returned the change to a state that already failed verification (${current.summary}). Running the same checks again cannot pass.`;
+    let repeats = 0;
+    for (const entry of [...history].reverse()) {
+        if (entry.passed || entry.signature !== current.signature)
+            break;
+        repeats++;
+    }
+    if (repeats >= 2)
+        return `The same verification failure survived ${repeats} correction rounds unchanged (${current.summary}). It is most likely outside what this change can fix: a pre-existing failure, another package, or the environment.`;
+    const previous = history.at(-1);
+    if (previous?.passed && history.some(entry => !entry.passed && entry.signature === current.signature)) {
+        return `A review correction brought back a verification failure that an earlier correction had fixed (${current.summary}). The review request and the checks pull in opposite directions; decide which one applies before resuming.`;
+    }
+    return undefined;
+}
+/** The same test for a candidate that has not been verified again yet: an unchanged failed candidate is not worth a new run. */
+export function unchangedFailure(history, candidateHash, planHash) {
+    return [...history].reverse().find(entry => !entry.passed && entry.candidateHash === candidateHash && entry.planHash === planHash);
+}