feat: Packer build orchestration (SAND-WP-0012)

Add vm-packer build mode, profile.vm-packer-build, State Hub progress
notes during long provision, docs/runbook, and build mode tests.

docs/extension-sdk.md

@@ -33,7 +33,7 @@ Reference implementations:
 | Extension | Module | Mode |
 |-----------|--------|------|
 | `ext.compose-ssh` | `compose_ssh.py` | Remote compose stack + tar snapshots |
-| `ext.vm-packer` | `vm_packer.py` | Attach workspace on pre-built VM |
+| `ext.vm-packer` | `vm_packer.py` | Attach workspace or Packer build mode |
 | `ext.saas-stub` | `saas_stub.py` | Metered stub + metadata snapshots |
 | `ext.e2b` | `e2b.py` | E2B cloud adapter |
 | `ext.modal` | `modal.py` | Modal cloud adapter |
@@ -82,7 +82,8 @@ Profiles declare semantics; extensions validate required `inputs` keys:
 | Extension | Required inputs | Optional |
 |-----------|-----------------|----------|
 | compose-ssh | `repo` | `sandbox_id` |
-| vm-packer | `vm` or `ssh_target` | `repo`, `tunnel_port`, `ssh_port`, `workspace_dir` |
+| vm-packer (attach) | `vm` or `ssh_target` | `repo`, `tunnel_port`, `ssh_port`, `workspace_dir` |
+| vm-packer (build) | `packer_template`, `vm_name` | `mode=build`, `packer_var_*` |
 
 Consumer attribution travels on `SandboxCreateRequest.consumer`, not extension inputs.
 

docs/migration-build-machines.md

@@ -8,7 +8,8 @@ Maps `the-custodian/infra/build-machines/` to sand-boxer `profile.vm-haskell-bui
 |-------------------------|---------------|
 | Packer OVA build | **Unchanged** — operator runs Packer in the-custodian |
 | VM boot + build-agent registration | **Unchanged** — systemd agent on VM |
-| `make remote-build PROJECT=` | `sandboxer create` + SSH into `reachability.remote_dir` |
+| `make remote-build PROJECT=` | `sandboxer create --profile profile.vm-haskell-build` + SSH build (shim in build-machines Makefile) |
+| `packer build` in `haskell/` | `sandboxer create --profile profile.vm-packer-build` |
 | Isolated workspace `/build/<project>` | `/build/sbx-<sandbox_id>/` per create |
 | `make bridge-status` | `ssh -p 12222 build@localhost` or `sandboxer inspect` (future) |
 
@@ -50,12 +51,36 @@ sandboxer destroy <sandbox_id>
 | `repo` | Optional rsync source to workspace |
 | `workspace_dir` | Override workspace path on VM |
 
+## Packer build mode (SAND-WP-0012)
+
+```bash
+sandboxer create \
+  --profile profile.vm-packer-build \
+  --input packer_template=~/the-custodian/infra/build-machines/haskell \
+  --input vm_name=haskell-build \
+  --host localhost
+```
+
+| Input | Purpose |
+|-------|---------|
+| `mode` | `build` (default for profile.vm-packer-build) or `attach` |
+| `packer_template` | Directory containing `*.pkr.hcl` |
+| `vm_name` / `vm` | Packer `vm_name` variable |
+| `packer_var_*` | Extra Packer `-var` flags (suffix → variable name) |
+
+Runbook: `docs/runbooks/profile-vm-packer-build.md`
+
+## Port registry (read-only pointer)
+
+`the-custodian/infra/build-machines/port-registry.yml` maps tunnel ports
+12221–12230 to VM slots. When attaching via tunnel, set
+`SANDBOXER_VM_TUNNEL_PORT` or `--input tunnel_port=` to a registered port.
+Full ops-bridge automation is deferred — operators bring tunnels up manually.
+
 ## Not migrated yet
 
-- Automated Packer `create` trigger from sand-boxer API
 - State Hub capability-catalog sync from build-agent (agent unchanged)
-- Port registry automation (`port-registry.yml`)
-- `make remote-build` Makefile targets in the-custodian (add shim in follow-on if needed)
+- Automated port-registry → ops-bridge config generation
 
 ## Runbook
 

docs/runbooks/profile-vm-packer-build.md

@@ -0,0 +1,54 @@
+# profile.vm-packer-build — Runbook
+
+Trigger a Packer OVA build on the local workstation (build-machines lineage).
+
+## Prerequisites
+
+- **Packer** >= 1.10 (`packer version`)
+- **VirtualBox** >= 7.0 (`VBoxManage --version`)
+- Template directory from `the-custodian/infra/build-machines/haskell`
+- `sandboxer` on PATH
+
+## Build OVA
+
+```bash
+sandboxer create \
+  --profile profile.vm-packer-build \
+  --input packer_template=~/the-custodian/infra/build-machines/haskell \
+  --input vm_name=haskell-build \
+  --host localhost
+```
+
+Progress notes emit to State Hub during `packer init` and `packer build`.
+
+On success, `reachability.remote_dir` points at the produced `.ova` file.
+
+## Optional Packer variables
+
+Pass extra `-var` flags via inputs prefixed with `packer_var_`:
+
+```bash
+sandboxer create \
+  --profile profile.vm-packer-build \
+  --input packer_template=~/the-custodian/infra/build-machines/haskell \
+  --input vm_name=haskell-build \
+  --input packer_var_memory=16384 \
+  --host localhost
+```
+
+## Destroy
+
+```bash
+sandboxer destroy <sandbox_id>
+```
+
+Removes the sandbox record only; the OVA artifact on disk is preserved.
+
+## Attach workflow (post-build)
+
+After import/setup per build-machines README, use `profile.vm-haskell-build`
+for workspace attach — see `docs/runbooks/profile-vm-haskell-build.md`.
+
+## Migration reference
+
+`docs/migration-build-machines.md`