docs: design Huge Blue app-server inspection route

Draft
TE
16d ago
+89-0

Problem

Huge Blue/app-server inspection needs a read-only, typed visibility contract, but the current Run attach work is deliberately scoped to terminal ticket redemption. The existing SSH/session registry and cmux-tui trusted-carrier probes already provide the identity and enrollment facts needed for inspection.

Change

This draft PR records the follow-up design for issue #21332:

  • define disabled, unavailable, unenrolled, and admitted inspection states;
  • bind SSH-backed inspection to the registered SSHHost/session identity;
  • reuse Cloud app-server cloud.machine.list/cloud.machine.connect_info and the trusted-carrier/enrollment probe where applicable;
  • keep provider credentials, terminal tokens, shell commands, raw route addresses, and arbitrary provider metadata out of the response;
  • keep Huge Blue execution-provider admission and Run attach-ticket redemption out of scope.

The implementation PR should follow this design once the owner of the app-server route confirms whether the inspection endpoint belongs on the Cloud app-server path or authenticated VM API path.

Validation

  • git diff --check
  • Documentation-only change; no native build required.

Closes #21332


View with [code]smith Autofix with [code]smith
Need help on this PR? Tag @codesmith-bot with what you need.


Summary by cubic

Adds a design document for a read-only Huge Blue app-server inspection route, defining four inspection states and the proposed response shape.

Design notes

  • Reuses the existing SSHHost/session registry and cloud.machine.list/connect_info instead of introducing new credentials.
  • Keeps provider credentials, terminal tokens, shell commands, and raw route addresses out of responses.
  • Leaves the endpoint path and transport envelope open until the route owner confirms the serving API path.