Module update_check 

The passive “a newer bb exists” notice.

bb update answers the question only when someone thinks to ask it, and most people never do — so this asks on their behalf, once a day, ahead of whatever command they actually ran.

Four properties, each with a test, because this runs before every command and must never be the reason one of them fails or changes shape:

• the notice goes to stderr, in human and --json mode alike, so the --json stdout contract stays intact and an agent reading stderr still learns about the upgrade;
• the network is touched at most once per CHECK_TTL; every other invocation reads one small file;
• every failure — offline, rate limited, unwritable config dir, corrupt cache — is swallowed silently, since the user asked for something else;
• BB_NO_UPDATE_CHECK=1 turns the whole thing off.

Structs

Cache

What the last check found. latest is stored as the raw tag (v0.19.4) because that is what the release API returns and is_newer tolerates the v.

Constants

CHECK_TTL

How long a recorded answer is trusted. A day is short enough that an upgrade is noticed promptly and long enough that the check is invisible in normal use.

Functions

cache_path

is_stale

True when the cache is missing, older than ttl, or stamped in the future. A future stamp means a clock moved backwards; treating it as fresh would freeze the check until the clock caught up.

load_cache

A missing or unreadable cache is indistinguishable from never having checked, which is exactly the right reading: check again.

maybe_notify

The pre-command hook. Prints at most one line, to stderr, and returns nothing to fail on.

notice

The line shown when latest is ahead of current, and None otherwise.

save_cache

Written the same way skill::save_state writes: temp file plus rename, so two bb processes racing cannot leave a truncated file that then silently disables the check.