Repository navigation
fix(docs): warmup states obsolete direct-lease retention rules #2996
Description
Summary
The warmup command guide gives obsolete direct-lease cleanup guidance: it promises a 12-hour running/provisioning grace and says manual cleanup always skips kept machines, including expired ones. The cleanup guide, lifecycle guide, release notes, and current implementation describe a one-hour grace and no keep exemption from expiry. Readers planning retention from the warmup page therefore receive conflicting guidance about when their direct machines become eligible for reclamation.
Runtime or environment
Source inspection covered the latest published release, v0.80.0 at 4431387c9ae4a132972f8b8d97f9bc725bce1168, and current main at ae86f38cee7fc505397bfaf266154314bd38cb42. The relevant warmup, cleanup, lifecycle, shared decision, guest guard, GCP cleanup adapter, and cleanup-test files are identical between these baselines. This is a documentation/source comparison; no cloud resources were created, expired, or deleted, and no data loss was observed.
Steps to reproduce
- At either inspected baseline, read
docs/commands/warmup.md, the “Lifetime: TTL and idle timeout” section, especially lines 175–191. - Compare its 12-hour stale-state grace and unconditional manual-cleanup exemption for
keep=trueagainstdocs/commands/cleanup.md:82–102anddocs/features/lifecycle-cleanup.md:684–709. - Inspect
internal/cli/pool.go:581–612,internal/cli/guest_expiry.go:50–73, andinternal/cli/pool_test.go:84–101. The shared Go decision and shell guard use a one-hour running/provisioning grace and do not exempt kept leases; the test explicitly expects kept expired leases to be reclaimable.
These inspection steps were performed on both baselines. Runtime cleanup and the tests themselves were not executed.
Expected behavior
The warmup lifetime guidance should describe the same retention contract as the cleanup/lifecycle documentation and implementation: keep=true preserves reuse after command exit but does not exempt an eligible direct lease from recorded expiry, and running/provisioning expiry decisions use a one-hour grace. Provider-specific qualifications should stay explicit, including GCP guest self-delete permissions and the adjoining Tenki exception for sticky kept leases.
Actual behavior
The warmup guide still states a 12-hour stale-state grace for GCP running/provisioning guests and says manual cleanup always skips keep=true, including expired machines. Both statements disagree with the linked cleanup guidance. The lifecycle guide explicitly identifies the old keep exemption and 12-hour window as superseded behavior.
The GCP cleanup adapter calls the shared decision, then requires an exact local claim and revalidates live identity and expiry before applying deletion. Thus the stale documentation is not evidence that arbitrary or unowned machines are deleted. Likewise, the adjoining Tenki-specific exception does not explain the blanket statement about manual cleanup or the GCP grace period.
Evidence
- Expected source: cleanup deletion decisions and lifecycle sweep/guard contract.
- Failure source: warmup lifetime guidance and adjoining Tenki exception.
- Evidence provenance: observed
- Local verification: static-proof
- Reproduction completeness: complete
Fresh source inspection directly observed the documentation contradiction; implementation and tests supply corroborating static evidence. Runtime cleanup reproduction was not run. The failing user-facing path is reading the warmup command's lifetime guidance for direct leases and following its link to the contradictory cleanup guide; no cloud state is needed to reproduce that contradiction.
Corroborating implementation: shared cleanup decision, guest decision, kept-expiry test, and GCP cleanup reachability and ownership/expiry checks.
Restoration check
Reading the warmup lifetime section and then the cleanup/lifecycle guides should yield one consistent answer for an owned direct lease with valid expiry metadata: kept leases remain subject to expiry, and running/provisioning eligibility starts only after expiry plus one hour. The warmup page should no longer promise an unconditional kept-machine cleanup exemption or a 12-hour GCP grace. Preserve the distinct Tenki and GCP-permission qualifications; changing cleanup behavior to match the obsolete prose would not restore documentation consistency with the current contract.
References
- Closed issue #2536 concerned the earlier warmup default and kept-lease idle reaping. This report concerns the obsolete guidance that remains after subsequent behavior changes; it does not request a new retention default.
- Merged PR #2553 introduced warmup retention configuration and the earlier GCP guard behavior.
- Merged PR #2806 changed direct cleanup/guest expiry to the current keep and one-hour rules; the release upgrade notes describe that change.
Triage assessment
- Impact level: P2
- Assessment status: provisional
- Impact basis: Readers may expect an expired kept direct machine to survive manual cleanup, or rely on a grace window eleven hours longer than the implemented window. That is operational retention guidance with a potential resource-loss consequence, rather than a cosmetic wording difference; no destructive incident or data loss was observed, and actual user reach is unknown.
- Workaround status: available
- Workaround basis: The cleanup and lifecycle guides already state the current rules, and cleanup documents a dry-run mode for inspecting eligible resources before mutation. Those sources let readers plan against the current contract without changing the CLI.
Activity
clawsweeper commentedon Nov 1, 2026
Codex review: this still needs some work.
Summary
This issue identifies a current documentation defect: warmup still promises retention protections that cleanup no longer provides, and no open fix was found.
Reproducibility: Reading current warmup guidance alongside cleanup documentation and both expiry implementations establishes the contradiction; no runtime cleanup or tests were executed.
Next step
Correct the two obsolete warmup promises and verify the revised text against cleanup decisions, existing expiry tests, and provider qualifications.
Review details
Best possible solution:
Make warmup retention guidance match the shipped expiry contract while preserving provider-specific qualifications.
Do we have a high-confidence way to reproduce the issue?
Reading current warmup guidance alongside cleanup documentation and both expiry implementations establishes the contradiction; no runtime cleanup or tests were executed.
Is this the best way to solve the issue?
A focused documentation correction is sufficient because the intended contract is already implemented, tested, and documented elsewhere.
AGENTS.md: found and applied where relevant.
Codex review notes: model internal, reasoning medium; reviewed against ae86f38cee7f.
Label changes
Label changes:
P2: Incorrect operational retention guidance can mislead users about reclamation timing, although accurate companion guides and cleanup dry-run are available.impact:other: The demonstrated impact is misleading resource-retention planning; no resource or data loss was observed.issue-rating: 🦞 diamond lobster: Current issue advisory state selects this label.clawsweeper:source-repro: Current issue advisory state selects this label.clawsweeper:queueable-fix: Current issue advisory state selects this label.clawsweeper:fix-shape-clear: Current issue advisory state selects this label.Label justifications:
P2: Incorrect operational retention guidance can mislead users about reclamation timing, although accurate companion guides and cleanup dry-run are available.impact:other: The demonstrated impact is misleading resource-retention planning; no resource or data loss was observed.Evidence reviewed
Acceptance criteria:
What I checked:
docs/commands/warmup.md:175, ae86f38cee7f)docs/commands/cleanup.md:82, ae86f38cee7f)internal/cli/pool.go:581, ae86f38cee7f)internal/cli/guest_expiry_test.go:32, ae86f38cee7f)internal/providers/gcp/backend.go:288, ae86f38cee7f)internal/cli/pool.go:590, c8010cb0fc95)How this review workflow works
@clawsweeper re-reviewcomments, exact-item GitHub events, scheduled/background review runs, or manual workflow dispatch.@clawsweeper re-reviewor@clawsweeper re-runon an open PR or issue to request a fresh review only.@clawsweeper reviewto request a fresh review only.@clawsweeper explainto ask for more context, or@clawsweeper stopto stop active automation.Reviewed November 1, 2026, 1:16 AM ET / 05:16 UTC.