Report real vGPU capacity and preserve create failure causes

[yummybomb]

Fixes the two remaining findings from the vGPU stack review (#366 → #322 → #363 → #364 → #321). Based on the stack top so it can be folded into #364/#321 or merged after, same shape as #377.

1. available counted candidate VFs, not concurrent capacity (#364)

listProfiles counted every free VF advertising a type as one creatable instance. Sibling VFs share their parent GPU's framebuffer, so a single 48Q assignment revokes the type from every other VF on that GPU — /resources and gpuProfileSlots could advertise dozens of slots where one per parent GPU exists, inviting placement bursts that mostly fail.

listProfiles now reports a conservative per-parent-GPU estimate: each GPU contributes min(free VFs advertising the type, remaining framebuffer / profile framebuffer), using the largest profile still creatable on the GPU as a lower bound on its remaining framebuffer (the driver only advertises a type that fits). Unlike the earlier per-parent-GPU variant this doesn't collapse small profiles to 1 per GPU — a 48G GPU with free VFs still reports 24× 2Q — while large profiles stop being overcounted. Profiles with unparseable framebuffer fall back to the free-VF count. OpenAPI description and the hypeman_resources_gpu_profile_slots metric description updated to match (lib/oapi/oapi.go regenerated via make oapi-generate).

2. vgpu_cleanup_pending hid the original create failure (#321)

Both retained and unretained messages replaced the create error with cleanup guidance; the cause survived only in server logs. The response message now leads with the wrapped error before the guidance. InnerError is unchanged (vgpu_retained_instance/vgpu_unretained_instance code + instance ID) so programmatic recovery keeps working.

Tests

• TestVendorVFIOListProfilesReportsPerGPUCapacity — 3 free VFs across 2 GPUs: 48Q reports 2, 2Q reports 3.
• TestVendorVFIOListProfilesCapsCapacityByRemainingFramebuffer — GPU with a 24Q assigned: one more 24Q despite two free VFs; 1Q stays VF-capped.
• Extended both vgpu_cleanup_pending handler tests to assert the cause survives.
• go build ./... and go test ./lib/devices ./lib/resources pass; cmd/api/api unit tests for the touched handler pass (the package's KVM/registry-dependent tests fail here on clean HEAD too).

[github-actions]

-->

✱ stlc build

✅ go code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

112 files generated at 20a5d1e (pushed)

go get github.com/kernel/hypeman-go-staging@20a5d1e4c80327bb8eb2da1cea718365b04db1da

✅ typescript code · compare

Your SDK build was successful.

generate ✅ → bootstrap ✅ → format ✅

134 files generated at 9fab810 (pushed)

Diagnostics: 💡 0 new / 5 total note

Level	Code	Message	Targets

Build metadata

Build	bd_766pFWLL-tiny-mist
Timestamp	2026-08-10T16:16:04.035Z
stlc	8413509
Spec hash	f335d050c4cd
Config hash	9125eb22cb4c

---

This comment is auto-generated by stlc and is kept up to date as you push.
If you push new commits, re-run this workflow to update this comment.
Last updated: 2026-08-10 16:16:25 UTC

[yummybomb]

folding these directly into #364 and #321 instead