Control-plane update progress
The shared console shows a compact update banner above its normal header. TUI, web and Tauri use the same React components and authenticated metadata route. The console and existing agent terminals remain mounted. Reading history, navigating settings, observing status and using recovery do not start an update.
The banner uses actual maintenance stages. A percentage appears only when the
reporting actor supplies a bounded completed/total measurement. Otherwise it
shows an activity indicator and elapsed time. A failed status read preserves the
last good console data and marks update evidence unavailable. Memory pressure,
including CONTROLLER_MEMORY_PRESSURE, never creates an update record.
Authority and scope
Update observations live in the existing controller-authority row, bounded to 16 entries. They create no execution queue or infrastructure permission. Only the private installation operator transport may begin, advance or finish one. Signed-in users can read controller-wide status and updates for their currently permitted execution hosts. The canonical installation operator can observe all installation hosts without tenant host-assignment rows. A tenant administrator cannot publish global status or inspect another user's hosts through this route.
During a reported service replacement/reconnection, only mutations depending on that controller or exact execution host are unavailable. Other host actions, passive reads and ordinary metadata settings remain available during a host update. Controller draining retains its existing server-side mutation barrier. Existing native terminal input and attachment paths are preserved.
UI actions declare the request they would execute; the shared action component uses the same request-scope rule as the controller. Final session launch, container start/stop and CLI-update controls use their actual selected targets. Opening a wizard, inspecting a session or changing a view remains possible. All shared API mutations also check current update availability before sending; the server remains authoritative if a control has no declaration or status is temporarily unavailable. Requests are never replayed automatically.
Each actor heartbeat extends a 45-second observation lease. An expired actor cannot keep host buttons disabled or replace a newer operation on the same target. Cached transient update guidance also expires after 90 seconds without a fresh response. An observed durable draining, fenced or standby authority is a separate barrier: mutations stay unavailable until a fresh active authority is observed or the authentication scope changes. Status reads and authenticated recovery remain available throughout. An authentication change clears cached updates, resource mappings and pending read epochs before the next user's metadata can render.
Maintained actors and proof
docker/upgrade.sh apply and docker/install-host.sh --upgrade wrap their
existing commands with docker/control-plane-update-progress.mjs. The wrapper
reports the actual phases and keeps metadata alive while the original command
runs. Nested host updates get independent host-scoped records. It never repeats
a build or service replacement after an uncertain response.
After a successful command exit, the actor waits at most 30 seconds plus one bounded HTTP request for readiness. Controller completion requires the current installation authority to be active. Host completion requires a fresh online inventory observed since its replacement began. Those receipts prove current control-plane readiness; they do not prove project work, account authentication, image equality or a customer's deployment. Existing detailed rollout acceptance and rollback procedures remain necessary.
An older controller can perform the initial upgrade that adds this metadata API.
Only an explicit telemetry 404 may take that path: the wrapper verifies the
same authenticated controller origin, an active private authority plan, the
controller version, and the unchanged controller identity/epoch in a second
plan. A host update also requires that exact enrolled host in both plans.
It reports telemetry as unsupported and starts the existing maintenance command
once, retaining that command's independent status, readiness and recovery.
Authentication failures, conflicts, unknown responses, changing identity or a
non-active authority never start or replay the command through this fallback.
No global stage or completion record is invented for an unsupported server.
API
GET /v1/controller-authority/updates: small owner-filtered passive view.POST /v1/controller-authority/updates: private operator starts a UUID and an exact controller/host scope.PUT /v1/controller-authority/updates/:id: private operator reports heartbeat, actual stage/measured progress, or terminal outcome.GET /v1/controller-authority/updates/:id/readiness: private operator reads actual current readiness before reporting completion.
These use the existing operator API discovery and request transport. They do not make maintenance privileges available to ordinary Project MCP sessions. An operator progress record never authorizes the underlying update command.