feat(devices): vm_host link groups — nest guest VMs under their host server (#2308)

[ToddHebebrand]

Closes #2308

Extends the #2138 device_link_groups mechanism (PR #2309) with the reserved asymmetric kind vm_host: one member is the host server, the rest are its guest VMs, nested under the host's row in the Devices list. Host + guests are concurrently online — no expected-offline collapse, no active-profile election; guests stay fully managed endpoints (own row, selectable, bulk-op visible). Auto-suggestion/detection is explicitly out of scope (follow-up per the issue).

API

• Migration 2026-07-10-vm-host-link-groups.sql — devices.link_group_role varchar(16) (idempotent ADD COLUMN IF NOT EXISTS, no inner BEGIN/COMMIT). NULL for unlinked devices and multiboot peers; 'host' | 'guest' for vm_host members — app-enforced values, matching kind's varchar-without-CHECK convention. No RLS change: devices is already covered and the Add linked device profiles for multi-boot systems #2138 composite FK keeps enforcing the same-org invariant. Invariant: link_group_id IS NULL => link_group_role IS NULL (every unlink path clears both).
• createLinkGroupSchema: kind ('multiboot' default so existing clients are untouched) + hostDeviceId; superRefine requires hostDeviceId for vm_host, rejects it for multiboot, and requires it to be one of deviceIds.
• POST /devices/link-groups claims the host and the guests in role batches under the same TOCTOU row-count guard; PATCH add links newcomers as guests via a split claim so a no-op re-add can never demote the host; remove/moveOrg/unlink all clear the role with the membership.
• dissolveLinkGroupIfBelowMinimum is now kind-aware: any group below 2 members dissolves (unchanged); a vm_host group additionally dissolves when headless — its host was unlinked, moved org, or hard-deleted while guests remain. moveOrg and cascade-delete paths get this for free through the shared helper.
• Devices list response carries linkGroupRole per row (non-null role implies kind vm_host), so the web list nests without a group-table join. Link-group GET payloads include each member's role.

Web

• groupLinkedDevices reorders guest rows directly beneath their host as full rows with vmRole/vmGroupId markers — the multiboot strip/bar heuristics deliberately never apply to vm_host groups. Host off-page → guests render ungrouped (same pagination caveat as multiboot).
• DeviceList: chevron expand/collapse on the host row (transient per-visit state, default expanded), left-edge bracket + corner glyph on guest rows, "N guest VMs hidden" strip when collapsed. Collapsed (hidden) guests are excluded from select-all — no invisible selection.
• New bulk action "Link as VM host + guests" → LinkVmHostModal host picker (radio list of the selection) → linkDevicesVmHost service call; toasts + refetch mirror the multiboot path.
• Linked Profiles tab: vm_host heading + guest count, Role column (Host/Guest badges), host sorted first, and a warning on "Unlink this device" when the current device is the host (unlinking it dissolves the group).

Verification

• apps/api: links.test.ts (8 new vm_host cases), new deviceLinkGroups.test.ts kind-aware dissolve suite, moveOrg.test.ts role-clear assertion, cascadeDelete.test.ts, links.mountorder.test.ts — 55 passed, single-fork.
• Integration (real Postgres :5433, breeze_app): deviceLinkGroupsRls.integration.test.ts — 6 passed, including the new vm_host headless-dissolve case (guest count ≥ 2 so only the headless rule can fire); migration applied cleanly via autoMigrate.
• apps/web: linkedDevices.test.ts (6 new), DeviceList.test.tsx (5 new), DeviceLinkedProfilesTab.test.tsx (3 new), new LinkVmHostModal.test.tsx — 85 passed. no-silent-mutations guard green.
• tsc --noEmit clean in both apps/api and apps/web (no .astro touched); pnpm db:check-drift clean (384 migrations match ledger).

🤖 Generated with Claude Code

[cloudflare-workers-and-pages]

Deploying breeze with    Cloudflare Pages

Latest commit:	e22440f
Status:	✅  Deploy successful!
Preview URL:	https://29f281eb.breeze-9te.pages.dev
Branch Preview URL:	https://feat-2308-vm-host-link-group.breeze-9te.pages.dev

View logs

[ToddHebebrand]

Review run: /pr-review-toolkit:review-pr — code-reviewer, silent-failure-hunter, pr-test-analyzer, plus a focused code-reviewer verification pass on the fix commit.

Findings: 8 raised → all addressed; 0 outstanding.

• pr-test-analyzer (2 + 2 optional, addressed in db0c7554): linkGroupId/linkGroupRole added to the core.list-response-shape contract test (the Server should detect main-agent silence while watchdog stays online #800/feat(devices): expose mainAgentSilentSince + watchdogStatus on list endpoint (#800 web-UI gap) #861/feat: Pending Reboot indicator on device list and detail views #1273 dropped-field failure mode — a dropped role would silently un-group every guest); the link-vm-host action-string chain now driven end-to-end in DevicesPage.test.tsx (bulk action → real modal → confirm → service args → refetch, plus the failure path); linkDevicesVmHost wire-body test; vm_host create audit assertion.
• code-reviewer (1 important, addressed in 872cdb4c): vm_host nesting was coupled to the multiboot-only "Collapse linked inactive profiles" toggle — decoupled; the toggle now gates only the multiboot strip/bar heuristics and is hidden for vm_host-only fleets.
• silent-failure-hunter (1 high / 1 medium / 3 low, addressed in 872cdb4c): move-org and hard-delete now record { linkGroupId, linkGroupDissolved } in audit details (a host move can unlink every guest — previously untraceable); the dissolve helper's impossible missing-group-row branch is now loud (console.error + Sentry); unknown linkGroupRole values warn once per value; the Role badge renders a dash instead of asserting "Guest" for null/unknown; collapsing a group deselects its hidden guests so no invisible row stays a bulk-action target. One accepted-by-design note: site-scope member filtering renders partial groups for restricted callers, identical to the existing multiboot posture.
• Verification pass on 872cdb4c: clean — toggle-ON multiboot behavior byte-identical, deselect-on-collapse uses functional state correctly, audit spreads type-safe.

Tests: affected API suites green single-fork (links, deviceLinkGroups, moveOrg, cascadeDelete, core.list-response-shape, links.mountorder — 55 passed); real-DB integration deviceLinkGroupsRls green incl. the new vm_host headless-dissolve case (6 passed, breeze_app on :5433); affected web suites green (linkedDevices, DeviceList, DeviceLinkedProfilesTab, DevicesPage, LinkVmHostModal, deviceActions, no-silent-mutations — 189 passed); tsc --noEmit clean in apps/api and apps/web; pnpm db:check-drift clean.

Status: review-clean, awaiting maintainer merge.