@mario.andreschak/mcp-bash 3.42.1 → 3.44.0

package/dist/tools.js

@@ -40,17 +40,71 @@ const BASH_SERVER_NAME = 'bash';
 export const BASH_TERMINAL_APP_URI = 'ui://bash/terminal';
 const log = createLogger('backend/services/mcp/internal/bashTools');
 const DEFAULT_TIMEOUT_MS = 60_000;
-const MAX_TIMEOUT_MS = 600_000;
+/**
+ * Foreground commands and `wait` calls may wrap builds, renders, migrations,
+ * and other jobs that take far longer than the historical ten-minute ceiling.
+ * Keep a finite default safety ceiling, aligned with the background-session
+ * lifetime, while allowing deployments to lower or raise it. Passing -1
+ * disables this Bash-side timer; cancellation and shutdown still clean up.
+ */
+const DEFAULT_MAX_TIMEOUT_MS = 12 * 60 * 60_000;
 const MAX_OUTPUT_CHARS = 100_000;
 const MAX_SESSIONS = 25;
 const MAX_TERMINAL_OUTPUT_CHARS = 2_000_000;
 /**
- * Lifecycle: live sessions end only by process exit, explicit kill, or Bash
- * server shutdown. Finished owner-scoped records remain readable for ten
- * minutes, then are reaped. An MCP View teardown may be an inline→dock handoff,
- * so it is not treated as an owner disconnect signal.
+ * Lifecycle (issue #413): a live session ends by process exit, explicit kill,
+ * OWNER RELEASE when its run finishes, idle/max-lifetime expiry, or Bash server
+ * shutdown. Finished owner-scoped records remain readable for ten minutes, then
+ * are reaped. An MCP View teardown may be an inline-to-dock handoff, so it is
+ * still not treated as an owner disconnect signal.
+ *
+ * Owner release is what closes the original leak: nothing used to tell this
+ * server that the run which started a background command had ended, so a
+ * `start`ed process (and its whole descendant tree) outlived its run and stayed
+ * resident for the lifetime of the FLUJO process.
  */
 const SESSION_TTL_MS = 10 * 60_000;
+/**
+ * Host-wide cap across background AND terminal sessions. The per-owner cap alone
+ * could not bound the machine: N concurrent runs each stayed under their own
+ * limit while together they forked an unbounded number of live trees.
+ */
+const MAX_LIVE_SESSIONS_HOST = 50;
+/** A live session with no reads/writes/output for this long is expired. */
+const SESSION_IDLE_TIMEOUT_MS = 60 * 60_000;
+/** Absolute ceiling on a live session's age, idle or not. */
+const SESSION_MAX_LIFETIME_MS = 12 * 60 * 60_000;
+/** How often the expiry sweep runs. */
+const SESSION_SWEEP_INTERVAL_MS = 60_000;
+function positiveEnvNumber(name, fallback) {
+    const raw = Number(process.env[name]);
+    return Number.isFinite(raw) && raw > 0 ? raw : fallback;
+}
+function maxLiveSessionsHost() {
+    return Math.floor(positiveEnvNumber('FLUJO_BASH_MAX_LIVE_SESSIONS', MAX_LIVE_SESSIONS_HOST));
+}
+function sessionIdleTimeoutMs() {
+    return positiveEnvNumber('FLUJO_BASH_SESSION_IDLE_MS', SESSION_IDLE_TIMEOUT_MS);
+}
+function sessionMaxLifetimeMs() {
+    return positiveEnvNumber('FLUJO_BASH_SESSION_MAX_LIFETIME_MS', SESSION_MAX_LIFETIME_MS);
+}
+function commandMaxTimeoutMs() {
+    return positiveEnvNumber('FLUJO_BASH_COMMAND_MAX_TIMEOUT_MS', DEFAULT_MAX_TIMEOUT_MS);
+}
+/** `undefined` means no Bash-side timeout (the explicit timeout=-1 contract). */
+function resolveCommandTimeoutMs(value) {
+    if (value === -1)
+        return undefined;
+    const requested = typeof value === 'number' && Number.isFinite(value) && value > 0
+        ? value * 1_000
+        : DEFAULT_TIMEOUT_MS;
+    return Math.min(requested, commandMaxTimeoutMs());
+}
+/** Test seam for the public timeout contract; not used by the runtime. */
+export function _resolveCommandTimeoutMsForTests(value) {
+    return resolveCommandTimeoutMs(value);
+}
 /**
  * Locate an executable by name on `PATH` ourselves (rather than relying on
  * `spawn`'s own resolution) so we can know in advance whether `pwsh`/`bash`
@@ -150,9 +204,14 @@ function isWindowsWslBashLauncher(candidate) {
     if (process.platform !== 'win32')
         return false;
     const systemRoot = getEnvCaseInsensitive('SystemRoot') ?? getEnvCaseInsensitive('windir');
-    if (!systemRoot)
-        return false;
-    return path.resolve(candidate).toLowerCase() === path.resolve(systemRoot, 'System32', 'bash.exe').toLowerCase();
+    const resolved = path.resolve(candidate).toLowerCase();
+    // The legacy WSL relay may be reached through System32, SysWOW64, or a
+    // SystemRoot-relative shim. It is not a usable POSIX interpreter without a
+    // provisioned distro, so never select it as the Bash MCP's `bash` shell.
+    if (systemRoot && resolved.startsWith(`${path.resolve(systemRoot).toLowerCase()}${path.sep}`)
+        && path.basename(resolved) === 'bash.exe')
+        return true;
+    return /[\\/]WindowsApps[\\/].*wsl.*[\\/]bash\.exe$/i.test(resolved);
 }
 let cachedBashPath;
 function resolveBashExecutable() {
@@ -211,11 +270,96 @@ function resolveCmdExecutable() {
         path.join(getEnvCaseInsensitive('SystemRoot') ?? 'C:\\Windows', 'System32', 'cmd.exe'),
     ]);
 }
+function resolveShExecutable() {
+    if (process.platform === 'win32')
+        return findExecutableOnPath('sh');
+    return firstExistingFile(['/bin/sh', findExecutableOnPath('sh')]);
+}
+/**
+ * Interpreters and utilities probed by `shell_info` (issue #364) so a caller can
+ * discover the machine up front instead of rediscovering it by failed commands.
+ */
+const PROBED_BINARIES = [
+    'python', 'python3', 'node', 'npm', 'npx', 'git', 'rg',
+    'ffmpeg', 'ffprobe', 'curl', 'tar', 'grep', 'sed', 'awk', 'head', 'tail',
+];
+/**
+ * A zero-byte Windows Store app-execution alias (typically `python3.exe` under
+ * `WindowsApps`) resolves on PATH but only opens the Store when executed.
+ */
+function isWindowsStoreAliasStub(candidate) {
+    if (!candidate || process.platform !== 'win32')
+        return false;
+    if (!/[\\/]WindowsApps[\\/]/i.test(candidate))
+        return false;
+    try {
+        return fs.statSync(candidate).size === 0;
+    }
+    catch {
+        return true;
+    }
+}
+function shellEntry(shell, resolved) {
+    return { shell, available: Boolean(resolved), path: resolved };
+}
+let cachedShellInfo;
+/** Describe the shells and interpreters actually available on this machine. */
+export function collectShellInfo() {
+    if (cachedShellInfo)
+        return cachedShellInfo;
+    const defaultPlan = buildSpawn('', 'default');
+    const shells = [
+        shellEntry('pwsh', resolvePwshExecutable()),
+        shellEntry('powershell', resolveWindowsPowerShellExecutable()),
+        shellEntry('bash', resolveBashExecutable()),
+        shellEntry('cmd', resolveCmdExecutable()),
+        shellEntry('sh', resolveShExecutable()),
+    ];
+    const binaries = PROBED_BINARIES.map((name) => {
+        const resolved = findExecutableOnPath(name);
+        if (isWindowsStoreAliasStub(resolved)) {
+            return { name, found: false, path: resolved, alias: true };
+        }
+        return { name, found: Boolean(resolved), path: resolved };
+    });
+    const notes = [
+        'Tool output merges stdout and stderr into one "output" field; "isError" reflects the process exit code only.',
+        `The "default" shell on this machine is "${defaultPlan.effectiveShell}".`,
+        'Pass shell:"bash" for POSIX syntax (&&, pipes into head/grep, $(…)); an unavailable explicit shell fails fast.',
+    ];
+    if (!shells.find((entry) => entry.shell === 'pwsh')?.available
+        && shells.find((entry) => entry.shell === 'powershell')?.available) {
+        notes.push('Only Windows PowerShell 5.1 is installed: "&&" and "||" are not valid statement separators there.');
+    }
+    cachedShellInfo = {
+        platform: process.platform,
+        defaultShell: defaultPlan.effectiveShell,
+        defaultShellPath: defaultPlan.file || null,
+        shells,
+        binaries,
+        notes,
+    };
+    return cachedShellInfo;
+}
+function availableShellNames() {
+    return collectShellInfo().shells.filter((entry) => entry.available).map((entry) => entry.shell);
+}
+function unavailableShellHint(shell) {
+    if (shell === 'bash' && process.platform === 'win32'
+        && findExecutablesOnPath('bash').some(isWindowsWslBashLauncher)) {
+        return 'Only the WSL bash launcher was found and no Linux distribution provides /bin/bash. Install Git for Windows (Git Bash) or a WSL distro.';
+    }
+    return 'Call "shell_info" to see which shells and interpreters exist on this machine.';
+}
+function shellInfoTool() {
+    return textResult(collectShellInfo());
+}
 /** Test-only: forget cached shell-executable lookups. */
 export function _resetBashShellCacheForTests() {
     cachedBashPath = undefined;
     cachedPwshPath = undefined;
     cachedWindowsPowerShellPath = undefined;
+    cachedShellInfo = undefined;
 }
 function sessions() {
     if (!global.__flujo_bash_sessions)
@@ -244,11 +388,203 @@ function ownedSession(id, ownerScope) {
     const session = sessions().get(id);
     return session?.ownerScope === ownerScope ? session : undefined;
 }
+/** Mark a session as active so the idle sweep leaves it alone. */
+function touchSession(session) {
+    session.lastActivityAt = Date.now();
+}
+/** Live sessions across BOTH tables — the quantity the host cap bounds. */
+function liveSessionCount() {
+    let count = 0;
+    for (const session of sessions().values())
+        if (session.running)
+            count += 1;
+    for (const terminal of terminalSessions().values())
+        if (terminal.running)
+            count += 1;
+    return count;
+}
+/** Live sessions for one owner across both tables. */
+function ownerLiveSessionCount(ownerScope) {
+    let count = 0;
+    for (const session of sessions().values()) {
+        if (session.running && session.ownerScope === ownerScope)
+            count += 1;
+    }
+    for (const terminal of terminalSessions().values()) {
+        if (terminal.running && terminal.ownerScope === ownerScope)
+            count += 1;
+    }
+    return count;
+}
+/** Terminate one background session's whole process tree and drop its timers. */
+function terminateSession(session) {
+    if (session.running) {
+        try {
+            session.cancelEscalation = killProcessTree(session.child);
+        }
+        catch {
+            /* best-effort */
+        }
+    }
+    if (session.reapTimer) {
+        clearTimeout(session.reapTimer);
+        session.reapTimer = undefined;
+    }
+}
+/** Terminate one PTY session and drop its timers. */
+function terminateTerminal(terminal) {
+    try {
+        if (terminal.running) {
+            terminal.running = false;
+            terminal.pty.kill();
+        }
+    }
+    catch {
+        /* best-effort */
+    }
+    if (terminal.reapTimer) {
+        clearTimeout(terminal.reapTimer);
+        terminal.reapTimer = undefined;
+    }
+}
+/**
+ * Atomically remove and terminate every NON-DETACHED session of one owner.
+ *
+ * Called when the owning FLUJO run reaches a terminal state. Removing the map
+ * entry BEFORE killing means a concurrent release (or a second call from a retry
+ * path) cannot observe the same session twice, so the operation is idempotent -
+ * repeated releases of the same scope are a no-op instead of a double kill
+ * against a possibly-recycled pid.
+ */
+export function releaseOwnerScope(ownerScope) {
+    const result = {
+        ownerScope,
+        killedSessions: [],
+        closedTerminals: [],
+        retainedDetached: [],
+    };
+    for (const [id, session] of Array.from(sessions())) {
+        if (session.ownerScope !== ownerScope)
+            continue;
+        if (session.detached) {
+            if (session.running)
+                result.retainedDetached.push(id);
+            continue;
+        }
+        sessions().delete(id);
+        if (session.running)
+            result.killedSessions.push(id);
+        terminateSession(session);
+    }
+    for (const [id, terminal] of Array.from(terminalSessions())) {
+        if (terminal.ownerScope !== ownerScope)
+            continue;
+        if (terminal.detached) {
+            if (terminal.running)
+                result.retainedDetached.push(id);
+            continue;
+        }
+        terminalSessions().delete(id);
+        if (terminal.running)
+            result.closedTerminals.push(id);
+        terminateTerminal(terminal);
+    }
+    if (result.killedSessions.length || result.closedTerminals.length) {
+        log.info('Released owner-scoped bash sessions', {
+            ownerScope,
+            killed: result.killedSessions.length,
+            closedTerminals: result.closedTerminals.length,
+            retainedDetached: result.retainedDetached.length,
+        });
+    }
+    return result;
+}
+/**
+ * Expire live sessions that exceeded the idle timeout or the absolute lifetime.
+ *
+ * Detached sessions are exempt from IDLE expiry (being idle is often the point of
+ * a detached watcher) but NOT from the absolute lifetime ceiling - otherwise
+ * `detached` would be an unbounded leak with extra steps.
+ */
+export function expireStaleSessions(now = Date.now()) {
+    const idleLimit = sessionIdleTimeoutMs();
+    const lifetimeLimit = sessionMaxLifetimeMs();
+    const expired = [];
+    for (const [id, session] of Array.from(sessions())) {
+        if (!session.running)
+            continue;
+        const tooOld = now - session.startedAt >= lifetimeLimit;
+        const tooIdle = !session.detached && now - session.lastActivityAt >= idleLimit;
+        if (!tooOld && !tooIdle)
+            continue;
+        sessions().delete(id);
+        terminateSession(session);
+        expired.push(id);
+    }
+    for (const [id, terminal] of Array.from(terminalSessions())) {
+        if (!terminal.running)
+            continue;
+        const tooOld = now - terminal.startedAt >= lifetimeLimit;
+        const tooIdle = !terminal.detached && now - terminal.lastActivityAt >= idleLimit;
+        if (!tooOld && !tooIdle)
+            continue;
+        terminalSessions().delete(id);
+        terminateTerminal(terminal);
+        expired.push(id);
+    }
+    if (expired.length)
+        log.info('Expired stale bash sessions', { count: expired.length });
+    return expired;
+}
+/** Bounded per-session diagnostics: identity/state only, never output. */
+export function bashSessionDiagnostics() {
+    const now = Date.now();
+    const rows = [];
+    for (const session of sessions().values()) {
+        rows.push({
+            sessionId: session.id,
+            type: 'background',
+            ownerScope: session.ownerScope,
+            running: session.running,
+            detached: session.detached === true,
+            ageMs: now - session.startedAt,
+            idleMs: now - session.lastActivityAt,
+        });
+    }
+    for (const terminal of terminalSessions().values()) {
+        rows.push({
+            sessionId: terminal.id,
+            type: 'terminal',
+            ownerScope: terminal.ownerScope,
+            running: terminal.running,
+            detached: terminal.detached === true,
+            ageMs: now - terminal.startedAt,
+            idleMs: now - terminal.lastActivityAt,
+        });
+    }
+    return {
+        liveSessions: liveSessionCount(),
+        maxLiveSessions: maxLiveSessionsHost(),
+        sessions: rows,
+    };
+}
 function terminalMeta(visibility = ['model', 'app']) {
     return { ui: { resourceUri: BASH_TERMINAL_APP_URI, visibility } };
 }
-/** Kill every live session's process tree — used on FLUJO process exit. */
+/**
+ * Kill every live session's process tree - used on Bash server shutdown and on
+ * FLUJO process exit.
+ *
+ * Idempotent and DETACHED-INCLUSIVE: a detached session survives owner release,
+ * but nothing survives the death of the server that owns its pipes. Timers are
+ * cleared too, so a repeated call cannot leave a handle keeping the event loop
+ * alive after "shutdown".
+ */
 export function shutdownBashSessions() {
+    if (global.__flujo_bash_sweep_timer) {
+        clearInterval(global.__flujo_bash_sweep_timer);
+        global.__flujo_bash_sweep_timer = undefined;
+    }
     for (const child of foregroundChildren()) {
         try {
             killProcessTree(child);
@@ -266,8 +602,10 @@ export function shutdownBashSessions() {
                 /* best-effort */
             }
         }
-        if (s.reapTimer)
+        if (s.reapTimer) {
             clearTimeout(s.reapTimer);
+            s.reapTimer = undefined;
+        }
     }
     for (const terminal of terminalSessions().values()) {
         try {
@@ -279,11 +617,27 @@ export function shutdownBashSessions() {
         catch {
             /* best-effort */
         }
-        if (terminal.reapTimer)
+        if (terminal.reapTimer) {
             clearTimeout(terminal.reapTimer);
+            terminal.reapTimer = undefined;
+        }
     }
 }
 function registerExitCleanup() {
+    if (!global.__flujo_bash_sweep_timer) {
+        // Idle/max-lifetime expiry needs a periodic sweep: a session that simply
+        // stops producing output never fires an event we could hang the check on.
+        const timer = setInterval(() => {
+            try {
+                expireStaleSessions();
+            }
+            catch {
+                /* a sweep failure must never crash the server */
+            }
+        }, SESSION_SWEEP_INTERVAL_MS);
+        timer.unref?.();
+        global.__flujo_bash_sweep_timer = timer;
+    }
     if (global.__flujo_bash_cleanup_registered)
         return;
     global.__flujo_bash_cleanup_registered = true;
@@ -323,6 +677,27 @@ async function resolveCwd(input, roots) {
     }
     return resolved;
 }
+/**
+ * Resolve an `outputFile` spool target under the same confinement rules as
+ * `cwd` (issue #364) and make sure its parent directory exists.
+ */
+async function resolveOutputFile(input, cwd, roots) {
+    const raw = typeof input === 'string' ? input.trim() : '';
+    if (!raw)
+        throw new Error('"outputFile" must be a non-empty path.');
+    const resolved = path.isAbsolute(raw) ? path.resolve(raw) : path.resolve(cwd, raw);
+    if (await isProtectedPathsEnabled()) {
+        const prot = isProtected(resolved);
+        if (prot.denied) {
+            throw new Error(`outputFile "${resolved}" is within a protected location (${prot.matchedRoot}).`);
+        }
+    }
+    if (roots.length === 0 || !roots.some((root) => isInside(root, resolved))) {
+        throw new Error(`outputFile "${resolved}" is outside the configured bash roots.`);
+    }
+    await fs.promises.mkdir(path.dirname(resolved), { recursive: true });
+    return resolved;
+}
 /**
  * Best-effort advisory scan (issue #260, item 4) of a command string for
  * absolute-looking paths that point OUTSIDE the configured roots or INTO a
@@ -359,6 +734,47 @@ function maskGlobOptionValues(command) {
     }
     return chars.join('');
 }
+/**
+ * Windows utilities that take `/x`-style switches (issue #314, item D). A slash
+ * token is only demoted from "absolute path" to "switch" when one of these
+ * appears EARLIER IN THE SAME command segment, so `cd … && dir /b && rg …` and
+ * `echo dir /b` stay quiet while `echo /.git/config` keeps its advisory.
+ * Deliberately excludes names that are also common POSIX utilities (`find`,
+ * `sort`, `type`, `more`, `mkdir`, `rmdir`) — suppressing their arguments would
+ * silence genuine path advisories such as `find /etc -name passwd`.
+ */
+const WINDOWS_SWITCH_UTILITIES = new Set([
+    'dir', 'xcopy', 'robocopy', 'copy', 'move', 'del', 'erase', 'attrib', 'icacls', 'takeown',
+    'findstr', 'tasklist', 'taskkill', 'sc', 'reg', 'net', 'subst', 'where', 'ren', 'rename',
+    'md', 'rd', 'tree', 'fc', 'comp', 'cacls', 'schtasks', 'chkdsk', 'sfc', 'shutdown',
+    'wmic', 'diskpart', 'label', 'vol', 'mklink', 'assoc', 'ftype', 'gpupdate', 'powercfg',
+]);
+/**
+ * A cmd-style switch: `/b`, `/ad`, `/mir`, `/e:on`. Never matches a nested path
+ * (no interior separator), so `/etc/passwd` is untouched.
+ */
+const WINDOWS_SWITCH_RE = /^\/[A-Za-z][A-Za-z0-9?*-]{0,15}(?::[^\s"']*)?$/;
+/** Text of the command segment (split on shell separators) preceding `index`. */
+function segmentTextBefore(command, index) {
+    const separators = /&&|\|\||[|;&\n]/g;
+    let start = 0;
+    let match;
+    while ((match = separators.exec(command)) !== null) {
+        if (match.index >= index)
+            break;
+        start = match.index + match[0].length;
+    }
+    return command.slice(start, index);
+}
+/** True when a slash-switch utility heads the segment containing `index`. */
+function windowsSwitchUtilityPrecedes(command, index) {
+    for (const word of segmentTextBefore(command, index).match(/[^\s"'<>()]+/g) ?? []) {
+        const name = word.replace(/^.*[\\/]/, '').toLowerCase().replace(/\.(?:exe|com|bat|cmd)$/, '');
+        if (WINDOWS_SWITCH_UTILITIES.has(name))
+            return true;
+    }
+    return false;
+}
 async function scanCommandForExternalPaths(command, cwd, roots) {
     const warnings = [];
     const protectedPathsEnabled = await isProtectedPathsEnabled();
@@ -369,10 +785,19 @@ async function scanCommandForExternalPaths(command, cwd, roots) {
     // Absolute-looking tokens: Windows drive (X:\ or X:/), UNC (\\host\share),
     // POSIX (/foo), and ~-prefixed home paths.
     const tokenRe = /(?:[A-Za-z]:[\\/][^\s"']*|\\\\[^\s"']+|~\/[^\s"']*|(?<![\w.])\/[^\s"']+)/g;
-    const matches = (commandForPathScan.match(tokenRe) ?? []).filter(
-    // A single-letter slash token is a Windows command switch, not a POSIX path.
-    // Keep longer tokens so genuine POSIX absolute paths remain advisory notices.
-    (token) => !(process.platform === 'win32' && /^\/[A-Za-z]$/.test(token)));
+    const matches = [...commandForPathScan.matchAll(tokenRe)]
+        .filter((match) => {
+        if (process.platform !== 'win32')
+            return true;
+        // Two independent conditions must hold before a token is dropped: it must
+        // LOOK like a cmd switch, and a slash-switch utility must appear earlier
+        // in the SAME segment (`… && dir /b && …`). This keeps `/etc/passwd` and
+        // other genuine POSIX paths advisory.
+        if (!WINDOWS_SWITCH_RE.test(match[0]))
+            return true;
+        return !windowsSwitchUtilityPrecedes(commandForPathScan, match.index ?? 0);
+    })
+        .map((match) => match[0]);
     const home = (() => {
         try {
             return getHomeDir();
@@ -499,6 +924,17 @@ function buildChildEnv(overrides = {}) {
         }
         out.PATHEXT = windowsExecutableExtensions().join(';');
     }
+    // Deterministic text encoding and number formatting for children (issue #364):
+    // without this, interpreters emit locale-dependent decimal commas and non-UTF-8
+    // bytes that come back as mojibake. Explicit per-call `env` still wins below.
+    if (out.PYTHONIOENCODING === undefined)
+        out.PYTHONIOENCODING = 'utf-8';
+    if (process.platform !== 'win32') {
+        if (!out.LANG)
+            out.LANG = 'C.UTF-8';
+        if (!out.LC_ALL)
+            out.LC_ALL = 'C.UTF-8';
+    }
     for (const [key, value] of Object.entries(overrides)) {
         if (process.platform === 'win32') {
             for (const existing of Object.keys(out)) {
@@ -528,6 +964,35 @@ function validateEnv(input) {
     }
     return { valid: true, env };
 }
+/**
+ * PowerShell prelude (issue #364). It makes three platform traps go away for
+ * every command we run:
+ *   - stderr from a native binary no longer turns into a terminating error, so
+ *     the reported exit code is the native process' own,
+ *   - console output is forced to UTF-8 (otherwise logs come back as UTF-16 or
+ *     OEM mojibake),
+ *   - the culture is pinned to invariant, so numbers never use a decimal comma.
+ * The epilogue re-surfaces the native exit code (`$LASTEXITCODE`), falling back
+ * to `$?` when no native command ran.
+ */
+const POWERSHELL_PRELUDE = [
+    "$ErrorActionPreference='Continue'",
+    "$ProgressPreference='SilentlyContinue'",
+    'try { [Console]::OutputEncoding=[Text.Encoding]::UTF8; $OutputEncoding=[Text.Encoding]::UTF8 } catch {}',
+    'try { [Threading.Thread]::CurrentThread.CurrentCulture=[Globalization.CultureInfo]::InvariantCulture;'
+        + ' [Threading.Thread]::CurrentThread.CurrentUICulture=[Globalization.CultureInfo]::InvariantCulture } catch {}',
+].join('; ');
+const POWERSHELL_EPILOGUE = 'exit $(if ($null -ne $LASTEXITCODE) { $LASTEXITCODE } elseif ($?) { 0 } else { 1 })';
+export function wrapPowerShellCommand(command) {
+    return `${POWERSHELL_PRELUDE}\n${command}\n${POWERSHELL_EPILOGUE}`;
+}
+/** `chcp 65001` forces UTF-8 output for cmd.exe children (issue #364). */
+export function wrapCmdCommand(command) {
+    return `chcp 65001>nul & ${command}`;
+}
+function powerShellArgs(command) {
+    return ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', wrapPowerShellCommand(command)];
+}
 /**
  * Build the spawn arguments for the requested shell. Returns the command, argv
  * and whether Node's `shell:true` wrapping applies. Shells are resolved
@@ -539,7 +1004,20 @@ function buildSpawn(command, shell) {
     if (shell === 'pwsh') {
         const resolved = resolvePwshExecutable();
         if (resolved) {
-            return { file: resolved, args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command], useShell: false, effectiveShell: 'pwsh' };
+            return { file: resolved, args: powerShellArgs(command), useShell: false, effectiveShell: 'pwsh' };
+        }
+        const windowsPowerShell = resolveWindowsPowerShellExecutable();
+        if (windowsPowerShell) {
+            return {
+                file: windowsPowerShell,
+                args: powerShellArgs(command),
+                useShell: false,
+                effectiveShell: 'powershell',
+                shellSubstitution: {
+                    requested: 'pwsh', used: 'powershell',
+                    reason: 'PowerShell 7 (pwsh) is not installed on this machine.',
+                },
+            };
         }
         return { file: '', args: [], useShell: false, effectiveShell: 'pwsh', unavailableShell: 'pwsh' };
     }
@@ -555,7 +1033,7 @@ function buildSpawn(command, shell) {
         if (resolved) {
             return {
                 file: resolved,
-                args: ['/d', '/s', '/c', command],
+                args: ['/d', '/s', '/c', wrapCmdCommand(command)],
                 useShell: false,
                 effectiveShell: 'cmd',
                 windowsVerbatimArguments: true,
@@ -566,17 +1044,17 @@ function buildSpawn(command, shell) {
     if (process.platform === 'win32') {
         const pwsh = resolvePwshExecutable();
         if (pwsh) {
-            return { file: pwsh, args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command], useShell: false, effectiveShell: 'pwsh' };
+            return { file: pwsh, args: powerShellArgs(command), useShell: false, effectiveShell: 'pwsh' };
         }
         const windowsPowerShell = resolveWindowsPowerShellExecutable();
         if (windowsPowerShell) {
-            return { file: windowsPowerShell, args: ['-NoLogo', '-NoProfile', '-NonInteractive', '-Command', command], useShell: false, effectiveShell: 'powershell' };
+            return { file: windowsPowerShell, args: powerShellArgs(command), useShell: false, effectiveShell: 'powershell' };
         }
         const cmd = resolveCmdExecutable();
         if (cmd) {
             return {
                 file: cmd,
-                args: ['/d', '/s', '/c', command],
+                args: ['/d', '/s', '/c', wrapCmdCommand(command)],
                 useShell: false,
                 effectiveShell: 'cmd',
                 windowsVerbatimArguments: true,
@@ -632,7 +1110,7 @@ function invalidShellResult(requestedShell) {
     }, true);
 }
 function startChild(command, cwd, shell, env) {
-    const { file, args, useShell, effectiveShell, unavailableShell, startError, windowsVerbatimArguments, } = buildSpawn(command, shell);
+    const { file, args, useShell, effectiveShell, unavailableShell, startError, windowsVerbatimArguments, shellSubstitution, } = buildSpawn(command, shell);
     if (unavailableShell)
         return { effectiveShell, unavailableShell };
     if (startError)
@@ -647,7 +1125,7 @@ function startChild(command, cwd, shell, env) {
             detached,
             ...(windowsVerbatimArguments ? { windowsVerbatimArguments: true } : {}),
         });
-        return { child, effectiveShell };
+        return { child, effectiveShell, shellSubstitution };
     }
     catch (err) {
         return {
@@ -656,21 +1134,212 @@ function startChild(command, cwd, shell, env) {
         };
     }
 }
-function makeAppender(get, set) {
-    return (chunk) => {
-        let out = get();
-        if (out.length >= MAX_OUTPUT_CHARS) {
-            if (chunk)
-                set(out, true);
+/**
+ * Bounded output accumulator (issue #364). Retention is head + tail rather than
+ * head-only, so the command echo at the start AND the final result at the end
+ * both survive an output flood (e.g. a 50k-line ffmpeg progress log); the
+ * omitted middle is reported explicitly.
+ */
+function makeAppender(get, set, maxChars = MAX_OUTPUT_CHARS) {
+    const limit = Math.max(1_000, Math.min(Math.floor(maxChars) || MAX_OUTPUT_CHARS, MAX_OUTPUT_CHARS));
+    const headLimit = Math.max(1, Math.floor(limit * 0.3));
+    const tailLimit = Math.max(1, limit - headLimit);
+    let head = '';
+    let tail = '';
+    let dropped = 0;
+    let total = 0;
+    const compose = () => (dropped > 0
+        ? head + '\n…[' + dropped + ' characters of output omitted]…\n' + tail
+        : head + tail);
+    const append = ((chunk) => {
+        if (!chunk)
             return;
+        total += chunk.length;
+        let rest = chunk;
+        if (head.length < headLimit) {
+            const take = Math.min(headLimit - head.length, rest.length);
+            head += rest.slice(0, take);
+            rest = rest.slice(take);
         }
-        out += chunk;
-        let truncated = false;
-        if (out.length > MAX_OUTPUT_CHARS) {
-            out = out.slice(0, MAX_OUTPUT_CHARS) + '\n…[output truncated]';
-            truncated = true;
+        if (rest) {
+            tail += rest;
+            if (tail.length > tailLimit) {
+                const remove = tail.length - tailLimit;
+                tail = tail.slice(remove);
+                dropped += remove;
+            }
+        }
+        set(compose(), dropped > 0);
+    });
+    append.totalChars = () => total;
+    append.droppedChars = () => dropped;
+    // `get` is retained for call-site symmetry with the previous signature.
+    void get;
+    return append;
+}
+/**
+ * Shell-dialect trap detection (issue #364). Commands are NEVER rewritten —
+ * translating shell text between dialects is far riskier than executing what
+ * the caller wrote — so every finding is returned as an advisory
+ * `dialectWarnings` entry with a concrete suggested fix.
+ */
+const POSIX_ONLY_BINARIES = new Set([
+    'head', 'tail', 'grep', 'sed', 'awk', 'wc', 'cat', 'cut', 'tr', 'uniq', 'sort', 'xargs', 'touch', 'which',
+    'rg', 'jq', 'find', 'ls', 'pwd', 'less', 'du', 'df',
+]);
+const SHELL_BUILTINS = new Set([
+    'cd', 'echo', 'exit', 'export', 'set', 'unset', 'if', 'then', 'else', 'fi', 'for', 'while', 'do', 'done',
+    'true', 'false', 'test', 'type', 'alias', 'function', 'return', 'shift', 'source', '.', 'dir', 'cls',
+    'copy', 'del', 'erase', 'md', 'mkdir', 'rd', 'rmdir', 'move', 'ren', 'rename', 'pushd', 'popd',
+]);
+function isMissingCommandCandidate(head, shell) {
+    const name = path.basename(head).toLowerCase().replace(/\.exe$/, '');
+    if (!name || SHELL_BUILTINS.has(name) || /^[-/$]/.test(head) || /^[A-Za-z_][\w-]*=/.test(head))
+        return false;
+    if (/^[A-Za-z]+-[A-Za-z][A-Za-z-]*$/.test(head) && (shell === 'pwsh' || shell === 'powershell'))
+        return false;
+    return !/[\\/]/.test(head) && !/^\.?\.?$/.test(head);
+}
+/** Blank out quoted spans so operators inside string literals never trip us. */
+function stripQuotedSegments(command) {
+    return command.replace(/"(?:\\.|[^"\\])*"|'[^']*'/g, (match) => ' '.repeat(match.length));
+}
+function commandSegmentHeads(stripped) {
+    return stripped
+        .split(/&&|\|\||[|;\n]/)
+        .map((segment) => segment.trim().split(/\s+/)[0] ?? '')
+        .map((head) => head.replace(/^[('"`]+/, ''))
+        .filter(Boolean);
+}
+/** True when the command relies on POSIX `&&` / `||` statement chaining. */
+export function commandUsesPosixChaining(command) {
+    return /&&|\|\|/.test(stripQuotedSegments(command));
+}
+export function detectDialectMismatch(command, shell, isAvailable = (name) => Boolean(findExecutableOnPath(name))) {
+    const warnings = [];
+    const stripped = stripQuotedSegments(command);
+    const heads = commandSegmentHeads(stripped);
+    const posixShell = shell === 'bash' || shell === 'sh';
+    if (!posixShell) {
+        for (const head of new Set(heads)) {
+            const name = path.basename(head).toLowerCase().replace(/\.exe$/, '');
+            if (!isMissingCommandCandidate(head, shell) || isAvailable(name))
+                continue;
+            if (POSIX_ONLY_BINARIES.has(name)) {
+                warnings.push(`"${name}" is a POSIX utility and is not available as an executable on this machine; `
+                    + `under ${shell} it resolves to nothing (or to an unrelated alias). Pass shell:"bash" or use the native equivalent.`);
+            }
+            else {
+                warnings.push(`"${name}" was not found on PATH; under ${shell} this will fail with a "command not found" error. `
+                    + 'Install it, use the native equivalent, or call "shell_info".');
+            }
+        }
+    }
+    if (shell === 'powershell' && /&&|\|\|/.test(stripped)) {
+        warnings.push('"&&" and "||" are not statement separators in Windows PowerShell 5.1 (they are a parse error). '
+            + 'Use ";" for unconditional chaining, or pass shell:"bash" / shell:"pwsh".');
+    }
+    if (shell === 'pwsh' || shell === 'powershell') {
+        if (/\$\(\s*([A-Za-z_][\w-]*)/.test(stripped)) {
+            const inner = /\$\(\s*([A-Za-z_][\w-]*)/.exec(stripped)?.[1] ?? '';
+            if (POSIX_ONLY_BINARIES.has(inner.toLowerCase()) && !isAvailable(inner.toLowerCase())) {
+                warnings.push(`"$(${inner} …)" is POSIX command substitution; PowerShell evaluates it as a subexpression `
+                    + 'and cannot run that utility. Pass shell:"bash".');
+            }
+        }
+        if ((stripped.match(/`/g) ?? []).length >= 2) {
+            warnings.push('Backticks are the line-continuation/escape character in PowerShell, not command substitution. '
+                + 'Use "$(…)" for PowerShell, or pass shell:"bash".');
+        }
+        if (/2>&1/.test(stripped)) {
+            warnings.push('No "2>&1" redirection is needed: this tool already merges stdout and stderr into one "output" field, '
+                + 'and "isError" is derived from the exit code only.');
+        }
+    }
+    if (shell === 'cmd') {
+        if (/'/.test(command.replace(/"(?:\\.|[^"\\])*"/g, ''))) {
+            warnings.push('cmd.exe does not treat single quotes as string delimiters; use double quotes.');
+        }
+        if (/\$\(|`/.test(stripped)) {
+            warnings.push('Command substitution ($(…) / backticks) is not supported by cmd.exe. Pass shell:"bash" or shell:"pwsh".');
+        }
+    }
+    if (posixShell && /\b(?:Get|Set|New|Remove|Write|Select|Out|Format|Test|Invoke|Start|Stop)-[A-Z][A-Za-z]+\b/.test(stripped)) {
+        warnings.push('This looks like a PowerShell cmdlet but the command is running under a POSIX shell. Pass shell:"pwsh".');
+    }
+    return warnings;
+}
+function missingExecutableHint(exitCode, warnings) {
+    if ((exitCode === 9009 || exitCode === 255 || exitCode === 1)
+        && warnings.some((warning) => /not found on PATH|not available as an executable/.test(warning))) {
+        return { hint: 'A referenced executable was not found — see dialectWarnings.' };
+    }
+    return {};
+}
+/** Commands that typically hang forever waiting on a pager or interactive prompt. */
+export function detectInteractiveHangRisk(command) {
+    const hints = [];
+    const stripped = stripQuotedSegments(command);
+    if (/\bgit\b(?![^|;]*--no-pager)[^|;]*\b(?:log|diff|show|branch)\b/.test(stripped)) {
+        hints.push('git paginates by default; use "git --no-pager …" (or append "| cat") for non-interactive runs.');
+    }
+    if (/(^|[|;\s])(?:less|more)(\s|$)/.test(stripped)) {
+        hints.push('"less"/"more" are interactive pagers and will never exit here; drop them.');
+    }
+    if (/Format-(?:Table|List)\b/.test(stripped) && !/Out-String/.test(stripped)) {
+        hints.push('Pipe Format-Table/Format-List into "| Out-String" so PowerShell does not wait on the host formatter.');
+    }
+    if (/(^|[|;\s])(?:npm|yarn|pnpm)\s+(?:init|login)(\s|$)/.test(stripped)) {
+        hints.push('This command prompts interactively; add its non-interactive flag (e.g. "npm init -y").');
+    }
+    return hints;
+}
+function validateEncoding(input) {
+    if (input === undefined)
+        return 'auto';
+    if (input === 'utf8' || input === 'utf16le' || input === 'auto')
+        return input;
+    return null;
+}
+function looksLikeUtf16le(buf) {
+    const len = Math.min(buf.length, 64);
+    if (len < 4)
+        return false;
+    let nuls = 0;
+    for (let i = 0; i < len; i += 1)
+        if (buf[i] === 0)
+            nuls += 1;
+    return nuls / len > 0.3;
+}
+/**
+ * Decode child output deterministically (issue #364). Windows tooling happily
+ * writes UTF-16LE (e.g. PowerShell redirection into a log) which the default
+ * UTF-8 decode turns into NUL-riddled mojibake. `auto` sniffs a BOM or a high
+ * NUL ratio in the first chunk and then stays with that choice.
+ */
+export function createStreamDecoder(mode = 'auto') {
+    let resolved = mode === 'auto' ? null : mode;
+    let first = true;
+    return (chunk) => {
+        if (typeof chunk === 'string')
+            return chunk;
+        let buf = chunk;
+        if (first) {
+            if (buf.length >= 2 && buf[0] === 0xff && buf[1] === 0xfe) {
+                if (resolved === null)
+                    resolved = 'utf16le';
+                if (resolved === 'utf16le')
+                    buf = buf.subarray(2);
+            }
+            else if (resolved === null) {
+                resolved = looksLikeUtf16le(buf) ? 'utf16le' : 'utf8';
+            }
+            first = false;
         }
-        set(out, truncated);
+        let text = buf.toString(resolved ?? 'utf8');
+        if (text.charCodeAt(0) === 0xfeff)
+            text = text.slice(1);
+        return text;
     };
 }
 /** Resolve an interactive shell executable without wrapping a command string. */
@@ -723,6 +1392,9 @@ function createCommandProgressReporter(context) {
         return { push: () => undefined, stop: async () => undefined };
     const startedAt = Date.now();
     const maxMessageChars = 4_000;
+    // MCP requires `progress` to increase with every notification. It is a
+    // notification sequence here (not a byte count), because silent-command
+    // heartbeats must advance it too.
     let progress = 0;
     let pending = '';
     let flushTimer;
@@ -733,7 +1405,7 @@ function createCommandProgressReporter(context) {
     const deliver = (message) => {
         if (!message)
             return;
-        const snapshot = progress;
+        const snapshot = ++progress;
         chain = chain
             .then(() => report({ progress: snapshot, message }))
             .catch((error) => {
@@ -763,7 +1435,6 @@ function createCommandProgressReporter(context) {
         push: (chunk) => {
             if (stopped || !chunk)
                 return;
-            progress += Buffer.byteLength(chunk, 'utf8');
             const remaining = Math.max(0, MAX_OUTPUT_CHARS - forwardedChars);
             if (remaining > 0) {
                 const accepted = chunk.slice(0, remaining);
@@ -817,7 +1488,25 @@ export function bashToolDefinitions() {
         additionalProperties: { type: 'string' },
         description: 'Environment variables to add or override for this command.',
     };
+    const encodingProp = {
+        type: 'string',
+        enum: ['auto', 'utf8', 'utf16le'],
+        description: 'How to decode child output. "auto" (default) detects UTF-16LE (BOM or NUL-heavy) and otherwise uses UTF-8.',
+    };
+    const maxOutputCharsProp = {
+        type: 'number',
+        description: 'Cap the returned output (default and hard maximum 100000 characters). When exceeded, the head and tail are kept and the omitted middle is reported.',
+    };
+    const outputFileProp = {
+        type: 'string',
+        description: 'Spool the full merged output to this file (confined to the configured roots) while the result stays bounded.',
+    };
     return [
+        {
+            name: 'shell_info',
+            description: 'Describe this machine before running anything: platform, which shell "default" resolves to, which of pwsh/powershell/bash/cmd/sh are available, and whether common interpreters (python, node, git, ffmpeg, …) are on PATH. Call this instead of discovering the environment through failed commands.',
+            inputSchema: { type: 'object', properties: {} },
+        },
         {
             name: 'open_terminal',
             description: 'Open a real interactive pseudoterminal (PTY/ConPTY) and display its MCP App. Returns an owner-scoped terminal sessionId.',
@@ -830,6 +1519,10 @@ export function bashToolDefinitions() {
                     env: envProp,
                     cols: { type: 'number', description: 'Initial terminal columns (20-400, default 100).' },
                     rows: { type: 'number', description: 'Initial terminal rows (5-200, default 30).' },
+                    detached: {
+                        type: 'boolean',
+                        description: 'Keep the terminal alive after the run that opened it finishes (default false). Still bounded by the host session cap and the absolute max lifetime.',
+                    },
                 },
             },
         },
@@ -884,7 +1577,9 @@ export function bashToolDefinitions() {
         },
         {
             name: 'run',
-            description: 'Run one command to completion. Output is sent as live progress when supported and returned with the exit code; use start/status for a persistent background session.',
+            description: 'Run one command to completion. "output" is stdout and stderr MERGED (no 2>&1 needed) and "isError" reflects the process exit code only — text on stderr is not a failure. '
+                + 'On an unknown machine call "shell_info" first; prefer shell:"bash" for POSIX syntax (&&, pipes into head/grep). Output is UTF-8 decoded and PowerShell runs with invariant culture, so numbers and text are stable. '
+                + 'Use start/status for a persistent background session.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -892,15 +1587,22 @@ export function bashToolDefinitions() {
                     cwd: cwdProp,
                     shell: shellProp,
                     env: envProp,
-                    timeout: { type: 'number', description: 'Timeout in seconds (default 60, max 600).' },
+                    timeout: {
+                        type: 'number',
+                        description: 'Bash-side timeout in seconds (default 60; -1 disables it; positive values are capped at 12 hours by default). '
+                            + 'While running, output and 10-second liveness heartbeats are sent as MCP progress. On timeout the whole process tree is killed.',
+                    },
                     normalizeNewlines: { type: 'boolean', description: 'If true, CRLF/CR in the captured output are normalized to LF.' },
+                    encoding: encodingProp,
+                    maxOutputChars: maxOutputCharsProp,
+                    outputFile: outputFileProp,
                 },
                 required: ['command'],
             },
         },
         {
             name: 'start',
-            description: 'Start an independent background command and return its sessionId. Multiple sessions may run in parallel; use status/wait, write_stdin, or kill.',
+            description: 'Start an independent background command and return its sessionId. Output is stdout and stderr merged, decoded as UTF-8. Multiple sessions may run in parallel; use status/wait, write_stdin, or kill.',
             inputSchema: {
                 type: 'object',
                 properties: {
@@ -908,6 +1610,13 @@ export function bashToolDefinitions() {
                     cwd: cwdProp,
                     shell: shellProp,
                     env: envProp,
+                    encoding: encodingProp,
+                    maxOutputChars: maxOutputCharsProp,
+                    outputFile: outputFileProp,
+                    detached: {
+                        type: 'boolean',
+                        description: 'Survive the end of the run that started it (default false). Detached sessions are still bounded by the host session cap and the absolute max lifetime, and are always killed when the bash server shuts down.',
+                    },
                 },
                 required: ['command'],
             },
@@ -928,7 +1637,10 @@ export function bashToolDefinitions() {
                 type: 'object',
                 properties: {
                     sessionId: { type: 'string', description: 'The id returned by start.' },
-                    timeout: { type: 'number', description: 'Max seconds to wait (default 60, max 600).' },
+                    timeout: {
+                        type: 'number',
+                        description: 'Max seconds to wait (default 60; -1 waits until completion or cancellation; positive values are capped at 12 hours by default).',
+                    },
                 },
                 required: ['sessionId'],
             },
@@ -957,7 +1669,12 @@ export function bashToolDefinitions() {
         },
         {
             name: 'list_sessions',
-            description: 'List background sessions owned by this caller scope. Returns { sessions: [{ sessionId, command, running, exitCode, startedAt, endedAt }] }.',
+            description: 'List background sessions owned by this caller scope. Returns { sessions: [{ sessionId, command, running, exitCode, detached, startedAt, endedAt }] }.',
+            inputSchema: { type: 'object', properties: {} },
+        },
+        {
+            name: 'release_owner',
+            description: 'Kill and forget every non-detached background and terminal session owned by this caller scope. Idempotent. Sessions started with "detached": true are retained. FLUJO calls this when a run finishes; the scope is host-derived, so a caller can only release its own sessions. Returns { ownerScope, killedSessions, closedTerminals, retainedDetached }.',
             inputSchema: { type: 'object', properties: {} },
         },
     ];
@@ -965,6 +1682,68 @@ export function bashToolDefinitions() {
 function maybeNormalize(text, normalize) {
     return normalize ? text.replace(/\r\n?/g, '\n') : text;
 }
+/**
+ * Only when the caller said `shell: "default"` may we pick a different shell
+ * (issue #364): a command chained with POSIX `&&`/`||` cannot even parse under
+ * Windows PowerShell 5.1, so prefer a shell that can run it. An explicitly
+ * requested shell is never overridden.
+ */
+function selectShell(command, requested) {
+    if (requested !== 'default')
+        return { shell: requested, autoSelected: false };
+    const plan = buildSpawn(command, 'default');
+    if (plan.effectiveShell === 'powershell' && commandUsesPosixChaining(command)) {
+        if (resolvePwshExecutable())
+            return { shell: 'pwsh', autoSelected: true };
+        if (resolveBashExecutable())
+            return { shell: 'bash', autoSelected: true };
+    }
+    return { shell: 'default', autoSelected: false };
+}
+/** Optional per-call output limits shared by `run` and `start`. */
+function resolveMaxOutputChars(input) {
+    return typeof input === 'number' && input > 0
+        ? Math.min(Math.floor(input), MAX_OUTPUT_CHARS)
+        : MAX_OUTPUT_CHARS;
+}
+/** Spool the full merged output to a file while the tool result stays bounded. */
+function createOutputSpool(file) {
+    if (!file)
+        return { write: () => undefined, close: () => undefined, bytes: () => 0, error: () => undefined };
+    let bytes = 0;
+    let failure;
+    let stream;
+    try {
+        stream = fs.createWriteStream(file, { encoding: 'utf8' });
+        stream.on('error', (err) => { failure = err instanceof Error ? err.message : String(err); });
+    }
+    catch (err) {
+        failure = err instanceof Error ? err.message : String(err);
+    }
+    return {
+        write: (chunk) => {
+            if (!stream || failure || !chunk)
+                return;
+            try {
+                stream.write(chunk);
+                bytes += Buffer.byteLength(chunk, 'utf8');
+            }
+            catch (err) {
+                failure = err instanceof Error ? err.message : String(err);
+            }
+        },
+        close: () => {
+            try {
+                stream?.end();
+            }
+            catch {
+                /* best-effort */
+            }
+        },
+        bytes: () => bytes,
+        error: () => failure,
+    };
+}
 async function runTool(args, roots, context) {
     const command = String(args?.command ?? '').trim();
     if (!command)
@@ -979,27 +1758,68 @@ async function runTool(args, roots, context) {
     if (context?.signal?.aborted) {
         return textResult({ error: 'Command cancelled before it started.', cancelled: true, requestedShell }, true);
     }
+    const encodingMode = validateEncoding(args.encoding);
+    if (!encodingMode) {
+        return textResult({ error: '"encoding" must be one of "utf8", "utf16le", or "auto".' }, true);
+    }
     const cwd = await resolveCwd(args.cwd, roots);
     const warnings = await scanCommandForExternalPaths(command, cwd, roots);
     const warn = warnings.length ? { warnings } : {};
     const normalize = args.normalizeNewlines === true;
-    const timeoutSec = typeof args.timeout === 'number' && args.timeout > 0 ? args.timeout : DEFAULT_TIMEOUT_MS / 1000;
-    const timeoutMs = Math.min(timeoutSec * 1000, MAX_TIMEOUT_MS);
+    const timeoutMs = resolveCommandTimeoutMs(args.timeout);
+    const maxOutputChars = resolveMaxOutputChars(args.maxOutputChars);
+    let outputFilePath;
+    if (args.outputFile !== undefined) {
+        try {
+            outputFilePath = await resolveOutputFile(args.outputFile, cwd, roots);
+        }
+        catch (err) {
+            return textResult({ error: err instanceof Error ? err.message : String(err), cwd }, true);
+        }
+    }
+    const selection = selectShell(command, requestedShell);
     registerExitCleanup();
+    const startedAt = Date.now();
     return await new Promise((resolve) => {
         let output = '';
         let truncated = false;
         let settled = false;
-        const append = makeAppender(() => output, (v, t) => { output = v; truncated = t || truncated; });
+        let stderrChars = 0;
+        const append = makeAppender(() => output, (v, t) => { output = v; truncated = t || truncated; }, maxOutputChars);
+        const spool = createOutputSpool(outputFilePath);
+        const decodeStdout = createStreamDecoder(encodingMode);
+        const decodeStderr = createStreamDecoder(encodingMode);
         const progress = createCommandProgressReporter(context);
-        const { child, startError, effectiveShell, unavailableShell } = startChild(command, cwd, requestedShell, envValidation.env);
+        const { child, startError, effectiveShell, unavailableShell, shellSubstitution } = startChild(command, cwd, selection.shell, envValidation.env);
+        const dialectWarnings = detectDialectMismatch(command, effectiveShell);
+        const dialect = dialectWarnings.length ? { dialectWarnings } : {};
+        const auto = selection.autoSelected ? { shellAutoSelected: true } : {};
+        const substitution = shellSubstitution ? { shellSubstitution } : {};
+        const spoolInfo = () => (outputFilePath
+            ? { outputFile: outputFilePath, outputBytes: spool.bytes(), ...(spool.error() ? { outputFileError: spool.error() } : {}) }
+            : {});
+        const outputStats = () => ({
+            truncated,
+            stderrChars,
+            outputChars: append.totalChars(),
+            ...(append.droppedChars() > 0 ? { omittedChars: append.droppedChars() } : {}),
+        });
         if (unavailableShell) {
+            spool.close();
             void progress.stop().then(() => {
-                resolve(textResult({ error: `Requested shell "${unavailableShell}" is unavailable or could not be resolved.`, cwd, shell: unavailableShell }, true));
+                resolve(textResult({
+                    error: `Requested shell "${unavailableShell}" is unavailable or could not be resolved.`,
+                    cwd,
+                    requestedShell,
+                    shell: unavailableShell,
+                    availableShells: availableShellNames(),
+                    hint: unavailableShellHint(unavailableShell),
+                }, true));
             });
             return;
         }
         if (startError || !child) {
+            spool.close();
             void progress.stop().then(() => {
                 resolve(textResult({ error: `Failed to start command (${effectiveShell}): ${startError ?? 'unknown error'}`, cwd, shell: effectiveShell }, true));
             });
@@ -1018,8 +1838,12 @@ async function runTool(args, roots, context) {
                 requestedShell,
                 shell: effectiveShell,
                 exitCode: null,
-                truncated,
                 output: finalOut,
+                ...outputStats(),
+                ...spoolInfo(),
+                ...dialect,
+                ...substitution,
+                ...auto,
                 ...warn,
             }, true), true);
         };
@@ -1032,31 +1856,48 @@ async function runTool(args, roots, context) {
             context?.signal?.removeEventListener('abort', onAbort);
             if (!keepKillEscalation)
                 cancelEscalation?.();
+            spool.close();
             await progress.stop();
             resolve(result);
         };
-        timer = setTimeout(() => {
-            cancelEscalation = killProcessTree(child);
-            const finalOut = maybeNormalize(output, normalize);
-            void finish(textResult({
-                timedOut: true,
-                cwd,
-                requestedShell,
-                shell: effectiveShell,
-                exitCode: null,
-                truncated,
-                output: `${finalOut}${finalOut ? '\n' : ''}[killed after ${timeoutMs / 1000}s timeout]`,
-                ...warn,
-            }, true), true);
-        }, timeoutMs);
+        if (timeoutMs !== undefined) {
+            timer = setTimeout(() => {
+                cancelEscalation = killProcessTree(child);
+                const finalOut = maybeNormalize(output, normalize);
+                const hangHints = detectInteractiveHangRisk(command);
+                void finish(textResult({
+                    timedOut: true,
+                    cwd,
+                    requestedShell,
+                    shell: effectiveShell,
+                    exitCode: null,
+                    timeoutMs,
+                    elapsedMs: Date.now() - startedAt,
+                    killedProcessTree: true,
+                    suggestion: `Command exceeded ${timeoutMs / 1000}s and its process tree was killed. `
+                        + `Raise "timeout" (positive values cap at ${commandMaxTimeoutMs() / 1000}s), pass -1, or use "start" + "wait" for a persistent job.`,
+                    output: `${finalOut}${finalOut ? '\n' : ''}[killed after ${timeoutMs / 1000}s timeout]`,
+                    ...outputStats(),
+                    ...spoolInfo(),
+                    ...(hangHints.length ? { hangHints } : {}),
+                    ...dialect,
+                    ...substitution,
+                    ...auto,
+                    ...warn,
+                }, true), true);
+            }, timeoutMs);
+        }
         child.stdout?.on('data', (d) => {
-            const chunk = d.toString();
+            const chunk = decodeStdout(d);
             append(chunk);
+            spool.write(chunk);
             progress.push(maybeNormalize(chunk, normalize));
         });
         child.stderr?.on('data', (d) => {
-            const chunk = d.toString();
+            const chunk = decodeStderr(d);
+            stderrChars += chunk.length;
             append(chunk);
+            spool.write(chunk);
             progress.push(maybeNormalize(chunk, normalize));
         });
         child.on('error', (err) => {
@@ -1071,7 +1912,20 @@ async function runTool(args, roots, context) {
             if (settled)
                 return;
             const finalOut = maybeNormalize(output, normalize);
-            void finish(textResult({ exitCode: code, cwd, requestedShell, shell: effectiveShell, truncated, output: finalOut, ...warn }, code !== 0));
+            void finish(textResult({
+                exitCode: code,
+                cwd,
+                requestedShell,
+                shell: effectiveShell,
+                output: finalOut,
+                ...outputStats(),
+                ...spoolInfo(),
+                ...dialect,
+                ...missingExecutableHint(code, dialectWarnings),
+                ...substitution,
+                ...auto,
+                ...warn,
+            }, code !== 0));
         });
         if (context?.signal?.aborted)
             onAbort();
@@ -1112,13 +1966,52 @@ async function startTool(args, roots, ownerScope, context) {
     if (table.size >= MAX_SESSIONS) {
         return textResult({ error: `Too many active background sessions (max ${MAX_SESSIONS}). Kill some first.` }, true);
     }
+    // Issue #413: the HOST-wide live cap spans background and terminal sessions.
+    // A per-owner limit alone let N concurrent runs each stay legal while together
+    // forking an unbounded number of live process trees on one machine. Expire
+    // stale sessions first so the cap is measured against genuinely live work.
+    expireStaleSessions();
+    const hostLimit = maxLiveSessionsHost();
+    if (liveSessionCount() >= hostLimit) {
+        return textResult({
+            error: `Too many live sessions on this host (max ${hostLimit} across background and terminal sessions). Wait for one to finish or kill one first.`,
+            liveSessions: liveSessionCount(),
+        }, true);
+    }
+    if (ownerLiveSessionCount(ownerScope) >= MAX_SESSIONS) {
+        return textResult({ error: `Too many live sessions for this caller (max ${MAX_SESSIONS}). Kill some first.` }, true);
+    }
+    // Surviving the owning run must be an explicit choice (see releaseOwnerScope).
+    const detached = args.detached === true || args.persistAfterRun === true;
     registerExitCleanup();
+    const encodingMode = validateEncoding(args.encoding);
+    if (!encodingMode) {
+        return textResult({ error: '"encoding" must be one of "utf8", "utf16le", or "auto".' }, true);
+    }
     const cwd = await resolveCwd(args.cwd, roots);
     const warnings = await scanCommandForExternalPaths(command, cwd, roots);
     const warn = warnings.length ? { warnings } : {};
-    const { child, startError, effectiveShell, unavailableShell } = startChild(command, cwd, requestedShell, envValidation.env);
+    const maxOutputChars = resolveMaxOutputChars(args.maxOutputChars);
+    let outputFilePath;
+    if (args.outputFile !== undefined) {
+        try {
+            outputFilePath = await resolveOutputFile(args.outputFile, cwd, roots);
+        }
+        catch (err) {
+            return textResult({ error: err instanceof Error ? err.message : String(err), cwd }, true);
+        }
+    }
+    const selection = selectShell(command, requestedShell);
+    const { child, startError, effectiveShell, unavailableShell, shellSubstitution } = startChild(command, cwd, selection.shell, envValidation.env);
     if (unavailableShell) {
-        return textResult({ error: `Requested shell "${unavailableShell}" is unavailable or could not be resolved.`, cwd, shell: unavailableShell }, true);
+        return textResult({
+            error: `Requested shell "${unavailableShell}" is unavailable or could not be resolved.`,
+            cwd,
+            requestedShell,
+            shell: unavailableShell,
+            availableShells: availableShellNames(),
+            hint: unavailableShellHint(unavailableShell),
+        }, true);
     }
     if (startError || !child) {
         return textResult({ error: `Failed to start command (${effectiveShell}): ${startError ?? 'unknown error'}`, cwd, shell: effectiveShell }, true);
@@ -1135,11 +2028,27 @@ async function startTool(args, roots, ownerScope, context) {
         running: true,
         exitCode: null,
         startedAt: Date.now(),
+        lastActivityAt: Date.now(),
+        ...(detached ? { detached: true } : {}),
     };
     table.set(id, session);
-    const append = makeAppender(() => session.output, (v, t) => { session.output = v; session.truncated = t || session.truncated; });
-    child.stdout?.on('data', (d) => append(d.toString()));
-    child.stderr?.on('data', (d) => append(d.toString()));
+    const append = makeAppender(() => session.output, (v, t) => { session.output = v; session.truncated = t || session.truncated; }, maxOutputChars);
+    const spool = createOutputSpool(outputFilePath);
+    const decodeStdout = createStreamDecoder(encodingMode);
+    const decodeStderr = createStreamDecoder(encodingMode);
+    child.stdout?.on('data', (d) => {
+        const chunk = decodeStdout(d);
+        touchSession(session);
+        append(chunk);
+        spool.write(chunk);
+    });
+    child.stderr?.on('data', (d) => {
+        const chunk = decodeStderr(d);
+        session.stderrChars = (session.stderrChars ?? 0) + chunk.length;
+        touchSession(session);
+        append(chunk);
+        spool.write(chunk);
+    });
     child.on('error', (err) => {
         append(`\n${err.message}`);
         session.running = false;
@@ -1150,9 +2059,23 @@ async function startTool(args, roots, ownerScope, context) {
         session.running = false;
         session.exitCode = code;
         session.endedAt = Date.now();
+        spool.close();
         scheduleReap(session);
     });
-    return textResult({ sessionId: id, cwd, requestedShell, shell: effectiveShell, ...warn });
+    const dialectWarnings = detectDialectMismatch(command, effectiveShell);
+    session.missingExecutableWarning = dialectWarnings.some((warning) => /not found on PATH|not available as an executable/.test(warning));
+    return textResult({
+        sessionId: id,
+        cwd,
+        requestedShell,
+        shell: effectiveShell,
+        ...(detached ? { detached: true } : {}),
+        ...(shellSubstitution ? { shellSubstitution } : {}),
+        ...(selection.autoSelected ? { shellAutoSelected: true } : {}),
+        ...(dialectWarnings.length ? { dialectWarnings } : {}),
+        ...(outputFilePath ? { outputFile: outputFilePath } : {}),
+        ...warn,
+    });
 }
 function snapshot(session, extra = {}) {
     return {
@@ -1161,6 +2084,9 @@ function snapshot(session, extra = {}) {
         exitCode: session.exitCode,
         output: session.output,
         truncated: session.truncated,
+        stderrChars: session.stderrChars ?? 0,
+        ...(session.missingExecutableWarning && (session.exitCode === 9009 || session.exitCode === 255 || session.exitCode === 1)
+            ? { hint: 'A referenced executable was not found — see dialectWarnings.' } : {}),
         ...extra,
     };
 }
@@ -1181,8 +2107,7 @@ async function waitTool(args, ownerScope, context) {
     if (context?.signal?.aborted) {
         return textResult(snapshot(session, { timedOut: false, cancelled: true }), true);
     }
-    const timeoutSec = typeof args.timeout === 'number' && args.timeout > 0 ? args.timeout : DEFAULT_TIMEOUT_MS / 1000;
-    const timeoutMs = Math.min(timeoutSec * 1000, MAX_TIMEOUT_MS);
+    const timeoutMs = resolveCommandTimeoutMs(args.timeout);
     const progress = createCommandProgressReporter(context);
     const outcome = await new Promise((resolve) => {
         let settled = false;
@@ -1215,7 +2140,9 @@ async function waitTool(args, ownerScope, context) {
             }
             pollTimer = setTimeout(poll, 100);
         };
-        timeoutTimer = setTimeout(() => void finish('timedOut'), timeoutMs);
+        if (timeoutMs !== undefined) {
+            timeoutTimer = setTimeout(() => void finish('timedOut'), timeoutMs);
+        }
         context?.signal?.addEventListener('abort', onAbort, { once: true });
         poll();
     });
@@ -1249,6 +2176,7 @@ function killTool(args, ownerScope) {
     if (session.running) {
         session.cancelEscalation = killProcessTree(session.child);
     }
+    touchSession(session);
     return textResult({ sessionId: id, killed: true });
 }
 function listSessionsTool(ownerScope) {
@@ -1259,11 +2187,28 @@ function listSessionsTool(ownerScope) {
         command: s.command,
         running: s.running,
         exitCode: s.exitCode,
+        detached: s.detached === true,
         startedAt: new Date(s.startedAt).toISOString(),
         endedAt: s.endedAt ? new Date(s.endedAt).toISOString() : undefined,
     }));
     return textResult({ sessions: list });
 }
+/**
+ * Release every non-detached session of the CALLING scope.
+ *
+ * The scope is host-derived (`_meta.flujo.ownerScope`), never a tool argument, so
+ * a caller can only ever release its own sessions - releasing by arbitrary scope
+ * would be a cross-run kill primitive.
+ */
+function releaseOwnerTool(ownerScope) {
+    const released = releaseOwnerScope(ownerScope);
+    return textResult({
+        ownerScope: released.ownerScope,
+        killedSessions: released.killedSessions,
+        closedTerminals: released.closedTerminals,
+        retainedDetached: released.retainedDetached,
+    });
+}
 function terminalSnapshot(session) {
     return {
         sessionId: session.id,
@@ -1301,10 +2246,28 @@ async function openTerminalTool(args, roots, ownerScope) {
     if (ownedRunning.length >= MAX_SESSIONS) {
         return textResult({ error: `Too many active terminal sessions (max ${MAX_SESSIONS}). Close one first.` }, true);
     }
+    // Issue #413: PTY sessions count against the SAME host-wide live cap as
+    // background sessions - a terminal is just as much a live process tree.
+    expireStaleSessions();
+    const hostLimit = maxLiveSessionsHost();
+    if (liveSessionCount() >= hostLimit) {
+        return textResult({
+            error: `Too many live sessions on this host (max ${hostLimit} across background and terminal sessions). Close one first.`,
+            liveSessions: liveSessionCount(),
+        }, true);
+    }
+    if (ownerLiveSessionCount(ownerScope) >= MAX_SESSIONS) {
+        return textResult({ error: `Too many live sessions for this caller (max ${MAX_SESSIONS}). Close one first.` }, true);
+    }
+    registerExitCleanup();
     const cwd = await resolveCwd(args.cwd, roots);
     const plan = buildPtySpawn(shellValidation.shell);
     if (plan.unavailableShell) {
-        return textResult({ error: `Requested shell "${plan.unavailableShell}" is unavailable or could not be resolved.` }, true);
+        return textResult({
+            error: `Requested shell "${plan.unavailableShell}" is unavailable or could not be resolved.`,
+            availableShells: availableShellNames(),
+            hint: 'Call "shell_info" to see which shells and interpreters exist on this machine.',
+        }, true);
     }
     if (plan.startError)
         return textResult({ error: plan.startError }, true);
@@ -1345,9 +2308,14 @@ async function openTerminalTool(args, roots, ownerScope) {
         running: true,
         exitCode: null,
         startedAt: Date.now(),
+        lastActivityAt: Date.now(),
+        ...(args.detached === true || args.persistAfterRun === true ? { detached: true } : {}),
     };
     terminalSessions().set(id, session);
-    pty.onData((chunk) => appendTerminalOutput(session, chunk));
+    pty.onData((chunk) => {
+        touchSession(session);
+        appendTerminalOutput(session, chunk);
+    });
     pty.onExit(({ exitCode }) => {
         session.running = false;
         session.exitCode = exitCode;
@@ -1365,6 +2333,7 @@ function readTerminalTool(args, ownerScope) {
     const session = ownedTerminal(id, ownerScope);
     if (!session)
         return textResult({ error: `No terminal session with id "${id}".` }, true);
+    touchSession(session);
     const requested = Number.isFinite(args.cursor) ? Math.max(0, Math.floor(Number(args.cursor))) : session.outputStart;
     const reset = requested < session.outputStart || requested > session.nextCursor;
     const cursor = reset ? session.outputStart : requested;
@@ -1386,6 +2355,7 @@ function writeTerminalTool(args, ownerScope) {
     if (data.length > 65_536)
         return textResult({ error: 'Terminal input is limited to 65,536 characters per write.' }, true);
     try {
+        touchSession(session);
         session.pty.write(data);
         return textResult({ sessionId: id, written: Buffer.byteLength(data, 'utf8') });
     }
@@ -1456,6 +2426,8 @@ export async function bashCallTool(toolName, args, callerNodeId, ownerScope, con
                 return closeTerminalTool(args, scope);
             case 'terminal_list':
                 return listTerminalsTool(scope);
+            case 'shell_info':
+                return shellInfoTool();
             case 'run': {
                 const roots = await loadEffectiveRoots(BASH_SERVER_NAME, BASH_ROOT_ENV_VARS, callerNodeId);
                 return await runTool(args, roots, context);
@@ -1474,6 +2446,8 @@ export async function bashCallTool(toolName, args, callerNodeId, ownerScope, con
                 return killTool(args, scope);
             case 'list_sessions':
                 return listSessionsTool(scope);
+            case 'release_owner':
+                return releaseOwnerTool(scope);
             default:
                 return textResult({ error: `Unknown tool on the built-in bash server: ${toolName}` }, true);
         }