fauxnix-cli 0.7.0 → 0.8.0

package/dist/commands/text-filters.js

@@ -77,7 +77,7 @@ function textExpr(w) {
     return exprOfWord(w);
 }
 /** Collect EVERY value of a short option (-kN, -k N) — parseWords keeps only the last. */
-function collectShortValues(args, letter, longName) {
+function collectShortValues(args, letter) {
     const out = [];
     let onlyOps = false;
     for (let i = 0; i < args.length; i++) {
@@ -88,9 +88,7 @@ function collectShortValues(args, letter, longName) {
         }
         if (onlyOps)
             continue;
-        if (longName && t.startsWith(longName + '='))
-            out.push(t.slice(longName.length + 1));
-        else if (t === '-' + letter) {
+        if (t === '-' + letter) {
             if (i + 1 < args.length) {
                 out.push(wordToString(args[i + 1]));
                 i++;
@@ -102,6 +100,32 @@ function collectShortValues(args, letter, longName) {
     }
     return out;
 }
+/** Collect repeated value-taking long options without mistaking short bundles for values. */
+function collectLongValues(args, names) {
+    const out = [];
+    let onlyOps = false;
+    for (let i = 0; i < args.length; i++) {
+        const t = wordToString(args[i]);
+        if (t === '--') {
+            onlyOps = true;
+            continue;
+        }
+        if (onlyOps || !t.startsWith('--'))
+            continue;
+        const eq = t.indexOf('=');
+        const name = eq >= 0 ? t.slice(0, eq) : t;
+        if (!names.includes(name))
+            continue;
+        if (eq >= 0) {
+            out.push({ name, value: t.slice(eq + 1) });
+        }
+        else if (i + 1 < args.length) {
+            out.push({ name, value: wordToString(args[i + 1]) });
+            i++;
+        }
+    }
+    return out;
+}
 /** Build the "collect file operands through fx-glob" PS prologue. */
 function psCollectSources(filesExpr, cmdErr, leafOnly) {
     const test = leafOnly
@@ -238,8 +262,19 @@ function ereToDotNet(re) {
 /* grep                                                                */
 /* ------------------------------------------------------------------ */
 const grep = (args) => {
-    const includeGlobs = collectShortValues(args, '', '--include');
-    const { flags, operandWords, values } = parseWords(args, ['A', 'B', 'C']);
+    const filterOptionNames = ['--include', '--exclude', '--exclude-dir'];
+    const filterOptions = collectLongValues(args, filterOptionNames);
+    const fileFilterOptions = filterOptions.filter((o) => o.name !== '--exclude-dir');
+    const excludeDirGlobs = filterOptions
+        .filter((o) => o.name === '--exclude-dir')
+        .map((o) => o.value.replace(/[\\/]+$/, ''));
+    const { flags, operandWords, values, missingValue } = parseWords(args, ['A', 'B', 'C'], filterOptionNames);
+    const missingFilterOption = missingValue.find((o) => filterOptionNames.includes(o));
+    if (missingFilterOption) {
+        return ('[Console]::Error.WriteLine(' +
+            psStr("grep: option '" + missingFilterOption + "' requires an argument") +
+            '); $script:fx_exit = 2');
+    }
     const ci = flags.has('i');
     const inv = flags.has('v');
     const num = flags.has('n');
@@ -320,23 +355,68 @@ const grep = (args) => {
     // --- source collection -------------------------------------------------
     if (fileWords.length > 0) {
         lines.push(PS_GLOB_FN);
-        lines.push('$fx_inc = @(' + includeGlobs.map((g) => psStr(g)).join(', ') + ')', '$fx_srcs = @()', '$fx_err = $false', '$fx_recd = $false');
+        lines.push('$fx_fsel = @(' +
+            fileFilterOptions
+                .map((o) => '[pscustomobject]@{ Keep = ' +
+                pb(o.name === '--include') +
+                '; Glob = ' +
+                psStr(o.value) +
+                ' }')
+                .join(', ') +
+            ')', '$fx_excd = @(' + excludeDirGlobs.map((g) => psStr(g)).join(', ') + ')', '$fx_srcs = @()', '$fx_err = $false', '$fx_recd = $false');
+        lines.push('function fx-globmatch($fx_name, $fx_glob, $fx_suffix) {');
+        lines.push("  $fx_n = ([string]$fx_name).Replace('\\', '/')");
+        lines.push("  $fx_p = ([string]$fx_glob).Replace('\\', '/')");
+        lines.push('  if ($fx_n -like $fx_p) { return $true }');
+        lines.push('  if ($fx_suffix) {');
+        lines.push("    $fx_slash = $fx_n.IndexOf('/')");
+        lines.push('    while ($fx_slash -ge 0 -and $fx_slash + 1 -lt $fx_n.Length) {');
+        lines.push('      $fx_n = $fx_n.Substring($fx_slash + 1)');
+        lines.push('      if ($fx_n -like $fx_p) { return $true }');
+        lines.push("      $fx_slash = $fx_n.IndexOf('/')");
+        lines.push('    }');
+        lines.push('  }');
+        lines.push('  return $false');
+        lines.push('}');
+        lines.push('function fx-anyglob($fx_name, $fx_globs, $fx_suffix) {');
+        lines.push('  foreach ($fx_glob in $fx_globs) { if (fx-globmatch $fx_name $fx_glob $fx_suffix) { return $true } }');
+        lines.push('  return $false');
+        lines.push('}');
+        lines.push('function fx-filewanted($fx_path, $fx_suffix) {');
+        lines.push('  if ($fx_fsel.Count -eq 0) { return $true }');
+        lines.push('  $fx_name = if ($fx_suffix) { [string]$fx_path } else { [IO.Path]::GetFileName([string]$fx_path) }');
+        lines.push('  $fx_keep = -not [bool]$fx_fsel[0].Keep');
+        lines.push('  foreach ($fx_rule in $fx_fsel) { if (fx-globmatch $fx_name $fx_rule.Glob $fx_suffix) { $fx_keep = [bool]$fx_rule.Keep } }');
+        lines.push('  return $fx_keep');
+        lines.push('}');
+        if (rec) {
+            lines.push('function fx-walkfiles($fx_root) {');
+            lines.push('  $fx_dirs = New-Object System.Collections.Stack');
+            lines.push('  $fx_dirs.Push([string]$fx_root)');
+            lines.push('  while ($fx_dirs.Count -gt 0) {');
+            lines.push('    $fx_cur = [string]$fx_dirs.Pop()');
+            lines.push('    foreach ($fx_item in @(Get-ChildItem -LiteralPath $fx_cur -Force -ErrorAction SilentlyContinue)) {');
+            lines.push('      if ($fx_item.PSIsContainer) {');
+            lines.push('        if (($fx_item.Attributes -band [IO.FileAttributes]::ReparsePoint) -eq 0 -and -not (fx-anyglob $fx_item.Name $fx_excd $false)) { $fx_dirs.Push($fx_item.FullName) }');
+            lines.push('      } elseif (fx-filewanted $fx_item.FullName $false) { $fx_item.FullName }');
+            lines.push('    }');
+            lines.push('  }');
+            lines.push('}');
+        }
         lines.push('foreach ($fx_o in ' + psArray(fileWords) + ') {');
         lines.push('  foreach ($fx_g in (fx-glob $fx_o)) {');
         lines.push("    if (-not (Test-Path -LiteralPath $fx_g)) { [Console]::Error.WriteLine('grep: ' + $fx_g + ': No such file or directory'); $fx_err = $true; continue }");
         lines.push('    if (Test-Path -LiteralPath $fx_g -PathType Container) {');
         if (rec) {
+            lines.push('      $fx_dir = Get-Item -LiteralPath $fx_g');
+            lines.push('      if (fx-anyglob $fx_g $fx_excd $true) { continue }');
             lines.push('      $fx_recd = $true');
-            lines.push('      $fx_subs = @(Get-ChildItem -LiteralPath $fx_g -Recurse -Force -File -ErrorAction SilentlyContinue)');
-            lines.push('      if ($fx_inc.Count -gt 0) {');
-            lines.push("        $fx_subs = @($fx_subs | Where-Object { $fx_ok = $false; foreach ($fx_gi in $fx_inc) { if ($_.Name -like $fx_gi) { $fx_ok = $true; break } }; $fx_ok })");
-            lines.push('      }');
-            lines.push('      foreach ($fx_s in $fx_subs) { $fx_srcs += $fx_s.FullName }');
+            lines.push('      $fx_srcs += @(fx-walkfiles $fx_dir.FullName)');
         }
         else {
             lines.push("      [Console]::Error.WriteLine('grep: ' + $fx_g + ': Is a directory'); $fx_err = $true");
         }
-        lines.push('    } else { $fx_srcs += $fx_g }');
+        lines.push('    } elseif (fx-filewanted $fx_g $true) { $fx_srcs += $fx_g }');
         lines.push('  }');
         lines.push('}');
         lines.push('$fx_pre = $false');

package/dist/commands/text-io.d.ts

@@ -1,2 +1,3 @@
-import { Handler } from '../registry.js';
+import { CommandSpec, Handler } from '../registry.js';
+export declare const specs: CommandSpec[];
 export declare const handlers: Record<string, Handler>;

package/dist/commands/text-io.js

@@ -691,8 +691,8 @@ const wc = (args) => {
 /* tee                                                                 */
 /* ------------------------------------------------------------------ */
 const tee = (args, ctx) => {
-    const { flags, operandWords } = parseWords(args);
-    const append = flags.has('a') || flags.has('append');
+    const { flags, longs, operandWords } = parseWords(args);
+    const append = flags.has('a') || longs.has('--append');
     return [
         PS_WRITE_FN,
         fxTermLine(ctx.position),
@@ -1142,6 +1142,18 @@ const xargs = (args) => {
     ].join('\n');
 };
 /* ------------------------------------------------------------------ */
+export const specs = [
+    {
+        names: ['tee'],
+        options: [
+            { short: 'a', long: '--append', support: 'implemented' },
+        ],
+        effects: ['read', 'write'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: tee,
+    },
+];
 export const handlers = {
     echo,
     printf,
@@ -1149,7 +1161,6 @@ export const handlers = {
     head,
     tail,
     wc,
-    tee,
     nl,
     tac,
     md5sum,

package/dist/executor.d.ts

@@ -3,14 +3,22 @@ export interface ExecResult {
     stdout: string;
     stderr: string;
     exitCode: number;
+    timedOut: boolean;
+    cancelled: boolean;
+    truncated: boolean;
+    spawnError?: 'ENOENT' | 'START';
 }
 export interface ExecOptions {
     timeoutMs?: number;
     /** Extra environment layered over the session (used by MCP per-call cwd). */
     cwd?: string;
+    signal?: AbortSignal;
+    stdoutLimit?: number;
+    stderrLimit?: number;
 }
 /** Session persists cwd and env across segments, like a real shell. */
 export declare class FauxnixSession {
+    id: string;
     cwd: string | null;
     env: Record<string, string>;
     /** Exit code of the previous segment — powers bash's `$?`. */
@@ -20,14 +28,18 @@ export declare class FauxnixSession {
     private scriptFile;
     private hostFile;
     private host;
-    private runLock;
+    private lifecycleLock;
     constructor();
     private bindFiles;
+    private withLock;
     private syncFromDisk;
     private ensureHost;
     /** Boot powershell.exe now so the first run() is not the 1.1s cold start. */
     prewarm(): Promise<void>;
     dispose(): Promise<void>;
+    /** Kill the host and re-prewarm the same session object (no second FauxnixSession). */
+    reset(): Promise<void>;
+    private disposeUnlocked;
     /** env for the child powershell process. */
     childEnv(cwdOverride?: string, stdinFile?: string | null): NodeJS.ProcessEnv;
     run(plans: SegmentPlan[], opts?: ExecOptions): Promise<ExecResult>;

package/dist/executor.js

@@ -5,8 +5,13 @@ import path from 'node:path';
 import { normalizeLiteralPath, wrapScript } from './translator.js';
 import { decodeOutput, normalizeHostNewlines, resolveNativePref } from './encoding.js';
 import { normalizeStderr } from './errors.js';
-import { PowerShellHost, PS_MISSING_MESSAGE } from './ps-host.js';
+import { DEFAULT_STDERR_LIMIT, DEFAULT_STDOUT_LIMIT, PowerShellHost, PS_MISSING_MESSAGE, } from './ps-host.js';
 const DEFAULT_TIMEOUT_MS = 120_000;
+const DEFAULT_WINDOWS_PATHEXT = '.COM;.EXE;.BAT;.CMD';
+function hasEnvKey(env, name) {
+    const normalized = name.toUpperCase();
+    return Object.keys(env).some((key) => key.toUpperCase() === normalized);
+}
 /** Resolve /dev/null and POSIX-ish literal targets to real Windows paths. */
 function winTarget(target) {
     const p = normalizeLiteralPath(target);
@@ -148,6 +153,7 @@ function planRedirects(redirects) {
 }
 /** Session persists cwd and env across segments, like a real shell. */
 export class FauxnixSession {
+    id;
     cwd = null;
     env = {};
     /** Exit code of the previous segment — powers bash's `$?`. */
@@ -157,16 +163,23 @@ export class FauxnixSession {
     scriptFile;
     hostFile;
     host = null;
-    runLock = Promise.resolve();
+    lifecycleLock = Promise.resolve();
     constructor() {
-        this.bindFiles(randomUUID().slice(0, 8));
+        this.id = randomUUID().slice(0, 8);
+        this.bindFiles(this.id);
     }
     bindFiles(id) {
+        this.id = id;
         this.cwdFile = path.join(os.tmpdir(), 'fauxnix-' + id + '-cwd.txt');
         this.envFile = path.join(os.tmpdir(), 'fauxnix-' + id + '-env.json');
         this.scriptFile = path.join(os.tmpdir(), 'fauxnix-' + id + '-script.ps1');
         this.hostFile = path.join(os.tmpdir(), 'fauxnix-' + id + '-host.ps1');
     }
+    withLock(fn) {
+        const done = this.lifecycleLock.then(fn, fn);
+        this.lifecycleLock = done.then(() => undefined, () => undefined);
+        return done;
+    }
     syncFromDisk() {
         try {
             if (existsSync(this.cwdFile)) {
@@ -196,10 +209,22 @@ export class FauxnixSession {
         return this.host;
     }
     /** Boot powershell.exe now so the first run() is not the 1.1s cold start. */
-    async prewarm() {
-        await this.ensureHost().ready();
+    prewarm() {
+        return this.withLock(async () => {
+            await this.ensureHost().ready();
+        });
     }
-    async dispose() {
+    dispose() {
+        return this.withLock(() => this.disposeUnlocked());
+    }
+    /** Kill the host and re-prewarm the same session object (no second FauxnixSession). */
+    reset() {
+        return this.withLock(async () => {
+            await this.disposeUnlocked();
+            await this.ensureHost().ready();
+        });
+    }
+    async disposeUnlocked() {
         if (this.host) {
             await this.host.stop();
             this.host = null;
@@ -224,6 +249,14 @@ export class FauxnixSession {
             else
                 env[k] = v;
         }
+        // The MCP SDK's safe Windows stdio environment omits PATHEXT. Without it,
+        // PowerShell cannot resolve extensionless native commands such as `node`.
+        // Windows environment names are case-insensitive, so preserve any explicit
+        // spelling/value supplied by the caller and only restore the OS default
+        // when no variant is present at all.
+        if (process.platform === 'win32' && !hasEnvKey(env, 'PATHEXT')) {
+            env.PATHEXT = DEFAULT_WINDOWS_PATHEXT;
+        }
         env.FAUXNIX_CWD_FILE = this.cwdFile;
         env.FAUXNIX_ENV_FILE = this.envFile;
         if (stdinFile)
@@ -242,16 +275,22 @@ export class FauxnixSession {
         return env;
     }
     run(plans, opts = {}) {
-        const done = this.runLock.then(() => runPlans(plans, this, opts, () => this.syncFromDisk(), () => this.ensureHost()));
-        this.runLock = done.then(() => undefined, () => undefined);
-        return done;
+        return this.withLock(() => runPlans(plans, this, opts, () => this.syncFromDisk(), () => this.ensureHost()));
     }
 }
 async function runPlans(plans, session, opts, afterSegment, ensureHost) {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    const deadline = Date.now() + timeoutMs;
+    const stdoutLimit = opts.stdoutLimit ?? DEFAULT_STDOUT_LIMIT;
+    const stderrLimit = opts.stderrLimit ?? DEFAULT_STDERR_LIMIT;
+    const timeoutMessage = '\nbash: command timed out after ' + Math.round(timeoutMs / 1000) + 's';
     let stdout = '';
     let stderr = '';
     let exitCode = 0;
+    let timedOut = false;
+    let cancelled = false;
+    let truncated = false;
+    let spawnError;
     // bash list semantics: `a && b ; c` runs c regardless of a; `a && b && c`
     // skips b AND c when a fails. chainOk models the value of the current
     // &&/|| chain; `;` segments always run and restart the chain.
@@ -267,6 +306,19 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             continue;
         if (plan.op === '||' && chainOk)
             continue;
+        if (opts.signal?.aborted) {
+            cancelled = true;
+            exitCode = 130;
+            session.prevExit = exitCode;
+            break;
+        }
+        if (Date.now() >= deadline) {
+            stderr += timeoutMessage;
+            exitCode = 124;
+            timedOut = true;
+            session.prevExit = exitCode;
+            break;
+        }
         const red = planRedirects(plan.redirects);
         red.stdinFile = red.stdinFile ? resolveTarget(red.stdinFile) : null;
         red.stdoutFile = red.stdoutFile ? resolveTarget(red.stdoutFile) : null;
@@ -339,19 +391,41 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
                 chainOk = false;
                 continue;
             }
+            const remainingMs = deadline - Date.now();
+            if (opts.signal?.aborted) {
+                cancelled = true;
+                exitCode = 130;
+                session.prevExit = exitCode;
+                break;
+            }
+            if (remainingMs <= 0) {
+                stderr += timeoutMessage;
+                exitCode = 124;
+                timedOut = true;
+                session.prevExit = exitCode;
+                break;
+            }
             const encoded = wrapScript(plan.body, { mode: 'host' });
             const inv = await ensureHost().invoke(encoded, {
                 FAUXNIX_CWD: currentDir,
                 FAUXNIX_PREV_EXIT: session.prevExit === null ? '' : String(session.prevExit),
                 FAUXNIX_STDIN_FILE: red.stdinFile || '',
-            }, timeoutMs);
-            if (inv.spawnError === 'ENOENT') {
+            }, remainingMs, opts.signal);
+            if (inv.spawnError === 'ENOENT' || inv.spawnError === 'START') {
                 stderr += inv.stderr.toString('utf8') || PS_MISSING_MESSAGE;
                 exitCode = 127;
+                spawnError = inv.spawnError;
                 session.prevExit = exitCode;
                 chainOk = false;
                 continue;
             }
+            if (inv.cancelled) {
+                cancelled = true;
+                exitCode = 130;
+                session.prevExit = exitCode;
+                chainOk = false;
+                break;
+            }
             afterSegment();
             const decodePref = resolveNativePref();
             // GNU line discipline: the PS host terminates Write-Output lines with
@@ -360,7 +434,7 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             let segOut = normalizeHostNewlines(decodeOutput(inv.stdout, decodePref));
             let segErr = normalizeHostNewlines(normalizeStderr(decodeOutput(inv.stderr, decodePref)));
             if (inv.timedOut) {
-                segErr += '\nbash: command timed out after ' + Math.round(timeoutMs / 1000) + 's';
+                segErr += timeoutMessage;
             }
             if (red.mergeStderr) {
                 segOut += (segOut && !segOut.endsWith('\n') && segErr ? '\n' : '') + segErr;
@@ -402,7 +476,11 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             }
             stdout += segOut;
             stderr += segErr;
-            exitCode = inv.timedOut ? 124 : inv.exitCode;
+            if (inv.truncated)
+                truncated = true;
+            exitCode = inv.timedOut ? 124 : inv.cancelled ? 130 : inv.exitCode;
+            if (inv.timedOut)
+                timedOut = true;
             session.prevExit = exitCode;
             chainOk = exitCode === 0;
             // Only inherit cwd from a segment that actually ran and whose
@@ -410,10 +488,32 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             // not move later relative redirects.
             if (redirectOk && session.cwd)
                 currentDir = session.cwd;
+            if (inv.timedOut)
+                break;
         }
         finally {
             closePrepFds(prepFds);
         }
     }
-    return { stdout, stderr, exitCode };
+    const clippedOut = clipUtf8(stdout, stdoutLimit);
+    const clippedErr = clipUtf8(stderr, stderrLimit);
+    if (clippedOut.truncated || clippedErr.truncated)
+        truncated = true;
+    return {
+        stdout: clippedOut.text,
+        stderr: clippedErr.text,
+        exitCode,
+        timedOut,
+        cancelled,
+        truncated,
+        spawnError,
+    };
+}
+function clipUtf8(text, limit) {
+    if (Buffer.byteLength(text, 'utf8') <= limit)
+        return { text, truncated: false };
+    let end = text.length;
+    while (end > 0 && Buffer.byteLength(text.slice(0, end), 'utf8') > limit)
+        end--;
+    return { text: text.slice(0, end), truncated: true };
 }

package/dist/mcp.d.ts

@@ -1,4 +1,23 @@
+import { ExecResult } from './executor.js';
 import { translatePipelineBody } from './translator.js';
 import './commands/install-all.js';
+export declare function formatBashText(r: Pick<ExecResult, 'stdout' | 'stderr' | 'exitCode' | 'timedOut' | 'cancelled'>): string;
+export declare function bashToolResult(r: ExecResult, sessionId: string, infra: boolean): {
+    isError?: true | undefined;
+    content: {
+        type: "text";
+        text: string;
+    }[];
+    structuredContent: {
+        schemaVersion: 1;
+        stdout: string;
+        stderr: string;
+        exitCode: number;
+        timedOut: boolean;
+        cancelled: boolean;
+        truncated: boolean;
+        sessionId: string;
+    };
+};
 export declare function startMcpServer(): Promise<void>;
 export { translatePipelineBody };

package/dist/mcp.js

@@ -1,16 +1,12 @@
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
-import { readFileSync } from 'node:fs';
-import { fileURLToPath } from 'node:url';
 import { z } from 'zod';
 import { FauxnixSession } from './executor.js';
 import { parseCommand } from './parser.js';
 import { translateCommandList, wrapScript, translatePipelineBody } from './translator.js';
 import { registeredNames } from './registry.js';
+import { packageVersion } from './version.js';
 import './commands/install-all.js';
-// single source of truth: the npm package version in package.json
-// (src/ and dist/ sit one level below the root, so the relative path holds in both)
-const pkgVersion = JSON.parse(readFileSync(fileURLToPath(new URL('../package.json', import.meta.url)), 'utf8')).version;
 const TOOL_NAME = process.env.FAUXNIX_TOOL_NAME || 'bash';
 const EXEC_ANNOTATIONS = {
     readOnlyHint: false,
@@ -37,15 +33,46 @@ Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), e
 
 Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), variables ($VAR $HOME ~), command substitution $(...), and ${registeredNames().length}+ coreutils-style commands (${registeredNames().slice(0, 18).join(', ')}...).
 Unknown commands (git, node, npm, python, cargo...) are passed through and executed natively with argv-style quoting.
-Not supported: heredocs, while/until/case, background jobs. if/then/elif/else/fi, for-in loops, and word-level \$((...)) arithmetic expansion are supported.
+Not supported: heredocs, while/until/case, env -i/--ignore-environment, background jobs. if/then/elif/else/fi, for-in loops, and word-level \$((...)) arithmetic expansion are supported.
 
 CWD, environment variables, export/unset and cd persist across calls within this session — a resident PowerShell 5.1 host is started when the MCP session begins (and after reset), so the first bash tool call is already warm.
-Exit codes follow bash conventions (0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout).
+Exit codes follow bash conventions (0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout, 130 cancelled). The tool also returns structuredContent (schemaVersion 1) with stdout/stderr/exitCode/timedOut/cancelled/truncated/sessionId.
 
 Platform requirement: the execution backend is native Windows PowerShell 5.1+. On hosts without PowerShell on PATH (e.g. Linux containers/sandboxes), the bash tool returns exit code 127 with an actionable error instead of running the command.`;
+export function formatBashText(r) {
+    const parts = [];
+    if (r.stdout.length)
+        parts.push(r.stdout.replace(/\n$/, ''));
+    if (r.stderr.length)
+        parts.push(r.stderr.replace(/\n$/, ''));
+    if (r.cancelled)
+        parts.push('Cancelled');
+    else if (r.timedOut)
+        parts.push('Exit code: 124');
+    else if (r.exitCode !== 0)
+        parts.push('Exit code: ' + r.exitCode);
+    return parts.length ? parts.join('\n') : '(no output)';
+}
+export function bashToolResult(r, sessionId, infra) {
+    const structuredContent = {
+        schemaVersion: 1,
+        stdout: r.stdout,
+        stderr: r.stderr,
+        exitCode: r.exitCode,
+        timedOut: r.timedOut,
+        cancelled: r.cancelled,
+        truncated: r.truncated,
+        sessionId,
+    };
+    return {
+        content: [{ type: 'text', text: formatBashText(r) }],
+        structuredContent,
+        ...(infra ? { isError: true } : {}),
+    };
+}
 export async function startMcpServer() {
-    const server = new McpServer({ name: 'fauxnix', version: pkgVersion }, { capabilities: { tools: {} } });
-    let session = new FauxnixSession();
+    const server = new McpServer({ name: 'fauxnix', version: packageVersion }, { capabilities: { tools: {} } });
+    const session = new FauxnixSession();
     await session.prewarm();
     server.tool(TOOL_NAME, TOOL_DESCRIPTION, {
         command: z.string().describe('The bash-style command line to run'),
@@ -56,23 +83,26 @@ export async function startMcpServer() {
             .max(600_000)
             .optional()
             .describe('Timeout in milliseconds (default 120000)'),
-    }, EXEC_ANNOTATIONS, async ({ command, timeout_ms }) => {
+    }, EXEC_ANNOTATIONS, async ({ command, timeout_ms }, extra) => {
         try {
             const plans = translateCommandList(parseCommand(command));
-            const result = await session.run(plans, { timeoutMs: timeout_ms });
-            const parts = [];
-            if (result.stdout.trim())
-                parts.push(result.stdout.replace(/\n$/, ''));
-            if (result.stderr.trim())
-                parts.push(result.stderr.replace(/\n$/, ''));
-            if (result.exitCode !== 0)
-                parts.push('Exit code: ' + result.exitCode);
-            const text = parts.length ? parts.join('\n') : '(no output)';
-            return { content: [{ type: 'text', text }] };
+            const result = await session.run(plans, {
+                timeoutMs: timeout_ms,
+                signal: extra.signal,
+            });
+            const infra = result.spawnError === 'ENOENT' || result.spawnError === 'START';
+            return bashToolResult(result, session.id, infra);
         }
         catch (e) {
             const msg = e instanceof Error ? e.message : String(e);
-            return { content: [{ type: 'text', text: msg }], isError: true };
+            return bashToolResult({
+                stdout: '',
+                stderr: msg,
+                exitCode: 2,
+                timedOut: false,
+                cancelled: false,
+                truncated: false,
+            }, session.id, true);
         }
     });
     server.tool('fauxnix_translate', 'Translate a bash-style command into the equivalent PowerShell script WITHOUT executing it. Useful for learning/debugging what fauxnix does under the hood.', { command: z.string().describe('The bash-style command line to translate (never executed)') }, TRANSLATE_ANNOTATIONS, async ({ command }) => {
@@ -94,18 +124,45 @@ export async function startMcpServer() {
             .describe('"status" shows the session state (cwd, tracked env keys); "reset" clears it back to a fresh shell'),
     }, SESSION_ANNOTATIONS, async ({ action }) => {
         if (action === 'reset') {
-            await session.dispose();
-            session = new FauxnixSession();
-            await session.prewarm();
+            await session.reset();
             return { content: [{ type: 'text', text: 'fauxnix: session reset' }] };
         }
         const envKeys = Object.keys(session.env).sort();
         const text = 'cwd: ' + (session.cwd ?? '(inherit from server start)') +
             '\nenv keys: ' + (envKeys.length ? envKeys.join(', ') : '(none tracked)') +
+            '\nsession: ' + session.id +
             '\ncommands registered: ' + registeredNames().length;
         return { content: [{ type: 'text', text }] };
     });
     const transport = new StdioServerTransport();
+    let shuttingDown = false;
+    const shutdown = async () => {
+        if (shuttingDown)
+            return;
+        shuttingDown = true;
+        await session.dispose();
+        try {
+            await server.close();
+        }
+        catch {
+            /* ignore */
+        }
+    };
+    process.stdin.on('end', () => {
+        void shutdown();
+    });
+    process.stdin.on('close', () => {
+        void shutdown();
+    });
+    process.on('SIGINT', () => {
+        void shutdown();
+    });
+    process.on('SIGTERM', () => {
+        void shutdown();
+    });
+    transport.onclose = () => {
+        void shutdown();
+    };
     await server.connect(transport);
 }
 // keep referenced for tree-shaking clarity