Refresh Precheck

Refresh Transaction

The invariant is:

select one mode -> one targeted preflight -> exactly one refresh -> one targeted receipt

Refresh reloads code and configuration already visible to the runtime. It does not install, update, switch a checkout, repair a venv, save unfinished work, or grant authority. Read this reference immediately before the call.

Select exactly one mode

Mode budgets are ceilings, not goals. A has one combined transaction gate plus at most one changed-owner check: two before and two after. B uses the combined transaction gate, target receipt, and selector equality: three before and two after. The first after-check includes changed-MCP health only on that trigger. Never inspect an unchanged subsystem.

Universal transaction gate

Before A or B, resolve these two facts as one decision, not two tool calls:

1. Target and authority: name the exact agent/workdir, record its current process incarnation or heartbeat baseline, and name the authorized reload or already-authorized write. A nudge, successful preflight, or tool availability is not consent to install, migrate, edit config, or expand a preset allowlist. A safe pure self-reload needs no invented write authority.
2. Work safety: refuse while the relaunch would interrupt active human work, an in-flight collaboration, or daemon work whose result needs this process. Tend any durable state that actually needs tending; do not run generic Git, notification, or daemon inventories.

Stop if the target or runtime selector is ambiguous. Route source, venv, installer, nudge, and mismatch diagnosis to runtime-update-checks; do not refresh hoping ambiguity will resolve itself.

Add only the triggered owner check

Preset activation is an additive A case. The runtime itself owns preset/revert exclusivity, allowlist authorization, materialization, and context-fit refusal. Do not simulate or bypass those gates; if refused, preserve the old surface and route the exact error.

Issue exactly one call

Choose one shape; nulls are explicit because the System input is closed.

system(action="refresh", input={"reason":"<authorized reload reason>","preset":null,"revert_preset":null}, reasoning="reload <targeted change>")
system(action="refresh", input={"reason":null,"preset":"<exact allowed path>","revert_preset":null}, reasoning="activate authorized preset")
system(action="refresh", input={"reason":null,"preset":null,"revert_preset":true}, reasoning="return to configured default preset")

Execute exactly one of those lines. Never stack calls or refresh again “to be sure.” A successful tool result only accepts or hands off the request; it does not prove that a replacement process started. Missing launch-command or watcher setup, handshake failure, and terminal watcher exhaustion remain failures until fresh-process evidence exists.

Capture one targeted receipt

Record one compact receipt, not a second checklist:

mode: A | B | C
target: <exact agent/workdir>
authority_and_reason: <who/what authorized this transaction>
refresh_calls: 1
fresh_process: <new incarnation or heartbeat advanced beyond the pre-call baseline>
target_assertion: <one changed surface, runtime tuple, or repaired fault + result>
originating_channel_round_trip: <required for B; otherwise n/a>

For B, the update/build owner must freeze before refresh: target, exact runtime_tuple fields (sys_executable, lingtai_file, lingtai_kernel_file, and version_or_head), plus intended selectors. Consume that receipt and compare intended selectors once; do not rerun .pth, editable-install, package, or general Git audits. On the fresh process, compare those four runtime fields directly to the frozen tuple. If MCP interpreter or config changed, include the expected MCP entry and relevant problem state in that same target assertion. Then complete one real request/response round trip on the originating channel. If LINGTAI_RUNTIME_PYTHON is absent or the tuple differs, stop and diagnose through runtime-update-checks; never substitute PATH Python or a guessed venv.

Mode C: recover one fault, once

1. Read the returned error first. If the watcher exhausted its bounded retries, also read logs/refresh_failed_permanent.json and the matching high-priority system notification. That artifact is terminal evidence, not permission to launch again.
2. Route the named fault: preset/refusal semantics to substrate-manual; source, venv, selector, or import mismatch to runtime-update-checks; MCP fault to mcp-manual; context fit/rebuild to context-manual; launcher/watcher fault to its owner. Do not rerun the happy-path table.
3. Repair only that fault with the required human/config-owner authority. If the cause is unknown, the repair is unproved, or a permanent failure has not been escalated to the human/launcher owner, stop.
4. After a specific repair, permit exactly one deliberate retry and produce the C receipt. A failed retry ends the transaction; do not loop or stack calls.

Hard scope boundary

This reference is guidance, not a public command, script, runtime guard, or installer. It performs no write, migration, download, package switch, config change, allowlist expansion, or automatic retry. Owner checks remain available on their triggers; .pth, install provenance, MCP, preset, Git, nudge, whole tool surface, and daemon checks are never unconditional refresh ceremony.