[Enrique Saurez (esaurez)]

Part of #822: PR 3 of 11, replacement between the check and OpenVMM's open (C5).
The prerequisites #863 and #867 have merged. This PR is rebased onto
origin/dev at 6af32ba0 and contains only the step-hook and checked-image replacement work, with
the review and rebase fixes folded into its original commit.

What changed

• runtime-adapter-host launch takes a test-only step hook, the new runtime_adapter::hook module, from RUNTIME_ADAPTER_STEP_HOOK:
  • STEP:pause:PATH creates PATH with the step's name, then waits until the file is gone. The launch leaves the time paused out of its startup deadline, so a test can pause it for as long as it needs;
  • STEP:exit exits at once with status 5, without unwinding: the launch ends nothing that it started, and the system releases its descriptors or handles, as a crash would.
• The steps, in their order:
  • checked: after the checks of the staged bindings; the launch holds the checked files and the scratch image's claim, and has begun nothing.
  • spawned: the VMM runs, and the journal records it.
  • ready: the guest assembled the root, and the checked files are released.
  • commit: just before the commit.
• A value that names no step or action is a usage error (status 2). Without the variable, the hook does nothing. Later scenarios, such as runtime adapter: the consumer-contract scenarios C2, C3, C6 and C7 on real VMs #859's crash recovery, reuse it, and later steps of the launch can join Step.
• vm_steps.rs (new, in VMs):
  • C5: a launch paused at checked while files of zeros, which no guest could assemble or mount, try to take the image's and the scratch image's paths. On Linux they take them, and the guest still assembles the checked originals and writes nothing to the replacements. On Windows the replacements, deletions, and an open of the image for writing all fail until the guest is ready, after which the images can be renamed again.
  • A launch that the hook ends at checked, which leaves no journal, VMM log, runtime record, or launch record, and whose exit released the scratch image's claim: the next launch boots.
  • A launch paused at each step in turn. At checked, the store holds nothing of the launch, and a one-attempt ScratchBinding::check finds the scratch image claimed. At the later steps, the journal records a running VMM and no runtime record exists yet. Each launch then goes on, and is stopped.
• step_hook.rs (new, host only): the values that set the hook and those that set none, a pause, which returns how long it paused, and the host program's status 2 for a hook that it cannot read.
• tests/common: Sandbox::start, finish, start_launch, finish_launch, and paused. A Started command that a failed test left paused is killed on drop, so the sandbox's drop can take the lock and end the VM.
• The README documents the step hook, status 5, and the new tests.
• The rebased VM test uses runtime_adapter::staged::Staged, preserving the upstream module split.

Validation

Fresh Windows checks after rebasing:

• python scripts\nvx.py verify.
• Rust 1.95.0: formatting; Clippy with -D warnings, build, and tests of both protocol-only and host-only configurations (31 and 64 tests passed, respectively; the 30 hypervisor tests are intentionally ignored in the host-only gate).
• Rust 1.89: cargo check --locked --all-targets of both configurations.
• The step-hook regression tests pass (3/3), including the elapsed pause duration.
• Markdown links and runtime-adapter CI wiring tests pass.

The existing resolved review about pauses consuming the startup deadline remains
fixed: both post-spawn hooks extend the deadline by the actual pause duration.
The original author also verified 65-second pauses and the VM suites on WHP and
MSHV before this rebase; those are historical results, not fresh runs of the
rebased commit.

The fresh exact-head CI run
passed on the single folded commit a073ecfd:

• Linux and Windows quality, CLI, nvx-rs, and aci_edge_sandboxes gates.
• The guest-only configuration and guest artifacts.
• MicroVM tests and runtime-adapter scenarios on Linux/KVM, Linux/MSHV,
  and Windows/WHP.
• The required status check.

The latest automated review of a073ecfd recommends approval with no open
issues, and all review threads are resolved. Merge still requires the
repository's designated reviewer-team approval.

A supplemental, non-CI host-only adapter documentation check with
RUSTDOCFLAGS=-D warnings exposed pre-existing unresolved Runner links in
unchanged tests/runtime-adapter/src/exec.rs. These are outside this PR's
scope; the authoritative adapter gate does not run that extra command.

[Copilot]

🟡 Changes recommended

Post-spawn pauses consume the startup timeout, causing sufficiently long inspections to terminate an otherwise healthy VM on resume.

1 open issue

• Exclude pause hook time from VM startup deadline · New

What changed in this PR

This PR extends the runtime test adapter with named launch hooks and VM scenarios for checked-image replacement, building on the staged-image handoff work in #822.

Changes:

• Adds pause and immediate-exit hooks at four launch steps.
• Tests image replacement protection, claim release after exit, and launch state at each step.
• Adds asynchronous test helpers with paused-process cleanup and documents the hook contract.

File	Description
tests/​runtime-adapter/​tests/​vm_steps.rs	Adds VM tests for replacement protection and launch hooks.
tests/​runtime-adapter/​tests/​step_hook.rs	Tests hook parsing, pauses, and usage errors.
tests/​runtime-adapter/​tests/​common/​mod.rs	Adds asynchronous command helpers and cleanup.
tests/​runtime-adapter/​src/​lib.rs	Exposes and documents the host-only hook module.
tests/​runtime-adapter/​src/​hook.rs	Implements named pause and exit actions.
tests/​runtime-adapter/​src/​bin/​runtime-adapter-host.rs	Reads hook configuration and invokes launch steps.
tests/​runtime-adapter/​README.md	Documents hooks, exit status, and new scenarios.

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No blocking issues remain in the reviewed changes, and the previously reported pause-deadline issue is addressed.

No open issues 🎉

1 resolved since last review

• Exclude pause hook time from VM startup deadline

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

The test-only hooks, pause accounting, cleanup helpers, and platform-specific regression coverage have no identified blocking issues.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No blocking issues remain in the reviewed changes, and the previously reported pause-deadline issue remains fixed.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

Static review identified no blocking issues, and the previously reported startup-deadline problem remains fixed; hypervisor tests were not run during this review.

No open issues 🎉

_{Review effort: Balanced}

[Copilot]

🟢 Approval recommended

No blocking issues remain in the hook implementation, deadline handling, replacement tests, or cleanup paths.

No open issues 🎉

_{Review effort: Balanced}