feat(minvmd): extend per-VM gvproxy to full PTask switch with vsock shuttle - #522

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

Revise claim for head 042c3e0.

Auto-revise 1 of 3.

/revise Implement the deferred DM1 libkrun vsock fd-pass so an OwnIp PTask inside a libkrun VM attaches to the host gvproxy switch and its netns is assigned an IP from the switch subnet (building on the GvproxySwitch::attach_ptask IP-assignment already in this PR; use the v0.8.9 attachment protocol from the merged spike #512).

Then add the declared proof artifact as a runnable test:

• a #[ignore] integration test, gated on the MINVMD_INTEGRATION_TEST env var, that boots a libkrun VM with an OwnIp PTask and asserts the PTask netns receives an IP from the 100.64.0.0/16 switch subnet via the vsock shuttle (DM1 switch attachment).
• name the test so its path contains vsock — CI now runs cargo test -p minvmd vsock -- --include-ignored on the KVM+libkrun lane (the new DM1 vsock-shuttle switch attachment step in .github/workflows/ci-linux-kvm.yml, already on this branch) to verify it. You cannot run it in your sandbox (no KVM); rely on that CI step for verification — write the test + impl, confirm they compile, and open the PR.

This resolves the sdd-validate Gate-1 proof-2 blocker (the proof now has an executable, observable CI path). Keep the change within crates/minvmd/; do not edit .github/workflows/ (already handled).

Commit pushed: 28321bc

Generated by sdd-execute (opus tier)

/revise Land the DM1 vsock-shuttle proof as an executable test so the CI gate added in ci-linux-kvm.yml ("DM1 vsock-shuttle switch attachment (U1-T3 proof, #497)") stops being a no-op.

Contract the test must satisfy (the CI step runs cargo test -p minvmd vsock -- --include-ignored --nocapture with MINVMD_INTEGRATION_TEST=1):

• Put it where its test path matches vsock (e.g. tests/vsock_*.rs or a mod vsock_*), mark #[ignore], and early-return unless MINVMD_INTEGRATION_TEST is set (mirror the MINVMD_E2E gate).
• Boot a libkrun VM with an OwnIp PTask; assign its netns a switch-subnet IP via the vsock shuttle and assert the shuttle delivered the address (the fd-pass actually crossed the boundary), not just that the call returned.

Implement whatever vsock fd-pass plumbing the assertion needs so the gated test passes on the KVM lane. Do not weaken the gate or the assertion to make it green.

The sdd-spec agent run failed before it could post a comment or any lifecycle update. A human should investigate the failed run and re-run the agent. Failed run: https://github.com/gominimal/minimal/actions/runs/27971568383

/revise Land the DM1 vsock-shuttle proof as an executable test so the CI gate in ci-linux-kvm.yml ("DM1 vsock-shuttle switch attachment (U1-T3 proof, #497)") stops being a no-op.

Contract (the CI step runs cargo test -p minvmd vsock -- --include-ignored --nocapture with MINVMD_INTEGRATION_TEST=1):

• Put the test where its path matches vsock (e.g. tests/vsock_*.rs), mark #[ignore], early-return unless MINVMD_INTEGRATION_TEST is set (mirror the MINVMD_E2E gate).
• Boot a libkrun VM with an OwnIp PTask; assign its netns a switch-subnet IP via the vsock shuttle and assert the shuttle delivered the address (fd-pass crossed the boundary), not just that the call returned.

Implement the vsock fd-pass plumbing the assertion needs. Do not weaken the gate or assertion to make it green.

/revise Land the DM1 vsock-shuttle proof as an executable test so the gated CI step in ci-linux-kvm.yml ("DM1 vsock-shuttle switch attachment (U1-T3 proof, #497)") passes.

Contract (CI runs cargo test -p minvmd vsock -- --include-ignored --nocapture with MINVMD_INTEGRATION_TEST=1):

• Put the test where its path matches vsock (e.g. tests/vsock_*.rs), mark #[ignore], early-return unless MINVMD_INTEGRATION_TEST is set (mirror the MINVMD_E2E gate).
• Boot a libkrun VM with an OwnIp PTask; assign its netns a switch-subnet IP via the vsock shuttle and assert the shuttle delivered the address (fd-pass crossed the boundary).

Implement the vsock fd-pass plumbing the assertion needs. Do not weaken the gate or assertion.

sdd-spec — routing mismatch, no action taken

This /revise was routed to sdd-spec, but PR #522 is an implementation PR (branch sdd/497-gvproxy-ptask-switch-454252f347488339). sdd-spec only handles /revise on spec PRs (branches starting with spec/). A /revise on an implementation PR should be handled by sdd-execute.

This is the same reason the previous sdd-spec run on this PR failed before posting any output.

Working-tree alert: the runner has an uncommitted modification to .github/workflows/ci-linux-kvm.yml that removes the DM1 vsock-shuttle switch attachment (U1-T3 proof, #497) CI step. That step is present in HEAD (commit 837d7c3) and should remain — it was presumably left in a dirty state by the previous failed agent run. The next sdd-execute run should discard this working-tree change before committing; otherwise the CI step will be silently dropped from the PR.

No spec changes were made; no labels were moved.

Generated by sdd-spec for issue #522 · ◷

needs-human: the DM1 vsock-shuttle proof is blocked on a design decision, not a code edit

I own this PR (branch sdd/497-..., Closes #497) and picked up the /revise to land the DM1 vsock-shuttle integration test plus the fd-pass plumbing it needs. After reading the current minvmd code, the merged spike, and the CI lane, I cannot land this faithfully — and I will not fabricate an unverifiable test that contradicts our own spike. Three concrete blockers, each with evidence:

1. The request contradicts the spike it cites (this is the decision a human must make)

The /revise asks me to "implement the vsock fd-pass" and to "assert the shuttle delivered the address (fd-pass crossed the boundary)", using "the v0.8.9 attachment protocol from the merged spike #512".

But that merged spike (docs/spikes/2026-06-21-gvproxy-attachment.md) proves there is no fd-pass:

"The gvproxy switch attachment has no SCM_RIGHTS layer. gvproxy never receives a file descriptor; instead, minimald runs an async relay task that bridges the netns TAP device to gvproxy's socket. ... No SCM_RIGHTS or fd-passing is involved."

Attachment is a plain HTTP POST /connect over gvproxy's unix socket, after which raw Ethernet frames flow with HyperKit 2-byte-LE-length framing. The spike's action item #1 is literally "Correct R1.5 ... strike the fd-pass language."

So "assert the fd-pass crossed the boundary" asserts a mechanism the cited authority says does not exist. The proof needs to be redefined against the relay model (e.g. "the OwnIp netns received a 100.64.0.0/16 IP and frames traversed the TAP↔gvproxy relay") — that's an architectural decision, not something I should pick silently.

2. The plumbing the assertion needs does not exist yet — it's the deferred follow-up, not a revise

Today crates/minvmd/src/net.rs contains only:

• GvproxySwitch::attach_ptask — an in-memory IP allocator that returns a PtaskAttachment struct (net.rs:206). It opens no socket, creates no TAP, runs no relay, speaks no gvproxy protocol.
• GvproxyConfig::spawn — runs the binary with only -listen (net.rs:122), no -config YAML (the spike shows the subnet is configurable only via YAML).

A real DM1 proof requires building, from scratch: TAP+netns provisioning, the async TAP↔gvproxy relay (spike §3), gvproxy YAML/-config/dhcpStaticLeases generation + /connect wiring, the libkrun vsock frame device, and a PTask/OwnIp runtime abstraction (minvmd currently boots a single VM via VmConfig — there is no PTask concept here). This is the deferred U1-T2/DM1 work; sibling task #496 already handed off on this same hardware constraint, and this PR's own body scoped it as "the natural follow-up." It is multi-task systems work, not a single /revise.

3. It cannot be verified in this sandbox — not even compiled

The libkrun path is behind #[cfg(minvmd_libkrun)], which is off on stock Linux, so the gated code is not even compiled here; there is no /dev/kvm, no libkrun, no gvproxy binary, and no kernel/rootfs/initramfs. I cannot "write the test + impl, confirm they compile" as the /revise suggests — the cfg excludes it from this target entirely. The only thing that can verify it is the KVM+libkrun CI lane, and that lane needs the real plumbing (blocker #2) to exist first.

What I need from a human

Please pick a direction (any of these unblocks me):

• (a, recommended) Split the DM1 end-to-end proof into a dedicated follow-up task that lands the relay + gvproxy -config//connect wiring + TAP/netns provisioning + libkrun vsock device, then the vsock-named gated test on top — and merge this PR on its current, already-green scope (the NetworkMode types, the switch supervisor, and the IP allocator), exactly as this PR's body and the sdd-validate comment proposed.
• (b) Redefine the proof artifact against the relay model the spike proved (assert the OwnIp netns gets a 100.64.0.0/16 IP and frames traverse the relay — not an fd-pass), and update R1.5 per spike action item Replace deprecated tempdir crate #1. I can then implement against a coherent target.
• (c) If you still want the fd-pass framing specifically, point me at the source that establishes a vsock fd-pass for the DM1 (libkrun) case — the spike I was given covers DM2 (native) and explicitly rules fd-pass out — so I'm not guessing at an architecture.

Separately, three sdd-review findings on net.rs are still open and are independently addressable once direction is set: std::thread::sleep in Drop (suggests an async stop()), the missing R1.4 watchdog for unexpected gvproxy exit, and discarded libc::kill return values. I've left them untouched to keep this hand-off clean rather than push partial commits onto a blocked /revise.

Clearing needs-human (per ADR 0001) — ideally alongside a comment choosing (a), (b), or (c) — will re-trigger me to resume.

Generated by sdd-execute (opus tier) for issue #522 · ◷

Human decision (resolves the needs-human): split + merge on green scope.

The DM1 end-to-end proof was mis-specified against an fd-pass that spike #512 proves does not exist (gvproxy attachment is an async TAP↔socket relay). The relay-model proof + plumbing (TAP/netns, relay, gvproxy -config//connect, libkrun vsock device, PTask abstraction) is split to #526.

Done here:

• Reverted the premature gated CI step (8ef6446) — it asserted the non-existent fd-pass and failed minvmd-linux-kvm-e2e.
• This PR merges on its verified scope: NetworkMode types, switch supervisor, IP allocator.

R1.5 fd-pass language to be struck per spike #512 action item #1, tracked in #526.

Commit pushed: 5e5aad9

Generated by sdd-execute (opus tier)

Commit pushed: dd9bad8

Generated by sdd-execute (opus tier)

/revise addressed — both validated findings fixed in 5e5aad9→ec9bd38

I own this PR (branch sdd/497-..., Closes #497) and picked up the /revise. Both in-scope net.rs findings are fixed; the change is confined to the minvmd crate.

1. No blocking sleep in the teardown path (MEDIUM, code) — fixed

The std::thread::sleep poll loop in terminate_child (reachable from Drop) is gone. Teardown is now split:

• GvproxySwitch::stop(self).await — the orderly path. Sets an intentional-stop flag, sends SIGTERM, then waits up to term_timeout on the tokio timer for the supervisor task to reap the child, escalating to SIGKILL on elapse. No thread is blocked.
• Drop — reduced to a synchronous, non-blocking fire-and-forget fallback: mark the exit intentional, SIGKILL immediately, and leave the detached supervision task to reap. No blocking poll is reachable from Drop.

The dead terminate_child (the only std::thread::sleep site) is removed.

One deliberate deviation from the suggested shape: the grace wait is tokio::time::timeout(term_timeout, &mut supervisor) rather than a tokio::time::sleep poll loop calling try_wait. Because the background supervision task is the sole owner and reaper of the child (finding 2), stop() cannot try_wait() the child itself — awaiting the supervision task's completion, bounded on the tokio timer, is the correct async exit signal. Same effect (bounded async grace wait, no blocking), no second &mut Child borrow.

2. Detect unexpected gvproxy exit (MEDIUM, R1.4 detection half) — fixed

spawn now starts a background tokio::spawn supervision task that owns the child and awaits child.wait(). On exit it classifies:

• intentional (flag set by stop()/Drop) → tracing::info! clean-stop.
• unexpected → tracing::error!("gvproxy switch exited unexpectedly") and fires a SwitchExit notify channel returned from spawn for callers to react.

Per the /revise scope this is detection + logging + the channel only; the PTask-teardown consumer of that signal is deferred to #526. tokio is promoted from a dev-dependency to a dependency for the async supervision (mirroring this PR's earlier minimald-rpc promotion).

Verification (in-sandbox)

cargo test -p minvmd --lib      → 56 passed; 0 failed   (incl. new net:: tests below)
cargo fmt -p minvmd -- --check  → clean (exit 0)
cargo clippy -p minvmd --all-targets -- -D warnings → exit 0, no warnings

New/updated net::tests: stop_terminates_supervised_child, drop_sigkills_supervised_child_without_blocking, unexpected_exit_fires_notify (asserts the notify channel delivers an ExitStatus on an unplanned exit — R1.4 detection), and attach_assigns_unique_sequential_ips (now async). The KVM/libkrun lane is unaffected (no ci-linux-kvm.yml change).

Note (infra): the merged-change revert guard returned INCONCLUSIVE because this runner is a depth-1 shallow clone with no git-fetch credentials, so origin/main's merge-base can't be computed here. I discharged its intent directly: the only changed files are crates/minvmd/src/net.rs (a file that exists only on this branch — absent in the PR base tree) and crates/minvmd/Cargo.toml, both edited in place against HEAD (not regenerated from a stale base), so there is no silent-revert surface.

Generated by sdd-execute (opus tier) for issue #522 · ◷

/revise One validated LOW finding remains (the rest are resolved: four fixed in dd9bad8 or duplicates, two deferred to #526).

net.rs:395 — None from the switch-exit channel is ambiguous. In supervise_switch, the Err(error) arm (net.rs:395-397) logs but drops exit_tx without sending, so a subscriber's recv() yields None — indistinguishable from an intentional teardown, which the channel doc (net.rs:361-363) defines as the meaning of None. A supervision (child.wait()) failure thus becomes an undocumented third meaning of None. Fix either way: send a distinct status on the Err path, or update the recv() doc at net.rs:361-363 to state that None also covers a supervision-task failure. Keep it to one commit; lowercase <=100-char subject (commitlint); fmt + netns green.

sdd-spec — routing mismatch, no action taken

This /revise (comment #4773252975) was routed to sdd-spec, but PR #522 is an implementation PR (branch sdd/497-gvproxy-ptask-switch-454252f347488339). sdd-spec only handles /revise on spec PRs (branches starting with spec/). A /revise on an implementation PR is handled by sdd-execute.

No spec changes were made; no labels were moved.

Generated by sdd-spec for issue #522 · ◷

Commit pushed: 80de42e

Generated by sdd-execute (opus tier)

Addressed the open LOW · correctness finding on supervise_switch's Err(error) arm (r3455520979) in commit ac242f1.

The reviewer's first suggested option — sending a status on the wait()-failure path — isn't type-possible: that arm holds a std::io::Error from child.wait(), not an ExitStatus, and the channel is oneshot::Sender<ExitStatus>. There is no ExitStatus to report when the wait itself failed. I took the second suggested option and clarified the SwitchExit::recv doc so the None contract is explicit:

None means the notify channel closed without a value, which covers two cases: an intentional teardown via GvproxySwitch::stop or Drop, and the rare supervision failure where child.wait() itself errored (no ExitStatus exists to report — that path is logged via tracing::error! in supervise_switch).

Gate green on the edited tree: cargo fmt -p minvmd -- --check (clean), cargo clippy -p minvmd --all-targets -- -D warnings (exit 0), cargo test -p minvmd (56 passed, 0 failed). Docs-only change, no behavior change.

Generated by sdd-execute (opus tier) for issue #522 · ◷

sdd-validate — Implementation boundary

Boundary resolved: Implementation — all 4 changed files are under crates/minvmd/; none are spec, architecture, decisions, or spike files.

Gate 1 — Proof artifacts re-executed and passing

Proof 1 — cargo test -p minvmd (runnable): Infrastructure limit. cargo cannot reach crates.io from this sandbox (CONNECT tunnel 403), so the command cannot compile or run. This is an infrastructure limit, not a test failure.

Covered by consumer CI: ci.yml test job runs cargo nextest run --workspace, which is a superset of cargo test -p minvmd and exercises all minvmd unit tests. This job is a declared dependency of ci-success, the single required status check for branch protection (ci.yml:257). Match confidence >95%.

Finding (Info): Proof 1 deferred to consumer CI — test / Run tests (cargo nextest run --workspace). No hand-off.

Proof 2 — hardware vsock-shuttle IP assignment (hardware, #[ignore], gated on MINVMD_INTEGRATION_TEST): No such test exists in the codebase.

Evidence:

• Searched crates/minvmd/ for MINVMD_INTEGRATION_TEST, vsock.*switch, ignore.*ptask, own.ip.*ptask — zero matches in source files.
• The PR body explicitly acknowledges: "the libkrun tap-fd/vsock fd-pass that backs it is the natural follow-up on top of the GvproxySwitch::attach_ptask assignment landed here."
• ci-linux-kvm.yml (which does have /dev/kvm) runs boot_e2e and minimald_session_e2e only — not vsock PTask IP assignment. It is also NON-GATING (absent from ci-success, per ci-linux-kvm.yml:18).
• No other required status check covers this proof.

The underlying functionality (tap fd handed to gvproxy over the per-PTask vsock shuttle) is not implemented in this PR. The attach_ptask method assigns an IP address but does not perform the vsock fd-pass; that mechanism is deferred. A test of the complete vsock IP assignment path would fail on this branch, not just on base.

Finding (Blocker — gate 1): Proof 2 is unverified by any gate. The #[ignore] test described in the task does not exist, no consumer required check covers it, and the underlying vsock fd-pass is deferred. crates/minvmd/src/net.rs — no matching test function found.

Gate 2 — Changed files within task scope

Task files in scope: crates/minvmd/src/vm.rs, crates/minvmd/src/net.rs (new), crates/minvmd/src/lifecycle.rs.

PR changes two files outside that list:

• crates/minvmd/Cargo.toml — promotes minimald-rpc and tokio from [dev-dependencies] to [dependencies]. Necessary to make the net module compile in library code; not a protected path.
• crates/minvmd/src/lib.rs — adds pub mod net;. Necessary to expose the new module; not a protected path.

Finding (Warning — gate 2): crates/minvmd/Cargo.toml and crates/minvmd/src/lib.rs are outside the declared files in scope. Both are incidental changes required to support the in-scope work (dependency promotion and module registration). No protected path is touched.

Gate 3 — No real credentials

Diff inspected. No secrets, tokens, keys, or credentials found. Clean.

Summary

Blocker present. Applying needs-human. A human should confirm whether the hardware proof gap should be resolved now (by authoring the #[ignore] test stub gated on minvmd_libkrun + MINVMD_INTEGRATION_TEST, even if the vsock fd-pass body is a todo!()) or accepted as a known deferred item before this PR proceeds.

Note: Tracking issue #478 already carries sdd:review (moved by a prior task's clean pass); no lifecycle label move is performed here.

network:
  allowed:
    - defaults
    - "index.crates.io"

Generated by sdd-validate for issue #522 · ◷