Sam & Claude 080d18fab8 skill(freebsd): add freebsd-os-upgrade — minor point-release runbook

Ports the verified freebsd-update-reboot.md (reboot-needed detection, pre/post
status capture, package/service notes, vuln-audit wording) from clawdie-ai into
a layered-soul skill, alongside the existing freebsd-* operational skills.

SKILL.md wraps it as the same-major upgrade procedure (15.0 -> 15.1): ABI
FreeBSD:15:amd64 unchanged so no package rebuild / no PG dump-restore; reboot
only on operator go-ahead; build-host-first sequence; and the clawdie-iso side
(bump/override FREEBSD_VERSION, version-agnostic docs). Escalation is
host-agnostic (mdo on the operator image, sudo/doas elsewhere).

Validation-evidence slot left for the real OSA 15.0->15.1 run to fold in.

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

2026-06-25 10:41:55 +02:00

2.9 KiB

Raw Blame History

FreeBSD Base Update Reboot Handoff

Use this reference after FreeBSD base or package updates, and whenever the operator asks whether a reboot is required.

Reboot-needed rule

A reboot is required when the installed kernel/userland version is newer than the running kernel:

freebsd-version -k   # installed kernel
freebsd-version -u   # installed userland
uname -r             # running kernel

If freebsd-version -k or freebsd-version -u reports a newer patch level than uname -r, the update is staged but not fully active. Report that plainly and ask the operator for an explicit reboot go-ahead. Reboot only on operator go-ahead.

Example interpretation:

freebsd-version -k: 15.0-RELEASE-p9
freebsd-version -u: 15.0-RELEASE-p9
uname -r:          15.0-RELEASE-p8

This means the system has p9 installed but is still running a p8 kernel. A reboot is required to complete the update.

Pre-reboot status capture

Before recommending or handing off a reboot, capture enough state for the next agent/operator to compare after boot:

hostname
freebsd-version -k
freebsd-version -u
uname -r
/usr/sbin/service clawdie status
/usr/sbin/service nginx status
/usr/sbin/service postgresql status
/usr/sbin/jls
/sbin/pfctl -s info

Use absolute paths for base-system tools when the agent shell has a narrow PATH. Unprivileged agents may see permission errors for service internals, PostgreSQL, or PF. Record those as permission-limited checks rather than claiming the service is down.

Package/service considerations

A same-major PostgreSQL package upgrade, such as postgresql18-server 18.3 → 18.4, does not require dump/restore. It still benefits from a reboot or service restart so the new binaries are loaded.

If nginx, tailscale, PostgreSQL, or other long-running daemons were upgraded, prefer a controlled reboot over piecemeal restarts unless the operator asks for a minimal-disruption restart plan.

Post-reboot verification

After the operator confirms the host is back, verify:

freebsd-version -k
freebsd-version -u
uname -r
/usr/sbin/service clawdie status
/usr/sbin/service nginx status
/usr/sbin/service postgresql status
/usr/sbin/jls
/sbin/pfctl -s info

Expected after a successful reboot: freebsd-version -k, freebsd-version -u, and uname -r all report the same patch level.

Also verify application-specific readiness that matters for the current work:

Clawdie control plane reachable/running
Forgejo reachable if git work is active
jails are running (cms, worker, or whatever the host normally owns)
PF enabled and rules loaded
Tailscale reachable if remote agents depend on it

Vulnerability audit wording

If pkg audit still reports vulnerable packages after an upgrade, do not imply the upgrade failed. Say that the applied upgrade completed, but unrelated packages remain vulnerable until fixed packages are available or the operator chooses a ports/package remediation path.

2.9 KiB Raw Blame History