@sema-ai/core 1.275.1

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

@@ -0,0 +1,1031 @@
+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";
+// Naturalized (design/71 P2, design/103): the secret-env scrubber + the exec output-tail bound are first-party
+// (src/core/{secret-env,exec-output-tail}.ts) — the canonical homes. This naturalized env consumes them (single source).
+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);
+}
+/** Convert user-facing timeout seconds into a positive, timer-safe millisecond delay. */
+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({
+        // [K-PLATFORM-SWEEP] MAJOR#4: dual-family basename — a win32 native path is backslash-form, and the
+        // "/"-only split returned the WHOLE absolute path as `name` (ignoreDirs/name matching all broke).
+        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;
+        });
+        // Upstream-parity fix (2026-07 diff, openclaw e779abf70e class): a stream-level error (e.g. EPIPE)
+        // on an un-listened stdio stream is an UNCAUGHT exception that crashes the host process. Swallow it;
+        // the child's own error/close handlers still settle the promise.
+        child.stdout?.on("error", () => { });
+        child.on("error", () => {
+            clearTimeout(timeout);
+            resolveLocal({ stdout: "", status: null });
+        });
+        child.on("close", (status) => {
+            clearTimeout(timeout);
+            resolveLocal({ stdout, status });
+        });
+    });
+}
+/** service [377] review finding (win32): `where bash.exe` can resolve to `System32\bash.exe` — the
+ *  WSL LAUNCHER, not a native shell. Running it drops into a Linux subsystem where Windows cwd/paths
+ *  do not exist; silently adopting it is exactly the "wrong shell, false green" failure D1 forbids.
+ *  Filter it (and the WindowsApps alias) out of PATH discovery; Git-Bash candidates are tried first. */
+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;
+}
+/** Shell discovery for the platform (service [377] ask ①: exported as the single SDK source so a host
+ *  adapter does not mirror the platform logic). Explicit `customShellPath` wins (missing → err);
+ *  win32 = Git-Bash discovery (ProgramFiles → PATH, WSL launcher filtered) with fail-loud
+ *  `shell_unavailable` (never a silent cmd.exe fallback); POSIX = /bin/bash → PATH bash → sh. */
+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"] });
+}
+// VENDORED EDIT (D2, naturalized): the per-stream rolling-TAIL output bound was extracted to the first-party
+// `src/core/exec-output-tail.ts` (canonical, vendor-independent — OUR robustness invariant, shared with a
+// downstream exec adapter [267], survives de-vendoring). This (temporary) vendored env CONSUMES it. The first-
+// party `bash` tool calls `exec` with NO onStdout/onStderr, so a `cat big.bin | base64` / `yes` would otherwise
+// grow the durable worker heap to the full output within the 120s/600s timeout — RollingTailBuffer keeps the tail.
+/** VENDORED EDIT (D5): grace window to FORCE-settle an exec whose `close` never fires after a kill (a re-parented
+ *  grandchild holding the stdout pipe / a D-state process) so an abort/timeout the engine requested can finalize. */
+const EXEC_FORCE_SETTLE_GRACE_MS = 3000;
+/** VENDORED EDIT (sema vendored bug-hunt D1, security): env keys whose VALUE is a secret a model-driven shell
+ *  must not read. Matched on the trailing segment so `DEEPSEEK_API_KEY`/`GIT_API_TOKEN`/`AWS_SECRET_ACCESS_KEY`/
+ *  `*_PASSWORD` are dropped while `API_BASE_URL`/`ANDROID_HOME`/`NODE_ENV`/`SSH_AUTH_SOCK` are kept (low breakage). */
+// VENDORED EDIT (D1, naturalized): the secret-env PATTERN + scrubber were extracted to the first-party
+// `src/core/secret-env.ts` (the canonical, vendor-independent home — it is OUR security invariant, shared with a
+// downstream host adapter [265], and must survive the planned de-vendoring). This (temporary) vendored env just
+// CONSUMES it, so there is a single source of the pattern with zero drift.
+/**
+ * VENDORED EDIT (sema vendored bug-hunt D1, security/DRAG): the harness was distilled from CC's INTERACTIVE model
+ * where the human owns the env; in our AUTONOMOUS model a model-chosen `printenv DEEPSEEK_API_KEY` via the `bash`
+ * tool would otherwise exfiltrate the orchestrator's brain key / git token / DB creds (the gate authorizes WHICH
+ * tool runs, NOT isolation). So the shell child's env is FAIL-CLOSED by default: `scrub` drops secret-pattern keys
+ * (keeps PATH/build/locale vars → low breakage). `inheritEnv:"all"` is the explicit opt-out (e.g. a trusted local
+ * dev); a `string[]` is a strict allowlist. `baseEnv`/`extraEnv` (caller-supplied) always pass through verbatim.
+ */
+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); // default "scrub"
+    }
+    return {
+        ...inherited,
+        ...baseEnv,
+        ...extraEnv,
+    };
+}
+/** Node-backed execution environment for agent harness filesystem and shell operations. */
+/** Signal name → number, to encode a signal-terminated exit as 128+signum (shell convention; shared with exec). */
+const SIGNUM = { SIGHUP: 1, SIGINT: 2, SIGQUIT: 3, SIGABRT: 6, SIGKILL: 9, SIGSEGV: 11, SIGPIPE: 13, SIGTERM: 15 };
+/** design/128 T1-1 / codex 1.236 复审 R2: open the spool file pair ALL-OR-NOTHING — a failure opening the
+ *  second file must close the first fd before rethrowing (the caller's catch only clears its references, so
+ *  a half-open pair would leak fdOut for the env's lifetime). `wx` + 0600 (never follow / never reuse an
+ *  existing path). Exported for direct fault-injection tests (pre-create a path → EEXIST). */
+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 {
+            /* best-effort */
+        }
+        throw e;
+    }
+    return { outPath, errPath, fds: [fdOut, fdErr] };
+}
+export class NodeExecutionEnv {
+    cwd;
+    shellPath;
+    shellEnv;
+    inheritEnv;
+    // design/105: optional injected scheduler daemon backend (the flywheel's shell daemon). Absent ⇒ INERT.
+    scheduler;
+    // design/103: background-shell registry — env-local, non-durable. The shellId is opaque; poll/kill only accept ids
+    // THIS env minted (越权隔离 = Map membership; a forged/cross-tenant id resolves to not_found).
+    bgShells = new Map();
+    bgCounter = 0;
+    retainBackgroundProcesses;
+    /** design/128 T1-1: lazily-created env-owned spool dir (mkdtemp under os tmp — unpredictable, never the cwd). */
+    bgSpoolDir;
+    // Assigned in the constructor (not a field literal) so the T1-1 retain declaration can surface on the
+    // capability face — the registry's teardown sweeps gate their kills on it (TB 2026-07-08 regression).
+    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, // 30 min
+            maxBgTimeoutSec: 2 * 60 * 60, // 2h hard ceiling — never unbounded (design/103 §3.6)
+            supportsDetach: true, // design/116 detach: a running foreground exec can be adopted as a background shell
+            retainBackgroundProcesses: this.retainBackgroundProcesses, // design/128 T1-1 — see BackgroundShellCapability
+        };
+    }
+    // ── design/105 SchedulerCapability: pure delegation to the injected daemon backend (core holds no scheduler
+    //    state — no store, no clock, no trigger). No backend ⇒ supported:false ⇒ `hasScheduler` false ⇒ tools unmounted.
+    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(); // D2: bounded rolling tail (first-party src/core/exec-output-tail)
+            const stderrTail = new RollingTailBuffer();
+            let settled = false;
+            let timedOut = false;
+            let callbackError;
+            let child;
+            const timeoutRef = {};
+            const forceSettleRef = {}; // D5
+            // D5: after a kill (abort/timeout), `close` may never fire (a re-parented grandchild holds the pipe). Arm a
+            // bounded fallback that force-settles + tears down the pipes so the engine's requested abort/timeout always
+            // finalizes. Idempotent: `settle` guards `settled`, so a real `close` arriving first wins.
+            const armForceSettle = (result) => {
+                if (forceSettleRef.current || settled)
+                    return;
+                forceSettleRef.current = setTimeout(() => {
+                    try {
+                        child?.stdout?.destroy();
+                        child?.stderr?.destroy();
+                    }
+                    catch {
+                        /* best-effort pipe teardown */
+                    }
+                    settle(result);
+                }, EXEC_FORCE_SETTLE_GRACE_MS);
+                forceSettleRef.current.unref?.();
+            };
+            const onAbort = () => {
+                if (child?.pid) {
+                    killProcessTree(child.pid, { force: true });
+                }
+                armForceSettle(err(new ExecutionError("aborted", "aborted")));
+            };
+            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}`))); // D5
+                    }, timeoutMs);
+            if (options?.abortSignal) {
+                if (options.abortSignal.aborted) {
+                    onAbort();
+                }
+                else {
+                    options.abortSignal.addEventListener("abort", onAbort, { once: true });
+                }
+            }
+            // design/116 detach (飞轮 [C] gap ③): mid-flight ctrl+b — ADOPT the running child as a background
+            // shell instead of killing it. The exec settles with a `detached` marker (already-captured output
+            // included); ownership (data listeners → bg tails, close handling, bg timeout, kill) moves to the
+            // bgShells entry. The child handle NEVER leaves this env. Fired after `settled` → ignored (too late).
+            const onDetach = () => {
+                if (settled || !child)
+                    return;
+                const shellId = this.adoptRunningChild(child, stdoutTail.result().text, stderrTail.result().text);
+                if (shellId === undefined)
+                    return; // over the live-shell limit — detach refused, exec keeps running
+                // Exec's kill paths must no longer touch the adopted process: drop timeout + abort ownership.
+                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 });
+                    // remove on settle happens implicitly: a once listener on a signal that never fires is harmless.
+                }
+            }
+            // Keep `setEncoding("utf8")` so the streaming onStdout/onStderr callbacks still get correctly-decoded
+            // STRING chunks (Node's StringDecoder buffers incomplete sequences across data events); feed the byte form
+            // to the rolling tail (D2). `Buffer.from(completeString)` is split-safe — each `chunk` is already a whole
+            // decoded string, so the only multi-byte split is at the tail-trim boundary (harmless, marked truncated).
+            child.stdout?.setEncoding("utf8");
+            child.stderr?.setEncoding("utf8");
+            child.stdout?.on("data", (chunk) => {
+                stdoutTail.push(Buffer.from(chunk, "utf8")); // D2: keep a rolling TAIL, never OOM
+                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();
+                }
+            });
+            // Upstream-parity fix (2026-07 diff, openclaw e779abf70e class): child.stdout/stderr are streams
+            // with their OWN error events (e.g. EPIPE) — without a listener a stream error is an uncaught
+            // exception that crashes the host process. Swallow: the child's close event still settles the exec
+            // with whatever output was captured (and a signal-encoded exit code when the child died).
+            child.stdout?.on("error", () => { });
+            child.stderr?.on("error", () => { });
+            child.on("error", (error) => {
+                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}`)));
+                    return;
+                }
+                if (options?.abortSignal?.aborted) {
+                    settle(err(new ExecutionError("aborted", "aborted")));
+                    return;
+                }
+                // VENDORED EDIT (audit round-2 A-3): a signal-terminated child (OOM SIGKILL, SIGSEGV, external
+                // kill) reports `(code=null, signal=...)` — the old `code ?? 0` translated that into a SUCCESS
+                // with half an output, and the model advanced on a fake green (e.g. "tests passed"). Report the
+                // conventional shell encoding instead: 128 + signal number (best-effort 137 for unknown names),
+                // with the signal name appended to stderr so the model sees WHY.
+                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 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));
+        }
+    }
+    // VENDORED EDIT (design/72 §2.1): one-hop symlink target read (raw, not followed), so a guard can
+    // resolve a DANGLING leaf symlink that `realpath`/`canonicalPath` cannot.
+    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));
+        }
+    }
+    // ─── design/103 background-shell capability ─────────────────────────────────────────────────────────────────
+    /** design/116 detach: adopt a RUNNING foreground child as a background shell. Pre-fills the bg tails with
+     *  the output captured so far (so TaskOutput's first read has the full history), attaches fresh data/close
+     *  handlers, and arms the default bg timeout. Returns undefined when the live-shell limit is hit (detach
+     *  refused; the exec keeps running in the foreground). */
+    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);
+        });
+        // Race guard: the child may have ALREADY exited between the detach request and adoption.
+        if (child.exitCode !== null || child.signalCode !== null) {
+            entry.status = "exited";
+            entry.exitCode = child.exitCode ?? (child.signalCode ? 128 + (SIGNUM[child.signalCode] ?? 9) : 0);
+        }
+        else {
+            // Default bg timeout takes over from the (cleared) exec timeout — never unbounded (design/103 §3.6).
+            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) {
+        // Count only LIVE (running) shells against the limit — terminal entries are KEPT for post-exit polling but must
+        // NOT wedge the limit (review: maxConcurrent 终态占槽). TaskStop flips a shell to "killed" → frees its slot, so
+        // the "TaskStop one first" guidance is actionable.
+        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));
+        }
+        // design/128 T1-1 (retain): spool stdio to env-owned temp files so the child never depends on a host
+        // pipe (host exit ⇒ no EPIPE). Unpredictable mkdtemp path + `wx` + 0600 (never the cwd — a workspace
+        // symlink must not redirect the spool; same posture as the frozen-path restore hardening). On any spool
+        // failure fall back to pipes: the process still won't be disposed, just with best-effort stdio.
+        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; // fall back to pipes: still not disposed, just best-effort stdio
+                spoolFds = undefined;
+            }
+        }
+        let child;
+        try {
+            child = spawn(shellConfig.value.shell, [...shellConfig.value.args, command], {
+                // Resolve a relative cwd against the env root, same as exec (review: cwd parity) — the Bash tool passes an
+                // absolute cwdRef.current, but a direct API caller may pass a relative path.
+                cwd: options?.cwd ? resolvePath(this.cwd, options.cwd) : this.cwd,
+                // detached:true (own process group on Unix) so disposeBackgroundShells' killProcessTree group-kills the whole
+                // tree — the dev-server's esbuild/worker grandchildren die too (design/103 §5.1; same as exec's spawn).
+                detached: process.platform !== "win32",
+                // SAME secret-scrub as exec (design/103 §3.1 red line): the background child must NOT read SECRET_* keys.
+                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 {
+                        /* best-effort */
+                    }
+                }
+            }
+            const cause = toError(error);
+            return err(new BackgroundShellError("spawn_failed", cause.message, cause));
+        }
+        // The child holds its own dup of the spool fds — release the parent's handles immediately.
+        if (spoolFds) {
+            for (const fd of spoolFds) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    /* best-effort */
+                }
+            }
+        }
+        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;
+        });
+        // Upstream-parity fix (2026-07 diff, openclaw e779abf70e class, swept to the bg-shell pipe path):
+        // un-listened stream errors (EPIPE) crash the host — swallow; close still classifies the entry.
+        child.stdout?.on("error", () => { });
+        child.stderr?.on("error", () => { });
+        child.on("error", () => {
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            if (entry.status === "running")
+                entry.status = "failed";
+        });
+        // Drive terminal status off "close" (fires AFTER all stdio EOF), NOT "exit" — so the final buffered output has
+        // landed in the tail before the model is told the process ended (review: exit 先于 stdout drain 漏残余).
+        child.on("close", (code, signal) => {
+            if (entry.timer)
+                clearTimeout(entry.timer);
+            if (entry.status === "killed")
+                return; // killBackground / timeout already classified it
+            entry.status = "exited";
+            entry.exitCode = code === null && signal ? 128 + (SIGNUM[signal] ?? 9) : (code ?? 0);
+        });
+        // BG timeout is a HARD wall (design/103 §3.6): bounded to maxBgTimeoutSec, never unbounded.
+        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) {
+            // unknown / cross-env id → not_found (never leak whether another env's id exists, design/103 §3.8).
+            return err(new BackgroundShellError("not_found", `Unknown background shell: ${shellId}`));
+        }
+        this.syncSpool(entry); // design/128 T1-1: retain mode — fold spool-file increments into the tails first
+        // Cursor over ABSOLUTE byte offsets. The tail retains bytes [droppedBytes, totalBytes); return [cursor, total).
+        // NOTE: the tail is decoded to text then re-encoded for the byte slice, so if a head-evict split a multi-byte char
+        // the orphan bytes decode to U+FFFD (3 bytes each) — the single poll spanning that evict may show a few garbled or
+        // duplicated bytes at its head. Only when output exceeds the 8MB tail; bounded + rare (honest-marked downstream).
+        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 }); // group-kill the whole tree (detached → own pgid)
+        }
+        return ok(undefined); // idempotent: killing an already-dead shell is a no-op success
+    }
+    /** design/128 T1-1: incrementally read a retained shell's spool files into the in-memory tails, so
+     *  pollBackground serves the same cursor semantics whether stdio came over pipes or spool files.
+     *  Bounded single read per stream per poll (the tail keeps only its rolling window anyway). */
+    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); // ≥ tail window per poll
+                    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 {
+                // spool unreadable (deleted / permissions) — the poll serves whatever the tail already has
+            }
+        }
+    }
+    async disposeBackgroundShells(opts) {
+        // design/128 T1-1: a retain-declared env NEVER auto-reaps — the runner's every-exit-path dispose and
+        // cleanup() both land here, so this single gate is the whole retain semantic. Explicit killBackground
+        // and the per-shell bg-timeout reaper still work while the host lives.
+        if (this.retainBackgroundProcesses)
+            return;
+        // 飞轮 [492]②: `except` shells (session-resident persistent Monitors) survive the run teardown —
+        // entry AND timer kept intact so pollBackground/killBackground/the bg-timeout reaper keep working.
+        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 {
+                // best-effort; disposeBackgroundShells MUST never throw (design/103 §3.7).
+            }
+            if (keep !== undefined)
+                this.bgShells.delete(id);
+        }
+        if (keep === undefined)
+            this.bgShells.clear();
+    }
+    async cleanup() {
+        // Release any still-running background processes. The Runner also disposes on every exit path (design/103 §3.7),
+        // but cleanup is ExecutionEnv's resource-release contract, so honour it here too (idempotent backstop).
+        await this.disposeBackgroundShells();
+    }
+}
+//# sourceMappingURL=node-execution-env.js.map