# Wiki image retention on ces-control

Wiki CI builds one runtime image and one integration-test image per revision. Web
and worker share the runtime image. Tags can share an image ID; displayed image
sizes include shared layers and must not be added to estimate reclaimed space.

## Policy

- Retain the current release and the two preceding distinct successful releases.
  `scripts/deploy.sh` records success in `/opt/prompt/successful-releases` only after
  all existing deployment checks pass. The ledger is replaced atomically.
- The first three successful deployments bootstrap this ledger. Until then,
  retain all runtime images, since old release directories alone do not prove
  successful deployment. No historical success is guessed from directory dates.
- Keep the test images corresponding to retained runtime releases: Studio verification
  and publishing scripts use them as operational tools. Remove other successful
  job test images unless a container still references them or their image ID has
  another protected tag.
- Retain other runtime/test/build images for at least 72 hours for debugging.
  Expired runtime images outside the three retained releases become eligible.
- Remove expired project/build-labelled exited containers only with no mounts.
  Remove expired project-labelled untagged image intermediates where Docker allows.
- Always preserve images referenced by any running, created or stopped container.
  This can deliberately keep more than three runtime versions.
- Preserve foreign tags/digests, unlabelled intermediates and legacy
  `prompt:*` images. Legacy images require a separate reviewed migration list.
- Never use global prune, force image/container removal, or volume deletion.
  Database, object storage, backups and release directories are outside this tool.

## Preview and apply

Run from the reviewed checkout on the confirmed ces-control host:

```sh
sudo python3 scripts/wiki-image-lifecycle.py preview
sudo python3 scripts/wiki-image-lifecycle.py apply
```

The default command is preview. Both print keep/delete reasons, image IDs and tags.
Preview reads Docker metadata and may create empty lock files, but never changes
Docker state. Both commands refuse to proceed if the current release metadata or
success ledger is invalid. They also refuse while another cooperating build or
deployment holds the locks.

The workflow invokes `ci --sha <full-sha>` once on main. A single exclusive
`/opt/prompt/.image-lifecycle.lock` spans builds, integration, deployment and
cleanup. Cleanup also takes the existing `.deploy.lock`, protecting manual
`deploy.sh` invocations. Use this CI entrypoint for manual builds too; raw Docker
commands and old workflow revisions do not participate in this lock. Allow old
wiki jobs to finish before first enabling apply. Other projects are out of scope.

Cleanup runs after both success and failure. Errors are reported without changing
the original build/deployment status or rolling back healthy services. Referenced
images and Docker refusal are reported and retained. Failed CI does not record a
successful release and does not immediately remove that job's test image.

After the user merges to main, policy checks run Python tests and shell syntax
checks on ces-control without building or touching Docker. The full application
build/integration/deployment also runs only on main updates, subject to its path
filters. PR events and manual dispatch do not trigger either workflow. No local
builds are needed.