@pasko70/pibo 1.0.5 → 1.2.0

package/dist/debug/pty.js

@@ -0,0 +1,924 @@
+import { spawn, spawnSync } from "node:child_process";
+import { mkdir, readFile, writeFile } from "node:fs/promises";
+import path from "node:path";
+const DEFAULT_ROWS = 24;
+const DEFAULT_COLS = 100;
+const DEFAULT_TIMEOUT_MS = 60_000;
+const DEFAULT_IDLE_TIMEOUT_MS = 10_000;
+const DEFAULT_INPUT_DELAY_MS = 40;
+const DEFAULT_REAL_PROVIDER_MAX_ITERATIONS = 10;
+const ARTIFACT_SCHEMA_VERSION = 1;
+const PYTHON_PTY_DRIVER = String.raw `
+import os, sys, pty, select, subprocess, signal, termios, fcntl, struct, time
+rows = int(os.environ.get("PIBO_PTY_ROWS", "24"))
+cols = int(os.environ.get("PIBO_PTY_COLS", "100"))
+cmd = sys.argv[1:]
+if cmd and cmd[0] == "--":
+    cmd = cmd[1:]
+if not cmd:
+    print("missing command", file=sys.stderr)
+    sys.exit(64)
+master, slave = pty.openpty()
+try:
+    fcntl.ioctl(slave, termios.TIOCSWINSZ, struct.pack("HHHH", rows, cols, 0, 0))
+except Exception:
+    pass
+proc = subprocess.Popen(cmd, stdin=slave, stdout=slave, stderr=slave, close_fds=True, start_new_session=True)
+os.close(slave)
+os.set_blocking(master, False)
+os.set_blocking(sys.stdin.fileno(), False)
+stdin_open = True
+
+def terminate(signum, frame):
+    try:
+        os.killpg(proc.pid, signum)
+    except Exception:
+        try:
+            proc.terminate()
+        except Exception:
+            pass
+signal.signal(signal.SIGTERM, terminate)
+signal.signal(signal.SIGINT, terminate)
+
+def drain_once():
+    try:
+        data = os.read(master, 4096)
+    except OSError:
+        return False
+    if not data:
+        return False
+    os.write(sys.stdout.fileno(), data)
+    sys.stdout.flush()
+    return True
+
+exit_code = None
+while True:
+    fds = [master]
+    if stdin_open:
+        fds.append(sys.stdin.fileno())
+    try:
+        readable, _, _ = select.select(fds, [], [], 0.05)
+    except OSError:
+        readable = []
+    if master in readable:
+        if not drain_once():
+            break
+    if stdin_open and sys.stdin.fileno() in readable:
+        try:
+            data = os.read(sys.stdin.fileno(), 4096)
+        except BlockingIOError:
+            data = b""
+        except OSError:
+            stdin_open = False
+            data = b""
+        if data:
+            try:
+                os.write(master, data)
+            except OSError:
+                pass
+        else:
+            stdin_open = False
+    polled = proc.poll()
+    if polled is not None:
+        exit_code = polled
+        deadline = time.time() + 0.2
+        while time.time() < deadline and drain_once():
+            pass
+        break
+if exit_code is None:
+    exit_code = proc.poll()
+if exit_code is None:
+    try:
+        proc.terminate()
+    except Exception:
+        pass
+    exit_code = proc.wait(timeout=1)
+sys.exit(exit_code if exit_code is not None else 1)
+`;
+export async function runDebugPty(args) {
+    if (args.length === 0 || args[0] === "--help" || args[0] === "-h") {
+        printPtyDiscovery();
+        return;
+    }
+    const command = args[0];
+    if (command === "run") {
+        if (args[1] === "--help" || args[1] === "-h") {
+            printPtyDiscovery();
+            return;
+        }
+        const options = parsePtyOptions(args.slice(1));
+        if (options.command.length === 0)
+            throw new Error("pibo debug pty run requires -- <command...>");
+        const scenario = scenarioFromRunOptions(options);
+        const result = await executePtyScenario(scenario, options);
+        printRunResult(result);
+        return;
+    }
+    if (command === "scenario") {
+        if (args[1] === "--help" || args[1] === "-h") {
+            printPtyDiscovery();
+            return;
+        }
+        const options = parsePtyOptions(args.slice(1));
+        const scenario = await loadScenarioFromOptions(options);
+        const result = await executePtyScenario(scenario, options);
+        printRunResult(result);
+        return;
+    }
+    if (command === "list-scenarios") {
+        printBuiltinScenarios();
+        return;
+    }
+    throw new Error(`Unknown pibo debug pty command "${command}". Run pibo debug pty --help.`);
+}
+function printPtyDiscovery() {
+    console.log(`pibo debug pty - run and inspect interactive CLI/TUI commands under a pseudo-terminal
+
+Commands:
+  run             Run one command under PTY
+  scenario        Run a declarative PTY scenario JSON file
+  list-scenarios  List built-in scenario names
+
+Usage:
+  pibo debug pty run [options] -- <command...>
+  pibo debug pty scenario [options] <file>
+  pibo debug pty scenario --builtin cli-session-ui-mocked-e2e
+
+Common options:
+  --rows <n>                 Terminal rows (default: ${DEFAULT_ROWS})
+  --cols <n>                 Terminal columns (default: ${DEFAULT_COLS})
+  --timeout-ms <n>           Wall-clock timeout (default: ${DEFAULT_TIMEOUT_MS})
+  --idle-timeout-ms <n>      Idle timeout after no output (default: ${DEFAULT_IDLE_TIMEOUT_MS})
+  --input-delay-ms <n>       Delay between typed characters (default: ${DEFAULT_INPUT_DELAY_MS})
+  --artifact-dir <path>      Artifact directory
+  --artifact                 Write artifacts for successful runs too
+  --expect <text>            Require cleaned output text (repeatable)
+  --reject <text>            Forbid cleaned output text (repeatable)
+  --type <text>              Type text as a scenario step
+  --press <key>              Press Enter, Escape, CtrlC, Up, or Down
+  --wait-for <text>          Wait until cleaned output contains text
+  --sleep-ms <n>             Sleep as a scenario step
+  --docker-worker <name>     Run inside a named Docker worker/container
+  --workdir <path>           Workdir for host cwd or Docker -w
+  --real-provider            Explicitly allow live provider scenarios
+  --max-iterations <n>       Real-provider iteration cap (default: ${DEFAULT_REAL_PROVIDER_MAX_ITERATIONS})
+
+Safety:
+  Mocked/deterministic mode is default. Real provider mode requires --real-provider and bounded iterations.
+`);
+}
+function printBuiltinScenarios() {
+    console.log(`Built-in PTY scenarios:
+  cli-session-ui-mocked-e2e    Runs pibo tui:sessions without --demo using a deterministic debug fixture when available
+
+Next:
+  pibo debug pty scenario --builtin cli-session-ui-mocked-e2e --artifact
+`);
+}
+function parsePtyOptions(args) {
+    const options = {
+        positionals: [],
+        artifact: false,
+        realProvider: false,
+        env: [],
+        expect: [],
+        reject: [],
+        stopPatterns: [],
+        steps: [],
+        command: [],
+    };
+    let commandMode = false;
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (commandMode) {
+            options.command.push(arg);
+            continue;
+        }
+        if (arg === "--") {
+            commandMode = true;
+            continue;
+        }
+        if (arg === "--artifact")
+            options.artifact = true;
+        else if (arg === "--real-provider")
+            options.realProvider = true;
+        else if (arg === "--rows")
+            options.rows = requireOptionValue(args, ++index, arg);
+        else if (arg === "--cols")
+            options.cols = requireOptionValue(args, ++index, arg);
+        else if (arg === "--timeout-ms")
+            options.timeoutMs = requireOptionValue(args, ++index, arg);
+        else if (arg === "--idle-timeout-ms")
+            options.idleTimeoutMs = requireOptionValue(args, ++index, arg);
+        else if (arg === "--input-delay-ms")
+            options.inputDelayMs = requireOptionValue(args, ++index, arg);
+        else if (arg === "--artifact-dir")
+            options.artifactDir = requireOptionValue(args, ++index, arg);
+        else if (arg === "--docker-worker")
+            options.dockerWorker = requireOptionValue(args, ++index, arg);
+        else if (arg === "--workdir")
+            options.workdir = requireOptionValue(args, ++index, arg);
+        else if (arg === "--provider-mode")
+            options.providerMode = requireOptionValue(args, ++index, arg);
+        else if (arg === "--max-iterations")
+            options.maxIterations = requireOptionValue(args, ++index, arg);
+        else if (arg === "--name")
+            options.name = requireOptionValue(args, ++index, arg);
+        else if (arg === "--env")
+            options.env.push(requireOptionValue(args, ++index, arg));
+        else if (arg === "--expect")
+            options.expect.push(requireOptionValue(args, ++index, arg));
+        else if (arg === "--reject")
+            options.reject.push(requireOptionValue(args, ++index, arg));
+        else if (arg === "--stop-pattern")
+            options.stopPatterns.push(requireOptionValue(args, ++index, arg));
+        else if (arg === "--type")
+            options.steps.push({ typeText: requireOptionValue(args, ++index, arg) });
+        else if (arg === "--press")
+            options.steps.push({ press: requireOptionValue(args, ++index, arg) });
+        else if (arg === "--wait-for")
+            options.steps.push({ waitFor: requireOptionValue(args, ++index, arg) });
+        else if (arg === "--sleep-ms")
+            options.steps.push({ sleepMs: parseNonNegativeInteger(requireOptionValue(args, ++index, arg), arg) });
+        else if (arg === "--builtin")
+            options.builtin = requireOptionValue(args, ++index, arg);
+        else if (arg === "--help" || arg === "-h") {
+            printPtyDiscovery();
+            process.exitCode = 0;
+            return options;
+        }
+        else if (arg.startsWith("--")) {
+            throw new Error(`Unknown pibo debug pty option "${arg}"`);
+        }
+        else {
+            options.positionals.push(arg);
+        }
+    }
+    return options;
+}
+function requireOptionValue(args, index, option) {
+    const value = args[index];
+    if (!value || value.startsWith("--"))
+        throw new Error(`${option} requires a value`);
+    return value;
+}
+function scenarioFromRunOptions(options) {
+    return {
+        name: options.name ?? "adhoc-run",
+        command: options.command,
+        cwd: options.workdir,
+        env: envPairsToRecord(options.env),
+        rows: numberOption(options.rows, "--rows"),
+        cols: numberOption(options.cols, "--cols"),
+        timeoutMs: numberOption(options.timeoutMs, "--timeout-ms"),
+        idleTimeoutMs: numberOption(options.idleTimeoutMs, "--idle-timeout-ms"),
+        inputDelayMs: numberOption(options.inputDelayMs, "--input-delay-ms"),
+        providerMode: parseProviderMode(options.providerMode ?? (options.realProvider ? "real" : undefined)),
+        maxIterations: numberOption(options.maxIterations, "--max-iterations"),
+        artifactDir: options.artifactDir,
+        artifact: options.artifact,
+        steps: options.steps,
+        expect: options.expect,
+        reject: options.reject,
+        stopPatterns: options.stopPatterns,
+    };
+}
+async function loadScenarioFromOptions(options) {
+    if (options.builtin)
+        return builtinScenario(options.builtin, options);
+    const file = options.positionals[0];
+    if (!file)
+        throw new Error("pibo debug pty scenario requires <file> or --builtin <name>");
+    const parsed = JSON.parse(await readFile(file, "utf8"));
+    const scenario = validateScenario(parsed, file);
+    return applyScenarioOverrides(scenario, options);
+}
+function builtinScenario(name, options) {
+    if (name !== "cli-session-ui-mocked-e2e")
+        throw new Error(`Unknown built-in PTY scenario "${name}"`);
+    return applyScenarioOverrides({
+        name,
+        command: ["pibo", "tui:sessions"],
+        rows: 24,
+        cols: 100,
+        timeoutMs: 90_000,
+        idleTimeoutMs: 15_000,
+        inputDelayMs: 45,
+        providerMode: "mocked",
+        artifactDir: "tmp/pty-smoke-artifacts/cli-session-ui-mocked-e2e",
+        env: {
+            PIBO_DEBUG_PTY_SCENARIO: "cli-session-ui-mocked-e2e",
+            PIBO_DEBUG_PTY_CLI_SESSIONS_MOCKED: "1",
+            PIBO_DEBUG_PTY_ASSISTANT_REPLY: "Mocked PTY assistant response",
+        },
+        steps: [
+            { waitFor: "Pibo CLI Sessions", timeoutMs: 20_000 },
+            { typeText: "/new" },
+            { press: "Enter" },
+            { sleepMs: 750 },
+            { typeText: "Hi", iteration: true },
+            { press: "Enter" },
+            { waitFor: "Mocked PTY assistant response", timeoutMs: 10_000 },
+            { typeText: "/status" },
+            { press: "Enter" },
+            { waitFor: "source=", timeoutMs: 10_000 },
+            { typeText: "/quit" },
+            { press: "Enter" },
+        ],
+        expect: ["Pibo CLI Sessions", "Hi", "Mocked PTY assistant response"],
+        reject: ["UnhandledPromiseRejection", "source_closed"],
+    }, options);
+}
+function applyScenarioOverrides(scenario, options) {
+    return {
+        ...scenario,
+        name: options.name ?? scenario.name,
+        cwd: options.workdir ?? scenario.cwd,
+        workdir: options.workdir ?? scenario.workdir,
+        env: { ...(scenario.env ?? {}), ...envPairsToRecord(options.env) },
+        rows: numberOption(options.rows, "--rows") ?? scenario.rows,
+        cols: numberOption(options.cols, "--cols") ?? scenario.cols,
+        timeoutMs: numberOption(options.timeoutMs, "--timeout-ms") ?? scenario.timeoutMs,
+        idleTimeoutMs: numberOption(options.idleTimeoutMs, "--idle-timeout-ms") ?? scenario.idleTimeoutMs,
+        inputDelayMs: numberOption(options.inputDelayMs, "--input-delay-ms") ?? scenario.inputDelayMs,
+        providerMode: parseProviderMode(options.providerMode ?? (options.realProvider ? "real" : undefined)) ?? scenario.providerMode,
+        maxIterations: numberOption(options.maxIterations, "--max-iterations") ?? scenario.maxIterations,
+        artifactDir: options.artifactDir ?? scenario.artifactDir,
+        artifact: options.artifact || scenario.artifact,
+        steps: [...(scenario.steps ?? []), ...options.steps],
+        expect: [...(scenario.expect ?? []), ...options.expect],
+        reject: [...(scenario.reject ?? []), ...options.reject],
+        stopPatterns: [...(scenario.stopPatterns ?? []), ...options.stopPatterns],
+    };
+}
+function validateScenario(value, source) {
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${source}: scenario must be an object`);
+    const raw = value;
+    if (!Array.isArray(raw.command) || raw.command.some((item) => typeof item !== "string") || raw.command.length === 0) {
+        throw new Error(`${source}: command must be a non-empty string array`);
+    }
+    const scenario = {
+        name: optionalString(raw.name, "name", source),
+        command: raw.command,
+        cwd: optionalString(raw.cwd, "cwd", source),
+        workdir: optionalString(raw.workdir, "workdir", source),
+        env: optionalStringRecord(raw.env, "env", source),
+        rows: optionalPositiveNumber(raw.rows, "rows", source),
+        cols: optionalPositiveNumber(raw.cols, "cols", source),
+        timeoutMs: optionalPositiveNumber(raw.timeoutMs, "timeoutMs", source),
+        idleTimeoutMs: optionalPositiveNumber(raw.idleTimeoutMs, "idleTimeoutMs", source),
+        inputDelayMs: optionalNonNegativeNumber(raw.inputDelayMs, "inputDelayMs", source),
+        providerMode: parseProviderModeValue(raw.providerMode, "providerMode", source),
+        maxIterations: optionalPositiveNumber(raw.maxIterations, "maxIterations", source),
+        artifactDir: optionalString(raw.artifactDir, "artifactDir", source),
+        artifact: optionalBoolean(raw.artifact, "artifact", source),
+        steps: parseSteps(raw.steps, source),
+        expect: optionalStringArray(raw.expect, "expect", source),
+        reject: optionalStringArray(raw.reject, "reject", source),
+        stopPatterns: optionalStringArray(raw.stopPatterns, "stopPatterns", source),
+    };
+    return scenario;
+}
+function parseSteps(value, source) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error(`${source}: steps must be an array`);
+    return value.map((step, index) => {
+        if (!step || typeof step !== "object" || Array.isArray(step))
+            throw new Error(`${source}: steps[${index}] must be an object`);
+        const raw = step;
+        const parsed = {
+            waitFor: optionalString(raw.waitFor, `steps[${index}].waitFor`, source),
+            typeText: optionalString(raw.typeText, `steps[${index}].typeText`, source),
+            writeBytes: optionalString(raw.writeBytes, `steps[${index}].writeBytes`, source),
+            press: optionalString(raw.press, `steps[${index}].press`, source),
+            sleepMs: optionalNonNegativeNumber(raw.sleepMs, `steps[${index}].sleepMs`, source),
+            expect: optionalString(raw.expect, `steps[${index}].expect`, source),
+            reject: optionalString(raw.reject, `steps[${index}].reject`, source),
+            timeoutMs: optionalPositiveNumber(raw.timeoutMs, `steps[${index}].timeoutMs`, source),
+            iteration: optionalBoolean(raw.iteration, `steps[${index}].iteration`, source),
+        };
+        const actionCount = [parsed.waitFor, parsed.typeText, parsed.writeBytes, parsed.press, parsed.sleepMs, parsed.expect, parsed.reject].filter((item) => item !== undefined).length;
+        if (actionCount !== 1)
+            throw new Error(`${source}: steps[${index}] must define exactly one action`);
+        return parsed;
+    });
+}
+async function executePtyScenario(input, options) {
+    const scenario = normalizeScenario(input, options);
+    const started = Date.now();
+    const startedAt = new Date(started).toISOString();
+    let runner;
+    const assertions = [];
+    let iterations = 0;
+    let stopReason = "completed";
+    try {
+        validateProviderSafety(scenario, options);
+        runner = await startRunner(scenario);
+        let lastOutputAt = Date.now();
+        let outputLength = 0;
+        const refreshOutputTimestamp = () => {
+            const raw = runner?.getRawOutput() ?? "";
+            if (raw.length !== outputLength) {
+                outputLength = raw.length;
+                lastOutputAt = Date.now();
+            }
+            return lastOutputAt;
+        };
+        for (const step of scenario.steps) {
+            if (step.iteration === true) {
+                iterations += 1;
+                if (scenario.providerMode === "real" && scenario.maxIterations !== undefined && iterations > scenario.maxIterations) {
+                    stopReason = "max_iterations";
+                    throw new Error(`Real-provider PTY scenario exceeded max iterations (${scenario.maxIterations})`);
+                }
+            }
+            await checkIdle(runner, refreshOutputTimestamp, scenario.idleTimeoutMs);
+            await runStep(runner, scenario, step, assertions, refreshOutputTimestamp);
+            refreshOutputTimestamp();
+            const clean = cleanTerminalText(runner.getRawOutput());
+            const matchedStop = scenario.stopPatterns.find((pattern) => clean.includes(pattern));
+            if (matchedStop) {
+                stopReason = `stop_pattern:${matchedStop}`;
+                break;
+            }
+        }
+        const exit = await waitForExitOrIdle(runner, Math.max(1, scenario.timeoutMs - (Date.now() - started)), scenario.idleTimeoutMs, refreshOutputTimestamp);
+        if (exit.idleTimedOut) {
+            stopReason = "idle_timeout";
+            throw new Error(`PTY command produced no output for ${scenario.idleTimeoutMs}ms`);
+        }
+        if (exit.timedOut) {
+            stopReason = stopReason === "completed" ? "wall_clock_timeout" : stopReason;
+            throw new Error(`PTY command timed out after ${scenario.timeoutMs}ms`);
+        }
+        const clean = cleanTerminalText(runner.getRawOutput());
+        assertPatterns(clean, scenario.expect, scenario.reject, assertions);
+        if (exit.exitCode !== 0) {
+            stopReason = `exit_code:${exit.exitCode ?? "signal"}`;
+            throw new Error(`PTY command exited with status ${exit.exitCode ?? exit.signal ?? "unknown"}`);
+        }
+        const result = buildResult(scenario, runner, true, assertions, iterations, started, startedAt, stopReason, exit.exitCode, exit.signal);
+        if (scenario.writeArtifactsOnSuccess)
+            result.artifactDir = await writeArtifacts(scenario, result);
+        return result;
+    }
+    catch (error) {
+        if (stopReason === "completed")
+            stopReason = runner ? "error" : "preflight_error";
+        if (runner)
+            await runner.terminate(stopReason);
+        const result = buildResult(scenario, runner, false, assertions, iterations, started, startedAt, stopReason, null, null);
+        result.artifactDir = await writeArtifacts(scenario, result, error instanceof Error ? error.message : String(error));
+        const message = `${error instanceof Error ? error.message : String(error)}\nPTY artifacts: ${result.artifactDir}`;
+        throw new Error(message);
+    }
+}
+function normalizeScenario(input, options) {
+    const providerMode = parseProviderMode(options.providerMode ?? (options.realProvider ? "real" : undefined)) ?? input.providerMode ?? "mocked";
+    const name = input.name ?? options.name ?? "pty-scenario";
+    const timeoutMs = input.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const idleTimeoutMs = input.idleTimeoutMs ?? DEFAULT_IDLE_TIMEOUT_MS;
+    const artifactDir = input.artifactDir ?? options.artifactDir ?? path.join("tmp", "pty-smoke-artifacts", `${safeName(name)}-${new Date().toISOString().replace(/[:.]/g, "-")}`);
+    const env = { ...(input.env ?? {}) };
+    if (env.PIBO_DEBUG_PTY_SCENARIO === "cli-session-ui-mocked-e2e" && env.PIBO_HOME === undefined) {
+        env.PIBO_HOME = path.resolve(artifactDir, "pibo-home");
+    }
+    return {
+        ...input,
+        name,
+        command: [...input.command],
+        cwd: input.cwd ?? input.workdir ?? options.workdir,
+        workdir: options.workdir ?? input.workdir ?? input.cwd,
+        env,
+        rows: input.rows ?? DEFAULT_ROWS,
+        cols: input.cols ?? DEFAULT_COLS,
+        timeoutMs,
+        idleTimeoutMs,
+        inputDelayMs: input.inputDelayMs ?? DEFAULT_INPUT_DELAY_MS,
+        providerMode,
+        maxIterations: providerMode === "real" ? (input.maxIterations ?? DEFAULT_REAL_PROVIDER_MAX_ITERATIONS) : input.maxIterations,
+        artifactDir,
+        writeArtifactsOnSuccess: options.artifact || input.artifact === true,
+        steps: input.steps ?? [],
+        expect: input.expect ?? [],
+        reject: input.reject ?? [],
+        stopPatterns: input.stopPatterns ?? [],
+        backend: options.dockerWorker ? "docker" : "host",
+        dockerWorker: options.dockerWorker,
+    };
+}
+function validateProviderSafety(scenario, options) {
+    if (scenario.providerMode !== "real")
+        return;
+    if (!options.realProvider)
+        throw new Error("Real-provider PTY scenarios require explicit --real-provider");
+    if (!Number.isInteger(scenario.maxIterations) || (scenario.maxIterations ?? 0) < 1)
+        throw new Error("Real-provider PTY scenarios require --max-iterations to be a positive integer");
+    if (scenario.steps.length === 0 || !scenario.steps.some((step) => step.iteration === true)) {
+        throw new Error("Real-provider PTY scenarios require at least one step marked iteration: true so max iterations can be enforced");
+    }
+    if (scenario.timeoutMs <= 0 || scenario.idleTimeoutMs <= 0)
+        throw new Error("Real-provider PTY scenarios require wall-clock and idle timeouts");
+    if (scenario.expect.length === 0 && scenario.stopPatterns.length === 0 && !scenario.steps.some((step) => step.waitFor)) {
+        throw new Error("Real-provider PTY scenarios require an expected output, stop pattern, or waitFor stop condition");
+    }
+}
+async function startRunner(scenario) {
+    if (scenario.backend === "docker")
+        return startDockerRunner(scenario);
+    return startHostRunner(scenario);
+}
+async function startHostRunner(scenario) {
+    const python = detectHostPython();
+    const env = { ...process.env, ...scenario.env, PIBO_PTY_ROWS: String(scenario.rows), PIBO_PTY_COLS: String(scenario.cols) };
+    const child = spawn(python, ["-u", "-c", PYTHON_PTY_DRIVER, "--", ...scenario.command], {
+        cwd: scenario.cwd,
+        env,
+        stdio: "pipe",
+    });
+    return wrapChild(child, "host", `python:${python}`);
+}
+async function startDockerRunner(scenario) {
+    if (!scenario.dockerWorker)
+        throw new Error("Docker PTY backend requires --docker-worker <name>");
+    const python = detectDockerPython(scenario.dockerWorker);
+    const args = ["exec", "-i"];
+    if (scenario.workdir)
+        args.push("-w", scenario.workdir);
+    args.push("-e", `PIBO_PTY_ROWS=${scenario.rows}`, "-e", `PIBO_PTY_COLS=${scenario.cols}`);
+    for (const [key, value] of Object.entries(scenario.env))
+        args.push("-e", `${key}=${value}`);
+    args.push(scenario.dockerWorker, python, "-u", "-c", PYTHON_PTY_DRIVER, "--", ...scenario.command);
+    const child = spawn("docker", args, { stdio: "pipe" });
+    return wrapChild(child, "docker", `docker-exec:${python}`);
+}
+function detectHostPython() {
+    for (const candidate of ["python3", "python"]) {
+        const result = spawnSync(candidate, ["--version"], { stdio: "ignore" });
+        if (result.status === 0)
+            return candidate;
+    }
+    throw new Error("No Python PTY driver found on host. Install python3 or run in an environment with PTY support.");
+}
+function detectDockerPython(worker) {
+    const inspect = spawnSync("docker", ["inspect", "-f", "{{.State.Running}} {{.Id}}", worker], { encoding: "utf8" });
+    if (inspect.status !== 0)
+        throw new Error(`Docker worker "${worker}" is not available or not running`);
+    if (!inspect.stdout.trim().startsWith("true"))
+        throw new Error(`Docker worker "${worker}" is not running`);
+    const result = spawnSync("docker", ["exec", worker, "sh", "-lc", "command -v python3 || command -v python"], { encoding: "utf8" });
+    if (result.status !== 0 || result.stdout.trim().length === 0) {
+        throw new Error(`Docker worker "${worker}" does not provide python3/python for PTY execution. Install python3, or add an internal PTY helper/script fallback.`);
+    }
+    return result.stdout.trim().split(/\s+/)[0] ?? "python3";
+}
+function wrapChild(child, backend, ptyMethod) {
+    let rawOutput = "";
+    let driverStderr = "";
+    const events = [];
+    let exitState;
+    const exitPromise = new Promise((resolve) => {
+        child.on("exit", (exitCode, signal) => {
+            exitState = { exitCode, signal };
+            resolve(exitState);
+        });
+    });
+    child.stdout.on("data", (data) => {
+        const text = data.toString("utf8");
+        rawOutput += text;
+        events.push({ t: Date.now(), source: "stdout", data: text });
+    });
+    child.stderr.on("data", (data) => {
+        const text = data.toString("utf8");
+        driverStderr += text;
+        events.push({ t: Date.now(), source: "system", kind: "driver_stderr", data: text });
+    });
+    child.on("error", (error) => {
+        driverStderr += `${error.message}\n`;
+        events.push({ t: Date.now(), source: "system", kind: "error", detail: error.message });
+    });
+    return {
+        backend,
+        ptyMethod,
+        async write(data) {
+            events.push({ t: Date.now(), source: "stdin", data: Buffer.isBuffer(data) ? data.toString("utf8") : data });
+            await new Promise((resolve, reject) => {
+                child.stdin.write(data, (error) => error ? reject(error) : resolve());
+            });
+        },
+        async terminate(reason) {
+            events.push({ t: Date.now(), source: "system", kind: "terminate", detail: reason });
+            if (exitState)
+                return;
+            child.kill("SIGTERM");
+            await Promise.race([
+                exitPromise,
+                delay(1_000).then(() => {
+                    if (!exitState)
+                        child.kill("SIGKILL");
+                }),
+            ]);
+        },
+        async waitForExit(timeoutMs) {
+            if (exitState)
+                return { ...exitState, timedOut: false };
+            const timeout = delay(timeoutMs).then(() => ({ exitCode: null, signal: null, timedOut: true }));
+            const exit = exitPromise.then((value) => ({ ...value, timedOut: false }));
+            return Promise.race([exit, timeout]);
+        },
+        getRawOutput: () => rawOutput,
+        getDriverStderr: () => driverStderr,
+        getEvents: () => events,
+    };
+}
+async function runStep(runner, scenario, step, assertions, markOutput) {
+    if (step.waitFor !== undefined) {
+        await waitForText(runner, step.waitFor, step.timeoutMs ?? scenario.timeoutMs, scenario.idleTimeoutMs, markOutput);
+        return;
+    }
+    if (step.typeText !== undefined) {
+        for (const char of step.typeText) {
+            await runner.write(char);
+            if (scenario.inputDelayMs > 0)
+                await delay(scenario.inputDelayMs);
+        }
+        return;
+    }
+    if (step.writeBytes !== undefined) {
+        await runner.write(step.writeBytes);
+        return;
+    }
+    if (step.press !== undefined) {
+        await runner.write(keySequence(step.press));
+        if (scenario.inputDelayMs > 0)
+            await delay(scenario.inputDelayMs);
+        return;
+    }
+    if (step.sleepMs !== undefined) {
+        await delay(step.sleepMs);
+        return;
+    }
+    const clean = cleanTerminalText(runner.getRawOutput());
+    if (step.expect !== undefined) {
+        assertPatterns(clean, [step.expect], [], assertions);
+        return;
+    }
+    if (step.reject !== undefined)
+        assertPatterns(clean, [], [step.reject], assertions);
+}
+async function waitForText(runner, pattern, timeoutMs, idleTimeoutMs, markOutput) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const lastOutputAt = markOutput();
+        if (cleanTerminalText(runner.getRawOutput()).includes(pattern))
+            return;
+        if (Date.now() - lastOutputAt > idleTimeoutMs) {
+            await runner.terminate("idle_timeout");
+            throw new Error(`PTY command produced no output for ${idleTimeoutMs}ms while waiting for ${JSON.stringify(pattern)}`);
+        }
+        await delay(50);
+    }
+    throw new Error(`Timed out waiting for PTY output ${JSON.stringify(pattern)} after ${timeoutMs}ms`);
+}
+async function waitForExitOrIdle(runner, timeoutMs, idleTimeoutMs, markOutput) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        const lastOutputAt = markOutput();
+        const remaining = Math.max(1, Math.min(100, deadline - Date.now()));
+        const exit = await runner.waitForExit(remaining);
+        if (!exit.timedOut)
+            return { ...exit, timedOut: false, idleTimedOut: false };
+        if (Date.now() - lastOutputAt > idleTimeoutMs)
+            return { exitCode: null, signal: null, timedOut: false, idleTimedOut: true };
+    }
+    return { exitCode: null, signal: null, timedOut: true, idleTimedOut: false };
+}
+async function checkIdle(runner, lastOutputAt, idleTimeoutMs) {
+    if (Date.now() - lastOutputAt() > idleTimeoutMs) {
+        await runner.terminate("idle_timeout");
+        throw new Error(`PTY command produced no output for ${idleTimeoutMs}ms`);
+    }
+}
+function assertPatterns(clean, expect, reject, assertions) {
+    for (const pattern of expect) {
+        const passed = clean.includes(pattern);
+        assertions.push({ type: "expect", pattern, passed, message: passed ? undefined : `Missing expected text: ${pattern}` });
+        if (!passed)
+            throw new Error(`Missing expected PTY output ${JSON.stringify(pattern)}`);
+    }
+    for (const pattern of reject) {
+        const passed = !clean.includes(pattern);
+        assertions.push({ type: "reject", pattern, passed, message: passed ? undefined : `Forbidden text appeared: ${pattern}` });
+        if (!passed)
+            throw new Error(`Forbidden PTY output appeared ${JSON.stringify(pattern)}`);
+    }
+}
+function keySequence(key) {
+    const normalized = key.toLowerCase();
+    if (normalized === "enter" || normalized === "return")
+        return "\r";
+    if (normalized === "escape" || normalized === "esc")
+        return "\x1b";
+    if (normalized === "ctrlc" || normalized === "ctrl-c" || normalized === "c-c")
+        return "\x03";
+    if (normalized === "up")
+        return "\x1b[A";
+    if (normalized === "down")
+        return "\x1b[B";
+    throw new Error(`Unsupported PTY key "${key}". Supported: Enter, Escape, CtrlC, Up, Down.`);
+}
+function cleanTerminalText(raw) {
+    return raw
+        .replace(/\x1b\][^\x07]*(?:\x07|\x1b\\)/g, "")
+        .replace(/\x1b\[[0-?]*[ -/]*[@-~]/g, "")
+        .replace(/\x1b[PX^_].*?\x1b\\/gs, "")
+        .replace(/\x1b[@-_]/g, "")
+        .replace(/\r\n/g, "\n")
+        .replace(/\r/g, "\n");
+}
+function buildResult(scenario, runner, ok, assertions, iterations, started, startedAt, stopReason, exitCode, signal) {
+    const ended = Date.now();
+    return {
+        ok,
+        name: scenario.name,
+        backend: scenario.backend,
+        exitCode,
+        signal,
+        stopReason,
+        startedAt,
+        endedAt: new Date(ended).toISOString(),
+        durationMs: ended - started,
+        rawOutput: runner?.getRawOutput() ?? "",
+        driverStderr: runner?.getDriverStderr() ?? "",
+        events: runner?.getEvents() ?? [],
+        assertions,
+        iterations,
+    };
+}
+async function writeArtifacts(scenario, result, error) {
+    const artifactDir = path.resolve(scenario.artifactDir);
+    await mkdir(artifactDir, { recursive: true });
+    const clean = cleanTerminalText(result.rawOutput);
+    const metadata = {
+        schemaVersion: ARTIFACT_SCHEMA_VERSION,
+        name: scenario.name,
+        backend: scenario.backend,
+        ptyMethod: result.backend === "docker" ? "docker-python-pty" : "host-python-pty",
+        dockerWorker: scenario.dockerWorker,
+        command: scenario.command,
+        cwd: scenario.cwd,
+        workdir: scenario.workdir,
+        rows: scenario.rows,
+        cols: scenario.cols,
+        providerMode: scenario.providerMode,
+        realProviderRequested: scenario.providerMode === "real",
+        maxIterations: scenario.maxIterations,
+        observedIterations: result.iterations,
+        timeoutMs: scenario.timeoutMs,
+        idleTimeoutMs: scenario.idleTimeoutMs,
+        startedAt: result.startedAt,
+        endedAt: result.endedAt,
+        durationMs: result.durationMs,
+        exitCode: result.exitCode,
+        signal: result.signal,
+        ok: result.ok,
+        stopReason: result.stopReason,
+        error,
+        env: redactEnvKeys(scenario.env),
+        screenCaptureMethod: "cleaned-tail",
+    };
+    await writeFile(path.join(artifactDir, "metadata.json"), `${JSON.stringify(metadata, null, 2)}\n`);
+    await writeFile(path.join(artifactDir, "input.json"), `${JSON.stringify({ steps: scenario.steps, inputDelayMs: scenario.inputDelayMs }, null, 2)}\n`);
+    await writeFile(path.join(artifactDir, "assertions.json"), `${JSON.stringify({ assertions: result.assertions, expect: scenario.expect, reject: scenario.reject }, null, 2)}\n`);
+    await writeFile(path.join(artifactDir, "raw.ansi.log"), result.rawOutput);
+    await writeFile(path.join(artifactDir, "clean.txt"), clean);
+    await writeFile(path.join(artifactDir, "screen.txt"), finalScreen(clean, scenario.rows));
+    if (result.events.length > 0)
+        await writeFile(path.join(artifactDir, "events.jsonl"), result.events.map((event) => JSON.stringify(event)).join("\n") + "\n");
+    if (result.driverStderr)
+        await writeFile(path.join(artifactDir, "driver.stderr.log"), result.driverStderr);
+    return artifactDir;
+}
+function finalScreen(clean, rows) {
+    const lines = clean.split("\n");
+    return lines.slice(Math.max(0, lines.length - rows)).join("\n");
+}
+function printRunResult(result) {
+    console.log(`PTY ${result.ok ? "passed" : "failed"}: ${result.name}`);
+    console.log(`backend\t${result.backend}`);
+    console.log(`exitCode\t${result.exitCode ?? "-"}`);
+    console.log(`stopReason\t${result.stopReason}`);
+    console.log(`durationMs\t${result.durationMs}`);
+    if (result.artifactDir)
+        console.log(`artifacts\t${result.artifactDir}`);
+}
+function envPairsToRecord(pairs) {
+    const env = {};
+    for (const pair of pairs) {
+        const index = pair.indexOf("=");
+        if (index <= 0)
+            throw new Error(`--env values must use KEY=VALUE, got ${JSON.stringify(pair)}`);
+        env[pair.slice(0, index)] = pair.slice(index + 1);
+    }
+    return env;
+}
+function redactEnvKeys(env) {
+    const redacted = {};
+    for (const [key, value] of Object.entries(env)) {
+        redacted[key] = /token|secret|key|password|credential/i.test(key) ? "[redacted]" : value;
+    }
+    return redacted;
+}
+function parseProviderMode(value) {
+    if (value === undefined)
+        return undefined;
+    if (value === "mocked" || value === "deterministic" || value === "real")
+        return value;
+    throw new Error(`providerMode must be mocked, deterministic, or real; got ${JSON.stringify(value)}`);
+}
+function parseProviderModeValue(value, field, source) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error(`${source}: ${field} must be a string`);
+    return parseProviderMode(value);
+}
+function numberOption(value, option) {
+    if (value === undefined)
+        return undefined;
+    return parsePositiveInteger(value, option);
+}
+function parsePositiveInteger(value, field) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 1)
+        throw new Error(`${field} must be a positive integer`);
+    return parsed;
+}
+function parseNonNegativeInteger(value, field) {
+    const parsed = Number(value);
+    if (!Number.isInteger(parsed) || parsed < 0)
+        throw new Error(`${field} must be a non-negative integer`);
+    return parsed;
+}
+function optionalString(value, field, source) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "string")
+        throw new Error(`${source}: ${field} must be a string`);
+    return value;
+}
+function optionalBoolean(value, field, source) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "boolean")
+        throw new Error(`${source}: ${field} must be a boolean`);
+    return value;
+}
+function optionalPositiveNumber(value, field, source) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 1)
+        throw new Error(`${source}: ${field} must be a positive integer`);
+    return value;
+}
+function optionalNonNegativeNumber(value, field, source) {
+    if (value === undefined)
+        return undefined;
+    if (typeof value !== "number" || !Number.isInteger(value) || value < 0)
+        throw new Error(`${source}: ${field} must be a non-negative integer`);
+    return value;
+}
+function optionalStringArray(value, field, source) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value) || value.some((item) => typeof item !== "string"))
+        throw new Error(`${source}: ${field} must be a string array`);
+    return value;
+}
+function optionalStringRecord(value, field, source) {
+    if (value === undefined)
+        return undefined;
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        throw new Error(`${source}: ${field} must be an object`);
+    const record = {};
+    for (const [key, item] of Object.entries(value)) {
+        if (typeof item !== "string")
+            throw new Error(`${source}: ${field}.${key} must be a string`);
+        record[key] = item;
+    }
+    return record;
+}
+function safeName(name) {
+    return name.toLowerCase().replace(/[^a-z0-9._-]+/g, "-").replace(/^-+|-+$/g, "") || "pty-scenario";
+}
+function delay(ms) {
+    return new Promise((resolve) => setTimeout(resolve, ms));
+}
+export const __debugPtyForTests = {
+    cleanTerminalText,
+    keySequence,
+    validateScenario,
+};