[Bug]: SSH link mode fails as "ssh output was not valid UTF-8" when the remote's default shell is PowerShell (real error masked) #6088

Activity

1. github-actions

   added

   bugSomething isn't workingSomething isn't working

   on Sep 27, 2026
2. ZhenyuXiao commented on Sep 27, 2026

   

   ZhenyuXiao

   on Sep 27, 2026

   Author

   More actions

   One clarification that matters for triage: PowerShell is not generally unable to run sh.

   PS> sh -c 'echo 1'
   1
   

   The trigger is specifically the single-quoted command name in the generated argv. buildExecArgv quotes every remote argv element, including the first one, so PowerShell receives:

   'sh' '-c' 'PATH="$PATH:…"; exec ocx "$@"' 'ocx' 'connect' '--link' …
   

   In PowerShell a statement that starts with a quoted string is parsed as an expression, not as a command invocation, so 'sh' '-c' … becomes "string literal followed by string literal" and fails:

   ParserError:
   Line |
      1 |  'sh' '-c' 'PATH="$PATH:$HOME/.bun/bin:…'
        |       ~~~~
        | Unexpected token ''-c'' in expression or statement.
   

   That is exactly the ParserError captured in the report — the caret sits under -c (4 columns = the length of '-c').

   Two consequences worth noting for a fix:

   • Quoting the command name is what makes the difference. A POSIX-shaped invocation with an unquoted command name (sh -c '…' ocx …) would also have run under PowerShell; only the fully-quoted form fails. So "quote only the arguments that need it" may be enough for the simple cases, if the maintainers prefer to keep a single code path.
   • The $PATH=… and $@ inside the script argument survive as-is, because they sit inside a single-quoted string and PowerShell does not interpolate single-quoted strings — so no extra escaping is needed there.

   This does not change the root cause: the strict TextDecoder("utf-8", { fatal: true }) still turns one CP936 ellipsis byte pair (A1 AD) in PowerShell's error output into a generic decode failure that hides all of the above.
3. ZhenyuXiao commented on Sep 27, 2026

   

   ZhenyuXiao

   on Sep 27, 2026

   Author

   More actions

   Update: verified fix (applied in a real install and confirmed end-to-end)

   Emitting the command name bare instead of single-quoting it makes link mode work against a remote whose sshd DefaultShell is PowerShell, with no change on the remote.

   Why it works:

   • PowerShell parses a bare first word as a command name and the following token as an argument. A statement that starts with a quoted string is parsed as an expression, which is exactly what produced the Unexpected token ''-c'' ParserError in the report.
   • POSIX shells are unaffected: a bare sh and a quoted 'sh' are the same word, so Linux/macOS remotes keep behaving identically.

   Patch (src/link/ssh-argv.ts, quoteRemote):

    export function quoteRemote(argv: readonly string[]): string {
   -  return argv.map(arg => {
   +  return argv.map((arg, index) => {
        if (arg.includes("\0")) throw new LinkSshArgumentError("remote argument contains NUL");
   +    // The command name stays bare: PowerShell parses a leading quoted string as an
   +    // expression (`'sh' '-c' …` → "Unexpected token ''-c''"), while a bare word is a
   +    // command in both PowerShell and POSIX shells. Restricted to a conservative shape.
   +    if (index === 0) {
   +      if (!/^[A-Za-z0-9._-]+$/.test(arg)) {
   +        throw new LinkSshArgumentError(`remote command name is not a safe bare token: ${JSON.stringify(arg)}`);
   +      }
   +      return arg;
   +    }
        return `'${arg.replaceAll("'", `'"'"'`)}'`;
      }).join(" ");
    }

   Resulting wire form (printed by calling the patched function through the bundled Bun runtime):

   sh '-c' 'PATH="$PATH:$HOME/.bun/bin:$HOME/.local/bin:/opt/homebrew/bin:/usr/local/bin"; exec ocx "$@"' 'ocx' 'link' 'port'
   

   Verification performed:

   1. Reproduced the failure locally by running the current form through pwsh ('sh' '-c' … → the same ParserError, caret under -c), then confirmed the bare form parses fine (sh '-c' …).
   2. Confirmed PowerShell's native argument passing keeps the single-quoted elements as separate, quote-stripped arguments and does not interpolate the script argument — so $PATH and $@ still expand in the remote sh, and --key-stdin still receives stdin.
   3. Applied the patched quoteRemote in a real install, restarted the service, and completed the link: a Windows host whose OpenSSH DefaultShell is PowerShell now joins successfully as a Child. ocx --version, ocx link port, ocx link status --json, ocx link revoke and the tunnel all keep working.

   Notes for a maintainer-side fix:

   • This keeps a single code path — no remote-shell detection is needed for this failure mode. If you prefer detection over bare-quoting, the observable check is simply whether the command name survives as a command on the remote (sh -c true-style probe).
   • The strict TextDecoder("utf-8", { fatal: true }) still hides this whole class of failure whenever a non-UTF-8 byte appears (here: a single CP936 …). Decoding leniently, or attaching a hex / first-line excerpt to the error, would have surfaced the PowerShell error immediately instead of "ssh output was not valid UTF-8".
4. lidge-jun

   added 4 commits that reference this issue on Sep 27, 2026

   fix(link): invoke sh bare and surface non-UTF-8 ssh errors

   ...

   This issue will close once commit 039dae3 is merged into the 'main' branch.

   039dae3

   fix(link): invoke sh bare and surface non-UTF-8 ssh errors

   ...

   This issue will close once commit bf9de81 is merged into the 'main' branch.

   bf9de81

   fix(link): invoke sh bare and surface non-UTF-8 ssh errors

   ...

   This issue will close once commit 6a6abe3 is merged into the 'main' branch.

   6a6abe3

   fix(link): invoke sh bare and surface non-UTF-8 ssh errors

   ...

   This issue will close once commit 9f50bdd is merged into the 'main' branch.

   9f50bdd
5. lidge-jun commented on Sep 27, 2026

   

   lidge-jun

   on Sep 27, 2026

   Owner

   More actions

   Fixed on dev by #6113 (merge 2275680ab3, commit 9f50bddfe8). Thanks @ZhenyuXiao for the precise diagnosis and the end-to-end check.

   • The remote command now emits sh bare. Only sh is accepted in command position, and every argument stays single-quoted, so a PowerShell OpenSSH DefaultShell dispatches it as a command.
   • The Child's SSH runner caps stderr bytes, then decodes with replacement, so a CP936 error line reaches the redacted, length-bounded hint instead of ssh output was not valid UTF-8. Structured stdout stays strict UTF-8.

   Verification: a Windows-only test runs powershell.exe's parser on the generated command and asserts a single sh command invocation. It ran and passed on the Windows 6/9 shard of Cross-platform CI run 36331108394. POSIX tests execute the generated string through /bin/sh and check that argument bytes arrive intact. Runner tests cover invalid-UTF-8 stderr, strict stdout and the byte cap.

   Known limit: your end-to-end check used pwsh 7. Windows PowerShell 5.1's legacy native-argument passing does not escape embedded double quotes, and the -c script contains some, so that combination is untested. If you hit it, please open a new issue.
6. lidge-jun

   closed this as completedon Sep 27, 2026