Skip to content

fix(minimal): stop a wedged VM from the host when min stop --force cannot reach the guest - #2156

Merged
norrietaylor merged 6 commits into
mainfrom
inbox-patch/wedged-vm-host-stop-d487b4c3bc704bcb
Oct 10, 2026
Merged

norrietaylor merged 6 commits into
mainfrom
inbox-patch/wedged-vm-host-stop-d487b4c3bc704bcb

Conversation

@gominimal-aw-bot

@gominimal-aw-bot gominimal-aw-bot Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Routing-Key: inbox-route/I_kwDOSUhdos8AAAABWPGkqg

min stop stopped the daemon only through the in-guest one, so a wedged
guest failed the connect or Shutdown RPC and left the VM running. minvmd
already had a host-side stop that needs no guest; the CLI never used it.

minvmd now exposes it as stop_at(provider_dir), and on a VM backend
min stop --force falls back to it when the connect or the Shutdown RPC
fails and the daemon cannot be confirmed down. stop_at reports whether
the guest acknowledged Shutdown; only when it did not does the CLI print
the caveat on stderr (sessions killed without their stop path, unflushed
data can be lost, journal keeps metadata consistent). The stop then waits
for minvmd to release the alive lock, so an immediate min start cannot
race it. Without --force the failure exits 7 (host unreachable) and
names the recovery; a native minimald is unchanged. The
VM-backend gate keys on the provider kind, not the flag alone (flagless
macOS is minvmd-backed), and the guest bridge socket is now resolved from
the state dir being stopped, never minvmd's process-global provider dir.

Verification

  • cargo fmt --all --check --manifest-path Cargo.toml — clean
  • cargo clippy --workspace --all-targets --locked --manifest-path Cargo.toml -- -D warnings — clean
  • cargo test --locked --manifest-path Cargo.toml -p minvmd -p minimal — new
    tests stop_at_signals_vmm_and_stops (minvmd) and
    stop_force_stops_a_wedged_vm_from_the_host /
    stop_without_force_on_a_wedged_vm_names_the_recovery (minimal) pass; the
    few remaining failures reproduce identically on stock main and are
    unrelated to this change.
  • live-session: test-kvm

Summary by CodeRabbit

  • Bug Fixes
    • Improved stopping virtual machines when their daemon is unreachable. With --force, the VM can now be stopped from the host; without it, the error explains how to recover.
    • If a forced stop cannot confirm the guest has shut down, the error warns that its volume may need to replay its journal on the next boot.
    • Native daemon shutdown behavior is unchanged.

cannot reach the guest

cmd_stop only stopped the daemon through the in-guest one, so a wedged
guest (stuck vsock, OOM) failed the connect or Shutdown RPC and left
the VM running, with no recovery short of killing the VMM by hand.

minvmd's cmd::stop already had the host-side path; expose it as
stop_at(provider_dir) and let the CLI use it: on a VM backend, a
connect or Shutdown-RPC failure the daemon cannot be confirmed down
from now falls back to stop_at on the resolved provider dir plus
wait_for_daemon_stopped, but only with --force, printing one stderr
line about the journal replay. Without --force the error keeps failing
and names the recovery. The VM-backend gate keys on the provider kind,
not the --provider flag alone (NET-081: flagless macOS is minvmd-backed).

shutdown_guest_best_effort now resolves the bridge socket from the
state dir it is given rather than minvmd's process-global provider dir,
which the CLI process never sets and which could otherwise name a
sibling VM.

Native Linux minimald is unchanged.

Co-authored-by: Copilot <223556219+Copilot@users.noreply.github.com>
@gominimal-aw-bot
gominimal-aw-bot Bot requested a review from a team as a code owner October 10, 2026 03:28
@gominimal-aw-bot gominimal-aw-bot Bot added the agent:fix Agentic fix PR eligible for review iteration; min-aw's worker-iterate gates on it. label Oct 10, 2026
@coderabbitai

coderabbitai Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Review in Change Stack →Review in Change Stack →

Warning

Review limit reached

  • Run on-demand review

This review includes 6 billable files and costs up to $1.50.

Or wait 8 minutes for your next included review.

Check out review usage here.

View limit details

Limit details: You’ve used all 3 included reviews currently available. Your 45 included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.

Learn how review limits work.

Review configuration:

⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Essentials
  • Run ID: e20443cb-481b-4ab2-af70-56c77ab1bf3b

📥 Commits

Reviewing files that changed from the base of the PR and between 23c2806 and d1b2de1.


📒 Files selected for processing (6)
  • crates/minimal-client/src/lib.rs
  • crates/minimal/src/cli.rs
  • crates/minimal/src/cmd/session.rs
  • crates/minimal/src/tests.rs
  • crates/minvmd/src/cmd/stop.rs
  • docs/reference/cli-min.md

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info
⚙️ Run configuration
  • Configuration used: Organization UI
  • Review profile: CHILL
  • Plan: Essentials
  • Run ID: 74b868d0-9c1a-4941-9313-aa5650c7efde






📥 Commits

Reviewing files that changed from the base of the PR and between 22fa1f6 and 23c2806.







📒 Files selected for processing (1)
  • crates/minimal/src/cmd/session.rs






Included review availability: This review used your included allowance. 0 included reviews remain after this review. Your included PR review attempts over the past 7 days set your current allowance at 3 reviews per hour.








📝 Walkthrough
📝 Walkthrough
📝 Walkthrough
📝 Walkthrough
📝 Walkthrough
📝 Walkthrough

Walkthrough

VM-backed stop commands can stop the VM from the host when the daemon connection or Shutdown RPC fails and --force is set. The minvmd stop flow resolves the guest socket from the selected VM’s provider directory. Tests cover forced stopping and non-forced recovery guidance.

Changes

VM Stop Recovery

Layer / File(s) Summary
Provider-scoped VM stop
crates/minvmd/src/cmd/stop.rs
Adds stop_at for a specified provider directory. Guest shutdown resolves the socket from that VM’s state directory. A test covers stopping a live child when the bridge socket does not answer.
Forced stop recovery
crates/minimal/src/cmd/session.rs, crates/minimal/src/tests.rs
For minvmd connection or Shutdown RPC failures, cmd_stop checks whether the daemon stopped. If it has not stopped, --force enables host-side stopping; otherwise, the command returns an error with recovery guidance. Tests check process termination, stopped state, and error guidance.

Priority: ⬇️ Low

Estimated code review effort: 3 (Moderate) | ~25 minutes

Change: Bug fix · Severity of issue fixed: Low

Sequence Diagram(s)

sequenceDiagram
  participant cmd_stop
  participant VM_daemon
  participant minvmd_stop_at
  participant VM_process
  participant VM_state
  cmd_stop->>VM_daemon: Connect or send Shutdown RPC
  VM_daemon-->>cmd_stop: Connection or RPC failure
  opt --force is set and daemon is not stopped
    cmd_stop->>minvmd_stop_at: Stop VM using provider directory
    minvmd_stop_at->>VM_process: Signal VMM
    minvmd_stop_at->>VM_state: Persist Stopped state
    cmd_stop->>VM_state: Wait for daemon stopped state
  end
Loading

Suggested reviewers: norrietaylor

















Merge Risk: ⚪ Minimal · up to 23c28

The forced-stop recovery is mergeable after normal checks; no actionable risk was established.

Pre-merge checks | Passed 5
✅ Passed checks (5 passed)
Check name Status Explanation
Docstring Coverage Passed Docstring coverage is 100.00% which is sufficient. The required threshold is 80.00%. Docstring coverage is scoped to functions touched by this diff. Analyzed 12 functions across 3 files.
Linked Issues check Passed Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check Passed Check skipped because no linked issues were found for this pull request.
Title check Passed The title clearly and concisely describes the main change: using host-side recovery to stop a wedged VM when the guest cannot be reached. It follows the required Conventional Commit format.
Description check Passed The description provides a clear change summary and detailed verification results. The ## Verification section covers the required testing information, but the template headings ## Summary and `##…



✨ Finishing Touches
📝 Generate docstrings
  • Commit to this branch
  • Create a new PR









🧪 Generate unit tests (beta)
  • Commit to this branch
  • Create a new PR











  • Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

A rabbit watched the daemon stall,
Then helped the host VM heed the call.
The socket found its proper place,
The process stopped at steady pace.
“With force,” said rabbit, “that’s the way!”
And bounded off to greet the day.

Comment @coderabbitai help to get the list of available commands.

@gominimal-aw-bot gominimal-aw-bot Bot added the agent:resolve Consent gate: pr-conflict-resolver may rewrite this branch label Oct 10, 2026
A VM that went down between the stop probe and the connect is the goal
state, not a wedged guest: report it as not running instead of
force-stopping it from the host, or failing without --force.
@norrietaylor norrietaylor changed the title fix: Stop a wedged VM from the host when min stop --force cannot reach the guest fix(minimal): stop a wedged VM from the host when min stop --force cannot reach the guest Oct 10, 2026
…lected VM

min stop --force no longer reports a host-side stop of a VM that is
still booting (no VMM pid to signal). The recovery hints carry --vm for
a named VM, the RPC-failure arm skips minvmd stop's second guest
Shutdown, and the stop reference and --force help describe the
host-side fallback.
… 7 on the refusal

stop_at reports whether the guest acknowledged Shutdown, and min stop
--force prints the data-loss caveat only when it did not: the journal
keeps the volume's metadata consistent, not data the guest had not
flushed, and the sessions were killed without their stop path.

The host-side stop now waits for minvmd to release the alive lock.
stop_at writes Stopped itself, so the lifecycle wait returned at once
and an immediate min start could find the lock still held.

Without --force the unanswering VM is the typed host-unreachable
failure, so the run exits 7 instead of 1.

A test pins stop_at's guest Shutdown to the passed dir's ssh.sock.
@norrietaylor

Copy link
Copy Markdown
Member

/review

@minimal-foundry

minimal-foundry Bot commented Oct 10, 2026 •

Copy link
Copy Markdown
Contributor

Approved: no findings at d1b2de1bd632.

Nothing to do.

Clobber: none: git log shows the PR is built from its own commits on main, and the changed lines in stop.rs/session.rs are the PR's own.

…e stop

min stop's Shutdown RPC used the generic 60 s deadline, so a healthy guest
still draining past it was killed from the host at about 85 s, sooner than
minvmd stop itself would signal the VMM. On a VM backend the RPC now gets
minvmd's own guest Shutdown budget.

Also: a VM that went down between the liveness probe and the host-side
stop is reported as not running rather than as still booting; a booting
VM without --force is told to retry rather than to use --force, which
refuses it; and the alive-lock timeout no longer claims a signal that may
not have been sent.

@minimal-foundry minimal-foundry Bot 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.

minimal-review — approved

Verdict APPROVE — No findings.

@minimal-foundry minimal-foundry Bot added the review:approved minimal-review approved the current head label Oct 10, 2026
@norrietaylor

Copy link
Copy Markdown
Member

/review

@minimal-foundry minimal-foundry Bot 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.

minimal-review — approved

Verdict APPROVE — No findings.

@norrietaylor
norrietaylor added this pull request to the merge queue Oct 10, 2026
Merged via the queue into main with commit 802988e Oct 10, 2026
42 of 44 checks passed
@norrietaylor
norrietaylor deleted the inbox-patch/wedged-vm-host-stop-d487b4c3bc704bcb branch October 10, 2026 09:25
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

agent:fix Agentic fix PR eligible for review iteration; min-aw's worker-iterate gates on it. agent:resolve Consent gate: pr-conflict-resolver may rewrite this branch review:approved minimal-review approved the current head

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant