* docs(tools): sync shell.md with the shipped run_shell_command contract
Four statements in this file contradict the tool as shipped.
is_background was documented as required -- twice in the arguments list and the Usage note, plus a "Required Background Parameter" section whose rationale was backwards. The schema is required: [command] (shell.ts:5762) and the parameter description says "Optional: ... If not specified, defaults to false (foreground execution)" (shell.ts:5743), so foreground is the fallback, not what the parameter exists to avoid.
The foreground bullet list recommended cat and grep as one-time foreground commands, which the same tool description forbids in favour of the dedicated tools. #12532 replaced that list in the shipped description with one line; this mirrors it and states why the file tools are not candidates, so the list does not come back.
"or by explicitly adding & to commands" offered & as a second control for backgrounding. On the managed background path a bare trailing & is stripped as redundant (stripTrailingBackgroundAmp, shell.ts:143, called at :4125). The sentence is now scoped to that path instead of claiming & never works: the example further down uses it with is_background=false, which is the unmanaged path, and is left alone deliberately.
Verified against origin/main at e68822c815. No other docs file carries the "required" claim. Prettier clean. Docs only -- no code or test change.
Co-authored-by: Qwen-Coder <[email protected]>
* docs(tools): fix the fourth is_background mention to optional
The Background execution choices bullet still called the parameter
required, contradicting the rest of the page after this PR.
Co-authored-by: Qwen-Coder <[email protected]>
* docs(tools): state the actual trailing-& contract
The page said a bare trailing & is "stripped as redundant" and that a
command containing & backgrounds the call. Neither holds: validation
rejects is_background:true with a trailing bare & before execution, the
spawn-time strip only covers what validation does not classify, and a
mid-command & never makes the tool return early. Rewrite the section
lead, the background bullets, and the mislabeled example to the shipped
contract.
Co-authored-by: Qwen-Coder <[email protected]>
* docs(tools): describe what a shell-level & actually does
56a0952a stated that a bare trailing `&` is stripped at spawn time and
that `npm run dev &` with `is_background=false` runs in the foreground
and blocks the turn. Neither holds. `stripTrailingBackgroundAmp` is
called only from `executeBackground`, reached only when `is_background`
is true; the foreground path passes the command through verbatim, so the
shell detaches it and the result settles on 'close' or
POST_EXIT_STREAM_DRAIN_MS after exit — ShellExecutionService names
`sleep 10 &` as exactly that case.
The difference that matters is tracking, not foreground versus background:
only `is_background=true` registers a background task that `task_stop`
can reach. Also drop the `Background PIDs` field name, which no code
emits; the managed return carries `id` and `pid`.
Co-authored-by: Qwen-Coder <[email protected]>
---------
Co-authored-by: Qwen-Coder <[email protected]>
* perf(cli): optimize one-shot headless execution
* fix(cli): preserve unset shell schema default
* fix(cli): fall back when process replacement fails
* fix(cli): keep relaunch supervisor for headless slash-command prompts
Process replacement leaves no supervisor to consume exit code 43, so a
headless `/update` would exit having installed nothing. Keep the parent
process when the one-shot prompt dispatches as a slash command, and pin
both directions in llm.test.tsx.
Co-authored-by: Qwen-Coder <[email protected]>
* test(cli): update settings dialog snapshots for mode-based PTY default
With no fixed schema default the dialog now renders "(not set)" for
Interactive Shell (PTY) instead of true; refresh the ten snapshots.
Co-authored-by: Qwen-Coder <[email protected]>
* docs(cli): document process-replacement supervisor and reset semantics
Explain at the execve call why afterSpawn has nothing to protect there,
and record in the design doc that onUpdateRelaunch intentionally never
fires on the replacement path and that "reset to default" now clears the
interactive-shell key instead of writing true.
Co-authored-by: Qwen-Coder <[email protected]>
* Revert "fix(cli): keep relaunch supervisor for headless slash-command prompts"
The guarded path is unreachable: both relaunchForUpdate() call sites sit
inside `if (context.executionMode === 'interactive' && projectRoot)`
(update-command.ts:89), and a one-shot prompt resolves executionMode to
'non_interactive' (config.ts:1837-1839 -> nonInteractiveCliCommands.ts:431),
so a headless `/update` updates standalone installs in-process or prints
manual instructions and never exits 43. Per review correction, drop the
guard and its test rather than pin a non-bug.
Co-authored-by: Qwen-Coder <[email protected]>
* test(cli): pin stream-json shell default; document schema default contract
Add the missing --input-format stream-json leg to the shell-default
matrix, and note at the SettingDefinition declaration that `default` is
required for type inference even when its runtime value is undefined.
Co-authored-by: Qwen-Coder <[email protected]>
* test(cli): pin the full replaceProcess predicate for one-shot launches
The verify lane's mutation run left M7 (jsonFd term) surviving and the broader predicate shape unpinned after the slash-command guard was reverted. Assert the replaceProcess value relaunchAppInChildProcess receives across the launch modes: plain and slash-command one-shot prompts replace the process; ACP, -i, file, json-fd, stream-json, and dual-output file inputs keep the supervisor. Mutation-checked: deleting the jsonFd term fails the json-fd row, forcing the expression true fails all six supervisor rows.
Co-authored-by: Qwen-Coder <[email protected]>
Patrol-Run: qwen-pr-closeout/jmuakc4l1ae
* style(cli): prettier-format the replaceProcess predicate test
The Lint & Static lane's Run Prettier step failed on the test file
pushed in 22dd3240aa. Format-only change, no semantics.
Co-authored-by: Qwen-Coder <[email protected]>
Patrol-Run: qwen-pr-closeout/jmuakc4l1ae
* fix(cli): surface execve fallback reason and pin no-prompt predicate
* refactor(cli): name the one-shot prompt predicate and drop redundant pins
---------
Co-authored-by: Qwen-Coder <[email protected]>
Document that the setting defaults to true on most platforms but false
on Windows builds <= 19041 due to ConPTY reliability issues, matching
VS Code's approach.
Co-authored-by: Qwen-Coder <[email protected]>
