fauxnix-cli 0.5.0 → 0.6.0

package/README.md

@@ -193,7 +193,8 @@ fauxnix optimizes for the commands agents actually run. Documented deviations:
   word expansion precedes the temporary environment).
 - `yes` is capped at 65,536 lines — PS 5.1 pipelines cannot signal upstream producers to stop, so
   an unbounded `yes | head` would hang.
-- `tail -f`, `eval`, `alias`, heredocs, `while`/`until`/`case`
+- `tail -f`, `eval`, `alias`, heredocs, `while`/`until`/`case`, word-level
+  `$((...))` arithmetic expansion
   and background `&` are rejected with actionable error messages instead of misbehaving.
   (`if/then/else/fi`, `for x in ...`, backtick substitution, `command -v`, pipeline `read`,
   and dotenv-style `source` are supported.)

package/dist/ast.d.ts

@@ -12,7 +12,8 @@
  *
  * Explicitly unsupported (parser throws a helpful FauxnixError):
  *   heredocs, subshells (...), background &, while/until/case,
- *   globs inside quotes, process substitution <(...).
+ *   word-level $((...)) arithmetic expansion, globs inside quotes,
+ *   process substitution <(...).
  */
 export interface CommandList {
     kind: 'CommandList';

package/dist/ast.js

@@ -12,7 +12,8 @@
  *
  * Explicitly unsupported (parser throws a helpful FauxnixError):
  *   heredocs, subshells (...), background &, while/until/case,
- *   globs inside quotes, process substitution <(...).
+ *   word-level $((...)) arithmetic expansion, globs inside quotes,
+ *   process substitution <(...).
  */
 export function wordToString(w) {
     return w.map(partToString).join('');

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

@@ -30,22 +30,22 @@ const SESSION_ANNOTATIONS = {
     idempotentHint: true,
     openWorldHint: false,
 };
-const TOOL_DESCRIPTION = `Execute a Linux/bash-style command on this Windows machine.
-
-Commands are deterministically translated to PowerShell and executed natively — no WSL or VM.
-Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), errors look like bash errors, and text encoding (UTF-8/GBK) is handled automatically.
-
-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/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.
-Exit codes follow bash conventions (0 ok, 1 fail, 2 usage/serious, 127 command not found, 124 timeout).
-
+const TOOL_DESCRIPTION = `Execute a Linux/bash-style command on this Windows machine.
+
+Commands are deterministically translated to PowerShell and executed natively — no WSL or VM.
+Output is formatted to look like GNU/Linux tooling (ls -l, ps aux, df -h ...), errors look like bash errors, and text encoding (UTF-8/GBK) is handled automatically.
+
+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, 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 — 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/parser.js

@@ -256,6 +256,12 @@ function readDollar(input, i) {
         }
         return { part: { kind: 'Var', name }, next: end + 1 };
     }
+    // $((...)) is arithmetic expansion, not command substitution of a
+    // parenthesized body. Today it was parsed as $( (expr) ) and became an
+    // empty/confusing command. Reject loudly until word-level arith lands.
+    if (input[j] === '(' && j + 1 < n && input[j + 1] === '(') {
+        throw new FauxnixParseError('fauxnix: $((...)) arithmetic expansion is not supported; compute the value in the agent or compare with [[ $n -eq m ]]');
+    }
     // $(cmd substitution) — captured with balanced parens; the translator
     // recursively translates this text before embedding it.
     if (input[j] === '(') {

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,14 +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.
+ * 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,21 +771,72 @@ 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;
 }
-/**
- * Wrap a pipeline body with the Fauxnix executor contract:
- * UTF-8 everywhere, bash-style exit codes, cwd/env persistence channels.
- */
-export function wrapScript(body) {
-    const lines = [
+const WRAP_HELPER_ORDER = [
+    'fx-readlines',
+    'fx-csub',
+    'fx-svenc',
+    'fx-svdec',
+    'fx-arrload',
+    'fx-scalar0',
+    'fx-ifs1',
+    'fx-arrdrop',
+    'fx-arrhas',
+    'fx-arrpackget',
+    'fx-arrpackset',
+    'fx-arrput',
+    'fx-arrclr',
+    'fx-subget',
+];
+const WRAP_HELPER_DEPS = {
+    'fx-readlines': [],
+    'fx-csub': [],
+    'fx-svenc': [],
+    'fx-svdec': [],
+    'fx-arrload': ['fx-scalar0', 'fx-svdec'],
+    'fx-scalar0': ['fx-svdec'],
+    'fx-ifs1': ['fx-scalar0'],
+    'fx-arrdrop': [],
+    'fx-arrhas': [],
+    'fx-arrpackget': [],
+    'fx-arrpackset': ['fx-arrdrop'],
+    'fx-arrput': ['fx-arrdrop', 'fx-svenc'],
+    'fx-arrclr': ['fx-arrdrop'],
+    'fx-subget': ['fx-arrload', 'fx-ifs1'],
+};
+/** Helpers the body calls that wrapScript still has to emit (not already defined there). */
+function wrapHelpersNeeded(body) {
+    const defined = new Set();
+    const defRe = /function\s+(fx-[A-Za-z0-9]+)/g;
+    let m;
+    while ((m = defRe.exec(body)))
+        defined.add(m[1]);
+    const seeds = [];
+    const callRe = /\b(fx-[A-Za-z0-9]+)\b/g;
+    while ((m = callRe.exec(body))) {
+        const n = m[1];
+        if (!defined.has(n) && n in WRAP_HELPER_DEPS)
+            seeds.push(n);
+    }
+    const needed = new Set();
+    const stack = seeds.slice();
+    while (stack.length) {
+        const n = stack.pop();
+        if (needed.has(n) || defined.has(n))
+            continue;
+        needed.add(n);
+        for (const d of WRAP_HELPER_DEPS[n])
+            stack.push(d);
+    }
+    return needed;
+}
+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)
@@ -796,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
@@ -803,157 +861,10 @@ export function wrapScript(body) {
         // .NET APIs (ReadAllBytes & friends) resolve relative paths against the
         // process working directory, NOT the PS location — keep them in sync.
         'try { [Environment]::CurrentDirectory = (Get-Location).ProviderPath } catch {}',
-        // byte-sniffing line reader for `< file` stdin redirects (UTF-8 → GBK)
-        'function fx-readlines($p) {',
-        '  $b = [IO.File]::ReadAllBytes($p)',
-        '  $t = $null',
-        '  try { $t = (New-Object System.Text.UTF8Encoding($false, $true)).GetString($b) } catch {}',
-        "  if ($null -eq $t) { try { $t = [System.Text.Encoding]::GetEncoding(936).GetString($b) } catch { $t = [System.Text.Encoding]::ASCII.GetString($b) } }",
-        '  $t = $t -replace "`r`n", "`n"',
-        '  $t = $t -replace "`r", "`n"',
-        '  $parts = @($t.Split("`n"))',
-        "  if ($parts.Count -eq 1 -and $parts[0] -eq '') { return @() }",
-        "  if ($parts[$parts.Count - 1] -eq '') { $parts = $parts[0..($parts.Count - 2)] }",
-        '  return $parts',
-        '}',
-        'function fx-csub([scriptblock]$b) {',
-        '  $fx_prevcs = $script:fx_csub',
-        '  $script:fx_csub = $true',
-        '  try { $fx_o = @(& $b | ForEach-Object { [string]$_ }) }',
-        '  finally { $script:fx_csub = $fx_prevcs }',
-        '  $fx_s = ($fx_o -join [string][char]10)',
-        '  while ($fx_s.Length -gt 0 -and $fx_s[$fx_s.Length - 1] -eq [char]10) {',
-        '    $fx_s = $fx_s.Substring(0, $fx_s.Length - 1)',
-        '  }',
-        '  return $fx_s',
-        '}',
-        'function fx-svenc($s) {',
-        '  return ([string]$s).Replace([string][char]92, ([string][char]92 + [string][char]92)).Replace([string][char]13, ([string][char]92 + [char]114)).Replace([string][char]10, ([string][char]92 + [char]110))',
-        '}',
-        'function fx-svdec($s) {',
-        '  $s = [string]$s',
-        '  $sb = New-Object System.Text.StringBuilder',
-        '  $i = 0',
-        '  while ($i -lt $s.Length) {',
-        '    $c = $s[$i]',
-        '    if ($c -eq [char]92 -and ($i + 1) -lt $s.Length) {',
-        '      $n2 = $s[$i + 1]',
-        '      if ($n2 -eq [char]110) { [void]$sb.Append([char]10); $i += 2; continue }',
-        '      if ($n2 -eq [char]114) { [void]$sb.Append([char]13); $i += 2; continue }',
-        '      if ($n2 -eq [char]92) { [void]$sb.Append([char]92); $i += 2; continue }',
-        '    }',
-        '    [void]$sb.Append($c)',
-        '    $i++',
-        '  }',
-        '  return [string]$sb',
-        '}',
-        'function fx-arrload($n) {',
-        '  $n = [string]$n',
-        '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
-        '    $fx_eq = $fx_pair.IndexOf([char]61)',
-        '    if ($fx_eq -lt 1) { continue }',
-        '    if ($fx_pair.Substring(0, $fx_eq) -cne $n) { continue }',
-        '    $out = @()',
-        '    foreach ($el in @($fx_pair.Substring($fx_eq + 1) -split [string][char]30)) { $out += ,(fx-svdec $el) }',
-        '    return $out',
-        '  }',
-        '  $s0 = fx-scalar0 $n',
-        '  if ($null -eq $s0) { return @() }',
-        '  return @([string]$s0)',
-        '}',
-        'function fx-scalar0($n) {',
-        '  $n = [string]$n',
-        "  if (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ceq $n }).Count -gt 0) { return $null }",
-        '  foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) {',
-        '    $fx_eq = $fx_pair.IndexOf([char]61)',
-        '    if ($fx_eq -lt 1) { continue }',
-        '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return (fx-svdec $fx_pair.Substring($fx_eq + 1)) }',
-        '  }',
-        "  if ($n -ceq 'HOME') { return [string]$HOME }",
-        "  if ($n -ceq 'PWD') { return [string]$PWD.Path }",
-        "  if ($n -ceq 'USER' -or $n -ceq 'LOGNAME') { return [string]$env:USERNAME }",
-        "  if ($n -ceq 'PATH') { return [string]$env:PATH }",
-        "  if ($n -ceq 'SHELL') { return 'powershell' }",
-        "  if ($n -ceq 'TERM') { return 'xterm-256color' }",
-        "  if ($n -ceq 'OLDPWD') { return $(if ($env:FAUXNIX_OLDPWD) { [string]$env:FAUXNIX_OLDPWD } else { $null }) }",
-        "  if ($n -ceq 'HOSTNAME') { return [string]$env:COMPUTERNAME }",
-        '  $ev = Get-ChildItem Env: | Where-Object { $_.Name -ceq $n } | Select-Object -First 1',
-        '  if ($ev) { return [string]$ev.Value }',
-        '  return $null',
-        '}',
-        'function fx-ifs1 {',
-        "  $s = fx-scalar0 'IFS'",
-        "  if ($null -eq $s) { return ' ' }",
-        "  if ([string]$s -eq '') { return '' }",
-        '  return [string]$s[0]',
-        '}',
-        'function fx-arrdrop($n) {',
-        '  $n = [string]$n',
-        '  $fx_sm = @()',
-        '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
-        '    $fx_eq = $fx_pair.IndexOf([char]61)',
-        '    if ($fx_eq -lt 1) { continue }',
-        '    if ($fx_pair.Substring(0, $fx_eq) -cne $n) { $fx_sm += $fx_pair }',
-        '  }',
-        '  $env:FAUXNIX_ARRS = ($fx_sm -join [string][char]10)',
-        '}',
-        'function fx-arrhas($n) {',
-        '  $n = [string]$n',
-        '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
-        '    $fx_eq = $fx_pair.IndexOf([char]61)',
-        '    if ($fx_eq -lt 1) { continue }',
-        '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return $true }',
-        '  }',
-        '  return $false',
-        '}',
-        'function fx-arrpackget($n) {',
-        '  $n = [string]$n',
-        '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
-        '    $fx_eq = $fx_pair.IndexOf([char]61)',
-        '    if ($fx_eq -lt 1) { continue }',
-        '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return $fx_pair.Substring($fx_eq + 1) }',
-        '  }',
-        '  return $null',
-        '}',
-        'function fx-arrpackset($n, $pay) {',
-        '  fx-arrdrop $n',
-        '  if ($null -eq $pay) { return }',
-        "  $env:FAUXNIX_ARRS = ((@($env:FAUXNIX_ARRS -split [string][char]10 | Where-Object { $_ -ne '' }) + ([string]$n + [string][char]61 + [string]$pay)) -join [string][char]10)",
-        '}',
-        'function fx-arrput($n, $vals) {',
-        '  $n = [string]$n',
-        '  $vals = @($vals)',
-        '  fx-arrdrop $n',
-        '  if ($vals.Count -eq 0) { } else {',
-        '    $encs = @(); foreach ($v in $vals) { $encs += (fx-svenc $v) }',
-        "    $env:FAUXNIX_ARRS = ((@($env:FAUXNIX_ARRS -split [string][char]10 | Where-Object { $_ -ne '' }) + ($n + [string][char]61 + ($encs -join [string][char]30))) -join [string][char]10)",
-        '  }',
-        "  $fx_0 = $(if ($vals.Count -gt 0) { [string]$vals[0] } else { '' })",
-        '  Set-Item -LiteralPath (\'Env:\\\' + $n) -Value $fx_0',
-        "  $env:FAUXNIX_SETVARS = ((@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) + $n) -join ';')",
-        "  $env:FAUXNIX_UNSETVARS = (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) -join ';')",
-        '  $fx_sv = @(); foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) { $fx_eq = $fx_pair.IndexOf([char]61); if ($fx_eq -lt 1) { continue }; if ($fx_pair.Substring(0, $fx_eq) -cne $n) { $fx_sv += $fx_pair } }',
-        "  $fx_sv += ($n + [string][char]61 + (fx-svenc $fx_0)); $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)",
-        '}',
-        'function fx-arrclr($n) {',
-        '  $n = [string]$n',
-        '  fx-arrdrop $n',
-        "  Remove-Item -LiteralPath ('Env:\\' + $n) -ErrorAction SilentlyContinue",
-        "  $env:FAUXNIX_SETVARS = (@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) -join ';')",
-        "  $env:FAUXNIX_UNSETVARS = ((@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) + $n) -join ';')",
-        '  $fx_sv = @(); foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) { $fx_eq = $fx_pair.IndexOf([char]61); if ($fx_eq -lt 1) { continue }; if ($fx_pair.Substring(0, $fx_eq) -cne $n) { $fx_sv += $fx_pair } }; $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)',
-        '}',
-        'function fx-subget($n, $ix) {',
-        '  $arr = @(fx-arrload $n)',
-        '  $ix = [string]$ix',
-        // argv-level `@` is expanded by argListExpr; this is the scalar/quoted-* join.
-        "  if ($ix -eq '*') { return ($arr -join (fx-ifs1)) }",
-        "  if ($ix -eq '@') { return ($arr -join (fx-ifs1)) }",
-        '  $i = 0',
-        '  if (-not [int]::TryParse($ix, [ref]$i)) { return \'\' }',
-        "  if ($i -lt 0 -or $i -ge $arr.Count) { return '' }",
-        '  return [string]$arr[$i]',
-        '}',
+    ];
+}
+function wrapBodyAndPersist(body, exitProcess) {
+    const lines = [
         'try {',
         ...body.split('\n').map((l) => '  ' + l),
         '} catch [System.Management.Automation.CommandNotFoundException] {',
@@ -971,7 +882,301 @@ export function wrapScript(body) {
         '  Get-ChildItem Env: | ForEach-Object { $envObj[$_.Name] = $_.Value }',
         '  [IO.File]::WriteAllText($env:FAUXNIX_ENV_FILE, (ConvertTo-Json $envObj -Compress))',
         '} catch {}',
-        'exit $script:fx_exit',
     ];
+    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) {',
+            '  $b = [IO.File]::ReadAllBytes($p)',
+            '  $t = $null',
+            '  try { $t = (New-Object System.Text.UTF8Encoding($false, $true)).GetString($b) } catch {}',
+            "  if ($null -eq $t) { try { $t = [System.Text.Encoding]::GetEncoding(936).GetString($b) } catch { $t = [System.Text.Encoding]::ASCII.GetString($b) } }",
+            '  $t = $t -replace "`r`n", "`n"',
+            '  $t = $t -replace "`r", "`n"',
+            '  $parts = @($t.Split("`n"))',
+            "  if ($parts.Count -eq 1 -and $parts[0] -eq '') { return @() }",
+            "  if ($parts[$parts.Count - 1] -eq '') { $parts = $parts[0..($parts.Count - 2)] }",
+            '  return $parts',
+            '}',
+        ],
+        'fx-csub': [
+            'function fx-csub([scriptblock]$b) {',
+            '  $fx_prevcs = $script:fx_csub',
+            '  $script:fx_csub = $true',
+            '  try { $fx_o = @(& $b | ForEach-Object { [string]$_ }) }',
+            '  finally { $script:fx_csub = $fx_prevcs }',
+            '  $fx_s = ($fx_o -join [string][char]10)',
+            '  while ($fx_s.Length -gt 0 -and $fx_s[$fx_s.Length - 1] -eq [char]10) {',
+            '    $fx_s = $fx_s.Substring(0, $fx_s.Length - 1)',
+            '  }',
+            '  return $fx_s',
+            '}',
+        ],
+        'fx-svenc': [
+            'function fx-svenc($s) {',
+            '  return ([string]$s).Replace([string][char]92, ([string][char]92 + [string][char]92)).Replace([string][char]13, ([string][char]92 + [char]114)).Replace([string][char]10, ([string][char]92 + [char]110))',
+            '}',
+        ],
+        'fx-svdec': [
+            'function fx-svdec($s) {',
+            '  $s = [string]$s',
+            '  $sb = New-Object System.Text.StringBuilder',
+            '  $i = 0',
+            '  while ($i -lt $s.Length) {',
+            '    $c = $s[$i]',
+            '    if ($c -eq [char]92 -and ($i + 1) -lt $s.Length) {',
+            '      $n2 = $s[$i + 1]',
+            '      if ($n2 -eq [char]110) { [void]$sb.Append([char]10); $i += 2; continue }',
+            '      if ($n2 -eq [char]114) { [void]$sb.Append([char]13); $i += 2; continue }',
+            '      if ($n2 -eq [char]92) { [void]$sb.Append([char]92); $i += 2; continue }',
+            '    }',
+            '    [void]$sb.Append($c)',
+            '    $i++',
+            '  }',
+            '  return [string]$sb',
+            '}',
+        ],
+        'fx-arrload': [
+            'function fx-arrload($n) {',
+            '  $n = [string]$n',
+            '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
+            '    $fx_eq = $fx_pair.IndexOf([char]61)',
+            '    if ($fx_eq -lt 1) { continue }',
+            '    if ($fx_pair.Substring(0, $fx_eq) -cne $n) { continue }',
+            '    $out = @()',
+            '    foreach ($el in @($fx_pair.Substring($fx_eq + 1) -split [string][char]30)) { $out += ,(fx-svdec $el) }',
+            '    return $out',
+            '  }',
+            '  $s0 = fx-scalar0 $n',
+            '  if ($null -eq $s0) { return @() }',
+            '  return @([string]$s0)',
+            '}',
+        ],
+        'fx-scalar0': [
+            'function fx-scalar0($n) {',
+            '  $n = [string]$n',
+            "  if (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ceq $n }).Count -gt 0) { return $null }",
+            '  foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) {',
+            '    $fx_eq = $fx_pair.IndexOf([char]61)',
+            '    if ($fx_eq -lt 1) { continue }',
+            '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return (fx-svdec $fx_pair.Substring($fx_eq + 1)) }',
+            '  }',
+            "  if ($n -ceq 'HOME') { return [string]$HOME }",
+            "  if ($n -ceq 'PWD') { return [string]$PWD.Path }",
+            "  if ($n -ceq 'USER' -or $n -ceq 'LOGNAME') { return [string]$env:USERNAME }",
+            "  if ($n -ceq 'PATH') { return [string]$env:PATH }",
+            "  if ($n -ceq 'SHELL') { return 'powershell' }",
+            "  if ($n -ceq 'TERM') { return 'xterm-256color' }",
+            "  if ($n -ceq 'OLDPWD') { return $(if ($env:FAUXNIX_OLDPWD) { [string]$env:FAUXNIX_OLDPWD } else { $null }) }",
+            "  if ($n -ceq 'HOSTNAME') { return [string]$env:COMPUTERNAME }",
+            '  $ev = Get-ChildItem Env: | Where-Object { $_.Name -ceq $n } | Select-Object -First 1',
+            '  if ($ev) { return [string]$ev.Value }',
+            '  return $null',
+            '}',
+        ],
+        'fx-ifs1': [
+            'function fx-ifs1 {',
+            "  $s = fx-scalar0 'IFS'",
+            "  if ($null -eq $s) { return ' ' }",
+            "  if ([string]$s -eq '') { return '' }",
+            '  return [string]$s[0]',
+            '}',
+        ],
+        'fx-arrdrop': [
+            'function fx-arrdrop($n) {',
+            '  $n = [string]$n',
+            '  $fx_sm = @()',
+            '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
+            '    $fx_eq = $fx_pair.IndexOf([char]61)',
+            '    if ($fx_eq -lt 1) { continue }',
+            '    if ($fx_pair.Substring(0, $fx_eq) -cne $n) { $fx_sm += $fx_pair }',
+            '  }',
+            '  $env:FAUXNIX_ARRS = ($fx_sm -join [string][char]10)',
+            '}',
+        ],
+        'fx-arrhas': [
+            'function fx-arrhas($n) {',
+            '  $n = [string]$n',
+            '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
+            '    $fx_eq = $fx_pair.IndexOf([char]61)',
+            '    if ($fx_eq -lt 1) { continue }',
+            '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return $true }',
+            '  }',
+            '  return $false',
+            '}',
+        ],
+        'fx-arrpackget': [
+            'function fx-arrpackget($n) {',
+            '  $n = [string]$n',
+            '  foreach ($fx_pair in @($env:FAUXNIX_ARRS -split [string][char]10)) {',
+            '    $fx_eq = $fx_pair.IndexOf([char]61)',
+            '    if ($fx_eq -lt 1) { continue }',
+            '    if ($fx_pair.Substring(0, $fx_eq) -ceq $n) { return $fx_pair.Substring($fx_eq + 1) }',
+            '  }',
+            '  return $null',
+            '}',
+        ],
+        'fx-arrpackset': [
+            'function fx-arrpackset($n, $pay) {',
+            '  fx-arrdrop $n',
+            '  if ($null -eq $pay) { return }',
+            "  $env:FAUXNIX_ARRS = ((@($env:FAUXNIX_ARRS -split [string][char]10 | Where-Object { $_ -ne '' }) + ([string]$n + [string][char]61 + [string]$pay)) -join [string][char]10)",
+            '}',
+        ],
+        'fx-arrput': [
+            'function fx-arrput($n, $vals) {',
+            '  $n = [string]$n',
+            '  $vals = @($vals)',
+            '  fx-arrdrop $n',
+            '  if ($vals.Count -eq 0) { } else {',
+            '    $encs = @(); foreach ($v in $vals) { $encs += (fx-svenc $v) }',
+            "    $env:FAUXNIX_ARRS = ((@($env:FAUXNIX_ARRS -split [string][char]10 | Where-Object { $_ -ne '' }) + ($n + [string][char]61 + ($encs -join [string][char]30))) -join [string][char]10)",
+            '  }',
+            "  $fx_0 = $(if ($vals.Count -gt 0) { [string]$vals[0] } else { '' })",
+            '  Set-Item -LiteralPath (\'Env:\\\' + $n) -Value $fx_0',
+            "  $env:FAUXNIX_SETVARS = ((@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) + $n) -join ';')",
+            "  $env:FAUXNIX_UNSETVARS = (@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) -join ';')",
+            '  $fx_sv = @(); foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) { $fx_eq = $fx_pair.IndexOf([char]61); if ($fx_eq -lt 1) { continue }; if ($fx_pair.Substring(0, $fx_eq) -cne $n) { $fx_sv += $fx_pair } }',
+            "  $fx_sv += ($n + [string][char]61 + (fx-svenc $fx_0)); $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)",
+            '}',
+        ],
+        'fx-arrclr': [
+            'function fx-arrclr($n) {',
+            '  $n = [string]$n',
+            '  fx-arrdrop $n',
+            "  Remove-Item -LiteralPath ('Env:\\' + $n) -ErrorAction SilentlyContinue",
+            "  $env:FAUXNIX_SETVARS = (@($env:FAUXNIX_SETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) -join ';')",
+            "  $env:FAUXNIX_UNSETVARS = ((@($env:FAUXNIX_UNSETVARS -split ';' | Where-Object { $_ -ne '' -and $_ -cne $n }) + $n) -join ';')",
+            '  $fx_sv = @(); foreach ($fx_pair in @($env:FAUXNIX_SETVALS -split [string][char]10)) { $fx_eq = $fx_pair.IndexOf([char]61); if ($fx_eq -lt 1) { continue }; if ($fx_pair.Substring(0, $fx_eq) -cne $n) { $fx_sv += $fx_pair } }; $env:FAUXNIX_SETVALS = ($fx_sv -join [string][char]10)',
+            '}',
+        ],
+        'fx-subget': [
+            'function fx-subget($n, $ix) {',
+            '  $arr = @(fx-arrload $n)',
+            '  $ix = [string]$ix',
+            // argv-level `@` is expanded by argListExpr; this is the scalar/quoted-* join.
+            "  if ($ix -eq '*') { return ($arr -join (fx-ifs1)) }",
+            "  if ($ix -eq '@') { return ($arr -join (fx-ifs1)) }",
+            '  $i = 0',
+            '  if (-not [int]::TryParse($ix, [ref]$i)) { return \'\' }',
+            "  if ($i -lt 0 -or $i -ge $arr.Count) { return '' }",
+            '  return [string]$arr[$i]',
+            '}',
+        ],
+    };
+    cachedWrapHelpers = helpers;
+    for (const name of WRAP_HELPER_ORDER) {
+        if (needed.has(name))
+            lines.push(...helpers[name]);
+    }
+    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.0",
+  "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": {