@poolzin/pool-bot 2026.2.21 → 2026.2.22

package/dist/agents/bash-tools.exec.js

@@ -1,571 +1,98 @@
 import crypto from "node:crypto";
+import fs from "node:fs/promises";
 import path from "node:path";
-import { Type } from "@sinclair/typebox";
-import { addAllowlistEntry, evaluateShellAllowlist, maxAsk, minSecurity, requiresExecApproval, resolveSafeBins, recordAllowlistUse, resolveExecApprovals, resolveExecApprovalsFromFile, } from "../infra/exec-approvals.js";
-import { requestHeartbeatNow } from "../infra/heartbeat-wake.js";
+import { addAllowlistEntry, evaluateShellAllowlist, maxAsk, minSecurity, requiresExecApproval, resolveSafeBins, recordAllowlistUse, resolveExecApprovals, resolveExecApprovalsFromFile, buildSafeShellCommand, buildSafeBinsShellCommand, } from "../infra/exec-approvals.js";
 import { buildNodeShellCommand } from "../infra/node-shell.js";
 import { getShellPathFromLoginShell, resolveShellEnvFallbackTimeoutMs, } from "../infra/shell-env.js";
-import { enqueueSystemEvent } from "../infra/system-events.js";
-import { logInfo, logWarn } from "../logger.js";
-import { formatSpawnError, spawnWithFallback } from "../process/spawn-utils.js";
-import { addSession, appendOutput, createSessionSlug, markBackgrounded, markExited, tail, } from "./bash-process-registry.js";
-import { buildDockerExecArgs, buildSandboxEnv, chunkString, clampNumber, coerceEnv, killSession, readEnvInt, resolveSandboxWorkdir, resolveWorkdir, truncateMiddle, } from "./bash-tools.shared.js";
+import { logInfo } from "../logger.js";
+import { parseAgentSessionKey, resolveAgentIdFromSessionKey } from "../routing/session-key.js";
+import { markBackgrounded, tail } from "./bash-process-registry.js";
+import { DEFAULT_APPROVAL_REQUEST_TIMEOUT_MS, DEFAULT_APPROVAL_TIMEOUT_MS, DEFAULT_MAX_OUTPUT, DEFAULT_NOTIFY_TAIL_CHARS, DEFAULT_PATH, DEFAULT_PENDING_MAX_OUTPUT, applyPathPrepend, applyShellPath, createApprovalSlug, emitExecSystemEvent, normalizeExecAsk, normalizeExecHost, normalizeExecSecurity, normalizeNotifyOutput, normalizePathPrepend, renderExecHostLabel, resolveApprovalRunningNoticeMs, runExecProcess, execSchema, validateHostEnv, } from "./bash-tools.exec-runtime.js";
+import { buildSandboxEnv, clampWithDefault, coerceEnv, readEnvInt, resolveSandboxWorkdir, resolveWorkdir, truncateMiddle, } from "./bash-tools.shared.js";
 import { callGatewayTool } from "./tools/gateway.js";
 import { listNodes, resolveNodeIdFromList } from "./tools/nodes-utils.js";
-import { getShellConfig, sanitizeBinaryOutput } from "./shell-utils.js";
-import { buildCursorPositionResponse, stripDsrRequests } from "./pty-dsr.js";
-import { parseAgentSessionKey, resolveAgentIdFromSessionKey } from "../routing/session-key.js";
-// Security: Blocklist of environment variables that could alter execution flow
-// or inject code when running on non-sandboxed hosts (Gateway/Node).
-const DANGEROUS_HOST_ENV_VARS = new Set([
-    "LD_PRELOAD",
-    "LD_LIBRARY_PATH",
-    "LD_AUDIT",
-    "DYLD_INSERT_LIBRARIES",
-    "DYLD_LIBRARY_PATH",
-    "NODE_OPTIONS",
-    "NODE_PATH",
-    "PYTHONPATH",
-    "PYTHONHOME",
-    "RUBYLIB",
-    "PERL5LIB",
-    "BASH_ENV",
-    "ENV",
-    "GCONV_PATH",
-    "IFS",
-    "SSLKEYLOGFILE",
-]);
-const DANGEROUS_HOST_ENV_PREFIXES = ["DYLD_", "LD_"];
-// Centralized sanitization helper.
-// Throws an error if dangerous variables or PATH modifications are detected on the host.
-function validateHostEnv(env) {
-    for (const key of Object.keys(env)) {
-        const upperKey = key.toUpperCase();
-        // 1. Block known dangerous variables (Fail Closed)
-        if (DANGEROUS_HOST_ENV_PREFIXES.some((prefix) => upperKey.startsWith(prefix))) {
-            throw new Error(`Security Violation: Environment variable '${key}' is forbidden during host execution.`);
-        }
-        if (DANGEROUS_HOST_ENV_VARS.has(upperKey)) {
-            throw new Error(`Security Violation: Environment variable '${key}' is forbidden during host execution.`);
-        }
-        // 2. Strictly block PATH modification on host
-        // Allowing custom PATH on the gateway/node can lead to binary hijacking.
-        if (upperKey === "PATH") {
-            throw new Error("Security Violation: Custom 'PATH' variable is forbidden during host execution.");
-        }
-    }
-}
-const DEFAULT_MAX_OUTPUT = clampNumber(readEnvInt("PI_BASH_MAX_OUTPUT_CHARS"), 200_000, 1_000, 200_000);
-const DEFAULT_PENDING_MAX_OUTPUT = clampNumber(readEnvInt("POOLBOT_BASH_PENDING_MAX_OUTPUT_CHARS") ??
-    readEnvInt("CLAWDBOT_BASH_PENDING_MAX_OUTPUT_CHARS"), 200_000, 1_000, 200_000);
-// Default exec timeout: 1800s (30 min) to accommodate long installs/builds.
-// Users can override via config (`tools.exec.timeoutSec`) or env var.
-const DEFAULT_EXEC_TIMEOUT_SEC = clampNumber(readEnvInt("POOLBOT_EXEC_TIMEOUT_SEC") ?? readEnvInt("CLAWDBOT_EXEC_TIMEOUT_SEC"), 1800, 1, 86_400);
-const DEFAULT_PATH = process.env.PATH ?? "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin";
-const DEFAULT_NOTIFY_TAIL_CHARS = 400;
-const DEFAULT_APPROVAL_TIMEOUT_MS = 120_000;
-const DEFAULT_APPROVAL_REQUEST_TIMEOUT_MS = 130_000;
-const DEFAULT_APPROVAL_RUNNING_NOTICE_MS = 10_000;
-const APPROVAL_SLUG_LENGTH = 8;
-const execSchema = Type.Object({
-    command: Type.String({ description: "Shell command to execute" }),
-    workdir: Type.Optional(Type.String({ description: "Working directory (defaults to cwd)" })),
-    env: Type.Optional(Type.Record(Type.String(), Type.String())),
-    yieldMs: Type.Optional(Type.Number({
-        description: "Milliseconds to wait before backgrounding (default 10000)",
-    })),
-    background: Type.Optional(Type.Boolean({ description: "Run in background immediately" })),
-    timeout: Type.Optional(Type.Number({
-        description: "Timeout in seconds (default 1800, kills process on expiry).",
-    })),
-    pty: Type.Optional(Type.Boolean({
-        description: "Run in a pseudo-terminal (PTY) when available (TTY-required CLIs, coding agents)",
-    })),
-    elevated: Type.Optional(Type.Boolean({
-        description: "Run on the host with elevated permissions (if allowed)",
-    })),
-    host: Type.Optional(Type.String({
-        description: "Exec host (sandbox|gateway|node).",
-    })),
-    security: Type.Optional(Type.String({
-        description: "Exec security mode (deny|allowlist|full).",
-    })),
-    ask: Type.Optional(Type.String({
-        description: "Exec ask mode (off|on-miss|always).",
-    })),
-    node: Type.Optional(Type.String({
-        description: "Node id/name for host=node.",
-    })),
-});
-function normalizeExecHost(value) {
-    const normalized = value?.trim().toLowerCase();
-    if (normalized === "sandbox" || normalized === "gateway" || normalized === "node") {
-        return normalized;
+function extractScriptTargetFromCommand(command) {
+    const raw = command.trim();
+    if (!raw) {
+        return null;
     }
-    return null;
-}
-function normalizeExecSecurity(value) {
-    const normalized = value?.trim().toLowerCase();
-    if (normalized === "deny" || normalized === "allowlist" || normalized === "full") {
-        return normalized;
+    // Intentionally simple parsing: we only support common forms like
+    //   python file.py
+    //   python3 -u file.py
+    //   node --experimental-something file.js
+    // If the command is more complex (pipes, heredocs, quoted paths with spaces), skip preflight.
+    const pythonMatch = raw.match(/^\s*(python3?|python)\s+(?:-[^\s]+\s+)*([^\s]+\.py)\b/i);
+    if (pythonMatch?.[2]) {
+        return { kind: "python", relOrAbsPath: pythonMatch[2] };
     }
-    return null;
-}
-function normalizeExecAsk(value) {
-    const normalized = value?.trim().toLowerCase();
-    if (normalized === "off" || normalized === "on-miss" || normalized === "always") {
-        return normalized;
+    const nodeMatch = raw.match(/^\s*(node)\s+(?:--[^\s]+\s+)*([^\s]+\.js)\b/i);
+    if (nodeMatch?.[2]) {
+        return { kind: "node", relOrAbsPath: nodeMatch[2] };
     }
     return null;
 }
-function renderExecHostLabel(host) {
-    return host === "sandbox" ? "sandbox" : host === "gateway" ? "gateway" : "node";
-}
-function normalizeNotifyOutput(value) {
-    return value.replace(/\s+/g, " ").trim();
-}
-function normalizePathPrepend(entries) {
-    if (!Array.isArray(entries))
-        return [];
-    const seen = new Set();
-    const normalized = [];
-    for (const entry of entries) {
-        if (typeof entry !== "string")
-            continue;
-        const trimmed = entry.trim();
-        if (!trimmed || seen.has(trimmed))
-            continue;
-        seen.add(trimmed);
-        normalized.push(trimmed);
+async function validateScriptFileForShellBleed(params) {
+    const target = extractScriptTargetFromCommand(params.command);
+    if (!target) {
+        return;
     }
-    return normalized;
-}
-function mergePathPrepend(existing, prepend) {
-    if (prepend.length === 0)
-        return existing;
-    const partsExisting = (existing ?? "")
-        .split(path.delimiter)
-        .map((part) => part.trim())
-        .filter(Boolean);
-    const merged = [];
-    const seen = new Set();
-    for (const part of [...prepend, ...partsExisting]) {
-        if (seen.has(part))
-            continue;
-        seen.add(part);
-        merged.push(part);
+    const absPath = path.isAbsolute(target.relOrAbsPath)
+        ? path.resolve(target.relOrAbsPath)
+        : path.resolve(params.workdir, target.relOrAbsPath);
+    // Best-effort: only validate if file exists and is reasonably small.
+    let stat;
+    try {
+        stat = await fs.stat(absPath);
     }
-    return merged.join(path.delimiter);
-}
-function applyPathPrepend(env, prepend, options) {
-    if (prepend.length === 0)
-        return;
-    if (options?.requireExisting && !env.PATH)
-        return;
-    const merged = mergePathPrepend(env.PATH, prepend);
-    if (merged)
-        env.PATH = merged;
-}
-function applyShellPath(env, shellPath) {
-    if (!shellPath)
-        return;
-    const entries = shellPath
-        .split(path.delimiter)
-        .map((part) => part.trim())
-        .filter(Boolean);
-    if (entries.length === 0)
-        return;
-    const merged = mergePathPrepend(env.PATH, entries);
-    if (merged)
-        env.PATH = merged;
-}
-function maybeNotifyOnExit(session, status) {
-    if (!session.backgrounded || !session.notifyOnExit || session.exitNotified)
-        return;
-    const sessionKey = session.sessionKey?.trim();
-    if (!sessionKey)
+    catch {
         return;
-    session.exitNotified = true;
-    const exitLabel = session.exitSignal
-        ? `signal ${session.exitSignal}`
-        : `code ${session.exitCode ?? 0}`;
-    const output = normalizeNotifyOutput(tail(session.tail || session.aggregated || "", DEFAULT_NOTIFY_TAIL_CHARS));
-    const summary = output
-        ? `Exec ${status} (${session.id.slice(0, 8)}, ${exitLabel}) :: ${output}`
-        : `Exec ${status} (${session.id.slice(0, 8)}, ${exitLabel})`;
-    enqueueSystemEvent(summary, { sessionKey });
-    requestHeartbeatNow({ reason: `exec:${session.id}:exit` });
-}
-function createApprovalSlug(id) {
-    return id.slice(0, APPROVAL_SLUG_LENGTH);
-}
-function resolveApprovalRunningNoticeMs(value) {
-    if (typeof value !== "number" || !Number.isFinite(value)) {
-        return DEFAULT_APPROVAL_RUNNING_NOTICE_MS;
     }
-    if (value <= 0)
-        return 0;
-    return Math.floor(value);
-}
-function emitExecSystemEvent(text, opts) {
-    const sessionKey = opts.sessionKey?.trim();
-    if (!sessionKey)
+    if (!stat.isFile()) {
         return;
-    enqueueSystemEvent(text, { sessionKey, contextKey: opts.contextKey });
-    requestHeartbeatNow({ reason: "exec-event" });
-}
-async function runExecProcess(opts) {
-    const startedAt = Date.now();
-    const sessionId = createSessionSlug();
-    let child = null;
-    let pty = null;
-    let stdin;
-    if (opts.sandbox) {
-        const { child: spawned } = await spawnWithFallback({
-            argv: [
-                "docker",
-                ...buildDockerExecArgs({
-                    containerName: opts.sandbox.containerName,
-                    command: opts.command,
-                    workdir: opts.containerWorkdir ?? opts.sandbox.containerWorkdir,
-                    env: opts.env,
-                    tty: opts.usePty,
-                }),
-            ],
-            options: {
-                cwd: opts.workdir,
-                env: process.env,
-                detached: process.platform !== "win32",
-                stdio: ["pipe", "pipe", "pipe"],
-                windowsHide: true,
-            },
-            fallbacks: [
-                {
-                    label: "no-detach",
-                    options: { detached: false },
-                },
-            ],
-            onFallback: (err, fallback) => {
-                const errText = formatSpawnError(err);
-                const warning = `Warning: spawn failed (${errText}); retrying with ${fallback.label}.`;
-                logWarn(`exec: spawn failed (${errText}); retrying with ${fallback.label}.`);
-                opts.warnings.push(warning);
-            },
-        });
-        child = spawned;
-        stdin = child.stdin;
     }
-    else if (opts.usePty) {
-        const { shell, args: shellArgs } = getShellConfig();
-        try {
-            const ptyModule = (await import("@lydell/node-pty"));
-            const spawnPty = ptyModule.spawn ?? ptyModule.default?.spawn;
-            if (!spawnPty) {
-                throw new Error("PTY support is unavailable (node-pty spawn not found).");
-            }
-            pty = spawnPty(shell, [...shellArgs, opts.command], {
-                cwd: opts.workdir,
-                env: opts.env,
-                name: process.env.TERM ?? "xterm-256color",
-                cols: 120,
-                rows: 30,
-            });
-            stdin = {
-                destroyed: false,
-                write: (data, cb) => {
-                    try {
-                        pty?.write(data);
-                        cb?.(null);
-                    }
-                    catch (err) {
-                        cb?.(err);
-                    }
-                },
-                end: () => {
-                    try {
-                        const eof = process.platform === "win32" ? "\x1a" : "\x04";
-                        pty?.write(eof);
-                    }
-                    catch {
-                        // ignore EOF errors
-                    }
-                },
-            };
-        }
-        catch (err) {
-            const errText = String(err);
-            const warning = `Warning: PTY spawn failed (${errText}); retrying without PTY for \`${opts.command}\`.`;
-            logWarn(`exec: PTY spawn failed (${errText}); retrying without PTY for "${opts.command}".`);
-            opts.warnings.push(warning);
-            const { child: spawned } = await spawnWithFallback({
-                argv: [shell, ...shellArgs, opts.command],
-                options: {
-                    cwd: opts.workdir,
-                    env: opts.env,
-                    detached: process.platform !== "win32",
-                    stdio: ["pipe", "pipe", "pipe"],
-                    windowsHide: true,
-                },
-                fallbacks: [
-                    {
-                        label: "no-detach",
-                        options: { detached: false },
-                    },
-                ],
-                onFallback: (fallbackErr, fallback) => {
-                    const fallbackText = formatSpawnError(fallbackErr);
-                    const fallbackWarning = `Warning: spawn failed (${fallbackText}); retrying with ${fallback.label}.`;
-                    logWarn(`exec: spawn failed (${fallbackText}); retrying with ${fallback.label}.`);
-                    opts.warnings.push(fallbackWarning);
-                },
-            });
-            child = spawned;
-            stdin = child.stdin;
-        }
+    if (stat.size > 512 * 1024) {
+        return;
     }
-    else {
-        const { shell, args: shellArgs } = getShellConfig();
-        const { child: spawned } = await spawnWithFallback({
-            argv: [shell, ...shellArgs, opts.command],
-            options: {
-                cwd: opts.workdir,
-                env: opts.env,
-                detached: process.platform !== "win32",
-                stdio: ["pipe", "pipe", "pipe"],
-                windowsHide: true,
-            },
-            fallbacks: [
-                {
-                    label: "no-detach",
-                    options: { detached: false },
-                },
-            ],
-            onFallback: (err, fallback) => {
-                const errText = formatSpawnError(err);
-                const warning = `Warning: spawn failed (${errText}); retrying with ${fallback.label}.`;
-                logWarn(`exec: spawn failed (${errText}); retrying with ${fallback.label}.`);
-                opts.warnings.push(warning);
-            },
-        });
-        child = spawned;
-        stdin = child.stdin;
+    const content = await fs.readFile(absPath, "utf-8");
+    // Common failure mode: shell env var syntax leaking into Python/JS.
+    // We deliberately match all-caps/underscore vars to avoid false positives with `$` as a JS identifier.
+    const envVarRegex = /\$[A-Z_][A-Z0-9_]{1,}/g;
+    const first = envVarRegex.exec(content);
+    if (first) {
+        const idx = first.index;
+        const before = content.slice(0, idx);
+        const line = before.split("\n").length;
+        const token = first[0];
+        throw new Error([
+            `exec preflight: detected likely shell variable injection (${token}) in ${target.kind} script: ${path.basename(absPath)}:${line}.`,
+            target.kind === "python"
+                ? `In Python, use os.environ.get(${JSON.stringify(token.slice(1))}) instead of raw ${token}.`
+                : `In Node.js, use process.env[${JSON.stringify(token.slice(1))}] instead of raw ${token}.`,
+            "(If this is inside a string literal on purpose, escape it or restructure the code.)",
+        ].join("\n"));
     }
-    const session = {
-        id: sessionId,
-        command: opts.command,
-        scopeKey: opts.scopeKey,
-        sessionKey: opts.sessionKey,
-        notifyOnExit: opts.notifyOnExit,
-        exitNotified: false,
-        child: child ?? undefined,
-        stdin,
-        pid: child?.pid ?? pty?.pid,
-        startedAt,
-        cwd: opts.workdir,
-        maxOutputChars: opts.maxOutput,
-        pendingMaxOutputChars: opts.pendingMaxOutput,
-        totalOutputChars: 0,
-        pendingStdout: [],
-        pendingStderr: [],
-        pendingStdoutChars: 0,
-        pendingStderrChars: 0,
-        aggregated: "",
-        tail: "",
-        exited: false,
-        exitCode: undefined,
-        exitSignal: undefined,
-        truncated: false,
-        backgrounded: false,
-    };
-    addSession(session);
-    let settled = false;
-    let timeoutTimer = null;
-    let timeoutFinalizeTimer = null;
-    let timedOut = false;
-    const timeoutFinalizeMs = 1000;
-    let resolveFn = null;
-    const settle = (outcome) => {
-        if (settled)
-            return;
-        settled = true;
-        resolveFn?.(outcome);
-    };
-    const finalizeTimeout = () => {
-        if (session.exited)
-            return;
-        markExited(session, null, "SIGKILL", "failed");
-        maybeNotifyOnExit(session, "failed");
-        const aggregated = session.aggregated.trim();
-        const reason = `Command timed out after ${opts.timeoutSec} seconds`;
-        settle({
-            status: "failed",
-            exitCode: null,
-            exitSignal: "SIGKILL",
-            durationMs: Date.now() - startedAt,
-            aggregated,
-            timedOut: true,
-            reason: aggregated ? `${aggregated}\n\n${reason}` : reason,
-        });
-    };
-    const onTimeout = () => {
-        timedOut = true;
-        killSession(session);
-        if (!timeoutFinalizeTimer) {
-            timeoutFinalizeTimer = setTimeout(() => {
-                finalizeTimeout();
-            }, timeoutFinalizeMs);
+    // Another recurring pattern from the issue: shell commands accidentally emitted as JS.
+    if (target.kind === "node") {
+        const firstNonEmpty = content
+            .split(/\r?\n/)
+            .map((l) => l.trim())
+            .find((l) => l.length > 0);
+        if (firstNonEmpty && /^NODE\b/.test(firstNonEmpty)) {
+            throw new Error(`exec preflight: JS file starts with shell syntax (${firstNonEmpty}). ` +
+                `This looks like a shell command, not JavaScript.`);
         }
-    };
-    if (opts.timeoutSec > 0) {
-        timeoutTimer = setTimeout(() => {
-            onTimeout();
-        }, opts.timeoutSec * 1000);
     }
-    const emitUpdate = () => {
-        if (!opts.onUpdate)
-            return;
-        const tailText = session.tail || session.aggregated;
-        const warningText = opts.warnings.length ? `${opts.warnings.join("\n")}\n\n` : "";
-        opts.onUpdate({
-            content: [{ type: "text", text: warningText + (tailText || "") }],
-            details: {
-                status: "running",
-                sessionId,
-                pid: session.pid ?? undefined,
-                startedAt,
-                cwd: session.cwd,
-                tail: session.tail,
-            },
-        });
-    };
-    const handleStdout = (data) => {
-        const str = sanitizeBinaryOutput(data.toString());
-        for (const chunk of chunkString(str)) {
-            appendOutput(session, "stdout", chunk);
-            emitUpdate();
-        }
-    };
-    const handleStderr = (data) => {
-        const str = sanitizeBinaryOutput(data.toString());
-        for (const chunk of chunkString(str)) {
-            appendOutput(session, "stderr", chunk);
-            emitUpdate();
-        }
-    };
-    if (pty) {
-        const cursorResponse = buildCursorPositionResponse();
-        pty.onData((data) => {
-            const raw = data.toString();
-            const { cleaned, requests } = stripDsrRequests(raw);
-            if (requests > 0) {
-                for (let i = 0; i < requests; i += 1) {
-                    pty.write(cursorResponse);
-                }
-            }
-            handleStdout(cleaned);
-        });
-    }
-    else if (child) {
-        child.stdout.on("data", handleStdout);
-        child.stderr.on("data", handleStderr);
-    }
-    const promise = new Promise((resolve) => {
-        resolveFn = resolve;
-        const handleExit = (code, exitSignal) => {
-            if (timeoutTimer)
-                clearTimeout(timeoutTimer);
-            if (timeoutFinalizeTimer)
-                clearTimeout(timeoutFinalizeTimer);
-            const durationMs = Date.now() - startedAt;
-            const wasSignal = exitSignal != null;
-            const isSuccess = code === 0 && !wasSignal && !timedOut;
-            const status = isSuccess ? "completed" : "failed";
-            markExited(session, code, exitSignal, status);
-            maybeNotifyOnExit(session, status);
-            if (!session.child && session.stdin) {
-                session.stdin.destroyed = true;
-            }
-            if (settled)
-                return;
-            const aggregated = session.aggregated.trim();
-            if (!isSuccess) {
-                const reason = timedOut
-                    ? `Command timed out after ${opts.timeoutSec} seconds`
-                    : wasSignal && exitSignal
-                        ? `Command aborted by signal ${exitSignal}`
-                        : code === null
-                            ? "Command aborted before exit code was captured"
-                            : `Command exited with code ${code}`;
-                const message = aggregated ? `${aggregated}\n\n${reason}` : reason;
-                settle({
-                    status: "failed",
-                    exitCode: code ?? null,
-                    exitSignal: exitSignal ?? null,
-                    durationMs,
-                    aggregated,
-                    timedOut,
-                    reason: message,
-                });
-                return;
-            }
-            settle({
-                status: "completed",
-                exitCode: code ?? 0,
-                exitSignal: exitSignal ?? null,
-                durationMs,
-                aggregated,
-                timedOut: false,
-            });
-        };
-        if (pty) {
-            pty.onExit((event) => {
-                const rawSignal = event.signal ?? null;
-                const normalizedSignal = rawSignal === 0 ? null : rawSignal;
-                handleExit(event.exitCode ?? null, normalizedSignal);
-            });
-        }
-        else if (child) {
-            child.once("close", (code, exitSignal) => {
-                handleExit(code, exitSignal);
-            });
-            child.once("error", (err) => {
-                if (timeoutTimer)
-                    clearTimeout(timeoutTimer);
-                if (timeoutFinalizeTimer)
-                    clearTimeout(timeoutFinalizeTimer);
-                markExited(session, null, null, "failed");
-                maybeNotifyOnExit(session, "failed");
-                const aggregated = session.aggregated.trim();
-                const message = aggregated ? `${aggregated}\n\n${String(err)}` : String(err);
-                settle({
-                    status: "failed",
-                    exitCode: null,
-                    exitSignal: null,
-                    durationMs: Date.now() - startedAt,
-                    aggregated,
-                    timedOut,
-                    reason: message,
-                });
-            });
-        }
-    });
-    return {
-        session,
-        startedAt,
-        pid: session.pid ?? undefined,
-        promise,
-        kill: () => killSession(session),
-    };
 }
 export function createExecTool(defaults) {
-    const defaultBackgroundMs = clampNumber(defaults?.backgroundMs ?? readEnvInt("PI_BASH_YIELD_MS"), 10_000, 10, 120_000);
+    const defaultBackgroundMs = clampWithDefault(defaults?.backgroundMs ?? readEnvInt("PI_BASH_YIELD_MS"), 10_000, 10, 120_000);
     const allowBackground = defaults?.allowBackground ?? true;
     const defaultTimeoutSec = typeof defaults?.timeoutSec === "number" && defaults.timeoutSec > 0
         ? defaults.timeoutSec
-        : DEFAULT_EXEC_TIMEOUT_SEC;
+        : 1800;
     const defaultPathPrepend = normalizePathPrepend(defaults?.pathPrepend);
     const safeBins = resolveSafeBins(defaults?.safeBins);
     const notifyOnExit = defaults?.notifyOnExit !== false;
+    const notifyOnExitEmptySuccess = defaults?.notifyOnExitEmptySuccess === true;
     const notifySessionKey = defaults?.sessionKey?.trim() || undefined;
     const approvalRunningNoticeMs = resolveApprovalRunningNoticeMs(defaults?.approvalRunningNoticeMs);
     // Derive agentId only when sessionKey is an agent session key.
@@ -585,6 +112,7 @@ export function createExecTool(defaults) {
             const maxOutput = DEFAULT_MAX_OUTPUT;
             const pendingMaxOutput = DEFAULT_PENDING_MAX_OUTPUT;
             const warnings = [];
+            let execCommandOverride;
             const backgroundRequested = params.background === true;
             const yieldRequested = typeof params.yieldMs === "number";
             if (!allowBackground && (backgroundRequested || yieldRequested)) {
@@ -593,7 +121,7 @@ export function createExecTool(defaults) {
             const yieldWindow = allowBackground
                 ? backgroundRequested
                     ? 0
-                    : clampNumber(params.yieldMs ?? defaultBackgroundMs, defaultBackgroundMs, 10, 120_000)
+                    : clampWithDefault(params.yieldMs ?? defaultBackgroundMs, defaultBackgroundMs, 10, 120_000)
                 : null;
             const elevatedDefaults = defaults?.elevated;
             const elevatedAllowed = Boolean(elevatedDefaults?.enabled && elevatedDefaults.allowed);
@@ -620,10 +148,12 @@ export function createExecTool(defaults) {
                     const contextParts = [];
                     const provider = defaults?.messageProvider?.trim();
                     const sessionKey = defaults?.sessionKey?.trim();
-                    if (provider)
+                    if (provider) {
                         contextParts.push(`provider=${provider}`);
-                    if (sessionKey)
+                    }
+                    if (sessionKey) {
                         contextParts.push(`session=${sessionKey}`);
+                    }
                     if (!elevatedDefaults?.enabled) {
                         gates.push("enabled (tools.elevated.enabled / agents.list[].tools.elevated.enabled)");
                     }
@@ -708,7 +238,14 @@ export function createExecTool(defaults) {
                 });
                 applyShellPath(env, shellPath);
             }
-            applyPathPrepend(env, defaultPathPrepend);
+            // `tools.exec.pathPrepend` is only meaningful when exec runs locally (gateway) or in the sandbox.
+            // Node hosts intentionally ignore request-scoped PATH overrides, so don't pretend this applies.
+            if (host === "node" && defaultPathPrepend.length > 0) {
+                warnings.push("Warning: tools.exec.pathPrepend is ignored for host=node. Configure PATH on the node host/service instead.");
+            }
+            else {
+                applyPathPrepend(env, defaultPathPrepend);
+            }
             if (host === "node") {
                 const approvals = resolveExecApprovals(agentId, { security, ask });
                 const hostSecurity = minSecurity(security, approvals.agent.security);
@@ -746,9 +283,6 @@ export function createExecTool(defaults) {
                 }
                 const argv = buildNodeShellCommand(params.command, nodeInfo?.platform);
                 const nodeEnv = params.env ? { ...params.env } : undefined;
-                if (nodeEnv) {
-                    applyPathPrepend(nodeEnv, defaultPathPrepend, { requireExisting: true });
-                }
                 const baseAllowlistEval = evaluateShellAllowlist({
                     command: params.command,
                     allowlist: [],
@@ -887,8 +421,9 @@ export function createExecTool(defaults) {
                             emitExecSystemEvent(`Exec denied (node=${nodeId} id=${approvalId}, invoke-failed): ${commandText}`, { sessionKey: notifySessionKey, contextKey });
                         }
                         finally {
-                            if (runningTimer)
+                            if (runningTimer) {
                                 clearTimeout(runningTimer);
+                            }
                         }
                     })();
                     return {
@@ -1042,8 +577,9 @@ export function createExecTool(defaults) {
                         if (allowlistMatches.length > 0) {
                             const seen = new Set();
                             for (const match of allowlistMatches) {
-                                if (seen.has(match.pattern))
+                                if (seen.has(match.pattern)) {
                                     continue;
+                                }
                                 seen.add(match.pattern);
                                 recordAllowlistUse(approvals.file, agentId, match, commandText, resolvedPath ?? undefined);
                             }
@@ -1061,6 +597,7 @@ export function createExecTool(defaults) {
                                 maxOutput,
                                 pendingMaxOutput,
                                 notifyOnExit: false,
+                                notifyOnExitEmptySuccess: false,
                                 scopeKey: defaults?.scopeKey,
                                 sessionKey: notifySessionKey,
                                 timeoutSec: effectiveTimeout,
@@ -1078,8 +615,9 @@ export function createExecTool(defaults) {
                             }, approvalRunningNoticeMs);
                         }
                         const outcome = await run.promise;
-                        if (runningTimer)
+                        if (runningTimer) {
                             clearTimeout(runningTimer);
+                        }
                         const output = normalizeNotifyOutput(tail(outcome.aggregated || "", DEFAULT_NOTIFY_TAIL_CHARS));
                         const exitLabel = outcome.timedOut ? "timeout" : `code ${outcome.exitCode ?? "?"}`;
                         const summary = output
@@ -1109,11 +647,41 @@ export function createExecTool(defaults) {
                 if (hostSecurity === "allowlist" && (!analysisOk || !allowlistSatisfied)) {
                     throw new Error("exec denied: allowlist miss");
                 }
+                // If allowlist uses safeBins, sanitize only those stdin-only segments:
+                // disable glob/var expansion by forcing argv tokens to be literal via single-quoting.
+                if (hostSecurity === "allowlist" &&
+                    analysisOk &&
+                    allowlistSatisfied &&
+                    allowlistEval.segmentSatisfiedBy.some((by) => by === "safeBins")) {
+                    const safe = buildSafeBinsShellCommand({
+                        command: params.command,
+                        segments: allowlistEval.segments,
+                        segmentSatisfiedBy: allowlistEval.segmentSatisfiedBy,
+                        platform: process.platform,
+                    });
+                    if (!safe.ok || !safe.command) {
+                        // Fallback: quote everything (safe, but may change glob behavior).
+                        const fallback = buildSafeShellCommand({
+                            command: params.command,
+                            platform: process.platform,
+                        });
+                        if (!fallback.ok || !fallback.command) {
+                            throw new Error(`exec denied: safeBins sanitize failed (${safe.reason ?? "unknown"})`);
+                        }
+                        warnings.push("Warning: safeBins hardening used fallback quoting due to parser mismatch.");
+                        execCommandOverride = fallback.command;
+                    }
+                    else {
+                        warnings.push("Warning: safeBins hardening disabled glob/variable expansion for stdin-only segments.");
+                        execCommandOverride = safe.command;
+                    }
+                }
                 if (allowlistMatches.length > 0) {
                     const seen = new Set();
                     for (const match of allowlistMatches) {
-                        if (seen.has(match.pattern))
+                        if (seen.has(match.pattern)) {
                             continue;
+                        }
                         seen.add(match.pattern);
                         recordAllowlistUse(approvals.file, agentId, match, params.command, allowlistEval.segments[0]?.resolution?.resolvedPath);
                     }
@@ -1122,8 +690,12 @@ export function createExecTool(defaults) {
             const effectiveTimeout = typeof params.timeout === "number" ? params.timeout : defaultTimeoutSec;
             const getWarningText = () => (warnings.length ? `${warnings.join("\n")}\n\n` : "");
             const usePty = params.pty === true && !sandbox;
+            // Preflight: catch a common model failure mode (shell syntax leaking into Python/JS sources)
+            // before we execute and burn tokens in cron loops.
+            await validateScriptFileForShellBleed({ command: params.command, workdir });
             const run = await runExecProcess({
                 command: params.command,
+                execCommand: execCommandOverride,
                 workdir,
                 env,
                 sandbox,
@@ -1133,6 +705,7 @@ export function createExecTool(defaults) {
                 maxOutput,
                 pendingMaxOutput,
                 notifyOnExit,
+                notifyOnExitEmptySuccess,
                 scopeKey: defaults?.scopeKey,
                 sessionKey: notifySessionKey,
                 timeoutSec: effectiveTimeout,
@@ -1142,12 +715,14 @@ export function createExecTool(defaults) {
             let yieldTimer = null;
             // Tool-call abort should not kill backgrounded sessions; timeouts still must.
             const onAbortSignal = () => {
-                if (yielded || run.session.backgrounded)
+                if (yielded || run.session.backgrounded) {
                     return;
+                }
                 run.kill();
             };
-            if (signal?.aborted)
+            if (signal?.aborted) {
                 onAbortSignal();
+            }
             else if (signal) {
                 signal.addEventListener("abort", onAbortSignal, { once: true });
             }
@@ -1169,10 +744,12 @@ export function createExecTool(defaults) {
                     },
                 });
                 const onYieldNow = () => {
-                    if (yieldTimer)
+                    if (yieldTimer) {
                         clearTimeout(yieldTimer);
-                    if (yielded)
+                    }
+                    if (yielded) {
                         return;
+                    }
                     yielded = true;
                     markBackgrounded(run.session);
                     resolveRunning();
@@ -1183,8 +760,9 @@ export function createExecTool(defaults) {
                     }
                     else {
                         yieldTimer = setTimeout(() => {
-                            if (yielded)
+                            if (yielded) {
                                 return;
+                            }
                             yielded = true;
                             markBackgrounded(run.session);
                             resolveRunning();
@@ -1193,10 +771,12 @@ export function createExecTool(defaults) {
                 }
                 run.promise
                     .then((outcome) => {
-                    if (yieldTimer)
+                    if (yieldTimer) {
                         clearTimeout(yieldTimer);
-                    if (yielded || run.session.backgrounded)
+                    }
+                    if (yielded || run.session.backgrounded) {
                         return;
+                    }
                     if (outcome.status === "failed") {
                         reject(new Error(outcome.reason ?? "Command failed."));
                         return;
@@ -1218,10 +798,12 @@ export function createExecTool(defaults) {
                     });
                 })
                     .catch((err) => {
-                    if (yieldTimer)
+                    if (yieldTimer) {
                         clearTimeout(yieldTimer);
-                    if (yielded || run.session.backgrounded)
+                    }
+                    if (yielded || run.session.backgrounded) {
                         return;
+                    }
                     reject(err);
                 });
             });