[abruption]

Summary

Commands now surface a structured clientUpdate fact when a fresh 24-hour cache proves that the invoking session-peer CLI is behind the latest stable GitHub release. Cache misses refresh in one detached local process, remote subprocesses opt out, human guidance stays on stderr, and every cache or network failure remains advisory.

Package-managed installs report pipx, uv, or pip upgrade guidance, while update --check refreshes the same cache without replacing package-owned files. README documents the additive JSON field, its scope relative to remoteVersion, cache semantics, and opt-out controls.

Closes #67

Type

• feat
• fix
• docs
• chore / refactor / test / perf

Checklist

• python3 session_peer.py list works locally
• python3 session_peer.py list --host <a real host> works over SSH
• --dry-run resolves a target without posting anything (covered by the existing regression suite)
• Commits follow Conventional Commits
• Docs updated if behavior changed (README / SKILL.md / CLAUDE.md)
• No secrets, tokens, or session keys in the diff

Verified against

• macOS 26.6.2, Python 3.14.7
• 215 unit/integration tests
• compileall, git diff --check, and the CI-equivalent shellcheck invocation
• Wheel and sdist builds, content inspection, isolated installation, and CLI version/update smoke checks
• Manual cached-update JSON, human stderr, and --no-update-notice behavior using an isolated cache

Notes

No live message was submitted. A missing, stale, malformed, offline, or opted-out cache omits clientUpdate; absence does not assert that the client is current. Multi-host responses retain their current dict/list shapes and copy the single local client fact into each result object.