[Refactoring] Split src/cloud-hypervisor-runtime-backend.ts into focused modules #8512

Refactoring Opportunity

Summary

• File: src/cloud-hypervisor-runtime-backend.ts
• Current size: 881 lines
• Responsibilities identified: 4 distinct concerns bundled into one ExternalAgentRuntimeBackend class

Evidence

The CloudHypervisorRuntimeBackend class (lines 211–880) mixes:

1. Boot orchestration — readonly start (lines 251–402, ~150 lines) drives infrastructure resolution, filesystem write-policy planning, and a 3-attempt boot retry loop with per-attempt manager creation.
2. Guest execution — readonly exec (lines 403–480) wires stdin forwarding, cancellation, and result handling for the running guest command.
3. Readiness/connectivity probing — probeGuestConnectivity (lines 577–714, 137 lines) and waitForGuestNetworkReady (lines 715–790, 75 lines) implement TCP/ping-style readiness checks with retry/backoff.
4. Cleanup/diagnostics — stop, preserve, stopManager, cleanupArtifactSnapshot, cleanupFailedBootAttempt (lines 481–880) handle teardown, diagnostics capture, and artifact-snapshot removal on failure.

probeGuestConnectivity alone spans 137 lines and waitForGuestNetworkReady spans 75 lines — both exceed the 80-line "long function" heuristic for a security-relevant boundary (guest network readiness gating before agent traffic is allowed through Squid).

Proposed Split

src/cloud-hypervisor-runtime-backend.ts (881 lines) could be split into:

• src/cloud-hypervisor/runtime-backend.ts — orchestration facade implementing ExternalAgentRuntimeBackend (preflight, start, exec, stop, preserve) delegating to the modules below (~250 lines)
• src/cloud-hypervisor/runtime-boot-loop.ts — boot-attempt retry loop, manager creation, filesystem write-policy wiring (~200 lines)
• src/cloud-hypervisor/runtime-readiness.ts — probeGuestConnectivity and waitForGuestNetworkReady (~230 lines)
• src/cloud-hypervisor/runtime-cleanup.ts — stopManager, cleanupArtifactSnapshot, cleanupFailedBootAttempt, captureGuestNetworkStateForDiagnostics (~200 lines)

Affected Callers

src/external-runtime-backend-resolver.ts
src/cloud-hypervisor-runtime-backend.env-mapping.test.ts
src/cloud-hypervisor-runtime-backend.test.ts

Only the resolver imports the class in production code; the split can preserve the current export surface (CloudHypervisorRuntimeBackend) as a re-export facade, matching the pattern already used for src/docker-manager.ts.

Effort Estimate

Medium

Benefits

• Isolates the security-relevant readiness/connectivity-probing logic for focused review and testing
• Shrinks the largest function in the file (685-line class body → ~200-line modules)
• Makes the boot-retry state machine independently testable without the full class

Detected by Refactoring Scanner workflow. Run date: 2026-09-13

Generated by Refactoring Opportunity Scanner · copilot · auto · 95.2 AIC · ⊞ 10.4K · ◷

• expires on Nov 12, 2026, 3:06 PM UTC