@mmmbuto/nexuscrew 0.8.50 → 0.8.52-rc.0

package/frontend/dist/index.html

@@ -11,8 +11,8 @@
   <meta name="apple-mobile-web-app-title" content="NexusCrew" />
   <link rel="manifest" href="/manifest.json" />
   <title>NexusCrew</title>
-  <script type="module" crossorigin src="/assets/index-kj-l-RDc.js"></script>
-  <link rel="stylesheet" crossorigin href="/assets/index-43DFO1EH.css">
+  <script type="module" crossorigin src="/assets/index-qLF-zV3C.js"></script>
+  <link rel="stylesheet" crossorigin href="/assets/index-DNQLAGoa.css">
 </head>
 <body>
   <div id="root"></div>

package/frontend/dist/version.json

@@ -1 +1 @@
-{"version":"0.8.50"}
+{"version":"0.8.51"}

package/lib/fleet/managed.js

@@ -19,6 +19,15 @@ const OLLAMA_CONTEXT = Object.freeze({
   'minimax-m3': 524288, 'qwen3.5:397b': 262144, 'deepseek-v4-flash': 1048576,
   'mistral-large-3:675b': 262144, 'gemma4:31b': 262144,
 });
+// Lo stesso modello si scrive con o senza tag ('deepseek-v4-flash' e
+// 'deepseek-v4-flash:0731'). Si prova prima la chiave esatta, perche' nella
+// mappa ci sono nomi in cui il tag fa parte dell'identita' del modello
+// ('qwen3.5:397b'), e solo dopo si ricade sul nome base. Troncare sempre al
+// primo ':' romperebbe proprio quelle voci.
+function ollamaContextFor(model) {
+  const key = String(model || '');
+  return OLLAMA_CONTEXT[key] ?? OLLAMA_CONTEXT[key.split(':')[0]];
+}
 const ALIBABA_TOKEN_PLAN_MODELS = Object.freeze([
   'qwen3.8-max-preview', 'qwen3.7-plus', 'qwen3.7-max',
   'qwen3.6-flash', 'glm-5.2', 'deepseek-v4-pro',
@@ -849,7 +858,7 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     } else {
       const endpoint = spec.baseUrl || profile.endpoint;
       const token = profile.auth === 'none' ? 'ollama' : cred.value;
-      const contextWindow = OLLAMA_CONTEXT[model] || (spec.provider === 'zai' ? 1000000 : 200000);
+      const contextWindow = ollamaContextFor(model) ?? (spec.provider === 'zai' ? 1000000 : 200000);
       Object.assign(env, {
         ANTHROPIC_BASE_URL: endpoint, ANTHROPIC_AUTH_TOKEN: token, ANTHROPIC_API_KEY: '',
         ANTHROPIC_MODEL: model, ANTHROPIC_DEFAULT_OPUS_MODEL: model,
@@ -866,7 +875,7 @@ function resolveManagedEngine(engine, cell, cfg = {}) {
     else if (spec.provider === 'ollama-cloud') {
       env.OPENAI_API_KEY = cred.value;
       args.push(...codexProviderArgs('ollama_cloud', 'Ollama Cloud', profile.endpoint, 'OPENAI_API_KEY'));
-      args.push('-c', 'model_providers.ollama_cloud.stream_idle_timeout_ms=600000', '-c', `model_context_window=${OLLAMA_CONTEXT[model] || 200000}`);
+      args.push('-c', 'model_providers.ollama_cloud.stream_idle_timeout_ms=600000', '-c', `model_context_window=${ollamaContextFor(model) ?? 200000}`);
       const localCatalog = path.join(home, '.codex', 'ollama_cloud_model_catalog.json');
       if (fs.existsSync(localCatalog)) args.push('-c', `model_catalog_json="${localCatalog}"`);
     } else if (spec.provider === 'openrouter') {

package/lib/mcp/tools.js

@@ -147,6 +147,92 @@ async function readLocalCellDirectory(ctx, callerSession) {
   return { nodeId, cells: normalizeCellPayload(payload, owner, callerSession) };
 }
 
+const VL_TARGET_RE = /^([a-f0-9]{16,64}):VL-([a-f0-9]{32})$/;
+
+function parseVlTarget(value) {
+  const match = VL_TARGET_RE.exec(String(value || ''));
+  return match ? { instanceId: match[1], nodeId: match[2], id: match[0] } : null;
+}
+
+async function requireActiveLocalSender(ctx, tool) {
+  const identity = await ctx.identity();
+  const callerSession = requireSession(identity.session, tool, identity.code);
+  const directory = await readLocalCellDirectory(ctx, callerSession);
+  if (!directory.cells.some((cell) => cell.self && cell.active)) {
+    throw new Error(`${tool}: la sessione chiamante non e' una cella Fleet attiva locale`);
+  }
+  return callerSession;
+}
+
+async function readVlDirectory(ctx) {
+  const [config, topology] = await Promise.all([
+    ctx.api('GET', '/api/config'), ctx.api('GET', '/api/topology'),
+  ]);
+  const localId = String(config && config.instanceId || '');
+  if (!NODE_ID_RE.test(localId)) throw new Error('instanceId locale non disponibile');
+  const owners = [{ instanceId: localId, route: [], label: 'Local', stale: false },
+    ...topologyOwners(topology).filter((owner) => !owner.stale && owner.instanceId !== localId)];
+  const nodes = [];
+  const availableOwners = [];
+  const unavailable = [];
+  await Promise.all(owners.map(async (owner) => {
+    // Le route /vl-nodes/* non sono federabili (NOTE in lib/proxy/federation.js).
+    // Un owner remoto non e' irraggiungibile: e' chiuso per decisione. Chiamarlo
+    // per raccogliere il 404 e riportarlo come 'unreachable' descriverebbe un
+    // confine sano come un guasto, e manderebbe chi diagnostica a cercare un
+    // tunnel che sta benissimo — proprio quando quel campo serve a distinguere
+    // un nodo davvero muto.
+    if (owner.route.length) {
+      unavailable.push({
+        instanceId: owner.instanceId, owner: owner.label,
+        route: owner.route.join('/'), failure: 'policy-denied',
+      });
+      return;
+    }
+    const apiPath = '/api/vl-nodes';
+    try {
+      const payload = await ctx.api('GET', apiPath);
+      if (String(payload && payload.instanceId || '') !== owner.instanceId
+        || !Array.isArray(payload && payload.nodes)) throw new Error('directory VL owner mismatch');
+      const route = owner.route.length ? owner.route.join('/') : 'local';
+      availableOwners.push({ instanceId: owner.instanceId, owner: owner.label, route });
+      for (const node of payload.nodes) {
+        const expected = `${owner.instanceId}:VL-${node && node.nodeId}`;
+        if (!node || !/^[a-f0-9]{32}$/.test(String(node.nodeId || '')) || node.id !== expected) continue;
+        nodes.push({
+          id: expected, instanceId: owner.instanceId, nodeId: node.nodeId,
+          cell: typeof node.cell === 'string' ? node.cell : `VL-${node.nodeId.slice(0, 8)}`,
+          label: typeof node.label === 'string' ? node.label : 'VL', route,
+          online: node.online === true, canManage: node.canManage === true,
+          lastSeen: Number.isSafeInteger(node.lastSeen) ? node.lastSeen : null,
+          generation: Number.isSafeInteger(node.generation) ? node.generation : 0,
+          version: typeof node.version === 'string' ? node.version : '',
+          capabilities: Array.isArray(node.capabilities) ? node.capabilities : [],
+          health: node.health && typeof node.health === 'object' ? node.health : null,
+          inflight: node.inflight && typeof node.inflight === 'object' ? node.inflight : null,
+          lastAck: node.lastAck && typeof node.lastAck === 'object' ? node.lastAck : null,
+        });
+      }
+    } catch (error) {
+      unavailable.push({
+        instanceId: owner.instanceId, owner: owner.label,
+        route: owner.route.length ? owner.route.join('/') : 'local',
+        failure: /timeout/i.test(String(error && error.message || error)) ? 'timeout' : 'unreachable',
+      });
+    }
+  }));
+  availableOwners.sort((a, b) => (a.route === 'local' ? -1 : b.route === 'local' ? 1 : a.route.localeCompare(b.route)));
+  nodes.sort((a, b) => (a.route === 'local' ? -1 : b.route === 'local' ? 1 : a.route.localeCompare(b.route))
+    || a.cell.localeCompare(b.cell));
+  unavailable.sort((a, b) => a.route.localeCompare(b.route));
+  return { nodeId: localId, owners: availableOwners, nodes, unavailable };
+}
+
+function vlOwnerPath(owner, leaf = '') {
+  const resource = leaf ? `vl-nodes/${leaf}` : 'vl-nodes';
+  return owner.route === 'local' ? `/api/${resource}` : routePath(owner.route.split('/'), resource);
+}
+
 // --- definizione tool (prefisso nc_ anti-collisione) ---------------------------
 // annotations.readOnlyHint:true sui tool che non mutano nulla (§1).
 const TOOLS = [
@@ -368,6 +454,94 @@ const TOOLS = [
       return readCellDirectory(ctx, callerSession);
     },
   },
+  {
+    name: 'nc_vl_nodes',
+    description: 'Directory read-only dei micro-device VL pairati sui nodi NexusCrew autorizzati. online richiede un poll end-to-end recente; usa l id owner-qualified esatto per i comandi.',
+    inputSchema: { type: 'object', properties: {} },
+    annotations: { readOnlyHint: true },
+    async handler(_args, ctx) {
+      return readVlDirectory(ctx);
+    },
+  },
+  {
+    name: 'nc_vl_invite',
+    description: 'Crea un invite VL one-time bounded su un owner NexusCrew autorizzato. Richiede una cella Fleet locale attiva; il valore restituito e un segreto effimero da consegnare fuori da log e argv.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        ownerId: { type: 'string', description: 'instanceId esatto restituito da nc_vl_nodes' },
+        label: { type: 'string', description: 'label device, max 48 caratteri' },
+        ttlSeconds: { type: 'integer', minimum: 30, maximum: 3600 },
+      },
+      required: ['ownerId', 'label'],
+    },
+    async handler(args, ctx) {
+      await requireActiveLocalSender(ctx, 'nc_vl_invite');
+      const ownerId = argString(args, 'ownerId', { required: true, max: 64 });
+      const label = argString(args, 'label', { required: true, max: 48 });
+      const ttlSeconds = args.ttlSeconds === undefined ? 600 : args.ttlSeconds;
+      if (!NODE_ID_RE.test(ownerId) || !Number.isSafeInteger(ttlSeconds)
+        || ttlSeconds < 30 || ttlSeconds > 3600) throw new Error('ownerId o ttlSeconds non valido');
+      const directory = await readVlDirectory(ctx);
+      const owner = directory.owners.find((item) => item.instanceId === ownerId);
+      if (!owner) throw new Error('owner VL non disponibile nella rete autorizzata');
+      const apiPath = vlOwnerPath(owner, 'invite');
+      if (!apiPath) throw new Error('route owner VL non valida');
+      const result = await ctx.api('POST', apiPath, { label, ttlSeconds });
+      return { ...result, note: 'invite e segreto effimero: non inserirlo in argv, log o handoff' };
+    },
+  },
+  {
+    name: 'nc_vl_command',
+    description: 'Invia un comando bounded a un micro-device VL online. submitted conferma solo consegna al poll live; il completamento richiede lastAck con lo stesso id.',
+    inputSchema: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'id owner-qualified esatto restituito da nc_vl_nodes' },
+        kind: { type: 'string', enum: ['status', 'health', 'start', 'stop', 'restart', 'version', 'capabilities', 'logs', 'update_candidate', 'unpair'] },
+        args: { type: 'object', description: 'argomenti exact del comando bounded' },
+      },
+      required: ['target', 'kind'],
+    },
+    async handler(args, ctx) {
+      await requireActiveLocalSender(ctx, 'nc_vl_command');
+      const target = parseVlTarget(argString(args, 'target', { required: true, max: 128 }));
+      const kind = argString(args, 'kind', { required: true, max: 32 });
+      const commandArgs = args.args === undefined ? {} : args.args;
+      if (!target || !commandArgs || typeof commandArgs !== 'object' || Array.isArray(commandArgs)
+        || JSON.stringify(commandArgs).length > 4096) throw new Error('target o args VL non validi');
+      const directory = await readVlDirectory(ctx);
+      const node = directory.nodes.find((item) => item.id === target.id);
+      if (!node) throw new Error('micro-device VL non trovato nella rete autorizzata');
+      if (!node.canManage || !node.online) throw new Error('micro-device VL offline; nessun comando accodato');
+      const apiPath = vlOwnerPath(node, `${target.nodeId}/commands`);
+      if (!apiPath) throw new Error('route micro-device VL non valida');
+      const receipt = await ctx.api('POST', apiPath, { kind, args: commandArgs });
+      return { ...receipt, target: target.id,
+        note: receipt.note || 'submitted conferma il trasporto live; completamento solo via lastAck' };
+    },
+  },
+  {
+    name: 'nc_vl_revoke',
+    description: 'Revoca esplicitamente un pairing VL su un owner autorizzato. Richiede una cella Fleet locale attiva e l id owner-qualified esatto.',
+    inputSchema: {
+      type: 'object', properties: {
+        target: { type: 'string', description: 'id owner-qualified esatto restituito da nc_vl_nodes' },
+      }, required: ['target'],
+    },
+    async handler(args, ctx) {
+      await requireActiveLocalSender(ctx, 'nc_vl_revoke');
+      const target = parseVlTarget(argString(args, 'target', { required: true, max: 128 }));
+      if (!target) throw new Error('target VL non valido');
+      const directory = await readVlDirectory(ctx);
+      const node = directory.nodes.find((item) => item.id === target.id);
+      if (!node) throw new Error('micro-device VL non trovato nella rete autorizzata');
+      const apiPath = vlOwnerPath(node, target.nodeId);
+      if (!apiPath) throw new Error('route micro-device VL non valida');
+      await ctx.api('DELETE', apiPath);
+      return { target: target.id, revoked: true };
+    },
+  },
   {
     name: 'nc_cell_diagnostics',
     description: 'Diagnostica read-only target-specifica di una cella Fleet locale: command Shell redatto e ultima causa spawn/start bounded. Richiede un caller Fleet locale attivo; non attraversa la federazione.',

package/lib/proxy/federation.js

@@ -105,16 +105,37 @@ function knownResource(resource) {
     || resource === '/files/upload'
     || resource === '/cells'
     || resource === '/cells/send'
+    // NOTE: `/vl-nodes`, `/vl-nodes/invite`, `/vl-nodes/:id` and
+    // `/vl-nodes/:id/commands` were federated when the VL bridge was written.
+    // They were removed before the bridge ever shipped. `commands` accepts
+    // `update_candidate`, which names the URL the device downloads its own
+    // update from — and accepts `http:` — while the `sha256` guarantees
+    // nothing, because the sender supplies both the URL and the hash. Federated,
+    // that lets a paired peer install an arbitrary binary on someone else's
+    // device.
+    //
+    // Same class as `/settings/peering/invite` below: a capability that extends
+    // trust past the boundary the owner chose. Denied by default; it can be
+    // federated the day the update channel is bound to something the receiving
+    // owner controls, not before. Local `/vl-nodes/*` calls are unaffected —
+    // this is the federation allowlist only.
     || resource === '/decks'
     || /^\/decks\/[a-z0-9-]{1,32}$/.test(resource)
     || resource === '/topology'
     || resource === '/diagnostics/status'
     || resource === '/diagnostics/logs'
     || resource === '/diagnostics/verbose'
-    // A connected client may ask its hub to mint a hub-owned, one-time
-    // pairing invite. This is the only settings mutation exposed through
-    // Hydra: the rest of /settings stays unreachable.
-    || resource === '/settings/peering/invite'
+    // NOTE: `/settings/peering/invite` used to live here, so a connected client
+    // could ask its hub to mint a hub-owned invite. It was removed on
+    // 2026-08-04. The invite is bound to the HUB's instanceId: whoever consumes
+    // it joins the hub, not the peer that asked for it. So any paired node could
+    // obtain a live invite and hand it to a third party, and the hub's operator
+    // would neither act nor know — trust became transitive without a decision.
+    //
+    // A paired node is otherwise trusted as its owner (see docs/SECURITY.md),
+    // and that is deliberate. This one is different: it is the capability that
+    // ADMITS a further node, so leaving it federated would let a peer break the
+    // very boundary the owner chose. Minting an invite is done on the hub.
     || resource === '/ws'
     || resource === '/audio/capability'
     || resource === '/audio/speak'
@@ -134,6 +155,7 @@ function allowedResource(resource, method = 'GET') {
   if (resource === '/files/upload') return method === 'POST';
   if (resource === '/cells') return method === 'GET';
   if (resource === '/cells/send') return method === 'POST';
+  // `/vl-nodes/*` is deliberately absent — see the NOTE in `knownResource`.
   if (resource === '/decks') return method === 'GET' || method === 'POST';
   if (/^\/decks\/[a-z0-9-]{1,32}$/.test(resource)) {
     return method === 'PUT' || method === 'PATCH' || method === 'DELETE';
@@ -142,7 +164,6 @@ function allowedResource(resource, method = 'GET') {
   if (resource === '/diagnostics/status') return method === 'GET';
   if (resource === '/diagnostics/logs') return method === 'GET' || method === 'DELETE';
   if (resource === '/diagnostics/verbose') return method === 'PATCH';
-  if (resource === '/settings/peering/invite') return method === 'POST';
   if (resource === '/ws') return method === 'GET';
   if (/^\/fleet\/(status|schema|definitions|credentials\/status)$/.test(resource)) return method === 'GET';
   if (/^\/fleet\/(credentials\/(?:set|remove)|up|down|restart|engine|boot|define-engine|edit-engine|remove-engine|define-cell|edit-cell|remove-cell|restore-cells|restore-engines)$/.test(resource)) return method === 'POST';

package/lib/server.js

@@ -56,6 +56,9 @@ const { notifyRoutes } = require('./notify/routes.js');
 const { createNpmUpdater } = require('./update/manager.js');
 const { createDiagnostics } = require('./diagnostics/store.js');
 const { diagnosticsRoutes } = require('./diagnostics/routes.js');
+const vlNodeStore = require('./vl-nodes/store.js');
+const { createBroker: createVlNodeBroker } = require('./vl-nodes/broker.js');
+const { publicRoutes: vlNodePublicRoutes, apiRoutes: vlNodeApiRoutes } = require('./vl-nodes/routes.js');
 
 function sessionExists(tmuxBin, name) {
   if (typeof name !== 'string' || !/^[\w.@%:+-]{1,128}$/.test(name)) return false;
@@ -141,6 +144,9 @@ function createServer(opts = {}) {
   // token / add-remove nodi visibili senza restart). token MAI redatto qui: e'
   // il valore che il proxy inietta upstream, non esce mai verso il browser.
   const nodesPath = cfg.nodesPath || nodesStore.defaultNodesPath(cfg.home || os.homedir());
+  const vlNodesPath = cfg.vlNodesPath || vlNodeStore.defaultPath(cfg.home || os.homedir());
+  const vlNodeBroker = opts.vlNodeBroker || createVlNodeBroker();
+  const vlOwnerId = () => (nodesStore.loadStore(nodesPath) || {}).nodeId || null;
   // fetch usata dai probe di salute federati (iniettabile nei test); default globale.
   const healthFetch = cfg.fetchImpl || fetch;
   const topologyCachePath = cfg.topologyCachePath || topologyCache.defaultPath(cfg.home || os.homedir());
@@ -518,6 +524,12 @@ function createServer(opts = {}) {
   // no-store on everything (HTML+assets+API): this is a local, token-adjacent tool.
   app.use((_req, res, next) => { res.set('Cache-Control', 'no-store'); next(); });
   app.use('/pair', publicPeeringRoutes({ cfg, nodesPath }));
+  // VL micro-device nodes use a separate, scoped credential surface.  These
+  // routes never accept the NexusCrew UI bearer and expose only pair, poll and
+  // self-unpair.  Operator management remains behind /api + federation ACL.
+  app.use('/vl-node/v1', vlNodePublicRoutes({
+    storePath: vlNodesPath, broker: vlNodeBroker, ownerId: vlOwnerId,
+  }));
   // This route is deliberately outside the bearer-authenticated federation
   // router.  It emits a MAC only on a listener owned by the expected slot and
   // never accepts/sends a bearer to a suspicious loopback listener.
@@ -678,6 +690,9 @@ function createServer(opts = {}) {
     })),
     readonly: proxyReadonly,
   }));
+  api.use('/vl-nodes', vlNodeApiRoutes({
+    storePath: vlNodesPath, broker: vlNodeBroker, ownerId: vlOwnerId, readonly: proxyReadonly,
+  }));
   api.use('/decks', decksRoutes({ cfg, decksPath }));
   api.use('/fs', fsRoutes({ home: os.homedir() }));  // folder-picker del dialog new session
   // /nodes (read-only, per la settings UI B2): stesso formato di `nodes list --json`

package/lib/vl-nodes/broker.js

@@ -0,0 +1,228 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const { NODE_ID_RE } = require('./store.js');
+
+const SESSION_RE = /^[a-f0-9]{32}$/;
+const PROTOCOL = 'vl-node/1';
+const MAX_WAIT_MS = 30_000;
+const ONLINE_GRACE_MS = 45_000;
+
+function boundedString(value, max = 128) {
+  return typeof value === 'string' ? value.normalize('NFC').replace(/[\p{Cc}\p{Cf}]/gu, '').slice(0, max) : '';
+}
+
+function boundedInteger(value, min, max, fallback = 0) {
+  return Number.isSafeInteger(value) && value >= min && value <= max ? value : fallback;
+}
+
+function sanitizeAck(raw) {
+  if (!raw || !/^[a-f0-9]{32}$/.test(String(raw.id || ''))) return null;
+  if (!['ok', 'error', 'rejected'].includes(raw.status)) return null;
+  const result = raw.result && typeof raw.result === 'object' && !Array.isArray(raw.result)
+    ? JSON.parse(JSON.stringify(raw.result).slice(0, 16_384)) : null;
+  return { id: raw.id, status: raw.status, ...(result ? { result } : {}) };
+}
+
+function sanitizeHealth(raw) {
+  const health = raw && typeof raw === 'object' && !Array.isArray(raw) ? raw : {};
+  return {
+    state: ['starting', 'running', 'stopped', 'degraded', 'error'].includes(health.state)
+      ? health.state : 'degraded',
+    uptimeSec: boundedInteger(health.uptimeSec, 0, Number.MAX_SAFE_INTEGER),
+    rssBytes: boundedInteger(health.rssBytes, 0, 1 << 30),
+    processCount: boundedInteger(health.processCount, 1, 16, 1),
+    brokerReachable: health.brokerReachable === true,
+    childPid: boundedInteger(health.childPid, 1, 1 << 30, 0) || null,
+    batteryPercent: boundedInteger(health.batteryPercent, 0, 100, -1),
+    detail: boundedString(health.detail, 256),
+  };
+}
+
+function sanitizeHeartbeat(raw) {
+  if (!raw || raw.protocol !== PROTOCOL || !SESSION_RE.test(String(raw.sessionId || ''))
+    || !Number.isSafeInteger(raw.seq) || raw.seq < 0) return null;
+  const capabilities = Array.isArray(raw.capabilities)
+    ? [...new Set(raw.capabilities.filter((item) => /^[a-z][a-z0-9_]{0,31}$/.test(String(item))))].slice(0, 32)
+    : [];
+  return {
+    protocol: PROTOCOL,
+    sessionId: raw.sessionId,
+    seq: raw.seq,
+    version: boundedString(raw.version, 64),
+    capabilities,
+    health: sanitizeHealth(raw.health),
+    ack: sanitizeAck(raw.ack),
+  };
+}
+
+function createBroker(options = {}) {
+  const now = options.now || Date.now;
+  const setTimer = options.setTimeout || setTimeout;
+  const clearTimer = options.clearTimeout || clearTimeout;
+  const randomBytes = options.randomBytes || crypto.randomBytes;
+  const states = new Map();
+
+  function ensure(node) {
+    let state = states.get(node.nodeId);
+    if (!state) {
+      state = {
+        nodeId: node.nodeId,
+        label: node.label,
+        pairedAt: node.pairedAt,
+        lastSeen: null,
+        heartbeat: null,
+        generation: 0,
+        waiter: null,
+        inflight: null,
+        lastAck: null,
+      };
+      states.set(node.nodeId, state);
+    }
+    state.label = node.label;
+    state.pairedAt = node.pairedAt;
+    return state;
+  }
+
+  function finishWaiter(state, value) {
+    const waiter = state.waiter;
+    if (!waiter) return false;
+    state.waiter = null;
+    clearTimer(waiter.timer);
+    waiter.cleanup?.();
+    waiter.resolve(value);
+    return true;
+  }
+
+  function observe(node, raw) {
+    const heartbeat = sanitizeHeartbeat(raw);
+    if (!heartbeat) return { ok: false, code: 'invalid-heartbeat' };
+    // Reaching this authenticated endpoint is itself the end-to-end proof.
+    // Do not preserve a stale false value from the instant before send().
+    heartbeat.health.brokerReachable = true;
+    const state = ensure(node);
+    const sameSession = Boolean(state.heartbeat
+      && state.heartbeat.sessionId === heartbeat.sessionId);
+    if (sameSession
+      && heartbeat.seq <= state.heartbeat.seq) return { ok: false, code: 'stale-sequence' };
+    if (!sameSession) {
+      state.generation += 1;
+      finishWaiter(state, { type: 'superseded', generation: state.generation });
+      if (state.inflight) {
+        state.lastAck = {
+          id: state.inflight.id,
+          status: 'error',
+          result: { code: 'stale-session', detail: 'device session changed before ack' },
+          at: now(),
+        };
+        state.inflight = null;
+      }
+    }
+    state.lastSeen = now();
+    state.heartbeat = heartbeat;
+    let acknowledged = false;
+    if (heartbeat.ack && state.inflight && heartbeat.ack.id === state.inflight.id) {
+      state.lastAck = { ...heartbeat.ack, at: state.lastSeen };
+      state.inflight = null;
+      acknowledged = true;
+    } else if (state.inflight && sameSession) {
+      state.lastAck = {
+        id: state.inflight.id,
+        status: 'error',
+        result: {
+          code: 'delivery-unknown',
+          detail: 'device repolled without acknowledging the dispatched command',
+        },
+        at: state.lastSeen,
+      };
+      state.inflight = null;
+    }
+    return { ok: true, state, acknowledged };
+  }
+
+  function poll(node, rawHeartbeat, { waitMs = MAX_WAIT_MS, signal = null } = {}) {
+    const observed = observe(node, rawHeartbeat);
+    if (!observed.ok) return Promise.resolve({ type: 'error', code: observed.code });
+    const state = observed.state;
+    finishWaiter(state, { type: 'superseded', generation: state.generation });
+    if (observed.acknowledged) {
+      return Promise.resolve({ type: 'acknowledged', generation: state.generation });
+    }
+    const boundedWait = Math.max(1, Math.min(MAX_WAIT_MS, Number(waitMs) || MAX_WAIT_MS));
+    return new Promise((resolve) => {
+      const waiter = { resolve, timer: null, cleanup: null };
+      waiter.timer = setTimer(() => {
+        if (state.waiter === waiter) state.waiter = null;
+        waiter.cleanup?.();
+        resolve({ type: 'idle', generation: state.generation });
+      }, boundedWait);
+      waiter.timer.unref?.();
+      if (signal) {
+        const onAbort = () => {
+          if (state.waiter === waiter) state.waiter = null;
+          clearTimer(waiter.timer);
+          resolve({ type: 'aborted', generation: state.generation });
+        };
+        signal.addEventListener('abort', onAbort, { once: true });
+        waiter.cleanup = () => signal.removeEventListener('abort', onAbort);
+      }
+      state.waiter = waiter;
+    });
+  }
+
+  function dispatch(nodeId, command) {
+    if (!NODE_ID_RE.test(String(nodeId || ''))) return { ok: false, code: 'invalid-node-id' };
+    const state = states.get(nodeId);
+    if (!state || !state.waiter || !state.heartbeat || now() - state.lastSeen > ONLINE_GRACE_MS) {
+      return { ok: false, code: 'node-offline' };
+    }
+    if (state.inflight) return { ok: false, code: 'command-in-flight' };
+    const id = randomBytes(16).toString('hex');
+    const envelope = { id, issuedAt: now(), generation: state.generation, ...command };
+    state.inflight = { id, kind: command.kind, status: 'submitted', submittedAt: envelope.issuedAt };
+    if (!finishWaiter(state, { type: 'command', command: envelope })) {
+      state.inflight = null;
+      return { ok: false, code: 'node-offline' };
+    }
+    return { ok: true, id, status: 'submitted', generation: state.generation };
+  }
+
+  function forget(nodeId) {
+    const state = states.get(nodeId);
+    if (state) finishWaiter(state, { type: 'revoked' });
+    return states.delete(nodeId);
+  }
+
+  function list(nodes) {
+    const at = now();
+    return nodes.map((node) => {
+      const state = states.get(node.nodeId);
+      const online = Boolean(state && (state.waiter || state.inflight)
+        && state.lastSeen !== null && at - state.lastSeen <= ONLINE_GRACE_MS);
+      return {
+        ...node,
+        online,
+        lastSeen: state?.lastSeen ?? null,
+        generation: state?.generation ?? 0,
+        version: state?.heartbeat?.version || '',
+        capabilities: state?.heartbeat?.capabilities || [],
+        health: state?.heartbeat?.health || null,
+        inflight: state?.inflight || null,
+        lastAck: state?.lastAck || null,
+      };
+    });
+  }
+
+  return { poll, dispatch, forget, list, observe, _states: states };
+}
+
+module.exports = {
+  SESSION_RE,
+  PROTOCOL,
+  MAX_WAIT_MS,
+  ONLINE_GRACE_MS,
+  sanitizeHeartbeat,
+  sanitizeHealth,
+  sanitizeAck,
+  createBroker,
+};