Repository navigation
refactor(rocm-core): one kernel-release read for the summary and the examination stacks - #990
Conversation
…re merged The summary stack's detect_kernel_version and the examination stack's probe_os both read `uname -r`, and are about to become one. Pin what each returns for the same fake uname first, so the change that merges them shows exactly which answers it moves. They agree on a working uname, on WSL 1 and WSL 2 style releases printed as they are, on a silent uname (nothing in both, no probe_failures entry) and on one that never answers. They differ on three inputs: a uname that prints a release and exits non-zero (the summary reads None, the examination keeps the release), output that is not UTF-8 (the summary reads None, the examination keeps it with the bad byte replaced), and a uname that answers after 3 s, past the summary's 1.5 s and within the examination's 5 s. A separate test pins what probe_wsl makes of each release string, including the empty string a failed read leaves, since kernel_release feeds is_wsl1_kernel. Each case plants a fake uname first on PATH and asks both in a child copy of the test binary, because the lookup of uname follows the process's own PATH, which a test thread cannot change without disturbing every other test. detect_kernel_version becomes crate-visible so a test next to probe_os can call it. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…examination stacks The summary stack's detect_kernel_version and the examination stack's probe_os both ran `uname -r` and could disagree: on a native Linux or WSL host where uname was slow or misbehaved, `kernel:` could read <unknown> while `kernel_release` was filled in, or the reverse. `kernel_release` also feeds the WSL version check and the kernel-dependent diagnoses, so its empty-versus-populated behaviour is not cosmetic. detect_kernel_version survives and probe_os now calls it for kernel_release, with a failed read left empty as before. `uname -v` stays in probe_os, and Windows is untouched: the examination still leaves kernel_release empty there, and the summary still reads `cmd /C ver`. The open questions are decided as follows. Timeout: 5 s, the longer of the two old limits, for the one read; uname is a few bytes from the kernel, so a read that takes seconds is a stalled host, where a spurious unknown costs more than waiting. Failure: None in the summary and an empty kernel_release in the examination, with no probe_failures entry, so a host without a usable uname is not reported as degraded. Non-zero exit with output: dropped by both, since a uname that fails is not a trustworthy release. Decoding: strict UTF-8 for both, since a release with replacement characters in it would reach the diagnoses and the WSL check as if it were one. Moves relative to the two old copies: the examination no longer keeps stdout of a uname that exits non-zero, no longer keeps non-UTF-8 output (lossily), and now waits 5 s where it waited 5 s; the summary now waits 5 s where it waited 1.5 s. The characterisation tests of the previous commit flip those assertions and nothing else: the two copies now agree on every input, and a new check that no case leaves a probe_failures entry about the kernel pins the failure decision. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…e run rocm examine --json reads the kernel release in the host summary (summary.kernel, shown as kernel: in the text) and in the examination (kernel_release), which now share one uname -r read. examine-39 plants a stand-in uname first on PATH and asserts both report the same specific release, on any Linux lane, native or WSL. examine-40 plants one that prints a release and then fails and asserts neither reports a kernel and neither records a failure about it, so a host without a usable uname does not read as degraded. Against the converged code, making probe_os read uname itself again turns examine-40 red, and an examination that reports another release than the summary turns examine-39 red. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The kernel release is the second pair of the note to converge. Record what survived, the four decisions (a single 5 s limit, a failed read left empty with no probe_failures entry, a non-zero exit dropped by both, strict UTF-8 for both), the answers that moved with the test or scenario that pins each, and that Windows is out of the change. The analysis of the two old copies stays as the record of what changed; the timeout question leaves the open list for the kernel and stays for the CPU read. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
There was a problem hiding this comment.
🟡 Changes recommended
The JSON handler still performs two independent kernel-release reads that can disagree or double the wait, and the timeout test can pass even when timeout enforcement is broken.
2 open issues
What changed in this PR
Consolidates Linux kernel-release probing in rocm-core so the host summary and examination use the same reader and handling rules. Windows behavior remains unchanged.
Changes:
- Routes examination kernel detection through
detect_kernel_version, with a 5-second timeout and strict output validation. - Adds unit tests and Linux scenarios covering release values, failed reads, and WSL version interpretation.
- Records the convergence decisions and behavior changes in the architecture and host-probing documentation.
| File | Description |
|---|---|
tests/e2e-cucumber/tests/e2e/examine_steps.rs |
Adds stand-in uname setup and report assertions. |
tests/e2e-cucumber/features/examine.feature |
Adds Linux success and failed-read scenarios. |
docs/host-probing.md |
Records kernel-reader convergence and behavior decisions. |
docs/architecture.md |
Updates the probing module descriptions. |
crates/rocm-core/src/host_gpu/os_facts.rs |
Exposes the shared reader and sets its Linux timeout. |
crates/rocm-core/src/host_gpu.rs |
Re-exports the reader within the crate. |
crates/rocm-core/src/examine/wsl.rs |
Tests WSL version interpretation of kernel releases. |
crates/rocm-core/src/examine/host_env.rs |
Uses the shared reader and adds kernel-read tests. |
Review effort: Balanced
| // The summary's read, so `kernel:` and `kernel_release` come from one | ||
| // `uname -r`. A failed read is empty here, with no `probe_failures` | ||
| // entry, as before: a host without a usable `uname` is not a degraded one. | ||
| e.kernel_release = crate::host_gpu::detect_kernel_version().unwrap_or_default(); |
There was a problem hiding this comment.
You are right: the --json handler built the examination and then the summary, each starting its own uname -r, so a transient failure could split the two fields and a hung uname cost two timeouts. I took the preferred fix in d128fc1: ExamineSummary::gather_after takes the examination's kernel_release, a failed read included, on Linux instead of running uname -r again, and rocm examine --json uses it. Callers that gather only the summary (the text form, the MCP and bridge snapshots) still read once for themselves, and off Linux the summary reads for itself, because the examination does not read the kernel on Windows. It is tested by counting reads: the_summary_reads_the_kernel_only_when_the_examination_did_not counts the read function per case (none when the examination has a value, none for an empty one, one otherwise), and scenario examine-39 now logs the calls of its stand-in uname and expects exactly one -r, which fails with two when the handler is put back on gather (I ran that mutation through the real harness). The note and the architecture entry say one read per run where that holds, and "one reader" for the rest.
Security scan found no critical or high findings on lines changed by this pull requestView 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. |
…moved The stand-in for a uname that never answers exits successfully with nothing after 30 s, which is also what a read with no timeout turns into None and an empty string, so the test stayed green with the timeout removed. It now checks the elapsed time: the child reads twice in a row, each bounded by the 5 s limit, so it takes about 10 s, at least 9 s shows the stand-in really hung, and under 25 s shows the reads did not outlive the limit. With the limit raised to 60 s it takes about a minute and the upper bound fails. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…json rocm examine --json built the examination, which ran uname -r through probe_os, and then the summary, which ran it again, so the two fields could disagree on a transient failure and a hung uname cost two timeouts. ExamineSummary::gather_after takes the examination's kernel_release on Linux, a failed read included, and the JSON handler uses it. Other callers that gather only the summary are unchanged and read once for themselves; off Linux the summary still reads for itself. summary_kernel makes the choice and is tested with a counted read: the examination's value is used without a read, an empty one is a failed read, and with no examination or off Linux the read happens once. Scenario examine-39 now also counts the calls of its stand-in uname and expects exactly one -r; with the handler back on gather it fails with two. The host-probing note and the architecture entry say one read per run instead of one reader. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
There was a problem hiding this comment.
Note
Copilot was unable to run its full agentic suite in this review.
Copilot review overview
6 open issues
These tests are described as “Linux only”, but they’re gated with#[cfg(unix)]. On non-Linux Unix… · New This comment block no longer matches the implementation:probe_osnow calls… · NewKERNEL_RELEASE_TIMEOUTis documented as “the longer … (1.5 s and 5 s)” and later text asserts… · New The generated shell script embedslog.display()inside single quotes. If the isolated-root path… · New Fail the timeout test when reads exceed the expected duration Reuse one uname result to keep inspection fields consistent
Review effort: Lite
| rocm_core::fake_executable::write_fake_executable( | ||
| &bin.join("uname"), | ||
| format!( | ||
| "#!/bin/sh\necho \"$*\" >> '{}'\nif [ \"$1\" = -v ]; then echo '#1 SMP stand-in'; exit 0; fi\n{release_body}\n", | ||
| log.display() |
There was a problem hiding this comment.
Agreed, a single quote in the isolated-root path would break the script. Fixed in 8d725dc: the script text comes from stand_in_uname_script in the harness library, which quotes the log path with a single-quote escape (a fix-up in the commit after it, because rocm-core is only a dev-dependency of that library). Two unit tests plant it in a directory whose name holds a single quote and a space and check what it prints and logs; putting the bare single quotes back turns both red. I ran examine-39 and examine-40 through the real harness again after the change.
…they pin now The kernel_pair tests were described as Linux only but gated with cfg(unix); on another Unix, probe_os does not take its Linux branch, so the expectations would fail there. Gate them on target_os = "linux", which is what the description says and the only Unix platform supported. The comment above them still described two readers with different limits; probe_os now calls detect_kernel_version, so it says what the tests pin through both entry points instead. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…onds KERNEL_RELEASE_TIMEOUT was set to the SHORT constant of probe_exec, which is 5 s today, so the 5 s the decision records depended on another module's constant staying put. Write it as Duration::from_secs(5) and pin it with the_kernel_release_timeout_is_five_seconds; the doc comment and the host-probing note say so. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The stand-in uname put the log path between bare single quotes, so an isolated-root path containing a single quote would have produced an invalid script or written elsewhere. The script text now comes from stand_in_uname_script in the harness library, which quotes the path with the shared posix_shell_quote. Unit tests plant it in a directory whose name holds a single quote and a space and check what it prints and logs; putting the bare quotes back turns them red. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Signed-off-by: Jussi Elo <jussi.elo@amd.com>
stand_in_uname_script called rocm_core::quoting, but rocm-core is only a dev-dependency of the harness library, so the library itself did not build outside its unit tests. Quote the log path with a local single-quote escape, tested through a real shell with a path holding a single quote. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
There was a problem hiding this comment.
🟢 Approval recommended
No active review issues remain for the change consolidating Linux and WSL kernel-release probing.
2 open issues
4 resolved since last review
These tests are described as “Linux only”, but they’re gated with#[cfg(unix)]. On non-Linux Unix…KERNEL_RELEASE_TIMEOUTis documented as “the longer … (1.5 s and 5 s)” and later text asserts… This comment block no longer matches the implementation:probe_osnow calls… Fail the timeout test when reads exceed the expected duration
Review effort: Balanced
nowycondro
left a comment
There was a problem hiding this comment.
🤖 Automated review · review-code · head 1c3e4c2c
Review — no blocking findings
Full review of the whole change (diff 227968dcb30...1c3e4c2c870c, 11 commits, 11 files). Closes ROCMAI-923 (ticket retrieved and checked): this is host-probing pair 2 of 6 (kernel-release consolidation), and the change's scope matches the ticket's "what to do" and acceptance criteria exactly — Linux-only convergence of detect_kernel_version/probe_os, Windows explicitly and correctly left untouched.
Blocking
None
Non-blocking
- The PR's stated cost of the 1.5s→5s timeout bump is narrower than the actual reach —
crates/rocm-core/src/host_gpu/os_facts.rs(KERNEL_RELEASE_TIMEOUT), PR description's "Decisions" section.
KERNEL_RELEASE_TIMEOUTlives insidedetect_kernel_version()itself, so the bump from 1.5s to 5s applies to every caller ofExamineSummary::gather()/gather_without_driver_facts()on a hungunamehost, not only the path the description calls out ("the text ofrocm examinecan wait up to 5s instead of 1.5s"). That includesapps/rocm/src/bridge_snapshot.rs,apps/rocm/src/chat/mcp_bridge.rs,apps/rocm/src/freeform_answer.rs,apps/rocm/src/driver_install.rs,apps/rocm/src/runtime_install_finalize.rs, andapps/rocmd'shost_snapshot.rs/mcp.rs/sandbox.rs— all of which still do their own independentuname -rread (correctly, per the design note), but now under the longer limit too. None of these sit on a hot path invoked on every CLI call (each is reached only from an examine-like or diagnostic action), so this isn't a functional defect, just a blast-radius statement that's a bit narrower than the code. Confidence 75 · architectural · Fix: one more clause in the PR description noting the timeout change applies to every summary-gathering caller, not just the text form ofrocm examine.
Decisions for the author
None
Positive signals
- Characterisation-tests-first discipline is followed and verifiable, not just claimed: the
kernel_pairunit tests incrates/rocm-core/src/examine/host_env.rspin both old copies' answers before the convergence commit flips only the assertions meant to change, and the e2e scenarioexamine-39counts the stand-inuname's actual invocations (rather than only comparing output values) to prove the single-read claim — a mutation that revertedgather_aftertogatherwould be caught by call count even though both reads would return the identical fake string. summary_kernel's branching (examined value reused only whenSome, non-empty, and Linux; falls through to a fresh read otherwise) is exactly right against theExaminationdefault andruntime_is_linux()semantics — traced by two independent passes with no reachable case where an off-Linux empty default gets misread as a Linux failed-read.
Deployment notes
The PR's mergeable_state is currently blocked; live CI shows two failing checks, "Security scan / gitleaks" and its "Security scan / Security scanners" aggregator. The gitleaks finding is pre-existing noise unrelated to this PR: it flags secrets-shaped strings in commit 88e6cc52667c9f89af39b2d67d393a3c9e4f50cc (test fixtures in apps/rocm/src/runtime_install_finalize.rs / serve_summary.rs from an older, unrelated PR, #867), a commit that predates and is not part of this PR's own 11-commit range. It's worth a maintainer re-running or allowlisting rather than something this PR needs to fix, but it is presently blocking merge via the required-check gate.
What this covered
Full review, fanned out to four independent passes: (1) core Rust logic (host_gpu.rs, host_gpu/os_facts.rs, examine/host_env.rs, examine/wsl.rs, apps/rocm/src/examine_cmd.rs, plus capture.rs/probe_exec.rs/examine.rs for context), (2) the e2e/test harness (stand_in_uname.rs, examine_steps.rs, examine.feature, lib.rs), (3) design review and impact analysis (completeness of the "one read" claim across every gather/gather_after call site, docs accuracy, blast radius, summary_kernel edge cases), (4) agent-instruction adherence (AGENTS.md/CONTRIBUTING.md/commit conventions/DCO/crate-edge policy) and history (prior TODOs, prior attempts, commit ordering against the host-probing.md plan). No embedded instructions directed at an AI reviewer were found anywhere in the PR's commits, code, or docs. All four passes ran to completion; not degraded. Read live CI via the GitHub API (not workflow definitions) — see Deployment notes for the one failing, pre-existing, unrelated check. Not reconciled against the PR's review-thread discussion (the existing Copilot bot comments and the author's own replies) — this review was reached independently of that thread, per method.
Not a human review. This is an automated code review; please verify findings independently before acting on them.
juhovainio
left a comment
There was a problem hiding this comment.
I went through the whole diff. I found nothing that breaks the change, only a few small things worth tightening before merge, so these are non-blocking.
Worth a look
ExamineSummary::gather_afterispubbut treats whateverExaminationit is handed as this host's kernel. Its only caller today isexamine_cmd.rs, so nothing is wrong now, butpub(crate)(or a doc line saying the examination must come from the local host) would keep it from being misused later.- The 3 s
unameanswer test leaves only 2 s of margin to the 5 s limit, so it could flake on a heavily loaded runner. Together with the hung-unametest, the kernel-pair tests add roughly 13 s of wall time to the rocm-core suite. single_quotedduplicatesrocm_core::quoting. The comment justifying it (rocm-core is only a dev-dependency there) is fine, just noting it.
Behaviour changes, to confirm they are deliberate: the 5 s timeout now also applies to the text form of rocm examine (was 1.5 s), a failed read leaves no probe_failures entry, and Windows is untouched. All three are disclosed in the PR body and docs.
CI: everything is green except the two security scan jobs (gitleaks and the scanners). The bot's three generic-api-key hits are in runtime_install_finalize.rs and serve_summary.rs, which this diff does not touch, so this looks like a pre-existing main issue that needs an allowlist or fix separately. It will still block merge until resolved.
The scenarios (examine-39/examine-40), the call-count and timing assertions, and the docs updates all look right.
| /// transient failure, and a hung `uname` costs one timeout rather than two. | ||
| /// Everywhere else (the examination does not read the kernel on Windows) the | ||
| /// summary reads it itself, as [`gather`](Self::gather) does. | ||
| pub fn gather_after(examination: &crate::Examination) -> Result<Self> { |
There was a problem hiding this comment.
gather_after is pub and takes whatever Examination it is given as this host's kernel (e.g. one deserialized, or probed for another host). Only examine_cmd.rs calls it, so no live bug, but consider pub(crate) or a doc line saying the examination must come from the local host. Non-blocking.
There was a problem hiding this comment.
Agreed on the risk. pub(crate) will not compile here: the only caller of gather_after is rocm examine --json in apps/rocm/src/examine_cmd.rs, which is a different crate, so it stays pub. 8b58e7d adds the doc line you suggested: the examination must come from probing this host, because its kernel release is reported as this host's, and it is not for one deserialised from a report or probed for another machine.
There was a problem hiding this comment.
Taken in order. The gather_after visibility and doc line and the 2 s answer test are fixed as in the two inline replies (8b58e7d and d0367b6). single_quoted duplicating rocm_core::quoting is deliberate, as you note: rocm-core is only a dev-dependency of that library, and the comment says so, so no change. On the behaviour changes: the 5 s limit is not only on the text form of rocm examine. It sits inside detect_kernel_version, so it reaches every caller of ExamineSummary::gather and gather_without_driver_facts that reads the kernel itself: the text of rocm examine, the bridge and MCP snapshots, the free-form answer, rocm install driver, the runtime-install finalizer, and rocmd's host snapshot, MCP and sandbox paths (I grepped every call site). None is on a path run for every command, and the note and the PR body now say so. The gitleaks failures are in files this PR does not touch, so I have left them for a separate allowlist or fix.
| /// the longer of the two old ones, 5 s. The summary used to give up at | ||
| /// 1.5 s. | ||
| #[test] | ||
| fn an_answer_after_three_seconds_is_read_by_both() { |
There was a problem hiding this comment.
A 3 s sleep against a 5 s limit leaves only 2 s of margin; a heavily loaded runner could flake this. Consider a shorter answer delay that still exceeds the old 1.5 s limit (e.g. 2 s), or a wider limit-to-answer gap. Non-blocking.
There was a problem hiding this comment.
Done in d0367b6: the test is now an_answer_after_two_seconds_is_read_by_both, with a 2 s delay. That is still past the summary's old 1.5 s limit, so it still shows the one limit applies to both, and it leaves 3 s of margin to the 5 s limit. Lowering the limit to 1 s turns it red (along with the hung-uname test and the limit pin). The suite wall time of cargo test -p rocm-core kernel is about 12 s on this loaded machine for 22 tests (about 10 s when it is quiet); nearly all of it is the hung-uname test, whose two sequential 5 s reads are what its elapsed-time bound needs, so I left that one as it is.
A 3 s answer against the 5 s limit left only 2 s of margin on a loaded runner. 2 s is still past the old 1.5 s limit of the summary, so the test still shows the one limit applies to both, and leaves 3 s of margin. Lowering the limit to 1 s turns it red. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…st, and who the 5 s limit reaches gather_after treats the kernel release of the examination it is given as this host's, so its doc comment now says the examination must come from probing this host. It stays pub because its only caller, rocm examine --json, is in another crate, where pub(crate) would not compile. The timeout moved from 1.5 s to 5 s inside detect_kernel_version, so it reaches every caller of ExamineSummary::gather and gather_without_driver_facts that reads the kernel itself, not only the text of rocm examine. The note says so, and the 3 s row of its table of moved answers is now 2 s. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
r0x0r
left a comment
There was a problem hiding this comment.
Approving this.
The thing a consolidation like this lives or dies on is whether the single read can really stand in for both, and here that is settled mechanically rather than by argument, which is what makes it easy to sign off on.
probe_os is the first probe in Examination::probe_with_interpreter (examine.rs:547), ahead of the WSL early return, so kernel_release is always populated on Linux by the time gather_after reads it. runtime_is_linux() is a const fn, so the summary and the examination cannot end up disagreeing about which platform they think they are on. And grep '"uname"' turns up exactly two production call sites, -v and -r - there is no third reader hiding anywhere. Every answer that moved is pinned by a kernel_pair test and by scenario examine-39, which counts the stand-in's -r calls, so a silent re-read would regress loudly rather than quietly. summary_kernel injects both the bool and the reader, so the Windows branch is covered even from a Linux host.
Three nits inline, none of them blocking. One of them you have in fact already fixed - I read this at 1c3e4c2c and the branch has since moved on to 8b58e7d0, so I re-anchored everything against the current head and am leaving that one only so the record is complete.
On CI: the two checks that were red when I started (gitleaks and the security scanners) were pre-existing generic-api-key false positives in serve_summary.rs and runtime_install_finalize.rs, neither of which this PR touches - #1000 is the attempt to remediate them. They are green on the current head; the rest of the suite is still running.
|
|
||
| The four open questions are decided as follows. | ||
|
|
||
| - Timeout: 5 s, the longer of the two old limits (`KERNEL_RELEASE_TIMEOUT`, written out as five seconds rather than borrowed from `SHORT`, which is also 5 s today, and pinned by `the_kernel_release_timeout_is_five_seconds`). `uname -r` is a few bytes the kernel hands over, so a read that takes seconds is a stalled host, where waiting costs little and a spurious "unknown" costs more: `kernel_release` feeds the WSL version check and the kernel-dependent diagnoses, which read an empty value as nothing to report. The cost is that every caller of `ExamineSummary::gather` and `gather_without_driver_facts` that reads the kernel for itself (the text of `rocm examine`, the MCP and bridge snapshots, the free-form answer, `rocm install driver`, the runtime-install finalizer, and `rocmd`'s host snapshot, MCP and sandbox paths) can wait up to 5 s instead of 1.5 s on a host whose `uname` hangs; none of them is on a path run for every command. `rocm examine --json` waits for one timeout, because it hands the examination's read to the summary. |
There was a problem hiding this comment.
Flagging this one only for the record - it was my note against 1c3e4c2c, and 8b58e7d0 has already fixed exactly it. No action needed.
What I had: this bullet understated who pays the 1.5 s -> 5 s change. It said the cost was that "the text of rocm examine can wait up to 5 s", but detect_kernel_version (crates/rocm-core/src/host_gpu/os_facts.rs:13-27, the KERNEL_RELEASE_TIMEOUT block in this same diff) sits on every ExamineSummary::gather() path, not just the text form: apps/rocmd/src/host_snapshot.rs:37, apps/rocmd/src/mcp.rs:567, apps/rocmd/src/sandbox.rs:194, apps/rocm/src/chat/mcp_bridge.rs:160, apps/rocm/src/bridge_snapshot.rs:38, apps/rocm/src/driver_install.rs:63,108,171, apps/rocm/src/freeform_answer.rs:61, apps/rocm/src/runtime_install_finalize.rs:546.
The sentence as it now reads names them, which is what I was going to ask for. For whatever it is worth, I also checked that this is not a tick source - watchers.rs:72 takes the GPU snapshot only, so nothing on a repeating timer inherits the longer wait.
There was a problem hiding this comment.
Thanks, no change.
| // question should not change it, and `--json` is the form tooling calls | ||
| // in a loop. | ||
| let host = ExamineSummary::gather()?; | ||
| // `gather_after`, so the kernel release is read once for both documents. |
There was a problem hiding this comment.
Stale comment. The "gather rather than examine_human_report" reasoning above now sits in front of a gather_after call, and the line added here reads as a dangling fragment - it has no subject, so it parses as a continuation of the in a loop. sentence rather than as its own point.
Worth folding the two together, e.g. naming gather_after in the first sentence and saying why it takes the examination, rather than appending to a comment that is about something else.
There was a problem hiding this comment.
Agreed. Rewritten as one comment that names the new entry point Examination::probe_with_summary (see the next replies): it keeps the reason for not using examine_human_report (its recovery step writes, and --json is called in a loop) and says the summary is gathered from the examination it probes, so the kernel release is read once for both documents and the two fields cannot disagree.
| /// reported as this host's. Not for one deserialised from a report or probed | ||
| /// for another machine. It stays `pub` because its caller, `rocm examine | ||
| /// --json`, is in another crate. | ||
| pub fn gather_after(examination: &crate::Examination) -> Result<Self> { |
There was a problem hiding this comment.
A note on the shape of this API rather than a live bug - no caller does this today.
gather_after is pub and accepts any &Examination, so the pairing it depends on is trusted rather than enforced. The doc comment just above now states the requirement in prose ("must come from probing this host... Not for one deserialised from a report or probed for another machine"), which helps, but the signature still cannot tell a locally probed examination from any other. apps/rocm/src/remote/doctor.rs:51 (parse_examination) already deserialises a remote host's Examination from JSON, so the value that would silently put a remote kernel release into the local summary is one that already exists in this binary.
Nothing to change for this PR; just worth knowing that the only thing standing between those two is that nobody has wired them together yet.
There was a problem hiding this comment.
You are right, and parse_examination in remote/doctor.rs made the wrong pairing one wiring away, so I enforced it by construction instead of documenting it. Examination::probe_with_summary in rocm-core probes this host and gathers the summary from that examination itself, returning both, and gather_after is now pub(crate), so no outside caller can hand it an arbitrary examination. rocm examine --json calls the entry point. Behaviour is unchanged: examine-39 still counts exactly one -r and examine-40 is unchanged.
juhovainio
left a comment
There was a problem hiding this comment.
Looks good. The single kernel-release read per --json run is pinned by the scenario counting the stand-in's -r calls, and the closure-taking summary_kernel makes the "no second read" claim unit-testable. Scope matches ROCMAI-923, and the docs and scenarios are in place.
Nothing blocking. A few small notes, left inline:
- The
probe_failuresassertions in the unit test and the scenario helper filter on "uname"/"kernel" wording, so a differently worded future failure entry would slip through; asserting the list is empty is sturdier. gather_afteris a newpubAPI that relies on a documented precondition (the examination must come from this host).- The never-answering
unametest takes about 10 s of serial wall time; fine, just worth knowing.
This is based on reading the diff and the live CI status (completed checks green, E2E and a few others were still running when I looked), not on running it locally.
| // in a loop. | ||
| let host = ExamineSummary::gather()?; | ||
| // `gather_after`, so the kernel release is read once for both documents. | ||
| let host = ExamineSummary::gather_after(&examination)?; |
There was a problem hiding this comment.
gather_after trusts examination.kernel_release (empty means a failed read). That holds here since probe_os always runs on this host; worth keeping in mind if another examination source ever feeds it.
There was a problem hiding this comment.
Same fix: the call is now Examination::probe_with_summary, which does the pairing inside rocm-core, so the caller no longer passes an examination and there is no precondition left to document.
| /// for another machine. It stays `pub` because its caller, `rocm examine | ||
| /// --json`, is in another crate. | ||
| pub fn gather_after(examination: &crate::Examination) -> Result<Self> { | ||
| Self::gather_scoped(true, Some(&examination.kernel_release)) |
There was a problem hiding this comment.
New pub API whose correctness rests on a documented precondition (the examination was probed on this host). Not blocking, but a typed handoff or narrower visibility would enforce it rather than rely on the doc comment.
There was a problem hiding this comment.
Same fix: gather_after is crate-private and only probe_with_summary calls it, with the examination it has just probed on this host. one_inspection_reads_the_kernel_release_once counts the reads of a fake uname through the entry point, for a working and a failing uname, and goes red when the summary is routed back through a second read.
| "failures_about_uname": e | ||
| .probe_failures | ||
| .iter() | ||
| .filter(|failure| failure.contains("uname") || failure.contains("kernel")) |
There was a problem hiding this comment.
This filter only counts entries containing "uname"/"kernel", so a future probe_failures entry worded differently would pass. Asserting the list is empty would be sturdier.
There was a problem hiding this comment.
Agreed. The child now reports the whole probe_failures list and the test asserts it is empty in every case, so a failure worded any way fails it. The fake host's os-release reads cleanly, so an empty list is right here rather than a baseline. I checked it by mutation: recording a failure with unrelated wording on a failed read turns the kernel-pair tests red.
There was a problem hiding this comment.
Thanks to both for the approvals. This round: the probe_failures assertions are wording-independent (c9c8258), and the gather_after pairing is enforced by construction through Examination::probe_with_summary with gather_after crate-private, with the examine_cmd.rs comment rewritten alongside it (4877662). The never-answering uname test takes about 10 s because it makes two sequential reads, each bounded by the 5 s limit, which is what its elapsed-time bound measures; that is by design and I have left it.
| .unwrap_or_else(|| panic!("`examine --json` has no probe_failures array:\n{json:#}")) | ||
| .iter() | ||
| .filter_map(serde_json::Value::as_str) | ||
| .filter(|failure| failure.contains("uname") || failure.contains("kernel release")) |
There was a problem hiding this comment.
Same keyword filter as the unit test: asserting probe_failures has no new entry, rather than matching "uname"/"kernel release" wording, would not depend on how a future failure is phrased.
There was a problem hiding this comment.
Agreed. Scenario examine-40 no longer filters by wording: it runs rocm examine --json once more on the same machine with a working uname as a baseline and asserts the failing run has no probe_failures entry beyond it, so entries a machine has for other reasons do not matter and a new one, however worded, does. The same mutation (a failure with unrelated wording) turns examine-40 red through the real harness; the fix is c9c8258.
nowycondro
left a comment
There was a problem hiding this comment.
🤖 Automated review · review-code · head 8b58e7d09a
Review — no blocking findings
Full review of the whole change (diff 227968dcb30...8b58e7d09ad9, 13 commits, 11 files). Closes ROCMAI-923 (ticket retrieved and checked): this is host-probing pair 2 of 6 (kernel-release consolidation); the change's scope, commit order, and the disclosed behavior decisions match the ticket's "what to do" and acceptance criteria.
Blocking
None
Non-blocking
- Several callers pay the widened kernel-release timeout more than once per single invocation, beyond what the blast-radius disclosure covers —
apps/rocm/src/driver_install.rs:63and:108(install_driver's pre-installExamineSummary::gather()andexecute_driver_install_plan's post-installExamineSummary::gather(), each paying the read even though only.driveris ever used),apps/rocm/src/chat/mcp_bridge.rs:160-161(the"examine"/"doctor"MCP/chat tool callsExamineSummary::gather()directly and thenrender_examine_text(), which independently callsgather()again viaexamine_human_report), andapps/rocmd/src/mcp.rs:567-568(the"examine"tool callsgather()in-process and then shells out torun_rocm_capture(&["examine"]), which re-probes a third time in the child process). All three files are untouched by this PR (confirmed viagit diffagainst base — identical in both), so the double/triple read itself is pre-existing, butKERNEL_RELEASE_TIMEOUTmoving from 1.5 s to 5 s insidedetect_kernel_versionenlarges its blast radius here specifically: each of these single user actions can now wait up to 10 s (or ~15 s for therocmdsubprocess case) on a hunguname, not the "up to 5 s" a plain reading of the docs' per-caller list implies.docs/host-probing.md's "Decided and delivered" section (updated in the latest commit) enumerates every affected caller but doesn't flag that some of them read the kernel release more than once per invocation. Confidence 85 (traced each call site directly;mcp_bridge.rs's androcmd/mcp.rs's double-read were not in the PR's own enumerated list of callers at all, though they do go throughgather()). Fix: a one-line addition to the doc noting these three paths pay the timeout multiple times, and/or (longer term) givedriver_install.rsa kernel-skipping summary variant since it never reads.kernel. - The "no kernel
probe_failuresentry" checks assert only a substring-filtered subset of the list, not the whole thing —tests/e2e-cucumber/tests/e2e/examine_steps.rs:2601-2609(kernel_read_failuresfilters on.contains("uname") || .contains("kernel release")) andcrates/rocm-core/src/examine/host_env.rs'skernel_pair_child_reports_both_answers(filters on.contains("uname") || .contains("kernel")). A differently-worded future kernel-failure message would silently pass both checks even though it should be absent. Confidence 75 (read both filters directly). Fix: assert the wholeprobe_failureslist is empty (or diff it against a pre-call snapshot) in these two checks instead of filtering by wording.
Decisions for the author
None
Positive signals
- Characterisation-tests-first discipline is followed and verifiable, not just claimed: the
kernel_pairunit tests inhost_env.rspin both old copies' answers before the convergence commit flips only the assertions meant to change, and e2e scenarioexamine-39counts the stand-inuname's actual-rinvocations (not just output values) to prove the single-read claim forrocm examine --json. summary_kernel's four branches (Linux+Some-nonempty, Linux+Some-empty, Linux+None, non-Linux) were traced againstExamination's default andruntime_is_linux()and match the documented matrix exactly, with no reachable case where an off-Linux empty default is misread as a Linux failed read.- The docs were kept honest through to the last commit: an earlier gap in the blast-radius disclosure (the per-caller list) was closed in commit
8b58e7ditself, which is the right instinct even though the multiplicity gap above remains.
Deployment notes
Live CI is fully green at this head (all required checks SUCCESS, mergeStateStatus: CLEAN, mergeable: MERGEABLE) — confirmed via the GitHub API, not inferred. No migration needed. Worth flagging for deployment: KERNEL_RELEASE_TIMEOUT (5 s) now governs every Linux uname -r read crate-wide, so several diagnostic/install commands (see Non-blocking above) have a higher worst-case latency on a host with a hung uname than before this PR.
What this covered
Full review, fanned out to four independent passes: (1) core Rust logic (host_gpu.rs, host_gpu/os_facts.rs, examine/host_env.rs, examine/wsl.rs, examine_cmd.rs, examine.rs, probe_exec.rs, command_capture.rs, host_gpu/capture.rs); (2) impact analysis of every caller of gather/gather_without_driver_facts/gather_after across apps/rocm and apps/rocmd; (3) the e2e/test harness (stand_in_uname.rs, examine_steps.rs, examine.feature, lib.rs) and docs accuracy; (4) agent-instruction adherence (AGENTS.md, CONTRIBUTING.md, commit/DCO/signing conventions, crate-edges policy) and history (git log/git blame on the touched files, confirming this consolidation is a planned continuation of a prior convergence pair rather than a silent reversal of a deliberate design). After consolidating, I independently re-verified several claims against the source directly rather than taking any one pass at face value: confirmed rocm_core::quoting does exist (one pass's claim that it didn't was based on an incomplete file set) and that stand_in_uname.rs's comment about it is accurate; confirmed the probe_failures substring-filter and the driver_install/mcp_bridge/rocmd double-read findings by reading the exact files; confirmed CI status live. No blocking findings survived verification. Not reconciled against this PR's existing review-thread discussion (the bot and human comments already on it) — this review was reached independently of that thread, per method.
Not a human review. This is an automated code review; please verify findings independently before acting on them.
…er its wording The kernel-pair unit test and the examine-40 step filtered probe_failures on the words uname and kernel, so a failure worded differently would have passed. The unit test's child now reports the whole list and the test asserts it is empty. examine-40 runs rocm examine --json once more on the same machine with a working uname as a baseline and asserts the failing run has no entry beyond it. Recording a failure with unrelated wording on a failed read turns the kernel-pair tests and examine-40 red. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…-core gather_after was a pub API whose correctness rested on a prose precondition, that the examination handed to it comes from this host; rocm doctor already deserialises an examination of a remote host in the same binary, so a wrong pairing was one wiring away. Examination::probe_with_summary now probes this host and gathers the summary from that examination itself, returning both, and gather_after is crate-private, so no outside caller can pass an arbitrary examination. rocm examine --json calls the entry point, with a rewritten comment that names it and says why it exists. Behaviour is unchanged: one kernel read per run, the failing-uname case, and the text form. one_inspection_reads_the_kernel_release_once counts the fake uname's calls through the entry point, for a working and a failing uname, and goes red when the summary is routed back through a second read. The note and the architecture entry name the entry point. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
| "#!/bin/sh\nif [ \"$1\" = -v ]; then echo '#1 SMP fake'; exit 0; fi\necho x >> '{}'\n{body}\n", | ||
| calls.display() |
Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Main now ends at examine-42 after the scenarios that took examine-39 to examine-42 merged. Renumber the two kernel-release scenarios to the next free ids, update the host-probing note, and keep their @id names. feature_naming requires sequential ids, so they cannot be numbered ahead of another change that has not merged yet. Signed-off-by: Jussi Elo <jussi.elo@amd.com>
nowycondro
left a comment
There was a problem hiding this comment.
🤖 Automated review · review-code · head 48776625
Review — no blocking findings
Full review of the whole change (diff 227968dcb30e...48776625, 15 commits, 12 files). States "Closes ROCMAI-923" (an internal tracker ticket; not retrieved — no access from this public review, identifier reported only). Documented in docs/host-probing.md as "pair 2 of 6" of an in-progress host-probing convergence series; this change's scope, commit order and disclosed behavior decisions are internally consistent with that stated framing.
Blocking
None
Non-blocking
- A documentation claim this diff itself writes is contradicted by two call sites it did not audit —
docs/host-probing.md("Callers that gather only the summary (the text form, the MCP and bridge snapshots) still read once for themselves"),apps/rocm/src/chat/mcp_bridge.rs:160-161,apps/rocmd/src/mcp.rs:567-568.
Traced directly:mcp_bridge.rs's"examine"/"doctor"internal MCP/chat tool arm callsExamineSummary::gather()once, then callsrender_examine_text()→render_examine_text_with_paths→examine_human_report, which callsExamineSummary::gather()a second time (apps/rocm/src/examine_report_text.rs:130) — two independentuname -rsubprocess reads for one tool invocation.rocmd's"examine"MCP tool similarly callsgather()in-process and then shells out viarun_rocm_capture(&["examine"]), which re-execsrocm examineas a child process that callsgather()again — a second read in a second OS process. Both patterns pre-date this PR (neither file is touched by the diff) and the double-read itself is out of this change's stated scope, butKERNEL_RELEASE_TIMEOUTmoving from 1.5s to 5s inside the now-shareddetect_kernel_version()enlarges the cost of that pre-existing pattern specifically at these two sites: a worst-case hungunamenow costs up to ~10s per invocation at each, not the "once ... for themselves" the doc states. Confidence 85 (full call chain traced in source, not inferred). Fix: a one-line qualifier indocs/host-probing.mdnoting these two paths read the kernel release more than once per invocation, and/or consider giving them a read-once-and-reuse path in a follow-up.
Decisions for the author
- Whether to extend the "one read" guarantee beyond
rocm examine --json— tradeoff. The finding above is a real latency-blast-radius gap, but closing it would mean changingchat/mcp_bridge.rsandrocmd/mcp.rs(and arguablydriver_install.rs's intentional pre/post-install double read), which this pair's stated scope (detect_kernel_version/probe_os/rocm examine --jsononly) deliberately excludes, consistent with how pair 1 (the PATH-lookup convergence) was also scoped narrowly. Leaving it for a later pair or a dedicated follow-up is a reasonable call; the author should confirm that's the intent rather than an oversight.
Positive signals
- The single-read guarantee is verified mechanically, not argued:
examine-39counts literal-rlines in the stand-inuname's call log (assert_uname_was_asked_for_the_release_once), so a regression that silently reintroduced a second read would fail on call count even if both reads returned an identical fake value. summary_kernel's four-way branch (Linux+non-empty, Linux+empty, Linux+None, non-Linux) was independently traced againstExamination's default andruntime_is_linux()(aconst fn) and is exactly right: thelinuxgate — notexamined.is_some()alone — is what prevents an off-Linux empty-by-designkernel_releasefrom being misread as a failed Linux read.ExamineSummary::gather_afterispub(crate), with a doc comment stating its precondition explicitly (theExaminationhanded in must be of this same host) — a prior-round nit about this beingpubwith an undocumented precondition has been fixed in the code at this head, not just in review discussion.- The
probe_failures-emptiness checks (both the Rust unit test and the e2e step helper) were tightened to assert the list is empty / diff against a same-machine working-unamebaseline, rather than filtering by a hardcoded substring like"uname"/"kernel"— verified directly incrates/rocm-core/src/examine/host_env.rs:707andtests/e2e-cucumber/tests/e2e/examine_steps.rs'sprobe_failures_with_a_working_uname, closing a real gap a differently-worded future failure message would otherwise have slipped through. - The stand-in
unamescript's log-path shell quoting (tests/e2e-cucumber/src/stand_in_uname.rs'ssingle_quoted) is the standard POSIX close/escape/reopen algorithm and is exercised against a hostile case (a directory name containing both a single quote and a space) with a real subprocess execution, not just an assertion on the escaped string's shape. - The platform gating on the new kernel-pair tests is
#[cfg(target_os = "linux")], not the looser#[cfg(unix)]a prior review round flagged — confirmed fixed in the code at this head. KERNEL_RELEASE_TIMEOUTis deliberately written out as its ownDuration::from_secs(5)rather than reused from another module's constant of the same current value, specifically so an unrelated future change to that other constant can't silently retune this one — and that independence is pinned by its own test.
Deployment notes
Live CI is green at this head: all 40 check runs (get_check_runs) are success or skipped (no failures), plus one additional commit status (Read the Docs build) also success — confirmed via the GitHub API against commit 48776625, not inferred from an earlier round. No migration needed. Worth noting for anyone operating this: KERNEL_RELEASE_TIMEOUT (5s) now governs every Linux uname -r read crate-wide, so rocm install driver, the runtime-install finalizer, the free-form chat answer, the bridge/host snapshots, and the two double-reading MCP paths above all have a higher worst-case latency on a host with a hung uname than before this change (up to 5s per read, up to ~10s where a read happens twice). Windows is unaffected and untouched by this change.
What this covered
Full review of the whole diff (227968dcb30edd574f0405c523536e91f14d4524...487766254ae2b16e648a59de3957d8d279622c92), read against a git worktree pinned to the exact head commit (never checked out in a shared clone). Fanned out to three independent background workers, each blind to the PR description and all review-thread discussion: (1) core Rust logic — host_gpu.rs, host_gpu/os_facts.rs, examine/host_env.rs, examine/wsl.rs, examine.rs, examine_cmd.rs, plus callees (capture.rs, probe_exec.rs, runtime.rs); (2) the e2e/test harness — stand_in_uname.rs, examine_steps.rs, examine.feature, lib.rs; (3) impact analysis and docs accuracy — a whole-repo grep for every caller of gather/gather_without_driver_facts/gather_after/detect_kernel_version, plus docs/architecture.md and docs/host-probing.md in full. The fourth source-reading pass (AGENTS.md/CONTRIBUTING.md adherence, git log/git blame history, prior similar commits, code-comment compliance) could not be dispatched to an independent worker — four spawn attempts were rejected by this environment's shared concurrent-subagent ceiling (other sessions' agents, outside this review's control, were occupying the available slots) — so I ran that pass myself inline instead of as an independent worker; flagging this per method, since it was not independent. Every candidate finding the three independent workers raised was individually re-verified by me directly against the source before scoring (exact file:line tracing, not taken at face value); only one cleared the ≥70-confidence bar for inclusion. Read live CI via the GitHub API (check-runs and status endpoints), not workflow definitions. No embedded instructions directed at an AI reviewer were found in the PR's commits, code, or docs. Not reconciled against this PR's existing review-thread discussion (two prior human approvals and several automated-review/bot rounds already posted here) — this review was reached independently of that thread, per method.
Not a human review. This is an automated code review; please verify findings independently before acting on them.
nowycondro
left a comment
There was a problem hiding this comment.
🤖 Automated review · review-code · head ade7224
Review — no blocking findings
Full review of the whole change (diff a09c9204...ade7224, 12 files, 717 insertions / 29 deletions), fanned out across four independent workers grouped by coupling: core rocm-core probing logic (examine.rs, examine/host_env.rs, examine/wsl.rs, host_gpu.rs, host_gpu/os_facts.rs, apps/rocm/src/examine_cmd.rs), e2e-cucumber test infrastructure, docs (docs/architecture.md, docs/host-probing.md), and a combined history + agent-instruction-adherence pass across all 12 changed files.
Closes an internal AMD tracker ticket (named in the PR body; not retrieved here, per this repo's own convention for bare internal ticket IDs). Per the PR body this is "pair 2 of 6" in docs/host-probing.md's running host-probing consolidation note — the change is scoped to merging two previously-independent uname -r reads into one, and the diff matches that stated scope; no unmentioned work and no claimed-but-missing work was found.
Blocking
None
Non-blocking
None
Decisions for the author
- Every summary-only caller's worst-case kernel-read timeout rises from 1.5 s to 5 s, not just
rocm examine --json— tradeoff
detect_kernel_versionincrates/rocm-core/src/host_gpu/os_facts.rsnow uses a singleKERNEL_RELEASE_TIMEOUT = Duration::from_secs(5)where it previously used the shorter ~1.5 s optional-command timeout. Since every caller ofExamineSummary::gather/gather_without_driver_factsthat reads the kernel field for itself (the text form ofrocm examine, MCP and bridge snapshots, the free-form answer,rocm install driver, the runtime-install finalizer,rocmd's host snapshot/MCP/sandbox paths) goes through this same function, all of them now wait up to 5 s instead of 1.5 s on a host whoseunamehangs, not only the merged--jsonpath. The PR body already states this cost explicitly and argues the tradeoff (a stalled host costs little extra wait vs. a spurious<unknown>); flagging it here only so a maintainer skimming the diff without the full PR body still sees it stated as a deliberate, repo-wide latency change rather than an incidental one.
Positive signals
ExamineSummary::gather_after(crates/rocm-core/src/host_gpu.rs) was deliberately made crate-private rather thanpub, specifically to prevent a caller from pairing the summary with anExaminationtaken from a different host (e.g. a deserialized remote report) — a real misuse this consolidation could otherwise have introduced, closed by the type/visibility design rather than a comment.- The new
kernel_pairunit-test module (crates/rocm-core/src/examine/host_env.rs) and the e2e scenariosexamine-43/examine-44were independently verified, mutation-style, to actually fail when the merge is reverted or a single branch is broken in isolation (e.g. routing the summary back through a secondunameread turnsone_inspection_reads_the_kernel_release_oncered; a differently-wordedprobe_failuresentry still turns the failure-count assertions red after the switch away from keyword matching) — not just superficially green tests. - The e2e harness's stand-in
unameshell-script generator is tested against an adversarial path containing a literal single quote, and the fix for an earlier quoting bug plus a related build-breaking intermediate commit were both caught and corrected within the same branch before this head.
Deployment notes
- See the timeout tradeoff above: any monitoring or expectations around CLI command latency should account for the new 5 s worst-case on a hung
uname, repo-wide (not just--jsonruns). - Windows behavior is explicitly unchanged (examination still leaves
kernel_releaseempty there; the summary still readscmd /C verunder the shorter optional-command timeout) — confirmed in code, not just asserted by the description. - No migration needed.
What this covered
Every file in the diff, read in full by at least one worker, plus the surrounding call graph (git grep across the full PR-head tree confirmed no other caller retained the old two-read pattern) and enough of each worker's neighboring context to judge the change in place. CI on the reviewed head commit: all 40 checks green (two skipped — Skill checks (skillscope) and Sphinx docs build (-W) — neither touched by this diff).
Did not run as a distinct pass: "prior changes" (do review comments on earlier PRs to these files apply here) — the history worker's git log/git blame pass over this PR's own commit range covered equivalent ground and found no contradicted pre-existing convention, but did not search other historical PRs. Not reconciled against this PR's own review discussion or its earlier (superseded) review rounds — this was a blind review per the method's independence rule, run against the current head only.
Not a human review. This is an automated code review; please verify findings independently before acting on them.


Closes ROCMAI-923.
Summary
rocm examine --jsonread the kernel release twice, with two separateuname -rruns. The host summary (detect_kernel_versioninhost_gpu/os_facts.rs, which feedskernel:in the text andsummary.kernelin the JSON) ran it with a 1.5 s limit, decoded the output strictly and dropped it on any failure or non-zero exit. The examination (probe_osinexamine/host_env.rs, which fillskernel_release) ran it with a 5 s limit, decoded lossily, ignored the exit code and kept whatever was printed. So on a host whereunamewas slow or misbehaved,kernel:could read<unknown>whilekernel_releasewas filled in, or the reverse. This matters beyond the display:kernel_releasefeedsis_wsl1_kernelfor the WSL facts and the kernel-dependent diagnoses, which read an empty value as nothing to report. This is pair 2 of 6 indocs/host-probing.md.The survivor is
detect_kernel_version, as the note proposed:probe_osnow calls it forkernel_releaseon Linux (native Linux and WSL share the path, sinceprobe_osruns before the WSL branch returns), and a failed read is left empty as before. It is also one read per run where one command runs both stacks:rocm examine --jsonbuilds the examination and then the summary, and both are now built by one new entry point,Examination::probe_with_summary, which probes this host and gathers the summary from that examination, so no caller can pair the summary with an examination of another host (ExamineSummary::gather_afteris crate-private, androcm examine --jsoncalls the entry point); the summary takes the examination'skernel_release(a failed read included) on Linux instead of runninguname -ragain. Callers that gather only the summary (the text form, the MCP and bridge snapshots) are unchanged and read once for themselves.uname -vstays inprobe_os, where it has no twin. Windows is out of scope and untouched: the examination still leaveskernel_releaseempty there and the summary still readscmd /C verunder the shorter optional-command timeout. Whetherkernel_releaseshould be filled on Windows stays open in the note, as does the Windows unit test the note suggested (the Windows branches did not change, and no Windows host was available).Decisions and every user-visible difference
Timeout: 5 s, the longer of the two old limits, for the one read, written out as
Duration::from_secs(5)inos_facts.rs(not borrowed from another module's constant, which is also 5 s today) and pinned bythe_kernel_release_timeout_is_five_seconds.uname -ris a few bytes the kernel hands over, so a read that takes seconds is a stalled host, where waiting costs little and a spurious "unknown" costs more, becausekernel_releasefeeds the WSL version check and the diagnoses. The cost is that every caller ofExamineSummary::gatherandgather_without_driver_factsthat reads the kernel for itself (the text ofrocm examine, the MCP and bridge snapshots, the free-form answer,rocm install driver, the runtime-install finalizer, androcmd's host snapshot, MCP and sandbox paths) can wait up to 5 s instead of 1.5 s on a host whoseunamehangs (the limit lives indetect_kernel_versionitself); none of them is on a path run for every command, and the--jsonrun waits for one timeout, not two.Empty versus none: a failed read is
Nonein the summary (<unknown>in the text, null in the JSON) and an emptykernel_releasein the examination, with noprobe_failuresentry, as before. Adding an entry would turnstatusdegraded on a host without a usableuname, such as a minimal container, which is a bigger change than this pair warrants. An emptykernel_releasestill reads as WSL 2.Non-zero exit with output: dropped by both. The examination used to keep what a failing
unameprinted and the summary dropped it; a release from aunamethat failed is not trustworthy.Decoding: strict UTF-8 for both. The examination used to decode lossily. A release is ASCII in practice, so the only input that moves is one that is not UTF-8 at all, and a string with replacement characters in it would reach the diagnoses and the WSL check as if it were a release.
The answers that move, one by one: a
unamethat prints a release and exits non-zero was (summary none, examination the release) and is now none in both; output that is not UTF-8 was (none, the release with the bad byte replaced) and is now none in both; aunamethat answers after 2 s was (none, the release) and is now the release in both. Unchanged and pinned: a workinguname, WSL 1 and WSL 2 style releases, aunamethat prints nothing, one that never answers (none in both, now after 5 s each), and the absence of aprobe_failuresentry in every one of those cases.Commit order
Characterisation first, as the note asks. (1) A test commit, green against the unchanged code, that plants a fake
unamethrough the fake-executable helper and pins both copies' answers for a workinguname, WSL 1 and WSL 2 style releases, a non-zero exit with output, a silentuname, output that is not UTF-8, an answer after 2 s and one that never comes, naming the pair in a comment; plus a test of whatprobe_wslmakes of each release string, including the empty one.detect_kernel_versionbecomes crate-visible in this commit so a test next toprobe_oscan call it. (2) The convergence, which flips exactly the assertions meant to change, adds the check that no case leaves a kernelprobe_failuresentry, and updatesdocs/architecture.md. (3) The scenarios. After review: (3a) the hung-unametest now checks the elapsed time, because a stand-in that exits successfully with nothing after 30 s gave the same answers with or without a timeout; (3b) the summary takes the examination's read inrocm examine --json, so the single-read claim holds for that run. (4) The note records the decision, like pair 1: the table of moved answers with the test that pins each, the analysis of the two old copies kept as the record.Tests and mutations
After review, the
probe_failuresassertions no longer filter on wording: the unit test asserts the list is empty andexamine-44compares with a baseline run of a workinguname, and recording a failure with unrelated wording turns both red. The unit tests are inexamine/host_env.rs(modulekernel_pair, gated on Linux becauseprobe_osreadsuname -ronly there) andexamine/wsl.rs; the stand-inunameof the scenarios is built bystand_in_uname_scriptin the harness library, which quotes its log path for the shell and is tested with a path holding a single quote. Because the lookup ofunamefollows the process's ownPATH, which a test thread cannot change without disturbing every other test, each case runs in a child copy of the test binary with its ownPATH, as in the PATH lookup pair. No test reads a file outside the crate. Mutations, each restored by a targeted edit: against the old code, decoding the summary lossily, giving the examination a 1 s limit, making the examination drop stdout of a failingunameand giving the summary a 5 s limit each turned the matching characterisation test red; makingis_wsl1_kernelnever true or true for anything containing "microsoft" turned theprobe_wsltest red. After review, raising the kernel limit to 60 s turns the hung-unametest red (it takes about a minute and the elapsed-time bound fails), routing the summary inprobe_with_summaryback through a secondunameread turnsone_inspection_reads_the_kernel_release_once(which counts the fakeuname's calls through the entry point) red, and makingsummary_kernelignore the examination's value or take an empty one as a release turnsthe_summary_reads_the_kernel_only_when_the_examination_did_notred. Against the converged code,probe_osreadingunameitself again (lossy, exit ignored) turned the non-zero-exit and non-UTF-8 tests red; the summary's limit back to 1.5 s turned the 2 s test red; not filtering an empty answer turned the silent-unametest red; recording a failed read as aprobe_failuresentry turned the failure checks red.Scenario
examine-43andexamine-44inexamine.featuredrive the observable answer on the Linux lane, native Linux and WSL alike (@requires-os:linux): with a stand-inunamefirst onPATH, onerocm examine --jsonrun holdssummary.kernelandkernel_releaselevel on a specific release (examine-43), and for aunamethat prints a release and then fails holds both empty with no kernelprobe_failuresentry (examine-44).examine-43also counts the calls of its stand-inunameand expects exactly one-r; with the JSON handler back ongatherit fails with two. I ran both through the real harness locally on a debugrocmbuilt with--features rocm/e2e-test-hooks(2 scenarios passed on this WSL host), and mutated the converged code to see them fail:probe_osreadingunameitself again turnsexamine-44red, and an examination that reports a different release than the summary turnsexamine-43red. Windows has no scenario here, which is the stated scope.Verification
Run locally on Linux:
cargo test -q --locked -p rocm-core(full),cargo test -q --locked -p xtask prepush,cargo fmt --all -- --check,cargo clippy --locked -p rocm-core -p rocm --all-targets -- -D warnings,cargo clippy --locked -p e2e-cucumber --test e2e -- -D warnings, the Windows-target clippy forrocm-core,cargo test -q --locked -p e2e-cucumber --test feature_naming,cargo xtask check-architecture-doc,check-crate-edgesandmanifest --check, lychee--offlineon the edited docs, a leak scan and a conflict-marker grep. Not run: any Windows host (the Windows branches are untouched and the Windows job is the only place thecfg(windows)code runs), and the rest of the e2e suite. The scenario ids follow the last id on main at the time of this merge (examine-42); whichever change merges later renumbers.Renumbering: the scenarios were
examine-39andexamine-40when first written. Another change merged first and tookexamine-39toexamine-42, so these two are nowexamine-43andexamine-44, the next free ids on main (the harness's feature_naming check requires sequential ids, so they cannot be reserved ahead of another pending change); whichever change merges later renumbers. Nothing else changed, and the @id names are the same.