Maintenance Mode

Maintenance is a flag on a node that says: stay enrolled, keep answering every command, take no new subshells. It answers a different question than shares do. Shares answer who may launch here; maintenance answers whether anyone may. You flip it when you want the machine back for yourself (an upgrade, a reboot, a noisy agent CLI misbehaving), without unenrolling anything or editing anybody's grants.

Every node has one, including the control plane host's own row.

What turning it on does

• New subshell launches on the node are refused, for everyone, the owner and every grantee included.
• Every subshell running there is terminated, whoever owns them. This is the part to read twice. Any node share lets its grantee launch private work on your machine, so maintenance stops work you cannot enumerate and may not own. Before you throw the switch, the node's page tells you how many subshells will stop (the count, and nothing about whose they are); the people who own them learn by push.
• Everything else keeps working: the node answers service controls, log reads, re-checks, config, and updates exactly as before. The row stays visible to everyone who could see it.

Turning it off puts the node back in service for the same audience as before; maintenance is a window, not a change to anyone's grants.

The two levers

The page. The node's page carries the switch, owner-only (admin on the control-plane host's row), the same gate as deleting the node or re-sharing it, because what it does is bigger than an edit grantee's business. PUT /api/nodes/:id/maintenance on the wire; every flip is audited.

The machine. Someone with a shell on the node decides locally too:

subshell maintenance on    # lists what is running; --yes confirms the stop
subshell maintenance off
subshell maintenance status

on names the running subshells it is about to terminate and refuses to do it without --yes.

Who wins, and why that is not a hole

The flag is one state with two copies, and either end can overrule the other: the newer change wins, and a tie goes to the control plane. So a plane can close a window an operator opened at the keyboard, and because the machine stamps its own decisions, a compromised machine can always present a winning stamp and clear the flag.

That is acceptable because the flag was never a containment control. Whoever can send the frame that clears it holds the node's key, and whoever holds that key is the machine's local OS user, who already owns every pane, every file, and every bearer token there. Maintenance is a routing preference, not a quarantine. It keeps answering every command precisely so the operator can keep maintaining the machine. To actually contain a suspect machine, use the acts that are out of a node key's reach from an authenticated browser: delete the node, rotate or disable its key, or clear its shares.

On the machine, the flag lives in its own small file and the node reads it fail-closed: if the mirror is unreadable, the node refuses launches rather than assuming "off", the inverse of the allowlist, and for the same reason read carefully: "refuse" is the safe answer for a switch that stops work, and "allow" is the safe answer for a restriction nobody set.

See also

• Sharing a Node: the other axis: who may launch here.
• Managing a Node: what stays reachable during the window.
• Notifications: how affected subshell owners hear about the stop.
• The threat model: the overrule semantics and the containment accounting.