e034a30e

feat(agent): macOS hosts run guests through vfkit

a73x 2026-08-06 09:12

Commit message

feat(agent): macOS hosts run guests through vfkit

A Mac in the fleet boots real Linux guests. internal/agent/vfkit is the second
reconcile.Provisioner: it drives Apple's Virtualization.framework through vfkit,
the signed helper Homebrew installs, one process per VM in its own session so
guests outlive an agent restart — the shape the cloud-hypervisor backend already
has on Linux. Guests boot under the framework's EFI bootloader with per-VM NVRAM,
so they own their kernel exactly as CLOUDHV.fd lets them elsewhere, and the root
disk is an APFS clone of the cached image grown in place. The console is the PTY
vfkit reports over its REST socket, opened raw because a PTY's defaults withhold
anything not ending in a newline — a login prompt among them.

Addressing is where the platforms genuinely differ. macOS keeps it: vmnet's NAT
and its bootpd assign a guest's address once the guest asks, so this backend has
no per-VM host networking to lifecycle and reads the lease instead. That is why
the seam polls Address rather than having Boot return it. Guests now pin their
DHCP client identifier to their MAC, on every platform: left to itself
systemd-networkd sends a DUID, and a lease filed under an identifier the fleet
never chose is a lease nothing can find — while an earlier MAC-keyed offer
lingers to be read as current, which is an address that is not missing but wrong.

vfkit is the one thing the agent cannot install for you, because it works only
carrying Apple's virtualization entitlement and an entitlement lives in a
signature — so a Mac without it refuses at preflight, naming the install, before
a create spends anything. A state directory too deep to hold a VM's control
socket is refused there too: macOS caps a unix socket path where Linux does not.

The inert platform goes with this. It existed because macOS had no backend.

Makefile

Old		New
@@ -194,11 +194,12 @@ server-image: web
194	# it, wire it into a real path, or move it into a _test.go.	194	# it, wire it into a real path, or move it into a _test.go.
195	#	195	#
196	# The analysis runs once per platform the agent ships on, because dead means	196	# The analysis runs once per platform the agent ships on, because dead means
197	# dead on ALL of them: hostinfo's Darwin parse helpers and the inert platform	197	# dead on ALL of them: hostinfo's Darwin parse helpers and the whole vfkit
198	# are unreachable on Linux, the whole cloud-hypervisor stack is unreachable on	198	# backend are unreachable on Linux, the whole cloud-hypervisor stack is
199	# Darwin, and none of it is dead. The two runs are intersected — except for	199	# unreachable on Darwin, and none of it is dead. The two runs are intersected
200	# build-tagged files, which are compiled in exactly one run and are therefore	200	# — except for build-tagged files, which are compiled in exactly one run and
201	# judged by that run alone, so dead code inside hostinfo_linux.go still fails.	201	# are therefore judged by that run alone, so dead code inside hostinfo_linux.go
		202	# still fails.
202	#	203	#
203	# `go install` into a temp GOBIN rather than `go run`: with GOOS set, `go run`	204	# `go install` into a temp GOBIN rather than `go run`: with GOOS set, `go run`
204	# would cross-compile the analyzer itself instead of the code under analysis.	205	# would cross-compile the analyzer itself instead of the code under analysis.

README.md

Old		New
@@ -2,17 +2,19 @@
2		2
3	A control plane for running virtual machines on your own hardware.	3	A control plane for running virtual machines on your own hardware.
4		4
5	eitri turns a pool of Linux hosts into a small VM cloud. You describe the guests	5	eitri turns a pool of machines into a small VM cloud. You describe the guests
6	you want; each host runs an agent that makes reality match that description and	6	you want; each host runs an agent that makes reality match that description and
7	reports back. Guests boot as real [cloud-hypervisor](https://www.cloudhypervisor.org/)	7	reports back. Guests boot as real VMs under UEFI, own their own kernel, and get
8	VMs under UEFI, own their own kernel, and get a sticky IP on a per-host bridge.	8	a sticky IP: on Linux under [cloud-hypervisor](https://www.cloudhypervisor.org/)
		9	on a per-host bridge, on macOS under Apple's Virtualization.framework via
		10	[vfkit](https://github.com/crc-org/vfkit).
9		11
10	## How it works	12	## How it works
11		13
12	eitri is built around a single desired-state loop, the same shape as a kubelet:	14	eitri is built around a single desired-state loop, the same shape as a kubelet:
13		15
14	```	16	```
15	eitri-server ──DesiredStateSnapshot──▶ eitri-agent ──▶ cloud-hypervisor guests	17	eitri-server ──DesiredStateSnapshot──▶ eitri-agent ──▶ guests (the host's VMM)
16	(control plane) (one per host)	18	(control plane) (one per host)
17	▲ │	19	▲ │
18	└──────────ActualStateReport─────────────┘ (also the heartbeat)	20	└──────────ActualStateReport─────────────┘ (also the heartbeat)
@@ -33,9 +35,10 @@ eitri is built around a single desired-state loop, the same shape as a kubelet:
33	from persisted records plus what it observes on the box.	35	from persisted records plus what it observes on the box.
34		36
35	The agent owns everything host-local: resource admission (vCPU / memory / disk /	37	The agent owns everything host-local: resource admission (vCPU / memory / disk /
36	address are admitted through one serialized gate), IP allocation (an embedded	38	address are admitted through one serialized gate), addressing (on Linux an
37	DHCP server hands each VM a sticky, deterministic address and reserves it at	39	embedded DHCP server hands each VM a sticky, deterministic address and reserves
38	create), and a content-addressed image cache (each base image is downloaded and	40	it at create; on macOS the OS's own NAT assigns it and the agent reads the
		41	lease), and a content-addressed image cache (each base image is downloaded and
39	decoded to raw once, then reflink-copied per guest).	42	decoded to raw once, then reflink-copied per guest).
40		43
41	## Components	44	## Components
@@ -43,7 +46,7 @@ decoded to raw once, then reflink-copied per guest).
43	\| Binary \| Role \|	46	\| Binary \| Role \|
44	\| --- \| --- \|	47	\| --- \| --- \|
45	\| `eitri-server` \| Control plane: HTTP API, QUIC sync stream, and the SSH-CA jump gate. \|	48	\| `eitri-server` \| Control plane: HTTP API, QUIC sync stream, and the SSH-CA jump gate. \|
46	\| `eitri-agent` \| Host agent: enrolls a host, reconciles its VMs, drives cloud-hypervisor. \|	49	\| `eitri-agent` \| Host agent: enrolls a host, reconciles its VMs, drives the host's VMM. \|
47	\| `eitri-mcp` \| MCP server exposing create/control/destroy VM tools to Claude. \|	50	\| `eitri-mcp` \| MCP server exposing create/control/destroy VM tools to Claude. \|
48	\| `eitri` \| Client CLI: signs an ephemeral cert with a tenant CA and reaches a guest through the gate. \|	51	\| `eitri` \| Client CLI: signs an ephemeral cert with a tenant CA and reaches a guest through the gate. \|
49		52
@@ -79,9 +82,10 @@ agent runs the reconcile + sync loop against the fleet. Run it under systemd
79	with `scripts/eitri-agent.service`—`Restart=on-failure` revives a crashed	82	with `scripts/eitri-agent.service`—`Restart=on-failure` revives a crashed
80	agent, and its `KillMode=process` keeps running VMs alive across agent stops.	83	agent, and its `KillMode=process` keeps running VMs alive across agent stops.
81		84
82	Guests boot from cloud images (the default is Ubuntu resolute) via UEFI firmware	85	Guests boot from cloud images (the default is Ubuntu resolute) under UEFI, so
83	(`CLOUDHV.fd`) shipped to each host, so the guest owns its kernel and any	86	the guest owns its kernel and any disk-only image boots unmodified. On Linux
84	disk-only image boots unmodified.	87	that is the `CLOUDHV.fd` firmware shipped to each host; on macOS it is the
		88	framework's own EFI bootloader, and each guest keeps its NVRAM beside its disk.
85		89
86	## Documentation	90	## Documentation
87		91
@@ -97,7 +101,7 @@ it's built this way ([decisions](docs/decisions.md)). What ships next is in
97	```	101	```
98	cmd/ entrypoints (eitri-server, eitri-agent, eitri-mcp, tooling)	102	cmd/ entrypoints (eitri-server, eitri-agent, eitri-mcp, tooling)
99	internal/	103	internal/
100	agent/ reconcile loop, cloud-hypervisor driver, DHCP, image cache, netenv	104	agent/ reconcile loop, VMM drivers (cloudhv, vfkit), DHCP, image cache, netenv
101	server/ API, QUIC sync service, SSH gate/CA, store, registry, hub	105	server/ API, QUIC sync service, SSH gate/CA, store, registry, hub
102	transport/ QUIC transport shared by both sides	106	transport/ QUIC transport shared by both sides
103	pb/ generated protobuf (proto/eitri/v1)	107	pb/ generated protobuf (proto/eitri/v1)

docs/architecture.md

docs/assumptions.md

@@ @@ -73,8 +73,9 @@ not viability. @@
+vmnet's DHCP assigns after the guest boots, and the lease is readable without
+privileges. Underpins discovering the address rather than assigning it, and
+rejecting both bootpd reservations and a userspace network stack.
+**Partly proven**: lease read-back spiked on real hardware; the vfkit
+provisioner now consumes it, keyed on the VM's deterministic MAC, but no guest
+has been reached at an address discovered this way.
+### Nobody depends on bring-your-own qcow2
+Underpins spending nothing—no download, no create slot—on a VM the host can
+never boot, and reporting the host's own reason rather than the first expensive
+step's symptom.
+**Partly proven**: pinned in reconcile's tests, and `vfkit` is the only backend
+that refuses today — a Mac with no vfkit installed. It assumes refusal is a
+static property of the host, which is why preflight is asked per create rather
+than once at start: a host whose answer can change (vfkit installed while the
+agent runs) is then re-asked rather than judged at boot.
+### A gzipped image wraps a raw one
+**Proven** for the qcow2 case. A gzipped vmdk would slip through as raw and
+fail at boot; nobody publishes one, and the fix if they do is to decompress to
+a temp file and hand it to the decoder.
+### vfkit is the helper we would have written
+Virtualization.framework is reachable only from Objective-C or Swift, so a Mac
+host needs a signed helper process between the agent and the framework. vfkit is
+that program already written — Apache-2.0, entitled, Homebrew-installed, one
+process per VM that outlives its parent. Underpins shipping a macOS backend
+without a Swift target, a signing identity, or a notarization step of our own.
+**Unverified as a dependency**: it is maintained for podman and crc, not for us,
+and its command line is the contract we build against. A breaking change there
+breaks guest creation on Macs. The escape hatch is that the surface we use is
+small — a bootloader, three device kinds and two REST calls.
+### A Mac's guests live outside the CIDR the fleet assigned it
+The server allocates every host a bridge CIDR, and macOS ignores it: vmnet owns
+its own subnet and its bootpd assigns from that. So a Mac's guests report
+addresses from a range the console never handed out.
+**DISPROVEN as harmless** 2026-08-01, on the first real guest. This was written
+claiming the divergence was harmless because nothing dials a guest from outside
+its host, so the address is only a label. It is not only a label: the control
+plane validates it. `store.RecordVMStatus` drops any reported address outside
+the owning host's `bridge_cidr` — a deliberate guard against APIPA addresses and
+agent bugs, and a silent one, because logging per tick would spam. So the whole
+chain worked and the address died at the last hop: vfkit booted the guest,
+bootpd leased it 192.168.64.7, the agent read the lease and recorded it, and the
+server discarded it. What that costs was established by experiment on
+-08-02, and it is NOT `eitri ssh`: the gate resolves a connect name to
+(hostID, vmID) and never reads the stored address (`internal/server/sshgate`),
+and the agent then dials the address in its OWN record
+(`internal/agent/syncclient`), which vfkit's `Address` does populate. What
+breaks is every consumer of the stored `assigned_ip` — the console's IP column,
+eitri-mcp's wait-for-address (`internal/mcpserver/tools.go`) and the deploy
+boot-gate (`internal/smoke/scenario.go`), and the last two HANG rather than
+fail, because both poll for a field that will never arrive. A host whose OS owns
+addressing has to tell the fleet which subnet its guests are on.
+The same day's live `eitri ssh` against the real macOS guest DID fail, with
+"cannot reach VM", and that was a separate fault now fixed in the seed: the
+guest's record held 192.168.64.7, the lease bootpd keyed on the VM's MAC, while
+the guest had come up on 192.168.64.8 under a DUID client identifier. Two
+failures, one symptom, and only the second one stopped a connection.
+**Resolved** 2026-08-02: the guard stopped asking about topology. It now asks
+only whether the value names a guest anything could reach — parses, and is not
+unspecified, loopback, link-local or multicast — which needs to know nothing
+about any host. Two halves were needed, because the guard explained a blank
+address once and the status cache is what made it permanent: `RecordVMStatus`
+returns the address it wrote, and `syncsvc` caches that rather than the value it
+sent, so a dropped address no longer suppresses every later report that would
+have corrected it. **Proven on hardware** 2026-08-03 on an M1 against a
+Mac-local control plane: `assigned_ip = 192.168.64.10`, an address no fleet
+allocation contains, accepted and stored. The Linux gate cannot show this — its
+guests sit inside their own host's `bridge_cidr` and satisfy the old guard too.
+What remains untrue is the host row itself. That same run reports the Mac's
+`bridge_cidr` as 10.102.1.0/24 while its guests live on 192.168.64.x: the fleet
+still allocates a subnet to a host whose OS already owns one. The address no
+longer dies of it, but the row asserts something false, and a host whose OS owns
+addressing should be telling the fleet which subnet its guests are on rather
+than being told.
+### Apple Silicon runs arm64 guests only
+Virtualization.framework cannot emulate a foreign architecture, so a Mac host
+needs an arm64 image where the rest of the fleet uses amd64.
+**Proven the hard way** 2026-08-03: a one-click create on an M1 took the fleet's
+single amd64 default and the guest never booted. Every symptom followed from
+that one fact — no serial output, so a blank console; no boot, so no DHCP and no
+address; then the hypervisor exited and the VM was reaped, reported as
+"ephemeral VM lost", which names neither the image nor the architecture.
+The original conclusion — leave the fleet default alone and pass an arm64 URL
+per VM — was wrong, because it made a correct create depend on the creator
+remembering. Both halves are addressed instead. `default_images` is keyed by the
+architecture of the host a VM lands on, so a one-click create takes the image
+its host can run, and an architecture with no configured image is refused at
+create naming it rather than handed something it cannot execute. And a lost
+guest now quotes whatever its hypervisor said on the way out, so the next
+failure of this shape reads as a cause rather than an absence.
+An explicit image is still not arch-checked, deliberately: a URL says nothing
+about what its contents can execute, and guessing from a filename would reject
+legitimate custom images to catch a mistake the operator made on purpose.
+### vfkit's command line is what we think it is
+The whole backend is an argv and two REST calls, built against vfkit's
+documentation rather than against a running Mac. Underpins every claim about
+how a guest boots here.
+**Proven on Linux** 2026-08-01, against vfkit's own parser: the exact argv this
+backend emits is accepted by `cmdline.AddFlags` + `config.BootloaderFromCmdLine`
++ `AddDevicesFromCmdLine` + `rest.NewEndpoint`, yields the intended machine (EFI
+bootloader with `createVariableStore`, root disk before seed, NAT'd NIC with our
+MAC, a pty serial, rng) and round-trips back to the same command line. What that
+does NOT prove is that the framework then boots it — only that vfkit will not
+reject it at the door.

docs/quickstart.md

Old		New
@@ -15,8 +15,9 @@ sign-in creates your tenant.
15		15
16	### Join a host	16	### Join a host
17		17
18	On the machine that will serve VMs (Linux, KVM—see "What you need"	18	On the machine that will serve VMs (Linux with KVM—see "What you need"
19	under Self-hosting), download and verify the host bundle:	19	under Self-hosting, or a Mac, see "Join a Mac"), download and verify the
		20	host bundle:
20		21
21	```sh	22	```sh
22	V=v0.0.1	23	V=v0.0.1
@@ -41,6 +42,38 @@ sudo systemctl enable --now eitri-agent
41	The agent dials out—a machine behind NAT needs no open ports. It goes	42	The agent dials out—a machine behind NAT needs no open ports. It goes
42	online in the console within seconds.	43	online in the console within seconds.
43		44
		45	### Join a Mac
		46
		47	A Mac joins the same way, with two differences. It runs guests through
		48	[vfkit](https://github.com/crc-org/vfkit) on Apple's Virtualization.framework,
		49	and you install that yourself:
		50
		51	```sh
		52	brew install vfkit
		53	```
		54
		55	The agent installs cloud-hypervisor on a Linux host but cannot do the same
		56	here: vfkit only works carrying Apple's virtualization entitlement, and an
		57	entitlement lives in a code signature. Homebrew's copy is signed. Without it,
		58	VMs placed on this host fail at once, saying so.
		59
		60	Take the darwin bundle instead of the linux one, run `eitri-agent join` with
		61	the blob from + Add host, then leave the agent running—there is no launchd
		62	unit in the bundle yet, so it is `sudo eitri-agent` under a supervisor of your
		63	choosing.
		64
		65	Apple Silicon runs arm64 guests only: the framework cannot emulate another
		66	architecture. Give VMs on a Mac an arm64 image—Ubuntu publishes one beside the
		67	amd64 default:
		68
		69	```
		70	https://cloud-images.ubuntu.com/resolute/current/resolute-server-cloudimg-arm64.img
		71	```
		72
		73	Guests get their addresses from macOS's own NAT rather than from the agent, so
		74	a Mac's guests sit on vmnet's subnet, not on the bridge CIDR the console shows.
		75	Everything above that—`eitri ssh`, the console, reconcile—is the same.
		76
44	### Boot a VM	77	### Boot a VM
45		78
46	Console → + Create VM, pick your host, create. Watch it boot in the	79	Console → + Create VM, pick your host, create. Watch it boot in the
@@ -88,8 +121,9 @@ your laptop. `192.0.2.10` is the server below. Substitute yours.
88		121
89	### What you need	122	### What you need
90		123
91	Every VM host needs KVM (`ls -l /dev/kvm`). Guest images are decoded in the	124	Every Linux VM host needs KVM (`ls -l /dev/kvm`); a Mac needs `brew install
92	agent, so there is no image toolchain to install. The agent fetches	125	vfkit` (see "Join a Mac"). Guest images are decoded in the
		126	agent, so there is no image toolchain to install. On Linux the agent fetches
93	cloud-hypervisor and the	127	cloud-hypervisor and the
94	guest firmware itself on first start, sha-verified against the release. To	128	guest firmware itself on first start, sha-verified against the release. To
95	manage them by hand instead, disable it in `/etc/default/eitri-agent`:	129	manage them by hand instead, disable it in `/etc/default/eitri-agent`:

docs/shape.html

Old		New
@@ -184,14 +184,6 @@
184	"imports": []	184	"imports": []
185	},	185	},
186	{	186	{
187	"importPath": "internal/agent/inert",
188	"plane": "data",
189	"synopsis": "Package inert is the platform for a host that is in the fleet but cannot run guests.",
190	"imports": [
191	"internal/agent/state"
192	]
193	},
194	{
195	"importPath": "internal/agent/ipalloc",	187	"importPath": "internal/agent/ipalloc",
196	"plane": "data",	188	"plane": "data",
197	"synopsis": "Package ipalloc allocates VM IPs within the host's bridge CIDR.",	189	"synopsis": "Package ipalloc allocates VM IPs within the host's bridge CIDR.",
@@ -277,6 +269,16 @@
277	]	269	]
278	},	270	},
279	{	271	{
		272	"importPath": "internal/agent/vfkit",
		273	"plane": "data",
		274	"synopsis": "Package vfkit manages one vfkit process per VM: the macOS backend, where vfkit is the signed helper that drives Apple's Virtualization.framework.",
		275	"imports": [
		276	"internal/agent/exec",
		277	"internal/agent/hostinfo",
		278	"internal/agent/state"
		279	]
		280	},
		281	{
280	"importPath": "internal/arch",	282	"importPath": "internal/arch",
281	"plane": "tooling",	283	"plane": "tooling",
282	"synopsis": "Package arch holds executable architecture fitness functions for the Eitri module.",	284	"synopsis": "Package arch holds executable architecture fitness functions for the Eitri module.",

docs/shape.json

Old		New
@@ -133,14 +133,6 @@
133	"imports": []	133	"imports": []
134	},	134	},
135	{	135	{
136	"importPath": "internal/agent/inert",
137	"plane": "data",
138	"synopsis": "Package inert is the platform for a host that is in the fleet but cannot run guests.",
139	"imports": [
140	"internal/agent/state"
141	]
142	},
143	{
144	"importPath": "internal/agent/ipalloc",	136	"importPath": "internal/agent/ipalloc",
145	"plane": "data",	137	"plane": "data",
146	"synopsis": "Package ipalloc allocates VM IPs within the host's bridge CIDR.",	138	"synopsis": "Package ipalloc allocates VM IPs within the host's bridge CIDR.",
@@ -226,6 +218,16 @@
226	]	218	]
227	},	219	},
228	{	220	{
		221	"importPath": "internal/agent/vfkit",
		222	"plane": "data",
		223	"synopsis": "Package vfkit manages one vfkit process per VM: the macOS backend, where vfkit is the signed helper that drives Apple's Virtualization.framework.",
		224	"imports": [
		225	"internal/agent/exec",
		226	"internal/agent/hostinfo",
		227	"internal/agent/state"
		228	]
		229	},
		230	{
229	"importPath": "internal/arch",	231	"importPath": "internal/arch",
230	"plane": "tooling",	232	"plane": "tooling",
231	"synopsis": "Package arch holds executable architecture fitness functions for the Eitri module.",	233	"synopsis": "Package arch holds executable architecture fitness functions for the Eitri module.",

internal/agent/imagecache/format.go

Old		New
@@ -45,8 +45,8 @@ func sniff(head []byte) imageFormat {
45		45
46	// permanentError marks a failure no retry can fix. reconcile matches the	46	// permanentError marks a failure no retry can fix. reconcile matches the
47	// Permanent() method structurally (errors.As against an anonymous interface),	47	// Permanent() method structurally (errors.As against an anonymous interface),
48	// so this mirrors cloudhv's and inert's markers instead of sharing one: what a	48	// so this mirrors the backends' markers instead of sharing one: what a VMM
49	// VMM driver and an image cache call permanent have nothing else in common.	49	// driver and an image cache call permanent have nothing else in common.
50	type permanentError struct{ err error }	50	type permanentError struct{ err error }
51		51
52	func (e permanentError) Error() string { return e.err.Error() }	52	func (e permanentError) Error() string { return e.err.Error() }

internal/agent/inert/inert.go

Old		New
@@ -1,89 +0,0 @@
1	// Package inert is the platform for a host that is in the fleet but cannot run
2	// guests. Every type here satisfies one of the agent's backend seams —
3	// reconcile.Provisioner and serialpump.ConsoleSource — while touching nothing
4	// on the host.
5	//
6	// Refusals are deliberate and loud. VM lifecycle calls fail with a Permanent()
7	// error so reconcile terminal-fails a misplaced VM in one attempt instead of
8	// burning its retry budget against a backend that can never succeed; a console
9	// request fails through the normal pump path rather than silently doing
10	// nothing. Address is the one exception: it answers "" rather than an error,
11	// because not knowing a guest's address is a legitimate state of the seam, not
12	// a refusal.
13	//
14	// The package is untagged so Linux CI proves its behavior, even though only
15	// wire_darwin.go builds it into a binary.
16	package inert
17
18	import (
19	"context"
20	"errors"
21	"fmt"
22	"io"
23	"runtime"
24
25	"github.com/a73x/eitri/internal/agent/state"
26	)
27
28	// The two refusals, exported so callers and tests can match them and an
29	// operator reading a failed VM sees one consistent sentence per cause.
30	var (
31	ErrNoRuntime = errors.New("no VM runtime on this host")
32	ErrNoConsole = errors.New("no guest consoles on this host")
33	)
34
35	// permanentError marks a failure no retry can fix. reconcile matches the
36	// Permanent() method structurally (errors.As against an anonymous interface),
37	// so this mirrors cloudhv's marker instead of sharing one: a shared type would
38	// be the only thing a real VMM driver and this one have in common.
39	type permanentError struct{ err error }
40
41	func (e permanentError) Error() string { return e.err.Error() }
42	func (e permanentError) Unwrap() error { return e.err }
43	func (e permanentError) Permanent() bool { return true }
44
45	// refuse wraps a cause with the host's platform, so the message an operator
46	// reads in the console says which kind of host said no.
47	func refuse(cause error) error {
48	return permanentError{err: fmt.Errorf("%w (%s/%s)", cause, runtime.GOOS, runtime.GOARCH)}
49	}
50
51	// Provisioner is the VM lifecycle on a host with no VM runtime: every call
52	// refuses, and nothing is ever running.
53	type Provisioner struct{}
54
55	// Preflight is where a VM misplaced onto this host should now fail: reconcile
56	// asks it before the image fetch, so the answer an operator reads is this
57	// host's verdict rather than whatever the create's first expensive step
58	// happened to trip over.
59	func (Provisioner) Preflight(_ context.Context) error { return refuse(ErrNoRuntime) }
60
61	func (Provisioner) PrepareRootDisk(_ context.Context, _ state.VMSpec, _ string) error {
62	return refuse(ErrNoRuntime)
63	}
64
65	func (Provisioner) Boot(_ context.Context, _ string, _ state.VMSpec) error {
66	return refuse(ErrNoRuntime)
67	}
68
69	func (Provisioner) Shutdown(_ context.Context, _ string) error { return refuse(ErrNoRuntime) }
70
71	// Destroy refuses like the rest of the lifecycle. Reconcile keeps the VM's
72	// record when Destroy fails, so a VM that somehow landed here is never
73	// hard-deleted from the fleet.
74	func (Provisioner) Destroy(_ context.Context, _ string) error { return refuse(ErrNoRuntime) }
75
76	func (Provisioner) Running(_ string) bool { return false }
77
78	// Address is empty because there are no guests to have one. Reconcile reads
79	// empty as "no answer" and leaves any recorded address alone, which is right:
80	// this platform has nothing to say either way.
81	func (Provisioner) Address(_ string) string { return "" }
82
83	// ConsoleSource is the guest console on a host with no guests. Open fails
84	// rather than handing back a stream that would never carry bytes; the pump
85	// treats that as a source that isn't up yet and backs off, which is the right
86	// shape for a host whose VM runtime isn't there.
87	type ConsoleSource struct{}
88
89	func (ConsoleSource) Open(_ string) (io.ReadWriteCloser, error) { return nil, ErrNoConsole }

internal/agent/inert/inert_test.go

Old		New
@@ -1,87 +0,0 @@
1	package inert
2
3	import (
4	"context"
5	"errors"
6	"runtime"
7	"testing"
8
9	"github.com/stretchr/testify/assert"
10	"github.com/stretchr/testify/require"
11
12	"github.com/a73x/eitri/internal/agent/reconcile"
13	"github.com/a73x/eitri/internal/agent/serialpump"
14	"github.com/a73x/eitri/internal/agent/state"
15	)
16
17	// The seams this package exists to satisfy. Asserted here rather than in the
18	// package so its production edges stay at stdlib plus state.
19	var (
20	_ reconcile.Provisioner = Provisioner{}
21	_ serialpump.ConsoleSource = ConsoleSource{}
22	)
23
24	// isPermanent matches the marker the way reconcile does — structurally, on the
25	// method, not on a shared type.
26	func isPermanent(err error) bool {
27	var p interface{ Permanent() bool }
28	return errors.As(err, &p) && p.Permanent()
29	}
30
31	// TestProvisionerRefusesEveryLifecycleCallPermanently is the contract that
32	// makes this platform safe to place a VM against by mistake: reconcile
33	// terminal-fails in one attempt instead of retrying a backend that can never
34	// succeed.
35	func TestProvisionerRefusesEveryLifecycleCallPermanently(t *testing.T) {
36	ctx := context.Background()
37	p := Provisioner{}
38	calls := map[string]error{
39	"Preflight": p.Preflight(ctx),
40	"PrepareRootDisk": p.PrepareRootDisk(ctx, state.VMSpec{}, "/base.img"),
41	"Boot": p.Boot(ctx, "vm-1", state.VMSpec{}),
42	"Shutdown": p.Shutdown(ctx, "vm-1"),
43	"Destroy": p.Destroy(ctx, "vm-1"),
44	}
45	for name, err := range calls {
46	require.Error(t, err, name)
47	assert.ErrorIs(t, err, ErrNoRuntime, name)
48	assert.True(t, isPermanent(err), "%s must be Permanent", name)
49	assert.Contains(t, err.Error(), "no VM runtime", name)
50	}
51	}
52
53	func TestProvisionerNeverReportsRunning(t *testing.T) {
54	assert.False(t, Provisioner{}.Running("vm-1"))
55	}
56
57	func TestProvisionerReportsNoAddress(t *testing.T) {
58	assert.Empty(t, Provisioner{}.Address("vm1"),
59	"a host that runs no guests knows no guest addresses")
60	}
61
62	// TestConsoleSourceFailsLoudly: a console request on this host must produce a
63	// visible error through the normal serialpump path, not a silent nothing. The
64	// error is deliberately NOT permanent — the pump's reconnect loop backs off on
65	// Open failure, which is exactly the behavior wanted for a host whose VM
66	// runtime simply isn't there.
67	func TestConsoleSourceFailsLoudly(t *testing.T) {
68	stream, err := ConsoleSource{}.Open("vm-1")
69	assert.Nil(t, stream)
70	assert.ErrorIs(t, err, ErrNoConsole)
71	assert.False(t, isPermanent(err))
72	}
73
74	// TestRefusalsNameThePlatform: an operator reading a failed VM should learn
75	// which kind of host refused it, not just that something said no.
76	func TestRefusalsNameThePlatform(t *testing.T) {
77	err := Provisioner{}.Boot(context.Background(), "vm-1", state.VMSpec{})
78	assert.Contains(t, err.Error(), runtime.GOOS)
79	assert.Contains(t, err.Error(), runtime.GOARCH)
80	}
81
82	// TestRefusalsUnwrapToTheirCause keeps the marker transparent: wrapping for
83	// the Permanent() signal must not hide the sentinel underneath it.
84	func TestRefusalsUnwrapToTheirCause(t *testing.T) {
85	err := Provisioner{}.Shutdown(context.Background(), "vm-1")
86	assert.Equal(t, ErrNoRuntime, errors.Unwrap(errors.Unwrap(err)))
87	}

internal/agent/reconcile/reconcile.go

Old		New
@@ -45,8 +45,8 @@ import (
45	)	45	)
46		46
47	// Provisioner is one VM's whole lifecycle on this host, networking included.	47	// Provisioner is one VM's whole lifecycle on this host, networking included.
48	// Implemented by the cloud-hypervisor backend (cloudhv.Provisioner) and by	48	// Implemented once per platform: cloudhv.Provisioner drives cloud-hypervisor on
49	// inert.Provisioner on a host that runs no guests.	49	// Linux, vfkit.Provisioner drives Apple's Virtualization.framework on macOS.
50	//	50	//
51	// Networking is part of this seam rather than beside it because a VM's network	51	// Networking is part of this seam rather than beside it because a VM's network
52	// attachment is not separately lifecycled from the VM: cloud-hypervisor takes	52	// attachment is not separately lifecycled from the VM: cloud-hypervisor takes

internal/agent/run/cli.go

Old		New
@@ -46,6 +46,7 @@ func hostRunner(ctx context.Context, name string, args ...string) (string, error
46	// Config carries serve's wiring, replacing a long positional list.	46	// Config carries serve's wiring, replacing a long positional list.
47	type Config struct {	47	type Config struct {
48	StateDir, CHBin, Firmware string	48	StateDir, CHBin, Firmware string
		49	VfkitBin string
49	BootstrapURL string	50	BootstrapURL string
50	TombstoneGrace, VanishGrace time.Duration	51	TombstoneGrace, VanishGrace time.Duration
51	VMTimeout time.Duration	52	VMTimeout time.Duration
@@ -92,10 +93,15 @@ func parseConfig(args []string) (Config, []string, error) {
92	fs := flag.NewFlagSet("eitri-agent", flag.ContinueOnError)	93	fs := flag.NewFlagSet("eitri-agent", flag.ContinueOnError)
93	stateDir := fs.String("state-dir", "/var/lib/eitri-agent", "agent state directory")	94	stateDir := fs.String("state-dir", "/var/lib/eitri-agent", "agent state directory")
94	// --ch-bin/--firmware/--bootstrap-url configure the cloud-hypervisor	95	// --ch-bin/--firmware/--bootstrap-url configure the cloud-hypervisor
95	// backend. They are accepted everywhere and ignored by platforms that don't	96	// backend and --vfkit-bin the macOS one. They are accepted everywhere and
96	// run it, so the agent has one flag surface on every host.	97	// ignored by platforms that don't run them, so the agent has one flag
		98	// surface on every host.
97	chBin := fs.String("ch-bin", "cloud-hypervisor", "path to cloud-hypervisor binary")	99	chBin := fs.String("ch-bin", "cloud-hypervisor", "path to cloud-hypervisor binary")
98	firmware := fs.String("firmware", "/usr/share/eitri/CLOUDHV.fd", "path to CH UEFI firmware (CLOUDHV.fd)")	100	firmware := fs.String("firmware", "/usr/share/eitri/CLOUDHV.fd", "path to CH UEFI firmware (CLOUDHV.fd)")
		101	// Bare name by default: Homebrew installs to /opt/homebrew/bin on Apple
		102	// Silicon and /usr/local/bin on Intel, so $PATH is the only answer that is
		103	// right on both.
		104	vfkitBin := fs.String("vfkit-bin", "vfkit", "path to the vfkit binary (macOS hosts)")
99	bootstrapURL := fs.String("bootstrap-url", "https://eitri.sh/dl/latest/manifest.json", "eitri.sh release manifest to fetch cloud-hypervisor/firmware from if missing at startup (empty disables bootstrap)")	105	bootstrapURL := fs.String("bootstrap-url", "https://eitri.sh/dl/latest/manifest.json", "eitri.sh release manifest to fetch cloud-hypervisor/firmware from if missing at startup (empty disables bootstrap)")
100	tombstoneGrace := fs.Duration("tombstone-grace", 5*time.Minute, "quarantine period for tombstoned VMs before destroy")	106	tombstoneGrace := fs.Duration("tombstone-grace", 5*time.Minute, "quarantine period for tombstoned VMs before destroy")
101	vanishGrace := fs.Duration("vanish-grace", time.Hour, "quarantine period for VMs that vanished without a tombstone")	107	vanishGrace := fs.Duration("vanish-grace", time.Hour, "quarantine period for VMs that vanished without a tombstone")
@@ -128,6 +134,7 @@ func parseConfig(args []string) (Config, []string, error) {
128	StateDir: *stateDir,	134	StateDir: *stateDir,
129	CHBin: *chBin,	135	CHBin: *chBin,
130	Firmware: *firmware,	136	Firmware: *firmware,
		137	VfkitBin: *vfkitBin,
131	BootstrapURL: *bootstrapURL,	138	BootstrapURL: *bootstrapURL,
132	TombstoneGrace: *tombstoneGrace,	139	TombstoneGrace: *tombstoneGrace,
133	VanishGrace: *vanishGrace,	140	VanishGrace: *vanishGrace,

internal/agent/run/wire_darwin.go

Old		New
@@ -5,36 +5,41 @@ package run
5	import (	5	import (
6	"context"	6	"context"
7		7
8	"github.com/a73x/eitri/internal/agent/inert"
9	"github.com/a73x/eitri/internal/agent/reconcile"	8	"github.com/a73x/eitri/internal/agent/reconcile"
10	"github.com/a73x/eitri/internal/agent/serialpump"	9	"github.com/a73x/eitri/internal/agent/serialpump"
11	"github.com/a73x/eitri/internal/agent/state"	10	"github.com/a73x/eitri/internal/agent/state"
		11	"github.com/a73x/eitri/internal/agent/vfkit"
12	)	12	)
13		13
14	// platformProvisioner is what this host advertises to the server at join	14	// platformProvisioner is what this host advertises to the server at join
15	// time — an opaque label the server stores and never interprets.	15	// time — an opaque label the server stores and never interprets.
16	const platformProvisioner = "inert"	16	const platformProvisioner = "vfkit"
17		17
18	// platform is this host's backend pair, mirroring wire_linux.go's contract:	18	// platform is this host's backend pair, mirroring wire_linux.go's contract:
19	// serve() is the sole consumer, wiring Prov and Pumps into the reconcile engine	19	// serve() is the sole consumer, wiring Prov and Pumps into the reconcile engine
20	// and the sync client. This host has no VM runtime, so both come from	20	// and the sync client.
21	// internal/agent/inert, which refuses the work it cannot do rather than
22	// pretending to do it.
23	type platform struct {	21	type platform struct {
24	Prov reconcile.Provisioner	22	Prov reconcile.Provisioner
25	Pumps *serialpump.Manager	23	Pumps *serialpump.Manager
26	}	24	}
27		25
28	// newPlatform builds the inert platform. bridgeCIDR is accepted (the same	26	// newPlatform builds the macOS backend: vfkit over Apple's
29	// signature as every newPlatform, so serve() doesn't need to know which	27	// Virtualization.framework, with the guest console on the PTY vfkit hands out.
30	// platform it got) but unused — the server assigns it, and nothing on this host	28	//
31	// consumes a bridge CIDR without a networking backend. There is no bootstrap	29	// It does nothing before returning, and the two things it does not do are the
32	// step either: unlike Linux, which installs cloud-hypervisor and its UEFI	30	// whole difference from Linux. There is no host networking to set up: vmnet's
33	// firmware on first run, there is no runtime binary to install for a platform	31	// NAT and its bootpd are already running, own the subnet, and hand out the
34	// that runs no guests.	32	// addresses — which is why bridgeCIDR, the CIDR the server assigned this host,
35	func newPlatform(_ context.Context, _ Config, st *state.Store, _ string) (platform, error) {	33	// is accepted for signature parity and then ignored. And there is no runtime to
36	return platform{	34	// bootstrap: cloud-hypervisor is a binary the agent can fetch and install,
37	Prov: inert.Provisioner{},	35	// while vfkit works only if it carries Apple's virtualization entitlement, and
38	Pumps: serialpump.NewManager(inert.ConsoleSource{}, st.SerialLogPath),	36	// an entitlement lives in a signature we cannot produce. So a Mac without vfkit
39	}, nil	37	// is not one the agent can fix at startup — it is one whose provisioner refuses
		38	// at Preflight, in a sentence naming the install.
		39	func newPlatform(_ context.Context, cfg Config, st *state.Store, _ string) (platform, error) {
		40	prov := vfkit.New(st, cfg.VfkitBin, hostRunner)
		41	pumps := serialpump.NewManager(vfkit.NewConsoleSource(prov.SocketPath), st.SerialLogPath)
		42	prov.Pumps = pumps
		43
		44	return platform{Prov: prov, Pumps: pumps}, nil
40	}	45	}

internal/agent/seed/seed.go

Old		New
@@ -225,9 +225,20 @@ func metaData(p Params) string {
225	}	225	}
226		226
227	// networkConfig returns a netplan v2 network-config that DHCPs on the primary	227	// networkConfig returns a netplan v2 network-config that DHCPs on the primary
228	// NIC. The address is served by the host's embedded DHCP responder from the	228	// NIC. The address is served by whichever DHCP server the host runs — the
229	// agent's per-VM reservation, so nothing about addressing is baked into the	229	// agent's own responder on Linux, macOS's bootpd under vmnet — so nothing about
230	// guest image. DNS is supplied by the DHCP server.	230	// addressing is baked into the guest image. DNS comes from the same place.
		231	//
		232	// dhcp-identifier: mac makes the guest identify itself by its hardware address
		233	// instead of the DUID systemd-networkd would otherwise invent. It is load-
		234	// bearing on macOS and free on Linux. eitri picks a VM's MAC deterministically
		235	// and that is the key everything about addressing hangs off: the agent's
		236	// responder looks up reservations by it, and on macOS it is the only handle we
		237	// have on a lease we did not grant. A guest that identifies as a DUID is a
		238	// guest whose lease is filed under a name the host never chose — bootpd records
		239	// it under the identifier, so the address becomes unfindable, and worse, an
		240	// earlier MAC-keyed offer can linger and be read as current. Linux is unharmed
		241	// because our responder keys on the packet's hardware address either way.
231	func networkConfig() string {	242	func networkConfig() string {
232	return `network:	243	return `network:
233	version: 2	244	version: 2
@@ -236,6 +247,7 @@ func networkConfig() string {
236	match:	247	match:
237	name: "en*"	248	name: "en*"
238	dhcp4: true	249	dhcp4: true
		250	dhcp-identifier: mac
239	`	251	`
240	}	252	}
241		253

internal/agent/seed/seed_test.go

@@ @@ -92,6 +92,22 @@ func TestNetworkConfigUsesDHCP(t *testing.T) { @@
+func TestNetworkConfigIdentifiesTheGuestByItsMAC(t *testing.T) {
+	got := networkConfig()
+	// Without this, systemd-networkd sends a DUID-based client identifier and
+	// the DHCP server files the lease under that instead of the hardware
+	// address. eitri chooses a VM's MAC deterministically and looks addresses
+	// up by it; on a host whose DHCP server we do not run — macOS's bootpd —
+	// that lookup is the only handle we have, and a DUID makes the live lease
+	// unfindable while an earlier MAC-keyed offer lingers to be misread as
+	// current. Observed for real: a guest held 192.168.64.8 under a DUID while
+	// its stale MAC lease still read 192.168.64.7.
+	if !strings.Contains(got, "dhcp-identifier: mac") {
+		t.Fatalf("network-config must pin the DHCP client identifier to the MAC, got:\n%s", got)
+	}
+}
+// --- C1b: seed injection-defense tests ---
+func TestBuildRejectsNewlineInHostname(t *testing.T) {

internal/agent/vfkit/console.go

@@ @@ -0,0 +1,193 @@ @@
+package vfkit
+import (
+	"context"
+	"encoding/json"
+	"fmt"
+	"io"
+	"net"
+	"net/http"
+	"os"
+	"syscall"
+	"time"
+	"golang.org/x/term"
+)
+// ConsoleSource opens a VM's guest console. It satisfies
+// serialpump.ConsoleSource; the func it wraps resolves a VM's vfkit REST
+// socket path (production: Provisioner.SocketPath).
+//
+// vfkit does not serve the serial line on a socket the way cloud-hypervisor
+// does — it allocates a PTY and reports the slave's path. So opening the
+// console is two steps rather than one: ask the running VM where its PTY is,
+// then open it. Both fail while the VM is down, and the pump's reopen loop is
+// the retry for that.
+//
+// It is a struct rather than the bare func it wraps because it has to own one
+// long-lived REST client: see newRESTClient for what a per-call one costs.
+type ConsoleSource struct {
+	sock func(vmID string) string
+	rest *http.Client
+}
+// NewConsoleSource builds a console source over sock, which resolves a VM id to
+// its vfkit REST socket path.
+func NewConsoleSource(sock func(vmID string) string) *ConsoleSource {
+	return &ConsoleSource{sock: sock, rest: newRESTClient()}
+}
+// inspectTimeout bounds the /vm/inspect call. It is short because the pump
+// calls Open inside its reconnect loop: a socket that is present but not
+// answering must fail fast enough to back off, not park the pump.
+const inspectTimeout = 3 * time.Second
+// Open returns vmID's guest console as a bidirectional stream. The PTY is
+// opened O_NOCTTY: without it, the first console the agent opens would become
+// the agent process's controlling terminal, and a guest that hung up would
+// deliver SIGHUP to the agent.
+func (s *ConsoleSource) Open(vmID string) (io.ReadWriteCloser, error) {
+	pty, err := inspectPTY(s.rest, s.sock(vmID))
+	if err != nil {
+		return nil, err
+	}
+	f, err := os.OpenFile(pty, os.O_RDWR|syscall.O_NOCTTY, 0)
+	if err != nil {
+		return nil, err
+	}
+	if err := rawMode(f); err != nil {
+		_ = f.Close()
+		return nil, fmt.Errorf("raw mode %s: %w", pty, err)
+	}
+	return f, nil
+}
+// rawMode strips the line discipline off a freshly opened PTY slave, because
+// its defaults are written for a human at a keyboard and this end of the line
+// is a log drain and a relay.
+//
+// ECHO is the destructive one: everything the guest writes arrives in the
+// slave's input queue, so with echo on the kernel feeds the guest's own boot
+// log back to it as if someone had typed it — a getty sitting at the login
+// prompt answers its own output, and the console fills with the guest's replies
+// to itself. That one is not ours to have caused and is not conditional on this
+// Open: the pair carries those defaults from the moment vfkit allocates it, so
+// the echo runs whether or not anything ever opens the slave. We clear it
+// because we hold the only descriptor that can. ICANON is ours — it withholds
+// what THIS end reads, and it withholds anything not terminated by
+// a newline, and the login prompt, the shell prompt and `Password:` are exactly
+// that, so they never reach serial.log or a live viewer. OPOST would rewrite
+// the bytes a viewer types on their way to the guest. term.MakeRaw clears all
+// three (and ISIG with them).
+//
+// A path that is not a terminal has no line discipline to configure and is left
+// alone: nothing in production hands us one — vfkit reports the pty it
+// allocated — but the check keeps the failure legible instead of turning every
+// Open against a plain file into an ioctl error.
+//
+// The descriptor is borrowed through SyscallConn rather than taken with Fd():
+// Fd() moves the file out of the runtime poller and leaves it blocking, and the
+// pump stops a console by closing it to unblock the goroutine parked in Read —
+// which only works while the poller still owns the descriptor.
+func rawMode(f *os.File) error {
+	rc, err := f.SyscallConn()
+	if err != nil {
+		return err
+	}
+	var ioctlErr error
+	if err := rc.Control(func(fd uintptr) {
+		if !term.IsTerminal(int(fd)) {
+			return
+		}
+		_, ioctlErr = term.MakeRaw(int(fd))
+	}); err != nil {
+		return err
+	}
+	return ioctlErr
+}
+// vmInspect is the part of vfkit's /vm/inspect response this package reads: a
+// device list in which each entry names its own kind. Everything else vfkit
+// reports about the VM — vcpus, memory, bootloader — is state we passed it, so
+// there is nothing to learn from reading it back.
+type vmInspect struct {
+	Devices []struct {
+		Kind    string `json:"kind"`
+		PtyName string `json:"ptyName"`
+	} `json:"devices"`
+}
+// serialKind is how vfkit spells the virtio-serial device in its JSON.
+const serialKind = "virtioserial"
+// inspectPTY asks the VM on sock where its serial PTY is.
+func inspectPTY(client *http.Client, sock string) (string, error) {
+	ctx, cancel := context.WithTimeout(withSocket(context.Background(), sock), inspectTimeout)
+	defer cancel()
+	req, err := http.NewRequestWithContext(ctx, http.MethodGet, "http://vfkit/vm/inspect", nil)
+	if err != nil {
+		return "", err
+	}
+	resp, err := client.Do(req)
+	if err != nil {
+		return "", fmt.Errorf("vfkit inspect: %w", err)
+	}
+	defer resp.Body.Close()
+	if resp.StatusCode >= 300 {
+		return "", fmt.Errorf("vfkit inspect: HTTP %d", resp.StatusCode)
+	}
+	var vm vmInspect
+	if err := json.NewDecoder(resp.Body).Decode(&vm); err != nil {
+		return "", fmt.Errorf("vfkit inspect: %w", err)
+	}
+	for _, d := range vm.Devices {
+		if d.Kind == serialKind && d.PtyName != "" {
+			return d.PtyName, nil
+		}
+	}
+	// vfkit fills ptyName in while it builds the VM, so an empty one is the
+	// normal answer for the first moments after Boot, not a broken config.
+	return "", fmt.Errorf("vfkit inspect: no serial PTY yet")
+}
+// sockKey carries the unix socket a REST request must dial, on the request's
+// context. It travels there rather than in a per-VM dialer because one client
+// serves every VM on the host, and the host in the URL — which is what the
+// connection pool keys on — is the same placeholder for all of them.
+type sockKey struct{}
+// withSocket marks ctx as belonging to the vfkit listening on sock.
+func withSocket(ctx context.Context, sock string) context.Context {
+	return context.WithValue(ctx, sockKey{}, sock)
+}
+// newRESTClient builds the one client its owner uses for every vfkit REST call
+// it will ever make. Building one per call is what this exists to stop: an
+// http.Transport with a zero IdleConnTimeout never expires an idle connection,
+// and each one holds a read goroutine, a write goroutine and a file descriptor
+// alive for as long as the process runs, with the transport itself unreachable
+// and so uncollectable. Both callers sit on retry loops — the serial pump
+// reopens the console until it succeeds, reconcile calls Shutdown every tick
+// past a stop request — so a VM that never answers leaked until the agent could
+// no longer open a file.
+//
+// Keep-alives are off, and that is what makes one client safe for every VM at
+// once: a pooled connection is keyed on the URL's host, which is the same
+// placeholder for all of them, so a connection to one VM's socket could serve
+// the next VM's inspect. Nothing is given up — a vfkit REST call is a one-shot
+// against a socket that dies with its VM, and no second request ever follows
+// close enough to reuse it.
+func newRESTClient() *http.Client {
+	return &http.Client{
+		Timeout: inspectTimeout,
+		Transport: &http.Transport{
+			DisableKeepAlives: true,
+			DialContext: func(ctx context.Context, _, _ string) (net.Conn, error) {
+				sock, _ := ctx.Value(sockKey{}).(string)
+				return (&net.Dialer{}).DialContext(ctx, "unix", sock)
+			},
+		},
+	}
+}

internal/agent/vfkit/console_pty_linux_test.go

@@ @@ -0,0 +1,184 @@ @@
+//go:build linux
+package vfkit
+import (
+	"fmt"
+	"io"
+	"net/http"
+	"os"
+	"os/exec"
+	"syscall"
+	"testing"
+	"time"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"golang.org/x/sys/unix"
+)
+// The rest of this package's console tests stand a regular file in for the PTY,
+// which is fair for what Open owes its caller — a stream at the path vfkit
+// named — and is exactly why the line discipline went unnoticed for so long: a
+// regular file has none. These tests use a real pty pair, so ECHO and ICANON
+// are in play the way they are on a Mac. Linux-only for the pty plumbing
+// (/dev/ptmx, TIOCGPTN); the behaviour under test is POSIX and identical on the
+// platform this backend ships to.
+// openPTY returns the master half of a fresh pty pair and the path of its
+// slave — the shape vfkit hands the agent: vfkit holds the master and drives
+// the guest's serial line through it, and reports the slave for us to open.
+// The master is left non-blocking so a test can assert that nothing arrived.
+func openPTY(t *testing.T) (masterFD int, slave string) {
+	t.Helper()
+	master, err := os.OpenFile("/dev/ptmx", os.O_RDWR|syscall.O_NOCTTY, 0)
+	if err != nil {
+		t.Skipf("no pty available on this host: %v", err)
+	}
+	t.Cleanup(func() { _ = master.Close() })
+	fd := int(master.Fd())
+	n, err := unix.IoctlGetInt(fd, unix.TIOCGPTN)
+	if err != nil {
+		t.Skipf("cannot number the pty: %v", err)
+	}
+	// TIOCSPTLCK takes a POINTER to the lock value, so the pointer form of the
+	// ioctl is the one that unlocks rather than returning EFAULT.
+	if err := unix.IoctlSetPointerInt(fd, unix.TIOCSPTLCK, 0); err != nil {
+		t.Skipf("cannot unlock the pty: %v", err)
+	}
+	require.NoError(t, unix.SetNonblock(fd, true))
+	return fd, fmt.Sprintf("/dev/pts/%d", n)
+}
+// openConsole opens a console over a real pty, the way the pump does: vfkit
+// reports the slave's path over its REST socket and Open takes it from there.
+func openConsole(t *testing.T) (console io.ReadWriteCloser, masterFD int) {
+	t.Helper()
+	fd, slave := openPTY(t)
+	sock := inspectServer(t, http.StatusOK,
+		`{"devices":[{"kind":"virtioserial","ptyName":"`+slave+`"}]}`)
+	rwc, err := NewConsoleSource(func(string) string { return sock }).Open("vm-1")
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = rwc.Close() })
+	return rwc, fd
+}
+// writeGuestOutput puts bytes on the master, which is what the guest writing to
+// its serial line looks like from this end.
+func writeGuestOutput(t *testing.T, fd int, s string) {
+	t.Helper()
+	_, err := unix.Write(fd, []byte(s))
+	require.NoError(t, err)
+}
+// readWithin drains fd until it holds want bytes or the wait runs out. It reads
+// the descriptor directly, non-blocking, so a discipline that withholds the
+// bytes fails the test instead of parking it.
+func readWithin(t *testing.T, fd int, want int, wait time.Duration) string {
+	t.Helper()
+	require.NoError(t, unix.SetNonblock(fd, true))
+	buf := make([]byte, 512)
+	var out []byte
+	for deadline := time.Now().Add(wait); len(out) < want && time.Now().Before(deadline); {
+		n, err := unix.Read(fd, buf)
+		if n > 0 {
+			out = append(out, buf[:n]...)
+			continue
+		}
+		if err != nil && err != unix.EAGAIN && err != unix.EINTR {
+			t.Fatalf("read: %v", err)
+		}
+		time.Sleep(5 * time.Millisecond)
+	}
+	return string(out)
+}
+// consoleFD is the descriptor behind an opened console.
+func consoleFD(t *testing.T, console io.ReadWriteCloser) int {
+	t.Helper()
+	f, ok := console.(*os.File)
+	require.True(t, ok, "the console must be a file the test can read directly")
+	return int(f.Fd())
+}
+func TestConsoleReadsGuestOutputThatHasNoNewline(t *testing.T) {
+	console, master := openConsole(t)
+	const prompt = "ubuntu login: "
+	writeGuestOutput(t, master, prompt)
+	// Under the default line discipline ICANON withholds everything up to the
+	// next newline, and a login prompt, a shell prompt and `Password:` are all
+	// exactly that — so the moments an operator most needs to see never reach
+	// serial.log or a live viewer at all.
+	assert.Equal(t, prompt, readWithin(t, consoleFD(t, console), len(prompt), 2*time.Second),
+		"the console withheld output that carries no newline")
+}
+func TestConsoleDoesNotEchoTheGuestsOutputBackAtIt(t *testing.T) {
+	_, master := openConsole(t)
+	writeGuestOutput(t, master, "Ubuntu 26.04 LTS ubuntu ttyS0\n")
+	// Everything the guest writes lands in the slave's INPUT queue, so with
+	// ECHO on the kernel types the guest's own boot log back at it: a getty at
+	// the login prompt answers itself, and the console fills with the guest
+	// replying to its own output.
+	assert.Empty(t, readWithin(t, master, 1, 200*time.Millisecond),
+		"the guest's own output was echoed back to it as console input")
+}
+func TestClosingTheConsoleUnblocksAReadInFlight(t *testing.T) {
+	console, _ := openConsole(t)
+	read := make(chan error, 1)
+	go func() {
+		buf := make([]byte, 1)
+		_, err := console.Read(buf)
+		read <- err
+	}()
+	time.Sleep(50 * time.Millisecond) // let the read park
+	require.NoError(t, console.Close())
+	// This is how the pump stops a console: it closes the stream to release
+	// the goroutine sitting in Read. That only works while the runtime poller
+	// owns the descriptor, so anything Open does to the fd has to borrow it
+	// (SyscallConn) rather than take it (Fd) — see rawMode.
+	select {
+	case <-read:
+	case <-time.After(2 * time.Second):
+		t.Fatal("closing the console left the drain goroutine parked in Read — the pump can never stop it")
+	}
+}
+// ptyChildEnv marks the re-executed half of the controlling-terminal test.
+const ptyChildEnv = "EITRI_VFKIT_PTY_CHILD"
+func TestConsoleDoesNotTakeTheAgentsControllingTerminal(t *testing.T) {
+	if os.Getenv(ptyChildEnv) == "1" {
+		openConsole(t)
+		// A process with no controlling terminal cannot open /dev/tty. If this
+		// succeeds, opening the console took one — and every subsequent guest
+		// that hangs up delivers SIGHUP to the agent, killing the fleet's
+		// connection to this host along with every VM's reconcile.
+		f, err := os.OpenFile("/dev/tty", os.O_RDWR|syscall.O_NOCTTY, 0)
+		if err == nil {
+			_ = f.Close()
+			t.Fatal("the guest console became this process's controlling terminal — Open must pass O_NOCTTY")
+		}
+		return
+	}
+	// Only a session leader with no controlling terminal can acquire one, and
+	// the test binary is neither, so the check has to run somewhere that is:
+	// Setsid makes the child exactly that. Re-executing this same test is what
+	// keeps the pty and the fake vfkit in one place.
+	cmd := exec.Command(os.Args[0], "-test.run", "^"+t.Name()+"$", "-test.v")
+	cmd.Env = append(os.Environ(), ptyChildEnv+"=1")
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
+	out, err := cmd.CombinedOutput()
+	require.NoError(t, err, string(out))
+}

internal/agent/vfkit/console_test.go

@@ @@ -0,0 +1,183 @@ @@
+package vfkit
+import (
+	"io"
+	"net"
+	"net/http"
+	"os"
+	"path/filepath"
+	"runtime"
+	"testing"
+	"time"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+)
+// inspectServer answers /vm/inspect on a unix socket with the given body and
+// status, and returns the socket path.
+func inspectServer(t *testing.T, status int, body string) string {
+	t.Helper()
+	sock := filepath.Join(t.TempDir(), "vfkit.sock")
+	ln, err := net.Listen("unix", sock)
+	require.NoError(t, err)
+	srv := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		assert.Equal(t, "/vm/inspect", r.URL.Path)
+		w.WriteHeader(status)
+		_, _ = io.WriteString(w, body)
+	})}
+	go func() { _ = srv.Serve(ln) }()
+	t.Cleanup(func() { _ = srv.Close() })
+	return sock
+}
+func TestConsoleOpensThePTYVfkitReports(t *testing.T) {
+	// A regular file stands in for the PTY slave: what Open owes its caller is
+	// a bidirectional stream at the path vfkit named, and the pty-ness of that
+	// path is the kernel's business, not this package's.
+	pty := filepath.Join(t.TempDir(), "ttys004")
+	require.NoError(t, os.WriteFile(pty, nil, 0o600))
+	sock := inspectServer(t, http.StatusOK, `{"vcpus":2,"devices":[
+		{"kind":"virtioblk","imagePath":"/disk.raw"},
+		{"kind":"virtioserial","usesPty":true,"ptyName":"`+pty+`"},
+		{"kind":"virtiorng"}]}`)
+	rwc, err := NewConsoleSource(func(string) string { return sock }).Open("vm-1")
+	require.NoError(t, err)
+	defer rwc.Close()
+	// Writable as well as readable: the console carries keystrokes back to the
+	// guest, which is why this backend asks vfkit for a pty and not a log file.
+	_, err = rwc.Write([]byte("uname -a\n"))
+	assert.NoError(t, err)
+	require.NoError(t, rwc.Close())
+	got, err := os.ReadFile(pty)
+	require.NoError(t, err)
+	assert.Equal(t, "uname -a\n", string(got))
+}
+func TestConsoleFailsWhileTheVMIsStillComingUp(t *testing.T) {
+	// vfkit fills ptyName in as it builds the VM, so a serial device with no
+	// pty yet is the normal answer in the first moments after Boot. The pump's
+	// reopen loop is the retry — Open must fail rather than hand back nothing.
+	sock := inspectServer(t, http.StatusOK, `{"devices":[{"kind":"virtioserial","usesPty":true}]}`)
+	_, err := NewConsoleSource(func(string) string { return sock }).Open("vm-1")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "no serial PTY")
+}
+func TestConsoleFailsWhenTheVMHasNoSerialDevice(t *testing.T) {
+	sock := inspectServer(t, http.StatusOK, `{"devices":[{"kind":"virtioblk"}]}`)
+	_, err := NewConsoleSource(func(string) string { return sock }).Open("vm-1")
+	assert.Error(t, err)
+}
+func TestConsoleFailsWhenVfkitIsNotListening(t *testing.T) {
+	missing := filepath.Join(t.TempDir(), "vfkit.sock")
+	// The VM is down, or was never booted. This is the pump's steady state
+	// between a Shutdown and the next Boot, so it must be an ordinary error.
+	_, err := NewConsoleSource(func(string) string { return missing }).Open("vm-1")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "vfkit inspect")
+}
+func TestConsoleFailsOnAnUnhappyVfkit(t *testing.T) {
+	sock := inspectServer(t, http.StatusInternalServerError, `{"error":"boom"}`)
+	_, err := NewConsoleSource(func(string) string { return sock }).Open("vm-1")
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "500")
+}
+func TestConsoleFailsOnAnUnreadableAnswer(t *testing.T) {
+	sock := inspectServer(t, http.StatusOK, `not json`)
+	_, err := NewConsoleSource(func(string) string { return sock }).Open("vm-1")
+	assert.Error(t, err)
+}
+func TestConsoleFailsWhenThePTYPathIsGone(t *testing.T) {
+	gone := filepath.Join(t.TempDir(), "ttys004")
+	sock := inspectServer(t, http.StatusOK,
+		`{"devices":[{"kind":"virtioserial","ptyName":"`+gone+`"}]}`)
+	_, err := NewConsoleSource(func(string) string { return sock }).Open("vm-1")
+	assert.Error(t, err)
+}
+// restCallCount is how many REST calls the leak tests make. Each leaked
+// connection costs a read goroutine and a write goroutine, so this is an order
+// of magnitude clear of the tolerance below.
+const restCallCount = 100
+// assertNoGoroutineGrowth fails if call leaves goroutines behind. It is how the
+// REST client's lifetime is pinned: one built per call never expires its idle
+// connections, and each one parks a readLoop and a writeLoop forever. The
+// tolerance is for the server side's own bookkeeping, which drains on its own
+// schedule — hence the wait rather than a single reading.
+func assertNoGoroutineGrowth(t *testing.T, call func()) {
+	t.Helper()
+	before := runtime.NumGoroutine()
+	call()
+	// Poll by hand rather than require.Eventually: the counts belong in the
+	// failure message, and testify evaluates those before the condition runs.
+	after := runtime.NumGoroutine()
+	for deadline := time.Now().Add(5 * time.Second); after >= before+10 && time.Now().Before(deadline); {
+		time.Sleep(50 * time.Millisecond)
+		after = runtime.NumGoroutine()
+	}
+	assert.Less(t, after, before+10,
+		"%d REST calls left goroutines behind: %d before, %d after", restCallCount, before, after)
+}
+func TestConsoleDoesNotLeakAConnectionPerInspect(t *testing.T) {
+	pty := filepath.Join(t.TempDir(), "ttys004")
+	require.NoError(t, os.WriteFile(pty, nil, 0o600))
+	sock := inspectServer(t, http.StatusOK,
+		`{"devices":[{"kind":"virtioserial","ptyName":"`+pty+`"}]}`)
+	s := NewConsoleSource(func(string) string { return sock })
+	// One call first, so the server's own machinery is up and the measurement
+	// covers only what the loop adds.
+	rwc, err := s.Open("vm-1")
+	require.NoError(t, err)
+	require.NoError(t, rwc.Close())
+	// Open runs inside the pump's reconnect loop, so this is not a synthetic
+	// volume: a VM whose PTY never opens is asked this many times in minutes.
+	assertNoGoroutineGrowth(t, func() {
+		for range restCallCount {
+			rwc, err := s.Open("vm-1")
+			require.NoError(t, err)
+			require.NoError(t, rwc.Close())
+		}
+	})
+}
+func TestConsoleAsksEachVMsOwnSocket(t *testing.T) {
+	pty := filepath.Join(t.TempDir(), "ttys004")
+	require.NoError(t, os.WriteFile(pty, nil, 0o600))
+	socks := map[string]string{}
+	for _, vmID := range []string{"vm-1", "vm-2"} {
+		socks[vmID] = inspectServer(t, http.StatusOK,
+			`{"devices":[{"kind":"virtioserial","ptyName":"`+pty+`"}]}`)
+	}
+	s := NewConsoleSource(func(vmID string) string { return socks[vmID] })
+	// One client serves every VM, and a connection is pooled under the URL's
+	// host — the same placeholder for all of them — so the second VM's inspect
+	// must not be able to ride the first VM's connection to the wrong socket.
+	for vmID := range socks {
+		rwc, err := s.Open(vmID)
+		require.NoError(t, err, vmID)
+		require.NoError(t, rwc.Close())
+	}
+}

internal/agent/vfkit/leases.go

@@ @@ -0,0 +1,130 @@ @@
+package vfkit
+import (
+	"net/netip"
+	"os"
+	"strconv"
+	"strings"
+	"github.com/a73x/eitri/internal/agent/state"
+)
+// Address returns the address macOS gave this VM's guest, or "" when there is
+// no answer yet.
+//
+// This backend reads addresses; it does not assign them. Under vmnet NAT the
+// host's own bootpd is the DHCP server, and it decides — there is no hook to
+// reserve an address in advance that does not require editing /etc/bootptab as
+// root and restarting a system daemon under the fleet's feet. So the address
+// does not exist until the guest has booted and asked for one, which is why
+// the seam polls Address rather than having Boot return it.
+//
+// The lease is keyed on the VM's deterministic MAC, so stickiness survives
+// anyway: the same VM asks with the same hardware address and bootpd offers it
+// the lease it already holds.
+func (p *Provisioner) Address(vmID string) string {
+	raw, err := os.ReadFile(p.leasesPath)
+	if err != nil {
+		// No lease database yet — no guest on this host has ever asked for an
+		// address. "" means "no answer", which is what reconcile reads it as.
+		return ""
+	}
+	return leaseAddress(string(raw), state.MAC(vmID))
+}
+// leaseAddress finds the address most recently leased to mac in the contents
+// of macOS's dhcpd_leases file, or "" if there is none. The file is a series
+// of brace-delimited stanzas of key=value lines:
+//
+//	{
+//		name=ubuntu
+//		ip_address=192.168.64.7
+//		hw_address=1,52:54:0:3a:9f:c1
+//		identifier=1,52:54:0:3a:9f:c1
+//		lease=0x68a1b2c3
+//	}
+//
+// The last matching stanza wins, and the honest reason is that a second one
+// should not exist. A guest asks under one hardware address, and the seed pins
+// its DHCP client identifier to that same address, so bootpd has one client to
+// file it under. Where a duplicate DOES arise the file gives no way to rank
+// them: `lease` is the epoch the lease EXPIRES at, not the moment it was
+// granted, and bootpd honours a client's requested duration — so a longer older
+// grant outlives a shorter newer one and expiry is not recency. Position is no
+// better; nothing bootpd documents fixes the write order, and the one database
+// captured on real hardware cannot settle it, because its two stanzas were
+// keyed differently (one by a DUID, one by the MAC) and only ever one of them
+// was a candidate. So: take the last, and treat two candidates as the anomaly
+// they are rather than pretending to arbitrate between them.
+func leaseAddress(leases, mac string) string {
+	want := normalizeMAC(mac)
+	if want == "" {
+		return ""
+	}
+	var ip, hw, found string
+	for _, line := range strings.Split(leases, "\n") {
+		field := strings.TrimSpace(line)
+		switch field {
+		case "{":
+			ip, hw = "", ""
+		case "}":
+			if hw == want && ip != "" {
+				found = ip
+			}
+		default:
+			key, value, ok := strings.Cut(field, "=")
+			if !ok {
+				continue
+			}
+			switch key {
+			case "ip_address":
+				ip = parseIP(value)
+			case "hw_address":
+				hw = normalizeMAC(value)
+			}
+		}
+	}
+	return found
+}
+// parseIP keeps a lease's address only if it is one. The field is written by a
+// system daemon the agent does not control, and hw_address is already checked
+// exhaustively; without the same treatment here, a stanza carrying this VM's
+// MAC and any non-empty junk becomes the VM's recorded address, and the damage
+// surfaces a layer away as a guest nothing can reach. Returns "" for anything
+// that is not an address, which the caller reads as "this stanza has none".
+func parseIP(s string) string {
+	addr, err := netip.ParseAddr(strings.TrimSpace(s))
+	if err != nil {
+		return ""
+	}
+	return addr.String()
+}
+// normalizeMAC reduces a hardware address to one comparable form, because the
+// two sides spell the same address differently: state.MAC pads every octet
+// ("52:54:00:0a:…") while bootpd writes them bare and prefixes the ARP
+// hardware type ("1,52:54:0:a:…"). Comparing the strings as written would miss
+// every lease. Returns "" for anything that is not six hex octets, so garbage
+// in the file can never match a real MAC.
+func normalizeMAC(s string) string {
+	if _, rest, ok := strings.Cut(s, ","); ok {
+		s = rest // drop bootpd's hardware-type prefix
+	}
+	octets := strings.Split(strings.TrimSpace(s), ":")
+	if len(octets) != 6 {
+		return ""
+	}
+	var b strings.Builder
+	for i, o := range octets {
+		v, err := strconv.ParseUint(o, 16, 8)
+		if err != nil {
+			return ""
+		}
+		if i > 0 {
+			b.WriteByte(':')
+		}
+		b.WriteString(strconv.FormatUint(v, 16))
+	}
+	return b.String()
+}

internal/agent/vfkit/leases_test.go

@@ @@ -0,0 +1,141 @@ @@
+package vfkit
+import (
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"testing"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	"github.com/a73x/eitri/internal/agent/state"
+)
+// lease renders one dhcpd_leases stanza in macOS's format: bootpd writes octets
+// unpadded, prefixes the ARP hardware type, and stamps the expiry epoch as hex.
+func lease(name, ip, mac string, expiry uint64) string {
+	return "{\n\tname=" + name + "\n\tip_address=" + ip + "\n\thw_address=1," + mac +
+		"\n\tidentifier=1," + mac + "\n\tlease=0x" + strconv.FormatUint(expiry, 16) + "\n}\n"
+}
+// Two expiries a day apart, so which one a test means is never in doubt.
+const (
+	older = 0x68a1b2c3
+	newer = 0x68a30443
+)
+func TestLeaseAddressFindsTheGuestByItsMAC(t *testing.T) {
+	// state.MAC pads every octet; bootpd does not. Matching the two as written
+	// would miss every lease this backend ever needs to read.
+	const padded = "52:54:00:0a:0b:0c"
+	leases := lease("other", "192.168.64.2", "52:54:0:ff:ee:dd", newer) +
+		lease("web", "192.168.64.7", "52:54:0:a:b:c", newer)
+	assert.Equal(t, "192.168.64.7", leaseAddress(leases, padded))
+}
+func TestLeaseAddressIgnoresALeaseKeyedByADUID(t *testing.T) {
+	const mac = "52:54:00:0a:0b:0c"
+	// A guest that identifies itself by a DUID gets its lease filed under one:
+	// hardware type "ff" and an opaque identifier that is not six octets. Such
+	// a stanza is not a candidate for any VM, so it can neither be returned nor
+	// displace a real match — which is the whole reason the one lease database
+	// captured on real hardware had two stanzas for one guest and still gave
+	// one unambiguous answer. The seed stops the guest asking that way at all;
+	// this is the parser's half of the same guarantee.
+	duid := "{\n\tname=web\n\tip_address=192.168.64.8" +
+		"\n\thw_address=ff,f1:f5:dd:7f:0:2:0:0:ab:11:69:49:e9:aa:ed:20:59:eb" +
+		"\n\tidentifier=ff,f1:f5:dd:7f:0:2:0:0:ab:11:69:49:e9:aa:ed:20:59:eb\n\tlease=0x6a6e5628\n}\n"
+	mine := lease("web", "192.168.64.7", "52:54:0:a:b:c", newer)
+	assert.Equal(t, "192.168.64.7", leaseAddress(duid+mine, mac))
+	assert.Equal(t, "192.168.64.7", leaseAddress(mine+duid, mac))
+	assert.Empty(t, leaseAddress(duid, mac), "a DUID lease belongs to no VM this backend knows")
+}
+func TestLeaseAddressTakesTheLastOfTwoCandidates(t *testing.T) {
+	const mac = "52:54:00:0a:0b:0c"
+	// Two stanzas keyed on one MAC should not happen — the guest asks under one
+	// address and the seed pins its client identifier to it. Nothing in the file
+	// ranks them if they do (`lease` is an expiry, not a grant time), so the
+	// rule is arbitrary and pinned here only so that changing it is deliberate.
+	leases := lease("web", "192.168.64.7", "52:54:0:a:b:c", older) +
+		lease("web", "192.168.64.9", "52:54:0:a:b:c", newer)
+	assert.Equal(t, "192.168.64.9", leaseAddress(leases, mac))
+}
+func TestLeaseAddressIsEmptyWhenTheGuestHasNotAskedYet(t *testing.T) {
+	leases := lease("other", "192.168.64.2", "52:54:0:ff:ee:dd", newer)
+	// Empty means "no answer", never "no address" — reconcile leaves any
+	// recorded address alone rather than clearing it.
+	assert.Empty(t, leaseAddress(leases, "52:54:00:0a:0b:0c"))
+}
+func TestLeaseAddressIgnoresAStanzaWithNoAddress(t *testing.T) {
+	leases := "{\n\tname=web\n\thw_address=1,52:54:0:a:b:c\n}\n"
+	assert.Empty(t, leaseAddress(leases, "52:54:00:0a:0b:0c"))
+}
+func TestLeaseAddressSurvivesAMalformedFile(t *testing.T) {
+	for name, leases := range map[string]string{
+		"empty":            "",
+		"no braces":        "ip_address=192.168.64.7\nhw_address=1,52:54:0:a:b:c\n",
+		"unterminated":     "{\n\tip_address=192.168.64.7\n\thw_address=1,52:54:0:a:b:c\n",
+		"junk hw_address":  lease("web", "192.168.64.7", "not-a-mac", newer),
+		"truncated octets": lease("web", "192.168.64.7", "52:54:0:a:b", newer),
+		// hw_address is checked exhaustively; ip_address must be too, or a
+		// stanza carrying our MAC and junk becomes the address we dial.
+		"junk ip_address":  lease("web", "not-an-address", "52:54:0:a:b:c", newer),
+		"empty ip_address": lease("web", "", "52:54:0:a:b:c", newer),
+		"ip with a port":   lease("web", "192.168.64.7:22", "52:54:0:a:b:c", newer),
+	} {
+		t.Run(name, func(t *testing.T) {
+			// The lease database is written by a system daemon we do not
+			// control; nothing in it may make the agent report a wrong address.
+			assert.Empty(t, leaseAddress(leases, "52:54:00:0a:0b:0c"))
+		})
+	}
+}
+func TestNormalizeMACRejectsAnythingThatIsNotSixOctets(t *testing.T) {
+	for _, in := range []string{"", "52:54:00", "52:54:00:0a:0b:0c:0d", "52-54-00-0a-0b-0c", "1,", "gg:54:00:0a:0b:0c"} {
+		assert.Empty(t, normalizeMAC(in), "%q must not normalise to anything a real MAC could equal", in)
+	}
+	// An octet past a byte is not a MAC either, however hex-looking it is.
+	assert.Empty(t, normalizeMAC("152:54:00:0a:0b:0c"))
+}
+func TestAddressReadsTheHostLeaseDatabase(t *testing.T) {
+	p := newTestProv(t, nil)
+	require.NoError(t, os.WriteFile(p.leasesPath,
+		[]byte(lease("web", "192.168.64.7", trimMACZeros(state.MAC("vm-1")), newer)), 0o600))
+	assert.Equal(t, "192.168.64.7", p.Address("vm-1"))
+}
+func TestAddressIsEmptyBeforeAnyGuestHasLeased(t *testing.T) {
+	p := newTestProv(t, nil)
+	p.leasesPath = filepath.Join(t.TempDir(), "never-written")
+	// A Mac that has never run a guest has no lease database at all; that is
+	// "no answer", not a failure worth reporting up the seam.
+	assert.Empty(t, p.Address("vm-1"))
+}
+// trimMACZeros rewrites a padded MAC the way bootpd would write it, so the test
+// fixture is the file's format rather than ours.
+func trimMACZeros(mac string) string {
+	octets := strings.Split(mac, ":")
+	for i, o := range octets {
+		octets[i] = strings.TrimLeft(o, "0")
+		if octets[i] == "" {
+			octets[i] = "0"
+		}
+	}
+	return strings.Join(octets, ":")
+}

internal/agent/vfkit/vfkit.go

@@ @@ -0,0 +1,500 @@ @@
+// Package vfkit manages one vfkit process per VM: the macOS backend, where
+// vfkit is the signed helper that drives Apple's Virtualization.framework.
+// It is cloudhv's opposite number and deliberately its mirror image —
+// argument assembly, a pidfile, a graceful stop over a unix socket with a
+// SIGTERM fallback — because the two backends answer the same seam and a
+// reader who knows one should recognize the other.
+//
+// vfkit rather than a helper of our own: Virtualization.framework is reachable
+// only from Objective-C or Swift, so SOMETHING has to stand between the agent
+// and the framework. vfkit is that binary already written, Apache-2.0, signed
+// with com.apple.security.virtualization, and shipped through Homebrew — and
+// it takes the shape the agent already spawns, one process per VM that outlives
+// its parent. Writing our own would buy a second thing to sign and notarize.
+//
+// The package carries no build tag, so Linux CI proves its behavior even
+// though only wire_darwin.go builds it into a binary. Nothing here is
+// Darwin-only in Go terms: the platform lives in the strings (vfkit's
+// arguments, the lease database's path), not in the syscalls.
+package vfkit
+import (
+	"bytes"
+	"context"
+	"fmt"
+	"net/http"
+	"os"
+	"os/exec"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"syscall"
+	agentexec "github.com/a73x/eitri/internal/agent/exec"
+	"github.com/a73x/eitri/internal/agent/hostinfo"
+	"github.com/a73x/eitri/internal/agent/state"
+)
+// logMode is the file mode for vfkit's diagnostic log.
+const logMode = 0o600
+// PumpHooks is the serial-console pump lifecycle the provisioner drives
+// (consumer-owned; the concrete implementation is *serialpump.Manager, wired
+// by the composition root — vfkit must not import serialpump). nil disables
+// the hooks.
+type PumpHooks interface {
+	Ensure(vmID string)
+	Stop(vmID string)
+}
+// Provisioner manages vfkit processes for all VMs on this host.
+//
+// There is no Network seam here, and its absence is the design. On Linux the
+// agent owns addressing outright — it builds the bridge, creates a tap per
+// guest and answers DHCP itself — so cloudhv needs a collaborator to do that
+// per VM. macOS keeps that machinery for itself: vmnet's NAT and its bootpd
+// hand a guest its address once the guest asks, and nothing the agent can
+// install changes the answer. So there is no per-VM host networking to
+// lifecycle, only a lease to read (see Address).
+type Provisioner struct {
+	st  *state.Store
+	bin string // vfkit binary: a path, or a bare name resolved on $PATH
+	run agentexec.Runner
+	// lookPath resolves bin for Preflight. Injected so the refusal path is
+	// testable without depending on what happens to be installed on the box
+	// running the tests.
+	lookPath func(file string) (string, error)
+	// leasesPath is macOS's DHCP lease database. Injected for the same reason.
+	leasesPath string
+	// bootID identifies the host boot a VM's process was started in. It is the
+	// same reader reconcile's own boot-ID guard uses, so the two agree by
+	// construction. Injected so a test can move the host to a later boot
+	// without rebooting the box running it.
+	bootID func() string
+	// signal delivers a signal to a pid. Injected because the branch that
+	// matters — a kill the kernel refuses — cannot otherwise be reached without
+	// depending on what the box running the tests is allowed to signal.
+	signal func(pid int, sig syscall.Signal) error
+	// rest is the one client every vfkit REST call on this host goes through.
+	// One, deliberately: see newRESTClient.
+	rest *http.Client
+	// Pumps receives serial-pump lifecycle calls at Boot/kill. nil = no-op.
+	Pumps PumpHooks
+}
+// defaultLeasesPath is where macOS's bootpd records the addresses it has
+// handed out. It is the whole of this backend's address knowledge.
+const defaultLeasesPath = "/var/db/dhcpd_leases"
+// New constructs a Provisioner. run may be nil when only pure methods
+// (buildArgs) are needed.
+func New(st *state.Store, bin string, run agentexec.Runner) *Provisioner {
+	return &Provisioner{
+		st:         st,
+		bin:        bin,
+		run:        run,
+		lookPath:   exec.LookPath,
+		leasesPath: defaultLeasesPath,
+		bootID:     hostinfo.BootID,
+		signal:     syscall.Kill,
+		rest:       newRESTClient(),
+	}
+}
+// permanentError marks a failure no retry can fix. reconcile matches the
+// Permanent() method structurally (errors.As against an anonymous interface),
+// so this mirrors cloudhv's marker rather than sharing one — a shared type
+// would be the only thing the two VMM drivers have in common.
+type permanentError struct{ err error }
+func (e permanentError) Error() string   { return e.err.Error() }
+func (e permanentError) Unwrap() error   { return e.err }
+func (e permanentError) Permanent() bool { return true }
+func permanentf(format string, args ...any) error {
+	return permanentError{err: fmt.Errorf(format, args...)}
+}
+// Preflight refuses a host that has no vfkit. The one thing this backend needs
+// beyond itself cannot be installed by the agent the way cloud-hypervisor can:
+// vfkit must carry Apple's virtualization entitlement, and an entitlement
+// survives only a signature we cannot produce, so a downloaded copy is not a
+// working copy. Homebrew's is signed; that is the install path, and naming it
+// here is the whole point of answering before the image fetch rather than
+// after it.
+//
+// The refusal is permanent because the retry budget cannot fix it: three
+// attempts against a Mac with no vfkit produce the same sentence three times.
+// Installing vfkit does not revive the failed VM — create it again.
+// It also refuses a state directory too deep to hold a VM's control socket.
+// That is a property of the host's configuration, not of any one VM, and it is
+// checked here for the same reason: the alternative is discovering it from
+// vfkit, after the image download, in a sentence about URIs.
+func (p *Provisioner) Preflight(_ context.Context) error {
+	if _, err := p.lookPath(p.bin); err != nil {
+		return permanentf("vfkit not found on this host (looked for %q): install it with `brew install vfkit` — "+
+			"the macOS backend runs guests through it, and it must be Apple-entitled, so the agent cannot install it itself", p.bin)
+	}
+	if sock := p.sockPath(strings.Repeat("0", vmIDLen)); len(sock) > maxSocketPath {
+		return permanentf("state directory is too deep for macOS: a VM's control socket would be %q, %d bytes against the %d-byte limit — "+
+			"run the agent with a shorter --state-dir", sock, len(sock), maxSocketPath)
+	}
+	return nil
+}
+const (
+	// maxSocketPath is macOS's cap on a unix socket path: sockaddr_un.sun_path
+	// is 104 bytes and the last one is the terminator. Linux allows 108, so a
+	// path that works in a test on Linux can still be refused on the platform
+	// this backend runs on — which is why it is checked rather than assumed.
+	maxSocketPath = 103
+	// vmIDLen is how long a VM id is (32 hex characters, server-minted).
+	// Preflight has to measure a VM's socket path before there is a VM, so it
+	// measures one of the right shape.
+	vmIDLen = 32
+)
+// vmFile returns a path inside the VM's directory. vfkit's per-VM artifacts
+// are named here rather than in state.Store because they are this backend's
+// business: the store holds what every backend has (the disk, the seed, the
+// serial log), and a second backend's private files do not belong in a type
+// both of them import.
+func (p *Provisioner) vmFile(vmID, name string) string {
+	return filepath.Join(p.st.VMDir(vmID), name)
+}
+func (p *Provisioner) pidPath(vmID string) string  { return p.vmFile(vmID, "vfkit.pid") }
+func (p *Provisioner) sockPath(vmID string) string { return p.vmFile(vmID, "vfkit.sock") }
+func (p *Provisioner) varStore(vmID string) string { return p.vmFile(vmID, "efi-vars.fd") }
+func (p *Provisioner) logPath(vmID string) string  { return p.vmFile(vmID, "vfkit.log") }
+// SocketPath is the VM's vfkit REST socket, exported so the composition root
+// can hand ConsoleSource the same path Boot writes.
+func (p *Provisioner) SocketPath(vmID string) string { return p.sockPath(vmID) }
+// disks returns the VM's block devices in attachment order: the root disk
+// first, then the cloud-init seed. Both files must already exist when vfkit
+// starts — it opens them while parsing its arguments, before any VM is built —
+// which they do: reconcile prepares the disk and writes the seed before Boot.
+//
+// vfkit's virtio-blk has no read-only option
+// — unlike cloud-hypervisor's — so state.Disk.ReadOnly is dropped here rather
+// than honored. Nothing rests on it: the seed is a per-VM file, and cloud-init
+// mounts it read-only from inside the guest regardless.
+func (p *Provisioner) disks(spec state.VMSpec) []state.Disk {
+	return []state.Disk{
+		{Path: p.st.DiskPath(spec.VMID)},
+		{Path: p.st.SeedPath(spec.VMID), ReadOnly: true},
+	}
+}
+// buildArgs returns the vfkit command line for spec. It is pure — createVarStore
+// is passed in rather than stat'ed here — so the whole argument contract is
+// unit-testable without a filesystem or a Mac.
+func (p *Provisioner) buildArgs(spec state.VMSpec, createVarStore bool) []string {
+	vmID := spec.VMID
+	// The EFI variable store is the guest's NVRAM, and `create` initializes a
+	// fresh one — which is why it is conditional. Ubuntu writes its boot entry
+	// there on first boot; recreating the store every launch would throw that
+	// away each time and leave the guest booting only by the removable-media
+	// fallback path. Create it exactly once, on the boot that has no store yet.
+	bootloader := "efi,variable-store=" + p.varStore(vmID)
+	if createVarStore {
+		bootloader += ",create"
+	}
+	args := []string{
+		// The REST socket is how Shutdown asks for an ACPI power-down and how
+		// the console finds its PTY. Without it vfkit exposes neither.
+		"--restful-uri", "unix://" + p.sockPath(vmID),
+		"--cpus", strconv.FormatInt(spec.VCPUs, 10),
+		"--memory", strconv.FormatInt(spec.MemMB, 10),
+		"--bootloader", bootloader,
+	}
+	for _, d := range p.disks(spec) {
+		args = append(args, "--device", "virtio-blk,path="+d.Path)
+	}
+	return append(args,
+		// nat is Apple's vmnet-shared network: the host NATs the guest out and
+		// its bootpd answers the guest's DHCP. mac is the stickiness key — it
+		// is what makes the lease, and therefore the address, the same one
+		// across a rebuild (see Address).
+		"--device", "virtio-net,nat,mac="+state.MAC(vmID),
+		// pty, not logFilePath: the console has to carry keystrokes back to the
+		// guest, and a log file is one-way. The pump opens the far end.
+		"--device", "virtio-serial,pty",
+		// cloud-hypervisor gives a guest virtio-rng without being asked; vfkit
+		// does not, and a guest short of entropy stalls in early boot.
+		"--device", "virtio-rng",
+	)
+}
+// maxDiskGB caps a VM disk at 1 PiB (2^20 GiB) — far beyond any real host,
+// and small enough that DiskGB<<30 can never overflow int64 (2^50 max).
+const maxDiskGB = 1 << 20
+// PrepareRootDisk creates the VM's root disk by cloning basePath on APFS and
+// growing it to spec.DiskGB gigabytes.
+//
+// The shrink guard is cloudhv's, restated rather than shared: truncating to an
+// EXACT size means a target below the base image would chop the guest
+// filesystem, and that is true of any backend that grows a cloned image. The
+// duplication is deliberate for now — hoisting the policy into reconcile is
+// the right fix, and is a change to the shared engine, not to this backend.
+func (p *Provisioner) PrepareRootDisk(ctx context.Context, spec state.VMSpec, basePath string) error {
+	base, err := os.Stat(basePath)
+	if err != nil {
+		return fmt.Errorf("stat base image %s: %w", basePath, err)
+	}
+	if spec.DiskGB < 1 || spec.DiskGB > maxDiskGB {
+		return permanentf("disk_gb %d out of range [1, %d]", spec.DiskGB, int64(maxDiskGB))
+	}
+	targetBytes := spec.DiskGB << 30
+	if targetBytes < base.Size() {
+		return permanentf("disk_gb %d (%d bytes) is smaller than base image %s (%d bytes) — shrinking would corrupt the guest",
+			spec.DiskGB, targetBytes, basePath, base.Size())
+	}
+	if err := os.MkdirAll(p.st.VMDir(spec.VMID), 0o700); err != nil {
+		return fmt.Errorf("mkdir %s: %w", p.st.VMDir(spec.VMID), err)
+	}
+	// Build into a sibling temp file and rename into place so a create killed
+	// mid-copy can never leave a torn disk.raw at the final path. Sibling, so
+	// the clone stays on one filesystem and the rename is atomic.
+	diskPath := p.st.DiskPath(spec.VMID)
+	tmpPath := diskPath + ".partial"
+	_ = os.Remove(tmpPath)
+	if err := p.clone(ctx, basePath, tmpPath); err != nil {
+		_ = os.Remove(tmpPath)
+		return err
+	}
+	// Grown in-process rather than by truncate(1): macOS does not ship one.
+	// os.Truncate grows sparsely, exactly as GNU truncate does on Linux.
+	if err := os.Truncate(tmpPath, targetBytes); err != nil {
+		_ = os.Remove(tmpPath)
+		return fmt.Errorf("grow %s to %dG: %w", tmpPath, spec.DiskGB, err)
+	}
+	if err := os.Rename(tmpPath, diskPath); err != nil {
+		_ = os.Remove(tmpPath)
+		return fmt.Errorf("rename %s -> %s: %w", tmpPath, diskPath, err)
+	}
+	return nil
+}
+// clone copies src to dst, sharing blocks where the filesystem can. `cp -c`
+// is APFS's clonefile — the reflink analog — but unlike `cp --reflink=auto` it
+// FAILS rather than degrading when the filesystem cannot clone, so the fallback
+// is spelled out here. A Mac's boot volume is APFS; a state directory on an
+// external HFS+ disk is the case that needs the second attempt.
+func (p *Provisioner) clone(ctx context.Context, src, dst string) error {
+	if _, err := p.run(ctx, "cp", "-c", src, dst); err == nil {
+		return nil
+	}
+	_ = os.Remove(dst) // a failed clone may have left a partial file in the way
+	if _, err := p.run(ctx, "cp", src, dst); err != nil {
+		return fmt.Errorf("cp %s %s: %w", src, dst, err)
+	}
+	return nil
+}
+// Boot spawns a vfkit process for spec. The process is placed in its own
+// session (Setsid) so it survives an agent restart, and ctx is deliberately NOT
+// wired to it: tying a guest's lifetime to the agent's would power off every VM
+// on a graceful agent stop. Stopping a VM is Shutdown/Destroy's job alone.
+func (p *Provisioner) Boot(_ context.Context, vmID string, spec state.VMSpec) error {
+	// vfkit removes its socket on a clean exit only, so a crash, a SIGKILL or a
+	// host reboot leaves one behind that the next bind would trip over.
+	_ = os.Remove(p.sockPath(vmID))
+	// Anything short of a successful stat means "initialise a store". Matching
+	// ENOENT alone read every other stat failure — EACCES on a state dir whose
+	// ownership moved, EIO on a sick disk — as proof the store is there, which
+	// is the one thing a failed stat cannot establish. Contents are not judged
+	// and cannot be: a truncated store stats perfectly well, and the firmware is
+	// the only reader that would know. A VM whose NVRAM is unreadable is rebuilt
+	// under a new id and a new directory, which is where it gets a fresh one.
+	_, err := os.Stat(p.varStore(vmID))
+	args := p.buildArgs(spec, err != nil)
+	cmd := exec.Command(p.bin, args...)
+	cmd.SysProcAttr = &syscall.SysProcAttr{Setsid: true}
+	// Guest console output goes to the PTY the pump drains. vfkit's own
+	// diagnostics — startup errors, the framework's complaints — go here.
+	vfLog, err := os.OpenFile(p.logPath(vmID), os.O_CREATE|os.O_APPEND|os.O_WRONLY, logMode)
+	if err != nil {
+		return fmt.Errorf("open vfkit.log %s: %w", vmID, err)
+	}
+	cmd.Stdout = vfLog
+	cmd.Stderr = vfLog
+	if err := cmd.Start(); err != nil {
+		_ = vfLog.Close()
+		return fmt.Errorf("vfkit start %s: %w", vmID, err)
+	}
+	_ = vfLog.Close() // the child holds its own copy
+	if err := os.WriteFile(p.pidPath(vmID), p.pidRecord(cmd.Process.Pid), 0o600); err != nil {
+		// Best effort: kill the orphan we can no longer track, and Wait to reap
+		// it — the async reaper below is not started on this path.
+		_ = cmd.Process.Kill()
+		_ = cmd.Wait()
+		return fmt.Errorf("write pidfile %s: %w", vmID, err)
+	}
+	go func() { _ = cmd.Wait() }() // reap; exit status is not ours to judge
+	// Start the pump now so the boot log lands in the ring from as close to
+	// power-on as possible. Its first few Opens will fail — the PTY does not
+	// exist until vfkit has built the VM — and the pump's reconnect loop is
+	// exactly the retry for that.
+	if p.Pumps != nil {
+		p.Pumps.Ensure(vmID)
+	}
+	return nil
+}
+// pidRecord renders the pidfile: the process id, and the host boot it was
+// started in. The boot id is there because the pid alone is not evidence of
+// anything after a reboot — see ownedPID.
+func (p *Provisioner) pidRecord(pid int) []byte {
+	return []byte(strconv.Itoa(pid) + "\n" + p.bootID() + "\n")
+}
+// ownedPID returns the pid of the vfkit process THIS agent started for vmID, or
+// 0 when there is none it may signal.
+//
+// The boot id is what makes that a real answer rather than a hope. The state
+// directory survives a reboot, macOS recycles pids out of a small space, and
+// this backend's host is a laptop that reboots most days — so a pidfile written
+// before the last boot names whatever now happens to hold that number. Reading
+// it as ours makes Running() report a dead VM as up, and, on the reap path,
+// SIGTERMs and then SIGKILLs an unrelated process on the user's machine.
+// reconcile's own boot-id guard does not cover this: reapVM reaches Shutdown
+// before any of that reasoning runs.
+//
+// A pidfile with no boot id at all is treated as ours. It can only have been
+// written by an agent that predates this format, and the cheaper-looking answer
+// — refuse, report not running — is the more expensive one: reconcile reads a
+// live VM as lost and boots a SECOND vfkit onto the same disk image, and two
+// hypervisors writing one disk corrupt the guest. The window is transitional,
+// since the next Boot rewrites the pidfile in this format.
+func (p *Provisioner) ownedPID(vmID string) int {
+	raw, err := os.ReadFile(p.pidPath(vmID))
+	if err != nil {
+		return 0
+	}
+	line, rest, _ := strings.Cut(string(raw), "\n")
+	pid, err := strconv.Atoi(strings.TrimSpace(line))
+	if err != nil {
+		return 0
+	}
+	if boot := strings.TrimSpace(rest); boot != "" && boot != p.bootID() {
+		return 0
+	}
+	return pid
+}
+// Running reports whether the vfkit process for vmID is still alive, by
+// pidfile and signal 0.
+//
+// PID-liveness within this host boot: a pidfile from an earlier boot reports
+// not-running outright (see ownedPID), and within one boot a pid this agent
+// wrote cannot have been recycled while its process is alive. reconcile's
+// boot-ID check remains the authoritative reboot guard for the VM's record.
+func (p *Provisioner) Running(vmID string) bool {
+	pid := p.ownedPID(vmID)
+	if pid == 0 {
+		return false
+	}
+	return p.signal(pid, 0) == nil
+}
+// Shutdown asks vfkit for a graceful stop — the framework's ACPI power-down,
+// the same request cloud-hypervisor's power-button API makes. Falls back to
+// SIGTERM when the socket is gone or refuses, which covers a vfkit that is
+// unhealthy or a VM that is not running.
+func (p *Provisioner) Shutdown(ctx context.Context, vmID string) error {
+	body := bytes.NewReader([]byte(`{"state":"Stop"}`))
+	req, err := http.NewRequestWithContext(withSocket(ctx, p.sockPath(vmID)), http.MethodPost, "http://vfkit/vm/state", body)
+	if err != nil {
+		return p.sigterm(vmID)
+	}
+	req.Header.Set("Content-Type", "application/json")
+	resp, err := p.rest.Do(req)
+	if err != nil {
+		return p.sigterm(vmID)
+	}
+	resp.Body.Close()
+	// vfkit answers 202 Accepted. Anything past 2xx means the stop did not
+	// happen — a 400 for a VM in the wrong state, a 500 from the framework.
+	if resp.StatusCode >= 300 {
+		return p.sigterm(vmID)
+	}
+	return nil
+}
+// sigterm sends SIGTERM to the process identified by vmID's PID file.
+func (p *Provisioner) sigterm(vmID string) error {
+	pid := p.ownedPID(vmID)
+	if pid == 0 {
+		return nil // already gone
+	}
+	if err := p.signal(pid, syscall.SIGTERM); err != nil && err != syscall.ESRCH {
+		return fmt.Errorf("SIGTERM %s (pid %d): %w", vmID, pid, err)
+	}
+	return nil
+}
+// Destroy stops the VM and releases every host resource it holds: the vfkit
+// process, its serial pump, its REST socket.
+//
+// The kill's error is propagated, exactly as cloudhv propagates the failure to
+// delete a VM's tap, and for the same reason: nil is the promise reconcile
+// deletes the record on the strength of, and the record is the only thing on
+// this host that names the process. A SIGKILL the kernel refused has not proved
+// the process gone, so answering nil would strand a live vfkit holding an
+// unlinked disk, a vmnet attachment and a DHCP lease, with nothing left to find
+// it by. A non-nil answer keeps the record and the next tick tries again.
+//
+// This backend has less to release than cloudhv does: it created no host
+// networking, because vmnet's NAT is host-wide and outlives every guest. The
+// guest's DHCP lease outlives it too, in a root-owned file bootpd ages out on
+// its own; because the lease is keyed on the VM's deterministic MAC, a rebuilt
+// VM reclaims the same address rather than leaking a new one.
+func (p *Provisioner) Destroy(_ context.Context, vmID string) error {
+	return p.kill(vmID)
+}
+// kill SIGKILLs the vfkit process for vmID, stops its serial pump and removes
+// the pidfile and REST socket. It takes no context: killing a process by
+// pidfile is a syscall, and pretending otherwise made callers think a cancelled
+// context could skip a teardown.
+func (p *Provisioner) kill(vmID string) error {
+	// Pump teardown first: a pump leaked past a failed kill would reopen a PTY
+	// whose far end is gone, forever.
+	if p.Pumps != nil {
+		p.Pumps.Stop(vmID)
+	}
+	// A pid this agent may not claim — none recorded, or one from an earlier
+	// host boot — leaves nothing to kill and nothing to keep the record for.
+	pid := p.ownedPID(vmID)
+	if pid != 0 {
+		if err := p.signal(pid, syscall.SIGKILL); err != nil && err != syscall.ESRCH {
+			// Keep the pidfile and report: a SIGKILL that failed with anything
+			// but ESRCH has not proved the process gone, and the pidfile is the
+			// only record of which process it is.
+			return fmt.Errorf("SIGKILL %s (pid %d): %w", vmID, pid, err)
+		}
+	}
+	_ = os.Remove(p.pidPath(vmID))
+	_ = os.Remove(p.sockPath(vmID))
+	return nil
+}

internal/agent/vfkit/vfkit_test.go

@@ @@ -0,0 +1,655 @@ @@
+package vfkit
+import (
+	"context"
+	"errors"
+	"fmt"
+	"net"
+	"net/http"
+	"os"
+	"path/filepath"
+	"strconv"
+	"strings"
+	"syscall"
+	"testing"
+	"time"
+	"github.com/stretchr/testify/assert"
+	"github.com/stretchr/testify/require"
+	agentexec "github.com/a73x/eitri/internal/agent/exec"
+	"github.com/a73x/eitri/internal/agent/state"
+)
+// testSpec is the VM every test provisions unless it needs otherwise.
+func testSpec() state.VMSpec {
+	return state.VMSpec{VMID: "vm-1", Name: "web", VCPUs: 2, MemMB: 2048, DiskGB: 10}
+}
+func newTestProv(t *testing.T, run agentexec.Runner) *Provisioner {
+	t.Helper()
+	st, err := state.Open(t.TempDir())
+	require.NoError(t, err)
+	p := New(st, "vfkit", run)
+	// Never let a test read the real host's lease database.
+	p.leasesPath = filepath.Join(t.TempDir(), "dhcpd_leases")
+	return p
+}
+// isPermanent reports whether err carries the marker reconcile terminal-fails on.
+func isPermanent(err error) bool {
+	var perm interface{ Permanent() bool }
+	return errors.As(err, &perm) && perm.Permanent()
+}
+func TestBuildArgsIsTheVfkitContract(t *testing.T) {
+	p := newTestProv(t, nil)
+	vmDir := p.st.VMDir("vm-1")
+	args := p.buildArgs(testSpec(), true)
+	assert.Equal(t, []string{
+		"--restful-uri", "unix://" + filepath.Join(vmDir, "vfkit.sock"),
+		"--cpus", "2",
+		"--memory", "2048",
+		"--bootloader", "efi,variable-store=" + filepath.Join(vmDir, "efi-vars.fd") + ",create",
+		"--device", "virtio-blk,path=" + filepath.Join(vmDir, "disk.raw"),
+		"--device", "virtio-blk,path=" + filepath.Join(vmDir, "seed.iso"),
+		"--device", "virtio-net,nat,mac=" + state.MAC("vm-1"),
+		"--device", "virtio-serial,pty",
+		"--device", "virtio-rng",
+	}, args)
+}
+func TestBuildArgsPutsTheRootDiskFirst(t *testing.T) {
+	p := newTestProv(t, nil)
+	args := p.buildArgs(testSpec(), false)
+	var blk []string
+	for i, a := range args {
+		if strings.HasPrefix(a, "virtio-blk,") {
+			blk = append(blk, a)
+			require.Equal(t, "--device", args[i-1])
+		}
+	}
+	require.Len(t, blk, 2)
+	// vfkit maps block devices to /dev/vd* by argument position, so the guest
+	// boots from whichever comes first. The seed overtaking the root disk would
+	// be silent until the guest failed to boot.
+	assert.Contains(t, blk[0], "disk.raw", "the root disk must be the first block device")
+	assert.Contains(t, blk[1], "seed.iso")
+}
+func TestBuildArgsCreatesTheVariableStoreOnlyWhenThereIsNone(t *testing.T) {
+	p := newTestProv(t, nil)
+	assert.Contains(t, strings.Join(p.buildArgs(testSpec(), true), " "), "efi-vars.fd,create")
+	// A second boot must NOT recreate it: the store is the guest's NVRAM, and
+	// re-initialising it throws away the boot entry the guest wrote there.
+	assert.NotContains(t, strings.Join(p.buildArgs(testSpec(), false), " "), ",create")
+}
+func TestPreflightRefusesAHostWithoutVfkit(t *testing.T) {
+	p := newTestProv(t, nil)
+	p.lookPath = func(string) (string, error) { return "", errors.New("executable file not found in $PATH") }
+	err := p.Preflight(context.Background())
+	require.Error(t, err)
+	assert.True(t, isPermanent(err), "no retry installs a signed binary — the refusal must be terminal")
+	assert.Contains(t, err.Error(), "brew install vfkit", "the refusal must name the fix")
+}
+func TestPreflightPassesWhenVfkitResolves(t *testing.T) {
+	p := newTestProv(t, nil)
+	p.lookPath = func(file string) (string, error) { return "/opt/homebrew/bin/" + file, nil }
+	assert.NoError(t, p.Preflight(context.Background()))
+}
+func TestPreflightRefusesAStateDirectoryTooDeepForASocket(t *testing.T) {
+	deep := filepath.Join(t.TempDir(), strings.Repeat("d", maxSocketPath))
+	require.NoError(t, os.MkdirAll(deep, 0o700))
+	st, err := state.Open(deep)
+	require.NoError(t, err)
+	p := New(st, "vfkit", nil)
+	p.lookPath = func(file string) (string, error) { return file, nil }
+	// macOS caps a unix socket path at 104 bytes. Left to vfkit, this surfaces
+	// as a URI complaint after the image download; here it is the host's own
+	// verdict, before anything is spent.
+	err = p.Preflight(context.Background())
+	require.Error(t, err)
+	assert.True(t, isPermanent(err), "a state directory does not get shorter on retry")
+	assert.Contains(t, err.Error(), "--state-dir", "the refusal must name the fix")
+}
+func TestPreflightAcceptsTheDefaultStateDirectory(t *testing.T) {
+	// Not t.TempDir(): its paths carry the test's own name and are long enough
+	// to trip the guard — which is a fair demonstration that the guard bites.
+	dir, err := os.MkdirTemp("", "e")
+	require.NoError(t, err)
+	t.Cleanup(func() { _ = os.RemoveAll(dir) })
+	st, err := state.Open(dir)
+	require.NoError(t, err)
+	p := New(st, "vfkit", nil)
+	p.lookPath = func(file string) (string, error) { return file, nil }
+	assert.NoError(t, p.Preflight(context.Background()))
+	// The shipped default is /var/lib/eitri-agent; a VM's socket under it is
+	// 68 bytes, so the guard must not be so tight that normal use trips it.
+	assert.Less(t, len("/var/lib/eitri-agent/vms/"+strings.Repeat("0", vmIDLen)+"/vfkit.sock"), maxSocketPath)
+}
+// fakeRunner records the commands it is asked to run and answers from a script
+// of per-command results, so disk preparation is testable without a Mac.
+type fakeRunner struct {
+	calls [][]string
+	// fail returns an error for the given argv, or nil to let the call succeed.
+	fail func(argv []string) error
+}
+func (f *fakeRunner) run(_ context.Context, name string, args ...string) (string, error) {
+	argv := append([]string{name}, args...)
+	f.calls = append(f.calls, argv)
+	if f.fail != nil {
+		if err := f.fail(argv); err != nil {
+			return "", err
+		}
+	}
+	// A real cp produces the destination; tests that inspect the disk need it.
+	if len(argv) >= 2 {
+		src, dst := argv[len(argv)-2], argv[len(argv)-1]
+		if data, err := os.ReadFile(src); err == nil {
+			_ = os.WriteFile(dst, data, 0o600)
+		}
+	}
+	return "", nil
+}
+func writeBaseImage(t *testing.T, size int) string {
+	t.Helper()
+	path := filepath.Join(t.TempDir(), "base.raw")
+	require.NoError(t, os.WriteFile(path, make([]byte, size), 0o600))
+	return path
+}
+func TestPrepareRootDiskClonesTheBaseImageAndGrowsIt(t *testing.T) {
+	r := &fakeRunner{}
+	p := newTestProv(t, r.run)
+	base := writeBaseImage(t, 4096)
+	require.NoError(t, p.PrepareRootDisk(context.Background(), testSpec(), base))
+	require.Len(t, r.calls, 1, "an APFS clone is one command, not a copy loop")
+	assert.Equal(t, []string{"cp", "-c", base, p.st.DiskPath("vm-1") + ".partial"}, r.calls[0])
+	st, err := os.Stat(p.st.DiskPath("vm-1"))
+	require.NoError(t, err, "the disk must be renamed into place, not left as .partial")
+	assert.Equal(t, int64(10)<<30, st.Size())
+	_, err = os.Stat(p.st.DiskPath("vm-1") + ".partial")
+	assert.True(t, os.IsNotExist(err), "no temp file may survive a successful prepare")
+}
+func TestPrepareRootDiskFallsBackToAPlainCopyOffAPFS(t *testing.T) {
+	r := &fakeRunner{fail: func(argv []string) error {
+		if len(argv) > 1 && argv[1] == "-c" {
+			return errors.New("cp: clonefile failed: Operation not supported")
+		}
+		return nil
+	}}
+	p := newTestProv(t, r.run)
+	base := writeBaseImage(t, 4096)
+	// `cp -c` errors rather than degrading when the filesystem cannot clone, so
+	// a state directory on a non-APFS volume must still produce a disk.
+	require.NoError(t, p.PrepareRootDisk(context.Background(), testSpec(), base))
+	require.Len(t, r.calls, 2)
+	assert.Equal(t, "-c", r.calls[0][1])
+	assert.Equal(t, []string{"cp", base, p.st.DiskPath("vm-1") + ".partial"}, r.calls[1])
+	st, err := os.Stat(p.st.DiskPath("vm-1"))
+	require.NoError(t, err)
+	assert.Equal(t, int64(10)<<30, st.Size())
+}
+func TestPrepareRootDiskReportsACopyThatFailedBothWays(t *testing.T) {
+	// A real cp writes what it can before it runs out of space, so the failure
+	// leaves a partial file behind — which is the only state in which the
+	// cleanup that follows it does any work.
+	r := &fakeRunner{fail: func(argv []string) error {
+		require.NoError(t, os.WriteFile(argv[len(argv)-1], make([]byte, 512), 0o600))
+		return errors.New("No space left on device")
+	}}
+	p := newTestProv(t, r.run)
+	err := p.PrepareRootDisk(context.Background(), testSpec(), writeBaseImage(t, 4096))
+	require.Error(t, err)
+	assert.False(t, isPermanent(err), "a full disk is retryable — the operator can free space")
+	_, statErr := os.Stat(p.st.DiskPath("vm-1"))
+	assert.True(t, os.IsNotExist(statErr), "a failed prepare must leave no disk behind")
+	// The temp file matters as much as the final path: it sits on the same
+	// filesystem the copy just filled, and a create that retries every tick
+	// would otherwise strand a fresh multi-gigabyte carcass each time.
+	_, statErr = os.Stat(p.st.DiskPath("vm-1") + ".partial")
+	assert.True(t, os.IsNotExist(statErr), "a failed prepare must leave no temp file behind")
+}
+func TestPrepareRootDiskRefusesToShrinkTheBaseImage(t *testing.T) {
+	r := &fakeRunner{}
+	p := newTestProv(t, r.run)
+	spec := testSpec()
+	spec.DiskGB = 1
+	// Growing is a truncate to an EXACT size, so a target under the base image
+	// would chop the guest filesystem rather than fitting it.
+	err := p.PrepareRootDisk(context.Background(), spec, writeBaseImage(t, 2<<30))
+	require.Error(t, err)
+	assert.True(t, isPermanent(err), "a spec that cannot hold its image is not fixed by retrying")
+	assert.Empty(t, r.calls, "nothing may be copied for a disk that cannot be built")
+}
+func TestPrepareRootDiskRejectsAnOutOfRangeSize(t *testing.T) {
+	base := writeBaseImage(t, 4096)
+	for _, gb := range []int64{0, -1, maxDiskGB + 1} {
+		t.Run(strconv.FormatInt(gb, 10), func(t *testing.T) {
+			r := &fakeRunner{}
+			p := newTestProv(t, r.run)
+			spec := testSpec()
+			spec.DiskGB = gb
+			err := p.PrepareRootDisk(context.Background(), spec, base)
+			require.Error(t, err)
+			assert.True(t, isPermanent(err))
+			// The range check must run BEFORE the byte computation: DiskGB<<30
+			// wraps to a small positive number for sizes past 2^33 GiB, and a
+			// wrapped value would sail through the shrink guard.
+			assert.Empty(t, r.calls)
+		})
+	}
+}
+// fakePumps records the serial-pump lifecycle calls the provisioner drives.
+type fakePumps struct{ ensured, stopped []string }
+func (f *fakePumps) Ensure(vmID string) { f.ensured = append(f.ensured, vmID) }
+func (f *fakePumps) Stop(vmID string)   { f.stopped = append(f.stopped, vmID) }
+// argRecorder writes a fake vfkit that records its argv and then sleeps, so
+// Boot's whole chain — stale-socket cleanup, argument assembly, spawn, pidfile,
+// pump — is observable without a hypervisor.
+func argRecorder(t *testing.T) (bin, argsFile string) {
+	t.Helper()
+	dir := t.TempDir()
+	bin, argsFile = filepath.Join(dir, "fake-vfkit"), filepath.Join(dir, "argv")
+	script := fmt.Sprintf("#!/bin/sh\nprintf '%%s\\n' \"$@\" > %s\nexec sleep 30\n", argsFile)
+	require.NoError(t, os.WriteFile(bin, []byte(script), 0o700))
+	return bin, argsFile
+}
+func TestBootSpawnsVfkitAndTracksIt(t *testing.T) {
+	bin, argsFile := argRecorder(t)
+	p := newTestProv(t, nil)
+	p.bin = bin
+	pumps := &fakePumps{}
+	p.Pumps = pumps
+	require.NoError(t, os.MkdirAll(p.st.VMDir("vm-1"), 0o700))
+	t.Cleanup(func() { _ = p.kill("vm-1") })
+	require.NoError(t, p.Boot(context.Background(), "vm-1", testSpec()))
+	assert.True(t, p.Running("vm-1"), "a booted VM must be tracked by its pidfile")
+	assert.Equal(t, []string{"vm-1"}, pumps.ensured,
+		"the pump must start at power-on or the boot log is lost before anyone attaches")
+	var argv []byte
+	require.Eventually(t, func() bool {
+		var err error
+		argv, err = os.ReadFile(argsFile)
+		return err == nil && len(argv) > 0
+	}, 5*time.Second, 20*time.Millisecond, "the fake vfkit never recorded its arguments")
+	assert.Contains(t, string(argv), "efi-vars.fd,create",
+		"the first boot of a VM must create its EFI variable store")
+	_, err := os.Stat(p.logPath("vm-1"))
+	assert.NoError(t, err, "vfkit's own diagnostics must land in a log, not the void")
+}
+func TestBootClearsAStaleSocket(t *testing.T) {
+	bin, _ := argRecorder(t)
+	p := newTestProv(t, nil)
+	p.bin = bin
+	require.NoError(t, os.MkdirAll(p.st.VMDir("vm-1"), 0o700))
+	// vfkit removes its socket on a clean exit only, so a crash or a host reboot
+	// leaves one that the next bind would trip over.
+	require.NoError(t, os.WriteFile(p.sockPath("vm-1"), []byte("stale"), 0o600))
+	t.Cleanup(func() { _ = p.kill("vm-1") })
+	require.NoError(t, p.Boot(context.Background(), "vm-1", testSpec()))
+	data, err := os.ReadFile(p.sockPath("vm-1"))
+	if err == nil {
+		assert.NotEqual(t, "stale", string(data), "the stale socket must be gone before vfkit binds")
+	}
+}
+func TestBootReportsAVfkitThatCannotStart(t *testing.T) {
+	p := newTestProv(t, nil)
+	p.bin = filepath.Join(t.TempDir(), "not-installed")
+	require.NoError(t, os.MkdirAll(p.st.VMDir("vm-1"), 0o700))
+	err := p.Boot(context.Background(), "vm-1", testSpec())
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "vfkit start")
+	assert.False(t, p.Running("vm-1"))
+}
+func TestRunningIsFalseForAVMThatWasNeverBooted(t *testing.T) {
+	p := newTestProv(t, nil)
+	assert.False(t, p.Running("vm-1"))
+}
+func TestRunningIsFalseAfterTheProcessIsGone(t *testing.T) {
+	p := newTestProv(t, nil)
+	require.NoError(t, os.MkdirAll(p.st.VMDir("vm-1"), 0o700))
+	// A pid that cannot be running: the kernel rejects it outright.
+	require.NoError(t, os.WriteFile(p.pidPath("vm-1"), []byte("2147483647"), 0o600))
+	assert.False(t, p.Running("vm-1"))
+}
+// serveREST starts an HTTP server on vmID's vfkit socket path and returns the
+// requests it received.
+func serveREST(t *testing.T, p *Provisioner, vmID string, h http.HandlerFunc) *[]*http.Request {
+	t.Helper()
+	require.NoError(t, os.MkdirAll(p.st.VMDir(vmID), 0o700))
+	ln, err := net.Listen("unix", p.sockPath(vmID))
+	require.NoError(t, err)
+	var got []*http.Request
+	srv := &http.Server{Handler: http.HandlerFunc(func(w http.ResponseWriter, r *http.Request) {
+		got = append(got, r)
+		h(w, r)
+	})}
+	go func() { _ = srv.Serve(ln) }()
+	t.Cleanup(func() { _ = srv.Close() })
+	return &got
+}
+func TestShutdownAsksVfkitForAGracefulStop(t *testing.T) {
+	p := newTestProv(t, nil)
+	var body string
+	got := serveREST(t, p, "vm-1", func(w http.ResponseWriter, r *http.Request) {
+		b := make([]byte, 64)
+		n, _ := r.Body.Read(b)
+		body = string(b[:n])
+		w.WriteHeader(http.StatusAccepted) // what vfkit answers
+	})
+	require.NoError(t, p.Shutdown(context.Background(), "vm-1"))
+	require.Len(t, *got, 1)
+	assert.Equal(t, http.MethodPost, (*got)[0].Method)
+	assert.Equal(t, "/vm/state", (*got)[0].URL.Path)
+	// "Stop" is the ACPI power-down; "HardStop" would cut the power instead,
+	// which is Destroy's job, not Shutdown's.
+	assert.JSONEq(t, `{"state":"Stop"}`, body)
+}
+func TestShutdownFallsBackToSigtermWhenVfkitRefuses(t *testing.T) {
+	p := newTestProv(t, nil)
+	serveREST(t, p, "vm-1", func(w http.ResponseWriter, _ *http.Request) {
+		w.WriteHeader(http.StatusInternalServerError)
+	})
+	// A pid the signal cannot reach stands in for a VM whose process is gone:
+	// the fallback must report success, not an error about a dead process.
+	require.NoError(t, os.WriteFile(p.pidPath("vm-1"), []byte("2147483647"), 0o600))
+	assert.NoError(t, p.Shutdown(context.Background(), "vm-1"))
+}
+func TestShutdownOfAVMWithNoProcessIsNotAnError(t *testing.T) {
+	p := newTestProv(t, nil)
+	// No socket, no pidfile: reconcile calls Shutdown on every tick past a stop
+	// request, and a VM that is already down must not fail the pass.
+	assert.NoError(t, p.Shutdown(context.Background(), "vm-1"))
+}
+func TestDestroyKillsTheProcessAndStopsThePump(t *testing.T) {
+	bin, _ := argRecorder(t)
+	p := newTestProv(t, nil)
+	p.bin = bin
+	pumps := &fakePumps{}
+	p.Pumps = pumps
+	require.NoError(t, os.MkdirAll(p.st.VMDir("vm-1"), 0o700))
+	require.NoError(t, p.Boot(context.Background(), "vm-1", testSpec()))
+	pid := p.ownedPID("vm-1")
+	require.NotZero(t, pid)
+	// nil is the promise reconcile deletes the VM's record on the strength of,
+	// so it may only follow a kill that actually happened.
+	require.NoError(t, p.Destroy(context.Background(), "vm-1"))
+	assert.Equal(t, []string{"vm-1"}, pumps.stopped)
+	assert.Eventually(t, func() bool { return syscall.Kill(pid, 0) != nil },
+*time.Second, 20*time.Millisecond, "the vfkit process outlived Destroy")
+	_, err := os.Stat(p.pidPath("vm-1"))
+	assert.True(t, os.IsNotExist(err), "the pidfile must not outlive the process it names")
+}
+func TestDestroyOfAVMThatWasNeverBootedIsNotAnError(t *testing.T) {
+	p := newTestProv(t, nil)
+	// Destroy is called on every tick past a VM's grace until it returns nil.
+	assert.NoError(t, p.Destroy(context.Background(), "vm-1"))
+	assert.NoError(t, p.Destroy(context.Background(), "vm-1"))
+}
+// writePidfile puts a pidfile in place without booting anything, so the paths
+// that read one can be driven to any state a real host can be in.
+func writePidfile(t *testing.T, p *Provisioner, vmID, contents string) {
+	t.Helper()
+	require.NoError(t, os.MkdirAll(p.st.VMDir(vmID), 0o700))
+	require.NoError(t, os.WriteFile(p.pidPath(vmID), []byte(contents), 0o600))
+}
+func TestDestroyReportsAKillTheKernelRefused(t *testing.T) {
+	p := newTestProv(t, nil)
+	p.signal = func(int, syscall.Signal) error { return syscall.EPERM }
+	writePidfile(t, p, "vm-1", "4321\n"+p.bootID()+"\n")
+	err := p.Destroy(context.Background(), "vm-1")
+	// A refused SIGKILL has not proved the process gone. reconcile deletes the
+	// VM's whole directory the moment Destroy answers nil, so answering nil
+	// here would take the pidfile — the only record of a live vfkit still
+	// holding an unlinked disk and a vmnet attachment — with it.
+	require.Error(t, err)
+	assert.Contains(t, err.Error(), "SIGKILL")
+	_, statErr := os.Stat(p.pidPath("vm-1"))
+	assert.NoError(t, statErr, "the record of a process we could not kill must survive")
+}
+func TestDestroyTreatsAProcessThatIsAlreadyGoneAsDone(t *testing.T) {
+	p := newTestProv(t, nil)
+	p.signal = func(int, syscall.Signal) error { return syscall.ESRCH }
+	writePidfile(t, p, "vm-1", "4321\n"+p.bootID()+"\n")
+	// ESRCH is the answer that proves the kill's whole purpose is served.
+	require.NoError(t, p.Destroy(context.Background(), "vm-1"))
+	_, statErr := os.Stat(p.pidPath("vm-1"))
+	assert.True(t, os.IsNotExist(statErr))
+}
+func TestBootRecordsTheHostBootAlongsideThePID(t *testing.T) {
+	bin, _ := argRecorder(t)
+	p := newTestProv(t, nil)
+	p.bin = bin
+	p.bootID = func() string { return "boot-a" }
+	require.NoError(t, os.MkdirAll(p.st.VMDir("vm-1"), 0o700))
+	t.Cleanup(func() { _ = p.kill("vm-1") })
+	require.NoError(t, p.Boot(context.Background(), "vm-1", testSpec()))
+	raw, err := os.ReadFile(p.pidPath("vm-1"))
+	require.NoError(t, err)
+	assert.Contains(t, string(raw), "boot-a", "a pid without the boot it belongs to is not evidence of anything")
+}
+func TestAPidFromAnEarlierBootIsNotOurs(t *testing.T) {
+	p := newTestProv(t, nil)
+	p.bootID = func() string { return "boot-b" }
+	var signalled []int
+	p.signal = func(pid int, _ syscall.Signal) error { signalled = append(signalled, pid); return nil }
+	// A pidfile written before the last reboot. macOS recycles pids out of a
+	// small space and this backend's host is a laptop, so the number now names
+	// whatever the user happens to be running.
+	writePidfile(t, p, "vm-1", "4321\nboot-a\n")
+	assert.False(t, p.Running("vm-1"), "a VM whose process died with the host is not running")
+	assert.NoError(t, p.Shutdown(context.Background(), "vm-1"))
+	assert.NoError(t, p.Destroy(context.Background(), "vm-1"))
+	assert.Empty(t, signalled, "SIGTERM and SIGKILL went to a pid this agent never started")
+	_, statErr := os.Stat(p.pidPath("vm-1"))
+	assert.True(t, os.IsNotExist(statErr), "nothing of ours is left, so the record must go")
+}
+func TestAPidfileWithoutABootIDIsStillOurs(t *testing.T) {
+	p := newTestProv(t, nil)
+	p.bootID = func() string { return "boot-a" }
+	var signalled []syscall.Signal
+	p.signal = func(_ int, sig syscall.Signal) error { signalled = append(signalled, sig); return nil }
+	// The format an agent that predates the boot id wrote. Refusing it would be
+	// worse than trusting it: reconcile would read the VM as lost and boot a
+	// second vfkit onto the same disk image.
+	writePidfile(t, p, "vm-1", "4321\n")
+	assert.True(t, p.Running("vm-1"))
+	require.NoError(t, p.Destroy(context.Background(), "vm-1"))
+	assert.Contains(t, signalled, syscall.SIGKILL)
+}
+// TestBootedVMSurvivesCtxCancellation pins the VM-lifetime contract: the vfkit
+// process must NOT die when the context passed to Boot is cancelled. The
+// agent's root context is cancelled on every graceful agent stop, and guests
+// are meant to outlive the agent (that is why Boot uses Setsid and why its
+// context parameter is deliberately unused). Killing a VM is the exclusive job
+// of Shutdown/Destroy. cloudhv carries the same test for the same reason.
+func TestBootedVMSurvivesCtxCancellation(t *testing.T) {
+	bin, _ := argRecorder(t)
+	p := newTestProv(t, nil)
+	p.bin = bin
+	require.NoError(t, os.MkdirAll(p.st.VMDir("vm-1"), 0o700))
+	t.Cleanup(func() { _ = p.Destroy(context.Background(), "vm-1") })
+	ctx, cancel := context.WithCancel(context.Background())
+	require.NoError(t, p.Boot(ctx, "vm-1", testSpec()))
+	require.True(t, p.Running("vm-1"), "the process must be alive right after Boot")
+	cancel()
+	// Poll rather than sleep once: exec.CommandContext's SIGKILL lands and is
+	// reaped within milliseconds, so a regression fails immediately and 300ms
+	// is orders of magnitude of margin.
+	deadline := time.Now().Add(300 * time.Millisecond)
+	for time.Now().Before(deadline) {
+		require.True(t, p.Running("vm-1"),
+			"the vfkit process died with the context passed to Boot — a guest's lifetime is not the agent's")
+		time.Sleep(50 * time.Millisecond)
+	}
+}
+// varStoreRecorder writes a fake vfkit that initialises the EFI variable store
+// the way the real one does, then records its argv and sleeps. Creating the
+// store FIRST means argv's arrival proves the store exists, so a second Boot
+// can be sequenced against it without a second wait.
+func varStoreRecorder(t *testing.T, varStore string) (bin, argsFile string) {
+	t.Helper()
+	dir := t.TempDir()
+	bin, argsFile = filepath.Join(dir, "fake-vfkit"), filepath.Join(dir, "argv")
+	script := fmt.Sprintf("#!/bin/sh\ntouch %s\nprintf '%%s\\n' \"$@\" > %s\nexec sleep 30\n", varStore, argsFile)
+	require.NoError(t, os.WriteFile(bin, []byte(script), 0o700))
+	return bin, argsFile
+}
+func TestASecondBootKeepsTheVariableStoreTheGuestWrote(t *testing.T) {
+	p := newTestProv(t, nil)
+	require.NoError(t, os.MkdirAll(p.st.VMDir("vm-1"), 0o700))
+	bin, argsFile := varStoreRecorder(t, p.varStore("vm-1"))
+	p.bin = bin
+	t.Cleanup(func() { _ = p.kill("vm-1") })
+	require.NoError(t, p.Boot(context.Background(), "vm-1", testSpec()))
+	assert.Contains(t, waitForArgv(t, argsFile), "efi-vars.fd,create",
+		"the first boot of a VM must initialise its EFI variable store")
+	require.NoError(t, p.kill("vm-1"))
+	require.NoError(t, os.Remove(argsFile))
+	require.NoError(t, p.Boot(context.Background(), "vm-1", testSpec()))
+	// The store is the guest's NVRAM and holds the boot entry Ubuntu writes on
+	// first boot. Re-initialising it every launch throws that away and leaves
+	// the guest booting only by the removable-media fallback path.
+	assert.NotContains(t, waitForArgv(t, argsFile), ",create",
+		"a boot that already has a variable store must not recreate it")
+}
+func TestBootRebuildsAVariableStoreItCannotStat(t *testing.T) {
+	p := newTestProv(t, nil)
+	require.NoError(t, os.MkdirAll(p.st.VMDir("vm-1"), 0o700))
+	bin, argsFile := varStoreRecorder(t, p.varStore("vm-1"))
+	p.bin = bin
+	t.Cleanup(func() { _ = p.kill("vm-1") })
+	// A store whose stat fails for a reason that is not ENOENT — here a symlink
+	// loop, on a real host an EACCES from a state dir whose ownership moved.
+	// Matching ENOENT alone read every one of those as "the store is there" and
+	// launched vfkit against NVRAM it could not open, on every retry forever.
+	require.NoError(t, os.Symlink(p.varStore("vm-1"), p.varStore("vm-1")))
+	require.NoError(t, p.Boot(context.Background(), "vm-1", testSpec()))
+	assert.Contains(t, waitForArgv(t, argsFile), ",create")
+}
+// waitForArgv returns the argv the fake vfkit recorded, once it has.
+func waitForArgv(t *testing.T, argsFile string) string {
+	t.Helper()
+	var argv []byte
+	require.Eventually(t, func() bool {
+		var err error
+		argv, err = os.ReadFile(argsFile)
+		return err == nil && len(argv) > 0
+	}, 5*time.Second, 20*time.Millisecond, "the fake vfkit never recorded its arguments")
+	return string(argv)
+}
+func TestShutdownDialsTheVMsOwnSocket(t *testing.T) {
+	p := newTestProv(t, nil)
+	first := serveREST(t, p, "vm-1", func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusAccepted) })
+	second := serveREST(t, p, "vm-2", func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusAccepted) })
+	// One client serves every VM on the host, and the URL's host — the only
+	// thing an idle connection is pooled under — is the same placeholder for
+	// all of them. A pooled connection would answer the wrong VM's socket.
+	require.NoError(t, p.Shutdown(context.Background(), "vm-1"))
+	require.NoError(t, p.Shutdown(context.Background(), "vm-2"))
+	assert.Len(t, *first, 1)
+	assert.Len(t, *second, 1)
+}
+func TestShutdownDoesNotLeakAConnectionPerCall(t *testing.T) {
+	p := newTestProv(t, nil)
+	serveREST(t, p, "vm-1", func(w http.ResponseWriter, _ *http.Request) { w.WriteHeader(http.StatusAccepted) })
+	require.NoError(t, p.Shutdown(context.Background(), "vm-1"))
+	assertNoGoroutineGrowth(t, func() {
+		for range restCallCount {
+			require.NoError(t, p.Shutdown(context.Background(), "vm-1"))
+		}
+	})
+}

internal/arch/arch_test.go

Old		New
@@ -223,6 +223,7 @@ func TestOnlyProvisionersAndRootImportOsExecInDataPlane(t *testing.T) {
223	g := directImports(t)	223	g := directImports(t)
224	allowed := map[string]bool{	224	allowed := map[string]bool{
225	module + "/internal/agent/cloudhv": true, // provisioner: spawns cloud-hypervisor	225	module + "/internal/agent/cloudhv": true, // provisioner: spawns cloud-hypervisor
		226	module + "/internal/agent/vfkit": true, // provisioner: spawns vfkit
226	module + "/internal/agent/run": true, // composition root: builds hostRunner	227	module + "/internal/agent/run": true, // composition root: builds hostRunner
227	}	228	}
228	for pkg, offenders := range execViolations(g, module, "internal/agent/", allowed) {	229	for pkg, offenders := range execViolations(g, module, "internal/agent/", allowed) {
@@ -233,8 +234,8 @@ func TestOnlyProvisionersAndRootImportOsExecInDataPlane(t *testing.T) {
233	}	234	}
234		235
235	// R7: external process execution anywhere in internal/ is confined to a	236	// R7: external process execution anywhere in internal/ is confined to a
236	// sanctioned allowlist — cloudhv (a provisioner: spawning the VMM directly is	237	// sanctioned allowlist — cloudhv and vfkit (provisioners: spawning the VMM
237	// what a provisioner is, R6's narrower story), agent/run (the agent	238	// directly is what a provisioner is, R6's narrower story), agent/run (the agent
238	// composition root, which builds the Runner it injects into every other	239	// composition root, which builds the Runner it injects into every other
239	// package), cli (interactive ssh must be the real OpenSSH client), shape	240	// package), cli (interactive ssh must be the real OpenSSH client), shape
240	// (architecture tooling that shells out to `go list`, the same introspection	241	// (architecture tooling that shells out to `go list`, the same introspection
@@ -246,6 +247,7 @@ func TestExecIsConfinedToSanctionedPackages(t *testing.T) {
246	g := directImports(t)	247	g := directImports(t)
247	allowed := map[string]bool{	248	allowed := map[string]bool{
248	module + "/internal/agent/cloudhv": true, // provisioner: spawns the VMM directly (R6's story)	249	module + "/internal/agent/cloudhv": true, // provisioner: spawns the VMM directly (R6's story)
		250	module + "/internal/agent/vfkit": true, // provisioner: the same sanction, one platform over
249	module + "/internal/agent/run": true, // agent composition root: builds the injected Runner	251	module + "/internal/agent/run": true, // agent composition root: builds the injected Runner
250	module + "/internal/cli": true, // interactive sessions must be the real OpenSSH client	252	module + "/internal/cli": true, // interactive sessions must be the real OpenSSH client
251	module + "/internal/shape": true, // architecture tooling: shells `go list -json` to build the module graph — the same shell-out internal/arch's own tests make	253	module + "/internal/shape": true, // architecture tooling: shells `go list -json` to build the module graph — the same shell-out internal/arch's own tests make

scripts/coverage.sh

Old		New
@@ -24,7 +24,7 @@ declare -A FLOOR=(
24	[internal/agent/imagecache]=72	24	[internal/agent/imagecache]=72
25	[internal/agent/netenv]=76	25	[internal/agent/netenv]=76
26	[internal/agent/cloudhv]=40	26	[internal/agent/cloudhv]=40
27	[internal/agent/inert]=95	27	[internal/agent/vfkit]=85
28	[internal/agent/syncclient]=74	28	[internal/agent/syncclient]=74
29	[internal/server/api]=76	29	[internal/server/api]=76
30	[internal/server/boot]=17	30	[internal/server/boot]=17

Old		New
@@ -13,7 +13,7 @@ hosts and share only a wire contract:
13	\| Plane \| Packages \| Role \|	13	\| Plane \| Packages \| Role \|
14	\|-------\|----------\|------\|	14	\|-------\|----------\|------\|
15	\| Control plane (server) \| `internal/server/`, `cmd/eitri-server` \| Holds desired* state, tracks actual state, exposes the API + SSE UI. Never touches a VM. \|	15	\| Control plane (server) \| `internal/server/`, `cmd/eitri-server` \| Holds desired* state, tracks actual state, exposes the API + SSE UI. Never touches a VM. \|
16	\| Data plane (agent) \| `internal/agent/*`, `cmd/eitri-agent` \| Owns the entire VM lifecycle: disks, networking, cloud-hypervisor processes. \|	16	\| Data plane (agent) \| `internal/agent/*`, `cmd/eitri-agent` \| Owns the entire VM lifecycle: disks, networking, VMM processes. \|
17	\| Wire contract \| `internal/pb`, `internal/transport` \| The only code shared across the boundary: protobuf messages + QUIC framing/TLS. \|	17	\| Wire contract \| `internal/pb`, `internal/transport` \| The only code shared across the boundary: protobuf messages + QUIC framing/TLS. \|
18		18
19	The server expresses intent as a `pb.DesiredStateSnapshot` (server → agent); the	19	The server expresses intent as a `pb.DesiredStateSnapshot` (server → agent); the
@@ -38,7 +38,7 @@ bridge IP (`assigned_ip`) via the agent.
38	\| R3 \| The wire contract (`pb`, `transport`) imports no other internal package, so a heavy dependency can't leak across the boundary into both binaries. \| `internal/arch` `TestWireContractIsLeaf`. Behavior pinned by `transport` round-trip contract tests. \|	38	\| R3 \| The wire contract (`pb`, `transport`) imports no other internal package, so a heavy dependency can't leak across the boundary into both binaries. \| `internal/arch` `TestWireContractIsLeaf`. Behavior pinned by `transport` round-trip contract tests. \|
39	\| R4 \| Pure domain packages (`agent/state`, `agent/seed`, `agent/ipalloc`, `server/registry`) don't depend on the transport stack (HTTP/QUIC/`transport`). `server/store` may use `transport` (cert helpers) but not HTTP/QUIC. \| `internal/arch` `TestDomainDoesNotImportTransportStack` + `depguard` `domain-no-transport`. \|	39	\| R4 \| Pure domain packages (`agent/state`, `agent/seed`, `agent/ipalloc`, `server/registry`) don't depend on the transport stack (HTTP/QUIC/`transport`). `server/store` may use `transport` (cert helpers) but not HTTP/QUIC. \| `internal/arch` `TestDomainDoesNotImportTransportStack` + `depguard` `domain-no-transport`. \|
40	\| R5 \| The reconcile boundary interface (`Provisioner`) stays consumer-owned and small. A VM's network attachment lives inside it, because on every backend we ship the NIC is a launch argument rather than a separately-lifecycled resource; what crosses the seam is data (the VM's address) and not mechanism (taps, reservations). \| Convention (below) + `ireturn` allow-list keeps the seam's interface returns honest. \|	40	\| R5 \| The reconcile boundary interface (`Provisioner`) stays consumer-owned and small. A VM's network attachment lives inside it, because on every backend we ship the NIC is a launch argument rather than a separately-lifecycled resource; what crosses the seam is data (the VM's address) and not mechanism (taps, reservations). \| Convention (below) + `ireturn` allow-list keeps the seam's interface returns honest. \|
41	\| R6 \| All external process execution in the data plane funnels through `agent/exec.Runner`. The sole exception is `agent/cloudhv`, which launches the long-lived cloud-hypervisor process directly. Checked transitively (reaching `os/exec` via the sanctioned `cloudhv` is fine). \| `internal/arch` `TestOnlyCloudhvImportsOsExecInDataPlane` (transitive). \|	41	\| R6 \| All external process execution in the data plane funnels through `agent/exec.Runner`. The exceptions are the provisioners — `agent/cloudhv` and `agent/vfkit` — which launch the long-lived VMM process directly, and the composition root `agent/run`, which builds the Runner it injects. Checked transitively (reaching `os/exec` via a sanctioned package is fine). \| `internal/arch` `TestOnlyProvisionersAndRootImportOsExecInDataPlane` (transitive). \|
42	\| R13 \| The OIDC issuer and the relying party stay separate binaries. `eitri-server` is a pure relying party: the bundled issuer (`internal/oidcprovider`) is importable only by its own binary `cmd/eitri-oidc`, and the `go-oidc` verifier module only by `internal/server/api` (the RP). A server import of the issuer would silently rebuild the embedded-IdP coupling; `go-oidc` anywhere but the RP means a second relying party is being hand-rolled. \| `internal/arch` `TestIssuerAndRelyingPartyAreSeparate`. \|	42	\| R13 \| The OIDC issuer and the relying party stay separate binaries. `eitri-server` is a pure relying party: the bundled issuer (`internal/oidcprovider`) is importable only by its own binary `cmd/eitri-oidc`, and the `go-oidc` verifier module only by `internal/server/api` (the RP). A server import of the issuer would silently rebuild the embedded-IdP coupling; `go-oidc` anywhere but the RP means a second relying party is being hand-rolled. \| `internal/arch` `TestIssuerAndRelyingPartyAreSeparate`. \|
43		43
44	> The `internal/arch` tests shell out to `go list`, so Go's test cache can't see	44	> The `internal/arch` tests shell out to `go list`, so Go's test cache can't see
@@ -52,10 +52,10 @@ why the invariants hold:
52		52
53	1. Consumer-side interfaces only. An interface is declared by the package	53	1. Consumer-side interfaces only. An interface is declared by the package
54	that uses it, not the one that implements it. `reconcile` owns	54	that uses it, not the one that implements it. `reconcile` owns
55	`Provisioner`; `cloudhv` implements it. `cloudhv` in turn owns `Network`,	55	`Provisioner`; `cloudhv` and `vfkit` implement it. `cloudhv` in turn owns
56	which `netenv` implements. Keep them minimal (`Provisioner` is 6 methods).	56	`Network`, which `netenv` implements. Keep them minimal. This is what let the
57	This is what lets a host backend evolve — a second VMM, a different way of	57	second VMM land — vfkit on macOS, where the host OS assigns guest addresses
58	addressing guests — without touching the reconcile loop.	58	instead of the agent — without touching the reconcile loop.
59	2. Dependency injection via struct + function fields, no DI framework.	59	2. Dependency injection via struct + function fields, no DI framework.
60	`reconcile.Engine` is the template: collaborators as interface fields	60	`reconcile.Engine` is the template: collaborators as interface fields
61	(`Prov`), pure side effects as func fields (`Images`, `Seed`, `BootID`,	61	(`Prov`), pure side effects as func fields (`Images`, `Seed`, `BootID`,