refactor: extract a Provider seam and an explicit SSH endpoint

docs/getting-started/installation.md

@@ -187,9 +187,10 @@ install -Dm755 stoat ~/.local/bin/stoat
 ```
 
 A release also carries `darwin_amd64` and `darwin_arm64` tarballs, and
-`windows_amd64` and `windows_arm64` zip archives. On those hosts Stoat runs
-`doctor` and `capabilities` only. Every other command reports the host as
-unqualified, because macOS needs the QEMU HVF accelerator
+`windows_amd64` and `windows_arm64` zip archives. On those hosts Stoat cannot
+start or stop a local VM; it reports the host as unqualified. Commands that
+only read or edit VM records still run. This is because macOS needs the
+QEMU HVF accelerator
 ([#82](https://github.com/NovusEdge/stoat/issues/82)) and Windows needs WHPX
 ([#83](https://github.com/NovusEdge/stoat/issues/83)). Linux with KVM is the
 supported host today.

docs/reference/samples/vm.toml

@@ -16,6 +16,7 @@ sshport          = 2200            # int; default an allocated free port; stoat
 recipes          = ["docker"]      # string[]; default []; user/TUI and stoat create/update write the selection.
 display          = "auto"          # string; default "auto"; user/TUI writes: auto, window, or vnc.
 backend          = "apkovl"        # string; default inferred from image; stoat writes: apkovl, cloudinit, or ssh.
+provider         = "qemu"          # string; default qemu when empty; stoat writes the execution surface.
 base             = ""              # string path; default empty; stoat writes the absolute shared base-image path.
 sshuser          = "root"          # string; default guest-defined user (empty means root); stoat writes it.
 console_password = ""              # string; default "stoat" for cloud VMs, empty otherwise; stoat writes, never ssh.

docs/troubleshooting.md

@@ -7,20 +7,19 @@ Find the reported symptom or error text below, then follow its recovery steps.
 ```
 stoat: up: native VM operations are not qualified on darwin/arm64.
 darwin/arm64 needs a qualified runtime with the QEMU HVF accelerator (tracked in stoat#82).
-doctor and capabilities still work here; every other command needs a qualified host.
+starting and stopping a local VM needs a qualified host; commands that only read or edit VM records still work here.
 Linux with KVM is the supported configuration today.
 ```
 
-Stoat's VM lifecycle (create, start, stop, ssh, recipes, and every other
-command except `doctor` and `capabilities`) is qualified on Linux with KVM
-only. macOS arm64 and Windows amd64 builds exist and compile, but their
-native runtimes are not qualified yet; see
+Starting and stopping a local VM is qualified on Linux with KVM only. macOS
+arm64 and Windows amd64 builds exist and compile, but their native runtimes
+are not qualified yet; see
 [stoat#82](https://github.com/novusedge/stoat/issues/82) and
 [stoat#83](https://github.com/novusedge/stoat/issues/83). `--json` and MCP
 report this as the `host_unsupported` error code.
 
 **Fix:** run Stoat on Linux with KVM, or track the issue above for your
-platform. `stoat doctor` and `stoat capabilities` still run on any host.
+platform. Commands that only read or edit VM records still run on any host.
 
 ## No QEMU window appears
 
@@ -111,10 +110,10 @@ every command and for the TUI:
 `STOAT_GRAPHICAL=0` is also the answer to the OpenGL error above, where a
 session exists but QEMU cannot draw on it.
 
-## `ssh not reachable on port N after 1m30s`
+## `ssh not reachable at HOST:PORT after 1m30s`
 
 ```
-<name>: ssh not reachable on port <N> after 1m30s
+<name>: ssh not reachable at <host>:<port> after 1m30s
 ```
 
 **If this happens while applying recipes to a disk VM:** the VM is still

internal/capabilities/build.go

@@ -3,7 +3,7 @@ package capabilities
 import (
 	"runtime"
 
-	"github.com/novusedge/stoat/internal/core"
+	"github.com/novusedge/stoat/internal/hostcheck"
 )
 
 // Build evaluates the supplied host and metadata observations without I/O.
@@ -131,14 +131,14 @@ func currentEntry(name, status, scope string, requirements []Requirement, limits
 	return Capability{Name: name, Status: status, Scope: scope, Requirements: requirements, Limits: limits, Reason: reason, Evidence: []Evidence{implementationEvidence(name)}}
 }
 
-func qemuProfile(checks []core.HostCheck) Profile {
+func qemuProfile(checks []hostcheck.Check) Profile {
 	requirements := []Requirement{
 		requirement("host_tool", "qemu-system-x86_64", ""),
 		requirement("host_tool", "qemu-img", ""),
 		requirement("host_device", "/dev/kvm", ""),
 	}
 	p := Profile{Name: "qemu-x86_64", Status: StatusUnknown, Scope: ScopeHost, Requirements: requirements, Limits: []Limit{}, Evidence: []Evidence{}}
-	byName := make(map[string]core.HostCheck, len(checks))
+	byName := make(map[string]hostcheck.Check, len(checks))
 	for _, c := range checks {
 		if _, exists := byName[c.Name]; !exists {
 			byName[c.Name] = c

internal/capabilities/build_test.go

@@ -8,11 +8,12 @@ import (
 	"strconv"
 	"testing"
 
-	"github.com/novusedge/stoat/internal/core"
+	"github.com/novusedge/stoat/internal/coreerr"
+	"github.com/novusedge/stoat/internal/hostcheck"
 )
 
-func passingChecks() []core.HostCheck {
-	return []core.HostCheck{
+func passingChecks() []hostcheck.Check {
+	return []hostcheck.Check{
 		{Name: "qemu-system-x86_64", OK: true},
 		{Name: "qemu-img", OK: true},
 		{Name: "/dev/kvm", OK: true},
@@ -174,15 +175,15 @@ func TestCapabilitiesBoundaries(t *testing.T) {
 	}
 
 	t.Run("partial required host observations are unknown", func(t *testing.T) {
-		report := Build(Input{HostChecks: []core.HostCheck{{Name: "qemu-system-x86_64", OK: true}}})
+		report := Build(Input{HostChecks: []hostcheck.Check{{Name: "qemu-system-x86_64", OK: true}}})
 		profile := profileEntry(t, report.Profiles, "qemu-x86_64")
 		if profile.Status != "unknown" || profile.Reason == nil || profile.Reason.Code != "host_probe_unavailable" {
 			t.Errorf("qemu-x86_64 = %+v, want unknown/host_probe_unavailable", profile)
 		}
 	})
 
 	t.Run("failed fully observed host requirement is limited", func(t *testing.T) {
-		report := Build(Input{HostChecks: []core.HostCheck{
+		report := Build(Input{HostChecks: []hostcheck.Check{
 			{Name: "qemu-system-x86_64", OK: true},
 			{Name: "qemu-img", OK: false},
 			{Name: "/dev/kvm", OK: true},
@@ -197,7 +198,7 @@ func TestCapabilitiesBoundaries(t *testing.T) {
 	})
 
 	t.Run("empty host observations are unknown", func(t *testing.T) {
-		report := Build(Input{HostChecks: []core.HostCheck{}})
+		report := Build(Input{HostChecks: []hostcheck.Check{}})
 		profile := profileEntry(t, report.Profiles, "qemu-x86_64")
 		if profile.Status != "unknown" || profile.Reason == nil || profile.Reason.Code != "host_probe_unavailable" {
 			t.Errorf("qemu-x86_64 = %+v, want unknown/host_probe_unavailable", profile)
@@ -248,11 +249,11 @@ func TestCapabilitiesBoundaries(t *testing.T) {
 		}
 
 		for _, name := range []string{"", "../escape", "bad/name", "-bad", "_bad", "bad name"} {
-			if _, err := LoadTarget(name); !errors.Is(err, core.ErrInvalidSpec) {
+			if _, err := LoadTarget(name); !errors.Is(err, coreerr.ErrInvalidSpec) {
 				t.Errorf("LoadTarget(%q) error = %v, want ErrInvalidSpec", name, err)
 			}
 		}
-		if _, err := LoadTarget("missing"); !errors.Is(err, core.ErrNotFound) {
+		if _, err := LoadTarget("missing"); !errors.Is(err, coreerr.ErrNotFound) {
 			t.Errorf("LoadTarget(missing) error = %v, want ErrNotFound", err)
 		}
 		brokenDir := filepath.Join(root, "broken")
@@ -262,7 +263,7 @@ func TestCapabilitiesBoundaries(t *testing.T) {
 		if err := os.WriteFile(filepath.Join(brokenDir, "vm.toml"), []byte("name = \"broken\"\nmode = \"cloud\n"), 0o644); err != nil {
 			t.Fatal(err)
 		}
-		if _, err := LoadTarget("broken"); !errors.Is(err, core.ErrBroken) {
+		if _, err := LoadTarget("broken"); !errors.Is(err, coreerr.ErrBroken) {
 			t.Errorf("LoadTarget(broken) error = %v, want ErrBroken", err)
 		}
 	})

internal/capabilities/load.go

@@ -7,26 +7,26 @@ import (
 	"regexp"
 
 	"github.com/novusedge/stoat/internal/config"
-	"github.com/novusedge/stoat/internal/core"
+	"github.com/novusedge/stoat/internal/coreerr"
 )
 
 var targetNameRE = regexp.MustCompile(`^[A-Za-z0-9][A-Za-z0-9._-]*$`)
 
 // LoadTarget reads one VM's stored metadata without inspecting runtime state.
 func LoadTarget(name string) (Target, error) {
 	if !targetNameRE.MatchString(name) {
-		return Target{}, fmt.Errorf("%w: VM name %q", core.ErrInvalidSpec, name)
+		return Target{}, fmt.Errorf("%w: VM name %q", coreerr.ErrInvalidSpec, name)
 	}
 	path := filepath.Join(config.Root(), name, "vm.toml")
 	if _, err := os.Stat(path); err != nil {
 		if os.IsNotExist(err) {
-			return Target{}, fmt.Errorf("%w: %s", core.ErrNotFound, name)
+			return Target{}, fmt.Errorf("%w: %s", coreerr.ErrNotFound, name)
 		}
-		return Target{}, fmt.Errorf("%w: %s: %v", core.ErrBroken, name, err)
+		return Target{}, fmt.Errorf("%w: %s: %v", coreerr.ErrBroken, name, err)
 	}
 	v, err := config.Load(name)
 	if err != nil {
-		return Target{}, fmt.Errorf("%w: %s: %v", core.ErrBroken, name, err)
+		return Target{}, fmt.Errorf("%w: %s: %v", coreerr.ErrBroken, name, err)
 	}
 	return Target{Name: name, Mode: v.Mode, AgentAccess: v.AgentAccess}, nil
 }

internal/capabilities/model.go

@@ -1,6 +1,6 @@
 package capabilities
 
-import "github.com/novusedge/stoat/internal/core"
+import "github.com/novusedge/stoat/internal/hostcheck"
 
 const (
 	StatusSupported   = "supported"
@@ -103,6 +103,6 @@ type Evidence struct {
 type Input struct {
 	Version      string
 	ProjectState string
-	HostChecks   []core.HostCheck
+	HostChecks   []hostcheck.Check
 	Target       *Target
 }

internal/cli/cli.go

@@ -495,11 +495,15 @@ func Main(args []string, version string, stdin io.Reader, stdout, stderr io.Writ
 		return runDoctor(a, stdout, stderr)
 	}
 
-	// Every mutating or process-facing command must reject before resolving
-	// secrets, reading project scope, creating the data root, or initializing
-	// logs. The independent capabilities command is dispatched before this
-	// boundary by its owner and remains metadata-only.
-	if err := hostops.RequireVM(); err != nil {
+	// Every command past this point either drives a machine or writes to the
+	// data root, so an unqualified host refuses here, before secrets resolve,
+	// project scope is read, or a log is written.
+	//
+	// hostops.RequireDataRoot exists for the day a provider runs a VM
+	// somewhere other than this host. Moving these call sites onto it needs
+	// that provider first; opening the gate earlier only lets a macOS user
+	// reach a QEMU path that cannot work.
+	if err := hostops.RequireLocalHypervisor(); err != nil {
 		return a.fail(stdout, stderr, err)
 	}
 	if len(a.Params) > 0 {

internal/cli/run_access.go

@@ -110,7 +110,7 @@ func runSSH(a *Args, stdout, stderr io.Writer) int {
 		fmt.Fprintln(stderr, "stoat: ssh:", err)
 		return ExitFail
 	}
-	argv := append([]string{"ssh"}, sshx.Args(v)...)
+	argv := append([]string{"ssh"}, sshx.Args(sshx.LocalEndpoint(v))...)
 	if err := syscall.Exec(path, argv, os.Environ()); err != nil {
 		fmt.Fprintln(stderr, "stoat: ssh:", err)
 		return ExitFail

internal/cli/run_capabilities.go

@@ -7,8 +7,21 @@ import (
 	"github.com/novusedge/stoat/internal/capabilities"
 	"github.com/novusedge/stoat/internal/cli/wire"
 	"github.com/novusedge/stoat/internal/core"
+	"github.com/novusedge/stoat/internal/hostcheck"
 )
 
+// toHostChecks adapts core.Doctor's result to capabilities.Input.HostChecks.
+// The two types have identical fields but capabilities cannot import core:
+// core now imports provider, which imports capabilities, so the reverse
+// import would close a cycle.
+func toHostChecks(cs []core.HostCheck) []hostcheck.Check {
+	out := make([]hostcheck.Check, len(cs))
+	for i, c := range cs {
+		out[i] = hostcheck.Check{Name: c.Name, OK: c.OK, Detail: c.Detail, Fix: c.Fix, Optional: c.Optional}
+	}
+	return out
+}
+
 func runCapabilities(a *Args, version string, stdout, stderr io.Writer) int {
 	var target *capabilities.Target
 	if a.VM != "" {
@@ -25,7 +38,7 @@ func runCapabilities(a *Args, version string, stdout, stderr io.Writer) int {
 	report := capabilities.Build(capabilities.Input{
 		Version:      version,
 		ProjectState: projectState,
-		HostChecks:   core.Doctor(),
+		HostChecks:   toHostChecks(core.Doctor()),
 		Target:       target,
 	})
 	if a.JSON {

internal/config/config.go

@@ -94,6 +94,10 @@ type VM struct {
 	// Written by the form at creation time; dispatch elsewhere in stoat
 	// keys off Mode, not this field.
 	Backend string `toml:"backend"`
+	// Provider is the execution surface: "qemu" for a local hypervisor VM,
+	// or a cloud provider's name. Empty means "qemu", which is what every
+	// vm.toml written before this field existed says.
+	Provider string `toml:"provider,omitempty"`
 	// Base is the absolute path to the shared base image an overlay is
 	// created from. Cloud mode only.
 	Base string `toml:"base"`
@@ -202,7 +206,7 @@ func Root() string {
 
 // EnsureRoot creates the data root and its fixed subdirectories.
 func EnsureRoot() error {
-	if err := hostops.RequireVM(); err != nil {
+	if err := hostops.RequireLocalHypervisor(); err != nil {
 		return err
 	}
 	for _, d := range []string{"isos", "recipes"} {
@@ -276,7 +280,7 @@ func (v *VM) ISOPath() string {
 
 // Save writes vm.toml, creating the VM directory if needed.
 func (v *VM) Save() error {
-	if err := hostops.RequireVM(); err != nil {
+	if err := hostops.RequireLocalHypervisor(); err != nil {
 		return err
 	}
 	if v.Dir == "" {
@@ -381,7 +385,7 @@ var sshPortLine = regexp.MustCompile(`(?m)^\s*sshport\s*=\s*(\d+)\s*$`)
 
 // Delete removes the VM directory. It never touches isos/.
 func (v *VM) Delete() error {
-	if err := hostops.RequireVM(); err != nil {
+	if err := hostops.RequireLocalHypervisor(); err != nil {
 		return err
 	}
 	if v.Dir == "" || filepath.Dir(v.Dir) != Root() {

internal/core/access.go

@@ -2,6 +2,7 @@ package core
 
 import (
 	"bytes"
+	"context"
 	"errors"
 	"fmt"
 	"io"
@@ -30,7 +31,15 @@ func SSHCommand(name string) ([]string, error) {
 	if err != nil {
 		return nil, err
 	}
-	return append([]string{"ssh"}, sshx.Args(v)...), nil
+	p, err := providerFor(v)
+	if err != nil {
+		return nil, err
+	}
+	ep, err := p.Endpoint(context.Background(), v)
+	if err != nil {
+		return nil, err
+	}
+	return append([]string{"ssh"}, sshx.Args(ep)...), nil
 }
 
 // Which selects one of a VM's two log files.

internal/core/apply.go

@@ -13,7 +13,6 @@ import (
 	"github.com/novusedge/stoat/internal/backend"
 	"github.com/novusedge/stoat/internal/cloudinit"
 	"github.com/novusedge/stoat/internal/config"
-	"github.com/novusedge/stoat/internal/qemu"
 	"github.com/novusedge/stoat/internal/recipes"
 	"github.com/novusedge/stoat/internal/sshx"
 )
@@ -142,7 +141,11 @@ func resolveTargets(v *config.VM, only []string) ([]string, error) {
 
 // applyLocked is Apply's body, run while Apply holds name's provision lock.
 func applyLocked(ctx context.Context, v *config.VM, opts ApplyOpts) error {
-	if !qemu.Running(v) {
+	state, err := StateOf(ctx, v)
+	if err != nil {
+		return err
+	}
+	if state != StateRunning {
 		return fmt.Errorf("%w: %s", ErrNotRunning, v.Name)
 	}
 
@@ -283,10 +286,19 @@ func applyLocked(ctx context.Context, v *config.VM, opts ApplyOpts) error {
 func rebootAndWait(ctx context.Context, v *config.VM, recipe string) error {
 	appendProvisionLog(v, fmt.Sprintf("rebooting %s to finish %s...\n", v.Name, recipe))
 
+	p, err := providerFor(v)
+	if err != nil {
+		return err
+	}
+	ep, err := p.Endpoint(ctx, v)
+	if err != nil {
+		return err
+	}
+
 	// `reboot` tears down the ssh session before the process can report an
 	// exit status back to this host, so cmd.Run() returning an error here is
 	// expected and not a failure signal; only the wait below is.
-	cmd := exec.CommandContext(ctx, "ssh", sshx.Args(v, "reboot")...)
+	cmd := exec.CommandContext(ctx, "ssh", sshx.Args(ep, "reboot")...)
 	_ = cmd.Run()
 
 	// The pre-reboot sshd can keep answering for a moment after the reboot
@@ -328,7 +340,7 @@ func appendProvisionWarnings(v *config.VM, warnings []string) {
 
 // discoverCloudInitApplied rebuilds v.Applied for a cloudinit VM from the
 // marker files cloud-init left after first boot. It runs over ssh, so the VM
-// must be reachable; applyLocked calls it only after the qemu.Running check.
+// must be reachable; applyLocked calls it only after the running check.
 //
 // It no-ops unless the backend is cloudinit and v.Applied is still empty: once
 // a post-boot Apply has recorded state, that state is authoritative and this
@@ -344,7 +356,15 @@ func discoverCloudInitApplied(ctx context.Context, v *config.VM) ([]string, erro
 		return nil, nil
 	}
 	script := fmt.Sprintf("for marker in %s/*; do case \"$marker\" in *.out) continue;; esac; [ -f \"$marker\" ] || continue; name=$(basename \"$marker\"); printf '===%%s\\n' \"$name\"; cat \"$marker.out\" 2>/dev/null; done", cloudinit.MarkerDir)
-	out, err := exec.CommandContext(ctx, "ssh", sshx.Args(v, script)...).Output()
+	p, err := providerFor(v)
+	if err != nil {
+		return nil, err
+	}
+	ep, err := p.Endpoint(ctx, v)
+	if err != nil {
+		return nil, err
+	}
+	out, err := exec.CommandContext(ctx, "ssh", sshx.Args(ep, script)...).Output()
 	if err != nil {
 		return nil, nil // marker dir missing or a transient ssh error; discover nothing
 	}