@mmmbuto/nexuscrew 0.8.51 → 0.8.52-rc.0

package/README.md

@@ -137,6 +137,7 @@ product verifies a configured pool before it can rotate within it. See
 | [Notifications](docs/NOTIFICATIONS.md) | Toasts, Web Push and optional spoken alerts |
 | [Audio Share and native TTS](docs/AUDIO_SHARE.md) | Node-native TTS, consent, groups and MCP controls |
 | [MCP bridge](docs/MCP.md) | Operator tools, cell delivery and client setup |
+| [VL micro-device nodes](docs/VL_MICRO_NODES.md) | Outbound pairing and bounded management for constrained native VL nodes |
 | [Configuration](docs/CONFIGURATION.md) | Files, environment overrides and local settings |
 | [Operations](docs/OPERATIONS.md) | CLI, boot, backup, updates and diagnostics |
 | [Security](docs/SECURITY.md) | Trust boundaries, tokens and credential handling |

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,6 +105,20 @@ 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'
@@ -141,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';

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,
+};

package/lib/vl-nodes/routes.js

@@ -0,0 +1,195 @@
+'use strict';
+
+const express = require('express');
+const { bearerFrom } = require('../auth/middleware.js');
+const store = require('./store.js');
+const { PROTOCOL, MAX_WAIT_MS } = require('./broker.js');
+
+const OWNER_ID_RE = /^[a-f0-9]{16,64}$/;
+const SIMPLE_COMMANDS = new Set([
+  'status', 'health', 'start', 'stop', 'restart', 'version', 'capabilities', 'unpair',
+]);
+const MAX_CANDIDATE_BYTES = 2_621_440;
+
+function commandOf(body) {
+  if (!body || typeof body.kind !== 'string') return null;
+  if (SIMPLE_COMMANDS.has(body.kind)) {
+    if (body.args !== undefined && (typeof body.args !== 'object' || body.args === null
+      || Array.isArray(body.args) || Object.keys(body.args).length > 0)) return null;
+    return { kind: body.kind, args: {} };
+  }
+  if (body.kind === 'logs') {
+    const limit = body.args && body.args.limit;
+    if (!Number.isSafeInteger(limit) || limit < 1 || limit > 100) return null;
+    return { kind: 'logs', args: { limit } };
+  }
+  if (body.kind === 'update_candidate') {
+    const args = body.args;
+    if (!args || typeof args !== 'object' || Array.isArray(args)) return null;
+    const keys = Object.keys(args).sort();
+    if (keys.join(',') !== 'sha256,size,url,version') return null;
+    if (typeof args.url !== 'string' || args.url.length > 2048) return null;
+    let parsed;
+    try { parsed = new URL(args.url); } catch (_) { return null; }
+    if (!['http:', 'https:'].includes(parsed.protocol) || parsed.username || parsed.password) return null;
+    if (!/^[a-f0-9]{64}$/.test(String(args.sha256 || ''))) return null;
+    if (!Number.isSafeInteger(args.size) || args.size < 1 || args.size > MAX_CANDIDATE_BYTES) return null;
+    if (typeof args.version !== 'string' || !/^[A-Za-z0-9._+-]{1,64}$/.test(args.version)) return null;
+    return {
+      kind: body.kind,
+      args: { url: parsed.toString(), sha256: args.sha256, size: args.size, version: args.version },
+    };
+  }
+  return null;
+}
+
+function nodeToken(req) {
+  const token = bearerFrom(req);
+  return store.TOKEN_RE.test(String(token || '')) ? token : null;
+}
+
+function jsonBodyError(error, _req, res, _next) {
+  if (error && (error.type === 'entity.too.large' || error.status === 413)) {
+    return res.status(413).json({ error: 'body too large' });
+  }
+  if (error instanceof SyntaxError) return res.status(400).json({ error: 'invalid JSON' });
+  return res.status(400).json({ error: String(error?.message || error) });
+}
+
+function publicRoutes({ storePath, broker, ownerId }) {
+  const r = express.Router();
+  const body = express.json({ limit: '20kb' });
+
+  r.post('/pair', body, (req, res) => {
+    const localOwner = ownerId();
+    if (!OWNER_ID_RE.test(String(localOwner || ''))) return res.status(503).json({ error: 'owner identity unavailable' });
+    if (!req.body || req.body.protocol !== PROTOCOL) return res.status(400).json({ error: 'unsupported protocol' });
+    const invite = req.get('x-vl-invite');
+    const paired = store.pairNode(storePath, {
+      invite,
+      nodeId: req.body.nodeId,
+      label: req.body.label,
+    });
+    if (!paired.ok) {
+      const status = paired.code === 'node-exists' ? 409
+        : paired.code === 'invite-expired-or-used' ? 410 : 400;
+      return res.status(status).json({ error: paired.code });
+    }
+    return res.status(201).json({
+      protocol: PROTOCOL,
+      ownerId: localOwner,
+      nodeId: paired.node.nodeId,
+      label: paired.node.label,
+      token: paired.token,
+      pollMaxMs: MAX_WAIT_MS,
+    });
+  });
+
+  r.post('/poll', body, async (req, res) => {
+    const token = nodeToken(req);
+    const node = token && store.authenticate(storePath, token);
+    if (!node || req.body?.nodeId !== node.nodeId) return res.status(401).json({ error: 'unauthorized-node' });
+    const abort = new AbortController();
+    req.once('aborted', () => abort.abort());
+    const result = await broker.poll(node, req.body, {
+      waitMs: Number(req.get('x-vl-wait-ms')) || MAX_WAIT_MS,
+      signal: abort.signal,
+    });
+    if (res.headersSent || res.destroyed) return undefined;
+    if (result.type === 'command') return res.json({ protocol: PROTOCOL, command: result.command });
+    if (result.type === 'idle' || result.type === 'aborted' || result.type === 'acknowledged') {
+      return res.status(204).end();
+    }
+    if (result.type === 'superseded') return res.status(409).json({ error: 'stale-session', generation: result.generation });
+    if (result.type === 'revoked') return res.status(401).json({ error: 'unpaired' });
+    return res.status(400).json({ error: result.code || 'invalid-heartbeat' });
+  });
+
+  r.post('/unpair', body, (req, res) => {
+    const token = nodeToken(req);
+    const node = token && store.authenticate(storePath, token);
+    if (!node || req.body?.nodeId !== node.nodeId || req.body?.protocol !== PROTOCOL) {
+      return res.status(401).json({ error: 'unauthorized-node' });
+    }
+    store.removeNode(storePath, node.nodeId);
+    broker.forget(node.nodeId);
+    return res.status(204).end();
+  });
+
+  r.use(jsonBodyError);
+
+  return r;
+}
+
+function apiRoutes({ storePath, broker, ownerId, readonly = () => false }) {
+  const r = express.Router();
+
+  r.get('/', (_req, res) => {
+    const localOwner = ownerId();
+    if (!OWNER_ID_RE.test(String(localOwner || ''))) return res.status(503).json({ error: 'owner identity unavailable' });
+    const nodes = broker.list(store.listNodes(storePath)).map((node) => ({
+      ...node,
+      id: `${localOwner}:VL-${node.nodeId}`,
+      instanceId: localOwner,
+      cell: `VL-${node.nodeId.slice(0, 8)}`,
+      canReceive: false,
+      canManage: node.online === true,
+    }));
+    return res.json({ instanceId: localOwner, protocol: PROTOCOL, nodes });
+  });
+
+  r.post('/invite', express.json({ limit: '4kb' }), (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: invite blocked' });
+    const localOwner = ownerId();
+    if (!OWNER_ID_RE.test(String(localOwner || ''))) return res.status(503).json({ error: 'owner identity unavailable' });
+    const ttlSeconds = req.body?.ttlSeconds === undefined ? undefined : Number(req.body.ttlSeconds);
+    if (ttlSeconds !== undefined && (!Number.isSafeInteger(ttlSeconds) || ttlSeconds < 30 || ttlSeconds > 3600)) {
+      return res.status(400).json({ error: 'ttlSeconds must be 30..3600' });
+    }
+    const invite = store.createInvite(storePath, {
+      label: req.body?.label,
+      ...(ttlSeconds === undefined ? {} : { ttlMs: ttlSeconds * 1000 }),
+    });
+    return res.status(201).json({ protocol: PROTOCOL, ownerId: localOwner, ...invite });
+  });
+
+  r.post('/:nodeId/commands', express.json({ limit: '8kb' }), (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: command blocked' });
+    if (!store.NODE_ID_RE.test(String(req.params.nodeId || ''))
+      || !store.listNodes(storePath).some((node) => node.nodeId === req.params.nodeId)) {
+      return res.status(404).json({ error: 'node not paired' });
+    }
+    const command = commandOf(req.body);
+    if (!command) return res.status(400).json({ error: 'invalid bounded command' });
+    const result = broker.dispatch(req.params.nodeId, command);
+    if (!result.ok) {
+      const status = result.code === 'node-offline' || result.code === 'command-in-flight' ? 409 : 400;
+      return res.status(status).json({ error: result.code });
+    }
+    return res.status(202).json({
+      id: result.id,
+      status: result.status,
+      note: 'submitted confirms delivery to a live poll only; completion requires the node ack',
+    });
+  });
+
+  r.delete('/:nodeId', (req, res) => {
+    if (readonly()) return res.status(403).json({ error: 'READONLY: revoke blocked' });
+    if (!store.removeNode(storePath, req.params.nodeId)) return res.status(404).json({ error: 'node not paired' });
+    broker.forget(req.params.nodeId);
+    return res.status(204).end();
+  });
+
+  r.use(jsonBodyError);
+
+  return r;
+}
+
+module.exports = {
+  OWNER_ID_RE,
+  SIMPLE_COMMANDS,
+  MAX_CANDIDATE_BYTES,
+  commandOf,
+  publicRoutes,
+  apiRoutes,
+};

package/lib/vl-nodes/store.js

@@ -0,0 +1,203 @@
+'use strict';
+
+const crypto = require('node:crypto');
+const fs = require('node:fs');
+const path = require('node:path');
+
+const NODE_ID_RE = /^[a-f0-9]{32}$/;
+const TOKEN_RE = /^[a-f0-9]{64}$/;
+const STORE_VERSION = 1;
+const DEFAULT_INVITE_TTL_MS = 10 * 60 * 1000;
+const MAX_INVITE_TTL_MS = 60 * 60 * 1000;
+const MAX_STORE_BYTES = 256 * 1024;
+
+function emptyStore() {
+  return { version: STORE_VERSION, invites: [], nodes: [] };
+}
+
+function defaultPath(home) {
+  return path.join(home, '.nexuscrew', 'vl-nodes.json');
+}
+
+function cleanLabel(value, fallback = 'VL') {
+  if (typeof value !== 'string') return fallback;
+  const clean = value.normalize('NFC').replace(/[\p{Cc}\p{Cf}]/gu, '').trim();
+  return clean ? clean.slice(0, 48) : fallback;
+}
+
+function validRecord(record) {
+  return record && NODE_ID_RE.test(String(record.nodeId || ''))
+    && TOKEN_RE.test(String(record.tokenHash || ''))
+    && Number.isSafeInteger(record.pairedAt) && record.pairedAt > 0
+    && typeof record.label === 'string' && record.label.length > 0 && record.label.length <= 48;
+}
+
+function normalizeStore(raw, now = Date.now()) {
+  if (!raw || raw.version !== STORE_VERSION) return emptyStore();
+  const invites = Array.isArray(raw.invites) ? raw.invites.filter((invite) => (
+    invite && TOKEN_RE.test(String(invite.tokenHash || ''))
+      && Number.isSafeInteger(invite.expiresAt) && invite.expiresAt > now
+      && typeof invite.label === 'string' && invite.label.length > 0 && invite.label.length <= 48
+  )).slice(-64) : [];
+  const seen = new Set();
+  const nodes = [];
+  for (const record of Array.isArray(raw.nodes) ? raw.nodes : []) {
+    if (!validRecord(record) || seen.has(record.nodeId)) continue;
+    seen.add(record.nodeId);
+    nodes.push({
+      nodeId: record.nodeId,
+      label: cleanLabel(record.label),
+      tokenHash: record.tokenHash,
+      pairedAt: record.pairedAt,
+    });
+  }
+  return { version: STORE_VERSION, invites, nodes };
+}
+
+function ownedByCurrentUser(stat) {
+  return typeof process.getuid !== 'function' || stat.uid === process.getuid();
+}
+
+function assertSafeFile(stat) {
+  if (stat.isSymbolicLink() || !stat.isFile() || !ownedByCurrentUser(stat)
+    || (stat.mode & 0o077) !== 0 || stat.size > MAX_STORE_BYTES) {
+    throw new Error('unsafe VL node store');
+  }
+}
+
+function loadStore(file, now = Date.now()) {
+  let fd;
+  try {
+    fd = fs.openSync(file, fs.constants.O_RDONLY | (fs.constants.O_NOFOLLOW || 0));
+    assertSafeFile(fs.fstatSync(fd));
+    return normalizeStore(JSON.parse(fs.readFileSync(fd, 'utf8')), now);
+  } catch (error) {
+    if (error && error.code === 'ENOENT') return emptyStore();
+    throw error;
+  } finally {
+    if (fd !== undefined) fs.closeSync(fd);
+  }
+}
+
+function atomicWriteStore(file, store, now = Date.now()) {
+  const dir = path.dirname(file);
+  fs.mkdirSync(dir, { recursive: true, mode: 0o700 });
+  const dirStat = fs.lstatSync(dir);
+  if (dirStat.isSymbolicLink() || !dirStat.isDirectory() || !ownedByCurrentUser(dirStat)) {
+    throw new Error('unsafe VL node store directory');
+  }
+  fs.chmodSync(dir, 0o700);
+  try {
+    assertSafeFile(fs.lstatSync(file));
+  } catch (error) {
+    if (!error || error.code !== 'ENOENT') throw error;
+  }
+  const tmp = `${file}.tmp.${process.pid}.${crypto.randomBytes(8).toString('hex')}`;
+  const fd = fs.openSync(tmp, 'wx', 0o600);
+  try {
+    const payload = `${JSON.stringify(normalizeStore(store, now), null, 2)}\n`;
+    fs.writeFileSync(fd, payload, { encoding: 'utf8' });
+    fs.fsyncSync(fd);
+  } finally {
+    fs.closeSync(fd);
+  }
+  try {
+    fs.renameSync(tmp, file);
+    fs.chmodSync(file, 0o600);
+    try {
+      const dirFd = fs.openSync(dir, 'r');
+      try { fs.fsyncSync(dirFd); } finally { fs.closeSync(dirFd); }
+    } catch (_) {}
+  } catch (error) {
+    try { fs.unlinkSync(tmp); } catch (_) {}
+    throw error;
+  }
+}
+
+function digest(token) {
+  return crypto.createHash('sha256').update(String(token), 'utf8').digest('hex');
+}
+
+function timingSafeHex(left, right) {
+  if (!TOKEN_RE.test(String(left || '')) || !TOKEN_RE.test(String(right || ''))) return false;
+  return crypto.timingSafeEqual(Buffer.from(left, 'hex'), Buffer.from(right, 'hex'));
+}
+
+function randomToken(randomBytes = crypto.randomBytes) {
+  return randomBytes(32).toString('hex');
+}
+
+function createInvite(file, { label = 'VL', ttlMs = DEFAULT_INVITE_TTL_MS } = {}, seams = {}) {
+  const now = typeof seams.now === 'function' ? seams.now() : Date.now();
+  const boundedTtl = Math.max(30_000, Math.min(MAX_INVITE_TTL_MS, Number(ttlMs) || DEFAULT_INVITE_TTL_MS));
+  const token = randomToken(seams.randomBytes);
+  const store = loadStore(file, now);
+  store.invites.push({ tokenHash: digest(token), expiresAt: now + boundedTtl, label: cleanLabel(label) });
+  store.invites = store.invites.filter((invite) => invite.expiresAt > now).slice(-64);
+  atomicWriteStore(file, store, now);
+  return { invite: token, expiresAt: now + boundedTtl, label: cleanLabel(label) };
+}
+
+function pairNode(file, { invite, nodeId, label }, seams = {}) {
+  if (!TOKEN_RE.test(String(invite || ''))) return { ok: false, code: 'invalid-invite' };
+  if (!NODE_ID_RE.test(String(nodeId || ''))) return { ok: false, code: 'invalid-node-id' };
+  const now = typeof seams.now === 'function' ? seams.now() : Date.now();
+  const store = loadStore(file, now);
+  if (store.nodes.some((node) => node.nodeId === nodeId)) return { ok: false, code: 'node-exists' };
+  const inviteHash = digest(invite);
+  const index = store.invites.findIndex((row) => timingSafeHex(row.tokenHash, inviteHash));
+  if (index < 0) return { ok: false, code: 'invite-expired-or-used' };
+  const [accepted] = store.invites.splice(index, 1);
+  const token = randomToken(seams.randomBytes);
+  const record = {
+    nodeId,
+    label: cleanLabel(label, accepted.label),
+    tokenHash: digest(token),
+    pairedAt: now,
+  };
+  store.nodes.push(record);
+  atomicWriteStore(file, store, now);
+  return { ok: true, token, node: { nodeId, label: record.label, pairedAt: now } };
+}
+
+function authenticate(file, token, now = Date.now()) {
+  if (!TOKEN_RE.test(String(token || ''))) return null;
+  const tokenHash = digest(token);
+  const record = loadStore(file, now).nodes.find((node) => timingSafeHex(node.tokenHash, tokenHash));
+  return record ? { nodeId: record.nodeId, label: record.label, pairedAt: record.pairedAt } : null;
+}
+
+function removeNode(file, nodeId, now = Date.now()) {
+  if (!NODE_ID_RE.test(String(nodeId || ''))) return false;
+  const store = loadStore(file, now);
+  const kept = store.nodes.filter((node) => node.nodeId !== nodeId);
+  if (kept.length === store.nodes.length) return false;
+  store.nodes = kept;
+  atomicWriteStore(file, store, now);
+  return true;
+}
+
+function listNodes(file, now = Date.now()) {
+  return loadStore(file, now).nodes.map(({ nodeId, label, pairedAt }) => ({ nodeId, label, pairedAt }));
+}
+
+module.exports = {
+  NODE_ID_RE,
+  TOKEN_RE,
+  STORE_VERSION,
+  DEFAULT_INVITE_TTL_MS,
+  MAX_INVITE_TTL_MS,
+  emptyStore,
+  defaultPath,
+  cleanLabel,
+  normalizeStore,
+  loadStore,
+  atomicWriteStore,
+  digest,
+  timingSafeHex,
+  createInvite,
+  pairNode,
+  authenticate,
+  removeNode,
+  listNodes,
+};

package/package.json

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

package/skills/nexuscrew-agent/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: nexuscrew-agent
-description: Use when an AI agent connected to NexusCrew must notify or ask the human, inspect runtime or deck context, list authorized Fleet cells, message an exact active cell, read its inbox, deliver a file, recover from local tmux messages that remain unsubmitted or garbled, or when a drag in the web terminal does not scroll a full-screen TUI. Prefer nc_notify, nc_ask, nc_status, nc_deck, nc_cells, nc_send_cell, nc_inbox, and nc_send_file; use bundled tmux/file helpers only as a declared compatibility fallback.
+description: Use when an AI agent connected to NexusCrew must notify or ask the human, inspect runtime or deck context, manage exact authorized VL micro-device nodes, list authorized Fleet cells, message an exact active cell, read its inbox, deliver a file, recover from local tmux messages that remain unsubmitted or garbled, or when a drag in the web terminal does not scroll a full-screen TUI. Prefer nc_notify, nc_ask, nc_status, nc_deck, nc_cells, nc_vl_nodes, nc_vl_command, nc_send_cell, nc_inbox, and nc_send_file; use bundled tmux/file helpers only as a declared compatibility fallback.
 ---
 
 # NexusCrew Agent I/O
@@ -19,6 +19,10 @@ When the client exposes the NexusCrew MCP server, use these tools directly:
 | Read the caller's deck name(s) and member cells/tmux sessions | `nc_deck` |
 | List every authorized owner-qualified Fleet cell | `nc_cells` |
 | Submit a bounded message to an exact active Fleet cell | `nc_send_cell` |
+| List authorized VL micro-device owners/nodes | `nc_vl_nodes` |
+| Create a one-time VL pairing invite | `nc_vl_invite` |
+| Deliver a bounded VL command | `nc_vl_command` |
+| Revoke an exact VL pairing | `nc_vl_revoke` |
 | List files received for the current session | `nc_inbox` |
 | Deliver an absolute file path under the user's home | `nc_send_file` |
 
@@ -30,6 +34,7 @@ Apply these rules:
 - Use `nc_status` instead of scraping NexusCrew state files. Use `nc_deck` instead of reading `decks.json`: it returns every local or authorized shared-owner deck containing the caller, preserves visual member order, identifies each deck and member by stable owner ID, includes viewer-valid Hydra routes, and reports `cell: null` when no managed Fleet match is available.
 - Use `nc_cells` immediately before cross-cell delivery. Select its exact owner-qualified `id`; require `canReceive: true`; never guess a duplicate name or stale route.
 - Use `nc_send_cell {target, message}` for actual Fleet-cell delivery. `submitted` confirms bracketed paste plus Enter only, never task acceptance or completion. Inactive targets are not queued.
+- Use `nc_vl_nodes` immediately before VL mutation. Mutation tools require an active local Fleet caller and the full owner-qualified VL ID. `nc_vl_command` `submitted` means live-poll delivery only; require the same ID in `lastAck`. No offline queue exists.
 - Use `nc_inbox` instead of guessing an inbox path when the tool is available.
 - Pass `nc_send_file` an existing absolute regular-file path below the user's home. Let NexusCrew choose and sanitize the outbox name.
 - Do not treat an MCP notification as a substitute for the final response required by the active client.
@@ -128,6 +133,7 @@ work. The setting is also applied to windows created later in that session.
 | Discover this session's deck neighbours | `nc_deck` |
 | Discover authorized cells across nodes | `nc_cells` |
 | Submit to an exact active Fleet cell | `nc_send_cell` |
+| Discover/manage a paired VL micro-device | `nc_vl_nodes`, then `nc_vl_command` |
 | Give the human a file | `nc_send_file` or fallback `nc-deliver <file>...` |
 | Read a file the human sent | `nc_inbox` or fallback to the path in the prompt |
 | Send a prompt/command to a session | `nc-send <session> "text"` |