agent-device-lab 0.0.0-stage → 0.3.0

package/dist/core/project-runner.js

@@ -0,0 +1,359 @@
+import { spawn } from 'node:child_process';
+import { createWriteStream } from 'node:fs';
+import { connect } from 'node:net';
+import { redactSecrets } from './feed.js';
+import { identify } from './process-identity.js';
+import { describeMemberStop, mergeMembers, snapshotMembers, stopGroup } from './process-group.js';
+import { LabError } from './schema.js';
+/** One readiness probe: GET url+path, following redirects. */
+export async function probe(spec, timeoutMs = 2000) {
+    try {
+        const res = await fetch(spec.url + spec.readiness.path, { signal: AbortSignal.timeout(timeoutMs) });
+        await res.body?.cancel();
+        return res.status === spec.readiness.status ? { kind: 'healthy', status: res.status } : { kind: 'unhealthy', status: res.status };
+    }
+    catch (err) {
+        const cause = err.cause;
+        return { kind: 'down', reason: cause?.code ?? err.name };
+    }
+}
+/** Does host:port accept a TCP connection? */
+export function probeTcp(host, port, timeoutMs = 1000) {
+    return new Promise((resolve) => {
+        const socket = connect({ host, port });
+        const done = (r) => { socket.destroy(); resolve(r); };
+        socket.setTimeout(timeoutMs, () => done({ kind: 'down', reason: 'ETIMEDOUT' }));
+        socket.once('connect', () => done({ kind: 'healthy', status: 0 }));
+        socket.once('error', (err) => done({ kind: 'down', reason: err.code ?? err.name }));
+    });
+}
+/** Probe an http or tcp readiness check; other kinds cannot detect an instance that is already running. */
+export function probeReadiness(r, timeoutMs = 2000) {
+    if (r.kind === 'http')
+        return probe({ url: r.url, readiness: { path: r.path, status: r.status, timeoutMs: r.timeoutMs, intervalMs: r.intervalMs } }, timeoutMs);
+    if (r.kind === 'tcp')
+        return probeTcp(r.host, r.port, Math.min(timeoutMs, 1000));
+    return undefined;
+}
+export function describeReadiness(r) {
+    switch (r.kind) {
+        case 'http': return `GET ${r.url}${r.path} ${r.status}`;
+        case 'tcp': return `tcp ${r.host}:${r.port}`;
+        case 'log': return `log /${r.pattern}/`;
+        case 'alive': return `alive ${r.ms}ms`;
+        case 'exit': return 'exit 0';
+    }
+}
+/** Each service's output file stops growing at this size (env AGENTLAB_SERVICE_LOG_MAX_BYTES). */
+export const SERVICE_LOG_MAX_BYTES = 20 * 1024 * 1024;
+export function serviceLogMax(env = process.env) {
+    const n = Number(env.AGENTLAB_SERVICE_LOG_MAX_BYTES);
+    return Number.isInteger(n) && n > 0 ? n : SERVICE_LOG_MAX_BYTES;
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+/**
+ * A declared service the lab is responsible for. Only instances with `owned === true` are ever
+ * stopped; a reused service is never signalled, and a stop command runs only for a one-shot service
+ * the lab itself started.
+ */
+export class Service {
+    spec;
+    info;
+    child;
+    log;
+    exited;
+    stopping = false;
+    /** Identity of the process-group leader, captured at spawn; used for crash recovery. */
+    identity;
+    /**
+     * Identities of the other processes in the leader's group, snapshotted while the leader was alive. If the
+     * leader (the shell wrapper) dies first, these are what stop() may still signal, one by one.
+     */
+    groupMembers = [];
+    constructor(spec, info, child, log) {
+        this.spec = spec;
+        this.info = info;
+        this.child = child;
+        this.log = log;
+        this.identity = spec.mode === 'process' ? identify(child?.pid) : undefined;
+        this.exited = child
+            ? new Promise((resolve) => (child.exitCode !== null || child.signalCode !== null ? resolve() : child.once('exit', () => resolve())))
+            : Promise.resolve();
+    }
+    /** Reuse a service that already passes its http/tcp readiness check, or run its command and wait for readiness. */
+    static async ensure(spec, opts = {}) {
+        const t0 = Date.now();
+        const at = spec.url ?? describeReadiness(spec.readiness);
+        const existing = await probeReadiness(spec.readiness);
+        if (existing?.kind === 'healthy') {
+            if (!spec.reuseExisting) {
+                throw new LabError('port_conflict', `${label(spec)}: something is already ready at ${at} and reuseExisting is false`, {
+                    hint: 'Stop that process yourself, or set "reuseExisting": true.', details: { service: spec.name },
+                });
+            }
+            return new Service(spec, {
+                name: spec.name, ...(spec.url ? { url: spec.url } : {}), mode: spec.mode, status: 'reused', owned: false,
+                command: spec.command, readyMs: Date.now() - t0, readiness: describeReadiness(spec.readiness),
+            });
+        }
+        if (existing?.kind === 'unhealthy' && spec.readiness.kind === 'http') {
+            throw new LabError('port_conflict', `${label(spec)}: something is already answering at ${spec.readiness.url} but ${spec.readiness.path} returned ${existing.status} (expected ${spec.readiness.status})`, { hint: 'The lab will not start a second server on an occupied port or stop a process it did not start. Stop it or fix the readiness check.', details: { service: spec.name } });
+        }
+        return Service.start(spec, opts, t0);
+    }
+    static async start(spec, opts, t0) {
+        const log = opts.logFile ? createWriteStream(opts.logFile, { flags: 'a' }) : undefined;
+        const tail = [];
+        let logMatched = false;
+        const pattern = spec.readiness.kind === 'log' ? new RegExp(spec.readiness.pattern) : undefined;
+        const maxBytes = serviceLogMax();
+        let written = 0;
+        // The file is capped; readiness matching and the tail below keep seeing every line.
+        const write = (chunk) => {
+            if (!log || log.writableEnded || written > maxBytes)
+                return;
+            const room = maxBytes - written;
+            if (chunk.length <= room) {
+                written += chunk.length;
+                log.write(chunk);
+                return;
+            }
+            log.write(chunk.subarray(0, room));
+            log.write(`\n… output truncated at ${maxBytes} bytes; later output discarded\n`);
+            written = maxBytes + 1;
+        };
+        const record = (stream) => (chunk) => {
+            write(chunk);
+            for (const line of chunk.toString().split(/\r?\n/)) {
+                if (!line.trim())
+                    continue;
+                tail.push(`${stream}: ${line}`);
+                if (tail.length > 40)
+                    tail.shift();
+                if (pattern?.test(line))
+                    logMatched = true;
+                opts.onLog?.(line);
+            }
+        };
+        // detached → own process group, so stop() can signal the command and its children (npm → node).
+        const child = spawn(spec.command, {
+            cwd: spec.cwd,
+            env: { ...process.env, ...spec.env },
+            shell: true,
+            detached: true,
+            stdio: ['ignore', 'pipe', 'pipe'],
+        });
+        child.stdout?.on('data', record('out'));
+        child.stderr?.on('data', record('err'));
+        let spawnError;
+        child.once('error', (err) => { spawnError = err; });
+        const service = new Service(spec, {
+            name: spec.name, ...(spec.url ? { url: spec.url } : {}), mode: spec.mode, status: 'started', owned: true,
+            ...(spec.mode === 'process' ? { pid: child.pid } : {}), command: spec.command, readyMs: 0,
+            readiness: describeReadiness(spec.readiness), ...(opts.logFile ? { logFile: opts.logFile } : {}),
+        }, child, log);
+        const exited = () => !!spawnError || child.exitCode !== null || child.signalCode !== null;
+        const details = (extra = {}) => ({ service: spec.name, command: spec.command, cwd: spec.cwd, logTail: tail.slice(-15), logFile: opts.logFile, ...extra });
+        const failExit = async () => {
+            await sleep(50); // let trailing output arrive
+            log?.end();
+            throw new LabError('startup_failed', `${label(spec)}: command exited before becoming ready (${spawnError?.message ?? `exit code ${child.exitCode ?? child.signalCode}`})`, { hint: startupHint(tail, child.exitCode), details: details({ exitCode: child.exitCode }) });
+        };
+        const aborted = async () => {
+            await service.stop();
+            throw new LabError('startup_failed', `${label(spec)}: start abandoned because another service failed; the started process was stopped`, {
+                details: details({ aborted: true }),
+            });
+        };
+        const r = spec.readiness;
+        const timeoutMs = r.kind === 'alive' ? r.ms + 60_000 : r.timeoutMs;
+        const deadline = t0 + timeoutMs;
+        if (spec.mode === 'oneshot') {
+            // The command itself must finish successfully (e.g. `docker compose up -d`), then readiness is polled.
+            while (!exited()) {
+                if (opts.signal?.aborted)
+                    return aborted();
+                if (Date.now() > deadline) {
+                    await service.kill();
+                    throw new LabError('readiness_timeout', `${label(spec)}: one-shot command did not finish within ${timeoutMs}ms; it was stopped`, {
+                        hint: startupHint(tail), details: details(),
+                    });
+                }
+                await sleep(50);
+            }
+            await sleep(20);
+            if (spawnError || child.exitCode !== 0)
+                return failExit();
+        }
+        let last = 'not probed';
+        while (Date.now() < deadline) {
+            if (opts.signal?.aborted)
+                return aborted();
+            if (spec.mode === 'process' && exited())
+                return failExit();
+            let ready = false;
+            if (r.kind === 'log')
+                ready = logMatched;
+            else if (r.kind === 'exit')
+                ready = true;
+            else if (r.kind === 'alive')
+                ready = Date.now() - t0 >= r.ms;
+            else {
+                const p = (await probeReadiness(r, Math.min(2000, r.intervalMs * 4)));
+                ready = p.kind === 'healthy';
+                last = p.kind === 'down' ? p.reason : `HTTP ${p.status}`;
+            }
+            if (ready) {
+                service.info.readyMs = Date.now() - t0;
+                if (spec.mode === 'process') {
+                    service.refreshMembers();
+                    service.watchExit(opts.onUnexpectedExit, tail);
+                }
+                return service;
+            }
+            await sleep(r.kind === 'http' || r.kind === 'tcp' ? r.intervalMs : 50);
+        }
+        const stop = await service.stop();
+        const what = r.kind === 'http' ? `${r.url}${r.path}` : describeReadiness(r);
+        throw new LabError('readiness_timeout', `${label(spec)}: ${what} was not ready within ${timeoutMs}ms${r.kind === 'http' || r.kind === 'tcp' ? ` (last probe: ${last})` : ''}; the started process was ${stop.stopped ? 'stopped' : `not stopped (${stop.reason})`}`, { hint: startupHint(tail), details: details() });
+    }
+    /** Report an exit that the lab did not cause (see stop and kill). */
+    watchExit(cb, tail) {
+        const child = this.child;
+        if (!cb || !child)
+            return;
+        const report = () => {
+            if (this.stopping)
+                return;
+            // Let trailing output arrive before the tail is read.
+            setTimeout(() => cb({ name: this.spec.name, code: child.exitCode, signal: child.signalCode, logTail: tail.slice(-10).map(redactSecrets) }), 50);
+        };
+        if (child.exitCode !== null || child.signalCode !== null)
+            report();
+        else
+            child.once('exit', report);
+    }
+    /** Snapshot the group's current members; possible only while the leader is alive and verifiably ours. */
+    refreshMembers() {
+        if (this.spec.mode !== 'process' || !this.info.owned)
+            return;
+        const snapshot = snapshotMembers(this.identity);
+        if (snapshot)
+            this.groupMembers = mergeMembers(this.groupMembers, snapshot);
+    }
+    /** The recorded group members (not the leader), for ownership records. */
+    get members() {
+        return this.groupMembers;
+    }
+    get running() {
+        return !!this.child && this.child.exitCode === null && this.child.signalCode === null;
+    }
+    /** Stop the service if and only if the lab started it: signal its process group, or run a one-shot's stop command. */
+    async stop() {
+        if (!this.info.owned || !this.child?.pid)
+            return { stopped: false, reason: 'not owned by the lab; left running' };
+        this.stopping = true;
+        if (this.spec.mode === 'oneshot') {
+            if (this.running)
+                await this.kill();
+            this.log?.end();
+            if (!this.spec.shutdown.command)
+                return { stopped: false, reason: 'one-shot command finished; no shutdown.command declared' };
+            return runStopCommand(this.spec);
+        }
+        const { signal: sig, graceMs } = this.spec.shutdown;
+        if (this.running)
+            this.refreshMembers();
+        // The shell (e.g. dash) may stay as the service's parent and exit first, so the service has
+        // stopped only when its whole process group is empty. If the leader is already gone, only the
+        // members recorded while it lived are signalled, each after an identity check.
+        const r = await stopGroup(this.identity, this.groupMembers, { signal: sig, graceMs, ...(this.running ? { liveLeaderPid: this.child.pid } : {}) });
+        await this.exited;
+        this.log?.end();
+        if (r.via === 'group')
+            return { stopped: true, reason: r.graceful ? sig : `SIGKILL after ${graceMs}ms grace period` };
+        const detail = describeMemberStop(r, graceMs);
+        if (!detail)
+            return { stopped: true, reason: 'already exited' };
+        return { stopped: r.survivors.length === 0 && r.unverified.length === 0, reason: `already exited; ${detail}` };
+    }
+    /** Immediately end a command the lab started (a one-shot that overran). */
+    async kill() {
+        if (!this.child?.pid || !this.running)
+            return;
+        this.stopping = true;
+        try {
+            process.kill(-this.child.pid, 'SIGKILL');
+        }
+        catch { /* gone */ }
+        await this.exited;
+    }
+}
+/** Run a one-shot service's declared stop command (e.g. `docker compose stop cache`). */
+function runStopCommand(spec) {
+    return new Promise((resolve) => {
+        const child = spawn(spec.shutdown.command, { cwd: spec.cwd, env: { ...process.env, ...spec.env }, shell: true, stdio: 'ignore', detached: true });
+        const timer = setTimeout(() => { try {
+            process.kill(-child.pid, 'SIGKILL');
+        }
+        catch { /* gone */ } }, Math.max(spec.shutdown.graceMs, 30_000));
+        child.once('error', (err) => { clearTimeout(timer); resolve({ stopped: false, reason: `stop command failed: ${err.message}` }); });
+        child.once('exit', (code, sig) => {
+            clearTimeout(timer);
+            resolve(code === 0 ? { stopped: true, reason: `ran ${spec.shutdown.command}` } : { stopped: false, reason: `stop command exited ${code ?? sig}` });
+        });
+    });
+}
+/** The single web server of a schemaVersion 1 profile: a Service named "web" with an http readiness check. */
+export class WebServer {
+    service;
+    constructor(service) {
+        this.service = service;
+    }
+    static async ensure(spec, opts = {}) {
+        return new WebServer(await Service.ensure(webService(spec), opts));
+    }
+    get info() {
+        return serverInfo(this.service.info);
+    }
+    get identity() {
+        return this.service.identity;
+    }
+    get running() {
+        return this.service.running;
+    }
+    stop() {
+        return this.service.stop();
+    }
+}
+export function webService(spec) {
+    return {
+        name: 'web', command: spec.command, cwd: spec.cwd, url: spec.url, env: spec.env, requiredEnv: [],
+        readiness: { kind: 'http', url: spec.url, ...spec.readiness }, dependsOn: [], reuseExisting: spec.reuseExisting,
+        required: true, mode: 'process', shutdown: { signal: 'SIGTERM', graceMs: 5000 },
+    };
+}
+/** The single-server view (start and status results) of a service. */
+export function serverInfo(s) {
+    return {
+        url: s.url ?? '', owned: s.owned, reused: s.status === 'reused',
+        ...(s.pid !== undefined ? { pid: s.pid } : {}), ...(s.owned ? { command: s.command } : {}),
+        readyMs: s.readyMs, ...(s.logFile ? { logFile: s.logFile } : {}),
+    };
+}
+function label(spec) {
+    return `service "${spec.name}"`;
+}
+function startupHint(tail, exitCode) {
+    const text = tail.join('\n');
+    if (exitCode === 127 || /: not found$/m.test(text))
+        return 'The command was not found; install project dependencies or fix the service command.';
+    if (/EADDRINUSE|address already in use/i.test(text))
+        return 'The port is already in use by another process.';
+    if (/command not found|ENOENT|Cannot find module/i.test(text))
+        return 'A command or module is missing; install project dependencies first.';
+    if (/Cannot connect to the Docker daemon|docker daemon/i.test(text))
+        return 'Docker is not running; start it and try again.';
+    return 'See the log tail and log file for the service output.';
+}
+//# sourceMappingURL=project-runner.js.map

package/dist/core/replay.js

@@ -0,0 +1,303 @@
+import { readFileSync } from 'node:fs';
+import { routePath } from './action-log.js';
+import { loadBundle, sha256 } from './bundle.js';
+import { Lab } from './lab.js';
+import { loadProfile } from './profile.js';
+import { LabError, SCHEMA_VERSION, } from './schema.js';
+// Replay: re-run the agent actions of a failure bundle against the live project and say whether the failure
+// happens again. Security: nothing that runs comes from the bundle. Commands, environment and paths always
+// come from the agentlab.json in --project (its hash is compared and a difference is only a warning); the
+// bundle supplies role/name targets and typed values, which go through the same `act()` (and so the same
+// uploads.allow check) an agent's would. A replay never continues past a divergence: it stops there and reports.
+const ACTIONS = [
+    'click', 'fill', 'press', 'select', 'check', 'uncheck', 'scroll', 'swipe', 'back', 'forward', 'hover', 'upload', 'drag', 'open_tab', 'switch_tab', 'close_tab',
+];
+const NEEDS_TARGET = ['click', 'fill', 'select', 'check', 'uncheck', 'hover', 'upload', 'drag'];
+const DIRECTIONS = ['up', 'down', 'left', 'right'];
+const ENV_NAME = /^[A-Za-z_][A-Za-z0-9_]*$/;
+/** 0 reproduced, 1 not reproduced, 3 diverged or blocked (2, could not run, is an error thrown before a result exists). */
+export function replayExitCode(r) {
+    return r.outcome === 'reproduced' ? 0 : r.outcome === 'not-reproduced' ? 1 : 3;
+}
+const isRec = (v) => typeof v === 'object' && v !== null && !Array.isArray(v);
+/** The bundle is untrusted input: check every field the replay uses before it drives a browser. */
+function checkActions(raw) {
+    const bad = (i, why) => { throw new LabError('bundle_invalid', `Not a usable failure bundle: action ${i + 1} ${why}`); };
+    const optStr = (v) => v === undefined || typeof v === 'string';
+    const target = (v, i, what) => {
+        if (v === undefined)
+            return;
+        if (!isRec(v) || typeof v.role !== 'string' || typeof v.name !== 'string' || !optStr(v.context))
+            bad(i, `has a malformed ${what}`);
+    };
+    raw.forEach((a, i) => {
+        if (!isRec(a) || !Number.isInteger(a.index) || a.index < 1 || typeof a.at !== 'string')
+            return bad(i, 'is malformed');
+        if (a.actor === 'person') {
+            if (typeof a.description !== 'string')
+                bad(i, 'has no description');
+            return;
+        }
+        if (a.actor !== 'agent' || !ACTIONS.includes(a.action))
+            return bad(i, 'has an unknown actor or action');
+        target(a.target, i, 'target');
+        target(a.toTarget, i, 'toTarget');
+        const args = a.args;
+        if (!isRec(args))
+            return bad(i, 'has no args');
+        for (const k of ['value', 'key', 'tab', 'path'])
+            if (!optStr(args[k]))
+                bad(i, `has a non-text ${k}`);
+        for (const k of ['amount', 'dx', 'dy'])
+            if (args[k] !== undefined && (typeof args[k] !== 'number' || !Number.isFinite(args[k])))
+                bad(i, `has a non-numeric ${k}`);
+        for (const k of ['values', 'files'])
+            if (args[k] !== undefined && (!Array.isArray(args[k]) || !args[k].every((x) => typeof x === 'string')))
+                bad(i, `has a malformed ${k}`);
+        if (args.direction !== undefined && !DIRECTIONS.includes(args.direction))
+            bad(i, 'has an unknown direction');
+        for (const k of ['routeBefore', 'routeAfter', 'dialogBefore', 'dialogAfter'])
+            if (!optStr(a[k]))
+                bad(i, `has a malformed ${k}`);
+        if (a.outcome !== 'success' && a.outcome !== 'error')
+            bad(i, 'has no outcome');
+        if (a.error !== undefined && (!isRec(a.error) || typeof a.error.code !== 'string'))
+            bad(i, 'has a malformed error');
+    });
+    return [...raw].sort((a, b) => a.index - b.index);
+}
+function describe(a) {
+    const t = a.target ? ` ${a.target.role} ${JSON.stringify(a.target.name)}${a.target.context ? ` (in ${JSON.stringify(a.target.context)})` : ''}` : '';
+    const args = a.args;
+    switch (a.action) {
+        case 'fill': return `fill${t} ${a.secret ? 'with ‹secret›' : `(${(args.value ?? '').length} chars)`}`;
+        case 'press': return `press ${a.secret ? '‹secret›' : args.key}${t ? ` in${t}` : ''}`;
+        case 'select': return `select ${args.values?.length ?? 0} option(s) in${t}`;
+        case 'scroll':
+        case 'swipe': return `${a.action} ${args.direction ?? 'to'}${t}`;
+        case 'upload': return `upload ${args.files?.length ?? 0} file(s) to${t}`;
+        case 'drag': return `drag${t} ${a.toTarget ? `onto ${a.toTarget.role} ${JSON.stringify(a.toTarget.name)}` : `by (${args.dx ?? 0}, ${args.dy ?? 0})`}`;
+        case 'open_tab': return `open a tab at ${args.path}`;
+        case 'switch_tab':
+        case 'close_tab': return `${a.action} ${args.tab ?? ''}`.trim();
+        default: return `${a.action}${t}`;
+    }
+}
+const matchesTarget = (o, t) => o.controls.filter((c) => c.role === t.role && c.name === t.name);
+/** The ref of the one control matching role, name and (to pick among duplicates) context; otherwise why not. Never guesses. */
+async function resolveTarget(lab, t) {
+    const find = (o) => {
+        let m = matchesTarget(o, t);
+        if (m.length > 1 && t.context !== undefined)
+            m = m.filter((c) => c.context === t.context);
+        return m;
+    };
+    let obs = lab.lastObservation;
+    let m = find(obs);
+    if (!m.length && obs.omitted > 0) {
+        obs = await lab.observe({ limit: 500 });
+        m = find(obs);
+    }
+    const what = `${t.role} ${JSON.stringify(t.name)}${t.context ? ` in ${JSON.stringify(t.context)}` : ''}`;
+    if (m.length === 1)
+        return { ref: m[0].ref };
+    if (m.length > 1)
+        return { problem: `${m.length} controls match ${what}; not guessing` };
+    const sameRole = obs.controls.filter((c) => c.role === t.role).slice(0, 6).map((c) => JSON.stringify(c.name));
+    return { problem: `no ${what}${sameRole.length ? ` (${t.role}s here: ${sameRole.join(', ')})` : ''}` };
+}
+export async function replayBundle(o) {
+    const env = o.env ?? process.env;
+    const bundle = loadBundle(o.bundle);
+    const actions = checkActions(bundle.actions);
+    const failure = bundle.failure;
+    const failStep = failure.kind === 'action-error' ? failure.step : undefined;
+    for (const [step, name] of Object.entries(o.secrets ?? {})) {
+        const a = actions.find((x) => x.index === Number(step));
+        if (!ENV_NAME.test(name))
+            throw new LabError('invalid_request', `--secret ${step}=${name.slice(0, 40)}: "${name.slice(0, 40)}" is not an environment variable name`);
+        if (!a || a.actor !== 'agent' || !a.secret)
+            throw new LabError('invalid_request', `--secret: step ${step} has no masked value`, { hint: 'Steps with a masked value are marked ‹secret› in `agentlab bundles show`.' });
+    }
+    const profile = await loadProfile(o.project ?? process.cwd());
+    const warnings = [];
+    if (sha256(readFileSync(profile.profilePath)) !== bundle.project.profileSha256) {
+        warnings.push('agentlab.json differs from the one the bundle was recorded with; replaying against the current one');
+    }
+    const result = {
+        schemaVersion: SCHEMA_VERSION, outcome: 'blocked', reason: '', warnings, steps: [],
+        bundle: { id: bundle.id, createdAt: bundle.retention?.createdAt ?? '', reason: bundle.reason, failure },
+    };
+    const finish = (outcome, reason) => Object.assign(result, { outcome, reason });
+    const step = (s) => { result.steps.push(s); o.onStep?.(s); };
+    const block = (index, description, reason) => {
+        step({ index, description, status: 'blocked', detail: reason });
+        result.blocked = { step: index, reason };
+        return finish('blocked', `step ${index}: ${reason}`);
+    };
+    if (bundle.actionsOmitted > 0) {
+        return block(1, 'the recorded start', `the bundle's log dropped its first ${bundle.actionsOmitted} action(s), so the session cannot be rebuilt from the start`);
+    }
+    const lab = new Lab({ stateDir: o.stateDir });
+    o.onLab?.(lab);
+    try {
+        const started = await lab.start({
+            project: profile.profilePath, device: bundle.session.device, headed: o.headed === true, auth: bundle.session.auth === 'saved-state' ? 'saved' : 'fresh',
+        });
+        result.session = { id: started.session.id, device: started.session.device.id };
+        const now = () => ({ route: routePath(lab.lastObservation?.route), dialog: lab.lastObservation?.dialog });
+        const last = Math.min(o.until ?? Infinity, failStep ?? Infinity);
+        for (const a of actions) {
+            if (a.index > last)
+                break;
+            if (a.actor === 'person')
+                return block(a.index, `a person: ${a.description}`, `a person's interaction is recorded only as a description ("${a.description}"), so it cannot be replayed`);
+            const description = describe(a);
+            const diverge = (what, expected, actual) => {
+                step({ index: a.index, description, status: 'diverged', detail: `${what}: expected ${expected}, got ${actual}` });
+                result.divergence = { step: a.index, what, expected, actual };
+                return finish('diverged', `step ${a.index}: ${what}: expected ${expected}, got ${actual}`);
+            };
+            const cur = now();
+            if (a.routeBefore !== undefined && cur.route !== a.routeBefore)
+                return diverge('route before the step', a.routeBefore, cur.route ?? 'none');
+            if ((a.dialogBefore ?? null) !== (cur.dialog ?? null))
+                return diverge('dialog before the step', a.dialogBefore ? JSON.stringify(a.dialogBefore) : 'none', cur.dialog ? JSON.stringify(cur.dialog) : 'none');
+            if (NEEDS_TARGET.includes(a.action) && !a.target)
+                return block(a.index, description, 'the recorded action has no role/name target (its ref was not in the last observation), so it cannot be found again');
+            let ref;
+            let toRef;
+            if (a.target) {
+                const r = await resolveTarget(lab, a.target);
+                if ('problem' in r)
+                    return diverge('target', `${a.target.role} ${JSON.stringify(a.target.name)}`, r.problem);
+                ref = r.ref;
+            }
+            if (a.toTarget) {
+                const r = await resolveTarget(lab, a.toTarget);
+                if ('problem' in r)
+                    return diverge('drop target', `${a.toTarget.role} ${JSON.stringify(a.toTarget.name)}`, r.problem);
+                toRef = r.ref;
+            }
+            if (a.consequential && !o.allowConsequential) {
+                return block(a.index, description, `its target's name suggests a consequential action (${JSON.stringify(a.target?.name ?? a.toTarget?.name)}); pass --allow-consequential to run it`);
+            }
+            if (a.truncated)
+                return block(a.index, description, 'the typed value was longer than the log keeps');
+            const typed = {};
+            if (a.secret) {
+                const name = o.secrets?.[a.index];
+                if (!name)
+                    return block(a.index, description, `the recorded value is masked; supply it with --secret ${a.index}=<ENV_NAME>`);
+                const value = env[name];
+                if (!value)
+                    return block(a.index, description, `environment variable ${name} (for --secret ${a.index}) is not set`);
+                if (a.action === 'fill')
+                    typed.value = value;
+                else
+                    typed.key = value;
+            }
+            const args = a.args;
+            const request = {
+                action: a.action, ...(ref ? { ref } : {}), ...(toRef ? { toRef } : {}),
+                ...(args.value !== undefined ? { value: args.value } : {}), ...(args.key !== undefined ? { key: args.key } : {}), ...typed,
+                ...(args.values ? { values: args.values } : {}), ...(args.direction ? { direction: args.direction } : {}),
+                ...(args.amount !== undefined ? { amount: args.amount } : {}), ...(args.dx !== undefined ? { dx: args.dx } : {}), ...(args.dy !== undefined ? { dy: args.dy } : {}),
+                ...(args.files ? { files: args.files } : {}), ...(args.tab !== undefined ? { tab: args.tab } : {}), ...(args.path !== undefined ? { path: args.path } : {}),
+            };
+            const r = await lab.act(request);
+            const after = now();
+            const code = r.error?.code;
+            if (a.index === failStep) {
+                const want = failure.code;
+                if (r.outcome === 'error' && code === want) {
+                    step({ index: a.index, description, status: 'reproduced', detail: `failed with ${code}, as recorded` });
+                    return finish('reproduced', `step ${a.index} failed with ${code} again`);
+                }
+                const got = r.outcome === 'error' ? `failed with ${code}` : 'succeeded';
+                step({ index: a.index, description, status: 'not-reproduced', detail: `expected ${want}, ${got}` });
+                return finish('not-reproduced', `step ${a.index} ${got}; the recording failed with ${want}`);
+            }
+            if (r.outcome !== a.outcome || code !== a.error?.code) {
+                return diverge('outcome', a.outcome === 'error' ? `error ${a.error?.code}` : 'success', r.outcome === 'error' ? `error ${code}` : 'success');
+            }
+            if (a.routeAfter !== undefined && after.route !== a.routeAfter)
+                return diverge('route after the step', a.routeAfter, after.route ?? 'none');
+            if ((a.dialogAfter ?? null) !== (after.dialog ?? null))
+                return diverge('dialog after the step', a.dialogAfter ? JSON.stringify(a.dialogAfter) : 'none', after.dialog ? JSON.stringify(after.dialog) : 'none');
+            step({ index: a.index, description, status: a.outcome === 'error' ? 'error-as-recorded' : 'ok', ...(a.outcome === 'error' ? { detail: `failed with ${code}, as recorded` } : {}) });
+        }
+        // Every step that was asked for has run without divergence.
+        const stoppedEarly = o.until !== undefined && actions.some((a) => a.index > o.until && (failStep === undefined || a.index <= failStep));
+        if (stoppedEarly)
+            return finish('not-reproduced', `stopped after step ${o.until} (--until) before the failure could be checked`);
+        return await verify(lab, bundle, failure, result, finish);
+    }
+    finally {
+        await lab.close('replay finished').catch(() => undefined);
+    }
+}
+/** After the recorded actions: decide from the kind of failure. */
+async function verify(lab, bundle, failure, result, finish) {
+    const scenario = bundle.scenario;
+    switch (failure.kind) {
+        case 'action-error':
+            return finish('blocked', `step ${failure.step} is not in the bundle's action log`);
+        case 'findings': {
+            let found;
+            if (scenario) {
+                try {
+                    found = (await lab.scan({ scenarios: [scenario.name], devices: [scenario.device] })).findings.map((f) => f.fingerprint);
+                }
+                catch (err) {
+                    return finish('blocked', `scenario "${scenario.name}" could not be run: ${LabError.from(err).message}`);
+                }
+            }
+            else
+                found = lab.inspect().findings.map((f) => f.fingerprint);
+            const missing = failure.fingerprints.filter((f) => !found.includes(f));
+            result.findings = { expected: failure.fingerprints, missing };
+            return missing.length
+                ? finish('not-reproduced', `${failure.fingerprints.length - missing.length} of ${failure.fingerprints.length} recorded finding(s) appeared again`)
+                : finish('reproduced', `all ${failure.fingerprints.length} recorded finding(s) appeared again`);
+        }
+        case 'scenario-error': {
+            let run;
+            try {
+                run = (await lab.scan({ scenarios: [failure.scenario], devices: [failure.device] })).runs.find((r) => r.scenario === failure.scenario && r.device === failure.device);
+            }
+            catch (err) {
+                return finish('blocked', `scenario "${failure.scenario}" could not be run: ${LabError.from(err).message}`);
+            }
+            const at = run?.failedAt;
+            const code = run?.error?.code;
+            const same = run?.status === 'failed' && at === failure.failedAt && (failure.code === undefined || code === failure.code);
+            return same
+                ? finish('reproduced', `scenario "${failure.scenario}" on ${failure.device} failed at ${at}${code ? ` with ${code}` : ''} again`)
+                : finish('not-reproduced', `scenario "${failure.scenario}" on ${failure.device}: ${run?.status === 'failed' ? `failed at ${at}${code ? ` with ${code}` : ''}` : 'passed'}; the recording failed at ${failure.failedAt}${failure.code ? ` with ${failure.code}` : ''}`);
+        }
+        case 'expectation':
+        case 'manual': {
+            // The expectation itself is not in the bundle, so the check is that the recorded end state was reached.
+            const end = bundle.observations.at(-1);
+            const cur = { route: routePath(lab.lastObservation?.route), dialog: lab.lastObservation?.dialog };
+            if (!end)
+                return finish('reproduced', 'every recorded step ran; the bundle has no end state to compare');
+            if (cur.route !== end.route || (cur.dialog ?? null) !== (end.dialog ?? null)) {
+                return finish('not-reproduced', `the recorded end state (route ${end.route}${end.dialog ? `, dialog ${JSON.stringify(end.dialog)}` : ''}) was not reached: route ${cur.route}${cur.dialog ? `, dialog ${JSON.stringify(cur.dialog)}` : ''}`);
+            }
+            return finish('reproduced', `every recorded step ran and the recorded end state (route ${end.route}) was reached`);
+        }
+    }
+}
+/** Text mode: one line per step and the outcome. */
+export function formatReplay(r) {
+    const mark = { ok: 'ok', 'error-as-recorded': 'ok (error, as recorded)', reproduced: 'REPRODUCED', 'not-reproduced': 'NOT REPRODUCED', diverged: 'DIVERGED', blocked: 'BLOCKED' };
+    return [
+        `replay of ${r.bundle.id}: ${r.bundle.reason}`,
+        ...r.warnings.map((w) => `warning: ${w}`),
+        ...r.steps.map((s) => `  step ${s.index}  ${mark[s.status].padEnd(8)} ${s.description}${s.detail ? `  (${s.detail})` : ''}`),
+        `${r.outcome}: ${r.reason}`,
+    ].join('\n');
+}
+//# sourceMappingURL=replay.js.map