specrails-core 6.3.0 → 6.5.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

@@ -0,0 +1,26 @@
+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 { 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[];
+/** 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;
+export interface EnvironmentRepair {
+    installs: InstallOutcome[];
+    refused?: HostBlocker;
+}
+/**
+ * Runs the planned installs for the failed commands' roots once, narrating each
+ * step through `note` exactly as the legacy graph logs it (`[environment] npm
+ * 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;
+/** 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

@@ -0,0 +1,88 @@
+import { existsSync } from 'node:fs';
+import path from 'node:path';
+import { hostPrecondition, installEnvironment } from './compact/environment.js';
+import { guardrailEnabled } from './guardrails.js';
+const BLOCKER_KINDS = new Set(['network', 'credential', 'environment-variable', 'toolchain', 'setup', 'environment', 'scope']);
+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'];
+export function installRoots(context, commands) {
+    const roots = [];
+    for (const command of commands) {
+        const repository = context.repositories.find(repo => repo.id === command.repositoryId);
+        if (!repository)
+            continue;
+        let directory = command.cwd;
+        let chosen = repository.path;
+        for (;;) {
+            const relative = path.relative(repository.path, directory);
+            if (relative.startsWith('..') || path.isAbsolute(relative))
+                break;
+            if (INSTALL_MARKERS.some(name => existsSync(path.join(directory, name)))) {
+                chosen = directory;
+                break;
+            }
+            if (!relative)
+                break;
+            directory = path.dirname(directory);
+        }
+        roots.push(chosen);
+    }
+    // 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)])];
+}
+/** 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); });
+    return repository ? path.relative(repository.path, directory).split(path.sep).join('/') || '.' : directory;
+}
+/** The legacy host-facing sentence for a blocker; engine v2 hosts read the structured blocker instead. */
+export function hostPreconditionMessage(reason, command, args, directory) {
+    return `Verification cannot run in this environment: ${reason} (\`${[command, ...args].join(' ')}\` in ${directory}). This is not a defect in the change, so no correction round was started. Make it available to Specrails (for example in the login shell profile Specrails loads, or with a refreshed registry token), then resume.`;
+}
+/** A failed check the host must unblock (credentials, registry access, a missing variable): no correction round can repair it. */
+export function preconditionBlock(context, receipt) {
+    for (const command of receipt.commands) {
+        if (command.exitCode === 0)
+            continue;
+        const precondition = hostPrecondition(command.output);
+        if (precondition)
+            return boundedBlocker({ kind: precondition.kind, reason: precondition.reason, command: command.command, args: command.args, cwd: checkoutRelative(context, command.cwd),
+                requiredAction: precondition.requiredAction, ...(command.evidenceId ? { evidenceId: command.evidenceId } : {}) });
+    }
+    return undefined;
+}
+/**
+ * Runs the planned installs for the failed commands' roots once, narrating each
+ * step through `note` exactly as the legacy graph logs it (`[environment] npm
+ * install (app)`, `Environment: installed …`). An install the host cannot
+ * complete for a precondition reason becomes `refused`.
+ */
+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'),
+        ...(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)
+        return { installs };
+    const precondition = hostPrecondition(refused.detail) ?? { kind: 'environment', reason: refused.precondition, requiredAction: 'Repair the verification environment, then retry the run.' };
+    const cwd = checkoutRelative(context, refused.root);
+    const command = [refused.command, ...refused.args].join(' ');
+    return { installs, refused: boundedBlocker({ kind: precondition.kind, reason: `installing its dependencies failed because ${refused.precondition}`, command: refused.command, args: refused.args, cwd,
+            // A network blocker on an install names the exact command to repeat with connectivity; other kinds keep the classifier's action.
+            requiredAction: precondition.kind === 'network' ? `Run \`${command}\` in ${cwd} with network access, then retry the run.` : precondition.requiredAction }) };
+}
+/** A blocker as a durable JSON value: known kind, bounded strings, at most 16 arguments. */
+export function boundedBlocker(value) {
+    if (!value || typeof value !== 'object' || Array.isArray(value))
+        return undefined;
+    const raw = value;
+    if (typeof raw.kind !== 'string' || !BLOCKER_KINDS.has(raw.kind))
+        return undefined;
+    const bounded = (field, limit = BLOCKER_TEXT_LIMIT) => typeof field === 'string' ? field.slice(0, limit) : '';
+    const args = Array.isArray(raw.args) ? raw.args.slice(0, 16).map(arg => bounded(arg, 256)) : [];
+    // A correction role reports free-text `evidence` instead of a host reason.
+    const reason = bounded(raw.reason) || bounded(raw.evidence);
+    return { kind: raw.kind, reason, command: bounded(raw.command, 512), args, cwd: bounded(raw.cwd, 512), requiredAction: bounded(raw.requiredAction),
+        ...(typeof raw.evidenceId === 'string' && raw.evidenceId ? { evidenceId: bounded(raw.evidenceId, 128) } : {}) };
+}

package/dist/installer/util/registry.js

@@ -17,8 +17,8 @@
  * Everything in this module is synchronous to fit the installer's sync flow.
  */
 import { closeSync, existsSync, fsyncSync, lstatSync, mkdirSync, openSync, readFileSync, realpathSync, renameSync, statSync, unlinkSync, writeFileSync, } from 'node:fs';
-import os from 'node:os';
 import path from 'node:path';
+import { userHome } from '../../shared/specrails-home.js';
 /** Registry schema version. A reader that sees a higher value MUST treat all
  *  entries as absent (legacy fallback), never mis-parse. */
 export const REGISTRY_SCHEMA_VERSION = 1;
@@ -190,9 +190,9 @@ function isValidProjectEntry(key, value, home) {
 export function slugify(name) {
     return name.toLowerCase().replace(/[^a-z0-9]+/g, '-').replace(/^-|-$/g, '');
 }
-/** `$HOME` for the registry, overridable for tests. */
+/** `$HOME` for the registry, overridable for tests (shared with session journals). */
 function resolveHome(home) {
-    return home ?? process.env.SPECRAILS_REGISTRY_HOME ?? os.homedir();
+    return userHome(home);
 }
 /** Absolute path to `registry.json`. */
 export function registryPath(home) {