Repository navigation
fix(vscode): no fallback to a bare binary name, and the command quoted for the terminal's shell - #773
Merged
Merged
Conversation
…r the terminal's shell, and a real file check test
…phic quotes, and refuse a path a shell would act on
…ts; backslash safe only on Windows; pwsh on macOS/Linux
…capes control characters
3 of 4 tasks
jay23606
added a commit
to jay23606/flutter-probe
that referenced
this pull request
Nov 17, 2026
…d for the terminal's shell (AlphaWaveSystems#773) ## Summary Three follow-ups from the review of AlphaWaveSystems#769, in the VS Code extension's binary resolution. 1. **A behavior test for the real regular-file check.** `isFile` in `config.ts` was checked only through its source text, so the reviewer's mutant `isFile() || true` survived. It is now `isRegularFile` in the pure `toolPath.ts`, and `config.ts` passes it to the resolver. It is tested on real files: a file, a directory, a missing path, a link to a directory and a link to a file. 2. **No fallback to a bare name.** On macOS and Linux, when `probe` was on no absolute folder of PATH, the extension ran the bare name `probe`. That name could only be found through an empty or relative PATH entry (`::`, `.`, `bin`), and those resolve against the working directory, which is the workspace. Not found is now an error on every system, as it already was on Windows. `listDevices` and lint-on-save still return nothing instead of throwing (AlphaWaveSystems#769), and the commands show the message. 3. **Terminal quoting of the command path.** A command path with a space (`C:\Program Files\…`) broke in the terminal. `commandWord` (pure, `toolPath.ts`) quotes the command for the shell the terminal runs, taken from `vscode.env.shell` (per the API, "the detected default shell for the extension host"), or refuses a path it cannot type safely. A path made only of safe characters is typed as it is. | Shell | What is typed | |---|---| | bash, sh, zsh, dash, ksh (also Git Bash or WSL on Windows) | POSIX single quotes | | PowerShell | `& '…'`, with `'`, `‘` and `’` doubled. [about_Quoting_Rules](https://learn.microsoft.com/en-us/powershell/module/microsoft.powershell.core/about/about_quoting_rules) says PowerShell treats the typographic quotes "as normal quotation marks" and that a quote inside a single-quoted string is doubled. A path with `‚` or `‛` (not listed on that page) is **refused**: doubling a non-quote would change the path, and not doubling a quote would end the string. | | cmd.exe | `"…"`. A path with `%` (or `"`) is **refused**: `%NAME%` expands inside double quotes, and the [cmd reference](https://learn.microsoft.com/en-us/windows-server/administration/windows-commands/cmd) documents no way to escape it on a command line. | | any other shell (fish, nu, csh, pwsh on macOS or Linux, or none detected) | A path with a shell metacharacter (`& \| ; < > ^ \` $ ( ) ' " % !`, a newline, and on macOS and Linux a backslash) is **refused**. Otherwise the path is single-quoted on macOS and Linux, and typed as it is on Windows (a space only). | A refusal is an error that says what to do: install it in a folder without that character, or use another terminal shell. **This covers the command word only. The arguments are still quoted the POSIX way on every system**; that is a separate fix. The README and the unreleased CHANGELOG entry of AlphaWaveSystems#769 now describe both changes: not found is an error on every system, and the command is quoted (or refused) per shell. The VS Code docs page describes the not-found rule; it makes no quoting claim. ## Tests `vscode/src/test/toolPath.test.ts`: - `isRegularFile` on real files and symlinks (the symlinks are skipped on Windows); - not found is an error with no platform argument; - `commandWord` per shell: PowerShell with `'`, `‘` and `’` doubled (including a crafted `C:\x’; calc; ‘\probe.exe`, which stays one string, and `O’Brien`), and `‚` `‛` refused; cmd.exe refusing `%` and keeping `&` inside the quotes; unknown Windows and POSIX shells refusing each metacharacter and quoting a plain space; - **a real-shell test:** for each of bash, sh, zsh, dash and ksh installed (all five ran on macOS), seven hostile paths (a `'` with `; touch PWNED;`, `$(…)`, backticks, a newline, `" ; | &`, bidi and zero-width characters) are typed through `commandWord` and printed back by the shell. Each comes back as one word, byte for byte, and `PWNED` is never created; - `quotePosix` with a `'`; - the source checks updated: `config.ts` passes `isRegularFile`, and the terminal uses `commandWord(command, process.platform, vscode.env.shell)`. ## Mutation check Each mutant was applied, the tests were run, and the file was restored byte for byte. All 18 were killed: 9 for the first version, and 9 for the per-shell rules after the review. | Mutant | Result | |---|---| | `isRegularFile` accepts anything (`\|\| true`) | killed | | `isRegularFile` accepts a directory | killed | | not found falls back to the bare name | killed | | PowerShell without the call operator | killed | | cmd.exe gets the path as it is | killed | | Git Bash is not quoted | killed | | the POSIX command is not quoted | killed | | a single quote is not escaped | killed | | the terminal ignores `commandWord` | killed | | PowerShell: `’` not doubled | killed | | PowerShell: `‘` not doubled | killed | | PowerShell: U+201A not refused | killed | | cmd.exe: `%` not refused | killed | | an unknown shell gets a metacharacter | killed | | POSIX: a backslash not refused under an unknown shell | killed | | every shell treated as POSIX | killed | | dash not a verified shell | killed | | `quotePosix` does not escape a quote | killed | ## Not covered - No run in a real Windows terminal. The PowerShell and cmd.exe quoting follows Microsoft's pages, cited above, and is tested as text. The POSIX quoting ran in real shells. - The arguments are still quoted the POSIX way on every system, as before this change. An argument with a space typed into a cmd.exe or PowerShell terminal is a separate fix. ## Test plan - [x] `npm test` in `vscode/` passes: 79 tests. - [x] `npm run compile` passes. - [x] Mutation check (table above). ## Review follow-up - **Control characters are refused, for every shell, in the command and in every argument.** A line-editing shell acts on a control character while the text is typed: in bash, ^U deletes back to the start of the line, ^A moves to it and ^C cancels it, so a quoted path could lose its opening quote and run what follows (found in review with a real pty). `commandWord` now refuses U+0000 to U+001F and U+007F first, on every platform and shell. The arguments go through `quoteArg` in `toolPath.ts` (`shellEscape` in `probeTerminal.ts` now calls it), which refuses them too. This predates the PR, since the arguments had it. - **The backslash is typed unquoted only on Windows.** The safe-characters shortcut excluded nothing, so `/x/back\slash/probe` was typed bare on POSIX and the shell dropped the backslash. Now on macOS and Linux it is single-quoted for bash, sh, zsh, dash, ksh and WSL, and refused for any other shell. The earlier claim is now true: `commandWord('/a\\b/p', 'linux', '/bin/fish')` throws. - **PowerShell on macOS and Linux** runs a single-quoted path as a string, not a command, so only a path of plain characters is typed there; a space, `'`, `‘` or `’` is refused with a message. - **Tests:** - control characters (NUL, ^A, ^C, tab, LF, CR, ^U, ESC, U+001F, DEL) refused for 8 shell and platform pairs and for arguments; - the backslash quoted or refused on POSIX; - `wsl` on Windows (the earlier survivor); - pwsh on POSIX. The real-shell test of bash, sh, zsh, dash and ksh now uses a plain backslash path instead of the backslash-newline one, which is refused now. - **Mutants:** 6 of 6 killed: - control characters not refused, in the command; - control characters not refused, in the arguments; - the backslash safe on POSIX; - pwsh on POSIX typing any path; - `wsl` not a POSIX shell; - `CONTROL` missing U+007F. - `npm test`: 83 passed, 0 failed. Main is merged in. ## Second review follow-up - **C1 control characters (U+0080 to U+009F) are refused too**, in the command and in every argument. Under a single-byte locale (`LC_ALL=C`), readline reads a C1 character's second byte as a meta key: U+0092 is revert-line and U+0088 is M-Backspace, so the opening quote could be stripped (found in review in a real bash). `CONTROL` is now `[\^@-\^_\u007f-\^_]`. The tests add U+0080, U+0085, U+0088, U+0092 and U+009F for every shell and platform pair and for arguments. - **The refusal message escapes** DEL, C1, U+2028 and U+2029 as `\uXXXX`, so the message carries none of them. There's a test for this. U+2028/U+2029 are still allowed in a path: typed quoted, they did nothing. - Mutants: 4 of 4 killed (C1 missing, the message not escaping, and the two refusals again). `npm test`: 84 passed, 0 failed.
pbertsch
added a commit
that referenced
this pull request
Nov 17, 2026
…e in the terminal (#813) ## Summary The VS Code extension typed each tool's command line into the integrated terminal, quoted for the terminal's shell. **That can't be made safe**, so this PR removes it: the extension now runs the binary itself, with its arguments as a list and no shell, and shows the output in its own terminal. **Why quoting can't work.** The review reproduced this, and I reproduced it again. Under bash with `LC_ALL=C` or `LC_ALL=POSIX` (an SSH session, a container, any terminal with no locale), readline reads the bytes of a UTF-8 character one by one and acts on some of them as keys. The second byte of `Ò` (U+00D2, `C3 92`) and of U+2012 (`E2 80 92`) is `0x92`, which readline treats as revert-line: it drops everything typed so far, the opening quote included, and the rest is read as a new line. I typed the old code's quoted argument for `aÒx;touch PWN8;'` into an interactive shell in a real pty (`printf '%s\n' <word>`, then Enter): | Shell, locale | `touch PWN8` ran | |---|---| | `/bin/bash` (3.2.57), `LC_ALL=C` | **yes** | | `/bin/bash`, `LC_ALL=POSIX` | **yes** | | `/bin/bash`, `en_US.UTF-8` | no | | `/bin/zsh`, `LC_ALL=C` | no | The locale of the terminal can't be detected from the extension, and the same holds for other bytes and line editors. The earlier version of this PR, and `shellEscape` before it, had the same hole. ## The change - **`vscode/src/terminal/processRun.ts` (new).** - `RunQueue` starts the binary with `spawn(command, args, { shell: false, … })`. No shell parses, expands or line-edits an argument, on any system, under any terminal shell or locale. - It writes the output with `\r\n` line ends. - A run asked for while another runs in the same terminal starts when that one ends, as a command typed into a busy shell did. - Typed text is echoed and sent to the running tool line by line. Backspace edits the line, and arrow and function keys are dropped rather than typed as their letters. Ctrl+C sends SIGINT. - Closing the terminal drops waiting runs and sends SIGINT. Stopping a recording disposes its terminal, so `probe record` still gets its interrupt. - The command is shown above its output. Control characters, line and paragraph separators and bidirectional characters are written as `\uXXXX`, so a file name can't move the cursor, recolor the terminal or reorder what's shown. - **`probeTerminal.ts`.** Each named terminal is a VS Code `Pseudoterminal` backed by a `RunQueue`. Output written before VS Code opens the terminal is kept until `open`, because the API drops earlier events. The output stays after the run ends. - **Removed.** `argWord`, `commandWord`, `quoteArg`, `quotePosix` and `refuseControl` are gone, along with the shell-name logic. So are `terminalAction` and `envFingerprint`, which only existed because a terminal's environment was fixed when it was created; each run now gets its own environment. The secret-flag refusal stays. - **Why not `createTerminal({ shellPath, shellArgs })`.** That would also skip the shell, but each run would get a new terminal process, and keeping the output after the run ends depends on the user's settings. The pseudoterminal keeps the output, reuses the terminal, and queues runs. **What users notice:** - The run gets VS Code's environment (plus the secrets of a test run, as before), not the one their shell profile builds. A variable set only in a profile that VS Code didn't read won't reach it. - The command isn't in the shell's history. - The terminal isn't a shell to type other commands into. This is in the CHANGELOG and the README. **The other review points** applied to the quoting code, which is removed: - zsh's `=ls`: `=ls` is now just an argument, and it's in the hostile set; - the cmd-branch mutant; - PowerShell 5.1 dropping an empty argument: an empty argument now reaches the tool, and it's in the hostile set; - `!` under cmd's delayed expansion. The CHANGELOG line about control characters is replaced by the new entry. The #773 entry now points to it. ## Tests (`vscode/src/test/processRun.test.ts`, 10) - **Real processes.** Node runs a script that prints its arguments. 21 hostile arguments reach it as 21 arguments, unchanged, and no `PWNED` file appears. They include the quote and `$(…)` payloads, the backtick, `%PATH%`, `=ls`, an empty argument, a trailing backslash, a newline, bidi characters, and the `Ò` and U+2012 payloads. - **The review's case.** The `Ò` payload under `LC_ALL=C` and under `LC_ALL=POSIX` arrives as one unchanged argument, and `PWN8` isn't created. - **Errors.** A binary that can't be started says so (ENOENT), and the next run still starts. - **Queue behavior, with a stand-in child:** - a second run waits, then starts; - the run's cwd and env are passed; - output gets `\r\n`, and an error followed by a close ends the run once; - echo, a line sent to the tool, backspace, arrow and F1 dropped, Ctrl+C → SIGINT; - closing the terminal drops waiting runs and interrupts; - the shown command escapes ESC, bidi characters, C1 characters, quotes and backslashes. - **Source checks** (the terminal file imports `vscode`): - output is buffered until `open`; - `close` stops the queue and typed text goes to the queue; - no `sendText`, `shellPath` or `child_process` in the terminal file; - `spawn` uses `shell: false`. ## Mutation check Each mutant was applied, compiled and tested, then restored byte for byte. All 13 were killed: - spawning through a shell; - escape sequences typed as letters; - Ctrl+C not interrupting; - the interrupt being a plain kill; - a second run starting at once; - `stop` keeping waiting runs; - a run ending twice; - bare `\n` written to the terminal; - control characters shown raw; - the run's env not added; - output before `open` dropped; - closing not stopping the run; - the secret flag not refused. ## Test plan - [x] The extension's tests: 82 of 82 pass. This includes the generated-file checks, now green after #815. A local `npm test` here also picks up a stale compiled `out/test/argWord.test.js` from before its source was removed; `out/` is ignored, and a fresh checkout doesn't have it. - [x] `tsc` is clean, and no raw control or format characters are in the sources. - [x] The old hole was reproduced with a real pty, as above. - [ ] Manual run in VS Code (Run test, Record and stop, Devices): not done here, since no VS Code UI session is available to me. ## Second review follow-up - **Blocker: orphaned processes.** `stop()` (closing the terminal, or deactivating the extension) only sent SIGINT. - **macOS and Linux:** the tool now starts in its own process group (`detached`), and SIGINT goes to the whole group, as Ctrl+C in a shell does. A tool still running after 15 seconds gets SIGKILL (`probe record` waits up to 5 s for the agent after SIGINT, then writes the file), with its group. The timer is cancelled when the tool ends. - **Windows:** there is no Ctrl+C for another process, so Ctrl+C and close both end the tool and every program it started with `taskkill /T /F /PID`, run by its full path under `%SystemRoot%\System32`. The README now says that a recording isn't saved there. - **EPIPE:** `child.stdin` has an error handler, so typing into a tool that closed its input isn't an uncaught error. - **README:** the secrets paragraph now describes per-run environments; the old text said they stayed in the terminal for every command typed there. It also covers what Ctrl+C does on each OS, and notes that the tool's output, escape sequences included, is written as it is. - **The two test gaps from the review:** - the run's env now wins over VS Code's own `PROBE_CLOUD_KEY`, with a test; - a spawn that throws still starts the next waiting run, tested both as the first run and while another run waits. - **`.bat` and `.cmd` on Windows** are refused up front with a clear message, which modern Node would otherwise turn into an EINVAL. **Not verified on a real Windows machine:** I have none here. The Windows branches are covered by unit tests with the platform injected. - **Caps:** 100 waiting runs, a typed line of 64 KiB, and 1 MiB of output kept before the terminal opens. Beyond that, the output is cut with a note. - Main is merged. The CHANGELOG conflict is resolved, and this PR's entry is last in Security. **Tests: 8 new**, 18 in `processRun.test.ts`. - **Real processes (POSIX).** These are the review's `o.js` case: - a tool that ignores SIGINT and starts `sleep 300`: after `stop()` with a 300 ms grace period, both are gone 1.2 s later, and the waiting run doesn't start; - Ctrl+C ends the `sleep` grandchild through the process group; - a tool that closes its input while Enter is typed twice: no uncaught exception (the review's `e.js` case). - **With the stand-in child:** - env precedence; - a spawn that throws; - SIGINT, then SIGKILL after the grace period, and no SIGKILL when the tool ended in time; - the `.bat` and `.cmd` refusal on Windows only; - the caps. **Mutants:** 10 of 11 killed. The 11th, not cancelling the SIGKILL timer when the tool ends, is equivalent: the timer only signals while `this.running === child`, so removing the `clearTimeout` changes nothing observable. The extension tests pass, 90 of 90. ## Third review follow-up - **Deactivate could orphan a tool.** `deactivate()` returned at once, and the 15-second SIGKILL timer died with the extension host. - `RunQueue.shutdown(graceMs)` sends SIGINT, sends SIGKILL after `graceMs`, and resolves once the tool has ended. - `deactivate()` now returns `stopAllTerminals()`, which shuts every queue down with a 1-second grace and waits for them, capped at 3 seconds. That's a short time because the window is closing and VS Code waits only briefly; I didn't verify how long VS Code waits. - A recording in progress isn't saved on deactivate. The README and CHANGELOG say so. - A later `stop()` (the terminal's own close) never moves a SIGKILL later than one already scheduled. - **README and CHANGELOG:** if the extension host crashes, a tool it started keeps running until it next writes output, when its closed pipe ends it. - **Tests for the survivors:** - `stop()` of a run that already ended signals nothing; - the 15-second default grace, pinned with mock timers (14,999 ms: SIGINT only; 15,000 ms: SIGKILL); - the `taskkill` arguments `/T /F /PID <pid>` by full path under `SystemRoot`, with a fallback to Node's kill when `taskkill` can't start, through the new `makeSignalTree` with a stand-in spawn; - a refused `.cmd` lets the next waiting run start; - after a stopped run ends, the next run still escalates; - deactivate's wiring (source check); - the review's `d.js` case as a real process: a tool that ignores SIGINT is gone when `shutdown(300)` resolves. - **Mutants: 11 of 12 killed.** The survivor is equivalent. Removing the timer's `this.running === child` guard can't change a result while the `clearTimeout` on exit exists; the two are redundant defences against signalling a reused pid. My first run of this set hung on the mutant whose `shutdown` never resolves, so the harness now runs with `--test-timeout`. I ended that hung test process by its pid. - **Results:** `processRun.test.ts` passes 26 of 26, and the extension tests pass 98 of 98.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Three follow-ups from the review of #769, in the VS Code extension's binary resolution.
A behavior test for the real regular-file check.
isFileinconfig.tswas checked only through its source text, so the reviewer's mutantisFile() || truesurvived. It is nowisRegularFilein the puretoolPath.ts, andconfig.tspasses it to the resolver. It is tested on real files: a file, a directory, a missing path, a link to a directory and a link to a file.No fallback to a bare name. On macOS and Linux, when
probewas on no absolute folder of PATH, the extension ran the bare nameprobe. That name could only be found through an empty or relative PATH entry (::,.,bin), and those resolve against the working directory, which is the workspace. Not found is now an error on every system, as it already was on Windows.listDevicesand lint-on-save still return nothing instead of throwing (fix(vscode): a workspace cannot choose the binaries the extension runs #769), and the commands show the message.Terminal quoting of the command path. A command path with a space (
C:\Program Files\…) broke in the terminal.commandWord(pure,toolPath.ts) quotes the command for the shell the terminal runs, taken fromvscode.env.shell(per the API, "the detected default shell for the extension host"), or refuses a path it cannot type safely. A path made only of safe characters is typed as it is.& '…', with',‘and’doubled. about_Quoting_Rules says PowerShell treats the typographic quotes "as normal quotation marks" and that a quote inside a single-quoted string is doubled. A path with‚or‛(not listed on that page) is refused: doubling a non-quote would change the path, and not doubling a quote would end the string."…". A path with%(or") is refused:%NAME%expands inside double quotes, and the cmd reference documents no way to escape it on a command line.& | ; < > ^ \$ ( ) ' " % !`, a newline, and on macOS and Linux a backslash) is refused. Otherwise the path is single-quoted on macOS and Linux, and typed as it is on Windows (a space only).A refusal is an error that says what to do: install it in a folder without that character, or use another terminal shell. This covers the command word only. The arguments are still quoted the POSIX way on every system; that is a separate fix.
The README and the unreleased CHANGELOG entry of #769 now describe both changes: not found is an error on every system, and the command is quoted (or refused) per shell. The VS Code docs page describes the not-found rule; it makes no quoting claim.
Tests
vscode/src/test/toolPath.test.ts:isRegularFileon real files and symlinks (the symlinks are skipped on Windows);commandWordper shell: PowerShell with',‘and’doubled (including a craftedC:\x’; calc; ‘\probe.exe, which stays one string, andO’Brien), and‚‛refused; cmd.exe refusing%and keeping&inside the quotes; unknown Windows and POSIX shells refusing each metacharacter and quoting a plain space;'with; touch PWNED;,$(…), backticks, a newline," ; | &, bidi and zero-width characters) are typed throughcommandWordand printed back by the shell. Each comes back as one word, byte for byte, andPWNEDis never created;quotePosixwith a';config.tspassesisRegularFile, and the terminal usescommandWord(command, process.platform, vscode.env.shell).Mutation check
Each mutant was applied, the tests were run, and the file was restored byte for byte. All 18 were killed: 9 for the first version, and 9 for the per-shell rules after the review.
isRegularFileaccepts anything (|| true)isRegularFileaccepts a directorycommandWord’not doubled‘not doubled%not refusedquotePosixdoes not escape a quoteNot covered
Test plan
npm testinvscode/passes: 79 tests.npm run compilepasses.Review follow-up
Control characters are refused, for every shell, in the command and in every argument. A line-editing shell acts on a control character while the text is typed: in bash, ^U deletes back to the start of the line, ^A moves to it and ^C cancels it, so a quoted path could lose its opening quote and run what follows (found in review with a real pty).
commandWordnow refuses U+0000 to U+001F and U+007F first, on every platform and shell. The arguments go throughquoteArgintoolPath.ts(shellEscapeinprobeTerminal.tsnow calls it), which refuses them too. This predates the PR, since the arguments had it.The backslash is typed unquoted only on Windows. The safe-characters shortcut excluded nothing, so
/x/back\slash/probewas typed bare on POSIX and the shell dropped the backslash. Now on macOS and Linux it is single-quoted for bash, sh, zsh, dash, ksh and WSL, and refused for any other shell. The earlier claim is now true:commandWord('/a\\b/p', 'linux', '/bin/fish')throws.PowerShell on macOS and Linux runs a single-quoted path as a string, not a command, so only a path of plain characters is typed there; a space,
',‘or’is refused with a message.Tests:
wslon Windows (the earlier survivor);The real-shell test of bash, sh, zsh, dash and ksh now uses a plain backslash path instead of the backslash-newline one, which is refused now.
Mutants: 6 of 6 killed:
wslnot a POSIX shell;CONTROLmissing U+007F.npm test: 83 passed, 0 failed. Main is merged in.Second review follow-up
LC_ALL=C), readline reads a C1 character's second byte as a meta key: U+0092 is revert-line and U+0088 is M-Backspace, so the opening quote could be stripped (found in review in a real bash).CONTROLis now[\u0000-\u001f\u007f-\u009f]. The tests add U+0080, U+0085, U+0088, U+0092 and U+009F for every shell and platform pair and for arguments.\uXXXX, so the message carries none of them. There's a test for this. U+2028/U+2029 are still allowed in a path: typed quoted, they did nothing.npm test: 84 passed, 0 failed.