@sema-agent/core 1.279.0

package/dist/engine/execution-env/node-execution-env.js

@@ -0,0 +1,945 @@
+import { spawn } from "node:child_process";
+import { randomUUID } from "node:crypto";
+import { closeSync, constants, createReadStream, mkdtempSync, openSync, readSync, statSync } from "node:fs";
+import { access, appendFile, lstat, mkdir, mkdtemp, readdir, readFile, readlink, realpath, rm, writeFile, } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { isAbsolute, join, resolve } from "node:path";
+import { createInterface } from "node:readline";
+import { ExecutionError, err, FileError, ok, toError, } from "../harness/types.js";
+import { killProcessTree } from "./kill-tree.js";
+import { scrubSecretEnv } from "../../core/secret-env.js";
+import { RollingTailBuffer, markTruncated } from "../../core/exec-output-tail.js";
+import { BackgroundShellError } from "../../core/background-shell.js";
+import { SchedulerError } from "../../core/scheduler.js";
+const MAX_TIMER_TIMEOUT_MS = 2_147_000_000;
+function resolvePath(cwd, path) {
+    return isAbsolute(path) ? path : resolve(cwd, path);
+}
+export function resolveExecTimeoutMs(timeoutSeconds) {
+    if (typeof timeoutSeconds !== "number" ||
+        !Number.isFinite(timeoutSeconds) ||
+        timeoutSeconds <= 0) {
+        return undefined;
+    }
+    const milliseconds = Math.floor(timeoutSeconds * 1000);
+    if (!Number.isFinite(milliseconds) || milliseconds <= 0) {
+        return 1;
+    }
+    return Math.min(milliseconds, MAX_TIMER_TIMEOUT_MS);
+}
+function fileKindFromStats(stats) {
+    if (stats.isFile()) {
+        return "file";
+    }
+    if (stats.isDirectory()) {
+        return "directory";
+    }
+    if (stats.isSymbolicLink()) {
+        return "symlink";
+    }
+    return undefined;
+}
+function fileInfoFromStats(path, stats) {
+    const kind = fileKindFromStats(stats);
+    if (!kind) {
+        return err(new FileError("invalid", "Unsupported file type", path));
+    }
+    return ok({
+        name: (() => {
+            const t = path.replace(/[\\/]+$/, "");
+            return t.slice(Math.max(t.lastIndexOf("/"), t.lastIndexOf("\\")) + 1) || path;
+        })(),
+        path,
+        kind,
+        size: stats.size,
+        mtimeMs: stats.mtimeMs,
+    });
+}
+function isNodeError(error) {
+    return error instanceof Error && "code" in error;
+}
+function toFileError(error, path) {
+    if (error instanceof FileError) {
+        return error;
+    }
+    const cause = toError(error);
+    if (isNodeError(error)) {
+        const message = error.message;
+        switch (error.code) {
+            case "ABORT_ERR":
+                return new FileError("aborted", message, path, cause);
+            case "ENOENT":
+                return new FileError("not_found", message, path, cause);
+            case "EACCES":
+            case "EPERM":
+                return new FileError("permission_denied", message, path, cause);
+            case "ENOTDIR":
+                return new FileError("not_directory", message, path, cause);
+            case "EISDIR":
+                return new FileError("is_directory", message, path, cause);
+            case "EINVAL":
+                return new FileError("invalid", message, path, cause);
+            default:
+                break;
+        }
+    }
+    return new FileError("unknown", cause.message, path, cause);
+}
+function abortResult(signal, path) {
+    return signal?.aborted ? err(new FileError("aborted", "aborted", path)) : undefined;
+}
+async function pathExists(path) {
+    try {
+        await access(path, constants.F_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+}
+async function runCommand(command, args, timeoutMs) {
+    return await new Promise((resolveLocal) => {
+        let stdout = "";
+        let child;
+        try {
+            child = spawn(command, args, {
+                stdio: ["ignore", "pipe", "ignore"],
+                windowsHide: true,
+            });
+        }
+        catch {
+            resolveLocal({ stdout: "", status: null });
+            return;
+        }
+        const timeout = setTimeout(() => {
+            if (child.pid) {
+                killProcessTree(child.pid, { force: true });
+            }
+        }, timeoutMs);
+        child.stdout?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+        });
+        child.stdout?.on("error", () => { });
+        child.on("error", () => {
+            clearTimeout(timeout);
+            resolveLocal({ stdout: "", status: null });
+        });
+        child.on("close", (status) => {
+            clearTimeout(timeout);
+            resolveLocal({ stdout, status });
+        });
+    });
+}
+export function isWslBashLauncher(p) {
+    return /[/\\](system32|windowsapps)[/\\]bash\.exe$/i.test(p);
+}
+async function findBashOnPath() {
+    const result = process.platform === "win32"
+        ? await runCommand("where", ["bash.exe"], 5000)
+        : await runCommand("which", ["bash"], 5000);
+    if (result.status !== 0 || !result.stdout) {
+        return null;
+    }
+    const lines = result.stdout.trim().split(/\r?\n/);
+    const firstMatch = process.platform === "win32" ? lines.find((l) => !isWslBashLauncher(l)) : lines[0];
+    return firstMatch && (await pathExists(firstMatch)) ? firstMatch : null;
+}
+export async function getShellConfig(customShellPath) {
+    if (customShellPath) {
+        if (await pathExists(customShellPath)) {
+            return ok({ shell: customShellPath, args: ["-c"] });
+        }
+        return err(new ExecutionError("shell_unavailable", `Custom shell path not found: ${customShellPath}`));
+    }
+    if (process.platform === "win32") {
+        const candidates = [];
+        const programFiles = process.env.ProgramFiles;
+        if (programFiles) {
+            candidates.push(`${programFiles}\\Git\\bin\\bash.exe`);
+        }
+        const programFilesX86 = process.env["ProgramFiles(x86)"];
+        if (programFilesX86) {
+            candidates.push(`${programFilesX86}\\Git\\bin\\bash.exe`);
+        }
+        for (const candidate of candidates) {
+            if (await pathExists(candidate)) {
+                return ok({ shell: candidate, args: ["-c"] });
+            }
+        }
+        const bashOnPath = await findBashOnPath();
+        if (bashOnPath) {
+            return ok({ shell: bashOnPath, args: ["-c"] });
+        }
+        return err(new ExecutionError("shell_unavailable", "No bash shell found"));
+    }
+    if (await pathExists("/bin/bash")) {
+        return ok({ shell: "/bin/bash", args: ["-c"] });
+    }
+    const bashOnPath = await findBashOnPath();
+    if (bashOnPath) {
+        return ok({ shell: bashOnPath, args: ["-c"] });
+    }
+    return ok({ shell: "sh", args: ["-c"] });
+}
+const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
+function getShellEnv(inheritEnv, baseEnv, extraEnv) {
+    let inherited;
+    if (inheritEnv === "all") {
+        inherited = process.env;
+    }
+    else if (Array.isArray(inheritEnv)) {
+        inherited = {};
+        for (const k of inheritEnv)
+            if (process.env[k] !== undefined)
+                inherited[k] = process.env[k];
+    }
+    else {
+        inherited = scrubSecretEnv(process.env);
+    }
+    return {
+        ...inherited,
+        ...baseEnv,
+        ...extraEnv,
+    };
+}
+const SIGNUM = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGABRT: 6, SIGKILL: 9, SIGSEGV: 11, SIGPIPE: 13, SIGTERM: 15 };
+export function openSpoolPair(base) {
+    const outPath = `${base}.out.log`;
+    const errPath = `${base}.err.log`;
+    const fdOut = openSync(outPath, "wx", 0o600);
+    let fdErr;
+    try {
+        fdErr = openSync(errPath, "wx", 0o600);
+    }
+    catch (e) {
+        try {
+            closeSync(fdOut);
+        }
+        catch {
+        }
+        throw e;
+    }
+    return { outPath, errPath, fds: [fdOut, fdErr] };
+}
+export class NodeExecutionEnv {
+    cwd;
+    shellPath;
+    shellEnv;
+    inheritEnv;
+    scheduler;
+    bgShells = new Map();
+    bgCounter = 0;
+    retainBackgroundProcesses;
+    bgSpoolDir;
+    backgroundCapabilities;
+    constructor(options) {
+        this.cwd = options.cwd;
+        this.shellPath = options.shellPath;
+        this.shellEnv = options.shellEnv;
+        this.inheritEnv = options.inheritEnv ?? "scrub";
+        this.scheduler = options.scheduler;
+        this.retainBackgroundProcesses = options.retainBackgroundProcesses ?? false;
+        this.backgroundCapabilities = {
+            supported: true,
+            maxConcurrent: 8,
+            defaultBgTimeoutSec: 30 * 60,
+            maxBgTimeoutSec: 2 * 60 * 60,
+            supportsDetach: true,
+            retainBackgroundProcesses: this.retainBackgroundProcesses,
+        };
+    }
+    get schedulerCapabilities() {
+        return (this.scheduler?.schedulerCapabilities ?? {
+            supported: false,
+            maxScheduledPerScope: 0,
+            minDelaySec: 0,
+            minCronIntervalSec: 0,
+            maxScheduledHorizonSec: 0,
+        });
+    }
+    async schedule(intent, ctx) {
+        if (!this.scheduler)
+            return err(new SchedulerError("unsupported", "No scheduler backend wired on this environment."));
+        return this.scheduler.schedule(intent, ctx);
+    }
+    async cancel(id, ctx) {
+        if (!this.scheduler)
+            return err(new SchedulerError("unsupported", "No scheduler backend wired on this environment."));
+        return this.scheduler.cancel(id, ctx);
+    }
+    async list(ctx) {
+        if (!this.scheduler)
+            return err(new SchedulerError("unsupported", "No scheduler backend wired on this environment."));
+        return this.scheduler.list(ctx);
+    }
+    async absolutePath(path) {
+        return ok(resolvePath(this.cwd, path));
+    }
+    async joinPath(parts) {
+        return ok(join(...parts));
+    }
+    async exec(command, options) {
+        if (options?.abortSignal?.aborted) {
+            return err(new ExecutionError("aborted", "aborted"));
+        }
+        const cwd = options?.cwd ? resolvePath(this.cwd, options.cwd) : this.cwd;
+        const shellConfig = await getShellConfig(this.shellPath);
+        if (!shellConfig.ok) {
+            return shellConfig;
+        }
+        return await new Promise((resolvePromise) => {
+            const stdoutTail = new RollingTailBuffer();
+            const stderrTail = new RollingTailBuffer();
+            let settled = false;
+            let timedOut = false;
+            let callbackError;
+            let child;
+            const timeoutRef = {};
+            const forceSettleRef = {};
+            const armForceSettle = (result) => {
+                if (forceSettleRef.current || settled)
+                    return;
+                forceSettleRef.current = setTimeout(() => {
+                    try {
+                        child?.stdout?.destroy();
+                        child?.stderr?.destroy();
+                    }
+                    catch {
+                    }
+                    settle(result);
+                }, EXEC_FORCE_SETTLE_GRACE_MS);
+                forceSettleRef.current.unref?.();
+            };
+            const partialOutput = () => {
+                const so = stdoutTail.result();
+                const se = stderrTail.result();
+                return { stdout: markTruncated(so.text, so.droppedBytes), stderr: markTruncated(se.text, se.droppedBytes) };
+            };
+            const onAbort = () => {
+                if (child?.pid) {
+                    killProcessTree(child.pid, { force: true });
+                }
+                armForceSettle(err(new ExecutionError("aborted", "aborted", undefined, partialOutput())));
+            };
+            const settle = (result) => {
+                if (timeoutRef.current) {
+                    clearTimeout(timeoutRef.current);
+                }
+                if (forceSettleRef.current) {
+                    clearTimeout(forceSettleRef.current);
+                }
+                if (options?.abortSignal) {
+                    options.abortSignal.removeEventListener("abort", onAbort);
+                }
+                if (settled) {
+                    return;
+                }
+                settled = true;
+                resolvePromise(result);
+            };
+            try {
+                child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
+                    cwd,
+                    detached: process.platform !== "win32",
+                    env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env),
+                    stdio: ["ignore", "pipe", "pipe"],
+                    windowsHide: true,
+                });
+            }
+            catch (error) {
+                const cause = toError(error);
+                settle(err(new ExecutionError("spawn_error", cause.message, cause)));
+                return;
+            }
+            const timeoutMs = resolveExecTimeoutMs(options?.timeout);
+            timeoutRef.current =
+                timeoutMs === undefined
+                    ? undefined
+                    : setTimeout(() => {
+                        timedOut = true;
+                        if (child?.pid) {
+                            killProcessTree(child.pid, { force: true });
+                        }
+                        armForceSettle(err(new ExecutionError("timeout", `timeout:${options?.timeout}`, undefined, partialOutput())));
+                    }, timeoutMs);
+            if (options?.abortSignal) {
+                if (options.abortSignal.aborted) {
+                    onAbort();
+                }
+                else {
+                    options.abortSignal.addEventListener("abort", onAbort, { once: true });
+                }
+            }
+            const onDetach = () => {
+                if (settled || !child)
+                    return;
+                const shellId = this.adoptRunningChild(child, stdoutTail.result().text, stderrTail.result().text);
+                if (shellId === undefined)
+                    return;
+                if (timeoutRef.current)
+                    clearTimeout(timeoutRef.current);
+                settle(ok({ stdout: stdoutTail.result().text, stderr: stderrTail.result().text, exitCode: 0, detached: { shellId } }));
+            };
+            if (options?.detachSignal) {
+                if (options.detachSignal.aborted)
+                    onDetach();
+                else {
+                    const dl = () => onDetach();
+                    options.detachSignal.addEventListener("abort", dl, { once: true });
+                }
+            }
+            child.stdout?.setEncoding("utf8");
+            child.stderr?.setEncoding("utf8");
+            child.stdout?.on("data", (chunk) => {
+                stdoutTail.push(Buffer.from(chunk, "utf8"));
+                try {
+                    options?.onStdout?.(chunk);
+                }
+                catch (error) {
+                    const cause = toError(error);
+                    callbackError = new ExecutionError("callback_error", cause.message, cause);
+                    onAbort();
+                }
+            });
+            child.stderr?.on("data", (chunk) => {
+                stderrTail.push(Buffer.from(chunk, "utf8"));
+                try {
+                    options?.onStderr?.(chunk);
+                }
+                catch (error) {
+                    const cause = toError(error);
+                    callbackError = new ExecutionError("callback_error", cause.message, cause);
+                    onAbort();
+                }
+            });
+            child.stdout?.on("error", () => { });
+            child.stderr?.on("error", () => { });
+            child.on("error", (error) => {
+                if (options?.abortSignal?.aborted) {
+                    settle(err(new ExecutionError("aborted", "aborted", undefined, partialOutput())));
+                    return;
+                }
+                settle(err(new ExecutionError("spawn_error", error.message, error)));
+            });
+            child.on("close", (code, signal) => {
+                if (callbackError) {
+                    settle(err(callbackError));
+                    return;
+                }
+                if (timedOut) {
+                    settle(err(new ExecutionError("timeout", `timeout:${options?.timeout}`, undefined, partialOutput())));
+                    return;
+                }
+                if (options?.abortSignal?.aborted) {
+                    settle(err(new ExecutionError("aborted", "aborted", undefined, partialOutput())));
+                    return;
+                }
+                const so = stdoutTail.result();
+                const se = stderrTail.result();
+                if (code === null && signal) {
+                    const signum = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGABRT: 6, SIGKILL: 9, SIGSEGV: 11, SIGPIPE: 13, SIGTERM: 15 };
+                    settle(ok({
+                        stdout: markTruncated(so.text, so.droppedBytes),
+                        stderr: `${markTruncated(se.text, se.droppedBytes)}${se.text.endsWith("\n") || se.text === "" ? "" : "\n"}[process terminated by ${signal}]`,
+                        exitCode: 128 + (signum[signal] ?? 9),
+                    }));
+                    return;
+                }
+                settle(ok({ stdout: markTruncated(so.text, so.droppedBytes), stderr: markTruncated(se.text, se.droppedBytes), exitCode: code ?? 0 }));
+            });
+        });
+    }
+    async readTextFile(path, abortSignal) {
+        const resolved = resolvePath(this.cwd, path);
+        const aborted = abortResult(abortSignal, resolved);
+        if (aborted) {
+            return aborted;
+        }
+        try {
+            return ok(await readFile(resolved, { encoding: "utf8", signal: abortSignal }));
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
+    async readTextLines(path, options) {
+        const resolved = resolvePath(this.cwd, path);
+        const aborted = abortResult(options?.abortSignal, resolved);
+        if (aborted) {
+            return aborted;
+        }
+        if (options?.maxLines !== undefined && options.maxLines <= 0) {
+            return ok([]);
+        }
+        let stream;
+        let lineReader;
+        try {
+            stream = createReadStream(resolved, { encoding: "utf8", signal: options?.abortSignal });
+            lineReader = createInterface({ input: stream, crlfDelay: Infinity });
+            const lines = [];
+            for await (const line of lineReader) {
+                const loopAbort = abortResult(options?.abortSignal, resolved);
+                if (loopAbort) {
+                    return loopAbort;
+                }
+                lines.push(line);
+                if (options?.maxLines !== undefined && lines.length >= options.maxLines) {
+                    break;
+                }
+            }
+            const afterReadAbort = abortResult(options?.abortSignal, resolved);
+            if (afterReadAbort) {
+                return afterReadAbort;
+            }
+            return ok(lines);
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+        finally {
+            lineReader?.close();
+            stream?.destroy();
+        }
+    }
+    async readBinaryFile(path, abortSignal) {
+        const resolved = resolvePath(this.cwd, path);
+        const aborted = abortResult(abortSignal, resolved);
+        if (aborted) {
+            return aborted;
+        }
+        try {
+            return ok(await readFile(resolved, { signal: abortSignal }));
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
+    async writeFile(path, content, abortSignal) {
+        const resolved = resolvePath(this.cwd, path);
+        const aborted = abortResult(abortSignal, resolved);
+        if (aborted) {
+            return aborted;
+        }
+        try {
+            await mkdir(resolve(resolved, ".."), { recursive: true });
+            const afterMkdirAbort = abortResult(abortSignal, resolved);
+            if (afterMkdirAbort) {
+                return afterMkdirAbort;
+            }
+            await writeFile(resolved, content, { signal: abortSignal });
+            return ok(undefined);
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
+    async writeFileExclusive(path, content, abortSignal) {
+        const resolved = resolvePath(this.cwd, path);
+        const aborted = abortResult(abortSignal, resolved);
+        if (aborted) {
+            return aborted;
+        }
+        try {
+            await mkdir(resolve(resolved, ".."), { recursive: true });
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+        const afterMkdirAbort = abortResult(abortSignal, resolved);
+        if (afterMkdirAbort) {
+            return afterMkdirAbort;
+        }
+        try {
+            await writeFile(resolved, content, { signal: abortSignal, flag: "wx" });
+            return ok(undefined);
+        }
+        catch (error) {
+            if (error?.code === "EEXIST") {
+                return err(new FileError("already_exists", `file already exists: ${resolved}`, resolved, error instanceof Error ? error : undefined));
+            }
+            return err(toFileError(error, resolved));
+        }
+    }
+    async appendFile(path, content) {
+        const resolved = resolvePath(this.cwd, path);
+        try {
+            await mkdir(resolve(resolved, ".."), { recursive: true });
+            await appendFile(resolved, content);
+            return ok(undefined);
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
+    async fileInfo(path) {
+        const resolved = resolvePath(this.cwd, path);
+        try {
+            return fileInfoFromStats(resolved, await lstat(resolved));
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
+    async listDir(path, abortSignal) {
+        const resolved = resolvePath(this.cwd, path);
+        const aborted = abortResult(abortSignal, resolved);
+        if (aborted) {
+            return aborted;
+        }
+        try {
+            const entries = await readdir(resolved, { withFileTypes: true });
+            const infos = [];
+            for (const entry of entries) {
+                const loopAbort = abortResult(abortSignal, resolved);
+                if (loopAbort) {
+                    return loopAbort;
+                }
+                const entryPath = resolve(resolved, entry.name);
+                try {
+                    const info = fileInfoFromStats(entryPath, await lstat(entryPath));
+                    if (info.ok) {
+                        infos.push(info.value);
+                    }
+                }
+                catch (error) {
+                    return err(toFileError(error, entryPath));
+                }
+            }
+            return ok(infos);
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
+    async canonicalPath(path) {
+        const resolved = resolvePath(this.cwd, path);
+        try {
+            return ok(await realpath(resolved));
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
+    async readLink(path) {
+        const resolved = resolvePath(this.cwd, path);
+        try {
+            return ok(await readlink(resolved));
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
+    async exists(path) {
+        const result = await this.fileInfo(path);
+        if (result.ok) {
+            return ok(true);
+        }
+        if (result.error.code === "not_found") {
+            return ok(false);
+        }
+        return err(result.error);
+    }
+    async createDir(path, options) {
+        const resolved = resolvePath(this.cwd, path);
+        try {
+            await mkdir(resolved, { recursive: options?.recursive ?? true });
+            return ok(undefined);
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
+    async remove(path, options) {
+        const resolved = resolvePath(this.cwd, path);
+        try {
+            await rm(resolved, {
+                recursive: options?.recursive ?? false,
+                force: options?.force ?? false,
+            });
+            return ok(undefined);
+        }
+        catch (error) {
+            return err(toFileError(error, resolved));
+        }
+    }
+    async createTempDir(prefix = "tmp-") {
+        try {
+            return ok(await mkdtemp(join(tmpdir(), prefix)));
+        }
+        catch (error) {
+            return err(toFileError(error));
+        }
+    }
+    async createTempFile(options) {
+        const dir = await this.createTempDir("tmp-");
+        if (!dir.ok) {
+            return dir;
+        }
+        const filePath = join(dir.value, `${options?.prefix ?? ""}${randomUUID()}${options?.suffix ?? ""}`);
+        try {
+            await writeFile(filePath, "");
+            return ok(filePath);
+        }
+        catch (error) {
+            return err(toFileError(error, filePath));
+        }
+    }
+    adoptRunningChild(child, stdoutSoFar, stderrSoFar) {
+        const liveCount = [...this.bgShells.values()].filter((e) => e.status === "running").length;
+        if (liveCount >= this.backgroundCapabilities.maxConcurrent)
+            return undefined;
+        const shellId = `bg_${++this.bgCounter}_${randomUUID()}`;
+        const entry = {
+            child,
+            stdout: { tail: new RollingTailBuffer(), totalBytes: 0, cursorBytes: 0 },
+            stderr: { tail: new RollingTailBuffer(), totalBytes: 0, cursorBytes: 0 },
+            status: "running",
+        };
+        const seedOut = Buffer.from(stdoutSoFar, "utf8");
+        const seedErr = Buffer.from(stderrSoFar, "utf8");
+        entry.stdout.tail.push(seedOut);
+        entry.stdout.totalBytes += seedOut.length;
+        entry.stderr.tail.push(seedErr);
+        entry.stderr.totalBytes += seedErr.length;
+        child.stdout?.on("data", (chunk) => {
+            const buf = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+            entry.stdout.tail.push(buf);
+            entry.stdout.totalBytes += buf.length;
+        });
+        child.stderr?.on("data", (chunk) => {
+            const buf = typeof chunk === "string" ? Buffer.from(chunk, "utf8") : chunk;
+            entry.stderr.tail.push(buf);
+            entry.stderr.totalBytes += buf.length;
+        });
+        child.on("error", () => {
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            if (entry.status === "running")
+                entry.status = "failed";
+        });
+        child.on("close", (code, signal) => {
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            if (entry.status === "killed")
+                return;
+            entry.status = "exited";
+            entry.exitCode = code === null && signal ? 128 + (SIGNUM[signal] ?? 9) : (code ?? 0);
+        });
+        if (child.exitCode !== null || child.signalCode !== null) {
+            entry.status = "exited";
+            entry.exitCode = child.exitCode ?? (child.signalCode ? 128 + (SIGNUM[child.signalCode] ?? 9) : 0);
+        }
+        else {
+            const timeoutSec = this.backgroundCapabilities.defaultBgTimeoutSec;
+            entry.timer = setTimeout(() => {
+                entry.status = "killed";
+                if (child.pid)
+                    killProcessTree(child.pid, { force: true });
+            }, timeoutSec * 1000);
+            entry.timer.unref?.();
+        }
+        this.bgShells.set(shellId, entry);
+        return shellId;
+    }
+    async spawnBackground(command, options) {
+        const liveCount = [...this.bgShells.values()].filter((e) => e.status === "running").length;
+        if (liveCount >= this.backgroundCapabilities.maxConcurrent) {
+            return err(new BackgroundShellError("limit_exceeded", `Too many running background shells (max ${this.backgroundCapabilities.maxConcurrent}); TaskStop one first.`));
+        }
+        const shellConfig = await getShellConfig(this.shellPath);
+        if (!shellConfig.ok) {
+            return err(new BackgroundShellError("spawn_failed", shellConfig.error.message, shellConfig.error));
+        }
+        let spool;
+        let spoolFds;
+        if (this.retainBackgroundProcesses) {
+            try {
+                if (!this.bgSpoolDir)
+                    this.bgSpoolDir = mkdtempSync(join(tmpdir(), "sema-bg-"));
+                const pair = openSpoolPair(join(this.bgSpoolDir, `bg_${this.bgCounter + 1}_${randomUUID()}`));
+                spool = { outPath: pair.outPath, errPath: pair.errPath };
+                spoolFds = pair.fds;
+            }
+            catch {
+                spool = undefined;
+                spoolFds = undefined;
+            }
+        }
+        let child;
+        try {
+            child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
+                cwd: options?.cwd ? resolvePath(this.cwd, options.cwd) : this.cwd,
+                detached: process.platform !== "win32",
+                env: getShellEnv(this.inheritEnv, this.shellEnv, options?.env),
+                stdio: spoolFds ? ["ignore", spoolFds[0], spoolFds[1]] : ["ignore", "pipe", "pipe"],
+                windowsHide: true,
+            });
+        }
+        catch (error) {
+            if (spoolFds) {
+                for (const fd of spoolFds) {
+                    try {
+                        closeSync(fd);
+                    }
+                    catch {
+                    }
+                }
+            }
+            const cause = toError(error);
+            return err(new BackgroundShellError("spawn_failed", cause.message, cause));
+        }
+        if (spoolFds) {
+            for (const fd of spoolFds) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                }
+            }
+        }
+        const shellId = `bg_${++this.bgCounter}_${randomUUID()}`;
+        const entry = {
+            child,
+            stdout: { tail: new RollingTailBuffer(), totalBytes: 0, cursorBytes: 0 },
+            stderr: { tail: new RollingTailBuffer(), totalBytes: 0, cursorBytes: 0 },
+            status: "running",
+            ...(spool ? { spool } : {}),
+        };
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            const buf = Buffer.from(chunk, "utf8");
+            entry.stdout.tail.push(buf);
+            entry.stdout.totalBytes += buf.length;
+        });
+        child.stderr?.on("data", (chunk) => {
+            const buf = Buffer.from(chunk, "utf8");
+            entry.stderr.tail.push(buf);
+            entry.stderr.totalBytes += buf.length;
+        });
+        child.stdout?.on("error", () => { });
+        child.stderr?.on("error", () => { });
+        child.on("error", () => {
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            if (entry.status === "running")
+                entry.status = "failed";
+        });
+        child.on("close", (code, signal) => {
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            if (entry.status === "killed")
+                return;
+            entry.status = "exited";
+            entry.exitCode = code === null && signal ? 128 + (SIGNUM[signal] ?? 9) : (code ?? 0);
+        });
+        const timeoutSec = Math.min(options?.timeout ?? this.backgroundCapabilities.defaultBgTimeoutSec, this.backgroundCapabilities.maxBgTimeoutSec);
+        entry.timer = setTimeout(() => {
+            if (child.pid && entry.status === "running") {
+                entry.status = "killed";
+                killProcessTree(child.pid, { force: true });
+            }
+        }, timeoutSec * 1000);
+        entry.timer.unref?.();
+        this.bgShells.set(shellId, entry);
+        return ok({ shellId });
+    }
+    async pollBackground(shellId) {
+        const entry = this.bgShells.get(shellId);
+        if (!entry) {
+            return err(new BackgroundShellError("not_found", `Unknown background shell: ${shellId}`));
+        }
+        this.syncSpool(entry);
+        const slice = (s) => {
+            const { text, droppedBytes } = s.tail.result();
+            const droppedBeforeCursor = Math.max(0, droppedBytes - s.cursorBytes);
+            const startByte = Math.max(s.cursorBytes, droppedBytes);
+            const startInTail = startByte - droppedBytes;
+            const inc = startInTail <= 0 ? text : Buffer.from(text, "utf8").subarray(startInTail).toString("utf8");
+            s.cursorBytes = s.totalBytes;
+            return { inc, droppedBeforeCursor };
+        };
+        const out = slice(entry.stdout);
+        const er = slice(entry.stderr);
+        const droppedBeforeCursor = out.droppedBeforeCursor + er.droppedBeforeCursor;
+        return ok({
+            stdout: out.inc,
+            stderr: er.inc,
+            status: entry.status,
+            ...(entry.exitCode !== undefined ? { exitCode: entry.exitCode } : {}),
+            ...(droppedBeforeCursor > 0 ? { truncated: true, bytesDroppedBeforeCursor: droppedBeforeCursor } : {}),
+            bytesFromStart: entry.stdout.totalBytes + entry.stderr.totalBytes,
+        });
+    }
+    async killBackground(shellId) {
+        const entry = this.bgShells.get(shellId);
+        if (!entry) {
+            return err(new BackgroundShellError("not_found", `Unknown background shell: ${shellId}`));
+        }
+        if (entry.status === "running" && entry.child.pid) {
+            entry.status = "killed";
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            killProcessTree(entry.child.pid, { force: true });
+        }
+        return ok(undefined);
+    }
+    syncSpool(entry) {
+        if (!entry.spool)
+            return;
+        const streams = [
+            [entry.stdout, entry.spool.outPath],
+            [entry.stderr, entry.spool.errPath],
+        ];
+        for (const [stream, path] of streams) {
+            try {
+                const size = statSync(path).size;
+                if (size <= stream.totalBytes)
+                    continue;
+                const fd = openSync(path, "r");
+                try {
+                    const want = Math.min(size - stream.totalBytes, 8 * 1024 * 1024 + 4096);
+                    const buf = Buffer.alloc(want);
+                    const got = readSync(fd, buf, 0, want, stream.totalBytes);
+                    if (got > 0) {
+                        stream.tail.push(buf.subarray(0, got));
+                        stream.totalBytes += got;
+                    }
+                }
+                finally {
+                    closeSync(fd);
+                }
+            }
+            catch {
+            }
+        }
+    }
+    async disposeBackgroundShells(opts) {
+        if (this.retainBackgroundProcesses)
+            return;
+        const keep = opts?.except !== undefined && opts.except.length > 0 ? new Set(opts.except) : undefined;
+        for (const [id, entry] of this.bgShells) {
+            if (keep?.has(id))
+                continue;
+            try {
+                if (entry.timer)
+                    clearTimeout(entry.timer);
+                if (entry.status === "running" && entry.child.pid) {
+                    entry.status = "killed";
+                    killProcessTree(entry.child.pid, { force: true });
+                }
+            }
+            catch {
+            }
+            if (keep !== undefined)
+                this.bgShells.delete(id);
+        }
+        if (keep === undefined)
+            this.bgShells.clear();
+    }
+    async cleanup() {
+        await this.disposeBackgroundShells();
+    }
+}
+//# sourceMappingURL=node-execution-env.js.map