fauxnix-cli 0.9.2 → 0.9.3

package/README.md

@@ -58,6 +58,14 @@ Linux command line — file ops, text processing, process management, archives,
 maps cleanly onto PowerShell + .NET. fauxnix implements that subset faithfully and *fails loudly
 and helpfully* on what it can't translate, so the agent never gets silently-wrong results.
 
+Labs now train computer-use agents on fleets of real desktops. Reporting in 2026 (*The
+Information*, widely repeated) has OpenAI buying tens of thousands of Mac mini / Mac Studio
+boxes — no screen, no keyboard — to reinforcement-learn agents that click, edit, test, and
+run bash workflows, and Anthropic renting Mac minis through AWS for the same class of work.
+That scoring environment is macOS. Windows users should not have to install a guest Unix to
+keep up: the agent keeps writing bash; fauxnix makes the Windows box answer like the box the
+agent was trained on. See [`docs/rfc-computer-use-windows.md`](docs/rfc-computer-use-windows.md).
+
 ## Install
 
 ```bash
@@ -156,7 +164,7 @@ development:
 
 `cp` / `mv` / `rm` / `touch` / `du` / `ls` / `ll` / `mkdir` / `rmdir` / `mktemp` / `ln` /
 `readlink` / `realpath` / `basename` / `dirname` / `stat` / `file` / `df` / `chmod` / `chown` /
-`diff` / `tee` / `grep` / `head` carry a `CommandSpec`: unknown options fail with a GNU-style
+`diff` / `tee` / `grep` / `head` / `echo` / `printf` / `cat` / `tail` / `wc` carry a `CommandSpec`: unknown options fail with a GNU-style
 usage error instead of being ignored (`find` stays unspec'd so predicates like `-name` still
 compile). Implemented GNU holes: `cp -n` / `mv -n` / `touch -c` / `tee --append` / `grep -m` /
 `head --lines` / `du --max-depth`. `fauxnix list --json` and `docs/command-specs.md` dump the

package/dist/commands/archive.js

@@ -214,8 +214,9 @@ const tar = (args) => {
         '  if ($fx_c) { $fx_tar = $fx_c.Source } else { $fx_tar = $null }',
         '}',
         'if ($fx_tar) {',
-        '  & $fx_tar @($fx_args) | ForEach-Object { [string]$_ }',
-        '  if ($LASTEXITCODE -gt 0) { $script:fx_exit = $LASTEXITCODE }',
+        // fx-native captures stdout as pipeline strings and sets fx_exit.
+        // [object[]]@(...) keeps an empty argv from unwrapping to $null on PS 5.1.
+        '  fx-native $fx_tar ([object[]]@($fx_args))',
         '} else {',
         "  [Console]::Error.WriteLine('tar: fauxnix: tar.exe not found (Windows 10+ ships bsdtar as tar.exe)')",
         '  $script:fx_exit = 1',

package/dist/commands/files.js

@@ -55,7 +55,7 @@ function psIsLink(it) {
 /* ls                                                                  */
 /* ------------------------------------------------------------------ */
 const ls = (args) => {
-    const { flags, longs, values, operandWords } = parseWords(args, [], ['--format']);
+    const { flags, longs, values, operandWords } = parseWords(args, [], ['--format', '--color']);
     const long = flags.has('l') || longs.has('--long') || values.get('--format') === 'long';
     const all = flags.has('a') || longs.has('--all');
     const almost = flags.has('A') || longs.has('--almost-all');
@@ -725,7 +725,7 @@ const find = (args) => {
     const preds = raw.slice(pathEnd);
     if (preds.includes('-exec') || preds.includes('-execdir')) {
         return ('[Console]::Error.WriteLine(' +
-            psStr('find: -exec is not supported by fauxnix; pipe into the command instead (e.g. `find . -name "*.log" | xargs rm`)') +
+            psStr('find: -exec is not supported by fauxnix; use `find . -name "*.log" -delete` or grep -r instead') +
             '); $script:fx_exit = 1');
     }
     const plan = parseFindPreds(preds);
@@ -967,6 +967,8 @@ export const specs = [
         opt('S', undefined),
         opt('r', undefined),
         opt('R', '--recursive', 'unsupported', { reason: 'recursive listing' }),
+        // GNU optional WHEN; takesValue so --color=auto is valid. No ANSI.
+        opt(undefined, '--color', 'implemented', { takesValue: true }),
     ], ls),
     fileSpec(['mkdir'], ['write'], [opt('p', '--parents'), opt('v', '--verbose')], mkdir),
     fileSpec(['rmdir'], ['delete'], [], rmdir),

package/dist/commands/net.js

@@ -79,10 +79,9 @@ function synthWord(text) {
 }
 /** A native-exe invocation obeying the fauxnix contract (string lines + exit code). */
 function nativeCall(exe, argArray) {
-    return [
-        '& ' + psStr(exe) + ' @(' + argArray + ') | ForEach-Object { [string]$_ }',
-        'if ($LASTEXITCODE -gt 0) { $script:fx_exit = $LASTEXITCODE }',
-    ].join('\n');
+    // fx-native captures stdout as pipeline strings and sets fx_exit.
+    // [object[]]@(...) keeps an empty argv from unwrapping to $null on PS 5.1.
+    return 'fx-native ' + psStr(exe) + ' ([object[]]@(' + argArray + '))';
 }
 /* ------------------------------------------------------------------ */
 /* curl                                                                */

package/dist/commands/text-filters.js

@@ -583,48 +583,45 @@ const grep = (args) => {
             scan.push('    $fx_mleft--');
         if (onlyMatch && !inv) {
             if (fixed) {
+                // GNU -o: emit leftmost-longest matches in input order, not per-needle.
                 if (ci)
                     scan.push('    $lx = $fx_l.ToLower()');
                 const hay = ci ? '$lx' : '$fx_l';
-                const emitFixedHits = (needle, indent) => {
-                    scan.push(indent + '$p = ' + hay + '.IndexOf(' + needle + ')');
-                    scan.push(indent + 'while ($p -ge 0) {');
-                    scan.push(indent + '  $ok = $true');
-                    if (word) {
-                        scan.push(indent +
-                            "  if ($p -gt 0) { $c = " +
-                            hay +
-                            "[$p - 1]; $ok = -not ([char]::IsLetterOrDigit($c) -or $c -eq '_') }");
-                        scan.push(indent +
-                            '  if ($ok) { $e = $p + ' +
-                            needle +
-                            '.Length; if ($e -lt ' +
-                            hay +
-                            '.Length) { $c = ' +
-                            hay +
-                            "[$e]; $ok = -not ([char]::IsLetterOrDigit($c) -or $c -eq '_') } }");
-                        scan.push(indent +
-                            '  if ($ok) { fx-emitline $fx_i (' +
-                            hay +
-                            '.Substring($p, ' +
-                            needle +
-                            '.Length)) }');
-                    }
-                    else {
-                        scan.push(indent + '  fx-emitline $fx_i (' + hay + '.Substring($p, ' + needle + '.Length))');
-                    }
-                    scan.push(indent + '  $p = ' + hay + '.IndexOf(' + needle + ', $p + 1)');
-                    scan.push(indent + '}');
-                };
-                if (multiFixed) {
-                    const arr = ci ? '$fx_needles_ll' : '$fx_needles';
-                    scan.push('    foreach ($fx_needle in ' + arr + ') {');
-                    emitFixedHits('$fx_needle', '      ');
-                    scan.push('    }');
+                const needleArr = multiFixed
+                    ? ci
+                        ? '$fx_needles_ll'
+                        : '$fx_needles'
+                    : '@(' + (ci ? '$fx_needle_ll' : '$fx_needle') + ')';
+                scan.push('    $fx_cands = New-Object System.Collections.Generic.List[object]');
+                scan.push('    foreach ($fx_needle in ' + needleArr + ') {');
+                scan.push('      if ($fx_needle.Length -lt 1) { continue }');
+                scan.push('      $p = ' + hay + '.IndexOf($fx_needle)');
+                scan.push('      while ($p -ge 0) {');
+                if (word) {
+                    scan.push('        $ok = $true');
+                    scan.push("        if ($p -gt 0) { $c = " +
+                        hay +
+                        "[$p - 1]; $ok = -not ([char]::IsLetterOrDigit($c) -or $c -eq '_') }");
+                    scan.push('        if ($ok) { $e = $p + $fx_needle.Length; if ($e -lt ' +
+                        hay +
+                        '.Length) { $c = ' +
+                        hay +
+                        "[$e]; $ok = -not ([char]::IsLetterOrDigit($c) -or $c -eq '_') } }");
+                    scan.push('        if ($ok) { [void]$fx_cands.Add([pscustomobject]@{ Start = $p; Len = $fx_needle.Length }) }');
                 }
                 else {
-                    emitFixedHits(ci ? '$fx_needle_ll' : '$fx_needle', '    ');
+                    scan.push('        [void]$fx_cands.Add([pscustomobject]@{ Start = $p; Len = $fx_needle.Length })');
                 }
+                scan.push('        $p = ' + hay + '.IndexOf($fx_needle, $p + 1)');
+                scan.push('      }');
+                scan.push('    }');
+                scan.push('    $fx_end = 0');
+                scan.push('    foreach ($fx_c in @($fx_cands | Sort-Object Start, @{ Expression = { $_.Len }; Descending = $true })) {');
+                scan.push('      if ($fx_c.Start -ge $fx_end) {');
+                scan.push('        fx-emitline $fx_i (' + hay + '.Substring($fx_c.Start, $fx_c.Len))');
+                scan.push('        $fx_end = $fx_c.Start + $fx_c.Len');
+                scan.push('      }');
+                scan.push('    }');
             }
             else {
                 scan.push('    foreach ($fx_m in $fx_re.Matches($fx_l)) { fx-emitline $fx_i $fx_m.Value }');

package/dist/commands/text-io.js

@@ -1093,6 +1093,9 @@ const xargs = (args) => {
                     noRunIfEmpty = true;
                 else if (ch === 't')
                     trace = true;
+                else if (ch === '0') {
+                    return psErrExpr(psStr('xargs: -0 is not supported by fauxnix'));
+                }
                 else if (ch === 'n' || ch === 'I' || ch === 'L') {
                     const restv = body.slice(c + 1);
                     let val;
@@ -1140,12 +1143,12 @@ const xargs = (args) => {
     }
     const n = chunkN !== null && Number.isFinite(chunkN) && chunkN > 0 ? chunkN : 0;
     const replExpr = repl !== null ? psStr(repl) : null;
+    // fx-native already records $script:fx_exit from ExitCode.
     const invoke = [
         '    if (' +
             pb(trace) +
             ") { [Console]::Error.WriteLine(((@($fx_cmd) + @($fx_argv)) -join ' ')) }",
-        '    & $fx_cmd @fx_argv',
-        '    if ($LASTEXITCODE -ne 0 -and $script:fx_exit -eq 0) { $script:fx_exit = $LASTEXITCODE }',
+        '    fx-native $fx_cmd $fx_argv',
     ];
     let dispatch;
     const guard = '  if (' + pb(noRunIfEmpty) + ' -and $fx_args.Count -eq 0) { }' + '\n' + '  else {';
@@ -1154,7 +1157,7 @@ const xargs = (args) => {
         dispatch = [
             guard,
             '  foreach ($fx_l in $fx_args) {',
-            '    $fx_argv = @()',
+            '    $fx_argv = [object[]]@()',
             '    $fx_hit = $false',
             '    foreach ($fx_a in $fx_base) {',
             '      if ($fx_a.Contains(' + replExpr + ')) {',
@@ -1175,7 +1178,7 @@ const xargs = (args) => {
             '  $fx_i = 0',
             '  $fx_ran = $false',
             '  while ($fx_i -lt $fx_args.Count) {',
-            '    $fx_argv = @($fx_base)',
+            '    $fx_argv = [object[]]@($fx_base)',
             '    $fx_j = 0',
             '    while ($fx_j -lt ' + n + ' -and $fx_i -lt $fx_args.Count) {',
             '      $fx_argv += $fx_args[$fx_i]',
@@ -1185,10 +1188,8 @@ const xargs = (args) => {
             ...invoke,
             '  }',
             '  if (-not $fx_ran) {',
-            '    $fx_argv = @($fx_base)',
-            '    ' + invoke[0],
-            '    ' + invoke[1],
-            '    ' + invoke[2],
+            '    $fx_argv = [object[]]@($fx_base)',
+            ...invoke.map((line) => '  ' + line),
             '  }',
             '  }',
         ];
@@ -1196,17 +1197,27 @@ const xargs = (args) => {
     else {
         dispatch = [
             guard,
-            '  $fx_argv = @($fx_base) + @($fx_args)',
+            '  $fx_argv = [object[]](@($fx_base) + @($fx_args))',
             ...invoke,
             '  }',
         ];
     }
+    // Default GNU xargs splits on blanks; -I keeps whole lines as one item.
+    const collectArgs = replExpr !== null
+        ? "$fx_args = @($fx_in | Where-Object { $_ -ne '' })"
+        : [
+            '$fx_args = @()',
+            'foreach ($fx_l in $fx_in) {',
+            "  if ($fx_l -eq '') { continue }",
+            "  $fx_args += @($fx_l -split '[ \\t]+' | Where-Object { $_ -ne '' })",
+            '}',
+        ].join('\n');
     return [
         PS_SPLITLINES_FN,
         STDIN_INLINES,
         '$fx_tg = ' + argListExpr(target, exprOfWord),
         "if ($fx_tg.Count -eq 0) { $fx_cmd = ''; $fx_base = @() } else { $fx_cmd = [string]$fx_tg[0]; $fx_base = $(if ($fx_tg.Count -gt 1) { @($fx_tg[1..($fx_tg.Count - 1)]) } else { @() }) }",
-        "$fx_args = @($fx_in | Where-Object { $_ -ne '' })",
+        collectArgs,
         ...dispatch,
     ].join('\n');
 };
@@ -1236,6 +1247,74 @@ export const specs = [
         dispatch: 'translated',
         handler: head,
     },
+    {
+        names: ['echo'],
+        options: [
+            { short: 'n', support: 'implemented' },
+            { short: 'e', support: 'implemented' },
+            { short: 'E', support: 'implemented' },
+        ],
+        effects: [],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        usageExit: 2,
+        leadingOptions: true,
+        handler: echo,
+    },
+    {
+        names: ['printf'],
+        options: [],
+        effects: [],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        usageExit: 2,
+        leadingOptions: true,
+        handler: printf,
+    },
+    {
+        names: ['cat'],
+        options: [
+            { short: 'n', support: 'implemented' },
+            { short: 'b', support: 'implemented' },
+            { short: 's', support: 'implemented' },
+            { short: 'E', support: 'implemented' },
+            { short: 'T', support: 'implemented' },
+            { short: 'A', support: 'implemented' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: cat,
+    },
+    {
+        names: ['tail'],
+        options: [
+            { short: 'n', long: '--lines', takesValue: true, support: 'implemented' },
+            { short: 'c', long: '--bytes', takesValue: true, support: 'implemented' },
+            { short: 'q', long: '--quiet', support: 'implemented' },
+            { long: '--silent', support: 'implemented' },
+            { short: 'v', long: '--verbose', support: 'implemented' },
+            { short: 'f', support: 'unsupported', reason: 'no persistent tty' },
+            { short: 'F', support: 'unsupported', reason: 'no persistent tty' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: tail,
+    },
+    {
+        names: ['wc'],
+        options: [
+            { short: 'l', support: 'implemented' },
+            { short: 'w', support: 'implemented' },
+            { short: 'c', support: 'implemented' },
+            { short: 'm', support: 'implemented' },
+        ],
+        effects: ['read'],
+        platform: 'windows-ps51',
+        dispatch: 'translated',
+        handler: wc,
+    },
 ];
 export const handlers = {
     echo,

package/dist/errors.d.ts

@@ -2,4 +2,8 @@
  * Error normalization — make PowerShell failures look like bash failures
  * so agents can pattern-match on familiar Linux error styles.
  */
+/** Missing `python3` on Windows (Mac/Linux agents emit this; do not alias). */
+export declare const PYTHON3_WINDOWS_HINT = " (fauxnix: try `python` or `py` on Windows)";
+/** `.sh` cannot be CreateProcess'd; fx-native never emits the PS not-recognized line. */
+export declare const SH_SCRIPT_WINDOWS_HINT = " (fauxnix: .sh scripts cannot run natively on Windows)";
 export declare function normalizeStderr(stderr: string): string;

package/dist/errors.js

@@ -2,6 +2,19 @@
  * Error normalization — make PowerShell failures look like bash failures
  * so agents can pattern-match on familiar Linux error styles.
  */
+/** Missing `python3` on Windows (Mac/Linux agents emit this; do not alias). */
+export const PYTHON3_WINDOWS_HINT = ' (fauxnix: try `python` or `py` on Windows)';
+/** `.sh` cannot be CreateProcess'd; fx-native never emits the PS not-recognized line. */
+export const SH_SCRIPT_WINDOWS_HINT = ' (fauxnix: .sh scripts cannot run natively on Windows)';
+function commandNotFound(name) {
+    const msg = 'bash: ' + name + ': command not found';
+    const base = name.replace(/^.*[/\\]/, '');
+    if (/^python3(\.exe)?$/i.test(base))
+        return msg + PYTHON3_WINDOWS_HINT;
+    if (/\.sh$/i.test(name))
+        return msg + SH_SCRIPT_WINDOWS_HINT;
+    return msg;
+}
 /** Lines produced by PowerShell error formatting that bash would never show. */
 const PS_NOISE = [
     /^\s*\+ CategoryInfo\s*:/,
@@ -62,15 +75,15 @@ export function normalizeStderr(stderr) {
         // "The term 'x' is not recognized as a name of a cmdlet, function, ..."
         let m = line.match(/^The term '(.+?)' is not recognized/);
         if (m)
-            return 'bash: ' + m[1] + ': command not found';
+            return commandNotFound(m[1]);
         // zh-CN: 无法将"x"项识别为 cmdlet、函数、脚本文件或可运行程序的名称
         m = line.match(/^无法将["'”]?([^"'”]+)["'”]?项识别为/);
         if (m)
-            return 'bash: ' + m[1] + ': command not found';
+            return commandNotFound(m[1]);
         // "x : The term 'y' is not recognized ..." (with source prefix)
         m = line.match(/^(\S+)\s*:\s*The term '(.+?)' is not recognized/);
         if (m)
-            return 'bash: ' + m[2] + ': command not found';
+            return commandNotFound(m[2]);
         // "cat : Cannot find path 'D:\x' because it does not exist."
         m = line.match(/^(\S+)\s*:\s*Cannot find path '(.+?)' because it does not exist\.?$/);
         if (m) {
@@ -93,9 +106,9 @@ export function normalizeStderr(stderr) {
         m = line.match(/^(\S+)\s*:\s*(.*)Access to the path '(.+?)' is denied\.?$/);
         if (m)
             return m[1].toLowerCase() + ': cannot remove \'' + m[3] + '\': Permission denied';
-        // helpful hint for bash scripts
+        // leftover PS not-recognized lines that the rewrites above did not catch
         if (/\.sh'?/.test(line) && /is not recognized/.test(line)) {
-            return line + ' (fauxnix: .sh scripts cannot run natively on Windows)';
+            return line + SH_SCRIPT_WINDOWS_HINT;
         }
         return line;
     });

package/dist/executor.js

@@ -26,7 +26,35 @@ function isNulPath(p) {
     const base = p.split(/[/\\]/).pop() ?? p;
     return /^NUL$/i.test(base);
 }
-function emitToPrepDest(dest, msg, fds, fallback) {
+function applyRedirectDest(op, target, stdout, stderr) {
+    if (op === '2>&1')
+        return { stdout, stderr: stdout };
+    if (op === '1>&2')
+        return { stdout: stderr, stderr };
+    if (op === '<' || target === undefined)
+        return { stdout, stderr };
+    const dest = isNulPath(target) ? { kind: 'nul' } : { kind: 'file', path: target };
+    if (op === '>' || op === '>>')
+        return { stdout: dest, stderr };
+    if (op === '2>' || op === '2>>')
+        return { stdout, stderr: dest };
+    if (op === '&>' || op === '&>>')
+        return { stdout: dest, stderr: dest };
+    return { stdout, stderr };
+}
+/** Last-stage output fds only — captured stdout/stderr apply. */
+function lastStageOutputDests(redirects, resolveTarget) {
+    let stdout = { kind: 'caller', fd: 1 };
+    let stderr = { kind: 'caller', fd: 2 };
+    for (const r of redirects) {
+        const target = r.op === '2>&1' || r.op === '1>&2' || r.op === '<'
+            ? undefined
+            : resolveTarget(winTarget(r.target));
+        ({ stdout, stderr } = applyRedirectDest(r.op, target, stdout, stderr));
+    }
+    return { stdout, stderr };
+}
+function emitToPrepDest(dest, msg, fds, caller) {
     if (dest.kind === 'nul')
         return;
     if (dest.kind === 'file') {
@@ -35,10 +63,14 @@ function emitToPrepDest(dest, msg, fds, fallback) {
             return;
         }
         catch {
-            /* fall through to caller */
+            caller.stderr(msg);
+            return;
         }
     }
-    fallback(msg);
+    if (dest.fd === 1)
+        caller.stdout(msg);
+    else
+        caller.stderr(msg);
 }
 function writeAllSync(fd, data) {
     let off = 0;
@@ -94,9 +126,6 @@ function planRedirects(redirects) {
         appendStdout: false,
         stderrFile: null,
         appendStderr: false,
-        mergeStderr: false,
-        devNull: false,
-        swallowStderr: false,
     };
     for (const red of redirects) {
         const target = winTarget(red.target);
@@ -107,41 +136,30 @@ function planRedirects(redirects) {
             case '>':
             case '&>':
                 if (isNulPath(target)) {
-                    r.devNull = true;
                     r.stdoutFile = null;
-                    if (red.op === '&>') {
-                        r.swallowStderr = true;
+                    if (red.op === '&>')
                         r.stderrFile = null;
-                    }
                 }
                 else {
-                    r.devNull = false;
                     r.stdoutFile = target;
                     r.appendStdout = false;
-                    if (red.op === '&>') {
+                    if (red.op === '&>')
                         r.stderrFile = target;
-                        r.swallowStderr = false;
-                    }
                 }
                 break;
             case '>>':
             case '&>>':
                 if (isNulPath(target)) {
-                    r.devNull = true;
                     r.stdoutFile = null;
-                    if (red.op === '&>>') {
-                        r.swallowStderr = true;
+                    if (red.op === '&>>')
                         r.stderrFile = null;
-                    }
                 }
                 else {
-                    r.devNull = false;
                     r.stdoutFile = target;
                     r.appendStdout = true;
                     if (red.op === '&>>') {
                         r.stderrFile = target;
                         r.appendStderr = true;
-                        r.swallowStderr = false;
                     }
                 }
                 break;
@@ -149,31 +167,22 @@ function planRedirects(redirects) {
                 if (isNulPath(target)) {
                     // stderr only — must not undo a prior >/dev/null
                     r.stderrFile = null;
-                    r.swallowStderr = true;
                 }
                 else {
                     r.stderrFile = target;
                     r.appendStderr = false;
-                    r.swallowStderr = false;
                 }
                 break;
             case '2>>':
                 if (isNulPath(target)) {
                     r.stderrFile = null;
-                    r.swallowStderr = true;
                 }
                 else {
                     r.stderrFile = target;
                     r.appendStderr = true;
-                    r.swallowStderr = false;
                 }
                 break;
-            case '2>&1':
-                r.mergeStderr = true;
-                break;
-            case '1>&2':
-                r.mergeStderr = false;
-                r.stdoutToStderr = true;
+            default:
                 break;
         }
     }
@@ -364,18 +373,19 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             let redirectPrepFailed = false;
             // Snapshot fd destinations as we walk. `2>&1` copies stdout *at that
             // moment*; a later `>file` must not drag stderr along (bash fd dup).
-            let prepStdout = { kind: 'caller' };
-            let prepStderr = { kind: 'caller' };
-            const emitPrepError = (msg) => emitToPrepDest(prepStderr, msg, prepFds, (s) => {
-                stderr += s;
+            let prepStdout = { kind: 'caller', fd: 1 };
+            let prepStderr = { kind: 'caller', fd: 2 };
+            const emitPrepError = (msg) => emitToPrepDest(prepStderr, msg, prepFds, {
+                stdout: (s) => {
+                    stdout += s;
+                },
+                stderr: (s) => {
+                    stderr += s;
+                },
             });
             for (const r of plan.redirects) {
-                if (r.op === '2>&1') {
-                    prepStderr = prepStdout;
-                    continue;
-                }
-                if (r.op === '1>&2') {
-                    prepStdout = prepStderr;
+                if (r.op === '2>&1' || r.op === '1>&2') {
+                    ({ stdout: prepStdout, stderr: prepStderr } = applyRedirectDest(r.op, undefined, prepStdout, prepStderr));
                     continue;
                 }
                 const target = resolveTarget(winTarget(r.target));
@@ -389,33 +399,16 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
                     }
                     continue;
                 }
-                if (isNulPath(target)) {
-                    if (r.op === '>' || r.op === '>>')
-                        prepStdout = { kind: 'nul' };
-                    else if (r.op === '2>' || r.op === '2>>')
-                        prepStderr = { kind: 'nul' };
-                    else if (r.op === '&>' || r.op === '&>>') {
-                        prepStdout = { kind: 'nul' };
-                        prepStderr = { kind: 'nul' };
+                if (!isNulPath(target)) {
+                    const append = r.op === '>>' || r.op === '2>>' || r.op === '&>>';
+                    const fail = prepareRedirectFile(target, append, prepFds);
+                    if (fail) {
+                        emitPrepError('bash: ' + fail + '\n');
+                        redirectPrepFailed = true;
+                        break;
                     }
-                    continue;
-                }
-                const append = r.op === '>>' || r.op === '2>>' || r.op === '&>>';
-                const fail = prepareRedirectFile(target, append, prepFds);
-                if (fail) {
-                    emitPrepError('bash: ' + fail + '\n');
-                    redirectPrepFailed = true;
-                    break;
-                }
-                const fileDest = { kind: 'file', path: target };
-                if (r.op === '>' || r.op === '>>')
-                    prepStdout = fileDest;
-                else if (r.op === '2>' || r.op === '2>>')
-                    prepStderr = fileDest;
-                else if (r.op === '&>' || r.op === '&>>') {
-                    prepStdout = fileDest;
-                    prepStderr = fileDest;
                 }
+                ({ stdout: prepStdout, stderr: prepStderr } = applyRedirectDest(r.op, target, prepStdout, prepStderr));
             }
             if (redirectPrepFailed) {
                 exitCode = 1;
@@ -438,11 +431,15 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
                 break;
             }
             const encoded = wrapScript(plan.body, { mode: 'host' });
+            // Last-stage fds last-win independently. `2>&1 >/dev/null` snapshots
+            // stderr onto the caller's stdout before stdout is pointed at NUL, so
+            // captured stderr is still returned; `>/dev/null 2>&1` points both at NUL.
+            const applyDests = lastStageOutputDests(plan.outputRedirects, resolveTarget);
             // Response budgets cap what the CALLER receives — streams redirected to
             // files must never be truncated by them (Codex-review P1: `printf … > f`
             // with a small stdoutLimit was writing a clipped file). The final
             // clipUtf8 below still enforces the returned-data budget.
-            const fileRedirected = !!(red.stdoutFile || red.stderrFile);
+            const fileRedirected = applyDests.stdout.kind === 'file' || applyDests.stderr.kind === 'file';
             const inv = await ensureHost().invoke(encoded, {
                 FAUXNIX_CWD: currentDir,
                 FAUXNIX_PREV_EXIT: session.prevExit === null ? '' : String(session.prevExit),
@@ -470,52 +467,45 @@ async function runPlans(plans, session, opts, afterSegment, ensureHost) {
             // 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(inv.stdout, decodePref));
+            const segOut = normalizeHostNewlines(decodeOutput(inv.stdout, decodePref));
             let segErr = normalizeHostNewlines(normalizeStderr(decodeOutput(inv.stderr, decodePref)));
             if (inv.timedOut) {
                 segErr += timeoutMessage;
             }
-            if (red.mergeStderr) {
-                segOut += (segOut && !segOut.endsWith('\n') && segErr ? '\n' : '') + segErr;
-                segErr = '';
-            }
-            const stdoutToStderr = red.stdoutToStderr;
-            if (stdoutToStderr) {
-                segErr += segOut;
-                segOut = '';
-            }
-            if (red.swallowStderr)
-                segErr = '';
-            if (red.devNull)
-                segOut = '';
             // Write captured streams through the fds opened during preflight
             // (bash: the redirect refers to the open file, not the path). Reopening
             // the path would recreate a file the command just unlinked
             // (`rm out.txt > out.txt`).
             let redirectOk = true;
-            if (red.stdoutFile) {
-                try {
-                    writeToPrepFd(prepFds, red.stdoutFile, segOut);
-                    segOut = '';
-                }
-                catch (e) {
-                    segErr += 'bash: ' + red.stdoutFile + ': cannot create: ' + e.message + '\n';
-                    exitCode = 1;
-                    redirectOk = false;
-                }
-            }
-            if (red.stderrFile) {
-                try {
-                    const body = red.stderrFile === red.stdoutFile ? segOut + segErr : segErr;
-                    writeToPrepFd(prepFds, red.stderrFile, body);
-                    segErr = '';
-                }
-                catch {
-                    /* best effort */
+            const deliverCaptured = (dest, data, fromStdout) => {
+                if (!data)
+                    return;
+                if (dest.kind === 'nul')
+                    return;
+                if (dest.kind === 'file') {
+                    try {
+                        writeToPrepFd(prepFds, dest.path, data);
+                    }
+                    catch (e) {
+                        if (fromStdout) {
+                            stderr += 'bash: ' + dest.path + ': cannot create: ' + e.message + '\n';
+                            exitCode = 1;
+                            redirectOk = false;
+                            stdout += data;
+                        }
+                        else {
+                            stderr += data;
+                        }
+                    }
+                    return;
                 }
-            }
-            stdout += segOut;
-            stderr += segErr;
+                if (dest.fd === 1)
+                    stdout += data;
+                else
+                    stderr += data;
+            };
+            deliverCaptured(applyDests.stdout, segOut, true);
+            deliverCaptured(applyDests.stderr, segErr, false);
             if (inv.truncated)
                 truncated = true;
             exitCode = inv.timedOut ? 124 : inv.cancelled ? 130 : inv.exitCode;

package/dist/registry.d.ts

@@ -99,6 +99,8 @@ export interface CommandSpec {
     dispatch?: 'translated' | 'native' | 'dynamic';
     /** GNU usage/syntax exit (grep uses 2; cp/mv/rm use 1). */
     usageExit?: number;
+    /** First non-option operand ends option scanning (echo/printf). */
+    leadingOptions?: boolean;
     handler: Handler;
 }
 /** Register a spec'd command. Unknown/unsupported options become GNU-style usage errors. */

package/dist/registry.js

@@ -197,7 +197,8 @@ export function specsMarkdown() {
     for (const spec of registeredSpecs()) {
         lines.push('## `' + spec.names.join('` / `') + '`');
         lines.push('');
-        lines.push('Effects: ' + spec.effects.map((e) => '`' + e + '`').join(', '));
+        lines.push('Effects: ' +
+            (spec.effects.length ? spec.effects.map((e) => '`' + e + '`').join(', ') : 'none'));
         lines.push('');
         if (!spec.options.length) {
             lines.push('No options declared.');
@@ -319,6 +320,8 @@ export function specOptionError(spec, args, cmdName) {
             i++;
             continue;
         }
+        if (spec.leadingOptions)
+            onlyOperands = true;
         i++;
     }
     return null;

package/dist/translator.js

@@ -1,6 +1,7 @@
 import { FauxnixParseError, isUnquotedLiteral, } from './ast.js';
 import { parseCommand } from './parser.js';
 import { lookup, psStr } from './registry.js';
+import { PYTHON3_WINDOWS_HINT, SH_SCRIPT_WINDOWS_HINT } from './errors.js';
 /* ------------------------------------------------------------------ */
 /* Variable mapping                                                    */
 /* ------------------------------------------------------------------ */
@@ -1216,8 +1217,9 @@ export function wrapScript(body, opts = {}) {
             '}',
         ],
         'fx-winargv': [
-            'function fx-winargv($argv) {',
+            'function fx-winargv($argv, $cmdmeta) {',
             // Empty [object[]] unwraps to $null on PS 5.1; @($null) is one empty arg.
+            // $cmdmeta: also quote & | () <> ^ so cmd.exe /c does not split the tail.
             '  if ($null -eq $argv) { $argv = @() }',
             '  $parts = New-Object System.Collections.Generic.List[string]',
             '  foreach ($a in @($argv)) {',
@@ -1226,6 +1228,7 @@ export function wrapScript(body, opts = {}) {
             '    $need = $false',
             '    foreach ($ch in $s.ToCharArray()) {',
             "      if ($ch -eq ' ' -or $ch -eq ([char]9) -or $ch -eq [char]34) { $need = $true; break }",
+            "      if ($cmdmeta -and ($ch -eq '&' -or $ch -eq '|' -or $ch -eq '(' -or $ch -eq ')' -or $ch -eq '<' -or $ch -eq '>' -or $ch -eq '^')) { $need = $true; break }",
             '    }',
             '    if (-not $need) { $parts.Add($s); continue }',
             '    $sb = New-Object System.Text.StringBuilder',
@@ -1259,7 +1262,14 @@ export function wrapScript(body, opts = {}) {
             // operator is only for names that are not executables.
             '    $cmd = Get-Command -Name $name -ErrorAction SilentlyContinue | Select-Object -First 1',
             '    if ($null -eq $cmd) {',
-            "      [Console]::Error.WriteLine('bash: ' + $name + ': command not found')",
+            "      $fx_nf = 'bash: ' + $name + ': command not found'",
+            "      $fx_n = [string]$name",
+            // Hint only — never alias python3→python (wrong interpreter).
+            "      if ($fx_n -eq 'python3' -or $fx_n -eq 'python3.exe') { $fx_nf += '" +
+                PYTHON3_WINDOWS_HINT +
+                "' }",
+            "      elseif ($fx_n -like '*.sh') { $fx_nf += '" + SH_SCRIPT_WINDOWS_HINT + "' }",
+            '      [Console]::Error.WriteLine($fx_nf)',
             '      $script:fx_exit = 127',
             '      return',
             '    }',
@@ -1272,6 +1282,8 @@ export function wrapScript(body, opts = {}) {
             '  $psi = New-Object System.Diagnostics.ProcessStartInfo',
             '  $ext = [IO.Path]::GetExtension([string]$app.Source)',
             // CreateProcess cannot launch .cmd/.bat with UseShellExecute=false (npm.cmd).
+            // /s strips one outer quote pair from the /c tail; CRT-quote cmd
+            // metacharacters so `&`/`|`/`()` do not start a second command.
             "  if ($ext -eq '.cmd' -or $ext -eq '.bat') {",
             '    $comspec = Get-Command -Name cmd -CommandType Application -ErrorAction SilentlyContinue | Select-Object -First 1',
             '    if ($null -eq $comspec) {',
@@ -1280,8 +1292,10 @@ export function wrapScript(body, opts = {}) {
             '      return',
             '    }',
             '    $psi.FileName = $comspec.Source',
-            '    $fx_rest = fx-winargv $argv',
-            "    if ($fx_rest.Length -gt 0) { $psi.Arguments = '/d /s /c ' + (fx-winargv $app.Source) + ' ' + $fx_rest } else { $psi.Arguments = '/d /s /c ' + (fx-winargv $app.Source) }",
+            '    $fx_app = fx-winargv $app.Source $true',
+            '    $fx_rest = fx-winargv $argv $true',
+            "    if ($fx_rest.Length -gt 0) { $fx_tail = $fx_app + ' ' + $fx_rest } else { $fx_tail = $fx_app }",
+            '    $psi.Arguments = \'/d /s /c "\' + $fx_tail + \'"\'',
             '  } else {',
             '    $psi.FileName = $app.Source',
             '    $psi.Arguments = fx-winargv $argv',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "fauxnix-cli",
-  "version": "0.9.2",
+  "version": "0.9.3",
   "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": {