Housekeeping
Three scheduled jobs keep a box tidy without anyone logging in. They fetch, they clear out finished sessions, and they save uncommitted work somewhere a dead disk cannot take it.
nucleatedThe three jobs #
| Job | Default schedule | In one line |
|---|---|---|
refresh |
Hourly | Fetch every repo and drop branches deleted on the remote. |
cleanup |
Weekly | Remove finished sessions that hold nothing unsaved. |
snapshot |
Hourly | Push each session's uncommitted work to a hidden ref. |
They run inside the daemon, for every nucleus named in the config file, and they use the same code as the nucleate commands. There are no extra timers or scripts to install. Set a job's schedule to "off" to stop it.
Refresh #
The same as running nucleate refresh in each nucleus: fetch every bare clone, prune remote branches that no longer exist, and update the default branch.
It keeps the shared clones current so a new session starts from today's code. It never touches a session's worktree. A session that has been running for a day still has to fetch before it rebases.
Cleanup #
A session's folder is normally removed when the session ends. If the session ended with something unsaved, nucleate refuses and the folder stays, which is the point of the safety rule. Later the work gets pushed or merged, and nothing comes back to remove the folder. Cleanup does.
It removes a session only when all of these are true:
- Its agent session has ended.
- Every repo in it passes
nucleate's unsaved-work check: nothing uncommitted, nothing unpushed, and itsHEADis on a remote branch or is the head of a merged pull request. - Nothing in it has changed for
cleanup_min_age(seven days unless you change it). - No process has its working directory inside it.
It removes whole sessions, never one repo out of a session, and it uses nucleate remove-session to do it, so the rule that protects your work is the same rule in both places. A session that fails any test is left exactly as it was and listed in the journal with the reason.
Cleanup also clears stale worktree records from each bare clone. It tells whether a process is inside a session from /proc, so on a system without /proc it removes nothing.
See what it would do before it does it:
nucleated housekeeping run cleanup --dry-run
[
{
"dry_run": true,
"environment": "client-a",
"job": "cleanup",
"sessions": [
{ "action": "kept", "reason": "web: 2 unpushed commit(s)", "session": "fix-login" },
{ "action": "kept", "reason": "its agent session has not ended", "session": "add-search" },
{ "action": "kept", "reason": "it changed too recently", "session": "docs-pass" },
{ "action": "would_remove", "session": "bump-deps" }
]
}
]
A real run reports "removed" where the dry run says "would_remove".
And read what it did:
journalctl --user -u nucleated.service -g cleanup -n 40 --no-pager
A session folder that survives week after week is a to-do list: something in it exists nowhere else. Deal with that, and the next cleanup takes the folder away.
Snapshot #
A session can hold hours of edits that have not been committed. If the disk dies, they die with it, and no hook can help: a hook does not run when the power goes.
Once an hour, for every worktree with uncommitted changes, the snapshot job:
- Builds a commit of the worktree's current state, on top of its
HEAD, without touching the worktree, its index or its branch. - Pushes that commit to
refs/wip/<branch>on the remote, replacing the previous snapshot.
Slashes in the branch name become hyphens, so workspace/fix-login is saved as refs/wip/workspace-fix-login. Refs under refs/wip/ do not show up as branches. An unchanged worktree pushes nothing.
Two things are left out on purpose:
- Ignored files. A
.envcopied in from the seeds must never be pushed, so the snapshot respects.gitignore. - A worktree being written to. If any changed file was modified in the last two minutes, that worktree waits for the next round.
The push uses whatever credentials git already has in that worktree. On a box built from the recipe that is the short-lived GitHub App token.
Get work back #
On any machine with access to the repo:
git fetch origin refs/wip/workspace-fix-login
git checkout -b rescue FETCH_HEAD
rescue now holds the session's last commit plus one more commit with everything that was uncommitted when the snapshot ran.
One ref per branch keeps this bounded. When a branch is merged and gone, delete its snapshot with git push origin :refs/wip/workspace-fix-login.
Snapshots are not a backup of the box. Session transcripts, seed files and configuration are not in any repo. The recipe's nightly backup covers those.
Run a job now #
nucleated housekeeping run refresh
refresh, cleanup and snapshot can each be run this way. --env client-a limits a run to one environment, and --dry-run shows what cleanup or snapshot would do. Each prints JSON. The scheduled run is not affected.
Change the schedule #
[housekeeping]
refresh = "hourly"
cleanup = "daily"
snapshot = "hourly"
cleanup_min_age = "3d"
The daemon picks the change up by itself. A job that was due while the box was off runs soon after it starts.