Live host cell

Live is the phone-facing quick-open flow: a single host cell, designated per node, is what a Live session lands on. See Fleet and terminals for what Live is; this skill covers designating it, clearing it, and permitting it across nodes.

One host cell per node, guarded by a revision

Each node keeps exactly one hostCell (or none). Changing it is a compare-and-swap on a revision number, never an unconditional write:

1. GET .../live-host returns { hostCell, revision, eligible, host: { lease } }.
2. POST .../live-host/designate { cellId, expectedRevision } — expectedRevision must be the value just read. A stale revision (someone else changed the designation meanwhile) is rejected with 409, not silently overwritten.
3. POST .../live-host/clear { expectedRevision } — same rule, removes the designation.

Always re-read the revision immediately before writing; never reuse one from an earlier render. This is what keeps two people (or two tabs) racing to star a cell from leaving the store in a mixed state — one write wins, the other gets a 409 and re-reads.

The designation survives the cell going inactive; it is never dropped just because tmux is not attached right now. eligible is computed fresh on every read from the roster and the designated cell's lease state (live/grace/expired/none/unavailable) — a designated-but-not-eligible host is a distinct, readable state, not an error to explain away.

The rule is per node — and the cell may live on another node

One host cell per node is the rule, and it keeps holding when the designated cell belongs to a peer: the node serving the page keeps the pointer locally (ownerId plus the owner's own revision, and remote: true on GET) and forwards the bridge resolution to the owner instead of resolving it locally. The caller still chooses nothing — the designation is the choice, and it can now point off-node. An unreachable owner, or a peer that was never granted liveHostAccess, is a named outcome (live-host-owner-unreachable, live-host-not-granted), never a silent fallback to a local cell. clear removes the pointer on both sides.

Command the node that owns the cell, not the one serving the page

This is the point of the feature: the request must reach the node whose roster contains the cell, not whichever node happens to be rendering the current page. Route it exactly like a federated deck — an empty route for a local cell, that node's route array for a remote one:

getLiveHost(token, route)                                   // route: [] or [...hops]
designateHostCell(token, cellId, expectedRevision, route)
clearHostCell(token, expectedRevision, route)

Before 0.9.1 these calls took no route, so starring a cell shown from a remote node either did nothing or silently changed the wrong node's designation. That mismatch — not a missing capability — was the defect: a parameter nobody passed does not exist.

Federated permission: liveHostAccess

A peer may designate or read another node's Live host only if that node has granted it. The permission is per peer, denied by default, and granted by the node that owns the cell — never by the one asking:

nexuscrew nodes live-host <node> on
nexuscrew nodes live-host <node> off

Without it, the request gets a named rejection, not a timeout or a star that quietly does nothing: HTTP 403 with reason: "live-host-not-granted". Surface this distinctly from a generic failure — the fix is a grant on the owning node, not a retry from the requester.

Common mistakes

• Reusing a stale revision. GET immediately before every designate/clear; a revision read earlier in the session is stale by definition once anything else has changed the designation.
• Designating a cell that belongs to a different node than the route targets. The route selects which node's roster is searched; a cellId absent from that node's local roster is rejected with 404, never forwarded further to guess where it might live.
• Reading a live-host-not-granted rejection as a bug. It means exactly what it says: run nexuscrew nodes live-host <node> on on the node that owns the cell, not on the node making the request.
• Assuming Live host state is global. It is one value per node; a node with nothing designated still answers GET with hostCell: null — a valid state, distinct from "not permitted to ask".

The per-cell voice prompt

Once a session lands on a host cell, a native Live (engine codex-vl*) always sends thread/start an identity header naming the designated cell and its exact tmux session, and appends a per-cell prompt file's text after it when one exists. See The Live per-cell prompt for where the file goes and the ready-to-copy IT/EN/ES templates.

Dependencies

Bundled: this is a NexusCrew core feature. No external MCP companion or separate service is required — only a running NexusCrew node on each side of the designation.