Skip to content

refactor(rocm-core): one kernel-release read for the summary and the examination stacks - #990

Merged
jussielo-amd merged 17 commits into
mainfrom
refactor-one-kernel-release-read-for-host-probing
Nov 10, 2026
Merged

jussielo-amd merged 17 commits into
mainfrom
refactor-one-kernel-release-read-for-host-probing

Conversation

@jussielo-amd

@jussielo-amd jussielo-amd commented Nov 9, 2026 •

Copy link
Copy Markdown
Collaborator

Closes ROCMAI-923.

Summary

rocm examine --json read the kernel release twice, with two separate uname -r runs. The host summary (detect_kernel_version in host_gpu/os_facts.rs, which feeds kernel: in the text and summary.kernel in 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_os in examine/host_env.rs, which fills kernel_release) ran it with a 5 s limit, decoded lossily, ignored the exit code and kept whatever was printed. So on a host where uname was slow or misbehaved, kernel: could read <unknown> while kernel_release was filled in, or the reverse. This matters beyond the display: kernel_release feeds is_wsl1_kernel for the WSL facts and the kernel-dependent diagnoses, which read an empty value as nothing to report. This is pair 2 of 6 in docs/host-probing.md.

The survivor is detect_kernel_version, as the note proposed: probe_os now calls it for kernel_release on Linux (native Linux and WSL share the path, since probe_os runs 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 --json builds 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_after is crate-private, and rocm examine --json calls the entry point); the summary takes the examination's kernel_release (a failed read included) on Linux instead of running uname -r again. Callers that gather only the summary (the text form, the MCP and bridge snapshots) are unchanged and read once for themselves. uname -v stays in probe_os, where it has no twin. Windows is out of scope and untouched: the examination still leaves kernel_release empty there and the summary still reads cmd /C ver under the shorter optional-command timeout. Whether kernel_release should 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) in os_facts.rs (not borrowed from another module's constant, 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, because kernel_release feeds the WSL version check and the diagnoses. 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 (the limit lives in detect_kernel_version itself); none of them is on a path run for every command, and the --json run waits for one timeout, not two.

Empty versus none: a failed read is None in the summary (<unknown> in the text, null in the JSON) and an empty kernel_release in the examination, with no probe_failures entry, as before. Adding an entry would turn status degraded on a host without a usable uname, such as a minimal container, which is a bigger change than this pair warrants. An empty kernel_release still reads as WSL 2.

Non-zero exit with output: dropped by both. The examination used to keep what a failing uname printed and the summary dropped it; a release from a uname that 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 uname that 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; a uname that answers after 2 s was (none, the release) and is now the release in both. Unchanged and pinned: a working uname, WSL 1 and WSL 2 style releases, a uname that prints nothing, one that never answers (none in both, now after 5 s each), and the absence of a probe_failures entry 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 uname through the fake-executable helper and pins both copies' answers for a working uname, WSL 1 and WSL 2 style releases, a non-zero exit with output, a silent uname, 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 what probe_wsl makes of each release string, including the empty one. detect_kernel_version becomes crate-visible in this commit so a test next to probe_os can call it. (2) The convergence, which flips exactly the assertions meant to change, adds the check that no case leaves a kernel probe_failures entry, and updates docs/architecture.md. (3) The scenarios. After review: (3a) the hung-uname test 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 in rocm 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_failures assertions no longer filter on wording: the unit test asserts the list is empty and examine-44 compares with a baseline run of a working uname, and recording a failure with unrelated wording turns both red. The unit tests are in examine/host_env.rs (module kernel_pair, gated on Linux because probe_os reads uname -r only there) and examine/wsl.rs; the stand-in uname of the scenarios is built by stand_in_uname_script in the harness library, which quotes its log path for the shell and is tested with a path holding a single quote. Because the lookup of uname follows the process's own PATH, which a test thread cannot change without disturbing every other test, each case runs in a child copy of the test binary with its own PATH, 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 failing uname and giving the summary a 5 s limit each turned the matching characterisation test red; making is_wsl1_kernel never true or true for anything containing "microsoft" turned the probe_wsl test red. After review, raising the kernel limit to 60 s turns the hung-uname test red (it takes about a minute and the elapsed-time bound fails), routing the summary in probe_with_summary back through a second uname read turns one_inspection_reads_the_kernel_release_once (which counts the fake uname's calls through the entry point) red, and making summary_kernel ignore the examination's value or take an empty one as a release turns the_summary_reads_the_kernel_only_when_the_examination_did_not red. Against the converged code, probe_os reading uname itself 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-uname test red; recording a failed read as a probe_failures entry turned the failure checks red.

Scenario

examine-43 and examine-44 in examine.feature drive the observable answer on the Linux lane, native Linux and WSL alike (@requires-os:linux): with a stand-in uname first on PATH, one rocm examine --json run holds summary.kernel and kernel_release level on a specific release (examine-43), and for a uname that prints a release and then fails holds both empty with no kernel probe_failures entry (examine-44). examine-43 also counts the calls of its stand-in uname and expects exactly one -r; with the JSON handler back on gather it fails with two. I ran both through the real harness locally on a debug rocm built with --features rocm/e2e-test-hooks (2 scenarios passed on this WSL host), and mutated the converged code to see them fail: probe_os reading uname itself again turns examine-44 red, and an examination that reports a different release than the summary turns examine-43 red. 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 for rocm-core, cargo test -q --locked -p e2e-cucumber --test feature_naming, cargo xtask check-architecture-doc, check-crate-edges and manifest --check, lychee --offline on 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 the cfg(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-39 and examine-40 when first written. Another change merged first and took examine-39 to examine-42, so these two are now examine-43 and examine-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.

…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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 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

Comment on lines +57 to +60
// 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();

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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.

@github-actions

github-actions Bot commented Nov 9, 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.

…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>
@jussielo-amd
jussielo-amd requested a balanced review from Copilot November 9, 2026 18:21
Copilot stopped reviewing on behalf of jussielo-amd due to an error November 9, 2026 18:29

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

Comment on lines +2578 to +2582
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()

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

@jussielo-amd
jussielo-amd marked this pull request as ready for review November 9, 2026 20:35
@jussielo-amd
jussielo-amd requested a review from a team as a code owner November 9, 2026 20:35
@jussielo-amd
jussielo-amd requested a review from rominf November 9, 2026 20:35

@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 · 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_TIMEOUT lives inside detect_kernel_version() itself, so the bump from 1.5s to 5s applies to every caller of ExamineSummary::gather()/gather_without_driver_facts() on a hung uname host, not only the path the description calls out ("the text of rocm examine can wait up to 5s instead of 1.5s"). That includes apps/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, and apps/rocmd's host_snapshot.rs/mcp.rs/sandbox.rs — all of which still do their own independent uname -r read (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 of rocm examine.

Decisions for the author

None

Positive signals

  • Characterisation-tests-first discipline is followed and verifiable, not just claimed: the kernel_pair unit tests in crates/rocm-core/src/examine/host_env.rs pin both old copies' answers before the convergence commit flips only the assertions meant to change, and the e2e scenario examine-39 counts the stand-in uname's actual invocations (rather than only comparing output values) to prove the single-read claim — a mutation that reverted gather_after to gather would be caught by call count even though both reads would return the identical fake string.
  • summary_kernel's branching (examined value reused only when Some, non-empty, and Linux; falls through to a fresh read otherwise) is exactly right against the Examination default and runtime_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 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.

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_after is pub but treats whatever Examination it is handed as this host's kernel. Its only caller today is examine_cmd.rs, so nothing is wrong now, but pub(crate) (or a doc line saying the examination must come from the local host) would keep it from being misused later.
  • The 3 s uname answer 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-uname test, the kernel-pair tests add roughly 13 s of wall time to the rocm-core suite.
  • single_quoted duplicates rocm_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.

Comment thread crates/rocm-core/src/host_gpu.rs Outdated
/// 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> {

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.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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() {

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 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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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>
@jussielo-amd
jussielo-amd requested a balanced review from Copilot November 10, 2026 11:23
@jussielo-amd
jussielo-amd dismissed juhovainio’s stale review November 10, 2026 11:24

All points addressed in d0367b6 and 8b58e7d (slow-uname test margin, gather_after doc line, timeout reach in the PR text); replies posted on the threads.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟢 Approval recommended

No active review issues remain for the kernel-release probing consolidation.

2 open issues

Review effort: Balanced

@r0x0r r0x0r 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.

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.

Comment thread docs/host-probing.md

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.

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.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

Thanks, no change.

Comment thread apps/rocm/src/examine_cmd.rs Outdated
// 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.

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.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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.

Comment thread crates/rocm-core/src/host_gpu.rs Outdated
/// 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> {

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 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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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 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.

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_failures assertions 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_after is a new pub API that relies on a documented precondition (the examination must come from this host).
  • The never-answering uname test 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.

Comment thread apps/rocm/src/examine_cmd.rs Outdated
// 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)?;

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.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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))

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.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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"))

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.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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"))

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.

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.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

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

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.

@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 10, 2026
@jussielo-amd
jussielo-amd removed this pull request from the merge queue due to a manual request Nov 10, 2026

@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 · 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:63 and :108 (install_driver's pre-install ExamineSummary::gather() and execute_driver_install_plan's post-install ExamineSummary::gather(), each paying the read even though only .driver is ever used), apps/rocm/src/chat/mcp_bridge.rs:160-161 (the "examine"/"doctor" MCP/chat tool calls ExamineSummary::gather() directly and then render_examine_text(), which independently calls gather() again via examine_human_report), and apps/rocmd/src/mcp.rs:567-568 (the "examine" tool calls gather() in-process and then shells out to run_rocm_capture(&["examine"]), which re-probes a third time in the child process). All three files are untouched by this PR (confirmed via git diff against base — identical in both), so the double/triple read itself is pre-existing, but KERNEL_RELEASE_TIMEOUT moving from 1.5 s to 5 s inside detect_kernel_version enlarges its blast radius here specifically: each of these single user actions can now wait up to 10 s (or ~15 s for the rocmd subprocess case) on a hung uname, 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 and rocmd/mcp.rs's double-read were not in the PR's own enumerated list of callers at all, though they do go through gather()). Fix: a one-line addition to the doc noting these three paths pay the timeout multiple times, and/or (longer term) give driver_install.rs a kernel-skipping summary variant since it never reads .kernel.
  • The "no kernel probe_failures entry" 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_failures filters on .contains("uname") || .contains("kernel release")) and crates/rocm-core/src/examine/host_env.rs's kernel_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 whole probe_failures list 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_pair unit tests in host_env.rs pin both old copies' answers before the convergence commit flips only the assertions meant to change, and e2e scenario examine-39 counts the stand-in uname's actual -r invocations (not just output values) to prove the single-read claim for rocm examine --json.
  • summary_kernel's four branches (Linux+Some-nonempty, Linux+Some-empty, Linux+None, non-Linux) were traced against Examination's default and runtime_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 8b58e7d itself, 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>

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🟡 Changes recommended

The unit-test script leaves apostrophes in TMPDIR unescaped, causing shell parse errors and kernel-pair test failures unrelated to probing behavior.

3 open issues

Review effort: Balanced

Comment on lines +729 to +730
"#!/bin/sh\nif [ \"$1\" = -v ]; then echo '#1 SMP fake'; exit 0; fi\necho x >> '{}'\n{body}\n",
calls.display()
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 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 · 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 calls ExamineSummary::gather() once, then calls render_examine_text() → render_examine_text_with_paths → examine_human_report, which calls ExamineSummary::gather() a second time (apps/rocm/src/examine_report_text.rs:130) — two independent uname -r subprocess reads for one tool invocation. rocmd's "examine" MCP tool similarly calls gather() in-process and then shells out via run_rocm_capture(&["examine"]), which re-execs rocm examine as a child process that calls gather() 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, but KERNEL_RELEASE_TIMEOUT moving from 1.5s to 5s inside the now-shared detect_kernel_version() enlarges the cost of that pre-existing pattern specifically at these two sites: a worst-case hung uname now 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 in docs/host-probing.md noting 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 changing chat/mcp_bridge.rs and rocmd/mcp.rs (and arguably driver_install.rs's intentional pre/post-install double read), which this pair's stated scope (detect_kernel_version/probe_os/rocm examine --json only) 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-39 counts literal -r lines in the stand-in uname'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 against Examination's default and runtime_is_linux() (a const fn) and is exactly right: the linux gate — not examined.is_some() alone — is what prevents an off-Linux empty-by-design kernel_release from being misread as a failed Linux read.
  • ExamineSummary::gather_after is pub(crate), with a doc comment stating its precondition explicitly (the Examination handed in must be of this same host) — a prior-round nit about this being pub with 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-uname baseline, rather than filtering by a hardcoded substring like "uname"/"kernel" — verified directly in crates/rocm-core/src/examine/host_env.rs:707 and tests/e2e-cucumber/tests/e2e/examine_steps.rs's probe_failures_with_a_working_uname, closing a real gap a differently-worded future failure message would otherwise have slipped through.
  • The stand-in uname script's log-path shell quoting (tests/e2e-cucumber/src/stand_in_uname.rs's single_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_TIMEOUT is deliberately written out as its own Duration::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.

Copilot AI left a comment

Copy link
Copy Markdown
Contributor

Choose a reason for hiding this comment

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

🔵 Needs a closer look

The unit-test stand-in embeds an unescaped temporary log path in single quotes, causing the generated script and kernel-pair tests to fail when TMPDIR contains an apostrophe.

3 open issues

Review effort: Balanced

@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 10, 2026
Merged via the queue into main with commit cf20ee1 Nov 10, 2026
41 checks passed
@jussielo-amd
jussielo-amd deleted the refactor-one-kernel-release-read-for-host-probing branch November 10, 2026 15:06

@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 · 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_version in crates/rocm-core/src/host_gpu/os_facts.rs now uses a single KERNEL_RELEASE_TIMEOUT = Duration::from_secs(5) where it previously used the shorter ~1.5 s optional-command timeout. Since every caller of ExamineSummary::gather/gather_without_driver_facts that reads the kernel field for itself (the text form of rocm 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 whose uname hangs, not only the merged --json path. 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 than pub, specifically to prevent a caller from pairing the summary with an Examination taken 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_pair unit-test module (crates/rocm-core/src/examine/host_env.rs) and the e2e scenarios examine-43/examine-44 were 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 second uname read turns one_inspection_reads_the_kernel_release_once red; a differently-worded probe_failures entry 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 uname shell-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 --json runs).
  • Windows behavior is explicitly unchanged (examination still leaves kernel_release empty there; the summary still reads cmd /C ver under 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.

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.

5 participants