[Brad-Edwards]

Summary

Complete failed-start recovery already introduced by #1266: preserve anonymous node volumes during non-destructive cleanup, direct recovery commands to the selected project, and account for operational and appliance readiness failures under the start lifecycle lock.

Requirement UIDs

• (none — bug/refactor/maintenance run; see Traceability section below)

Related Issues

Closes #952

ADR Impact

• ADR-029
• ADR-030
• ADR-031

Changes

• Residue and recovery: default failures retain the range for diagnosis; counts and unknown observations reach the CLI, and pre-existing-range guidance shares project-qualified commands and accurate data consequences.
• Opt-in cleanup: carry remove_volumes=False through direct and residual Compose container removal; retain named and anonymous node data, keep disposable helper cleanup, and preserve volumes during ownership-capture compensation.
• Lock ordering: observe residue, perform cleanup and verify absence under the start owner. Publish finite guest readiness there; enter long-lived access supervision after releasing both normal and clean-start owners.
• Tests and docs: cover default and teardown paths, foreign/pre-existing protection, secondary cleanup failures, network-only residue, anonymous volume retention, recovery targets and actual guest channel sequencing. Document retained anonymous-volume and uncertain-ownership limits.

Test Plan

• Unit tests pass
• Integration tests pass if applicable
• Full completion suite required in CI before merge
• No coverage regression

Observed regression failures before implementation. The affected-file run passed 807 tests with one skip and one outdated stderr assertion; that assertion and the reviewer’s guest-access test now pass (3 targeted repair tests). Additional acceptance/appliance checks: 95 passed, plus 2 actual guest channel tests. Staged pre-commit and changed-source complexity checks pass. Hosted CI owns whole-tree and real lab qualification.

Ground Control Checks

• Repository policy checks required in CI before merge
• Pre-push Codex review completed; all findings fixed or dispositioned

Traceability

• IMPLEMENTS: Issue Failed aptl lab start leaves the whole range running with no teardown guidance #952: core lifecycle failure accounting, receipt-owned cleanup and shared recovery rendering; existing requirement links remain valid.
• TESTS: tests/test_lab.py; tests/test_cli.py; tests/test_compose_resource_ownership.py; tests/test_deployment_backend.py; tests/test_stranded_helper_cleanup.py; tests/test_seat_image_runtime.py.

Checklist

• Code follows the project's coding standards
• Changelog: owned by Release Please (generated from the Conventional Commit PR title; no per-PR fragment)
• Architectural docs updated if stack, package structure, or key behaviors changed

Documentation

Updated: see diff.

[Brad-Edwards]

Ground Control delivery — this pull request delivers issue #952; Phase E runs on merge.