[austinywang]

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 (feat(cmux-next): durable runs, attach bridge, and top-two UI tournament #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.

^{Written for commit 521f1f9. Summary will update on new commits.}

[coderabbitai]

Important

Review skipped

Auto reviews are disabled on base/target branches other than the default branch.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

• Configuration used: Repository: manaflow-ai/cmux/.coderabbit.yaml
• Review profile: ASSERTIVE
• Plan: Advanced
• Run ID: cc7d0197-0325-4983-a409-d343ac22abba

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

• 🔍 Trigger review

• Autofix · Keep fixing CodeRabbit findings and required CI, and resolving merge conflicts

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[teamleaderleo]

Bead cx-nfrdh created for this PR by the cmux coordinator.