fauxnix-cli 0.5.1 → 0.6.0

package/dist/executor.d.ts

@@ -18,8 +18,13 @@ export declare class FauxnixSession {
     private cwdFile;
     private envFile;
     private scriptFile;
+    private hostFile;
+    private host;
+    private runLock;
     constructor();
+    private bindFiles;
     private syncFromDisk;
+    private ensureHost;
     dispose(): Promise<void>;
     /** env for the child powershell process. */
     childEnv(cwdOverride?: string, stdinFile?: string | null): NodeJS.ProcessEnv;

package/dist/executor.js

@@ -1,13 +1,12 @@
-import { spawn } from 'node:child_process';
 import { randomUUID } from 'node:crypto';
-import { promises as fs, readFileSync, writeFileSync, existsSync, openSync, closeSync, writeSync } from 'node:fs';
+import { promises as fs, readFileSync, existsSync, openSync, closeSync, writeSync } from 'node:fs';
 import os from 'node:os';
 import path from 'node:path';
-import { normalizeLiteralPath } from './translator.js';
-import { decodeOutput, encodeCommand, normalizeHostNewlines, resolveNativePref } from './encoding.js';
+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';
 const DEFAULT_TIMEOUT_MS = 120_000;
-const PS_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass'];
 /** Resolve /dev/null and POSIX-ish literal targets to real Windows paths. */
 function winTarget(target) {
     const p = normalizeLiteralPath(target);
@@ -156,11 +155,17 @@ export class FauxnixSession {
     cwdFile;
     envFile;
     scriptFile;
+    hostFile;
+    host = null;
+    runLock = Promise.resolve();
     constructor() {
-        const id = randomUUID().slice(0, 8);
+        this.bindFiles(randomUUID().slice(0, 8));
+    }
+    bindFiles(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');
     }
     syncFromDisk() {
         try {
@@ -184,12 +189,27 @@ export class FauxnixSession {
             /* ignore */
         }
     }
+    ensureHost() {
+        if (!this.host) {
+            this.host = new PowerShellHost(this.hostFile, () => this.childEnv());
+        }
+        return this.host;
+    }
     async dispose() {
+        if (this.host) {
+            await this.host.stop();
+            this.host = null;
+        }
+        this.cwd = null;
+        this.env = {};
+        this.prevExit = null;
         await Promise.allSettled([
             fs.rm(this.cwdFile, { force: true }),
             fs.rm(this.envFile, { force: true }),
             fs.rm(this.scriptFile, { force: true }),
+            fs.rm(this.hostFile, { force: true }),
         ]);
+        this.bindFiles(randomUUID().slice(0, 8));
     }
     /** env for the child powershell process. */
     childEnv(cwdOverride, stdinFile) {
@@ -218,10 +238,12 @@ export class FauxnixSession {
         return env;
     }
     run(plans, opts = {}) {
-        return runPlans(plans, this, opts, () => this.syncFromDisk(), this.scriptFile);
+        const done = this.runLock.then(() => runPlans(plans, this, opts, () => this.syncFromDisk(), () => this.ensureHost()));
+        this.runLock = done.then(() => undefined, () => undefined);
+        return done;
     }
 }
-async function runPlans(plans, session, opts, afterSegment, scriptFile) {
+async function runPlans(plans, session, opts, afterSegment, ensureHost) {
     const timeoutMs = opts.timeoutMs ?? DEFAULT_TIMEOUT_MS;
     let stdout = '';
     let stderr = '';
@@ -313,65 +335,27 @@ async function runPlans(plans, session, opts, afterSegment, scriptFile) {
                 chainOk = false;
                 continue;
             }
-            const encoded = encodeCommand(plan.script);
-            // -EncodedCommand is capped by the ~32K command-line limit; heavy
-            // pipelines fall back to a UTF-8 BOM temp script (PS 5.1 honors the BOM
-            // regardless of the console codepage, so non-ASCII stays intact).
-            let psArgs;
-            if (encoded.length > 28000) {
-                writeFileSync(scriptFile, '\ufeff' + plan.script, 'utf8');
-                psArgs = [...PS_ARGS, '-File', scriptFile];
-            }
-            else {
-                psArgs = [...PS_ARGS, '-EncodedCommand', encoded];
-            }
-            const child = spawn('powershell.exe', psArgs, {
-                env: session.childEnv(currentDir, red.stdinFile),
-                stdio: ['pipe', 'pipe', 'pipe'],
-                windowsHide: true,
-            });
-            const running = { proc: child, killed: false };
-            const outBufs = [];
-            const errBufs = [];
-            child.stdout.on('data', (d) => outBufs.push(d));
-            child.stderr.on('data', (d) => errBufs.push(d));
-            child.stdin.end();
-            const timer = setTimeout(() => {
-                running.killed = true;
-                // Node-native termination — no external kill process, nothing injectable.
-                // Grandchildren of a timed-out script may survive; the `kill -9`/`pkill`
-                // builtins remain available for explicit Windows tree kills.
-                try {
-                    child.kill();
-                }
-                catch {
-                    /* best effort */
-                }
+            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);
-            const code = await new Promise((resolve) => {
-                child.on('error', (e) => {
-                    if (e.code === 'ENOENT') {
-                        stderr +=
-                            'fauxnix: powershell.exe not found — fauxnix executes bash via native Windows PowerShell 5.1+.\n' +
-                                'This host has no PowerShell on PATH (typical for Linux containers/sandboxes).\n' +
-                                'Run fauxnix on Windows, or install PowerShell and make powershell.exe reachable on PATH.\n';
-                    }
-                    else {
-                        stderr += 'fauxnix: failed to start powershell.exe: ' + e.message + '\n';
-                    }
-                    resolve(127);
-                });
-                child.on('close', (c) => resolve(running.killed ? 124 : (c ?? 0)));
-            });
-            clearTimeout(timer);
+            if (inv.spawnError === 'ENOENT') {
+                stderr += inv.stderr.toString('utf8') || PS_MISSING_MESSAGE;
+                exitCode = 127;
+                session.prevExit = exitCode;
+                chainOk = false;
+                continue;
+            }
             afterSegment();
             const decodePref = resolveNativePref();
             // GNU line discipline: the PS host terminates Write-Output lines with
             // CRLF. Exact writers (fx-write / printf / echo -n) must keep embedded
             // CR so `printf 'a\r\nb' > out` stays 4 bytes.
-            let segOut = normalizeHostNewlines(decodeOutput(Buffer.concat(outBufs), decodePref));
-            let segErr = normalizeHostNewlines(normalizeStderr(decodeOutput(Buffer.concat(errBufs), decodePref)));
-            if (running.killed) {
+            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';
             }
             if (red.mergeStderr) {
@@ -414,7 +398,7 @@ async function runPlans(plans, session, opts, afterSegment, scriptFile) {
             }
             stdout += segOut;
             stderr += segErr;
-            exitCode = code ?? 0;
+            exitCode = inv.timedOut ? 124 : inv.exitCode;
             session.prevExit = exitCode;
             chainOk = exitCode === 0;
             // Only inherit cwd from a segment that actually ran and whose

package/dist/mcp.js

@@ -39,13 +39,13 @@ Supported: pipes (|), && / || / ;, redirections (> >> 2> 2>&1 < /dev/null), vari
 Unknown commands (git, node, npm, python, cargo...) are passed through and executed natively with argv-style quoting.
 Not supported: heredocs, while/until/case, word-level \$((...)) arithmetic expansion, background jobs. if/then/else/fi and for-in loops are supported.
 
-CWD, environment variables, export/unset and cd persist across calls within this session — but prefer COMBINING related commands in one call with ; or && (e.g. 'cd src && ls | wc -l'); each call is a fresh translation+process, so batching is faster than many tiny calls.
+CWD, environment variables, export/unset and cd persist across calls within this session — a resident PowerShell 5.1 host is reused, so batching with ; or && is still nicer but many tiny calls no longer each pay a powershell.exe spawn.
 Exit codes follow bash conventions (0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout).
 
 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 async function startMcpServer() {
     const server = new McpServer({ name: 'fauxnix', version: pkgVersion }, { capabilities: { tools: {} } });
-    const session = new FauxnixSession();
+    let session = new FauxnixSession();
     server.tool(TOOL_NAME, TOOL_DESCRIPTION, {
         command: z.string().describe('The bash-style command line to run'),
         timeout_ms: z
@@ -94,6 +94,7 @@ export async function startMcpServer() {
     }, SESSION_ANNOTATIONS, async ({ action }) => {
         if (action === 'reset') {
             await session.dispose();
+            session = new FauxnixSession();
             return { content: [{ type: 'text', text: 'fauxnix: session reset' }] };
         }
         const envKeys = Object.keys(session.env).sort();

package/dist/ps-host.d.ts

@@ -0,0 +1,51 @@
+export declare const PS_MISSING_MESSAGE: string;
+export interface HostInvokeResult {
+    stdout: Buffer;
+    stderr: Buffer;
+    exitCode: number;
+    timedOut: boolean;
+    spawnError?: 'ENOENT' | 'START';
+    spawnMessage?: string;
+}
+export interface HostRequestEnv {
+    [key: string]: string;
+}
+export declare function encodeHostRequest(id: string, script: string, env: HostRequestEnv): string;
+export declare function decodeHostResponse(line: string): {
+    id: string;
+    stdout: Buffer;
+    stderr: Buffer;
+    exitCode: number;
+    ready?: boolean;
+};
+/**
+ * One resident powershell.exe 5.1 process. Frames are UTF-8 JSON lines;
+ * command stdout/stderr come back as base64 so PS 5.1's UTF-16LE pipe
+ * encoding cannot scramble the payload.
+ */
+export declare class PowerShellHost {
+    private readonly hostFile;
+    private readonly envFn;
+    private proc;
+    private stdoutBuf;
+    private queuedLines;
+    private waiters;
+    private stderrChunks;
+    private closeCode;
+    private closeErr;
+    private closed;
+    private startLock;
+    private invokeLock;
+    constructor(hostFile: string, envFn: () => NodeJS.ProcessEnv);
+    invoke(script: string, env: HostRequestEnv, timeoutMs: number): Promise<HostInvokeResult>;
+    stop(): Promise<void>;
+    private invokeSerial;
+    private ensureStarted;
+    private deadRestart;
+    private start;
+    private onStdout;
+    private nextLine;
+    private nextReadyLine;
+    private nextJsonLine;
+    private failWaiters;
+}

package/dist/ps-host.js

@@ -0,0 +1,310 @@
+import { spawn } from 'node:child_process';
+import { writeFileSync } from 'node:fs';
+import { hostBootstrapScript } from './translator.js';
+const PS_ARGS = ['-NoProfile', '-NonInteractive', '-ExecutionPolicy', 'Bypass'];
+const READY_TIMEOUT_MS = 30_000;
+export const PS_MISSING_MESSAGE = 'fauxnix: powershell.exe not found — fauxnix executes bash via native Windows PowerShell 5.1+.\n' +
+    'This host has no PowerShell on PATH (typical for Linux containers/sandboxes).\n' +
+    'Run fauxnix on Windows, or install PowerShell and make powershell.exe reachable on PATH.\n';
+export function encodeHostRequest(id, script, env) {
+    return JSON.stringify({
+        id,
+        scriptB64: Buffer.from(script, 'utf8').toString('base64'),
+        env,
+    });
+}
+export function decodeHostResponse(line) {
+    const j = JSON.parse(line);
+    const n = Number(j.exitCode);
+    return {
+        id: j.id ?? '',
+        stdout: Buffer.from(j.stdoutB64 ?? '', 'base64'),
+        stderr: Buffer.from(j.stderrB64 ?? '', 'base64'),
+        exitCode: Number.isFinite(n) ? n : 0,
+        ready: j.ready === true,
+    };
+}
+/**
+ * One resident powershell.exe 5.1 process. Frames are UTF-8 JSON lines;
+ * command stdout/stderr come back as base64 so PS 5.1's UTF-16LE pipe
+ * encoding cannot scramble the payload.
+ */
+export class PowerShellHost {
+    hostFile;
+    envFn;
+    proc = null;
+    stdoutBuf = Buffer.alloc(0);
+    queuedLines = [];
+    waiters = [];
+    stderrChunks = [];
+    closeCode;
+    closeErr = null;
+    closed = false;
+    startLock = null;
+    invokeLock = Promise.resolve();
+    constructor(hostFile, envFn) {
+        this.hostFile = hostFile;
+        this.envFn = envFn;
+    }
+    async invoke(script, env, timeoutMs) {
+        const run = this.invokeLock.then(() => this.invokeSerial(script, env, timeoutMs));
+        this.invokeLock = run.then(() => undefined, () => undefined);
+        return run;
+    }
+    async stop() {
+        const proc = this.proc;
+        this.proc = null;
+        this.closed = true;
+        this.failWaiters(new Error('fauxnix: powershell host stopped'));
+        if (!proc)
+            return;
+        try {
+            proc.stdin?.end();
+        }
+        catch {
+            /* ignore */
+        }
+        try {
+            proc.kill();
+        }
+        catch {
+            /* ignore */
+        }
+        await new Promise((resolve) => {
+            const t = setTimeout(resolve, 2000);
+            proc.once('close', () => {
+                clearTimeout(t);
+                resolve();
+            });
+        });
+    }
+    async invokeSerial(script, env, timeoutMs) {
+        const started = await this.ensureStarted();
+        if (started)
+            return started;
+        const id = 'f' + Date.now().toString(36) + Math.random().toString(36).slice(2, 8);
+        const line = encodeHostRequest(id, script, env);
+        try {
+            this.proc.stdin.write(line + '\n');
+        }
+        catch (e) {
+            await this.deadRestart();
+            return {
+                stdout: Buffer.alloc(0),
+                stderr: Buffer.from('fauxnix: powershell host exited unexpectedly\n', 'utf8'),
+                exitCode: 1,
+                timedOut: false,
+                spawnMessage: e.message,
+            };
+        }
+        try {
+            const raw = await this.nextJsonLine(timeoutMs, id);
+            const msg = decodeHostResponse(raw);
+            return {
+                stdout: msg.stdout,
+                stderr: msg.stderr,
+                exitCode: msg.exitCode,
+                timedOut: false,
+            };
+        }
+        catch (e) {
+            const timedOut = e.timedOut === true;
+            await this.stop();
+            if (timedOut) {
+                return { stdout: Buffer.alloc(0), stderr: Buffer.alloc(0), exitCode: 124, timedOut: true };
+            }
+            if (this.closeErr && this.closeErr.code === 'ENOENT') {
+                return {
+                    stdout: Buffer.alloc(0),
+                    stderr: Buffer.from(PS_MISSING_MESSAGE, 'utf8'),
+                    exitCode: 127,
+                    timedOut: false,
+                    spawnError: 'ENOENT',
+                };
+            }
+            const code = this.closeCode ?? 1;
+            return {
+                stdout: Buffer.alloc(0),
+                stderr: Buffer.from('fauxnix: powershell host exited unexpectedly' +
+                    (code !== 1 ? ' (exit ' + String(code) + ')' : '') +
+                    '\n', 'utf8'),
+                exitCode: code === 0 ? 1 : code,
+                timedOut: false,
+            };
+        }
+    }
+    async ensureStarted() {
+        if (this.proc && !this.closed)
+            return null;
+        if (!this.startLock)
+            this.startLock = this.start();
+        try {
+            await this.startLock;
+            return null;
+        }
+        catch (e) {
+            const err = e;
+            if (err.code === 'ENOENT') {
+                return {
+                    stdout: Buffer.alloc(0),
+                    stderr: Buffer.from(PS_MISSING_MESSAGE, 'utf8'),
+                    exitCode: 127,
+                    timedOut: false,
+                    spawnError: 'ENOENT',
+                };
+            }
+            return {
+                stdout: Buffer.alloc(0),
+                stderr: Buffer.from('fauxnix: failed to start powershell.exe: ' + err.message + '\n', 'utf8'),
+                exitCode: 127,
+                timedOut: false,
+                spawnError: 'START',
+                spawnMessage: err.message,
+            };
+        }
+        finally {
+            this.startLock = null;
+        }
+    }
+    async deadRestart() {
+        await this.stop();
+        this.closed = false;
+        this.closeCode = undefined;
+        this.closeErr = null;
+        this.stdoutBuf = Buffer.alloc(0);
+        this.queuedLines = [];
+        this.stderrChunks = [];
+    }
+    async start() {
+        await this.deadRestart();
+        this.closed = false;
+        writeFileSync(this.hostFile, '\ufeff' + hostBootstrapScript(), 'utf8');
+        const child = spawn('powershell.exe', [...PS_ARGS, '-File', this.hostFile], {
+            env: this.envFn(),
+            stdio: ['pipe', 'pipe', 'pipe'],
+            windowsHide: true,
+        });
+        this.proc = child;
+        child.stdout.on('data', (d) => this.onStdout(d));
+        child.stderr.on('data', (d) => this.stderrChunks.push(d));
+        child.on('error', (e) => {
+            this.closeErr = e;
+            this.closed = true;
+            this.failWaiters(e);
+        });
+        child.on('close', (c) => {
+            this.closeCode = c;
+            this.closed = true;
+            this.proc = null;
+            this.failWaiters(new Error('fauxnix: powershell host closed'));
+        });
+        try {
+            const readyLine = await this.nextReadyLine(READY_TIMEOUT_MS);
+            const msg = decodeHostResponse(readyLine);
+            if (!msg.ready) {
+                throw new Error('fauxnix: powershell host handshake failed');
+            }
+        }
+        catch (e) {
+            await this.stop();
+            throw e;
+        }
+    }
+    onStdout(chunk) {
+        this.stdoutBuf = Buffer.concat([this.stdoutBuf, chunk]);
+        while (true) {
+            const i = this.stdoutBuf.indexOf(0x0a);
+            if (i < 0)
+                break;
+            let line = this.stdoutBuf.subarray(0, i);
+            this.stdoutBuf = this.stdoutBuf.subarray(i + 1);
+            if (line.length && line[line.length - 1] === 0x0d)
+                line = line.subarray(0, line.length - 1);
+            const s = line.toString('utf8').replace(/^\uFEFF/, '');
+            const w = this.waiters.shift();
+            if (w)
+                w.resolve(s);
+            else
+                this.queuedLines.push(s);
+        }
+    }
+    nextLine(timeoutMs) {
+        if (this.queuedLines.length)
+            return Promise.resolve(this.queuedLines.shift());
+        if (this.closed) {
+            return Promise.reject(this.closeErr ?? new Error('fauxnix: powershell host closed'));
+        }
+        return new Promise((resolve, reject) => {
+            const waiter = {
+                resolve: (line) => {
+                    clearTimeout(timer);
+                    resolve(line);
+                },
+                reject: (err) => {
+                    clearTimeout(timer);
+                    reject(err);
+                },
+            };
+            const timer = setTimeout(() => {
+                const idx = this.waiters.indexOf(waiter);
+                if (idx >= 0)
+                    this.waiters.splice(idx, 1);
+                const err = new Error('fauxnix: powershell host timed out');
+                err.timedOut = true;
+                reject(err);
+            }, timeoutMs);
+            this.waiters.push(waiter);
+        });
+    }
+    async nextReadyLine(timeoutMs) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const line = await this.nextLine(Math.max(1, deadline - Date.now()));
+            if (!line.trim())
+                continue;
+            try {
+                const msg = decodeHostResponse(line);
+                if (msg.ready)
+                    return line;
+            }
+            catch {
+                /* skip PS boot noise */
+            }
+        }
+        const err = new Error('fauxnix: powershell host handshake timed out');
+        err.timedOut = true;
+        throw err;
+    }
+    async nextJsonLine(timeoutMs, id) {
+        const deadline = Date.now() + timeoutMs;
+        while (Date.now() < deadline) {
+            const line = await this.nextLine(Math.max(1, deadline - Date.now()));
+            if (!line.trim())
+                continue;
+            try {
+                const msg = decodeHostResponse(line);
+                if (msg.ready)
+                    continue;
+                if (msg.id === id)
+                    return line;
+            }
+            catch {
+                /* skip noise */
+            }
+        }
+        const err = new Error('fauxnix: powershell host timed out');
+        err.timedOut = true;
+        throw err;
+    }
+    failWaiters(err) {
+        const ws = this.waiters.splice(0);
+        for (const w of ws) {
+            try {
+                w.reject(err);
+            }
+            catch {
+                /* ignore */
+            }
+        }
+    }
+}

package/dist/translator.d.ts

@@ -76,16 +76,28 @@ export declare function translatePipelineBody(p: {
 }): PipelineParts;
 export interface SegmentPlan {
     op: ';' | '&&' | '||';
-    /** Complete PowerShell script for one powershell.exe invocation. */
+    /** Spawn-mode wrapScript (CLI/MCP `translate`, one-shot powershell.exe). */
     script: string;
+    /** Pipeline body before wrapScript — executor host mode re-wraps this. */
+    body: string;
     /** All redirects collected from this segment (executor handles them). */
     redirects: Redirect[];
 }
 export declare function translateCommandList(list: CommandList): SegmentPlan[];
+export type WrapMode = 'spawn' | 'host';
+export interface WrapScriptOptions {
+    /** spawn (default): one-shot process, `exit` at the end. host: no `exit`, no helper re-emit. */
+    mode?: WrapMode;
+}
 /**
  * Wrap a pipeline body with the Fauxnix executor contract:
  * UTF-8 everywhere, bash-style exit codes, cwd/env persistence channels.
- * Only the fx- helpers the body actually calls are emitted — the full
- * catalog is ~170 lines and was paid on every `echo hi`.
+ * Spawn mode emits only the fx- helpers the body actually calls. Host mode
+ * assumes the resident process already loaded the catalog and must not `exit`.
+ */
+export declare function wrapScript(body: string, opts?: WrapScriptOptions): string;
+/**
+ * Resident-host bootstrap: encoding + full fx-* catalog + JSON-line RPC loop.
+ * Loaded once via `powershell.exe -File`. Must never `exit` a successful frame.
  */
-export declare function wrapScript(body: string): string;
+export declare function hostBootstrapScript(): string;

package/dist/translator.js

@@ -771,7 +771,7 @@ export function translateCommandList(list) {
                     call +
                     ' }';
         }
-        plans.push({ op: seg.op, script: wrapScript(body), redirects });
+        plans.push({ op: seg.op, script: wrapScript(body), body, redirects });
     }
     return plans;
 }
@@ -833,20 +833,10 @@ function wrapHelpersNeeded(body) {
     }
     return needed;
 }
-/**
- * Wrap a pipeline body with the Fauxnix executor contract:
- * UTF-8 everywhere, bash-style exit codes, cwd/env persistence channels.
- * Only the fx- helpers the body actually calls are emitted — the full
- * catalog is ~170 lines and was paid on every `echo hi`.
- */
-export function wrapScript(body) {
-    const needed = wrapHelpersNeeded(body);
-    const lines = [
+function wrapEncodingPreamble() {
+    return [
         '$ErrorActionPreference = "Continue"',
         "$ProgressPreference = 'SilentlyContinue'",
-        '$fx_exit = 0',
-        '$fx_prev = 0',
-        'if ($env:FAUXNIX_PREV_EXIT) { try { $fx_prev = [int]$env:FAUXNIX_PREV_EXIT } catch { $fx_prev = 0 } }',
         // single console-encoding knob in PS 5.1: ansi mode decodes GBK-native
         // admin tools correctly, utf8 mode decodes UTF-8-native dev tools
         // (see encoding.ts — file reads sniff per file and are always right)
@@ -857,6 +847,13 @@ export function wrapScript(body) {
         '  try { chcp 65001 > $null } catch {}',
         '}',
         '$OutputEncoding = [System.Text.Encoding]::UTF8',
+    ];
+}
+function wrapCwdPreamble() {
+    return [
+        '$script:fx_exit = 0',
+        '$fx_prev = 0',
+        'if ($env:FAUXNIX_PREV_EXIT) { try { $fx_prev = [int]$env:FAUXNIX_PREV_EXIT } catch { $fx_prev = 0 } }',
         'if ($env:FAUXNIX_CWD) { try { Set-Location -LiteralPath $env:FAUXNIX_CWD } catch {} }',
         // capture AFTER the session cwd is applied — OLDPWD must refer to the
         // shell's previous directory, not the host process' startup directory
@@ -865,6 +862,43 @@ export function wrapScript(body) {
         // process working directory, NOT the PS location — keep them in sync.
         'try { [Environment]::CurrentDirectory = (Get-Location).ProviderPath } catch {}',
     ];
+}
+function wrapBodyAndPersist(body, exitProcess) {
+    const lines = [
+        'try {',
+        ...body.split('\n').map((l) => '  ' + l),
+        '} catch [System.Management.Automation.CommandNotFoundException] {',
+        "  [Console]::Error.WriteLine('bash: ' + $_.Exception.TargetName + ': command not found')",
+        '  $script:fx_exit = 127',
+        '} catch {',
+        '  [Console]::Error.WriteLine(($_.Exception.Message).Split("`n")[0])',
+        '  $script:fx_exit = 1',
+        '}',
+        '# persist session cwd and environment for the next segment',
+        'try { [IO.File]::WriteAllText($env:FAUXNIX_CWD_FILE, (Get-Location).Path) } catch {}',
+        'if ((Get-Location).Path -ne $fx_oldcwd) { $env:FAUXNIX_OLDPWD = $fx_oldcwd }',
+        'try {',
+        '  $envObj = @{}',
+        '  Get-ChildItem Env: | ForEach-Object { $envObj[$_.Name] = $_.Value }',
+        '  [IO.File]::WriteAllText($env:FAUXNIX_ENV_FILE, (ConvertTo-Json $envObj -Compress))',
+        '} catch {}',
+    ];
+    if (exitProcess)
+        lines.push('exit $script:fx_exit');
+    return lines;
+}
+/**
+ * Wrap a pipeline body with the Fauxnix executor contract:
+ * UTF-8 everywhere, bash-style exit codes, cwd/env persistence channels.
+ * Spawn mode emits only the fx- helpers the body actually calls. Host mode
+ * assumes the resident process already loaded the catalog and must not `exit`.
+ */
+export function wrapScript(body, opts = {}) {
+    const mode = opts.mode ?? 'spawn';
+    const needed = mode === 'host' ? new Set() : wrapHelpersNeeded(body);
+    const lines = mode === 'host'
+        ? wrapCwdPreamble()
+        : [...wrapEncodingPreamble(), ...wrapCwdPreamble()];
     const helpers = {
         'fx-readlines': [
             'function fx-readlines($p) {',
@@ -1045,10 +1079,104 @@ export function wrapScript(body) {
             '}',
         ],
     };
+    cachedWrapHelpers = helpers;
     for (const name of WRAP_HELPER_ORDER) {
         if (needed.has(name))
             lines.push(...helpers[name]);
     }
-    lines.push('try {', ...body.split('\n').map((l) => '  ' + l), '} catch [System.Management.Automation.CommandNotFoundException] {', "  [Console]::Error.WriteLine('bash: ' + $_.Exception.TargetName + ': command not found')", '  $script:fx_exit = 127', '} catch {', '  [Console]::Error.WriteLine(($_.Exception.Message).Split("`n")[0])', '  $script:fx_exit = 1', '}', '# persist session cwd and environment for the next segment', 'try { [IO.File]::WriteAllText($env:FAUXNIX_CWD_FILE, (Get-Location).Path) } catch {}', 'if ((Get-Location).Path -ne $fx_oldcwd) { $env:FAUXNIX_OLDPWD = $fx_oldcwd }', 'try {', '  $envObj = @{}', '  Get-ChildItem Env: | ForEach-Object { $envObj[$_.Name] = $_.Value }', '  [IO.File]::WriteAllText($env:FAUXNIX_ENV_FILE, (ConvertTo-Json $envObj -Compress))', '} catch {}', 'exit $script:fx_exit');
+    lines.push(...wrapBodyAndPersist(body, mode === 'spawn'));
     return lines.join('\n');
 }
+let cachedWrapHelpers = null;
+function wrapHelperCatalog() {
+    if (!cachedWrapHelpers)
+        wrapScript('');
+    return cachedWrapHelpers;
+}
+/**
+ * Resident-host bootstrap: encoding + full fx-* catalog + JSON-line RPC loop.
+ * Loaded once via `powershell.exe -File`. Must never `exit` a successful frame.
+ */
+export function hostBootstrapScript() {
+    const helpers = wrapHelperCatalog();
+    const helperLines = [];
+    for (const name of WRAP_HELPER_ORDER)
+        helperLines.push(...helpers[name]);
+    return [
+        ...wrapEncodingPreamble(),
+        '$script:fx_exit = 0',
+        ...helperLines,
+        HOST_RPC_LOOP,
+    ].join('\n');
+}
+/** Raw UTF-8 JSON lines on stdin/stdout; command streams captured per frame. */
+const HOST_RPC_LOOP = `
+$fx_utf8 = New-Object System.Text.UTF8Encoding $false
+$fx_in = [Console]::OpenStandardInput()
+$fx_out = [Console]::OpenStandardOutput()
+$fx_reader = New-Object System.IO.StreamReader($fx_in, $fx_utf8, $true, 8192, $true)
+$fx_proto = New-Object System.IO.StreamWriter($fx_out, $fx_utf8, 8192, $true)
+$fx_proto.NewLine = [string][char]10
+$fx_proto.AutoFlush = $true
+$fx_proto.WriteLine('{"ready":true}')
+while ($true) {
+  $fx_line = $fx_reader.ReadLine()
+  if ($null -eq $fx_line) { break }
+  if ($fx_line -eq '') { continue }
+  $fx_id = ''
+  $fx_msOut = $null
+  $fx_msErr = $null
+  $fx_outW = $null
+  $fx_errW = $null
+  $fx_oldOut = [Console]::Out
+  $fx_oldErr = [Console]::Error
+  try {
+    $fx_req = $fx_line | ConvertFrom-Json
+    $fx_id = [string]$fx_req.id
+    if ($fx_req.env) {
+      foreach ($fx_p in $fx_req.env.PSObject.Properties) {
+        $fx_en = [string]$fx_p.Name
+        $fx_ev = [string]$fx_p.Value
+        if ($fx_ev -eq '') {
+          Remove-Item -LiteralPath ('Env:\\' + $fx_en) -ErrorAction SilentlyContinue
+        } else {
+          Set-Item -LiteralPath ('Env:\\' + $fx_en) -Value $fx_ev
+        }
+      }
+    }
+    $fx_script = [System.Text.Encoding]::UTF8.GetString([Convert]::FromBase64String([string]$fx_req.scriptB64))
+    $fx_msOut = New-Object System.IO.MemoryStream
+    $fx_msErr = New-Object System.IO.MemoryStream
+    $fx_outW = New-Object System.IO.StreamWriter($fx_msOut, $fx_utf8, 1024, $true)
+    $fx_errW = New-Object System.IO.StreamWriter($fx_msErr, $fx_utf8, 1024, $true)
+    $fx_outW.NewLine = [string][char]13 + [string][char]10
+    $fx_errW.NewLine = [string][char]13 + [string][char]10
+    $fx_outW.AutoFlush = $true
+    $fx_errW.AutoFlush = $true
+    [Console]::SetOut($fx_outW)
+    [Console]::SetError($fx_errW)
+    $script:fx_exit = 0
+    $fx_sb = [scriptblock]::Create($fx_script)
+    & $fx_sb | ForEach-Object { [Console]::Out.WriteLine([string]$_) }
+  } catch [System.Management.Automation.CommandNotFoundException] {
+    [Console]::Error.WriteLine('bash: ' + $_.Exception.TargetName + ': command not found')
+    $script:fx_exit = 127
+  } catch {
+    [Console]::Error.WriteLine(($_.Exception.Message).Split([string][char]10)[0])
+    $script:fx_exit = 1
+  } finally {
+    try { if ($null -ne $fx_outW) { $fx_outW.Flush() } } catch {}
+    try { if ($null -ne $fx_errW) { $fx_errW.Flush() } } catch {}
+    try { [Console]::SetOut($fx_oldOut) } catch {}
+    try { [Console]::SetError($fx_oldErr) } catch {}
+  }
+  $fx_outB64 = ''
+  $fx_errB64 = ''
+  if ($null -ne $fx_msOut) { $fx_outB64 = [Convert]::ToBase64String($fx_msOut.ToArray()) }
+  if ($null -ne $fx_msErr) { $fx_errB64 = [Convert]::ToBase64String($fx_msErr.ToArray()) }
+  $fx_code = 0
+  try { $fx_code = [int]$script:fx_exit } catch { $fx_code = 1 }
+  $fx_res = @{ id = $fx_id; stdoutB64 = $fx_outB64; stderrB64 = $fx_errB64; exitCode = $fx_code }
+  $fx_proto.WriteLine(($fx_res | ConvertTo-Json -Compress))
+}
+`.trim();

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fauxnix-cli",
-  "version": "0.5.1",
+  "version": "0.6.0",
   "description": "Fauxnix — run Linux-style commands on Windows via deterministic PowerShell translation. No VM, no WSL. MCP server + CLI for AI agents.",
   "type": "module",
   "bin": {