Module updater 

Self-update, via kaishin.

A magi run takes minutes of agent latency, so a background release check costs nothing measurable: it is spawned on the same tokio runtime as the command, overlaps it, and is drained with a bounded wait at shutdown. It never delays the graph.

Structs

Beat

What the watchdog wants said this tick.

Checker

Throttled release checker.

HandoverLease

Proof that hand_over is running: written when it is entered, beaten while it waits on the loop, removed when it leaves.

LeaseGuard

Held by hand_over for as long as it runs; removes the lease on drop.

Progress

One upgrade’s progress, persisted at progress_path.

Stall

A non-terminal stage that has outlived what it should take.

Watchdog

Decides when the watchdog speaks. Pure: the caller supplies now.

Enums

Pending

A background update check, resolved at shutdown.

Stage

How far a self-upgrade this deck set in motion has gotten.

StallKind

How a non-terminal stage came to be called stuck.

Constants

HEARTBEAT_SECS

How often the watchdog repeats itself for one stage.

LEASE_TTL_SECS

A handover lease with no beat for this long is not alive. Same idiom as ask::LEASE_TTL; no pid is consulted.

LOG_MAX_BYTES

The log is rotated to upgrade.log.1 (one generation) past this size.

NO_AUTOUPDATE_ENV

Env kill-switch. Any non-empty value other than 0 / false disables the background check, and it is read before the config so a broken magi.toml cannot force a network call.

STALL_AFTER_SECS

A non-terminal replaced / restarting stage older than this is stuck.

WATCHDOG_POLL

How often the watchdog thread looks at upgrade.json.

Functions

append_bounded

Append line to path, rotating to <path>.1 first when the file has reached max bytes. Open-append-close every time, so a rename or a deleted file never leaves a stale handle.

default_interval

Default interval between checks.

disabled_by_env

Is the background check switched off by the environment?

effective_interval

The interval cfg configures, floored at [MIN_INTERVAL], or default_interval when unset or unparsable.

fail_progress

Record detail as the failure of the upgrade request that is asking, unless a handover is already in flight (parking / restarting): that handover is not this request’s to fail. The check and the write happen under the same lock as write_progress, so a handover that records parking in between cannot be overwritten. Returns whether it was written.

finalize

Drain a pending check and print at most one line.

lease_path

Where the HandoverLease lives, beside upgrade.json.

live_lease

The lease, when it proves hand_over of this upgrade is alive at now.

log_path

Where every handover step is appended, beside upgrade.json. Written by this module directly, so no supervisor redirection of stderr can orphan it.

log_step

One handover step: to tracing at INFO and to <home>/upgrade.log, with a UTC timestamp and this process’s pid. Best-effort - a failed write is a warning, never a failed upgrade.

log_warn

Like log_step, at WARN.

monotonic

What to persist when candidate is written over current.

progress_path

Where Progress is recorded: beside daemon.json, not under the cache dir - see Progress’s own doc for why the two are not the same place.

read_lease

The lease on disk, if there is one.

read_note

The watchdog’s message for exactly this stage of this upgrade, if any; a note from another stage or another upgrade is ignored.

read_progress

The last upgrade this deck recorded, if it has ever started one.

reconcile_after_restart

Reconcile a leftover progress record on startup, before the server starts answering requests.

repo_name

This binary’s own repository name, for --repo . auto-discovery (web::serve, main::resolve_repo) to match a checkout against without a second, driftable copy of [REPO] anywhere else.

run_self_update

magi self-update.

set_parked_talks

Record which chat turns the parked handover is still waiting on. Written only while the stage is Stage::Parking, under the same lock as write_progress, so a stage that moved on is never touched.

spawn

Spawn the background check for cfg, unless it is switched off.

spawn_watchdog

Run the watchdog on a thread of its own, so a blocked runtime, or a process half-way through dropping one, still speaks. It never ends; it is a daemon thread and dies with the process.

stage_age_secs

Seconds progress has been in its stage at now. A clock that went backwards counts as zero, never as a negative age.

stall

Pure: whether progress is stuck at now.

talks_phrase

The phrase naming the chat turns a park waits on, empty for none.

waited_secs

Seconds hand_over has been alive and waiting, when lease proves it.

write_progress

Persist progress, atomically, never moving an upgrade in progress back to an earlier stage - see monotonic.

write_progress_logged

write_progress that says so when it fails, instead of dropping the error: a progress file that silently stops moving is the symptom this module exists to explain.