Skip to content

ROCMAI-955: take the diagnose symptom from a file or stdin with --symptom-file - #1048

Merged
volen-silo merged 1 commit into
mainfrom
rocmai-955-symptom-file
Nov 13, 2026
Merged

volen-silo merged 1 commit into
mainfrom
rocmai-955-symptom-file

Conversation

@volen-silo

@volen-silo volen-silo commented Nov 11, 2026 •

Copy link
Copy Markdown
Collaborator

Why

rocm diagnose --symptom <TEXT> takes the user's pasted error as a shell argument, and a pasted error is exactly the input shells rewrite. In bash, $(...) inside double quotes runs. PowerShell does the same, and has its own rules for a stray quote. cmd.exe has no single quote at all. A paste that starts with - (a Windows NTSTATUS such as -1073741819) is rejected by clap as an unknown flag before rocm sees it. So the text that reaches the matcher may not be what the user pasted, and part of the paste can run as a command. The rocm-doctor skill currently works around this with per-shell quoting rules, and on PowerShell and cmd.exe it can only hand the user the command.

What changes

  • New rocm diagnose --symptom-file <PATH>. - reads standard input. It cannot be combined with --symptom.
  • The text that arrives is matched as --symptom would match it, minus one trailing \n or \r\n. A heredoc, echo, an editor and PowerShell's pipe each add exactly one. Any other whitespace is the user's and is kept.
  • A UTF-8 byte-order mark is dropped. UTF-16 with a byte-order mark, which Windows PowerShell 5.1's > writes, is decoded. Anything else must be UTF-8.
  • Windows PowerShell 5.1 pipes text to a native program as ASCII by default, so Get-Clipboard | rocm diagnose --symptom-file - turns every non-ASCII character of a paste into ? there (PowerShell 7 delivers it intact). The documentation recommends Get-Clipboard -Raw > error.txt followed by rocm diagnose --symptom-file error.txt, which is lossless on both shells, and says why.
  • Input is capped at 16 MiB. An unreadable path, a directory, non-text input and oversize input are each a clap usage error (exit 2) with rocm diagnose's usage line, never a panic. The README, --help, docs/testing.md and docs/manual-testing.md list the same causes.
  • When the path is - and stdin is a terminal, a hint on stderr says how to finish the paste: Ctrl-D, or Ctrl-Z then Enter on Windows. Without it the command would wait silently.
  • --help, README.md, docs/testing.md, docs/manual-testing.md, docs/wsl.md and docs/architecture.md describe the flag, with a bash heredoc, the PowerShell forms and a cmd.exe file example.
  • The advised-command scanner now treats a heredoc (<<) as a redirection, including when a second command follows it (<<'EOF' && …, <<EOF;, << EOF ||), so the documented bash form passes every_advised_command_parses and the command after it is still checked.

Verification

New scenarios in tests/e2e-cucumber/features/diagnose.feature:

  • diagnose-59: a paste with double and single quotes, $(...), & and a leading -v, piped through cmd.exe and Windows PowerShell, is diagnosed the same, cause for cause, score for score and evidence for evidence, as the same text passed as a safely quoted argument. The paste is ASCII only, because of the 5.1 pipe encoding above. The scenario cannot show that trimming works (the causes do not depend on a trailing line break) or that no shell ran the paste (the paste reaches each shell only as the contents of a file); the unit tests hold the trimming.
  • diagnose-60 (@requires-os:linux): a paste typed at a terminal is read until end-of-input, the CLI first prints how to end it, and the terminal screen then contains the whole report the argument form prints for the same text. It first requires that report to differ from a run with no symptom, so host-only causes cannot satisfy it.
  • diagnose-61: a missing file and a non-text file each exit 2 with the reason.
Platform Run Result
Windows cargo test --workspace --all-targets --no-fail-fast (AGENTS.md §8) 46 test binaries, 6474 pass, 0 fail, 17 ignored
Windows cargo clippy --workspace --all-targets -D warnings, python scripts/smoke_local.py (AGENTS.md §8) clean; smoke: ok
Windows cargo nextest run -p e2e-cucumber -p rocm (the cargo xtask affected set) 2052 pass, 6 skipped
Windows cargo xtask e2e for diagnose-59, -60, -61 59 and 61 pass; 60 skipped by its Linux tag
WSL2 (Ubuntu, Strix Halo) cargo nextest run -p e2e-cucumber -p rocm 2200 pass, 2 fail (below)
WSL2 cargo xtask e2e for diagnose-59, -60, -61 all 3 pass
Windows cargo fmt --check, feature_naming, skill_reference pass

The full-gate rows were taken one commit before the final wording pass. That pass changes only comments, documentation and the text of one step name and one assertion message. fmt, clippy, feature_naming, skill_reference and the three scenarios were re-run on the final tree, on Windows and in WSL2.

The 2 WSL failures are build_metadata::build_script::tests::git_watch_paths_*. They fail because that account's git config signs commits with an SSH key that is absent there, so the tests' own git commit fails. This change does not touch build.rs or those tests.

Not verified: the PowerShell 7 and cmd.exe forms by hand at an interactive terminal (diagnose-59 covers piped input through both shells); Ctrl-Z end-of-input in a native Windows console, which is covered only by the manual check in docs/manual-testing.md section 13; an input over 16 MiB through a scenario (the unit tests cover the limit, the exit code and the printed message).

Scope

  • skills/rocm-doctor/ is not changed here. fix(skill): make rocm-doctor follow what the rocm CLI does, and grade it #1029 rewrites those files, and the skill's quoting rules move to --symptom-file in a follow-up once it lands.
  • The vLLM out-of-memory note after rocm serve keeps printing rocm diagnose --symptom '<line>'. vLLM runs only on Linux and WSL, where that line is already quoted safely or falls back to a canonical symptom.
  • rocm remote doctor --symptom gets no file form in this change.
  • The symptom is read before the machine is examined. A --symptom-file that cannot be read, or an unrelated refusal such as --model with --distro, is therefore reported only after the paste has been asked for on a terminal. Moving the read after the refusal check needs its own scenario and is a follow-up.
  • Empty input counts as no symptom, the same as --symptom "", and non-UTF-8 text is refused rather than decoded with replacement characters.

Part of ROCMAI-955.

  • If this PR fixes a bug, searched tests/e2e-cucumber/expectations.toml for the fixed ticket ID and removed/narrowed any now-stale xfail rows. Not applicable: no bug fix.
  • If this PR adds a new subcommand or subsystem, its domain implementation lives in its own file per docs/architecture.md. The reading and decoding live in apps/rocm/src/symptom_input.rs; only the clap flag and the dispatch call are in cli.rs and main.rs.
  • Every new or changed user-facing message was read against the code path that runs after it, and its test asserts the resulting state, per AGENTS.md §3. The terminal hint is asserted together with the paste being read and diagnosed (diagnose-60). The usage errors are asserted together with exit 2 and no diagnosis (diagnose-61). The 16 MiB message is held by unit tests through the same error path, with no scenario.

@github-actions

github-actions Bot commented Nov 11, 2026 •

Copy link
Copy Markdown
Contributor
Security scan found no critical or high findings on lines changed by this pull request

View the security scan run for complete reports.

“New” means the finding is located in a changed file on an added or modified line; it is not a base-versus-head findings delta.

@volen-silo

Copy link
Copy Markdown
Collaborator Author

Merge note: #1048, #1051, #1052 and #1053 each add e2e scenarios numbered from diagnose-59 in diagnose.feature, and feature_naming requires the numbers to be sequential. Whichever of the four merges first keeps its numbers. Each of the others renumbers on rebase, and updates the numbers cited in its docs/testing.md section. Their @id: tags are distinct, so only the numbers collide. Their skill-doc follow-ups wait for #1029 to merge.

…file

A pasted error does not survive a shell as an argument: bash and
PowerShell run a $(...) even inside double quotes, a stray quote ends
the argument early, cmd.exe has no single quotes, and an error starting
with "-" is refused as a flag. `rocm diagnose --symptom-file <PATH>`
reads the text from a file, or from standard input when PATH is "-", so
the shell only ever parses the fixed command.

The text that arrives is matched as --symptom would match it, with one
trailing line break removed (heredocs, editors and PowerShell's pipe to
a native command each add one). A UTF-8 byte-order mark is dropped and
UTF-16 with a byte-order mark, which Windows PowerShell's ">" writes, is
decoded; anything else must be UTF-8. An unreadable file, input that is
not text, or input over 16 MiB is a usage error (exit 2) with the
diagnose usage line, never a panic. With a terminal on stdin the CLI
says how to end the paste. The two flags are mutually exclusive.

Windows PowerShell 5.1 pipes text to a native program as ASCII, turning
every other character into "?", so the docs have PowerShell users save
the clipboard with `Get-Clipboard -Raw > error.txt` and pass that file
rather than pipe it.

The serve OOM note keeps printing `rocm diagnose --symptom '<line>'`: it
already falls back to a canonical symptom when the line cannot be one
intact single-quoted word, and it is only printed where vLLM runs (Linux,
WSL), so the printed command stays runnable as is.

The advised-command scanner now treats a heredoc ("<<") as a
redirection rather than the start of a <placeholder>, so the documented
bash form is checked and a command after it in the same list is still
split off and checked.

Covered by unit tests for decoding, trimming and the error paths, a clap
test, a scanner test, and diagnose-59 to diagnose-61: a paste full of
quotes, $(...) and a leading "-" piped through bash, cmd.exe and Windows
PowerShell gets the same causes, scores and evidence as the same text
passed as one argument; a paste typed at a terminal is explained and
leaves a screen containing the whole report the argument form prints,
which must differ from the report without a symptom (Linux only, like
the suite's other pseudo-terminal scenarios); and unusable files are
refused as usage errors.

ROCMAI-955

Signed-off-by: Eugene Volen <eugene.volen@amd.com>
@volen-silo
volen-silo force-pushed the rocmai-955-symptom-file branch from 53546b0 to 7c4a1cb Compare November 13, 2026 07:16
@volen-silo
volen-silo marked this pull request as ready for review November 13, 2026 08:24
@volen-silo
volen-silo requested a review from a team as a code owner November 13, 2026 08:24
@volen-silo
volen-silo requested a review from r0x0r November 13, 2026 08:24

@nowycondro nowycondro left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🤖 Automated review · head 7c4a1cba

This automation never files a GitHub approval, so no approving review will appear here whatever the outcome — the merge decision stays with a human reviewer.

Review — needs work

Full review of the whole change (merge-base f536619a to head 7c4a1cba). Part of ROCMAI-955 (ticket not retrievable from here — no tracker access available to this review); the description's claims were checked against the diff and hold: no claimed behavior is missing, and no unmentioned behavior was found.

Blocking

  • UTF-8-BOM offset is reported relative to the post-strip buffer, not the original file — apps/rocm/src/symptom_input.rs:150-171 (decode, utf8)
    decode() does bytes.drain(..3) to remove a leading UTF-8 BOM and then calls utf8(bytes) on the already-shortened vector. The error path reports error.utf8_error().valid_up_to(), an offset into that shortened slice. For a file that opens with a UTF-8 BOM followed by, say, 10 valid bytes and then an invalid one, the message says "invalid byte at offset 10" while the byte actually sits at file offset 13 — off by exactly the 3-byte BOM length every time a BOM precedes invalid UTF-8. The module's own doc comment states "the error says where decoding failed," so this is the new code contradicting its own documented contract. The existing unit test (input_that_is_not_text_is_refused_with_where_it_failed) only exercises the no-BOM case, so this combination is untested.
    Confidence 82 · logic · Fix: capture the BOM length before draining and add it back when formatting the offset (valid_up_to() + bom_len), or run from_utf8 against a slice that still carries the original indices.

Non-blocking

  • diagnose-59's cmd.exe/PowerShell branches are not exercised by any required PR check — tests/e2e-cucumber/features/diagnose.feature:886, .github/workflows/ci.yml
    The only required Linux-matrixed job runs the #[cfg(not(windows))] bash branch; windows-debug skips the custom e2e harness (test = false), and windows-release only runs an explicit scenario allowlist that doesn't include diagnose-59. The Windows shell forms only run in the scheduled nightly lane and the self-hosted lane, both already-accepted non-required lanes for this pattern elsewhere in the suite (e.g. serve-33/34/35), so this isn't a new deviation introduced by this PR — flagging for visibility only: a cmd.exe/PowerShell quoting regression in this feature would not block a merge.
    Confidence 75 · test-coverage · Fix: none required by existing convention; optionally note in the PR body which lane (nightly/self-hosted) exercises the Windows branch.

Decisions for the author

None

Positive signals

  • The 16 MiB cap is enforced via reader.take(MAX_SYMPTOM_BYTES + 1) before read_to_end, so an infinite/oversized stdin stream is bounded in memory before the size check runs rather than read unboundedly first — verified with a dedicated io::repeat test.
  • diagnose-59 spawns real bash/cmd.exe/powershell.exe interpreters and diagnose-60 drives a genuine pseudo-terminal (portable-pty) rather than faking shell or TTY behavior, so both scenarios would actually catch a real quoting or TTY-detection regression.
  • Docs (README, docs/testing.md, docs/manual-testing.md) state the PowerShell 5.1-vs-7 ASCII-pipe caveat and its Get-Clipboard -Raw > error.txt workaround identically and consistently across all three places, and the documented bash heredoc example correctly quotes its delimiter (<<'EOF') to keep the shell out of the pasted body — consistent with the PR's own premise.

Deployment notes

None — purely additive, opt-in flag; no migration or breaking change.

What this covered

Every file in the diff, read completely at the PR head, plus the callers/surrounding code needed to judge them (diagnose_cmd.rs's consumption of the resolved symptom, cli.rs's existing conflicts_with idioms, tests/e2e-cucumber/tests/e2e.rs wiring, sibling step files for convention comparison, and AGENTS.md in full), across four independent passes: core implementation (symptom_input.rs, cli.rs, main.rs, advised_commands.rs), the test suite (diagnose.feature, e2e.rs, symptom_file_steps.rs), the documentation set (README, architecture.md, manual-testing.md, testing.md, wsl.md), and the source-reading passes (AGENTS.md adherence, history/blame, prior changes, code comments). All four passes completed without needing a re-spawn. CI was read via the GitHub API rather than re-derived: all required checks report success as of head 7c4a1cba (two non-required jobs show skipped — a hardware-gated Strix Halo lane and a skill-scope check — neither blocks this PR).

Did not run: ticket retrieval (ROCMAI-955 — no tracker tool available here). Not reconciled against any existing PR discussion or review threads.


Not a human review. This is an automated code review; please verify findings independently before acting on them.

@juhovainio juhovainio left a comment

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM. --symptom-file matches the stdin/file bullet of ROCMAI-955, the new scenarios (diagnose-59/60/61) are tagged, and README, --help, docs/testing.md, docs/manual-testing.md, docs/wsl.md and docs/architecture.md are all in sync. CI is green apart from the pending MI300X lane.

Non-blocking, take or leave:

  • symptom_input::resolve runs before --model/--distro/--report are considered. If those modes ignore the symptom, --symptom-file - on a terminal still prints the paste hint and blocks on stdin. Worth confirming.
  • A file literally named - needs ./-; one sentence in the README/--help would cover it.
  • diagnose-59 never asserts that shell-ran-the-paste is absent, so "nothing ran" holds only by construction (inline comment).
  • <<< here-strings fall into the new << branch in advised_commands.rs; harmless but untested.
  • The docs/wsl.md edit leaves a line much longer than its neighbours.

/// `KNOWN_SYMPTOM` in `diagnose_steps.rs`), so the diagnosis it gets is a real
/// one. ASCII only, because Windows PowerShell 5.1's pipe to a native command
/// encodes text as ASCII and would turn any other character into `?`.
const HOSTILE_PASTE: &str = "-v \"HSA_STATUS_ERROR_INVALID_ISA\" isn't it? \

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

HOSTILE_PASTE writes shell-ran-the-paste if any shell ever evaluates it, but no step checks the file is absent, so the scenario passes by construction. Consider asserting !paste_dir(world).join("shell-ran-the-paste").exists() in piped_matches_argument.

let Some(path) = symptom_file else {
return Ok(symptom);
};
if path.as_os_str() == STDIN_PATH {

Copy link
Copy Markdown
Collaborator

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

A file literally named - can't be selected (needs ./-); worth one sentence in the --help/README text. Also worth confirming the stdin read (and the terminal hint) shouldn't happen when --model/--distro/--report make the symptom irrelevant.

@volen-silo
volen-silo added this pull request to the merge queue Nov 13, 2026
Merged via the queue into main with commit 4221d66 Nov 13, 2026
56 of 57 checks passed
@volen-silo
volen-silo deleted the rocmai-955-symptom-file branch November 13, 2026 10:16
r0x0r added a commit that referenced this pull request Nov 16, 2026
Both sides appended three scenarios to diagnose.feature and both numbered
them 59/60/61. main's --symptom-file scenarios (#1048) keep 59/60/61 since
they are already merged and referenced elsewhere; this branch's APU memory
scenarios become 62/63/64 in the same relative order, as
tests/feature_naming.rs requires a scenario's number to equal its position
in the file.

The @id: tags are unchanged on both sets -- expectations.toml and the step
bindings key on those, not on the numbers.

References to this branch's renumbered scenarios updated in docs/testing.md
(the ROCMAI-912 section) and in a comment in e2e/diagnose_steps.rs. The
references to main's 59/60/61 in symptom_file_steps.rs, e2e.rs,
docs/architecture.md and the docs/testing.md --symptom-file section are
left alone.

Signed-off-by: Roman Sirokov <roman.sirokov@amd.com>
r0x0r pushed a commit to r0x0r/rocm-cli that referenced this pull request Nov 16, 2026
…OCm#1094)

* fix(diagnose): count a bad byte's offset from the start of --symptom-file input

--symptom-file names the offset of the first byte that is not valid UTF-8.
After dropping a UTF-8 byte-order mark the offset was counted in what was
left, so a file that began with a BOM and then held bad UTF-8 named an
offset three bytes too small, against the module's own promise that the
error says where decoding failed. The offset now counts from the start of
the input, and a test pins it behind a BOM.

Also from the review of the original change: say that a file named `-` is
passed as `./-`, pin how the advised-command scanner treats `<<<`
here-strings, re-wrap an overlong line in docs/wsl.md, and correct the
note in docs/testing.md about which CI lanes run the Windows shell forms
of diagnose-59: the self-hosted Strix Halo Windows lanes, per pull request
and nightly, neither of them required.

Follow-up to ROCm#1048. Part of ROCMAI-955.

Signed-off-by: Eugene Volen <eugene.volen@amd.com>

* test(diagnose): pin that a file named `-` is read as a file, and complete a CI note

The documentation now tells users that a file literally named `-` is
passed as `./-`, because `-` alone means standard input. Nothing tested
that claim. A unit test now checks that the two spellings are different
paths and that a file named `-` is opened as a file.

Also complete the note in docs/testing.md about where the Windows shell
forms of diagnose-59 run: the self-hosted Strix Halo Windows lane runs on
pull requests behind its path filter, on pushes to main and release
branches, and in the merge queue, in addition to the scheduled nightly
lane. Neither is a required check.

Follow-up to ROCm#1048. Part of ROCMAI-955.

Signed-off-by: Eugene Volen <eugene.volen@amd.com>

---------

Signed-off-by: Eugene Volen <eugene.volen@amd.com>
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

3 participants