specrails-core 6.4.0 → 6.6.0

package/dist/agent-runtime/session/testing/fixture-replayer.d.ts

@@ -0,0 +1,41 @@
+import type { ProcessSpawner, ProcessSpec } from '../drivers/common/process.js';
+/** One recorded transcript row (see the spike harness in the OpenSpec change). */
+export interface FixtureRow {
+    t: number;
+    dir: 'in' | 'out' | 'ctl';
+    json?: Record<string, unknown> | null;
+    raw?: string;
+}
+export declare function loadFixture(file: string): FixtureRow[];
+export interface ReplaySession {
+    readonly spec: ProcessSpec;
+    /** Lines the driver wrote to stdin, parsed. */
+    readonly written: Array<Record<string, unknown>>;
+    readonly inputEnded: boolean;
+    readonly terminated: boolean;
+    /** Resolves when the replay is blocked waiting for the driver, or finished. */
+    idle(): Promise<void>;
+}
+/**
+ * Replays a recorded provider transcript as a ProcessSpawner:
+ * - `out` rows are emitted in order (time compressed);
+ * - before passing an `in` row, replay waits until the driver wrote a line,
+ *   then maps recorded ids/uuids to the ones the driver used;
+ * - a `ctl kill` row waits for `terminate()` (output after it is what the
+ *   provider printed while stopping); `closeStdin` waits for `endInput()`;
+ * - after the last row the process stays alive until terminated, like a
+ *   resident provider, unless the transcript recorded a clean exit.
+ */
+export declare class FixtureReplayer {
+    private readonly rows;
+    private readonly options;
+    readonly sessions: ReplaySession[];
+    constructor(rows: FixtureRow[], options?: {
+        exitAtEnd?: boolean;
+    });
+    static fromFile(file: string, options?: {
+        exitAtEnd?: boolean;
+    }): FixtureReplayer;
+    get last(): ReplaySession;
+    readonly spawner: ProcessSpawner;
+}

package/dist/agent-runtime/session/testing/fixture-replayer.js

@@ -0,0 +1,172 @@
+import { readFileSync } from 'node:fs';
+export function loadFixture(file) {
+    return readFileSync(file, 'utf8').split('\n').filter((line) => line.trim()).map((line) => JSON.parse(line));
+}
+/** Fields whose recorded values are replaced by the values the driver actually wrote. */
+const REMAPPED = ['id', 'uuid', 'command_uuid'];
+/**
+ * Replays a recorded provider transcript as a ProcessSpawner:
+ * - `out` rows are emitted in order (time compressed);
+ * - before passing an `in` row, replay waits until the driver wrote a line,
+ *   then maps recorded ids/uuids to the ones the driver used;
+ * - a `ctl kill` row waits for `terminate()` (output after it is what the
+ *   provider printed while stopping); `closeStdin` waits for `endInput()`;
+ * - after the last row the process stays alive until terminated, like a
+ *   resident provider, unless the transcript recorded a clean exit.
+ */
+export class FixtureReplayer {
+    rows;
+    options;
+    sessions = [];
+    constructor(rows, options = {}) {
+        this.rows = rows;
+        this.options = options;
+    }
+    static fromFile(file, options) {
+        return new FixtureReplayer(loadFixture(file), options);
+    }
+    get last() {
+        const session = this.sessions.at(-1);
+        if (!session)
+            throw new Error('fixture replayer: nothing spawned');
+        return session;
+    }
+    spawner = (spec, handlers) => {
+        const rows = this.rows;
+        const ids = new Map();
+        const written = [];
+        let inputsSeen = 0;
+        let index = 0;
+        let inputOpen = true;
+        let terminated = false;
+        let exit = null;
+        let resolveExit;
+        const exited = new Promise((resolve) => { resolveExit = resolve; });
+        let idleWaiters = [];
+        let blocked = false;
+        const exitAtEnd = this.options.exitAtEnd ?? false;
+        const remap = (value) => {
+            if (Array.isArray(value))
+                return value.map(remap);
+            if (value && typeof value === 'object') {
+                return Object.fromEntries(Object.entries(value).map(([key, inner]) => [key,
+                    REMAPPED.includes(key) && ids.has(JSON.stringify(inner)) ? ids.get(JSON.stringify(inner)) : remap(inner)]));
+            }
+            return value;
+        };
+        const finish = (result) => {
+            if (exit)
+                return;
+            exit = result;
+            blocked = true;
+            resolveExit(result);
+            flushIdle();
+        };
+        const flushIdle = () => { const waiters = idleWaiters; idleWaiters = []; for (const waiter of waiters)
+            waiter(); };
+        const step = () => {
+            if (exit)
+                return;
+            blocked = false;
+            while (index < rows.length) {
+                const row = rows[index];
+                if (row.dir === 'in') {
+                    if (written.length <= inputsSeen) {
+                        blocked = true;
+                        flushIdle();
+                        return;
+                    }
+                    const actual = written[inputsSeen];
+                    for (const key of REMAPPED) {
+                        const recorded = row.json?.[key];
+                        if (recorded !== undefined && actual[key] !== undefined)
+                            ids.set(JSON.stringify(recorded), actual[key]);
+                    }
+                    inputsSeen += 1;
+                    index += 1;
+                    continue;
+                }
+                if (row.dir === 'ctl') {
+                    const control = row.json ?? {};
+                    if ('kill' in control) {
+                        if (!terminated) {
+                            blocked = true;
+                            flushIdle();
+                            return;
+                        }
+                        index += 1;
+                        continue;
+                    }
+                    if ('closeStdin' in control) {
+                        if (inputOpen) {
+                            blocked = true;
+                            flushIdle();
+                            return;
+                        }
+                        index += 1;
+                        continue;
+                    }
+                    if ('end' in control) {
+                        const match = /exit code=(\S+) sig=(\S+)/.exec(String(control.end));
+                        const code = match && match[1] !== 'null' ? Number(match[1]) : null;
+                        const signal = match && match[2] !== 'null' ? match[2] : null;
+                        // A harness timeout means the real process was still alive: stay resident.
+                        if (terminated || exitAtEnd || (signal !== 'SIGKILL' && signal !== 'SIGTERM')) {
+                            finish({ exitCode: code, signal });
+                            return;
+                        }
+                        index += 1;
+                        continue;
+                    }
+                    index += 1;
+                    continue;
+                }
+                index += 1;
+                if (row.json)
+                    handlers.onLine(JSON.stringify(remap(row.json)));
+                else if (row.raw)
+                    handlers.onLine(row.raw);
+                setImmediate(step);
+                return;
+            }
+            if (terminated || exitAtEnd)
+                finish({ exitCode: terminated ? null : 0, signal: terminated ? 'SIGTERM' : null });
+            else {
+                blocked = true;
+                flushIdle();
+            }
+        };
+        const session = {
+            spec,
+            written,
+            get inputEnded() { return !inputOpen; },
+            get terminated() { return terminated; },
+            idle: () => (blocked || exit ? Promise.resolve() : new Promise((resolve) => { idleWaiters.push(resolve); })),
+        };
+        this.sessions.push(session);
+        setImmediate(step);
+        return {
+            pid: 4242,
+            exited,
+            write(line) {
+                if (!inputOpen || exit)
+                    return false;
+                written.push(JSON.parse(line));
+                if (blocked)
+                    setImmediate(step);
+                return true;
+            },
+            endInput() {
+                inputOpen = false;
+                if (blocked)
+                    setImmediate(step);
+            },
+            terminate() {
+                terminated = true;
+                if (blocked)
+                    setImmediate(step);
+                return exited;
+            },
+        };
+    };
+}

package/dist/agent-runtime/session/testing/index.d.ts

@@ -0,0 +1,9 @@
+/**
+ * Test kit for hosts and driver authors (package export `./agent-runtime/session/testing`).
+ * Framework-free: usable from any test runner.
+ */
+export { DRIVER_CONFORMANCE, type ConformanceCheck, type ConformanceHarness } from './driver-conformance.js';
+export { FixtureReplayer, loadFixture, type FixtureRow, type ReplaySession } from './fixture-replayer.js';
+export { MemoryJournal } from './memory-journal.js';
+export { FakeClock, SequentialIds } from './fake-clock.js';
+export { ScriptedDriverFactory, ScriptedDriverSession, catalogOf, descriptor } from './scripted-driver.js';

package/dist/agent-runtime/session/testing/index.js

@@ -0,0 +1,9 @@
+/**
+ * Test kit for hosts and driver authors (package export `./agent-runtime/session/testing`).
+ * Framework-free: usable from any test runner.
+ */
+export { DRIVER_CONFORMANCE } from './driver-conformance.js';
+export { FixtureReplayer, loadFixture } from './fixture-replayer.js';
+export { MemoryJournal } from './memory-journal.js';
+export { FakeClock, SequentialIds } from './fake-clock.js';
+export { ScriptedDriverFactory, ScriptedDriverSession, catalogOf, descriptor } from './scripted-driver.js';

package/dist/agent-runtime/session/testing/memory-journal.d.ts

@@ -0,0 +1,27 @@
+import type { SessionEvent, SessionEventEnvelope } from '../domain/events.js';
+import { type SessionSnapshot } from '../domain/snapshot.js';
+import type { UsageBaseline } from '../domain/usage.js';
+import type { AppendOptions, SessionJournal, SessionRecord, SessionSummary } from '../ports.js';
+/**
+ * In-memory SessionJournal with the same contract as the SQLite adapter:
+ * gap-free sequences, atomic appends, baselines stored with their events.
+ * `failNextAppend` simulates a failed transaction (nothing becomes visible).
+ */
+export declare class MemoryJournal implements SessionJournal {
+    private readonly sessions;
+    private readonly baselines;
+    failNextAppend: Error | null;
+    createSession(record: SessionRecord): void;
+    getSession(sessionId: string): SessionRecord | null;
+    append(sessionId: string, events: SessionEvent[], options?: AppendOptions): SessionEventEnvelope[];
+    read(sessionId: string, afterSeq: number, limit: number): {
+        events: SessionEventEnvelope[];
+        hasMore: boolean;
+    };
+    snapshot(sessionId: string): SessionSnapshot | null;
+    list(filter: 'open' | 'closed' | 'all'): SessionSummary[];
+    baseline(providerRef: string): UsageBaseline | null;
+    /** Test helper: every committed event of a session. */
+    events(sessionId: string): SessionEventEnvelope[];
+    private require;
+}

package/dist/agent-runtime/session/testing/memory-journal.js

@@ -0,0 +1,70 @@
+import { emptySnapshot, foldEvents } from '../domain/snapshot.js';
+/**
+ * In-memory SessionJournal with the same contract as the SQLite adapter:
+ * gap-free sequences, atomic appends, baselines stored with their events.
+ * `failNextAppend` simulates a failed transaction (nothing becomes visible).
+ */
+export class MemoryJournal {
+    sessions = new Map();
+    baselines = new Map();
+    failNextAppend = null;
+    createSession(record) {
+        if (this.sessions.has(record.sessionId))
+            throw new Error(`Session ${record.sessionId} exists`);
+        this.sessions.set(record.sessionId, { record: { ...record }, events: [], snapshot: emptySnapshot(record.sessionId) });
+    }
+    getSession(sessionId) {
+        return this.sessions.get(sessionId)?.record ?? null;
+    }
+    append(sessionId, events, options) {
+        const entry = this.require(sessionId);
+        if (this.failNextAppend) {
+            const error = this.failNextAppend;
+            this.failNextAppend = null;
+            throw error;
+        }
+        const envelopes = events.map((event, index) => ({ sessionId, seq: entry.snapshot.lastSeq + index + 1, event: structuredClone(event) }));
+        const snapshot = foldEvents(entry.snapshot, envelopes);
+        entry.events.push(...envelopes);
+        entry.snapshot = snapshot;
+        if (options?.baseline)
+            this.baselines.set(options.baseline.providerRef, { ...options.baseline.value });
+        return envelopes.map((envelope) => structuredClone(envelope));
+    }
+    read(sessionId, afterSeq, limit) {
+        const all = this.require(sessionId).events.filter((envelope) => envelope.seq > afterSeq);
+        return { events: structuredClone(all.slice(0, limit)), hasMore: all.length > limit };
+    }
+    snapshot(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        return entry ? structuredClone(entry.snapshot) : null;
+    }
+    list(filter) {
+        return [...this.sessions.values()]
+            .filter(({ snapshot }) => filter === 'all' || snapshot.status === filter)
+            .map(({ record, snapshot }) => ({
+            sessionId: record.sessionId,
+            driver: record.driver,
+            model: snapshot.model,
+            status: snapshot.status,
+            phase: snapshot.phase,
+            lastSeq: snapshot.lastSeq,
+            createdAt: record.createdAt,
+            metadata: { ...record.metadata },
+        }));
+    }
+    baseline(providerRef) {
+        const value = this.baselines.get(providerRef);
+        return value ? { ...value } : null;
+    }
+    /** Test helper: every committed event of a session. */
+    events(sessionId) {
+        return structuredClone(this.require(sessionId).events);
+    }
+    require(sessionId) {
+        const entry = this.sessions.get(sessionId);
+        if (!entry)
+            throw new Error(`Unknown session ${sessionId}`);
+        return entry;
+    }
+}

package/dist/agent-runtime/session/testing/scripted-driver.d.ts

@@ -0,0 +1,30 @@
+import type { DriverCapabilities, DriverDescriptor } from '../domain/types.js';
+import type { CloseReason, DriverCatalog, DriverEvent, DriverEventSink, DriverFactory, DriverInput, DriverOpenSpec, DriverSession } from '../ports.js';
+export declare function descriptor(id: string, capabilities?: Partial<DriverCapabilities>): DriverDescriptor;
+/** One opened provider process, driven by the test through `emit`. */
+export declare class ScriptedDriverSession implements DriverSession {
+    readonly spec: DriverOpenSpec;
+    private readonly sink;
+    readonly sent: DriverInput[];
+    readonly calls: string[];
+    closed: CloseReason | null;
+    /** What `stopSubagents` resolves with. */
+    stopResult: string[] | 'process';
+    /** Events emitted while closing (e.g. Claude's stopped/killed notifications on SIGTERM). */
+    onClose: DriverEvent[];
+    constructor(spec: DriverOpenSpec, sink: DriverEventSink);
+    emit(...events: DriverEvent[]): void;
+    send(input: DriverInput): Promise<void>;
+    interrupt(): Promise<void>;
+    stopSubagents(ids?: string[]): Promise<string[] | 'process'>;
+    close(reason: CloseReason): Promise<void>;
+}
+export declare class ScriptedDriverFactory implements DriverFactory {
+    readonly descriptor: DriverDescriptor;
+    readonly sessions: ScriptedDriverSession[];
+    openError: Error | null;
+    constructor(descriptor: DriverDescriptor);
+    open(spec: DriverOpenSpec, sink: DriverEventSink): Promise<DriverSession>;
+    get last(): ScriptedDriverSession;
+}
+export declare function catalogOf(...factories: DriverFactory[]): DriverCatalog;

package/dist/agent-runtime/session/testing/scripted-driver.js

@@ -0,0 +1,77 @@
+export function descriptor(id, capabilities = {}) {
+    return {
+        id,
+        displayName: id,
+        capabilities: {
+            resident: true,
+            nativeInputQueue: true,
+            subagents: 'supported',
+            subagentDisable: true,
+            subagentModel: true,
+            subagentEffort: true,
+            autonomousContinuation: true,
+            steer: true,
+            toolFiltering: true,
+            usage: { costUsd: 'session-cumulative', tokens: 'per-turn' },
+            ...capabilities,
+        },
+    };
+}
+/** One opened provider process, driven by the test through `emit`. */
+export class ScriptedDriverSession {
+    spec;
+    sink;
+    sent = [];
+    calls = [];
+    closed = null;
+    /** What `stopSubagents` resolves with. */
+    stopResult = 'process';
+    /** Events emitted while closing (e.g. Claude's stopped/killed notifications on SIGTERM). */
+    onClose = [];
+    constructor(spec, sink) {
+        this.spec = spec;
+        this.sink = sink;
+    }
+    emit(...events) {
+        if (this.closed)
+            throw new Error('scripted driver: emit after close');
+        for (const event of events)
+            this.sink(event);
+    }
+    async send(input) { this.calls.push(`send:${input.inputId}`); this.sent.push(input); }
+    async interrupt() { this.calls.push('interrupt'); }
+    async stopSubagents(ids) { this.calls.push(`stopSubagents:${ids?.join(',') ?? '*'}`); return this.stopResult; }
+    async close(reason) {
+        if (this.closed)
+            return;
+        this.calls.push(`close:${reason}`);
+        for (const event of this.onClose)
+            this.sink(event);
+        this.closed = reason;
+    }
+}
+export class ScriptedDriverFactory {
+    descriptor;
+    sessions = [];
+    openError = null;
+    constructor(descriptor) {
+        this.descriptor = descriptor;
+    }
+    async open(spec, sink) {
+        if (this.openError)
+            throw this.openError;
+        const session = new ScriptedDriverSession(spec, sink);
+        this.sessions.push(session);
+        return session;
+    }
+    get last() {
+        const session = this.sessions.at(-1);
+        if (!session)
+            throw new Error('scripted driver: no session opened');
+        return session;
+    }
+}
+export function catalogOf(...factories) {
+    const map = new Map(factories.map((factory) => [factory.descriptor.id, factory]));
+    return { get: (id) => map.get(id), descriptors: () => factories.map((factory) => factory.descriptor) };
+}

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

@@ -0,0 +1,9 @@
+import type { PipelineContext, VerificationCommand } from '../pipeline/pipeline-state.js';
+/** The package script a command runs (`npm test`, `npm run x`, `pnpm [run] x`, `yarn [run] x`), when it runs exactly one with no extra arguments. */
+export declare function packageScriptOf(command: Pick<VerificationCommand, 'command' | 'args'>): string | undefined;
+/**
+ * The proposals to append to `planned` (already scope-defaulted). `normalize`
+ * applies the caller's scope default; proposals are expected to be
+ * structurally valid.
+ */
+export declare function admitVerificationProposals(context: PipelineContext, planned: readonly VerificationCommand[], proposals: readonly VerificationCommand[], normalize: (command: VerificationCommand) => VerificationCommand): VerificationCommand[];

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

@@ -0,0 +1,69 @@
+// Which agent-proposed verification commands the host adds to its plan.
+//
+// A repository without configured checks takes the proposals as its checks
+// (validated like any configured command). A repository with configured
+// checks keeps them and may gain only runs of a package script the
+// repository itself declares, such as `npm run test:e2e`: a change whose
+// acceptance needs browser or integration tests then gets host evidence for
+// them, without the agent introducing arbitrary commands next to the
+// configured ones.
+import { existsSync, readFileSync } from 'node:fs';
+import path from 'node:path';
+/** The package script a command runs (`npm test`, `npm run x`, `pnpm [run] x`, `yarn [run] x`), when it runs exactly one with no extra arguments. */
+export function packageScriptOf(command) {
+    const [first, second, ...rest] = command.args;
+    if (command.command === 'npm') {
+        if (first === 'test' && second === undefined)
+            return 'test';
+        if ((first === 'run' || first === 'run-script') && second && !rest.length)
+            return second;
+        return undefined;
+    }
+    if (command.command === 'pnpm' || command.command === 'yarn') {
+        if (first === 'run' && second && !rest.length)
+            return second;
+        if (first && second === undefined && !first.startsWith('-'))
+            return first;
+    }
+    return undefined;
+}
+function declaresScript(directory, script) {
+    const file = path.join(directory, 'package.json');
+    if (!existsSync(file))
+        return false;
+    try {
+        const scripts = JSON.parse(readFileSync(file, 'utf8')).scripts;
+        return !!scripts && typeof scripts[script] === 'string';
+    }
+    catch {
+        return false;
+    }
+}
+const planKey = (command) => JSON.stringify([command.repositoryId, command.cwd ?? '', command.command, command.args]);
+/**
+ * The proposals to append to `planned` (already scope-defaulted). `normalize`
+ * applies the caller's scope default; proposals are expected to be
+ * structurally valid.
+ */
+export function admitVerificationProposals(context, planned, proposals, normalize) {
+    const configured = new Set(planned.map(command => command.repositoryId));
+    const seen = new Set(planned.map(planKey));
+    const admitted = [];
+    for (const raw of proposals) {
+        const repository = context.repositories.find(repo => repo.id === raw.repositoryId);
+        if (!repository)
+            continue;
+        const command = normalize(raw);
+        if (configured.has(raw.repositoryId)) {
+            const script = packageScriptOf(command);
+            if (!script || !declaresScript(path.resolve(repository.path, command.cwd ?? '.'), script))
+                continue;
+        }
+        const key = planKey(command);
+        if (seen.has(key))
+            continue;
+        seen.add(key);
+        admitted.push(command);
+    }
+    return admitted;
+}

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

@@ -1,16 +1,45 @@
 import type { spawnSync } from 'node:child_process';
-import type { CommandReceipt, PipelineContext, VerificationReceipt } from '../pipeline/pipeline-state.js';
-import { type InstallOutcome } from './compact/environment.js';
+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 { HostBlocker } from './engine/contracts.js';
 import { type GuardrailSettings } from './guardrails.js';
 export type { HostBlocker } from './engine/contracts.js';
 export declare function installRoots(context: PipelineContext, commands: readonly CommandReceipt[]): string[];
+/**
+ * Installed dependencies out of their declared ranges in any package root that
+ * contains a failing command's cwd (from the cwd up to its repository). The
+ * failure such drift causes is arbitrary (a lint error on an untouched file),
+ * so the drift itself, not the output, marks the failure as environmental.
+ */
+export declare function driftedFailureRoots(context: PipelineContext, receipt: VerificationReceipt): Array<{
+    root: string;
+    drift: DriftedDependency[];
+}>;
+/** Why a failed receipt is the host's environment to repair: a missing tool or dependency in the output, or installed versions out of their declared ranges. */
+export declare function environmentFailure(context: PipelineContext, receipt: VerificationReceipt): {
+    drift: Array<{
+        root: string;
+        drift: DriftedDependency[];
+    }>;
+} | undefined;
 /** A directory as the log should name it: relative to the checkout that contains it. */
 export declare function checkoutRelative(context: PipelineContext, directory: string): string;
 /** The legacy host-facing sentence for a blocker; engine v2 hosts read the structured blocker instead. */
 export declare function hostPreconditionMessage(reason: string, command: string, args: readonly string[], directory: string): string;
 /** A failed check the host must unblock (credentials, registry access, a missing variable): no correction round can repair it. */
 export declare function preconditionBlock(context: PipelineContext, receipt: VerificationReceipt): HostBlocker | undefined;
+/** Error code of a verification whose commands keep rewriting the candidate: the repository's or operator's to fix, never the fixer's. */
+export declare const NONDETERMINISTIC_OUTPUT_CODE = "verification_nondeterministic_output";
+/**
+ * Every command exited 0 and ran to completion, and the receipt is invalid only
+ * because the commands modified the candidate themselves: deterministic tool
+ * output (a regenerated mapping) the host may adopt, never a code failure.
+ */
+export declare function selfMutationOnly(receipt: VerificationReceipt): boolean;
+/** The typed blocker for output that did not converge on the adoption re-run, or that the `verification-output-adoption` guardrail keeps out of the candidate. */
+export declare function nondeterministicOutputBlocker(context: PipelineContext, receipt: VerificationReceipt, adoption: boolean): HostBlocker;
+/** The progress line naming the files the host adopted into the candidate. */
+export declare function adoptedOutputNote(mutation: VerificationSelfMutation): string;
 export interface EnvironmentRepair {
     installs: InstallOutcome[];
     refused?: HostBlocker;

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

@@ -1,8 +1,9 @@
 import { existsSync } from 'node:fs';
 import path from 'node:path';
-import { hostPrecondition, installEnvironment } from './compact/environment.js';
+import { describeModifiedFiles } from '../pipeline/pipeline-state.js';
+import { driftedNodeDependencies, hostPrecondition, installEnvironment, isEnvironmentFailure } from './compact/environment.js';
 import { guardrailEnabled } from './guardrails.js';
-const BLOCKER_KINDS = new Set(['network', 'credential', 'environment-variable', 'toolchain', 'setup', 'environment', 'scope']);
+const BLOCKER_KINDS = new Set(['network', 'credential', 'environment-variable', 'toolchain', 'setup', 'environment', 'scope', 'nondeterministic-output']);
 const BLOCKER_TEXT_LIMIT = 2_000;
 /** Where a missing dependency install belongs: the nearest directory with a lockfile or manifest above the failing command, else the repository root. */
 const INSTALL_MARKERS = ['package-lock.json', 'npm-shrinkwrap.json', 'yarn.lock', 'pnpm-lock.yaml', 'bun.lock', 'bun.lockb', 'requirements.txt', 'pyproject.toml', 'go.mod', 'Cargo.toml'];
@@ -31,6 +32,35 @@ export function installRoots(context, commands) {
     // Every repository root stays a candidate: its plan is a no-op when it is already installed.
     return [...new Set([...roots, ...context.repositories.map(repository => repository.path)])];
 }
+/**
+ * Installed dependencies out of their declared ranges in any package root that
+ * contains a failing command's cwd (from the cwd up to its repository). The
+ * failure such drift causes is arbitrary (a lint error on an untouched file),
+ * so the drift itself, not the output, marks the failure as environmental.
+ */
+export function driftedFailureRoots(context, receipt) {
+    const roots = new Set();
+    for (const command of receipt.commands) {
+        const repository = command.exitCode === 0 ? undefined : context.repositories.find(repo => repo.id === command.repositoryId);
+        if (!repository)
+            continue;
+        for (let directory = command.cwd || repository.path;; directory = path.dirname(directory)) {
+            const relative = path.relative(repository.path, directory);
+            if (relative.startsWith('..') || path.isAbsolute(relative))
+                break;
+            if (existsSync(path.join(directory, 'package.json')))
+                roots.add(directory);
+            if (!relative)
+                break;
+        }
+    }
+    return [...roots].map(root => ({ root, drift: driftedNodeDependencies(root) })).filter(item => item.drift.length > 0);
+}
+/** Why a failed receipt is the host's environment to repair: a missing tool or dependency in the output, or installed versions out of their declared ranges. */
+export function environmentFailure(context, receipt) {
+    const drift = driftedFailureRoots(context, receipt);
+    return drift.length || receipt.commands.some(command => isEnvironmentFailure(command.exitCode, command.output)) ? { drift } : undefined;
+}
 /** A directory as the log should name it: relative to the checkout that contains it. */
 export function checkoutRelative(context, directory) {
     const repository = context.repositories.find(repo => { const relative = path.relative(repo.path, directory); return !relative.startsWith('..') && !path.isAbsolute(relative); });
@@ -52,6 +82,30 @@ export function preconditionBlock(context, receipt) {
     }
     return undefined;
 }
+/** Error code of a verification whose commands keep rewriting the candidate: the repository's or operator's to fix, never the fixer's. */
+export const NONDETERMINISTIC_OUTPUT_CODE = 'verification_nondeterministic_output';
+/**
+ * Every command exited 0 and ran to completion, and the receipt is invalid only
+ * because the commands modified the candidate themselves: deterministic tool
+ * output (a regenerated mapping) the host may adopt, never a code failure.
+ */
+export function selfMutationOnly(receipt) {
+    return !receipt.valid && !!receipt.selfMutation?.files.length && receipt.commands.length > 0 && !receipt.notRunEvidenceIds?.length
+        && receipt.commands.every(command => command.exitCode === 0 && (command.outcome === undefined || command.outcome === 'passed'));
+}
+/** The typed blocker for output that did not converge on the adoption re-run, or that the `verification-output-adoption` guardrail keeps out of the candidate. */
+export function nondeterministicOutputBlocker(context, receipt, adoption) {
+    const mutation = receipt.selfMutation ?? { files: [], commands: [] };
+    const command = receipt.commands.find(item => item.repositoryId === mutation.files[0]?.repositoryId && item.disposition !== 'reused') ?? receipt.commands[0];
+    return { kind: 'nondeterministic-output', reason: (adoption ? `the verification commands modified ${describeModifiedFiles(mutation)}, and modified them again when the host verified the adopted output once more`
+            : `the verification commands modified ${describeModifiedFiles(mutation)}, and the verification-output-adoption guardrail keeps verification output out of the candidate`).slice(0, BLOCKER_TEXT_LIMIT),
+        command: command?.command.slice(0, 512) ?? '', args: (command?.args ?? []).slice(0, 16).map(arg => arg.slice(0, 256)), cwd: command ? checkoutRelative(context, command.cwd) : '.',
+        requiredAction: 'Commit the generated output on the base branch or make the generator idempotent, then retry the run.' };
+}
+/** The progress line naming the files the host adopted into the candidate. */
+export function adoptedOutputNote(mutation) {
+    return `[verification] adopted ${mutation.files.length + (mutation.omittedFiles ?? 0)} generated file(s): ${describeModifiedFiles(mutation).replace(/^\d+ candidate files?: /, '')}`;
+}
 /**
  * Runs the planned installs for the failed commands' roots once, narrating each
  * step through `note` exactly as the legacy graph logs it (`[environment] npm
@@ -60,7 +114,8 @@ export function preconditionBlock(context, receipt) {
  */
 export function repairEnvironment(context, receipt, guardrails, note, spawn) {
     const failed = receipt.commands.filter(command => command.exitCode !== 0);
-    const installs = installEnvironment(installRoots(context, failed), { failureOutput: receipt.commands.map(command => command.output).join('\n'), lockfileRepair: guardrailEnabled(guardrails, 'lockfile-repair'),
+    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'),
         ...(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)