#21365 cmux-next: read-only Huge Blue app-server inspection route

Problem

cmux-next has no read-only way to ask whether a registered Cloud machine can be inspected by the Huge Blue app server. The only Huge Blue surface today is the Run create refusal, and attach mints terminal credentials. Closes #21332. This implements slices 1 and 2 of the design in #21335, plus the Cloud probe from slice 3.

Change

• GET /api/vm/:id/huge-blue-inspection[?deviceFingerprint=…] sits behind withAuthedVmApiRoute, and the account and team scope come from resolveVmRouteAccountScope.
• The machine is looked up in the caller's own registry (owner or billing team) in every mode. An unknown or foreign id gets a 404 even when inspection is disabled or not configured.
• CMUX_HUGE_BLUE_INSPECTION sets the mode. enabled probes. disabled returns disabled/inspection_disabled. When unset, it returns unavailable/adapter_not_configured with retryable: false, which matches the Run route's Huge Blue refusal.
• Only machines that are running get probed, so inspection never wakes a paused machine. The probe is the existing read-only cmux-tui attach bundle (remote-probe, enrolled devices, trusted-carrier listener). It never runs enroll create or approve, records no lease or usage event, and does not call openCmuxRemote.
• hugeBlueInspection.ts is a pure mapper and the only place a probe becomes a state. It fails closed:
  • A missing, non-integer or non-positive daemon protocol gives unavailable/daemon_probe_unreadable and drops all carrier and enrollment evidence.
  • Enrollment only counts when the caller named the device fingerprint.
  • Values that are truthy but not booleans are ignored.
• The response has only the machine id, session, state, reason, retryability, timestamp and safe capability facts. It never contains tokens, routes, addresses, invitations or provider metadata.
• requireUserVm is now exported (no behavior change), so the read path skips the side effects of requireAccessibleUserVm.
• The contract and the state/reason table are documented in web/services/vms/README.md.

Out of scope, as the issue asks:

• Run attach tickets (#21305).
• Huge Blue as a Run execution provider.
• A client view (slice 4).
• SSH-backed SSHHost targets. Those live in the macOS client registry, not the web API. This route accepts only registered Cloud machine ids and never a raw route.

Validation

• bun test tests/huge-blue-inspection.test.ts: 19 pass. Covers:
  • the mapper states;
  • redaction;
  • malformed and contradictory evidence;
  • the workflow over fake layers: ownership in every mode, no exec when disabled, unconfigured or paused, nothing minted, exec failure, non-zero exit and garbled output;
  • the route: 401 before the workflow, scope and mode passthrough, 400 on a malformed fingerprint, 404 passthrough.
• bun test tests/vm-cmux-tui.test.ts tests/vm-snapshots-route.test.ts tests/vm-snapshots-workflow.test.ts tests/vm-route-auth.test.ts: 141 pass.
• bun run typecheck, eslint on the changed files and bun run lint:complexity are clean.
• This is a new feature, so there is no red regression commit to record.
• Not verified live against a running Cloud machine. No native build is needed because the change is web only.

Changelog

none

🤖 Generated with Claude Code

---

^{Need help on this PR? Tag @codesmith-bot with what you need.}

---

Summary by cubic

Adds a read-only route that reports whether one of the caller's registered Cloud machines can be observed by the Huge Blue app server, closing #21332.

Changes

• GET /api/vm/:id/huge-blue-inspection[?deviceFingerprint=…] sits behind the existing authenticated VM route helper, and ownership is checked from the owner or billing team in every mode, so foreign or unknown ids answer 404.
• CMUX_HUGE_BLUE_INSPECTION selects the mode: enabled probes, disabled refuses, and unset or any other value is unconfigured.
• The response is a typed state and reason (disabled, unavailable, unenrolled, admitted) and never contains tokens, routes, commands, or provider metadata.
• Only running machines are probed, so a paused machine is never woken; the probe reuses the read-only cmux-tui attach bundle and never mints or records anything.
• The mapper fails closed: missing, non-integer, or non-positive daemon protocol is unavailable/daemon_probe_unreadable, and enrollment counts only when the caller named the device fingerprint.
• Exports requireUserVm with no behavior change so the read path skips access-verb side effects.
• Documents the route contract and the state/reason table in web/services/vms/README.md.

Validation

• 19 new mapper/workflow/route tests and 141 existing tests pass; typecheck, eslint, and complexity lints are clean.