comisai 1.0.37 → 1.0.41

package/node_modules/@comis/skills/dist/builtin/exec-tool.js

@@ -1,1259 +0,0 @@
-// SPDX-License-Identifier: Apache-2.0
-/**
- * Exec tool: execute shell commands in foreground or background mode.
- *
- * Foreground mode spawns a child process with streaming output capture,
- * tail-truncation for large outputs, temp file spillover, and process
- * tree kill on timeout/abort. Returns { exitCode, stdout, stderr } plus
- * optional { truncated, fullOutputPath } when output exceeds limits.
- *
- * Background mode spawns a detached process, registers it in the
- * ProcessRegistry, and returns immediately with { status, sessionId, pid }.
- *
- * Security:
- * - Command and environment validation delegated to exec-security.ts pipeline.
- * - Working directory is validated via safePath to prevent execution
- *   outside workspace bounds.
- *
- * Note: The command denylist is defense-in-depth, not a sandbox. Pattern
- * matching on raw command strings can be bypassed via shell quoting/encoding.
- * The actual security boundary is the builtinTools.exec toggle and tool policy.
- *
- * @module
- */
-import { Type } from "typebox";
-import { spawn } from "node:child_process";
-import { createWriteStream, mkdirSync, writeFileSync, copyFileSync, statSync, existsSync } from "node:fs";
-import { tmpdir } from "node:os";
-import { randomBytes } from "node:crypto";
-import { safePath, PathTraversalError } from "@comis/core";
-import { resolvePaths } from "./file/safe-path-wrapper.js";
-import { jsonResult, throwToolError, readStringParam, readNumberParam, readBooleanParam, } from "./platform/tool-helpers.js";
-import { generateSessionId, appendOutput } from "./process-registry.js";
-import { truncateTail, formatSize, DEFAULT_MAX_BYTES } from "./truncate.js";
-import { createOutputCleaner } from "./output-cleaner.js";
-import { extractHeredoc, validateExecCommand, interpretExitCode } from "./exec-security.js";
-import { matchExecRecoveryHint } from "./exec-diagnostics.js";
-import { tryGetContext } from "@comis/core";
-import { parseInstallDetour, } from "./install-detour.js";
-// ---------------------------------------------------------------------------
-// Constants
-// ---------------------------------------------------------------------------
-/** Maximum bytes to persist to disk for truncated output. */
-const MAX_PERSIST_BYTES = 64 * 1024 * 1024;
-/** Max output chars for background mode's ProcessSession rolling buffer. */
-const BACKGROUND_MAX_OUTPUT_CHARS = 1024 * 1024; // 1MB
-/** Rolling buffer size for foreground streaming (2x DEFAULT_MAX_BYTES). */
-const ROLLING_BUFFER_MAX = DEFAULT_MAX_BYTES * 2; // 100KB
-const DEFAULT_TIMEOUT_MS = 120_000;
-const MAX_TIMEOUT_MS = 600_000;
-// ---------------------------------------------------------------------------
-// Parameter schema
-// ---------------------------------------------------------------------------
-const ExecParams = Type.Object({
-    command: Type.String({ description: "The shell command to execute (single-line only — use 'input' param for multi-line scripts)" }),
-    cwd: Type.Optional(Type.String({ description: "Working directory (defaults to workspace)" })),
-    timeoutMs: Type.Optional(Type.Integer({
-        description: "Timeout in ms (default 120000, max 600000)",
-        default: 120_000,
-    })),
-    env: Type.Optional(Type.Record(Type.String(), Type.String(), {
-        description: "Environment variable overrides",
-    })),
-    background: Type.Optional(Type.Boolean({ description: "Run in background and return immediately" })),
-    input: Type.Optional(Type.String({ description: "String to write to process stdin" })),
-    autoBackgroundMs: Type.Optional(Type.Integer({
-        description: "Auto-background threshold in ms. Foreground commands exceeding this duration transition to background. Default 15000. Set 0 to disable.",
-        default: 15_000,
-    })),
-    description: Type.Optional(Type.String({
-        description: "Human-readable label for this command (e.g. 'Installing dependencies'). Appears in UI activity indicators and structured logs.",
-    })),
-    pty: Type.Optional(Type.Boolean({
-        description: "Allocate a pseudo-terminal for the command. Required for interactive CLI tools that check process.stdout.isTTY. Wraps the command in 'script' to provide a real TTY.",
-    })),
-    secretRefs: Type.Optional(Type.Array(Type.String(), {
-        maxItems: 8,
-        description: "Secret/credential NAMES (not values) to inject as env vars into the subprocess. Use this to pass API tokens to CLI tools like wrangler/gh/gcloud/kubectl without tripping the env-var allowlist. Names are resolved server-side via SecretManager; values never flow through agent context. Call env_list first to discover available names. Platform-managed secrets (referenced by the daemon config, e.g. ANTHROPIC_API_KEY) are rejected. Raw-interpreter commands (python -c, node -e, bash -c, etc.) are rejected with secretRefs to prevent trivial echo-to-stdout leaks. Example: {command: 'npx wrangler pages deploy ./dist', secretRefs: ['CLOUDFLARE_API_TOKEN', 'CLOUDFLARE_ACCOUNT_ID']}",
-    })),
-    allowInstallDetour: Type.Optional(Type.Boolean({
-        description: "Request an operator-approved override when the user explicitly needs " +
-            "package installation despite an equivalent connected MCP server or " +
-            "available skill. Submits an approval request — does NOT self-authorize. " +
-            "Per-commandDigest scoped (one approval does not cover a different install).",
-    })),
-});
-// ---------------------------------------------------------------------------
-// cwd resolution
-// ---------------------------------------------------------------------------
-/**
- * Resolve a user-supplied `cwd` against the workspace root via safePath.
- *
- * Accepts either an absolute path (must still be inside workspace) or a
- * workspace-relative path. Returns the resolved absolute path for spawn().
- * Throws a tool error via throwToolError when the path escapes workspace
- * bounds — caller never needs to validate the string separately.
- *
- * Why this shape: the previous implementation kept the raw user input
- * (typically a workspace-relative string like "projects/foo") and passed
- * it to Node child_process.spawn, which resolves relative paths against
- * the DAEMON'S process.cwd (not the workspace). That produced the
- * misleading "spawn sandbox-exec ENOENT" when the agent's cwd didn't
- * exist under the daemon's cwd. Now every cwd flowing into spawn is an
- * absolute, workspace-anchored path.
- */
-function resolveCwd(workspacePath, cwdParam) {
-    try {
-        return safePath(workspacePath, cwdParam);
-    }
-    catch (error) {
-        if (error instanceof PathTraversalError) {
-            throwToolError("invalid_value", `Working directory outside workspace bounds: ${cwdParam}`);
-        }
-        throw error;
-    }
-    // unreachable — throwToolError never returns, but TS needs this
-    return workspacePath;
-}
-// ---------------------------------------------------------------------------
-// Process tree kill
-// ---------------------------------------------------------------------------
-/**
- * Kill a process tree. When sandboxed, uses positive PID kill (bwrap's
- * --die-with-parent + --unshare-pid cascade to all children). When not
- * sandboxed, uses negative PID (process group kill) with fallback to
- * direct PID kill.
- */
-export function killTree(pid, sandboxed) {
-    try {
-        if (sandboxed) {
-            // Sandbox: kill bwrap directly (positive PID).
-            // --die-with-parent + --unshare-pid cascade to all children.
-            process.kill(pid, "SIGKILL");
-        }
-        else {
-            // No sandbox: kill process group (negative PID) as before.
-            process.kill(-pid, "SIGKILL");
-        }
-    }
-    catch {
-        try {
-            process.kill(pid, "SIGKILL");
-        }
-        catch {
-            // Process already dead
-        }
-    }
-}
-// ---------------------------------------------------------------------------
-// Sandbox spawn command builder
-// ---------------------------------------------------------------------------
-/**
- * Build spawn command arguments, optionally wrapping in the platform sandbox
- * and/or a PTY via `script`.
- *
- * When sandboxConfig is undefined, returns the existing /bin/bash -c command.
- * When present, calls sandboxConfig.sandbox.buildArgs() and prefixes the command.
- *
- * When pty is true, wraps the entire command (including sandbox) in `script`
- * to allocate a pseudo-terminal. On macOS, uses positional args; on Linux,
- * reconstructs a command string for `script -c`.
- *
- * Exported for direct unit testing.
- */
-export function buildSpawnCommand(command, cwd, sandboxConfig, workspacePath, tempDir, pty) {
-    let result;
-    if (!sandboxConfig) {
-        result = { bin: "/bin/bash", args: ["-c", command], cwd };
-    }
-    else {
-        const allReadOnlyPaths = [
-            ...sandboxConfig.readOnlyPaths,
-            ...sandboxConfig.configReadOnlyPaths,
-        ];
-        const resolvedShared = resolvePaths(sandboxConfig.sharedPaths);
-        const sandboxArgs = sandboxConfig.sandbox.buildArgs({
-            workspacePath,
-            sharedPaths: resolvedShared,
-            readOnlyPaths: allReadOnlyPaths,
-            cwd,
-            tempDir,
-        });
-        // bwrap handles cwd internally via --chdir; sandbox-exec does not.
-        // Pass cwd through to spawn() unless the provider handles it.
-        const providerHandlesCwd = sandboxConfig.sandbox.name === "bwrap";
-        result = {
-            bin: sandboxArgs[0],
-            args: [...sandboxArgs.slice(1), "/bin/bash", "-c", command],
-            cwd: providerHandlesCwd ? undefined : cwd,
-        };
-    }
-    // Wrap in PTY via Python pty.spawn() when requested.
-    // Python runs OUTSIDE the sandbox — it creates a PTY pair via openpty(),
-    // forks, connects the child to the PTY slave, and proxies I/O between
-    // its piped stdin/stdout and the PTY master. Unlike `script`, Python's
-    // pty.spawn() handles piped stdin gracefully (catches tcgetattr error
-    // on non-TTY stdin and continues without raw mode).
-    if (pty) {
-        result = {
-            bin: "python3",
-            args: ["-c", "import pty,sys;sys.exit(pty.spawn(sys.argv[1:]))", result.bin, ...result.args],
-            cwd: result.cwd,
-        };
-    }
-    return result;
-}
-// ---------------------------------------------------------------------------
-// secretRefs helpers
-// ---------------------------------------------------------------------------
-/** Valid secret env var name (same rule as env.set). */
-const SECRET_REF_NAME_PATTERN = /^[A-Z][A-Z0-9_]*$/;
-/**
- * Workspace-internal data env resolver.
- *
- * Returns env vars (PATH, MPLCONFIGDIR, XDG_CACHE_HOME, MPLBACKEND,
- * PIP_DISABLE_PIP_VERSION_CHECK) derived from `workspaceDir` so python /
- * matplotlib subprocesses do NOT inherit the daemon's host PATH or
- * cache-dir defaults. (15s pip-install hot path; matplotlib Fontconfig
- * error from a non-writable default cache dir).
- *
- * Defined inline to avoid a cross-package import from `@comis/agent`
- * (`@comis/skills` does not depend on `@comis/agent` -- they are siblings
- * wired together at the daemon composition root, mirroring the
- * `bridge-event-handlers.ts` "Defined inline to avoid cross-package
- * import" precedent). The shape mirrors
- * `packages/agent/src/workspace/data-env.ts` verbatim; if the contract
- * diverges, lift this into `@comis/shared`. The agent-side `data-env.ts`
- * remains the canonical owner of the no-host-env contract.
- *
- * This helper does NOT read host env. The values are pure derivations
- * from workspaceDir + safePath (no path.join).
- */
-function resolveDataEnv(opts) {
-    const venvBin = safePath(opts.workspaceDir, "venv", "bin");
-    const cacheDir = safePath(opts.workspaceDir, ".cache");
-    const mplDir = safePath(cacheDir, "matplotlib");
-    return {
-        PATH: venvBin,
-        MPLCONFIGDIR: mplDir,
-        XDG_CACHE_HOME: cacheDir,
-        MPLBACKEND: "Agg",
-        PIP_DISABLE_PIP_VERSION_CHECK: "1",
-    };
-}
-/**
- * Detect raw-interpreter command shapes. When `secretRefs` is present,
- * these are refused because they make `echo $TOKEN` / `print(os.environ)`
- * trivial one-liners. Agents should put credential-bearing scripts into
- * workspace files and invoke those instead.
- *
- * Matches the command verb (first non-shell-prefix token) against known
- * interpreter binaries combined with a `-c` / `-e` flag. Heredoc-style
- * invocations (`python3 - <<PY ...`) are already split by extractHeredoc
- * before validation and reach this point with command === "python3", so
- * we also refuse the bare-dash form.
- */
-function commandUsesRawInterpreter(command) {
-    // Normalize: drop leading `cd … && ` and `env … ` prefixes so we see the verb.
-    const stripped = command
-        .replace(/^\s*cd\s+\S+\s*&&\s*/i, "")
-        .replace(/^\s*env\s+(?:[A-Z_][A-Z0-9_]*=\S+\s+)*/i, "")
-        .trim();
-    // Match: <interpreter> (-c "…") or (-e "…") or (-) for stdin scripts.
-    // Include common Python/Node/Ruby/Perl/PHP/Bash/Shell forms.
-    const rawPattern = /^(python3?|node|nodejs|ruby|perl|php|bash|sh|zsh|dash|lua|deno|bun)(?:\s+-[cCeE](?:\s+|$)|\s+-(?:\s|$))/i;
-    return rawPattern.test(stripped);
-}
-/**
- * Resolve a list of secret names into an env-var record.
- *
- * Validates each name, rejects platform-managed names, rejects missing
- * names, and calls `secretManager.get` once per name. Returns an error
- * string on any rejection; otherwise returns the resolved record.
- *
- * The returned record is merged into the child's env AFTER the normal
- * userEnv merge, so `secretRefs` wins on collision — agents can't
- * override a server-resolved secret with a stale value by passing the
- * same name via `env`.
- */
-function resolveSecretRefs(refs, secretManager, platformSecretNames) {
-    const env = {};
-    const seen = new Set();
-    for (const name of refs) {
-        if (typeof name !== "string" || !SECRET_REF_NAME_PATTERN.test(name)) {
-            return {
-                ok: false,
-                error: `Invalid secretRefs name "${String(name)}". Names must match /^[A-Z][A-Z0-9_]*$/ (e.g. CLOUDFLARE_API_TOKEN).`,
-            };
-        }
-        if (seen.has(name))
-            continue; // dedup silently
-        seen.add(name);
-        if (platformSecretNames.has(name)) {
-            return {
-                ok: false,
-                error: `Secret "${name}" is referenced by the daemon config and is platform-managed — ` +
-                    `exec cannot expose it. This rule prevents agents from exfiltrating credentials ` +
-                    `the daemon uses to talk to providers. Ask the user to store a separate ` +
-                    `user-task secret under a different name, or invoke this command locally.`,
-            };
-        }
-        const value = secretManager.get(name);
-        if (value === undefined || value.length === 0) {
-            return {
-                ok: false,
-                error: `Secret "${name}" is not configured. Call gateway(action:"env_list", filter:"${name.split("_")[0]}*") ` +
-                    `to see available names, or ask the user to store it via env_set.`,
-            };
-        }
-        env[name] = value;
-    }
-    return { ok: true, env };
-}
-// ---------------------------------------------------------------------------
-// Install-detour helpers
-// ---------------------------------------------------------------------------
-/**
- * Map package manager to the structured ecosystem field used by the
- * `tool:install_detour_detected` event payload (closed shape).
- */
-function ecosystemFor(pm) {
-    return pm === "pip" ? "python" : "node";
-}
-/**
- * Build the structured install-detour hint augmentation for advise mode.
- * Returns BOTH a string (for `details.installDetourHint`) AND a sibling
- * `[hint]` content block (for the `result.content` array). Primary content,
- * stdout, stderr, exitCode, and status are NEVER mutated by callers.
- *
- * Hint is informational; primary signal stays on the
- * exec result envelope.
- */
-export function buildInstallDetourHint(decision) {
-    const lines = decision.overlaps.map((o) => {
-        const cluster = o.cluster ? ` (cluster: ${o.cluster})` : "";
-        return o.sourceType === "mcp"
-            ? `- ${o.packageName} -> connected MCP server "${o.sourceName}"${cluster}`
-            : `- ${o.packageName} -> available skill "${o.sourceName}"${cluster}`;
-    });
-    const text = `[hint] Installed packages overlap available capabilities:\n${lines.join("\n")}\n` +
-        `If you can use these capabilities directly, do so before relying on the install.`;
-    return {
-        installDetourHint: text,
-        hintContentBlock: { type: "text", text },
-    };
-}
-/**
- * Build the verbatim soft-stop error template. Returns `null` when
- * no overlap source remains connected/visible at error-build time
- * (overlaps disappeared mid-call; refusal no longer justified).
- * Caller falls through to spawn in that case.
- *
- * Bullet count == filtered-overlap count. Cluster shown in parens when defined.
- * MCP overlaps say `connected MCP server`; skill overlaps say `available skill`.
- * NO provider-specific tool names; NO self-authorizing override wording.
- */
-function buildSoftStopErrorTemplate(decision, port) {
-    // Re-check connection/visibility at error time, not parser time.
-    // The connected-server set may have drifted since parse. Filter to overlaps
-    // whose source is currently reachable.
-    const connectedServers = new Set(port.getConnectedMcpServers());
-    const visibleSkills = new Set(port.getPromptSkillCapabilities().map((s) => s.name));
-    const filtered = decision.overlaps.filter((o) => o.sourceType === "mcp" ? connectedServers.has(o.sourceName) : visibleSkills.has(o.sourceName));
-    if (filtered.length === 0)
-        return null; // overlaps disappeared — fall through
-    const bullets = filtered.map((o) => {
-        const cluster = o.cluster ? ` (cluster: ${o.cluster})` : "";
-        return o.sourceType === "mcp"
-            ? `- ${o.packageName} -> connected MCP server "${o.sourceName}"${cluster}`
-            : `- ${o.packageName} -> available skill "${o.sourceName}"${cluster}`;
-    });
-    return [
-        "Refused: install overlaps with available capability source(s).",
-        "",
-        "Overlapping packages:",
-        ...bullets,
-        "",
-        "To proceed, choose one:",
-        "1. Use the connected tool(s) or available skill(s) listed above for the overlapping work.",
-        "2. If you only need the non-overlapping packages, rerun exec with the overlapping ones removed.",
-        "3. If you genuinely need the install despite the overlap, ask the user/operator to approve the install-detour override, then rerun this exact command with `allowInstallDetour: true`.",
-    ].join("\n");
-}
-/**
- * Build the closed `tool:install_detour_detected` event payload from a
- * decision + the action/mode tags. Sanitized only:
- * NEVER includes `command`, `rawCommand`, `stdout`, `stderr`, raw shell
- * fragments, URLs, paths, or credentials.
- */
-function buildInstallDetourEventPayload(decision, mode, action) {
-    const ctx = tryGetContext();
-    return {
-        agentId: ctx?.sessionKey ?? "unknown", // sessionKey-as-agentId convention
-        sessionKey: ctx?.sessionKey ?? "unknown",
-        traceId: ctx?.traceId,
-        packageManager: decision.packageManager,
-        commandDigest: decision.commandDigest,
-        packages: decision.packages.map((p) => ({
-            normalizedName: p,
-            ecosystem: ecosystemFor(decision.packageManager),
-        })),
-        overlaps: decision.overlaps.map((o) => ({
-            packageName: o.packageName,
-            sourceType: o.sourceType,
-            sourceName: o.sourceName,
-            reason: o.reason,
-        })),
-        mode,
-        action,
-        timestamp: Date.now(),
-    };
-}
-/**
- * Create an exec tool for shell command execution.
- *
- * Backward compat NOT preserved (memory `feedback_no_backward_compat`).
- *
- * @param deps - Dependencies bundle. See `ExecToolDeps` for field semantics.
- *   `toolCapabilityPort` is REQUIRED; `approvalGate` is optional but
- *   required for the soft-stop override path.
- * @returns AgentTool implementing the exec interface.
- */
-export function createExecTool(deps) {
-    const { workspacePath, registry, secretManager, platformSecretNames, logger, subprocessEnv, sandboxConfig, eventBus, getToolResultsDir, } = deps;
-    // Comis extension: promptGuidelines is not part of AgentTool type, use object
-    // spread to avoid excess property checks in the return statement.
-    const guidelines = {
-        promptGuidelines: [
-            "Prefer dedicated file tools over exec for file operations: " +
-                "use `read` instead of `cat`/`head`/`tail`, " +
-                "`edit` instead of `sed`/`awk`, " +
-                "`write` instead of `echo >`/`cat <<EOF`, " +
-                "`grep` instead of `grep`/`rg`, " +
-                "`find` instead of `find`/`ls`.",
-            "When issuing multiple commands: chain dependent commands with `&&`, " +
-                "use `;` when you don't care if earlier commands fail. " +
-                "DO NOT use newlines to separate commands.",
-            "For git commands: prefer new commits over amending, " +
-                "never skip hooks (--no-verify) or bypass signing unless explicitly asked. " +
-                "Before running destructive operations (reset --hard, push --force, checkout --), " +
-                "consider safer alternatives first.",
-            "Avoid unnecessary `sleep` commands. Use `background: true` for long-running " +
-                "commands instead of sleep loops. Do not retry failing commands in a sleep " +
-                "loop — diagnose the root cause.",
-            "Use `background: true` for commands expected to run longer than 15 seconds " +
-                "(servers, builds, installs). The `autoBackgroundMs` threshold (default 15s) " +
-                "will auto-promote foreground commands that exceed it.",
-            "Default timeout is 120 seconds. For longer operations (builds, test suites), " +
-                "set `timeoutMs` explicitly up to 600000 (10 minutes).",
-            "For multi-line scripts (Python, Node, etc.), pipe the script body via " +
-                "the `input` parameter instead of embedding it in the command string. " +
-                "Example: command=\"python3 -\", input=\"import json\\nprint(json.dumps({...}))\". " +
-                "Newlines in the command string are rejected by security validation. " +
-                "For large data payloads, write data to a file first with the `write` tool, " +
-                "then exec a command that reads it.",
-        ],
-    };
-    return {
-        ...guidelines,
-        name: "exec",
-        label: "Exec",
-        description: "Execute a shell command. Supports background mode, environment overrides, stdin input, and PTY allocation (pty=true for interactive CLI tools that require a TTY).",
-        parameters: ExecParams,
-        async execute(toolCallId, params, signal, onUpdate) {
-            try {
-                const p = params;
-                let command = readStringParam(p, "command");
-                if (!command) {
-                    throwToolError("missing_param", "Missing required parameter: command");
-                }
-                const cwdParam = readStringParam(p, "cwd", false);
-                const rawTimeout = readNumberParam(p, "timeoutMs", false);
-                const userEnv = p.env;
-                const background = readBooleanParam(p, "background", false) ?? false;
-                let input = readStringParam(p, "input", false);
-                const autoBackgroundMs = readNumberParam(p, "autoBackgroundMs", false) ?? 15_000;
-                const description = readStringParam(p, "description", false);
-                const pty = readBooleanParam(p, "pty", false) ?? false;
-                const secretRefs = Array.isArray(p.secretRefs)
-                    ? p.secretRefs.filter((x) => typeof x === "string")
-                    : undefined;
-                // Auto-extract heredoc patterns before security validation.
-                // LLMs send `python3 - <<'PY'\n...\nPY` which Gate 0 blocks
-                // due to newlines. Split into clean command + stdin input.
-                const heredoc = extractHeredoc(command, input ?? undefined);
-                if (heredoc) {
-                    command = heredoc.command;
-                    input = heredoc.input;
-                }
-                // Validate command and env through security pipeline
-                const validationError = validateExecCommand(command, userEnv);
-                if (validationError) {
-                    // Emit command:blocked audit event before throwing
-                    // Note: RequestContext has no agentId field; sessionKey carries agent identity
-                    eventBus?.emit("command:blocked", {
-                        agentId: tryGetContext()?.sessionKey ?? "unknown",
-                        commandPrefix: command.slice(0, 200),
-                        reason: validationError.message,
-                        blocker: validationError.blocker,
-                        timestamp: Date.now(),
-                    });
-                    throwToolError("permission_denied", validationError.message);
-                }
-                // ===================================================================
-                // Install-detour mode policy gate
-                //
-                // Runs synchronously BEFORE any subprocess spawn. soft-stop refuses
-                // pre-spawn; observe and advise fall through to spawn after emitting
-                // events.
-                //
-                // The decision is computed ONCE here and propagated to:
-                // - Event emission (this block)
-                // - ProcessSession population at all 3 spawn sites
-                // - Foreground / auto-bg / explicit-bg envelope augmentation (advise)
-                // - process.status retroactive augmentation (read back from session)
-                // ===================================================================
-                const installDetourMode = deps.toolCapabilityPort.getInstallDetourMode();
-                const installDetourDecision = parseInstallDetour(command, deps.toolCapabilityPort);
-                const allowInstallDetourOverride = readBooleanParam(p, "allowInstallDetour", false) ?? false;
-                // Track the terminal action emitted by the mode cascade for the per-call INFO log.
-                // Initialized to "no-decision" because the parser may return null (no install form /
-                // no overlap); when null, the mode cascade and the log block both short-circuit (the
-                // log lives inside `if (decision !== null)`).
-                let terminalAction = "no-decision";
-                if (installDetourDecision !== null) {
-                    // Decision is non-null only when overlaps.length > 0 (parser contract).
-                    if (installDetourMode === "observe") {
-                        for (const overlap of installDetourDecision.overlaps) {
-                            // Scope each emit to the single overlap so downstream
-                            // consumers receive distinct per-overlap payloads.
-                            // The spread keeps packageManager / commandDigest /
-                            // packages identical across the N events for a single call —
-                            // only `overlaps[]` differs.
-                            eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload({ ...installDetourDecision, overlaps: [overlap] }, "observe", "observed"));
-                            terminalAction = "observed";
-                        }
-                        // Fall through to spawn (observe runs unchanged)
-                    }
-                    else if (installDetourMode === "advise") {
-                        for (const overlap of installDetourDecision.overlaps) {
-                            // Scope each emit to the single overlap.
-                            // See observe-loop comment above for the rationale.
-                            eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload({ ...installDetourDecision, overlaps: [overlap] }, "advise", "hinted"));
-                            terminalAction = "hinted";
-                        }
-                        // Fall through to spawn; envelope augmentation applied at completion sites
-                    }
-                    else if (installDetourMode === "soft-stop") {
-                        if (!allowInstallDetourOverride) {
-                            // Refuse pre-spawn, single soft_stopped event
-                            eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "soft_stopped"));
-                            terminalAction = "soft_stopped";
-                            const errorMessage = buildSoftStopErrorTemplate(installDetourDecision, deps.toolCapabilityPort);
-                            if (errorMessage === null) {
-                                // Overlaps disappeared mid-call. Fall through to spawn.
-                                logger?.debug({
-                                    toolName: "exec",
-                                    commandDigest: installDetourDecision.commandDigest,
-                                    mode: "soft-stop",
-                                    outcome: "overlaps-disappeared",
-                                }, "install-detour overlap sources disappeared mid-call; falling through to spawn");
-                            }
-                            else {
-                                throwToolError("permission_denied", errorMessage);
-                            }
-                        }
-                        else {
-                            // allowInstallDetour: true → submit approval request
-                            const ctx = tryGetContext();
-                            if (!deps.approvalGate || !ctx) {
-                                // Fail-closed: missing gate or missing context → emit override_denied + throw
-                                eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "override_denied"));
-                                terminalAction = "override_denied";
-                                const errorMessage = buildSoftStopErrorTemplate(installDetourDecision, deps.toolCapabilityPort);
-                                throwToolError("permission_denied", errorMessage ?? "Install-detour override denied: missing approval gate or request context.");
-                            }
-                            else {
-                                // Emit override_requested BEFORE awaiting (event-pair contract)
-                                eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "override_requested"));
-                                terminalAction = "override_requested";
-                                const resolution = await deps.approvalGate.requestApproval({
-                                    toolName: "exec",
-                                    action: `exec.install_detour.override:${installDetourDecision.commandDigest}`,
-                                    params: {
-                                        // sanitized only
-                                        packageManager: installDetourDecision.packageManager,
-                                        packages: installDetourDecision.packages,
-                                        overlaps: installDetourDecision.overlaps,
-                                        mode: "soft-stop",
-                                        commandDigest: installDetourDecision.commandDigest,
-                                    },
-                                    agentId: ctx.userId ?? "unknown",
-                                    sessionKey: ctx.sessionKey,
-                                    trustLevel: (ctx.trustLevel ?? "admin"),
-                                    channelType: ctx.channelType,
-                                });
-                                if (!resolution.approved) {
-                                    eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "override_denied"));
-                                    terminalAction = "override_denied";
-                                    throwToolError("permission_denied", `Install-detour override denied: ${resolution.reason ?? "no reason given"}`);
-                                }
-                                // Approved — emit overridden, fall through to spawn UNAUGMENTED.
-                                eventBus?.emit("tool:install_detour_detected", buildInstallDetourEventPayload(installDetourDecision, "soft-stop", "overridden"));
-                                terminalAction = "overridden";
-                            }
-                        }
-                    }
-                    // Per-call INFO log summarizing the policy-gate evaluation
-                    // (AGENTS.md §2.7 object-first convention).
-                    // Fires for every command where a decision was produced AND a mode branch ran.
-                    // The `terminalAction` field reflects the LAST emitted action for this call.
-                    // For multi-event paths (observe/advise: 1-per-overlap; soft-stop with override:
-                    // 2-event pair), `terminalAction` is the last action in the cascade for the call.
-                    logger?.info({
-                        toolName: "exec",
-                        commandDigest: installDetourDecision.commandDigest,
-                        packageManager: installDetourDecision.packageManager,
-                        packageCount: installDetourDecision.packages.length,
-                        overlapCount: installDetourDecision.overlaps.length,
-                        mode: installDetourMode,
-                        action: terminalAction,
-                    }, "install-detour policy gate evaluated");
-                }
-                // ===================================================================
-                // End install-detour mode block
-                // ===================================================================
-                // Detect --break-system-packages for post-execution warning
-                const breakSystemWarning = command.includes("--break-system-packages")
-                    ? "\u26a0\ufe0f WARNING: --break-system-packages modifies the system Python. Use a virtualenv: the workspace's pre-warmed venv (venv/bin/pip install ...) or a per-project one (python3 -m venv projects/<name>/.venv).\n\n"
-                    : "";
-                // Log command start (truncate command to 200 chars for security)
-                logger?.debug({ toolName: "exec", command: command.slice(0, 200), background, pty, ...(description && { description }) }, "Exec command start");
-                // Log env override (keys only, never values)
-                if (userEnv) {
-                    logger?.debug({ toolName: "exec", envOverrides: Object.keys(userEnv) }, "Exec env override applied");
-                }
-                // Clamp timeout
-                const timeoutMs = Math.min(Math.max(rawTimeout ?? DEFAULT_TIMEOUT_MS, 100), MAX_TIMEOUT_MS);
-                // Resolve working directory against the workspace (not the daemon's
-                // process.cwd). Throws via throwToolError if out-of-bounds.
-                const cwd = cwdParam ? resolveCwd(workspacePath, cwdParam) : workspacePath;
-                // Resolve secretRefs (if any). Raw-interpreter guard runs first to
-                // fail fast before touching the SecretManager. secretRefs values
-                // override userEnv on collision — a server-resolved secret always
-                // wins so the agent can't pin a stale value.
-                let resolvedSecretEnv;
-                if (secretRefs && secretRefs.length > 0) {
-                    if (commandUsesRawInterpreter(command)) {
-                        throwToolError("invalid_value", `Raw-interpreter commands (python -c, node -e, bash -c, ruby -e, etc.) ` +
-                            `are not allowed with secretRefs because they make secret echo trivial. ` +
-                            `Write your script to a workspace file (write tool) and invoke that instead, ` +
-                            `e.g. "python3 projects/foo/deploy.py".`);
-                    }
-                    const resolved = resolveSecretRefs(secretRefs, secretManager, platformSecretNames);
-                    if (!resolved.ok) {
-                        throwToolError("invalid_value", resolved.error);
-                    }
-                    else {
-                        resolvedSecretEnv = resolved.env;
-                        // Audit: emit one event per resolved name (value never logged).
-                        const agentId = tryGetContext()?.sessionKey ?? "unknown";
-                        for (const name of Object.keys(resolvedSecretEnv)) {
-                            eventBus?.emit("secret:accessed", {
-                                secretName: name,
-                                agentId,
-                                outcome: "success",
-                                timestamp: Date.now(),
-                            });
-                        }
-                        logger?.info({
-                            toolName: "exec",
-                            secretRefs: Object.keys(resolvedSecretEnv),
-                            commandPrefix: command.slice(0, 80),
-                        }, "Exec resolved secretRefs for subprocess");
-                    }
-                }
-                // Build environment (use filtered subprocess env instead of raw process.env).
-                const baseEnv = subprocessEnv ?? process.env;
-                // Workspace-internal env split into two halves:
-                //
-                //   1. Always-on: MPLCONFIGDIR / XDG_CACHE_HOME / MPLBACKEND /
-                //      PIP_DISABLE_PIP_VERSION_CHECK. Eliminates the matplotlib
-                //      `Fontconfig error` regardless of which venv layout (workspace-
-                //      root `venv/`, per-project `.venv/`, none) the agent uses --
-                //      the host `/root/.cache/matplotlib` may be read-only under
-                //      `ProtectSystem=strict`; the workspace cache dir is always
-                //      writable. Also prevents host XDG_CACHE_HOME leakage.
-                //
-                //   2. Conditional: PATH gets `${workspacePath}/venv/bin` prepended
-                //      only when that directory actually exists (i.e. the Dockerfile
-                //      pre-warm landed and wasn't shadowed by a stale volume). This
-                //      closes the 15s pip-install hot path for prewarm users without
-                //      shadowing per-project `projects/<name>/.venv/bin/python`
-                //      invocations the agent makes directly.
-                //
-                // Order: spread baseEnv -> override with dataEnv -> userEnv (so
-                // the agent can still pin a specific value via `env: {...}`) ->
-                // server-resolved secrets (always last; agent cannot override).
-                const dataEnv = resolveDataEnv({ workspaceDir: workspacePath });
-                const venvBin = safePath(workspacePath, "venv", "bin");
-                if (existsSync(venvBin)) {
-                    logger?.debug({ toolName: "exec", workspaceDir: workspacePath, hint: "Prepending workspace-prewarmed venv/bin to PATH" }, "Exec workspace venv detected");
-                    // Prepend venv bin so `python` / `pip` resolve to the prewarm
-                    // while system binaries (bash, sh, node, git, curl) remain
-                    // reachable via baseEnv.PATH.
-                    if (dataEnv.PATH && baseEnv.PATH) {
-                        dataEnv.PATH = `${dataEnv.PATH}:${baseEnv.PATH}`;
-                    }
-                }
-                else {
-                    // No prewarm on this workspace -- drop the venv-only PATH so
-                    // baseEnv.PATH wins. The matplotlib + cache dir env vars survive
-                    // and still kill the Fontconfig warning universally.
-                    delete dataEnv.PATH;
-                }
-                const env = {
-                    ...baseEnv,
-                    ...dataEnv,
-                    ...(userEnv ?? {}),
-                    ...(resolvedSecretEnv ?? {}),
-                };
-                // Wrap env for sandbox (e.g., redirect cache dirs into workspace)
-                const finalEnv = sandboxConfig?.sandbox.wrapEnv?.(env, workspacePath) ?? env;
-                // Compute temp directory: workspace-based when sandboxed, os.tmpdir() when not
-                const tempDir = sandboxConfig
-                    ? safePath(workspacePath, ".comis-tmp")
-                    : tmpdir();
-                if (sandboxConfig) {
-                    mkdirSync(tempDir, { recursive: true });
-                }
-                // Log stdin write (length only, never content)
-                if (input) {
-                    logger?.debug({ toolName: "exec", stdinLength: input.length }, "Exec stdin write");
-                }
-                if (background) {
-                    return executeBackground(command, cwd, finalEnv, input, registry, logger, sandboxConfig, workspacePath, tempDir, description, pty, installDetourDecision ?? undefined, installDetourMode);
-                }
-                const result = await executeForeground(command, cwd, finalEnv, timeoutMs, input, signal, onUpdate, logger, sandboxConfig, workspacePath, tempDir, registry, autoBackgroundMs, pty, description, toolCallId, getToolResultsDir, installDetourDecision ?? undefined, installDetourMode);
-                // Prepend --break-system-packages warning to stdout so the LLM sees it
-                if (breakSystemWarning && result.details) {
-                    const details = result.details;
-                    if (typeof details.stdout === "string") {
-                        details.stdout = breakSystemWarning + details.stdout;
-                    }
-                }
-                return result;
-            }
-            catch (err) {
-                if (err instanceof Error && err.message.startsWith("["))
-                    throw err;
-                throw err instanceof Error ? err : new Error(String(err));
-            }
-        },
-    };
-}
-/**
- * Execute auto-background escalation: create a ProcessRegistry session from
- * the running child, re-wire output streams, and resolve with a
- * "backgrounded" status containing the sessionId for polling.
- */
-function escalateToBackground(ctx) {
-    ctx.setResolved();
-    clearTimeout(ctx.timeoutTimer);
-    if (ctx.signal)
-        ctx.signal.removeEventListener("abort", ctx.onAbort);
-    const session = {
-        id: generateSessionId(),
-        command: ctx.command,
-        pid: ctx.child.pid,
-        startedAt: ctx.startTimeMs,
-        status: "running",
-        exitCode: undefined,
-        stdout: ctx.stdoutBuf,
-        stderr: ctx.stderrBuf,
-        child: ctx.child,
-        maxOutputChars: BACKGROUND_MAX_OUTPUT_CHARS,
-        sandboxed: !!ctx.sandboxConfig,
-        autoBackgrounded: true,
-        ...(ctx.description && { description: ctx.description }),
-        // Spawn-time decision capture (advise+overlap only).
-        // observe-mode runs unchanged with no retroactive hint; soft-stop refused calls
-        // never reach a session-creation site (refused pre-spawn).
-        ...(ctx.installDetourDecision !== null
-            && ctx.installDetourDecision !== undefined
-            && ctx.installDetourDecision.overlaps.length > 0
-            && ctx.installDetourMode === "advise"
-            && { installDetourDecision: ctx.installDetourDecision }),
-    };
-    // Re-wire stdout/stderr from rolling buffer to session append
-    const bgStdoutCleaner = createOutputCleaner();
-    const bgStderrCleaner = createOutputCleaner();
-    ctx.child.stdout?.removeAllListeners("data");
-    ctx.child.stderr?.removeAllListeners("data");
-    ctx.child.stdout?.on("data", (chunk) => {
-        appendOutput(session, "stdout", bgStdoutCleaner.process(chunk));
-    });
-    ctx.child.stderr?.on("data", (chunk) => {
-        appendOutput(session, "stderr", bgStderrCleaner.process(chunk));
-    });
-    ctx.child.on("close", (code) => {
-        const stdoutFlush = bgStdoutCleaner.flush();
-        const stderrFlush = bgStderrCleaner.flush();
-        if (stdoutFlush)
-            appendOutput(session, "stdout", stdoutFlush);
-        if (stderrFlush)
-            appendOutput(session, "stderr", stderrFlush);
-        session.status = code === 0 ? "completed" : "failed";
-        session.exitCode = code;
-        session.child = undefined;
-    });
-    ctx.registry.add(session);
-    ctx.logger?.info({ toolName: "exec", sessionId: session.id, pid: ctx.child.pid, durationMs: Math.round(performance.now() - ctx.startTime), ...(ctx.description && { description: ctx.description }) }, "Exec auto-backgrounded after threshold");
-    if (ctx.spillStream)
-        ctx.spillStream.end();
-    // Auto-bg envelope augmentation in advise mode
-    if (ctx.installDetourMode === "advise" &&
-        ctx.installDetourDecision !== null &&
-        ctx.installDetourDecision !== undefined &&
-        ctx.installDetourDecision.overlaps.length > 0) {
-        const hint = buildInstallDetourHint(ctx.installDetourDecision);
-        const augmented = jsonResult({
-            status: "backgrounded",
-            sessionId: session.id,
-            pid: ctx.child.pid,
-            stdoutSoFar: truncateTail(ctx.stdoutBuf).content,
-            stderrSoFar: truncateTail(ctx.stderrBuf).content,
-            ...(ctx.description && { description: ctx.description }),
-            installDetourHint: hint.installDetourHint,
-        });
-        ctx.resolve({
-            content: [...augmented.content, hint.hintContentBlock],
-            details: augmented.details,
-        });
-        return;
-    }
-    ctx.resolve(jsonResult({
-        status: "backgrounded",
-        sessionId: session.id,
-        pid: ctx.child.pid,
-        stdoutSoFar: truncateTail(ctx.stdoutBuf).content,
-        stderrSoFar: truncateTail(ctx.stderrBuf).content,
-        ...(ctx.description && { description: ctx.description }),
-    }));
-}
-// ---------------------------------------------------------------------------
-// Foreground execution
-// ---------------------------------------------------------------------------
-function executeForeground(command, cwd, env, timeoutMs, input, signal, onUpdate, logger, sandboxConfig, workspacePath, tempDir, registry, autoBackgroundMs, pty, description, toolCallId, getToolResultsDir, installDetourDecision, installDetourMode) {
-    const startTime = performance.now();
-    const startTimeMs = Date.now();
-    return new Promise((resolve) => {
-        const { bin, args, cwd: spawnCwd } = buildSpawnCommand(command, cwd, sandboxConfig, workspacePath ?? cwd, tempDir ?? tmpdir(), pty);
-        const child = spawn(bin, args, {
-            cwd: spawnCwd,
-            env,
-            detached: true,
-            stdio: ["pipe", "pipe", "pipe"],
-        });
-        const pid = child.pid;
-        // Rolling buffers for stdout, stderr, and combined (for onUpdate)
-        let stdoutBuf = "";
-        let stderrBuf = "";
-        let combinedBuf = "";
-        let totalBytes = 0;
-        let resolved = false;
-        // Output cleaners for stateful UTF-8 decode + ANSI strip + CR normalize + binary sanitize
-        const stdoutCleaner = createOutputCleaner();
-        const stderrCleaner = createOutputCleaner();
-        // Temp file spillover state
-        let spillStream = null;
-        let spillPath = null;
-        let _spillCapped = false;
-        function appendRolling(buf, chunk) {
-            const combined = buf + chunk;
-            if (combined.length > ROLLING_BUFFER_MAX) {
-                return combined.slice(-ROLLING_BUFFER_MAX);
-            }
-            return combined;
-        }
-        function ensureSpillFile() {
-            if (spillStream)
-                return;
-            const hex = randomBytes(8).toString("hex");
-            const filename = `comis-exec-${hex}.log`;
-            spillPath = safePath(tempDir ?? tmpdir(), filename);
-            spillStream = createWriteStream(spillPath, { flags: "a" });
-        }
-        // Wire stdout
-        child.stdout?.on("data", (chunk) => {
-            const str = stdoutCleaner.process(chunk);
-            stdoutBuf = appendRolling(stdoutBuf, str);
-            combinedBuf = appendRolling(combinedBuf, str);
-            totalBytes += chunk.length;
-            // Spill to temp file when output exceeds DEFAULT_MAX_BYTES, cap at MAX_PERSIST_BYTES
-            if (totalBytes > DEFAULT_MAX_BYTES && totalBytes <= MAX_PERSIST_BYTES) {
-                ensureSpillFile();
-                spillStream.write(chunk);
-            }
-            else if (totalBytes > MAX_PERSIST_BYTES && spillStream) {
-                spillStream.end();
-                spillStream = null;
-                _spillCapped = true;
-            }
-            // Stream onUpdate with truncated-tail of combined buffer
-            // EXEC-ABORT: guard with !resolved to prevent late onUpdate calls
-            // after tool resolution (orphaned child process output)
-            if (onUpdate && !resolved) {
-                const truncated = truncateTail(combinedBuf);
-                onUpdate({
-                    content: [{ type: "text", text: truncated.content }],
-                    details: undefined,
-                });
-            }
-        });
-        // Wire stderr
-        child.stderr?.on("data", (chunk) => {
-            const str = stderrCleaner.process(chunk);
-            stderrBuf = appendRolling(stderrBuf, str);
-            combinedBuf = appendRolling(combinedBuf, str);
-            totalBytes += chunk.length;
-            if (totalBytes > DEFAULT_MAX_BYTES && totalBytes <= MAX_PERSIST_BYTES) {
-                ensureSpillFile();
-                spillStream.write(chunk);
-            }
-            else if (totalBytes > MAX_PERSIST_BYTES && spillStream) {
-                spillStream.end();
-                spillStream = null;
-                _spillCapped = true;
-            }
-            // EXEC-ABORT: guard with !resolved to prevent late onUpdate calls
-            // after tool resolution (orphaned child process output)
-            if (onUpdate && !resolved) {
-                const truncated = truncateTail(combinedBuf);
-                onUpdate({
-                    content: [{ type: "text", text: truncated.content }],
-                    details: undefined,
-                });
-            }
-        });
-        // Close stdin to prevent hang on stdin-reading commands (e.g., bare `cat`)
-        if (input && child.stdin) {
-            child.stdin.write(input);
-            child.stdin.end();
-        }
-        else if (child.stdin) {
-            child.stdin.end();
-        }
-        // Manual timeout via setTimeout + killTree
-        let timedOut = false;
-        const timeoutTimer = setTimeout(() => {
-            if (resolved)
-                return;
-            timedOut = true;
-            if (pid)
-                killTree(pid, !!sandboxConfig);
-        }, timeoutMs);
-        // Manual abort via signal
-        let aborted = false;
-        function onAbort() {
-            if (resolved)
-                return;
-            aborted = true;
-            if (pid)
-                killTree(pid, !!sandboxConfig);
-        }
-        if (signal) {
-            if (signal.aborted) {
-                // Already aborted before spawn
-                aborted = true;
-                if (pid)
-                    killTree(pid, !!sandboxConfig);
-            }
-            else {
-                signal.addEventListener("abort", onAbort, { once: true });
-            }
-        }
-        // Auto-background escalation timer
-        const effectiveAutoMs = autoBackgroundMs ?? 15_000;
-        const escalationTimer = (effectiveAutoMs > 0 && registry)
-            ? setTimeout(() => {
-                if (resolved)
-                    return;
-                escalateToBackground({
-                    command, child, startTime, startTimeMs, stdoutBuf, stderrBuf,
-                    registry, sandboxConfig, logger, spillStream,
-                    signal, onAbort, timeoutTimer, resolve,
-                    setResolved: () => { resolved = true; },
-                    description,
-                    // Forward install-detour spawn-time decision + mode
-                    ...(installDetourDecision !== undefined && { installDetourDecision }),
-                    ...(installDetourMode !== undefined && { installDetourMode }),
-                });
-            }, effectiveAutoMs)
-            : null;
-        // Handle close event
-        child.on("close", (code, sig) => {
-            if (resolved)
-                return;
-            resolved = true;
-            // EXEC-ABORT: remove data listeners to prevent late onUpdate calls
-            // after tool resolution (orphaned child process output)
-            child.stdout?.removeAllListeners("data");
-            child.stderr?.removeAllListeners("data");
-            clearTimeout(timeoutTimer);
-            if (escalationTimer)
-                clearTimeout(escalationTimer);
-            if (signal)
-                signal.removeEventListener("abort", onAbort);
-            if (spillStream)
-                spillStream.end();
-            // Determine exit code
-            let exitCode;
-            if (timedOut) {
-                exitCode = 124; // Unix convention for timeout
-            }
-            else if (aborted) {
-                exitCode = 130; // Unix convention for SIGINT
-            }
-            else if (code !== null) {
-                exitCode = code;
-            }
-            else if (sig) {
-                exitCode = 1; // Unknown signal kill
-            }
-            else {
-                exitCode = 1;
-            }
-            // Flush any remaining buffered UTF-8 bytes from the output cleaners
-            const stdoutFlush = stdoutCleaner.flush();
-            const stderrFlush = stderrCleaner.flush();
-            if (stdoutFlush)
-                stdoutBuf = appendRolling(stdoutBuf, stdoutFlush);
-            if (stderrFlush)
-                stderrBuf = appendRolling(stderrBuf, stderrFlush);
-            // Apply tail truncation to stdout/stderr
-            const stdoutResult = truncateTail(stdoutBuf);
-            const stderrResult = truncateTail(stderrBuf);
-            let finalStdout = stdoutResult.content;
-            let finalStderr = stderrResult.content;
-            // Append truncation notices
-            if (stdoutResult.truncated) {
-                const notice = `\n[stdout truncated: kept last ${stdoutResult.outputLines} of ${stdoutResult.totalLines} lines, ${formatSize(stdoutResult.outputBytes)} of ${formatSize(stdoutResult.totalBytes)}]`;
-                finalStdout += notice;
-            }
-            if (stderrResult.truncated) {
-                const notice = `\n[stderr truncated: kept last ${stderrResult.outputLines} of ${stderrResult.totalLines} lines, ${formatSize(stderrResult.outputBytes)} of ${formatSize(stderrResult.totalBytes)}]`;
-                finalStderr += notice;
-            }
-            // Append timeout/abort messages to stderr
-            if (timedOut) {
-                finalStderr += (finalStderr ? "\n" : "") + `Process timed out after ${timeoutMs}ms`;
-            }
-            if (aborted) {
-                finalStderr += (finalStderr ? "\n" : "") + "Process aborted by signal";
-            }
-            // Recovery diagnostics: prepend a `RECOVERY HINT:` line for known-recoverable
-            // failures (e.g. Python ModuleNotFoundError + missing pyproject.toml). Same
-            // surfacing pattern as breakSystemWarning on stdout — gives the LLM an
-            // actionable next step at the HEAD of stderr instead of buried in JSON.
-            const recoveryHint = matchExecRecoveryHint({ stderr: finalStderr, exitCode, cwd });
-            if (recoveryHint) {
-                finalStderr = recoveryHint + (finalStderr ? "\n" + finalStderr : "");
-            }
-            const durationMs = Math.round(performance.now() - startTime);
-            logger?.debug({ toolName: "exec", durationMs, exitCode, ...(description && { description }) }, "Exec command complete");
-            const result = {
-                exitCode,
-                stdout: finalStdout,
-                stderr: finalStderr,
-                ...(description && { description }),
-            };
-            // Add semantic exit code interpretation
-            const exitCodeMeaning = interpretExitCode(command, exitCode);
-            if (exitCodeMeaning) {
-                result.exitCodeMeaning = exitCodeMeaning;
-            }
-            // Add truncation metadata when applicable
-            if (stdoutResult.truncated || stderrResult.truncated) {
-                result.truncated = true;
-            }
-            if (spillPath) {
-                result.fullOutputPath = spillPath;
-            }
-            // Persist full output to session tool-results dir when truncated
-            if ((stdoutResult.truncated || stderrResult.truncated) && getToolResultsDir) {
-                const toolResultsDir = getToolResultsDir();
-                if (toolResultsDir && toolCallId) {
-                    try {
-                        mkdirSync(toolResultsDir, { recursive: true });
-                        const persistPath = safePath(toolResultsDir, `exec-${toolCallId}.txt`);
-                        if (spillPath && totalBytes > ROLLING_BUFFER_MAX) {
-                            // Large output (>100KB): copy spill file which has up to 64MB of content.
-                            // The rolling buffers only hold the last 100KB tail, so spill file is
-                            // the best source for persistence.
-                            copyFileSync(spillPath, persistPath);
-                            const stats = statSync(persistPath);
-                            result.fullOutputPath = persistPath;
-                            result.fullOutputSize = stats.size;
-                            if (_spillCapped) {
-                                // Output exceeded MAX_PERSIST_BYTES (64MB), spill stream was capped
-                                result.fullOutputTruncatedOnDisk = true;
-                                finalStdout += `\n[Full output exceeded 64MB limit; last 64MB saved to disk]`;
-                            }
-                        }
-                        else {
-                            // Small-to-medium output (50-100KB): in-memory rolling buffers have complete content
-                            const fullOutput = stdoutBuf + (stderrBuf ? "\n--- STDERR ---\n" + stderrBuf : "");
-                            const fullOutputBuf = Buffer.from(fullOutput, "utf-8");
-                            writeFileSync(persistPath, fullOutputBuf);
-                            result.fullOutputPath = persistPath;
-                            result.fullOutputSize = fullOutputBuf.length;
-                        }
-                        const sizeStr = formatSize(result.fullOutputSize);
-                        finalStdout += `\n[Full output (${sizeStr}) saved to: ${persistPath}]`;
-                        finalStdout += `\n[Use the file read tool with offset/limit to access specific sections]`;
-                        result.stdout = finalStdout;
-                    }
-                    catch {
-                        // Persistence is best-effort -- don't fail the command
-                        logger?.debug({ toolName: "exec" }, "Failed to persist truncated output");
-                    }
-                }
-            }
-            // Foreground completion envelope augmentation
-            if (installDetourMode === "advise" &&
-                installDetourDecision !== undefined &&
-                installDetourDecision.overlaps.length > 0) {
-                const hint = buildInstallDetourHint(installDetourDecision);
-                result.installDetourHint = hint.installDetourHint;
-                const augmented = jsonResult(result);
-                resolve({
-                    content: [...augmented.content, hint.hintContentBlock],
-                    details: augmented.details,
-                });
-                return;
-            }
-            resolve(jsonResult(result));
-        });
-        // Handle spawn errors
-        child.on("error", (err) => {
-            if (resolved)
-                return;
-            resolved = true;
-            clearTimeout(timeoutTimer);
-            if (escalationTimer)
-                clearTimeout(escalationTimer);
-            if (signal)
-                signal.removeEventListener("abort", onAbort);
-            if (spillStream)
-                spillStream.end();
-            const durationMs = Math.round(performance.now() - startTime);
-            logger?.debug({ toolName: "exec", durationMs, exitCode: 1, ...(description && { description }) }, "Exec command complete");
-            resolve(jsonResult({
-                exitCode: 1,
-                stdout: "",
-                stderr: err.message,
-            }));
-        });
-    });
-}
-// ---------------------------------------------------------------------------
-// Background execution
-// ---------------------------------------------------------------------------
-function executeBackground(command, cwd, env, input, registry, logger, sandboxConfig, workspacePath, tempDir, description, pty, installDetourDecision, installDetourMode) {
-    const sessionId = generateSessionId();
-    const { bin, args, cwd: spawnCwd } = buildSpawnCommand(command, cwd, sandboxConfig, workspacePath ?? cwd, tempDir ?? tmpdir(), pty);
-    const child = spawn(bin, args, {
-        cwd: spawnCwd,
-        env,
-        detached: true,
-        stdio: ["pipe", "pipe", "pipe"],
-    });
-    const session = {
-        id: sessionId,
-        command,
-        pid: child.pid,
-        startedAt: Date.now(),
-        status: "running",
-        exitCode: undefined,
-        stdout: "",
-        stderr: "",
-        child,
-        maxOutputChars: BACKGROUND_MAX_OUTPUT_CHARS,
-        sandboxed: !!sandboxConfig,
-        ...(description && { description }),
-        // Spawn-time decision capture (advise+overlap only).
-        ...(installDetourDecision !== undefined
-            && installDetourDecision.overlaps.length > 0
-            && installDetourMode === "advise"
-            && { installDetourDecision }),
-    };
-    // Output cleaners for stateful UTF-8 decode + ANSI strip + CR normalize + binary sanitize
-    const stdoutCleaner = createOutputCleaner();
-    const stderrCleaner = createOutputCleaner();
-    // Wire stdout/stderr data events
-    child.stdout?.on("data", (chunk) => {
-        appendOutput(session, "stdout", stdoutCleaner.process(chunk));
-    });
-    child.stderr?.on("data", (chunk) => {
-        appendOutput(session, "stderr", stderrCleaner.process(chunk));
-    });
-    // Wire close event
-    child.on("close", (code) => {
-        const stdoutFlush = stdoutCleaner.flush();
-        const stderrFlush = stderrCleaner.flush();
-        if (stdoutFlush)
-            appendOutput(session, "stdout", stdoutFlush);
-        if (stderrFlush)
-            appendOutput(session, "stderr", stderrFlush);
-        if (code === 0) {
-            session.status = "completed";
-        }
-        else {
-            session.status = "failed";
-        }
-        session.exitCode = code;
-        session.child = undefined;
-    });
-    // Handle spawn errors
-    child.on("error", () => {
-        session.status = "failed";
-        session.child = undefined;
-    });
-    // Write stdin if provided
-    if (input && child.stdin) {
-        child.stdin.write(input);
-        child.stdin.end();
-    }
-    // Unref to allow parent process to exit independently.
-    // Skip for sandboxed processes to maintain ProcessRegistry tracking.
-    if (!sandboxConfig) {
-        child.unref();
-    }
-    // Register in ProcessRegistry
-    registry.add(session);
-    logger?.debug({ toolName: "exec", sessionId, pid: child.pid }, "Background process spawned");
-    // Explicit-bg envelope augmentation in advise mode
-    if (installDetourMode === "advise" &&
-        installDetourDecision !== undefined &&
-        installDetourDecision.overlaps.length > 0) {
-        const hint = buildInstallDetourHint(installDetourDecision);
-        const augmented = jsonResult({
-            status: "started",
-            sessionId,
-            pid: child.pid,
-            ...(description && { description }),
-            installDetourHint: hint.installDetourHint,
-        });
-        return {
-            content: [...augmented.content, hint.hintContentBlock],
-            details: augmented.details,
-        };
-    }
-    return jsonResult({
-        status: "started",
-        sessionId,
-        pid: child.pid,
-        ...(description && { description }),
-    });
-}