system-maintain

Take a restore point before you take anything else

This desktop has snapshot_create — a real restore point, which is the one undo that actually works here. A conversation can be rewound; an upgrade cannot. So before an upgrade, a kernel change, or anything you would be sorry about:

snapshot_create   name: before-upgrade-<date>

Say you took it and name it, so the person knows what to ask for if this goes wrong. snapshot_list shows what exists; snapshot_restore is the way back. Do not create one before a read-only sweep — a restore point per df -h is noise that makes the useful ones hard to find.

The pass, in order

The order matters: read before you change, and update before you clean, because cleaning first throws away the packages the update is about to want.

1. What is broken right now. check_errors first — it exists for exactly this and costs one call. Then run_command "systemctl --failed --no-pager" and run_command "journalctl -p 3 -b --no-pager | tail -40".
2. Disk before updates, because an upgrade on a full partition fails halfway and leaves dpkg in a state somebody has to unpick: run_command "df -h" and run_command "df -i".
3. Updates. search_packages / run_command "apt list --upgradable" to see what is coming, then install_packages — as a job if it is more than a handful: job_start, then job_wait. A wait that times out has NOT cancelled the install; call job_wait again. A second apt on top of a running one is how a dpkg lock becomes an afternoon.
4. Confirm the machine still works before cleaning: the failed-units check again, and any service the person cares about.
5. Cleanup, and only now. apt autoremove and apt clean are destructive in the sense that matters — autoremove has removed a kernel somebody was about to boot. Show what it would remove first (run_command "apt -s autoremove"), then ask.
6. Backups. Verify one exists and is recent. "There is a backup script" is not a backup; a file with today's date is.

What to report

One paragraph: what was updated, what was cleaned, what is still broken, and the name of the restore point. A maintenance pass that says "done" has told the person nothing they can act on — the value is in the list of what you found and chose not to touch.

A reboot is a decision, not a step

A kernel or libc upgrade needs one to take effect. Say so plainly, say what is running that would be interrupted (desktop_state reports who is here), and let a person choose the moment. Rebooting a desktop somebody is working on is the one mistake nobody forgives.