Skip to content

ROCMAI-872: keep the update check from preparing a managed Python - #951

Merged
jussielo-amd merged 34 commits into
mainfrom
fix-update-check-prepares-no-python
Nov 9, 2026
Merged

jussielo-amd merged 34 commits into
mainfrom
fix-update-check-prepares-no-python

Conversation

@jussielo-amd

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

Copy link
Copy Markdown
Collaborator

Reading the index for a wheel runtime needs the interpreter's wheel tag, and a runtime that records no usable Python made the update check go and get one: on a host with none it downloaded a managed uv, had uv install Python and saved that Python's path in the configuration. That ran for rocm update, for rocm update --json (the dashboard's check), for the check the CLI runs ahead of other commands, and for the plan behind rocm update --apply --dry-run, so a read-only look at the runtimes changed the host. It was found while fixing the same problem for the SDK install preview in #906.

These callers now go through a new runtime_update_check, which finds an interpreter with the search-only entry point #906 added and, when there is none, takes the wheel tag from the interpreter the layout requires. The text report adds a python_note: line saying an update would use uv to install the managed Python, which the check did not do; the JSON keeps its shape, since the dashboard parses it. The note's caveat about an unreadable wheel tag reuses the helper #906 introduced. runtime_update_plan, which rocm update --apply works from, still prepares the Python, because the install that follows needs it, so a real apply behaves as before. The update flow takes its two planners as arguments, so a unit test runs the choice on every platform, Windows included: a --dry-run calls only the check and an apply only the plan. Which therock function is the check is pinned only on Unix, by the unit test described below, and on Linux by update-10; no test on Windows pins that pairing, because the two arguments have the same type. rocm update --apply --dry-run prints the install preview's own python_note: and not the check's, so the same note is not printed twice (update-10 asserts it); a dry run that finds nothing newer returns before the preview and prints neither. The comment that documents the side effects of the assistant's read-only tools now says that update_check and install_sdk_dry_run prepare no Python.

Tests: a unit test drives the report, the JSON, the startup check, the check plan and apply_runtime_update with --dry-run on a host with no Python and a recording uv, with the apply plan and a real apply as the controls that show the stand-in is reachable. Scenarios update-09 (the report) and update-10 (the --dry-run preview) drive the built binary and check the note against the state it left: the recording uv was never run, and there is no managed-tools folder and no saved config. Both fail without the change. They run on Linux, which is the host the empty-PATH setup is built for. Known behaviours, not changed here: the progress line about a PATH Python that is not usable prints to standard output ahead of the report, as it already does for the install preview, and a ROCM_CLI_MANAGED_PYTHON_VERSION whose wheel tag does not fit makes the check fail with the planner's existing wording about what a real install would prepare. On a ROCm 10 or newer runtime the check still resolves the package versions with uv pip compile and can fetch the managed uv (the install preview no longer does, since #954), though it never prepares a Python. Not run locally: the full workspace gate, Windows and the GPU lanes.

On a host with no usable Python, rocm install sdk --dry-run (and the install_sdk_dry_run assistant tool) went on to download a managed uv, have it install Python and save that Python's path in the config before printing a plan, although a preview promises to change nothing. The preview only needs the interpreter's wheel tags, so it now reports that a real install would prepare a managed Python (python_note) and prepares nothing; every refusal the real resolution raises is raised for the preview too. A real install resolves and prepares exactly as before.

Adds unit tests for the no-Python, PATH Python, saved Python, stale saved Python and bootstrap-disabled cases, and scenario runtime-22, which checks the preview's note together with the empty tools, cache and config folders and a recording uv that is never run.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
… refuse

With ROCM_CLI_MANAGED_PYTHON_VERSION naming a version whose wheel tag is not the one the layout needs (3.13 against cp312), a dry run on a host with no usable Python said it would prepare that Python, but a real install prepares it, finds the wrong tag and refuses. The preview now applies the same tag rule, shared with the check an existing interpreter must pass, and fails with the install's message instead. A version whose tag cannot be read off its name is announced as before.

Adds a unit test and scenario runtime-23, which asserts the refusal together with the empty tools, cache and config folders.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The harness points the CLI at a cache shared across scenarios and, on CI, across runs. runtime-22 asserted that the preview had downloaded no tool archive by looking in that shared folder, so a uv archive left by an earlier run failed it although the preview downloaded nothing. The scenarios now set ROCM_CLI_CACHE_DIR to a folder under the scenario root and assert against it.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…y run

The dry run's check of ROCM_CLI_MANAGED_PYTHON_VERSION read only plain major.minor versions, so 3.13t, cpython-3.13 and cpython@3.13 were announced as a plan although the installed interpreter reports cp313 and the real install refuses it. The version is now read in those spellings. A version whose tag still cannot be read is announced as unchecked, in both the note and the progress line, rather than as a promise.

The progress line before the search no longer says a real install would prepare a Python, since the search can end in a refusal; the line naming the Python, or the refusal, follows it. runtime-23 asserts the whole output: no promise before the refusal.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…evidence

ROCM_CLI_UV_BINARY makes the CLI return the recording uv before any download could begin, so the check for a tool archive in the scenario's cache cannot fail by itself. It stays as a backstop and says so; the scenario comments and docs/testing.md now name the uv log as what shows nothing was prepared.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Signed-off-by: Jussi Elo <jussi.elo@amd.com>

# Conflicts:
#	apps/rocm/src/therock.rs
#	tests/e2e-cucumber/features/runtime_setup.feature
Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…sion

With an unusable PATH Python, no usable saved interpreter and managed Python disabled, the preview said a real install would use managed Python and then refused; the saved-interpreter line made the same premature claim. The two lines now state only what was found. The one line that predicts the preparation is built from the decision itself and printed by python_for_install, so it exists only for a decision that passed the bootstrap policy and the version check; the Using lines moved there with it. A real install prints exactly what it did.

Adds a state-matrix unit test over PATH Python, saved Python, bootstrap policy and version override that asserts each row's whole output and the state left behind, and scenario runtime-25 for the policy refusal.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
A preview of a ROCm 10 or newer wheel resolves its package versions with uv pip compile, so on a clean host it can still download the managed uv and create the data folder's tools folder, although it prepares no Python. docs/testing.md, docs/manual-testing.md and the dash-TUI tool-group comment now say so, and describe the state matrix and the refusal scenarios the preview is checked by.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The doc comment said a wildcard yields None, but "3.13.*" reads as cp313:
whatever follows the minor is not validated, because the major and minor
alone decide the wheel tag. A wildcard that leaves the minor open ("3.*", "*")
is what yields None. Reword the comment to say so and pin both unreadable
wildcards in the existing reader test.

Also say in the comment that this hand-rolled reader can drift from what uv
accepts, and that the failure is benign: an unreadable spelling is announced
as unchecked rather than refused.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
A preview that would prepare a managed Python whose wheel tag cannot be read
off its name said so twice, in the python_note line and in the progress line,
each with its own sentence. Build the caveat from one function so the two
cannot drift. The note is unchanged; the progress line now reads "... would
prepare Python pypy@3.10 (its wheel tag cannot be checked until it is
installed; cp312 is required). This preview does not." instead of using a
"whose ... " clause. The unit tests that pin both lines are updated to match.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
PythonLauncher::source was a bare &'static str ("env", "path", "managed",
"manifest") that three places matched or compared by spelling, with a
catch-all arm in the progress line that would hide a new spelling. Make it a
PythonSource enum with an as_str for the install plan's python_source line, and
match it exhaustively in the progress text. The printed output is unchanged.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…naged-Python policy

PythonResolverEnv already injects the two inputs that locate an interpreter (ROCM_CLI_PYTHON and the search directories), but the two inputs that decide what happens when none is found were still read from the process environment inside the decision: whether the managed bootstrap is disabled and which managed Python version is requested. A test of that decision therefore had to mutate process-wide environment variables under a lock.

Both now travel in PythonResolverEnv (read once by from_process_env, which the real resolver still uses), and find_python_launcher_in, plan_python_launcher_in and the real install's ensure_managed_python take them from it, so a preview and an install made from one environment cannot disagree about the version or the policy. managed_python_version keeps its signature for the progress line in therock.rs and still reads the process environment. No behaviour change: the existing tests, which build an environment from the process one, pass unchanged.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
The tests of what a dry run decides about Python drive it with shell-script interpreters and are cfg(unix), and the scenarios that cover it are Linux-only, so the Windows CI job ran none of it although a fresh Windows install is one of the hosts the preview is for.

The decision needs no interpreter: with nothing to find, python_for_install is a function of the resolver environment (now carrying the managed-Python policy) and the dry_run flag. The new test builds that environment directly and runs python_for_install through it, so it runs on the Windows job. It asserts, per row, the preview's complete progress output together with the state it leaves behind (no config, manifest, or folder created): the default, a patch release, a blank override and an unreadable spelling are announced (the last as unchecked); a version whose wheel tag is not the layout's is refused in every spelling that reads as one; a disabled bootstrap is refused with the install's own message. A control runs the real install on the same host and checks it reaches the managed uv, which is a file that cannot be launched, so nothing is downloaded or run and the preview's silence about uv is shown to mean something.

The search order (python3 before python on Linux, python, python3, py with PATHEXT on Windows) and the interpreter probes are still covered by the Unix tests only. RestoredEnv and snapshot lose their cfg(unix) because the new test shares them.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…l tag

PlannedPython::WouldPrepareManaged carried a tag_checked bool next to the requirement it was checked against. The bool is one of two named cases, so it is now a TagCheck enum (Checked, Unchecked), and unchecked_tag_caveat matches on it. The preview's note and progress line are unchanged; the existing tests, updated to the enum, pass as before.
Signed-off-by: Jussi Elo <jussi.elo@amd.com>
… install and a preview

An install and a preview word the two findings about a PATH Python and a saved managed Python that cannot serve the install differently (the install says what it goes on to do, the preview states the finding only), but only the preview's wording was pinned, by the state matrix on Unix hosts. This pins both, on every platform, before the two parallel match blocks that print them are merged into one.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
find_python_launcher_in printed the finding about a PATH Python and the one about a saved managed Python from two parallel Install/Preview match blocks that differed only in a trailing clause. LookupPurpose::unusable_python_line now builds both lines: both purposes state the finding, an install adds what it goes on to do. The output is byte-identical, as the test added in the previous commit pins for both purposes.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…d uv venv line is not verbatim

docs/testing.md and the runtime-23 scenario comment now name the unit test that runs the preview's Python decision on every platform, the Windows CI job included, and say what stays uncovered (the Windows search order and any Windows run of the preview). docs/testing.md and docs/manual-testing.md also say that the plan's command line prints uv venv --python 3.12, a version rather than a path, so it is not copy-pasteable verbatim: uv resolves 3.12 itself and may choose a different Python 3.12 than the managed one a real install prepares.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Re-wrap the manual-testing bullet and the testing.md paragraph on the dry-run Python preview to the surrounding 80-column style. No words change.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Reading the index for a wheel runtime needs the interpreter's wheel tag, and a runtime that records no usable Python made the check go and get one: on a host with none it downloaded a managed uv, had uv install Python and saved that Python's path in the configuration. That ran for `rocm update`, for `rocm update --json` (the dashboard's check), for the check the CLI runs ahead of other commands, and for the plan behind `rocm update --apply --dry-run`, so a read-only look at the runtimes changed the host.

These callers now go through `runtime_update_check`, which finds an interpreter with the search-only entry point the install preview already uses and, when there is none, takes the wheel tag from the interpreter the layout requires. The text report adds a `python_note:` line saying an update would use uv to install the managed Python, which the check did not do; the JSON keeps its shape. `runtime_update_plan`, which `rocm update --apply` works from, still prepares the Python, since the install that follows needs it.

A unit test drives the report, the JSON, the startup check and the check plan on a host with no Python and a recording uv, with the apply plan as the control that shows the stand-in is reachable. Scenarios update-09 and update-10 drive the report and the dry-run preview through the built binary and check the note against the state it left.

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 tool side-effect comments still claim Python is installed and its path saved, so they need to reflect search-only resolution while retaining the ROCm 10 caveat about acquiring uv.

1 open issue
What changed in this PR

This PR extends #906’s search-only Python planning to runtime update checks, preventing checks and dry runs from preparing managed Python while preserving preparation for real updates.

Changes:

  • Routes text, JSON, startup checks, and update previews through search-only planning, adding a text-only python_note without changing the JSON shape.
  • Adds regression tests and Linux scenarios that check output alongside evidence that no Python was prepared.
  • Updates architecture and testing documentation; the stacked diff also includes #906’s SDK-preview changes.

Tests were not run in this review environment.

File Description
tests/​e2e-cucumber/​tests/​e2e/​therock_steps.rs Adds no-Python fixtures and output/state assertions.
tests/​e2e-cucumber/​src/​bin/​fake-uv.rs Records invocations to detect unwanted preparation.
tests/​e2e-cucumber/​features/​update.feature Adds update-report and dry-run regression scenarios.
tests/​e2e-cucumber/​features/​runtime_setup.feature Adds SDK-preview and refusal scenarios from #906.
docs/​testing.md Documents coverage, commands, and resolution caveats.
docs/​manual-testing.md Adds manual checks for Python-free previews and updates.
docs/​architecture.md Describes separate update-check and apply planning paths.
crates/​rocm-dash-tui/​src/​agent/​tools.rs Revises comments documenting read-only tool side effects.
apps/​rocm/​src/​update_cmd.rs Selects search-only planning for dry runs.
apps/​rocm/​src/​therock/​update.rs Introduces search-only update checks and regression tests.
apps/​rocm/​src/​therock/​test_support.rs Adds scoped environment restoration for tests.
apps/​rocm/​src/​therock/​python.rs Separates Python discovery from preparation and generates planning notes.
apps/​rocm/​src/​therock.rs Integrates SDK-preview planning and exports the update-check entry point.

Review effort: Balanced

Comment thread crates/rocm-dash-tui/src/agent/tools.rs Outdated
Comment on lines +211 to +216
// `update_check` can also, on a host with no usable Python on PATH, download a
// managed `uv` and Python into the data folder and record that Python in the
// saved config; `install_sdk_dry_run` prepares no Python and saves no Python
// path: on such a host it reports the Python a real install would prepare. (A
// ROCm 10 preview still resolves package versions with `uv` and can fetch the
// managed `uv` into the data folder.) The boundary type

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.

Fixed in 96f121a. You are right that the comment still described the old behaviour. It now says that neither update_check nor install_sdk_dry_run prepares a Python or saves a Python path: on a host with no usable Python they report the Python a real update or install would prepare, and update_check runs rocm update, whose text report carries a python_note: line saying so. Only a real apply or install prepares it. The ROCm 10 caveat stays: a check or preview there can still fetch the managed uv, though never a Python. I found no other place that repeated the old claim.

The base pull request merged, so this branch now carries only its own change on top of main. main's version of everything that pull request owns is kept as merged, including its later review fixes; the update check, its plan function, the note, the shared test helper, the scenarios and the docs are the only content added here.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
… prepare

The side-effects note on the read-only ROCm tools still said that `update_check` can download a managed `uv` and Python and record that Python in the saved config, which is the behaviour the update check no longer has: it runs `rocm update`, which now only reports the Python a real update would prepare, in a `python_note:` line of its text report. The note now says that neither `update_check` nor `install_sdk_dry_run` prepares a Python or saves a Python path, that only a real apply or install does, and keeps the caveat that a ROCm 10 or newer check or preview can still fetch the managed `uv`. No other file repeated the old claim.

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.

🟢 Approval recommended

No active review issues were identified for the change separating search-only update checks and dry-run previews from Python preparation during apply.

1 open issue

Review effort: Balanced

@jussielo-amd
jussielo-amd marked this pull request as ready for review November 6, 2026 16:15
@jussielo-amd
jussielo-amd requested a review from a team as a code owner November 6, 2026 16:15
main moved after the base pull request merged, and one line of docs/architecture.md, the entry for therock/update.rs, was changed on both sides. The resolution keeps main's wording (including the root-payload clause) and adds only this change's two additions: the sentence about runtime_update_check and its name in the list of functions the entry covers.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
main moved again (the chat.rs split) and the entries for therock/update.rs, therock/test_support.rs and tool_policy.rs in docs/architecture.md, which sit next to each other, were changed on both sides. The resolution keeps main's text for the entries this change did not touch and this change's wording for the therock/update.rs entry, which main had left as it was.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>

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

Nothing blocking from my pass. The change reads correctly: the update check goes through the search-only path, the report says what would be prepared, and non-check behaviour is unchanged. update-09 and update-10 assert the note together with filesystem state.

Non-blocking:

  • plan_for_update is a pass-through whose unit test only proves the if. The dry_run forwarding at the call site is caught only by the unix-only test and update-10 (Linux), so a Windows swap of that argument would go unnoticed. A comment naming the covering test, or stating the gap in the PR text, would do.
  • RuntimeUpdatePlan.python_note is populated for --apply --dry-run, but apply_runtime_update never prints it.
  • The docs/architecture.md entry for therock/python.rs doesn't mention the now pub(super) plan_python_launcher or the new update_note (it was already stale before this PR).

Comment thread apps/rocm/src/update_cmd.rs Outdated
/// check, which prepares nothing; a real apply takes the plan, which prepares the
/// Python the install that follows needs. A function of the two so a test runs it
/// on every platform without a host that has no Python.
fn plan_for_update<T>(

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.

Non-blocking: plan_for_update is a generic pass-through; its unit test only proves the if, not that apply_runtime_update forwards dry_run. On Windows the therock/update.rs test is cfg(unix), so swapping the argument at the call site would not be caught. Consider a comment naming the test that proves the wiring, or state the gap in the PR text.

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, done in b5c49b2. The update flow now takes its two planners as arguments (apply_runtime_update_with), and the unit test a_dry_run_takes_the_check_and_an_apply_takes_the_plan drives it with planners that report nothing newer, so it needs no host without a Python and runs on Windows too: a --dry-run must call only the check and an apply only the plan. The pass-through helper is gone. I confirmed the test is red when the dry_run choice is inverted. Which therock function is the check is still pinned only on Unix, by the test in therock/update.rs, and on Linux by update-10, because the two arguments have the same type; the comments and the PR text now say that no test on Windows pins that pairing.

The other two notes from the review body have no thread, so here they are. python_note on an --apply --dry-run: the preview that follows already prints its own python_note: from the decision a real install takes (update-10 asserts it), so I did not print the plan's note a second time, and 9000afa records why in a comment; a dry run that finds nothing newer returns before the preview and prints neither note. The docs/architecture.md entry for therock/python.rs now describes plan_python_launcher, python_for_install and PlannedPython with its two note methods, and lists what therock/update.rs reads from the module (1216573).

…d an apply the plan

apply_runtime_update chose between the two planners through a pass-through helper whose unit test proved only the `if`, so the dry_run argument at the call site was caught only by a test that runs on Unix and by update-10 on Linux. The flow now takes the two planners as arguments (apply_runtime_update_with), and the unit test drives it with planners that report nothing newer, so it needs no host without a Python and runs on Windows too: a --dry-run must call only the check and an apply only the plan. Which therock function is the check stays pinned only on Unix and by update-10, and the comments now say so.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…hon_note

The plan an apply --dry-run works from carries a python_note, and apply_runtime_update never printed it. The preview that follows prints its own python_note from the decision a real install takes, which scenario update-10 asserts, so printing the plan's as well would say the same thing twice. A comment now records that, and that a dry run which finds nothing newer returns before the preview and prints neither note.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…python.rs entry

The architecture entry for therock/python.rs named neither the planned-Python lookup that previews and update checks use nor the python_note lines it writes, and did not list what therock/update.rs reads from it. It now says what plan_python_launcher, python_for_install and PlannedPython are and which items are pub(super) for the update module.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 9, 2026

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

Read through this one carefully and I'm happy with it. The fix sits at the right layer, and every entry point you switched over has a test that goes red when the change is reverted.

The test design is the strongest part. Each new test pairs the printed claim with the filesystem state it left behind, and adds a control proving the stand-in uv was actually reachable. That control is what makes the tests mean anything -- without it the note alone would still pass with the bug present.

I also went looking for a way the three lines could drift apart and couldn't find one: update_note, note and progress_text all derive from the same WouldPrepareManaged fields via unchecked_tag_caveat, so they can't disagree about the version. Nice side effect too -- --dry-run's help text ("without changing files") is true for the first time.

Worth a line in the release notes rather than a change here: rocm update's text report gains a python_note: line. The --json shape is unchanged.

Two design choices I'd rather hear your thinking on than see changed:

  • apply_runtime_update_with takes two planner closures of the same type, so the compiler can't catch a transposed pair -- and neither can the only cross-platform test, a_dry_run_takes_the_check_and_an_apply_takes_the_plan. The wiring is pinned only on Unix. You do document this, which I appreciate. Threading a PythonAccess-style enum through a single planner would make the transposition unrepresentable rather than merely tested for.
  • --json carries no python_note. That keeps the dashboard contract stable, which is defensible, but it means the dash Updates tile never learns the check skipped Python, while the agent's update_check tool (which reads the text rocm update) does.

CI is green on everything that has finished -- clippy, E2E and coverage included -- with the W7900 and MI300X lanes still queued as I write this.

Approving with two documentation nits inline. Neither blocks the merge, but both are entries that read as true and aren't.

Comment thread docs/architecture.md Outdated
- [`therock/consent.rs`](../apps/rocm/src/therock/consent.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/source.rs` and `therock/version.rs` and reaches the registry through [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) (split out of `therock.rs`): the consent gate for an install that would displace the active default runtime. `active_default_runtime_relation` says what the install would replace (an upgrade, downgrade or reinstall when it is the same family and channel, otherwise the different runtime it displaces) or `None` when nothing is the active default, and it fails closed, with a relation naming what could not be resolved, when the config names an active default the registry cannot resolve; `SdkInstallConsent` and `SdkInstallApprovalSource` say how consent is obtained (asked for, or already granted by `--yes`, `--approve-replacing-active-default` or `rocm update --apply`); `sdk_install_approval` turns those and whether a terminal is attached into proceed, prompt or refuse (`SdkInstallApproval`); `preapproved_install_line`, `fresh_install_line`, `refuse_non_interactive_message` and `confirm_overwrite_existing_sdk` are the wording of each outcome, and the prompt reads its answer through `prompt_yes_no` and the shared [`confirm.rs`](../crates/rocm-core/src/confirm.rs). `SdkInstallConsent`, `SdkInstallApprovalSource` and `preapproved_install_line` are re-exported by `therock.rs`; the other items `therock.rs` calls are `pub(super)`, as is `active_default_relation_text`, which the version property tests call, and the rest is private.
- [`therock/update.rs`](../apps/rocm/src/therock/update.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/family.rs`, `therock/io.rs`, `therock/process.rs`, `therock/python.rs`, `therock/resolve.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for the manifests (split out of `therock.rs`): whether an installed runtime has something newer, and the bounded startup check that asks. `runtime_update_plan` resolves the latest source for one runtime (`resolve_latest_for_manifest` re-resolves a wheel runtime through `resolve_pip_runtime_with_timeout` and a tarball one through `resolve_tarball_artifact_with_timeout`, on the layout `manifest_source_layout` reads back from the manifest) and `runtime_freshness` classifies it (`RuntimeFreshness`: up to date, update available, repair available when the installed composition is not the one a fresh install would record, or ahead of the index) into a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` (the form the dashboard's update check parses) present the plans, and `maybe_refresh_startup_update_check` keeps one `StartupUpdateCheckRecord` in the cache so the check runs at most once every twelve hours, under a two-second download timeout. `runtime_key` and `wheel_runtime_key`, which name the install a plan targets, stay in `therock.rs`; whether a replacement's root is installed is `rocm_core::install_root_has_payload`. `render_update_report`, `render_update_json`, `runtime_update_plan` and `maybe_refresh_startup_update_check` are `pub(crate)` and re-exported by `therock.rs`; `RuntimeFreshness`, `runtime_freshness` and `select_startup_update_manifest` are `pub(super)` for the version property tests, and the rest is private.
- [`therock/update.rs`](../apps/rocm/src/therock/update.rs) — full domain extraction, a child of `therock.rs` that builds on `therock/family.rs`, `therock/io.rs`, `therock/process.rs`, `therock/python.rs`, `therock/resolve.rs`, `therock/source.rs` and `therock/version.rs`, and on [`runtime_registry.rs`](../apps/rocm/src/runtime_registry.rs) for the manifests (split out of `therock.rs`): whether an installed runtime has something newer, and the bounded startup check that asks. `runtime_update_plan` resolves the latest source for one runtime, and `runtime_update_check` does the same for a caller that changes nothing (the report, the JSON, the startup check and an apply's preview): given a wheel runtime that records no usable Python, the plan prepares a managed Python (an apply needs one) while the check works the wheel tag out from the interpreter the layout requires and carries a `python_note` instead (`resolve_latest_for_manifest` re-resolves a wheel runtime through `resolve_pip_runtime_with_timeout` and a tarball one through `resolve_tarball_artifact_with_timeout`, on the layout `manifest_source_layout` reads back from the manifest) and `runtime_freshness` classifies it (`RuntimeFreshness`: up to date, update available, repair available when the installed composition is not the one a fresh install would record, or ahead of the index) into a `RuntimeUpdatePlan`. `render_update_report` and `render_update_json` (the form the dashboard's update check parses) present the plans, and `maybe_refresh_startup_update_check` keeps one `StartupUpdateCheckRecord` in the cache so the check runs at most once every twelve hours, under a two-second download timeout. `runtime_key` and `wheel_runtime_key`, which name the install a plan targets, stay in `therock.rs`; whether a replacement's root is installed is `rocm_core::install_root_has_payload`. `render_update_report`, `render_update_json`, `runtime_update_plan`, `runtime_update_check` and `maybe_refresh_startup_update_check` are `pub(crate)` and, with `RuntimeUpdatePlan`, which [`update_cmd.rs`](../apps/rocm/src/update_cmd.rs) reads its verdict from, re-exported by `therock.rs`; `RuntimeFreshness`, `runtime_freshness` and `select_startup_update_manifest` are `pub(super)` for the version property tests, and the rest is private.
- [`therock/test_support.rs`](../apps/rocm/src/therock/test_support.rs) — test-only (`#[cfg(test)]`), a child of `therock.rs`: fixtures shared by the `therock` child modules' tests and the tests left in `therock.rs` (`test_paths`, `test_runtime_manifest`, `write_test_runtime_manifest`, `family_for_test`). Separate from the crate-level [`test_support.rs`](../apps/rocm/src/test_support.rs), which holds the fixtures every module's tests share, such as `PROCESS_ENV_TEST_LOCK` and the background-helper fixtures `runtime_state` and `set_helper_facts`.

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 entry for therock/test_support.rs no longer describes the module accurately. It enumerates the module's fixtures as test_paths, test_runtime_manifest, write_test_runtime_manifest, family_for_test -- but this change moves RestoredEnv into that module (apps/rocm/src/therock/test_support.rs, the new RestoredEnv block, around line 37) and doesn't add it here.

AGENTS.md section 6 is the relevant bit: the check reads no prose, so keeping an entry's description true is on the author rather than on CI.

To be clear about which side is wrong -- the code is correct; it's this entry that's out of date. Adding RestoredEnv to the parenthesised list is the whole fix.

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, fixed in 5e630fc. The therock/test_support.rs entry now lists RestoredEnv with what it does (it sets or removes process environment variables for one test and puts them back on drop, so a caller holds PROCESS_ENV_TEST_LOCK for as long as it holds one).

use super::python::{
PythonLauncher, PythonSource, python_launcher_install_ready, python_requirement,
resolve_python_launcher, wheel_compatibility_for_python,
PythonLauncher, PythonSource, plan_python_launcher, python_launcher_install_ready,

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.

Anchored here because the diff doesn't reach the top of the file; the lines I actually mean are the module doc at apps/rocm/src/therock/update.rs lines 5-16.

That doc doesn't mention the new check entry point. It still describes runtime_update_plan as the module's resolver and names neither runtime_update_check, PythonAccess nor python_note -- while the architecture.md entry for this same file was updated in full in this change.

Mirroring the architecture.md wording here would be enough.

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, fixed in a623dc5. The module doc of therock/update.rs now names runtime_update_check next to runtime_update_plan, says that the two differ in PythonAccess (the plan prepares a managed Python for a runtime that records none, the check works the wheel tag out from the interpreter the layout requires and carries a python_note), and says that the JSON form carries no python_note. It mirrors the architecture entry for the same file.

On the three points in the review body, which have no thread of their own. Release notes: the repository keeps no changelog or release-notes file (the only file of that kind is the release trust document), so there is nothing for this change to add to, and the PR description already names the new python_note: line in the text report.

The two planner closures: you are right that the compiler cannot tell a transposed pair apart and that the cross-platform test cannot either. PythonAccess already exists in therock/update.rs, so the single-planner shape is small: apply_runtime_update_with would take one planner that receives a PythonAccess, choose SearchOnly for a --dry-run and MayPrepare for an apply, and the test would assert the value it received, which would pin the pairing on Windows as well. It needs the enum and plan_runtime_update to be visible to update_cmd.rs, and the two thin wrappers runtime_update_plan and runtime_update_check are used by the report, the JSON and the startup check too, so I would rather do it as a small follow-up than change an approved signature in this change. Say if you prefer it here.

python_note in --json: it is left out on purpose. The only consumer is the dashboard's Updates tile, which reads status and latest_version from the parsed document and ignores everything else, and those two fields are still right when the check skips preparing a Python, because the wheel tag comes from the interpreter the layout requires. The note says what an apply would do, not whether an update exists. Adding the field would be additive and harmless to the tile, so it can follow if the tile ever wants to show it.

@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Nov 9, 2026
…ure entry

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…te.rs module doc

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 9, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Nov 9, 2026
Signed-off-by: Jussi Elo <jussi.elo@amd.com>
…t the install preview fetches no uv

The merged notes still said the update check prepares a managed Python, which this change made false, and that the install preview can fetch the managed uv, which the preview change made false. The check on a ROCm 10 or newer runtime still resolves the package versions with uv and can fetch it; it prepares no Python, and the install preview fetches no uv.

Signed-off-by: Jussi Elo <jussi.elo@amd.com>
@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 9, 2026
@github-merge-queue
github-merge-queue Bot removed this pull request from the merge queue due to a conflict with the base branch Nov 9, 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 cf785f1fb6c4

Review — no blocking findings

Full review of the whole change.
Implements ROCMAI-872 in full: reuses #906's search-only Python-discovery entry point for the update check, reports what an update would prepare instead of preparing it, keeps rocm update --apply (real) behaviour unchanged, and pairs the new unit test / Gherkin scenarios (update-09, update-10) with filesystem-state assertions as the ticket's scope requested.

Blocking

None

Non-blocking

  • Stale module doc comment in the shared e2e steps file — tests/e2e-cucumber/tests/e2e/therock_steps.rs:5
    The file's header comment still reads "Steps for therock_next_generation.feature.", but the file now also hosts the step definitions for runtime_setup.feature and, as of this change, update.feature's new update-09/update-10 scenarios. Reusing the shared Python-preparation-contract helpers already in this file (rather than duplicating them in update_steps.rs) is a reasonable choice, but the header no longer tells a reader where to look. Confidence 72 · mechanical · Fix: broaden the doc comment to name all three feature files it now serves.

Decisions for the author

  • apply_runtime_update_with's check/apply_plan closures share one function-pointer type — tradeoff
    apps/rocm/src/update_cmd.rs binds therock::runtime_update_check and therock::runtime_update_plan to two parameters of identical type (FnOnce(&InstalledRuntimeManifest, &[InstalledRuntimeManifest]) -> Result<RuntimeUpdatePlan>), so a transposed pair would still compile. The real-function binding is pinned by only one cross-platform-reachable test: a #[cfg(unix)] unit test in apps/rocm/src/therock/update.rs, plus the Linux-only Gherkin scenario update-10; the one test that runs on every platform (a_dry_run_takes_the_check_and_an_apply_takes_the_plan) only proves the dry_run boolean selects the right position, using injected fakes, not that the right concrete functions fill those positions. This is honestly self-documented in both files' comments. Two reasonable paths: accept the current test-based guard (cheap, already covers the platforms CI builds end-to-end for this flow), or thread a PythonAccess-style enum/newtype through a single planner so the transposition becomes a compile error rather than a tested-for property. Worth confirming which was the deliberate choice.

Positive signals

  • PythonAccess { MayPrepare, SearchOnly } as a two-variant enum rather than a bare boolean is self-documenting at every call site and forces exhaustive handling in the resolver's match.
  • The regression tests' "control" pattern — asserting both the user-visible claim and that the stand-in uv was actually reachable by also exercising the code path that legitimately should call it — rules out the false-negative "the fixture is broken, not the code" failure mode, and is applied consistently across the new unit test and both new Gherkin scenarios.
  • RestoredEnv (apps/rocm/src/therock/test_support.rs) is a correctly-implemented RAII save/restore for process-wide environment variables used under the shared test lock; every current call site holds the lock for at least as long as it holds the guard, and restoration survives early return and panic.

Deployment notes

rocm update's plain-text report (and the --apply --dry-run preview) gains a new python_note: line when the runtime records no usable Python. The --json output shape is unchanged. Anything downstream that scrapes the text output verbatim (rather than parsing --json) should expect the new line.

What this covered

Every file in the change, read completely: apps/rocm/src/therock.rs, apps/rocm/src/therock/python.rs, apps/rocm/src/therock/update.rs, apps/rocm/src/therock/test_support.rs, apps/rocm/src/update_cmd.rs, crates/rocm-dash-tui/src/agent/tools.rs, docs/architecture.md, docs/manual-testing.md, docs/testing.md, tests/e2e-cucumber/features/update.feature, tests/e2e-cucumber/tests/e2e/therock_steps.rs, plus the callers/callees each touches (update_cmd.rs's dispatch, fake-uv.rs, runtime_setup.feature, docs/llm-tool-use.md). Reviewed as four independent blind workers grouped by coupling (core planner logic; CLI wiring + test support; e2e tests; docs + tool-comment consistency), consolidated and design-reviewed against this repo's AGENTS.md guardrails (subprocess/FFI rules, shared-component reuse, architecture-doc coverage, module-size limits — none violated or newly triggered).
b48c4ae8…cf785f1f.

CI at this exact head commit: all 29 reported checks completed, all green (build-and-test, Windows build/test, E2E consolidated report, clippy, CodeQL, coverage, commit-signatures, etc.); two jobs (Sphinx docs build, Skill checks (skillscope)) report skipped, taken at face value as not applicable to this diff.
Ticket ROCMAI-872 retrieved by identifier from Jira: its description and scope match the PR's own description closely (search-only check, report-not-prepare, byte-identical apply behaviour, message-paired-with-file-state regression test/scenario) — no mismatch found.

Did not run: history pass (no full git log/blame walk of the modified regions beyond base/head line-count comparison) and prior-changes pass (whether earlier review comments on these files still apply) — both skipped; this PR's own review thread was seen only incidentally while performing the mandatory pre-publish duplicate-review check, was not read for its content beyond that, and was not used to source or shape any finding above, so treat this report as not reconciled against that thread. Could not execute cargo build/test/clippy locally (the working clone has no checked-out working tree, by design, to avoid materializing untrusted PR content); all findings above are from static tracing of the diff and surrounding code, not from a run.


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

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 cf785f1fb6c

Outcome: no blocking findings. Implements ROCMAI-872 in full (reusing the search-only entry point from #906 to make rocm update's check/report/startup-check/--apply --dry-run paths prepare no Python, while rocm update --apply keeps preparing one as before). Nine independent blind passes (core logic in python.rs/update.rs/update_cmd.rs/therock.rs, test infra + tool-doc comment, docs cross-consistency, e2e Cucumber tests, AGENTS.md adherence, git-history/prior-PR precedent, and a dedicated comment-accuracy audit) turned up no correctness defects. CI is fully green at this head (29 checks).

Non-blocking

  • apps/rocm/src/therock/update.rs:7-8 (module doc) says runtime_update_check is what the startup check uses, but build_startup_update_check_record (same file, ~line 651) never calls that function — it calls resolve_latest_for_manifest(..., PythonAccess::SearchOnly) directly. Same semantics, but the comment names the wrong caller. Fix: reword to say the startup check resolves the same way directly with PythonAccess::SearchOnly, rather than crediting runtime_update_check itself.

Decisions for the author

  • answered-by-intent: the PR text itself says "no test on Windows pins that pairing" for which function is the check vs. the plan — confirmed true (the only cross-platform test uses fake stub closures, not the real search-only logic; the real behavior is pinned only by a #[cfg(unix)] test and a @requires-os:linux scenario). Worth noting PR #906 solved the analogous gap for the install-preview decision with an injected-environment test needing no real executables, which looks reusable here — but this is explicitly disclosed, not a silent gap.
  • tradeoff: apply_runtime_update_with's check/apply_plan closures share one type, so a future transposition would compile silently. Disclosed in-code; a PythonAccess-tagged signature would make it a type error instead of a tested property.
  • non-blocking-improvement: PlannedPython::note() and the new update_note() duplicate the same format-string scaffolding; a shared helper parameterized by wording would reduce the surface kept in sync by hand.

Positive signals: every new/edited comment's factual claims (named tests, platform gating, "never does X") were traced against real code/CI and checked out true; every new python_note/update_note assertion is paired with a filesystem-state assertion plus a "control" proving the fixture can detect the bug; RuntimeUpdatePlan.python_note was deliberately kept out of the dashboard JSON contract.

Covered: full diff (11 files) read completely across 9 blind fan-out passes plus targeted impact-analysis searches; no compiler/test run available in the review sandbox, so verification relied on tracing plus the PR's own green CI run.

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

@jussielo-amd
jussielo-amd added this pull request to the merge queue Nov 9, 2026
Merged via the queue into main with commit 227968d Nov 9, 2026
30 checks passed
@jussielo-amd
jussielo-amd deleted the fix-update-check-prepares-no-python branch November 9, 2026 17:58
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