docs: explain cleanup recovery ordering and retention acceptance #44

B+C publication update — 2026-11-10

This update supersedes the unmerged-candidate identity and native-resource blocker in the retained preparation text below; the historical records remain unchanged.

• Source engine issue: #111. Published engine PR: #169.
• Status: pending engine merge. Exact PR head: 2fd162abe31fd6d90e73ae5ea62f78f58efe2f74, tree eae28ec92bd242ebe9c9c84c853509ff24ed0c11, base a56fad2c47bf6b3f80e839af69615a2b42fc1461. Actual merged engine commit: pending.
• Retention runtime/test/maintenance-doc blobs are identical to final authored B db85025eb655fd3d26925a227ad2165a04f303f1. Original Council covered predecessor 44d27cb30bf6763967bb3078caaf258463b95f4c; accepted documentation corrections were subsequently applied. Original C Council covered ef388be5261a2eff21b0304cfd894817010ae85a, followed by wording corrections and integration clarifications. Both owners closed exact-source handoffs. One fresh GPT-6.1 Sol/high changed-documentation/integration review APPROVED exact head 2fd162abe31fd6d90e73ae5ea62f78f58efe2f74, with no blocking introduced issues or actionable nits. It verified source claims, blob mappings, 47-document links, whitespace and the native report hash/metadata; no unchanged-runtime/native rerun or host access occurred. Original Council scores remain attached only to their original revisions. Required hosted validation is still absent because its workflow is manually disabled; no bypass or replacement check is authorized.
• Full exact-source local_validate.py passed all eight stages with no expected skips, using independently selected base/main/policy/executor a56fad2c47bf6b3f80e839af69615a2b42fc1461. All eight exported stage-log hashes were verified. Report SHA-256: 01341dccbdc8f3ea1db120340eb3cdaac24cc41a3593b6c21362b889abf72f04. This is unsigned native validation, not signed policy-v2 acceptance or a substitute for required hosted checks/reviews. No repeated native run was needed for this tracking update.
• Resulting behavior: successful default-builder prune reports command completion, not measured reclamation; documentation separates completion, deferral, measured headroom and admission recovery. It adds no deletion authority or admission producer. The separate pre-existing JSON-inventory deadline gap remains disclosed and unfixed.
• Template gap assessment is unchanged: docs/UPDATING.md and its README pointers already distinguish measured capacity from Docker counts/estimates and retain maintenance/recovery gates. No duplicate guidance implementation, schema/desired-state/initializer/validator/evidence-field addition or compatibility-pin promotion is needed for this wording-only correction. Pending admission/observer guidance remains separate in #49.
• Acceptance checks: preserve engine required checks and review; retain exact source/result identities; verify guidance/links and update this record with the actual merged commit. Existing template implementation/release records are not revalidated by engine tests. Capability staging and migration are unchanged: existing reviewed storage-retention admission, protection and manager/runtime promotion requirements remain; this PR introduces no capability or activation.
• Documentation impact: engine maintenance, capacity, snapshot and observation guidance is updated in PR169; no new template source change is required here. Engine merge, template publication, adopter promotion and actual scheduled live reclamation/protected-resource survival/headroom/later reconciliation remain distinct. No issue closure, template release, private configuration or host activation is implied.

Current status — verified 2026-11-09

This status supersedes the pending/unmerged statements in the historical preparation record below; those records and their receipts are retained unchanged.

• Engine PR157 merged on 2026-10-30 as 840fb9be8a1c69404a5eebcf17855eff13c6c928, from reviewed head 9b1a5bf8ea0bfc02c8ebb6f6f7ea9b2b07f1724f against base 48f5d47e3b4a6b252ce0e16f1c6d8737e56389f1. Engine cleanup sequencing and classic-image ancestry support are available; they are not pending implementation.
• Template PR45 merged on 2026-10-30 as 1bdef39a6932ef9ae2dfdddff34956a9ca8e1e80, from reviewed head 3b44aeb8c2658a20256a019f040f2f44002d4c14 against base 1cb5332166f9c4b7631a5a5ec7f0baeea0e7dc6a. The repository-acceptance receipt is retained in the October 30 comment. This update independently verifies merge identities and current documentation, not a rerun of those historical suites.
• Current template main 5e66bd1f8b51f79383702530388f3fd38c860db3 already documents the merged maintenance behavior in docs/UPDATING.md, including independent container inventory, expired-resource/network-before-storage ordering, strict admitted accounting, classic-parent protection, and staged admission. Do not duplicate or overwrite this implemented guidance. No schema, initializer, capability-evidence field, or compatibility-pin change is needed for this status reconciliation.
• A template release containing PR45 is not established: the latest published release returned by GitHub is v1.1.0, published 2026-10-16, before PR45. The documented exact reviewed unpublished-revision import remains a distinct path; it is not a release claim. Historical engine #111 comments report adopter imports, but this update does not independently establish current adopter promotion, active runtime, or live acceptance.

Pending bounded engine wording follow-up — 2026-11-09

Source: engine #111, with the idle-window interaction in #166. No new engine PR is published. Local candidate db85025eb655fd3d26925a227ad2165a04f303f1 (tree 977bc3d4afecc39f9eee6da93819121e8e17d03e, base a56fad2c47bf6b3f80e839af69615a2b42fc1461) is unmerged. Council round 1 reviewed predecessor 44d27cb30bf6763967bb3078caaf258463b95f4c (Sol 9/10, supplied-artifact/no-tool Opus 8/10); the final successor contains only accepted documentation clarifications after that review, not a fresh Council acceptance.

The one-line runtime correction reports successful default-builder pruning as command completion with reclaimed bytes not measured, rather than an unconditional REMOVE line. Its fake-client regression covers successful 0B and 1GB Docker summaries without parsing either into net filesystem measurements. Maintenance guidance clarifies that successful command completion and DEFER storage headroom-insufficient can coexist; a budget deferral can also follow prior removals. New job-admission suppression may permit natural drain but does not retire protected runnable leftovers or idle runners. Deletion selection, guards, admission, deadlines, capabilities and schemas are unchanged.

Final-source development checks passed: 125 focused storage/network/health tests with no skips, 46-document local links, syntax, ShellCheck, whitespace, exact committed-history secret scan and commit convention. Full exact-source/base local_validate with independently pinned policy/executor, native images and real Docker cleanup E2E is blocked on an authorized exclusive disposable execution resource. No full/native/live acceptance is implied.

Template assessment: the exact current template source above has 38 regular tracked archive members and no occurrence of the old REMOVE eligible line; docs/UPDATING.md already separates measured capacity from Docker counts/estimates and retains the operational acceptance gates. No duplicate guidance implementation, initializer/schema/evidence addition, compatibility-pin promotion or new capability staging is required for this wording-only follow-up. Retain this pending identity separately from merged engine840/template1bdef support. Update it with the actual merged engine commit if this candidate is later accepted and merged; no merge, release, adoption or host activation is authorized here.

Remaining acceptance and authority boundaries

Keep engine availability, a published template release, an exact reviewed adopter import/promotion, supported runtime/manager activation, and live-host acceptance separate. Reviewed exclusive-daemon storage admission, compatible proxy, trusted current/checkpoint image proof and the unchanged installer/idle/uncertainty gates remain mandatory. Engine deployment alone does not enable retention.

Stopping new admissions may let already admitted jobs finish naturally; preexisting runnable leftovers and still-running idle runners can nevertheless block the maintenance window indefinitely. Terminal GitHub attempts, labels, names, age and disk pressure do not authorize retiring those workloads, removing protected images/volumes, clearing current-boot markers or bypassing the idle guard.

For engine #111 and #81, retain evidence of actual applying scheduled eligible reclamation, preserved protected resources, measured filesystem bytes/subnet headroom, and later successful reconciliation. Distinguish deferred maintenance, successful commands with no measured reclamation, actual measured recovery, and insufficient headroom. Docker record counts, overlapping reclaim estimates, enabled timers, zero service exits, manual recovery and disposable fixtures do not establish scheduled live success.

Documentation impact: existing docs/UPDATING.md maintenance/recovery guidance already implements this issue's scope; this is a tracking-status correction, not a new template feature or completed publication/adoption claim. No template merge/release, private configuration change, host operation, cleanup activation, capacity change, credential change or issue closure is authorized or performed by this update.

Historical preparation record (unchanged)

Source engine issues: RandomDevelopment/ci-fleet#81, RandomDevelopment/ci-fleet#111 and RandomDevelopment/ci-fleet#158.
Source engine PR: RandomDevelopment/ci-fleet#157. The cleanup and fixture changes are integrated in current PR head 5d330931b86bf132964a9415715d4d7d71701994. Current-head full validation and independent review remain pending.
Status: integrated into PR157; complete combined-source verification, independent review and merge remain pending.
Current integrated engine candidate: 5d330931b86bf132964a9415715d4d7d71701994. Authored source branch: 795ab65a09bc5322917135f860da0bd6780da62d, including cleanup implementation 94dedf9af4d7378b88ed3624a115646587222f55. Cherry-picks fdbaf8c and 5d33093 carry the authored changes. All eight affected files were independently compared with the source branch and match exactly. The integrated candidate is not yet independently reviewed or merged.
Merged engine commit: pending.

The candidate separates all-container inventory from Docker image/cache accounting, runs eligible network reclamation before admitted storage maintenance under the existing idle/installer/proxy/uncertainty gates, and retains classic-builder parent images while child images survive. Without storage admission, cleanup skips image/cache accounting. An admitted storage-accounting or image-protection failure still fails the service after the network pass. It does not establish disk recovery. Parent images can become eligible on later passes after their children disappear.

The original retention support tracked by closed #22 is implemented in current template guidance. This follow-up concerns the changed cleanup ordering and selection, plus operational acceptance. Open #43 owns portable-image semantics and its staging/recovery requirements; preserve its scope.

Affected template files: docs/UPDATING.md, especially "Disposable image and build-cache retention", and the maintenance/recovery pointers in README.md. Assess AGENTS.md for consistent operational boundaries. No new schema, desired-state, initializer, validator, optional capability, or rollout-evidence field is expected. Do not update compatibility pins merely for this documentation work, and preserve immutable published release records.

Acceptance checks:

• Link the actual reviewed merged engine maintenance and controller-recovery guidance after merge. Explain complete container inventory independently of storage accounting, leaf-only classic image selection, and that an admitted storage failure remains a failed service even if network removal succeeded.
• Retain the idle and uncertainty requirements. Running leftovers can defer the whole applying pass indefinitely. A completed GitHub attempt, resource name, age, or labels alone cannot authorize stopping or deleting running work.
• Explain that PR148's unassigned-cancellation guard is already merged, but an old empty-name error without completion fields cannot prove that case. Require actual completion diagnostics and representative job start/completion, runner cleanup and later reconciliation after supported rollout.
• Keep measured filesystem bytes and admission below 80% separate from deleted record counts and Docker's overlapping reclaim estimates. Retain sanitized dry-run/apply evidence, later scheduled reclamation and later reconciliation. A timer being enabled is not acceptance.
• Verify documentation examples, commands, links and applicable template checks. Preserve ordinary-CI read-only permissions, protected images, volumes, runner capacity and consumer deadlines.

Capability staging: existing docker_storage_retention admission and all portable-image, manager/checkpoint and active/pending evidence requirements continue to apply. This fix adds no capability. Engine deployment alone does not enable retention.

Migration: follow existing reviewed manager/engine/image promotion, remove and converge storage admission before an engine pin change when required by the current template, then re-admit only in a later reviewed same-engine change after runtime and exclusive-daemon inventory verification. A host already over admission needs separately authorized scoped recovery first. No template merge, release, private configuration change, VM operation, signing or host activation is authorized here.

Documentation impact: maintenance sequencing, classic image ancestry, truthful failure/deferred/reclaimed status, listener diagnostics and operational acceptance. Engine availability, published template guidance, adopter engine promotion and live-host acceptance need separate evidence.

Integration dependency update, 2026-10-29, before integration

PR157's run 40926498444 attempt 2 failed at 21:05:52 UTC after successful complete fixtures, embedded-template checks and native APT/image acceptance. The later cleanup requested storage accounting without storage-retention admission and rejected missing resource lists. The cleanup candidate is therefore a prerequisite to PR157's required validation. The recovery owner will carry both authored commits into the existing PR rather than wait for PR157 to merge or create a duplicate implementation PR. Final combined head and merged commit remain pending. Preserve the accepted 240-minute infrastructure adapter, --timeout 10800, local CLI default 1800, ordinary/convention five-minute limits and existing cleanup budgets.

The candidate does not make incomplete accounting acceptable on an admitted daemon. Capture the exact Docker response shape before extending that parser; missing lists cannot become empty resources. The global idle guard also remains. An exclusive lock, age and an empty reference snapshot do not prove an active or unknown workload will not need that network after the lock is released. Separately authorized classified legacy-resource retirement and actual scheduled storage reclamation remain required operational evidence. No new validation or host operation is authorized by this tracking update.

Combined candidate integration, 2026-10-29

PR157 now contains the changes at full head 5d330931b86bf132964a9415715d4d7d71701994. The recovery owner reports bounded VM storage and network regressions, actual dry-run and real success/failure/cancellation/timeout cleanup passed under the installed executor. Independent REST read confirms full supported run https://github.com/RandomDevelopment/ci-fleet/actions/runs/40962536216, attempt 1, is in progress on that exact head; its conclusion is not yet available. Current-head Codex review has been requested. No complete combined-source success, merge, rollout or live retention acceptance is claimed. The original run remains failed.

The 240-minute adapter, --timeout 10800, local CLI default 1800 and cleanup budgets are unchanged. The source branch remains frozen, and the recovery thread retains VM, validation, review and rollout ownership. Update this issue with the actual full reviewed and merged identity after those gates pass. Template implementation/release, adopter engine promotion and actual scheduled reclamation remain separate.