@mmmbuto/nexuscrew 0.9.27 → 0.9.29

package/lib/live-host/routes.js

@@ -26,6 +26,14 @@
 
 const express = require('express');
 const { CELL_ID_RE } = require('./store.js');
+const { HOP_HEADER } = require('../proxy/hop-proof.js');
+
+// Il ponte federato non nasce da una cella: nasce dal nodo che ospita la
+// pagina/app-server. L'identita' che si puo' PROVARE e' quindi il nodo, e il
+// budget si conta per nodo mittente; questa costante tiene il posto della cella
+// nella chiave (v. lib/audio/rate-limit.js: originKey vuole {node, cell}) e vale
+// anche come nome del target quando il nodo non ha una designazione da nominare.
+const LIVE_HOST_BUCKET = 'live-host';
 
 // Ricava l'elenco celle LOCALI dal fleet (definizioni, attive e non). Una cella
 // federata non compare qui: e' il check che chiude "designa solo una cella di questo
@@ -76,9 +84,40 @@ function eligibleOf(fleet, cell, hostCell) {
   return isActive(cell) && leaseState === 'live';
 }
 
-function liveHostRoutes({ fleetP, store, readonly = () => false, now = () => Date.now(), bridge = null }) {
+function liveHostRoutes({ fleetP, store, readonly = () => false, now = () => Date.now(), bridge = null,
+  // Federazione della designazione remota. `federation` (client seam:
+  // getOwnerState/bridgeForward/ownerRoute) e' presente solo sul nodo CLIENT;
+  // `originResolver` + `federatedRate` attivano la via federata DEL PROPRIETARIO:
+  // una richiesta con prova di hop puo' portare `{expect}` (unico campo) e deve
+  // coincidere con la designazione locale, altrimenti 409 nominato. Assenti
+  // (test parziali) le route restano esattamente quelle locali di prima.
+  // Sul ramo federato l'origine NON e' un campo del body: e' il risultato di una
+  // verifica (prova di hop + catena `visited` costruita dal server), e il budget
+  // del ponte si applica per NODO mittente ATTESTATO — stessa regola e stessi
+  // limiti dell'audio (lib/audio/rate-limit.js).
+  federation = null, originResolver = null, federatedRate = null }) {
   const r = express.Router();
 
+  // Una designazione con `ownerId` e' REMOTA: il puntamento vive qui,
+  // la verita' (thread/eligible/lease) vive sul proprietario. Lo stato del
+  // proprietario arriva via GET federata; irraggiungibile => threadStatus
+  // 'unknown' con reason NOMINATO, mai un fallback su una cella locale.
+  async function remoteOwnerState(snap) {
+    if (!federation || typeof federation.getOwnerState !== 'function') {
+      return { reason: 'live-host-federation-unavailable' };
+    }
+    const out = await federation.getOwnerState({ ownerId: snap.ownerId }).catch(() => ({ ok: false, reason: 'live-host-owner-unreachable' }));
+    if (!out || out.ok !== true || !out.body) return { reason: 'live-host-owner-unreachable' };
+    const b = out.body;
+    return {
+      state: {
+        eligible: b.eligible === true,
+        threadStatus: b.threadStatus || 'unknown',
+        host: b.host || null,
+      },
+    };
+  }
+
   // GET /api/live-host — { hostCell, revision, eligible, threadStatus,
   // host: {lease}, at }. threadStatus misura il runtime del thread ponte:
   // absent/present/active/unknown; non dichiara la presenza del client Live.
@@ -88,6 +127,17 @@ function liveHostRoutes({ fleetP, store, readonly = () => false, now = () => Dat
   r.get('/', async (_req, res) => {
     try {
       const snap = store.snapshot();
+      if (snap.hostCell != null && snap.ownerId) {
+        const remote = await remoteOwnerState(snap);
+        return res.json({
+          hostCell: snap.hostCell, revision: snap.revision, ownerId: snap.ownerId, remote: true,
+          eligible: remote.state ? remote.state.eligible : false,
+          threadStatus: remote.state ? remote.state.threadStatus : 'unknown',
+          host: remote.state ? remote.state.host : null,
+          ...(remote.reason ? { reason: remote.reason } : {}),
+          at: now(),
+        });
+      }
       let eligible = false;
       let lease = null;
       let threadStatus = 'absent';
@@ -164,13 +214,121 @@ function liveHostRoutes({ fleetP, store, readonly = () => false, now = () => Dat
   });
 
   // POST /api/live-host/bridge — risolve il puntamento per l'avvio di una Live
-  // (fetta 3). La richiesta NON è parametrizzabile: la designazione è la
-  // condizione (LC3) e nessun chiamante può scegliere il target (MC3.4). Il
-  // ponte risponde sempre 200: i `none` con reason sono esiti legittimi e
-  // distinti (nessuna designazione / cella non idonea / fallback), non errori.
-  // Body opzionale e vuoto: un body con campi è un 400, non viene ignorato.
+  // (fetta 3). La richiesta NON è parametrizzabile dal chiamante: la
+  // designazione è la condizione, e nessun chiamante sceglie il target — ma la
+  // designazione ora può puntare FUORI nodo, e in
+  // quel caso questo nodo (client) INOLTRA la risoluzione al proprietario
+  // (stessa richiesta, senza parametri di scelta; `expect` è l'attestazione di
+  // cosa il client sta puntando, verificata dal proprietario). Il ponte
+  // risponde sempre 200: i `none` con reason sono esiti legittimi e distinti
+  // (nessuna designazione / cella non idonea / fallback), non errori.
+  // Body opzionale e vuoto: un body con campi è un 400, non viene ignorato —
+  // eccezione: sul PERCORSO FEDERATO (prova di hop) il proprietario accetta
+  // `{expect:{hostCell,revision}}` e lo verifica contro la propria
+  // designazione (mismatch = 409 nominato); il gate `liveHostAccess` del peer
+  // è già stato applicato dall'ingresso federato (federation.js).
   r.post('/bridge', express.json({ limit: '1kb' }), async (req, res) => {
     const body = req.body || {};
+    const federated = !!(originResolver && req.headers && req.headers[HOP_HEADER]);
+    if (federated) {
+      const keys = Object.keys(body);
+      if (keys.length > 1 || (keys.length === 1 && keys[0] !== 'expect')) {
+        return res.status(400).json({ error: 'la risoluzione non accetta parametri' });
+      }
+      // Budget federato. L'origine la da' l'originResolver, che verifica la prova
+      // di hop e la catena controllata dal server: la stringa `visited` letta a
+      // mano non e' un'attribuzione, e un limiter interrogato con la forma
+      // sbagliata (`allow` invece di `check`) non limita nulla — era il difetto.
+      // Una richiesta la cui origine non e' verificabile viene rifiutata qui,
+      // non servita senza budget: fail-closed, mai un limite saltato in silenzio.
+      if (federatedRate) {
+        const resolved = typeof originResolver.resolve === 'function'
+          ? await originResolver.resolve(req, { requireCell: false })
+          : { ok: false, reason: 'no-origin-resolver' };
+        if (!resolved || resolved.ok !== true) {
+          return res.status(403).json({
+            error: 'origine federata non verificabile', reason: 'live-host-origin-unverified',
+            detail: (resolved && resolved.reason) || 'unknown',
+          });
+        }
+        const quota = federatedRate.check({
+          origin: { node: resolved.origin.node, cell: LIVE_HOST_BUCKET },
+          target: store.snapshot().hostCell || LIVE_HOST_BUCKET,
+          urgency: 'normal',
+        });
+        if (!quota.allowed) {
+          return res.status(429).json({
+            error: 'troppo frequente', reason: 'rate-limited',
+            bucket: quota.bucket, retryInMs: quota.retryInMs,
+          });
+        }
+      }
+      const snap = store.snapshot();
+      if (keys.length === 1) {
+        const expect = body.expect || {};
+        const okExpect = expect && typeof expect.hostCell === 'string'
+          && Number.isInteger(expect.revision)
+          && expect.hostCell === snap.hostCell && expect.revision === snap.revision;
+        if (!okExpect) {
+          return res.status(409).json({
+            error: 'la designazione del proprietario non coincide con quella dichiarata dal client',
+            reason: 'live-host-expectation-mismatch',
+            revision: snap.revision, hostCell: snap.hostCell, at: now(),
+          });
+        }
+      }
+      if (readonly()) return res.json({ mode: 'none', reason: 'readonly', at: now() });
+      if (!bridge) return res.status(503).json({ error: 'ponte Live non configurato su questo nodo' });
+      try {
+        const result = await bridge.resolveForLive();
+        res.json(result);
+      } catch (e) {
+        res.json({ mode: 'none', reason: 'bridge-error', detail: String(e && e.message || e), at: now() });
+      }
+      return;
+    }
+    const snap = store.snapshot();
+    if (snap.hostCell != null && snap.ownerId) {
+      // Nodo CLIENT con host remoto: inoltra al proprietario, mai un
+      // fallback su una cella locale (il chiamante non sceglie il target: lo
+      // sceglie la designazione, che punta fuori nodo).
+      if (!federation || typeof federation.bridgeForward !== 'function') {
+        return res.status(503).json({ mode: 'none', reason: 'live-host-federation-unavailable', at: now() });
+      }
+      const out = await federation.bridgeForward({
+        ownerId: snap.ownerId,
+        expect: { hostCell: snap.hostCell, revision: snap.revision },
+      }).catch(() => ({ ok: false, reason: 'live-host-owner-unreachable' }));
+      if (!out) {
+        return res.status(502).json({ mode: 'none', reason: 'live-host-owner-unreachable', at: now() });
+      }
+      // The owner's DECIDABLE answers come first: a refusal and a moved
+      // designation are decisions, not failures. Flattening them into
+      // "unreachable" would hide exactly what the operator has to fix.
+      if (out.status === 403 || out.reason === 'live-host-not-granted') {
+        return res.status(403).json({ mode: 'none', reason: 'live-host-not-granted', at: now() });
+      }
+      if (out.status === 409 || out.reason === 'live-host-expectation-mismatch') {
+        return res.status(409).json({
+          error: 'la designazione del proprietario non coincide con quella dichiarata dal client',
+          reason: 'live-host-expectation-mismatch', at: now(),
+        });
+      }
+      if (out.ok !== true) {
+        // Whatever else the owner answered: our own name plus the status we saw,
+        // never a peer string we did not check — and never "unreachable" for a
+        // node that did answer.
+        const reason = out.reason === 'live-host-owner-unreachable' ? 'live-host-owner-unreachable' : 'live-host-owner-rejected';
+        return res.status(502).json({
+          mode: 'none', reason,
+          ...(Number.isInteger(out.status) ? { ownerStatus: out.status } : {}), at: now(),
+        });
+      }
+      const ownerBody = out.body || { mode: 'none', reason: 'bridge-error' };
+      const route = federation.ownerRoute
+        ? await federation.ownerRoute(snap.ownerId).catch(() => null) : null;
+      return res.json({ ...ownerBody, owner: snap.ownerId, ...(Array.isArray(route) && route.length ? { route } : {}), at: now() });
+    }
     if (Object.keys(body).length > 0) return res.status(400).json({ error: 'la risoluzione non accetta parametri' });
     if (readonly()) return res.json({ mode: 'none', reason: 'readonly', at: now() });
     if (!bridge) return res.status(503).json({ error: 'ponte Live non configurato su questo nodo' });

package/lib/live-host/store.js

@@ -17,6 +17,7 @@ const os = require('node:os');
 const { readJsonSafe, atomicWriteJson } = require('../notify/persist.js');
 
 const CELL_ID_RE = /^[A-Za-z0-9._-]{1,32}$/;
+const NODE_ID_RE = /^[a-f0-9]{32}$/i;
 
 // Path del file di stato: override esplicito -> dir del token (~/.nexuscrew) -> home.
 // Stessa convenzione di consentPath/groupsPath, cosi' i test isolano lo stato via
@@ -34,7 +35,13 @@ function normalize(raw) {
   const revision = raw && Number.isInteger(raw.revision) && raw.revision >= 0 ? raw.revision : 0;
   const hostCell = raw && typeof raw.hostCell === 'string' && CELL_ID_RE.test(raw.hostCell)
     ? raw.hostCell : null;
-  return { revision, hostCell };
+  // La designazione puo' puntare a una cella di un ALTRO nodo. `ownerId`
+  // assente/null = cella locale (comportamento storico); presente = puntamento
+  // remoto: `revision` e' quella del PROPRIETARIO (il client non la avanza,
+  // rispecchia lo stato di chi possiede la cella).
+  const ownerId = raw && typeof raw.ownerId === 'string' && NODE_ID_RE.test(raw.ownerId)
+    ? raw.ownerId.toLowerCase() : null;
+  return { revision, hostCell, ownerId };
 }
 
 function readLiveHost(filePath) {
@@ -90,7 +97,38 @@ function createLiveHostStore({ filePath, now = () => Date.now() } = {}) {
     });
   }
 
-  return { snapshot, compareAndSet, filePath };
+  // Registra/rispecchia il puntamento remoto dopo che il PROPRIETARIO ha
+  // accettato la designazione (via federata). Nessun CAS locale: la revision
+  // e' quella del proprietario, il client la rispecchia.
+  function setRemoteDesignation({ ownerId, hostCell, revision }) {
+    return serialize(() => {
+      if (!NODE_ID_RE.test(String(ownerId || ''))) {
+        return { ok: false, conflict: true, revision: 0, hostCell: null };
+      }
+      const cell = typeof hostCell === 'string' && CELL_ID_RE.test(hostCell) ? hostCell : null;
+      const rev = Number.isInteger(revision) && revision >= 0 ? revision : 0;
+      const revised = { revision: rev, hostCell: cell, ownerId: cell == null ? null : ownerId.toLowerCase(), updatedAt: now() };
+      atomicWriteJson(filePath, revised);
+      return { ok: true, revision: revised.revision, hostCell: revised.hostCell, ownerId: revised.ownerId, at: revised.updatedAt };
+    });
+  }
+
+  // Cancella il puntamento remoto SOLO se appartiene a quel proprietario
+  // (una designazione locale non toccata da un clear federato altrui).
+  function clearForOwner(ownerId) {
+    return serialize(() => {
+      const cur = readLiveHost(filePath);
+      if (cur.ownerId && NODE_ID_RE.test(String(ownerId || '')) && cur.ownerId !== String(ownerId).toLowerCase()) {
+        return { ok: false, revision: cur.revision, hostCell: cur.hostCell, ownerId: cur.ownerId };
+      }
+      if (!cur.ownerId) return { ok: true, revision: cur.revision, hostCell: cur.hostCell, ownerId: null };
+      const revised = { revision: 0, hostCell: null, updatedAt: now() };
+      atomicWriteJson(filePath, revised);
+      return { ok: true, revision: 0, hostCell: null, ownerId: null, at: revised.updatedAt };
+    });
+  }
+
+  return { snapshot, compareAndSet, setRemoteDesignation, clearForOwner, filePath };
 }
 
 module.exports = { createLiveHostStore, liveHostPath, readLiveHost, normalize, CELL_ID_RE };

package/lib/proxy/federation.js

@@ -221,8 +221,8 @@ function panelAllowedFor(ingress) {
 // che la possiede, non un dato che ogni peer pairato vede gia' — stesso gate
 // per-peer del pannello, stesso default negato. A differenza del pannello (un
 // sottoalbero /panel/<cella>/*, perche' serve HTML/JS/asset), qui l'insieme
-// delle risorse e' chiuso: tre endpoint fissi, non un percorso arbitrario.
-const LIVE_HOST_RESOURCES = new Set(['/live-host', '/live-host/designate', '/live-host/clear']);
+// delle risorse e' chiuso: quattro endpoint fissi, non un percorso arbitrario.
+const LIVE_HOST_RESOURCES = new Set(['/live-host', '/live-host/designate', '/live-host/clear', '/live-host/bridge']);
 function isLiveHostResource(resource) { return LIVE_HOST_RESOURCES.has(resource); }
 function liveHostAllowedFor(ingress) {
   if (!ingress) return true;
@@ -233,6 +233,9 @@ function allowedResource(resource, method = 'GET') {
   if (isPanelResource(resource)) return method === 'GET' || method === 'POST';
   if (resource === '/live-host') return method === 'GET';
   if (resource === '/live-host/designate' || resource === '/live-host/clear') return method === 'POST';
+  // The bridge resolution travels to the owner without parameters: the
+  // designation picks the target, so a forwarded call cannot add one.
+  if (resource === '/live-host/bridge') return method === 'POST';
   if (resource === '/sessions') return method === 'GET' || method === 'POST';
   if (/^\/sessions\/[\w.@%:+-]{1,128}$/.test(resource)) return method === 'DELETE';
   if (/^\/sessions\/[\w.@%:+-]{1,128}\/visibility$/.test(resource)) return method === 'PATCH';
@@ -364,17 +367,57 @@ function rewriteSetCookiePath(headers, prefix) {
   return out;
 }
 
-function proxyHttp(req, res, { port, path, credential, visited = null, hopProof = null, setCookiePrefix = null, panelCookie = null }) {
+// What this node records when a designation is created or removed on a PEER
+// through it: `ownerId` is the peer the forward went to, and the revision is
+// the owner's own, taken from its 2xx answer — never a local guess, because the
+// owner is the one that decides. A non-2xx answer, or a body without
+// `{hostCell, revision}`, records nothing: an absent pointer is honest, an
+// invented one is not.
+function liveHostLedgerCapture({ ledger, ownerId, resource }) {
+  return (status, text) => {
+    if (!ledger || !(status >= 200 && status < 300)) return;
+    if (resource === '/live-host/clear') {
+      if (typeof ledger.clearRemote === 'function') ledger.clearRemote(ownerId);
+      return;
+    }
+    let body = null;
+    try { body = JSON.parse(String(text || '')); } catch (_) { return; }
+    if (!body || typeof body.hostCell !== 'string' || !Number.isInteger(body.revision)) return;
+    if (typeof ledger.recordRemote === 'function') {
+      ledger.recordRemote({ ownerId, hostCell: body.hostCell, revision: body.revision });
+    }
+  };
+}
+
+function proxyHttp(req, res, { port, path, credential, visited = null, hopProof = null, setCookiePrefix = null, panelCookie = null, capture = null }) {
+  // A body a local middleware has already read is no longer in the stream: the
+  // headers would announce bytes that nothing sends, and the peer would wait for
+  // a body that never arrives. Say it at once, with a name, instead of letting
+  // the forward sit until the upstream timeout expires.
+  if (Number(req.headers['content-length'] || 0) > 0 && req.readableEnded) {
+    return res.status(502).json({ error: 'request body already read by a local middleware', reason: 'federation-body-consumed' });
+  }
   const up = http.request({ host: '127.0.0.1', port, method: req.method, path, headers: cleanHeaders(req.headers, credential, visited, hopProof, panelCookie) }, (r) => {
     const headers = setCookiePrefix ? rewriteSetCookiePath(r.headers, setCookiePrefix) : r.headers;
-    res.writeHead(r.statusCode, sanitizeResponseHeaders(headers)); r.pipe(res);
+    if (!capture) { res.writeHead(r.statusCode, sanitizeResponseHeaders(headers)); r.pipe(res); return; }
+    // Buffered only where a capture asks for it (the two live-host mutations):
+    // the owner's answer carries the revision that has to be recorded.
+    const chunks = [];
+    r.on('data', (chunk) => chunks.push(chunk));
+    r.on('end', () => {
+      const body = Buffer.concat(chunks);
+      try { capture(r.statusCode, body.toString('utf8')); } catch (_) { /* the ledger never breaks the forward */ }
+      if (res.writableEnded) return;
+      res.writeHead(r.statusCode, sanitizeResponseHeaders(headers));
+      res.end(body);
+    });
   });
   up.setTimeout(30000, () => up.destroy());
-  up.on('error', () => { if (!res.headersSent) res.status(502).json({ error: 'peer non raggiungibile' }); else res.destroy(); });
+  up.on('error', () => { if (!res.headersSent) res.status(502).json({ error: 'peer non raggiungibile', reason: 'federation-peer-unreachable' }); else res.destroy(); });
   req.pipe(up);
 }
 
-function routeHandler({ nodesPath, localPort, localCredential, ingress = null, readonly = () => false, hopSecret = null }) {
+function routeHandler({ nodesPath, localPort, localCredential, ingress = null, readonly = () => false, hopSecret = null, liveHostLedger = null }) {
   return (req, res) => {
     const parsed = parseRoute(req.url);
     // Prima dell'allowlist: un peer senza permesso non deve nemmeno sapere se la
@@ -422,7 +465,13 @@ function routeHandler({ nodesPath, localPort, localCredential, ingress = null, r
     const setCookiePrefix = !ingress && isPanelResource(parsed.resource)
       ? `/api/route/${parsed.route.join('/')}/${ROUTE_DELIMITER}`
       : null;
-    proxyHttp(req, res, { port: next.localPort, path, credential: next.token, visited, setCookiePrefix, panelCookie });
+    // A designation forwarded from here lands on the owner: what this node ends
+    // up pointing at is decided THERE, so the pointer is recorded from the
+    // owner's answer (liveHostLedgerCapture) and not from a local guess.
+    const capture = liveHostLedger && (parsed.resource === '/live-host/designate' || parsed.resource === '/live-host/clear')
+      ? liveHostLedgerCapture({ ledger: liveHostLedger, ownerId: next.nodeId, resource: parsed.resource })
+      : null;
+    proxyHttp(req, res, { port: next.localPort, path, credential: next.token, visited, setCookiePrefix, panelCookie, capture });
   };
 }
 
@@ -1257,9 +1306,9 @@ function peerRouter({ nodesPath, localPort, localCredential, fetchImpl, readonly
   return r;
 }
 
-function localRouter({ nodesPath, localPort, localCredential, readonly, hopSecret = null }) {
+function localRouter({ nodesPath, localPort, localCredential, readonly, hopSecret = null, liveHostLedger = null }) {
   const r = express.Router();
-  r.use((req, res) => routeHandler({ nodesPath, localPort, localCredential, readonly, hopSecret })(req, res));
+  r.use((req, res) => routeHandler({ nodesPath, localPort, localCredential, readonly, hopSecret, liveHostLedger })(req, res));
   return r;
 }
 

package/lib/server.js

@@ -29,6 +29,7 @@ const { cellsRoutes } = require('./cells/routes.js');
 const { liveHostRoutes } = require('./live-host/routes.js');
 const { createLiveHostStore, liveHostPath } = require('./live-host/store.js');
 const { createLiveBridge } = require('./live-host/bridge.js');
+const { createLiveHostFederation } = require('./live-host/federation.js');
 const { fsRoutes } = require('./fs/routes.js');
 const nodesStore = require('./nodes/store.js');
 const nodesTunnel = require('./nodes/tunnel.js');
@@ -979,9 +980,13 @@ function createServer(opts = {}) {
   // Fetta 3: il ponte risolve il puntamento all'avvio di una Live (POST /bridge
   // nello stesso gruppo, stessa auth, stesso local-only). Isolabile da cfg
   // (rev5 MC0): spento non crea connessioni e la Live resta standard.
+  // One store instance serves both sides of a remote designation: the routes
+  // (owner side) and the forwarder that records the pointer to a peer (client
+  // side). Two instances over the same file would work, one is honest.
+  const liveHostStore = createLiveHostStore({ filePath: liveHostPath(cfg) });
   api.use('/live-host', liveHostRoutes({
     fleetP,
-    store: createLiveHostStore({ filePath: liveHostPath(cfg) }),
+    store: liveHostStore,
     readonly: proxyReadonly,
     bridge: createLiveBridge({
       cfg,
@@ -990,6 +995,18 @@ function createServer(opts = {}) {
       filesRoot: cfg.filesRoot,
       log: opts.log || console.log,
     }),
+    // Client side: read the owner's state and forward the bridge resolution to
+    // the node the designation points at. Owner side: accept a forwarded
+    // resolution behind the same per-peer gate and the same rate limiting as
+    // the other federated routes.
+    federation: createLiveHostFederation({
+      localNodeId: federatedNodeId,
+      peers: federatedPeers,
+      localPort: () => (server && server.address() ? server.address().port : cfg.port),
+      localToken: () => tokenHolder.value,
+    }),
+    originResolver: createOriginResolver({ localNodeId: federatedNodeId, hopSecret: () => hopSecret }),
+    federatedRate: createSpeakRateLimiter(),
   }));
   // Pannello per-cella: montato con il suo ingresso dedicato (ticket+cookie)
   // PRIMA del requireToken generale — vedi il blocco sopra, dove nascono
@@ -1075,6 +1092,12 @@ function createServer(opts = {}) {
   api.use('/route', federation.localRouter({
     nodesPath, localPort: () => (server && server.address() ? server.address().port : cfg.port), localCredential: () => tokenHolder.value, readonly: proxyReadonly,
     hopSecret: () => hopSecret,
+    // A designation forwarded from here to a peer is recorded by the answer
+    // the peer gives, not by a local guess: see liveHostLedgerCapture.
+    liveHostLedger: {
+      recordRemote: (entry) => liveHostStore.setRemoteDesignation(entry),
+      clearRemote: (ownerId) => liveHostStore.clearForOwner(ownerId),
+    },
   }));
   api.get('/voice/status', (_req, res) => res.json({ serverSttConfigured: !!cfg.voiceUrl }));
   api.post('/voice/transcribe',

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mmmbuto/nexuscrew",
-  "version": "0.9.27",
+  "version": "0.9.29",
   "description": "Faithful browser tmux client — attach to live sessions over a real PTY, localhost-only, mobile-easy",
   "main": "lib/server.js",
   "bin": {

package/skills/live/SKILL.md

@@ -33,6 +33,18 @@ 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