feat(lume): implement macOS backend with identity-pinned clones

CHANGELOG.md

@@ -1 +1,10 @@
 # Changelog
+
+## Unreleased
+
+### Added
+
+- Optional Lume macOS backend with identity-pinned clones, durable sandbox
+  metadata, snapshot recovery, SSH guest execution, and SFTP file transfer.
+- Mac platform dispatch and the Tahoe desktop seed catalog entry. Deployment
+  qualification remains pending the server VM's source-restricted SSH setup.

README.md

@@ -43,7 +43,7 @@ images_file: images/catalog.yaml
 
 OVN requires the fleet-managed central, chassis TLS configuration, and physical uplink. To use the bridge fallback, set `default_network_kind: bridge` and configure `incus.host`.
 
-Pass its path with `--config` or `AGENTCOMPUTE_CONFIG`. YAML and TOML are strict: unknown keys fail startup. Catalog and certificate paths resolve relative to the configuration file.
+Pass its path with `--config` or `AGENTCOMPUTE_CONFIG`. YAML and TOML are strict: unknown keys fail startup. Catalog and credential paths resolve relative to the configuration file.
 
 Run the local STDIO transport:
 
@@ -57,7 +57,9 @@ Run Streamable HTTP on its loopback default:
 go run ./cmd/agentcompute http --config agentcompute.yaml --addr localhost:8080
 ```
 
-Both commands build shared Incus, catalog, compute, and CodeMode dependencies once. HTTP reuses them across sessions. Startup reconciles digest-pinned images; upstream `remote:alias` images are fetched on first use.
+Both commands build shared backend, catalog, compute, and CodeMode dependencies once. HTTP reuses them across sessions. Startup reconciles digest-pinned Incus images; upstream `remote:alias` images are fetched on first use. Mac `seed:` entries remain host-local and bypass Incus reconciliation.
+
+For Mac guests, configure the optional Lume backend using the [macOS runbook](images/macos/README.md#configure-the-server). Create a sandbox with `platform="mac"` and select `macos/tahoe/desktop`. Mac guests use Lume's NAT network; cluster placement and network overrides are unsupported.
 
 For a local MCP client, build the binary and configure its absolute path:
 
@@ -97,9 +99,9 @@ OVN instances may use an explicit online `host`. Without one, placement prefers
 
 An OVN network with `nat=false` is isolated: it has no direct outside path and consumes no external address. Attach a router instance or use `net.peer` for reachability. Isolated networks reject external forwards. Operator-management and OOB denies are immutable, including against broader user allow rules.
 
-Restoring a snapshot stages a copy before deleting the current instance, then recreates it under the same agent-visible name and ownership. The Incus identity and NIC MAC can change, so the DHCP lease can change too; the original instance's snapshots are consumed. Low-level Incus access remains blocked.
+On Incus, restoring a snapshot stages a copy before deleting the current instance, then recreates it under the same agent-visible name and ownership. The Incus identity and NIC MAC can change, so the DHCP lease can change too; the original instance's snapshots are consumed. Low-level Incus access remains blocked. Lume snapshots are stopped host-local clones: creating one temporarily stops a running guest, and restoring one retains the named snapshot for reuse.
 
-Exec retains 64 KiB per stream while draining the rest. `stdout_truncated` and `stderr_truncated` report overflow. An exec-only timeout returns `timed_out=true`; caller cancellation remains an error. `user` accepts a numeric UID or `root`. macOS is not available.
+Exec retains 64 KiB per stream while draining the rest. `stdout_truncated` and `stderr_truncated` report overflow. An exec-only timeout returns `timed_out=true`; caller cancellation remains an error. Linux `user` accepts a numeric UID or `root`. Mac exec defaults to `lume` (UID 501); other numeric UIDs and `root` require guest sudo access. Windows exec uses the Incus agent service identity and does not accept `user`.
 
 Only `main()`'s final converted value is returned. Intermediate capability results remain inside the worker and do not enter the model's context.
 

go.mod

@@ -9,10 +9,12 @@ require (
 	github.com/meigma/codemode v0.2.1
 	github.com/modelcontextprotocol/go-sdk v1.7.0
 	github.com/pelletier/go-toml/v2 v2.4.3
+	github.com/pkg/sftp v1.13.11
 	github.com/spf13/cobra v1.10.2
 	github.com/spf13/viper v1.21.0
 	github.com/stretchr/testify v1.12.1
 	go.yaml.in/yaml/v3 v3.0.5
+	golang.org/x/crypto v0.55.0
 	golang.org/x/image v0.31.0
 )
 
@@ -51,7 +53,6 @@ require (
 	github.com/opencontainers/runtime-spec v1.3.0 // indirect
 	github.com/opencontainers/umoci v0.6.1-0.20251213054154-70fc5ee1f4df // indirect
 	github.com/pkg/errors v0.9.1 // indirect
-	github.com/pkg/sftp v1.13.11 // indirect
 	github.com/pkg/xattr v0.4.12 // indirect
 	github.com/rogpeppe/go-internal v1.15.0 // indirect
 	github.com/rootless-containers/proto/go-proto v0.0.0-20260207013450-f6ee952d53d9 // indirect
@@ -77,7 +78,6 @@ require (
 	go.opentelemetry.io/otel/trace v1.44.0 // indirect
 	go.starlark.net v0.0.0-20260708150628-5395d018f003 // indirect
 	go.yaml.in/yaml/v4 v4.0.0-rc.6 // indirect
-	golang.org/x/crypto v0.55.0 // indirect
 	golang.org/x/net v0.57.0 // indirect
 	golang.org/x/oauth2 v0.36.0 // indirect
 	golang.org/x/sync v0.22.0 // indirect

images/catalog.yaml

@@ -80,3 +80,17 @@ images:
   memory_mb: 4096
   disk_gb: 100
   alias: windows/server-2025-26100.32230
+# macOS images are host-local Lume seeds, not registry digests. The seed name
+# is the stopped VM on the Mac host; clones inherit operator TCC consent.
+- name: macos/tahoe/desktop
+  os: macos
+  version: '26.6.2'
+  platform: mac
+  kinds:
+  - vm
+  kind: vm
+  desktop: true
+  cpus: 4
+  memory_mb: 8192
+  disk_gb: 100
+  seed: ac-seed-macos-tahoe-desktop