Runtime Update Checks

Runtime Update Checks

Use this reference to determine what is running, what is on disk, and who owns a change. It is read-only guidance, not permission to download, install, modify configuration, switch a checkout, or relaunch. Once a target source/venv is proven and authorized, refresh-precheck owns the complete refresh transaction; do not copy its happy-path sequence here.

Ownership map

Nudge lifecycle and meanings

1. Local facts. kernel_version.py reads the already-loaded lingtai wrapper for the running version and distribution metadata for the installed version. runtime_identity.py stamps package/dev mode, source kind, and available Git identity into durable events.
2. Release-version producer. Packaged, non-editable, non-dev runtimes compare matching local versions with the exact release-manifest asset on GitHub and Gitee through a bounded probe gate. Two available mirrors must agree on version, content, and hashes; one available mirror may establish the result. Network or mirror disagreement is diagnosis, not an update. Editable/source/ dev runtimes are release-version-silent and clear only their stale entry.
3. Source-integrity producer. source_drift.py compares the startup runtime fingerprint with a fresh on-disk fingerprint. source_drift means this process differs from local disk; it never becomes release-migration or package-install authority.
4. Dispatch. Heartbeat runs the nudge dispatcher once per one-second tick. kernel_version and source_drift each use a roughly 60-second in-memory probe gate. One producer failure is logged and does not block the others.
5. Persistence and delivery. The user-facing aggregate is .notification/nudge.json; dismissal mute expiries live in .notification/.nudge_state.json. Each producer owns one kind. Atomic upsert replaces that kind and resolution removes it. Notification sync injects changed allowlisted files at an IDLE boundary, wakes ASLEEP, defers during ACTIVE, and cannot inject into STUCK/SUSPENDED.
6. Interpretation. A nudge is synchronized kernel evidence, not a human command. Compare its fields and diagnose ambiguity before proposing action.

Built-in nudge kinds are:

• kernel_version on release_version: running, installed, latest (or null for code already on disk), source, and a suggested action.
• source_drift on source_integrity: startup and disk fingerprints.
• init_config_shape on configuration_staleness: configuration-shape guidance, not update authority.

The controls LINGTAI_NUDGE_ENABLED and LINGTAI_NUDGE_REPEAT_INTERVAL govern publication and the post-dismiss mute window. Their values, invalid fallback, read point, and reload behavior live in environment-variables; producer probe gates are observation costs, not user cadence. Dismissal is mute, not resolution.

Packaged versus source/dev evidence

For a packaged/non-editable runtime:

• running != installed normally means newer package code is already on disk than this process loaded: investigate a reload, not another package install.
• latest > installed means an official release manifest advertises an update; it does not mean anything was downloaded.
• Running newer than metadata indicates stale metadata or an import-path mismatch; never blindly downgrade.

Editable/source/dev detection uses direct_url.json with dir_info.editable: true, source checkout markers, module paths, and dev-version markers. Missing distribution metadata is source/dev evidence, not permission to install. For these runtimes, exact interpreter, both imported module paths, checkout, branch, commit, dirty state, and selector values are the useful facts. Read Git only at the source path identified by the import probe; generic Git status in the current agent directory proves nothing.

Exact read-only probe

Use the interpreter exported by the launcher. If it is absent, stop and ask the launcher owner; do not substitute PATH Python or guess a venv.

PYTHON="$LINGTAI_RUNTIME_PYTHON"
[ -n "$PYTHON" ] || { echo "LINGTAI_RUNTIME_PYTHON is unset; stop" >&2; return 1 2>/dev/null || exit 1; }
"$PYTHON" - <<'PY'
import importlib.metadata as md
import sys
import lingtai, lingtai.kernel
print("python=", sys.executable)
print("lingtai_version=", getattr(lingtai, "__version__", "unknown"))
try:
    print("lingtai_dist=", md.version("lingtai"))
    print("direct_url=", md.distribution("lingtai").read_text("direct_url.json"))
except Exception as exc:
    print("distribution_metadata=", type(exc).__name__, str(exc)[:120])
print("lingtai_file=", getattr(lingtai, "__file__", "unknown"))
print("lingtai.kernel_file=", getattr(lingtai.kernel, "__file__", "unknown"))
PY

When those paths identify a source checkout, the narrow follow-up is:

git -C <identified-source-checkout> status --short --branch
git -C <identified-source-checkout> log -1 --format='%H %cI %s'

Do not print environment dumps, credentials, or unrelated remotes. Inspect .pth, direct_url.json, dist-info, or installer state only when this probe shows an install/import mismatch or a source/venv cutover requires it; none is a universal refresh check.

Update/install route and authority

For a real user-facing install or update, let Shell execute https://lingtai.ai/install.sh --help and follow its current output without reading or pasting the script source. That installer owns managed kernel/TUI/ portal installation, exact-tag migration navigation, mirror comparison, artifact verification, and child command shapes. Bare pip install --upgrade lingtai is not the normal user instruction; pip/venv commands are limited to authorized diagnosis or developer verification.

Tell the human what the nudge and probe established. After applicable migrations and writes are displayed, proceed only after receiving explicit confirmation and explicit human/config-owner authority for each download, install, migration, configuration write, and disruptive relaunch. A nudge and this manual grant none.

The update/build owner validates its own work before handoff and freezes one cutover receipt containing:

target: <exact agent/workdir>
runtime_tuple:
  sys_executable: <exact executable>
  lingtai_file: <exact lingtai.__file__>
  lingtai_kernel_file: <exact lingtai.kernel.__file__>
  version_or_head: <exact expected version/commit>
source_root: <optional diagnostic root>
selectors: <intended launcher/init interpreter selector values>
authority: <who authorized install/write/cutover>
owner_validation: <targeted update/build/install result>

Hand that receipt to refresh-precheck mode B. That reference owns selector comparison, exactly one refresh, the fresh runtime-tuple check, originating- channel round trip, and failure recovery. Do not duplicate them here.

Mismatch diagnosis

Nudges are delivered once and never cleared by delivery; there is no notification dismiss action, so interpreted nudges need no acknowledgement call. A changed finding is delivered again. Use notification(action="check") only to reread the current mirror deliberately.

Boundaries

This reference owns update/source/install/nudge/mismatch diagnosis and the cutover handoff. It does not own refresh ordering, preset activation, retries, or post-refresh receipts. It performs no download, write, install, checkout switch, migration, relaunch, or notification mutation by itself. source_drift stays local and outside release-migration routing; refresh-precheck is the single owner of every happy-path or recovery refresh transaction.