@milpa/comal 0.2.3 → 0.2.4

package/README.md

@@ -28,7 +28,7 @@ comal --help
 
 Keep the PATH line in your shell startup file if you use that prefix. If your Node manager already provides a user prefix, you can omit `--prefix "$HOME/.local"`. The package registers the `comal` executable; you do not need to create a shell alias.
 
-You can pin a version with `npx @milpa/comal@0.2.3` or `npm install --global @milpa/comal@0.2.3`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
+You can pin a version with `npx @milpa/comal@0.2.4` or `npm install --global @milpa/comal@0.2.4`. The local release manifest preserves SHA-256 and SHA-512 integrity is checked against npm at publish time. No independent publisher signature is claimed.
 
 ## Test without account or model
 

package/backend/contracts/remote-device-v1.json

@@ -0,0 +1,423 @@
+{
+  "protocol": "comal.remote.device.v1",
+  "description": "Contract between a Comal Remote Control (/rc) session and an M5Stack device: pairing, the two inputs a device may send, the ephemeral permission card, the session.stats projection and the reasons a device is refused. The device is a pre-check surface only: the local Comal host revalidates every answer (arm, expiry, card digest, session, device) before mutating. Owned by the Comal Node repository; the backend keeps a byte-identical copy.",
+  "pairing": {
+    "code_alphabet": "0123456789ABCDEFGHJKMNPQRSTVWXYZ",
+    "code_length": 8,
+    "code_ttl_seconds": 600,
+    "poll_interval_seconds": 5
+  },
+  "inputs": {
+    "permission_answer": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "question_id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+        },
+        "card_digest": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "decision": {
+          "type": "string",
+          "enum": [
+            "allow_once",
+            "deny"
+          ]
+        }
+      },
+      "required": [
+        "question_id",
+        "card_digest",
+        "decision"
+      ]
+    },
+    "quick_reply": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "text": {
+          "type": "string",
+          "enum": [
+            "continúa",
+            "sí",
+            "no"
+          ]
+        }
+      },
+      "required": [
+        "text"
+      ]
+    }
+  },
+  "stats": {
+    "maxBytes": 2048,
+    "schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "model": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "provider": {
+              "type": "string",
+              "maxLength": 64
+            },
+            "profile": {
+              "type": "string",
+              "maxLength": 64
+            },
+            "model": {
+              "type": "string",
+              "maxLength": 64
+            },
+            "effort": {
+              "type": "string",
+              "maxLength": 64
+            },
+            "effort_levels": {
+              "type": "array",
+              "maxItems": 8,
+              "items": {
+                "type": "string",
+                "maxLength": 64
+              }
+            }
+          }
+        },
+        "capabilities": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "tools": {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            "vision": {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            "thinking": {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            "cache": {
+              "type": [
+                "boolean",
+                "null"
+              ]
+            },
+            "sources": {
+              "type": "object",
+              "maxProperties": 8,
+              "additionalProperties": {
+                "type": "string",
+                "maxLength": 64
+              }
+            }
+          }
+        },
+        "permissions": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "mode": {
+              "type": "string",
+              "enum": [
+                "default",
+                "acceptEdits",
+                "plan",
+                "auto",
+                "bypassPermissions"
+              ]
+            },
+            "device_armed": {
+              "type": "boolean"
+            },
+            "device_until": {
+              "type": [
+                "integer",
+                "null"
+              ],
+              "minimum": 0
+            },
+            "add_dirs": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "context": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "input_tokens": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "window": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "output_reserve": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "percent": {
+              "type": "number",
+              "minimum": 0,
+              "maximum": 100
+            },
+            "compaction_window": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "soft_threshold": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "hard_threshold": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "last_compaction": {
+              "type": [
+                "object",
+                "null"
+              ],
+              "additionalProperties": false,
+              "properties": {
+                "at": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "trigger": {
+                  "type": "string",
+                  "maxLength": 64
+                },
+                "before": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "after": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "messages_active": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "messages_original": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "usage": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "last": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "input": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "output": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "cached": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "session": {
+              "type": "object",
+              "additionalProperties": false,
+              "properties": {
+                "input": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "output": {
+                  "type": "integer",
+                  "minimum": 0
+                },
+                "cached": {
+                  "type": "integer",
+                  "minimum": 0
+                }
+              }
+            },
+            "calls": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "call_limit": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "timing": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "comal_ms": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "reasoning_ms": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "first_response_ms": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "tools_ms": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "human_wait_ms": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "work": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "objective": {
+              "type": "string",
+              "maxLength": 120
+            },
+            "done": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "total": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "current_task": {
+              "type": [
+                "string",
+                "null"
+              ],
+              "maxLength": 120
+            },
+            "checks_passing": {
+              "type": "integer",
+              "minimum": 0
+            },
+            "checks_failing": {
+              "type": "integer",
+              "minimum": 0
+            }
+          }
+        },
+        "connection": {
+          "type": "object",
+          "additionalProperties": false,
+          "properties": {
+            "transport": {
+              "type": "string",
+              "enum": [
+                "websocket",
+                "https-polling",
+                "disconnected"
+              ]
+            },
+            "host_online": {
+              "type": "boolean"
+            }
+          }
+        }
+      }
+    }
+  },
+  "card": {
+    "maxBytes": 4096,
+    "schema": {
+      "type": "object",
+      "additionalProperties": false,
+      "properties": {
+        "question_id": {
+          "type": "string",
+          "pattern": "^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$"
+        },
+        "card_digest": {
+          "type": "string",
+          "pattern": "^[a-f0-9]{64}$"
+        },
+        "tool": {
+          "type": "string",
+          "maxLength": 64
+        },
+        "kind": {
+          "type": "string",
+          "enum": [
+            "bash",
+            "write",
+            "edit",
+            "summary",
+            "terminal"
+          ]
+        },
+        "lines": {
+          "type": "array",
+          "maxItems": 16,
+          "items": {
+            "type": "string",
+            "maxLength": 120
+          }
+        },
+        "truncated": {
+          "type": "boolean"
+        },
+        "overwrite": {
+          "type": "boolean"
+        }
+      },
+      "required": [
+        "question_id",
+        "card_digest",
+        "tool",
+        "kind",
+        "lines",
+        "truncated"
+      ]
+    }
+  },
+  "arm": {
+    "default_seconds": 1800,
+    "max_seconds": 28800
+  },
+  "refusals": [
+    "disarmed",
+    "expired",
+    "stale",
+    "terminal_only",
+    "other_device",
+    "plan_mode",
+    "confirm_always",
+    "offline"
+  ]
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@milpa/comal",
-  "version": "0.2.3",
+  "version": "0.2.4",
   "description": "Comal: governed operations, execution receipts, and programming assistance in any language",
   "type": "module",
   "private": false,
@@ -25,6 +25,7 @@
     "backend/contracts/remote-commands-v1.json",
     "backend/contracts/remote-relay-answers-v1.json",
     "backend/contracts/remote-workspace-v1.schema.json",
+    "backend/contracts/remote-device-v1.json",
     "governance/source-task-v1.json",
     "governance/source-task-v2.json",
     "governance/chrome-task-v1.json",

package/src/cli.mjs

@@ -1,3 +1,5 @@
+import { forwardHouseRow, parseRcDevice, runRcDevice, runRcDeviceScan, deviceCodeChoice, parseRcPermissions, runRcPermissions } from './remote-device.mjs';
+import { scanPairingQr } from './qr-scan.mjs';
 import { registerSecretEnv } from './child-env.mjs';
 import {prepareSourceTask,readSourceTask} from './workflows/source-task.mjs';
 import {savedSourceTask} from './source-task-proof.mjs';
@@ -5,6 +7,7 @@ import { t, registerMessages, configureLanguage, languageArguments } from './i18
 import cliSpanish from './i18n/cli-es.mjs';
 registerMessages(cliSpanish);
 import { RemoteHost } from './remote-control.mjs';
+import { PermissionDesk, confirmWithDevice } from './remote-permissions.mjs';
 import { remoteCommandHelp, isRemoteCommand } from './remote-commands.mjs';
 import { codeRunDefinition } from './code-run.mjs';
 import {installCodeRunSession} from './code-run-session.mjs';
@@ -53,6 +56,7 @@ import {GitIntegrationOperations} from './git-integration-operations.mjs';
 import {prepareGitPageCliBridge,assertGitPageCliEntry} from './git-page-cli-bridge.mjs';
 import { registerGitSourceOperations } from './git-source.mjs';
 import { projectRemoteWorkspace } from './remote-workspace.mjs';
+import { buildSessionStats, readContext, statsFromRows } from './remote-stats.mjs';
 import { evidenceOperations } from './work-state.mjs';
 import { auditExecution, auditReport } from './audit.mjs';
 import { comalEnvironment, defaultStateDir } from './compat.mjs';
@@ -371,10 +375,12 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
   const interactive = !print;
   const color = (code, text) => stdout.isTTY && !process.env.NO_COLOR ? `\x1b[${code}m${text}\x1b[0m` : text;
   let remoteHost;
-  let controller, authController, modelController, runtime, peerBus, listenTimer, listenFinish, swarmFeed, relayFollower, textOpen = false, lastGoalDisplay = '';
+  // One desk per process: a permission card answered from the paired M5Stack races the terminal card.
+  const permissionDesk = new PermissionDesk({ sendCard: card => remoteHost?.sendCard(card), closeCard: id => remoteHost?.closeCard(id), record: row => store.append(session.id, { ...row, source: 'remote_device', at: new Date().toISOString() }) });
+  let controller, authController, modelController, scanController, runtime, peerBus, listenTimer, listenFinish, swarmFeed, relayFollower, textOpen = false, lastGoalDisplay = '';
   const peerGuard=new PeerTurnGuard({cwd,resolveWrite:file=>tools.resolve(file,{create:true}),effects:name=>house.registry.get(name)?.contract?.effects});
   let lastModelProgress = 0;
-  setInterrupt(() => { if(modelController)modelController.abort();else if(authController)authController.abort();else if (controller) controller.abort(); else if (runtime) runtime.exit().catch(error => ui.notice(error.message, true)); else if(listenFinish)listenFinish();else ui?.close(); });
+  setInterrupt(() => { if(scanController)scanController.abort();else if(modelController)modelController.abort();else if(authController)authController.abort();else if (controller) controller.abort(); else if (runtime) runtime.exit().catch(error => ui.notice(error.message, true)); else if(listenFinish)listenFinish();else ui?.close(); });
   // Private files named by flags join the default private locations: no /add-dir may cover them.
   const flagPrivate = [v['state-dir'], v['providers-config'], v['plugin-config']].filter(Boolean).map(item => path.resolve(item));
   const policy = new PermissionPolicy({ mode: permissionMode, dangerouslySkipPermissions: skipPermissions, allowed: csv(v['allowed-tools']), denied: csv(v['disallowed-tools']), cwd, readRoots, privateLocations: flagPrivate,
@@ -382,7 +388,8 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
     confirm: interactive ? async (name, input, options = {}) => {
       const signals = [options.signal, controller?.signal || startupSignal].filter(Boolean), signal = signals.length > 1 ? AbortSignal.any(signals) : signals[0];
       const card = options.summary === undefined ? await house.confirmSummary(name, input, { signal }) : null;
-      return ui.confirm(name, input, signal, { summary: options.summary ?? card?.summary, edit: card?.edit, remember: options.remember });
+      const summary = options.summary ?? card?.summary, terminal = shown => ui.confirm(name, input, shown, { summary, edit: card?.edit, remember: options.remember });
+      return confirmWithDevice({ armed: remoteHost?.permissionsArmed() === true, desk: permissionDesk, questionId: options.questionId, name, input, summary, signal, terminal, resolveWrite: (file, how) => tools.resolve(file, how), confirmAlways: () => policy.confirmAlways(name), mode: () => policy.mode, notice: text => ui.notice(text) });
     } : undefined });
   // /add-dir rows are the human's decisions in this session's book (under .comal, which the model cannot write);
   // on resume they open again if the directory still qualifies, otherwise one line says why.
@@ -400,7 +407,10 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
     }
   };
   const recordLaunchPermissions = () => store.append(session.id, { type: 'mode', source: 'human_cli', mode: policy.mode, dangerously_skip_permissions: skipPermissions, scope: 'process_launch' });
+  // Model calls of the current work and their limit, as model_progress reports them (session.stats).
+  let statsCalls = null;
   const onEvent = event => {
+    if (event.type === 'model_progress') statsCalls = { calls: event.turn, call_limit: event.maxTurns };
     remoteHost?.observe(event);
     if (ui) { ui.handleEvent(event); return; }
     if (format === 'stream-json') stdout.write(JSON.stringify(event) + '\n');
@@ -438,7 +448,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
       stderr.write(color('90', t("Session {v0} · {v1} calls · {v2} tokens", {v0: event.session_id, v1: event.turns, v2: event.usage.input_tokens + event.usage.output_tokens})) + '\n');
     }
   };
-  const house = new House({ cwd, record: async event => { const row=await store.append(event.session_id,event); if(event.session_id===session.id)remoteHost?.invalidateWorkspace(); return row; } });
+  const house = new House({ cwd, record: async event => { const row=await store.append(event.session_id,event); if(event.session_id===session.id)remoteHost?.invalidateWorkspace(); forwardHouseRow(event,{sessionId:session.id,remoteHost}); return row; } });
   if (v.codemode) house.registry.add(codeRunDefinition);
   house.guard('peer-authority',view=>peerGuard.check(view),{revision:'peer-turn-v1',configuration_digest:digest({cwd})});
   const onPermission = decision => store.append(session.id, { type: 'permission', ...decision });
@@ -610,7 +620,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
   house.registry.add({name:'CloudAccountLogout',description:'Human detaches Remote Control and removes the local Comal account credential.',input_schema:emptyInput,audience:'human',surfaces:['tui'],permission:null,effects:{workspace:'none',external:'write',process:'none',authority:'credential_control'},run:async()=>{await remoteHost?.stop();return cloudClient.logout();}});
   const openRemoteControl=async()=>{
     if(!runtime)throw Error('Remote Control requires an interactive local session.');
-    if(!remoteHost || remoteHost.stopped)remoteHost=new RemoteHost({client:new CloudClient({origin:v['cloud-url']}),onInput:(input,binding)=>runtime.admitRemote(input,binding),onStop:id=>runtime.stopRemote(id),onNotice:text=>ui.notice(text),getWorkspace:async snapshot=>projectRemoteWorkspace(snapshot || await store.load(session.id),house.stateContext()),relay:relayRemote,onRelay:interactive?(input,binding)=>relayAnswers.handle(input,binding):null});
+    if(!remoteHost || remoteHost.stopped)remoteHost=new RemoteHost({client:new CloudClient({origin:v['cloud-url']}),onInput:(input,binding)=>runtime.admitRemote(input,binding),onStop:id=>runtime.stopRemote(id),onNotice:text=>ui.notice(text),getWorkspace:async snapshot=>projectRemoteWorkspace(snapshot || await store.load(session.id),house.stateContext()),relay:relayRemote,onRelay:interactive?(input,binding)=>relayAnswers.handle(input,binding):null,onPermission:interactive?(input,binding)=>permissionDesk.handle(input,binding):null,onPermissionsDisarmed:reason=>{store.append(session.id,{type:'remote_control',action:'permissions.arm',armed:false,until:null,reason,source:'host',at:new Date().toISOString()}).catch(()=>{});},getStats:sessionStats});
     const connection = new AbortController(); authController = connection;
     const cancel = () => remoteHost.stop().catch(() => {});
     connection.signal.addEventListener('abort', cancel, { once: true });
@@ -798,7 +808,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
       if (ui && error.usage) ui.handleEvent({ type: 'turn_usage', usage: error.usage });
       if (ui) ui.notice(error.message, true); else stderr.write(`\n${color('31', 'Error')}: ${clean(error.message)}\n`);
       return 1;
-    } finally { await remoteHost?.endTurn(); controller = null; peerGuard.reset();await peerBus.setState('idle'); }
+    } finally { statsCalls = null; await remoteHost?.endTurn(); controller = null; peerGuard.reset();await peerBus.setState('idle'); }
   };
   const peerProbe = memoizedPeerProbe({
     stamp: async () => { const info = await stat(store.file(session.id)); return [session.id, info.size, info.mtimeMs, peerBus.inbound, peerBus.availability?.available].join(':'); },
@@ -815,7 +825,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
       if(format==='json')stdout.write(JSON.stringify(result)+'\n');
       return result.is_error?1:0;
     } catch(error){if(ui)ui.notice(error.message,true);else stderr.write(t("Pending message: {v0}\n", {v0: clean(error.message)}));return 1;}
-    finally{await remoteHost?.endTurn();controller=null;peerGuard.reset();await peerBus.setState('idle');}
+    finally{statsCalls=null;await remoteHost?.endTurn();controller=null;peerGuard.reset();await peerBus.setState('idle');}
   };
   const directTool = async (name, input, text, userIntent) => {
     if (name === 'Agent' && v.demo) throw new Error(t("Subagents require a real model; --demo is a script."));
@@ -888,7 +898,17 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
     const format = { '.csv': 'csv', '.tsv': 'tsv', '.json': 'json', '.md': 'markdown' }[path.extname(file_path).toLowerCase()];
     if (!format) throw new Error(t("Use a .csv, .tsv, .json, or .md file.")); return JSON.stringify({ text, format });
   } });
-  const changeMode = mode => { if (skipPermissions) throw new Error(t(BYPASS_LOCKED_MESSAGE)); return humanTools.execute('SessionMode', { mode }); };
+  const changeMode = async mode => { if (skipPermissions) throw new Error(t(BYPASS_LOCKED_MESSAGE)); const result = await humanTools.execute('SessionMode', { mode }); remoteHost?.publishStats().catch(() => {}); return result; };
+  // session.stats for /rc: the same sources /status, /context and the status bar read; buildSessionStats keeps only numbers, enums and bounded labels.
+  const sessionStats = async () => { try {
+    const current = await store.load(session.id), recorded = statsFromRows(current.rows), rc = remoteHost?.status() || {};
+    let work = null; try { work = projectRemoteWorkspace(current, house.stateContext()); } catch {}
+    const calls = statsCalls || (recorded.usage?.calls !== undefined ? { calls: recorded.usage.calls, call_limit: agent.workMaxCalls } : {});
+    return buildSessionStats({ metadata: metadata(), promptCaching: typeof provider?.promptCaching === 'boolean' ? provider.promptCaching : null,
+      ...readContext({ compactor: agent.compactor, system, tools: agent.tools.definitions(), maxTokens: requestProvider.maxTokens, session: current }),
+      lastCompaction: recorded.lastCompaction, usage: recorded.usage ? { ...recorded.usage, ...calls } : null, timing: recorded.timing, work,
+      permissions: rc.permission_answers || null, transport: rc.transport, addDirCount: policy.workRoots.length, cwd });
+  } catch { return null; } };
   let discoveredModels = [], discoveredModelKey = '', discoveredSessions = [], discoveredPeers = [];
   let authStatus={};
   const refreshConnections=async()=>{const statuses=await Promise.allSettled(AUTH_PROVIDERS.map(item=>authManager.status(item.id)));authStatus=Object.fromEntries(AUTH_PROVIDERS.map((item,index)=>[item.id,statuses[index].status==='fulfilled'?statuses[index].value.status:'unknown']));};
@@ -955,7 +975,7 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
     validateRemote: item => remoteHost?.validate(item) ?? Promise.reject(Error('Remote host detached.')),
     remoteTurnMatches: id => !remoteHost?.stopped && remoteHost?.turnId===id,
     detachRemote: () => remoteHost?.stop(),
-    metadata, discovery, execute: run, interrupt: () => {controller?.abort();authController?.abort();modelController?.abort();}, cycleMode: () => changeMode(nextPermissionMode(policy.mode)),
+    metadata, discovery, execute: run, interrupt: () => {controller?.abort();authController?.abort();modelController?.abort();scanController?.abort();}, cycleMode: () => changeMode(nextPermissionMode(policy.mode)),
     hasPeerMessages:peerProbe,executePeer:runPeer,
     listSessions: async () => { discoveredSessions = await store.list(); return discoveredSessions; }, saveQueue: (id, snapshot) => store.append(id, { type: 'queue', snapshot }), saveDraft: (id, text, attachments = []) => store.append(id, { type: 'draft', text, attachments }),
     goalControl: argument => runGoal(argument),
@@ -1012,7 +1032,28 @@ async function boot(args, createScreen, setInterrupt, startupSignal, host) {
           await relayFlow.record({action:'remote.arm',until:new Date(until).toISOString(),armed:true});
           return relayStatus()+' '+t('Plans and success criteria also need a sign-in from the last 10 minutes in that browser; retrying blocked tasks stays here. /rc relay off disarms.');
         }
-        if(!['','start','status','stop'].includes(action))throw Error('Use /rc [start|status|stop|relay on [30m|2h|8h]|relay off].');
+        // /rc device CODE · /rc device · /rc device forget: empareja el M5Stack con esta sesión de /rc.
+        const deviceCommand=parseRcDevice(action);
+        const bookRecord=row=>store.append(session.id,{...row,source:interactive?'human_tui':'human_cli',at:new Date().toISOString()});
+        // /rc device scan [/dev/videoN]: la cámara lee el QR del M5Stack sólo durante este escaneo (≤30 s) y la persona confirma el código.
+        if(deviceCommand?.kind==='scan'){
+          const scan=async({camera})=>{
+            scanController=new AbortController();
+            const signal=controller?.signal?AbortSignal.any([controller.signal,scanController.signal]):scanController.signal;
+            ui.setupStatus({title:t('Scanning the M5Stack pairing QR'),description:t('Bring the M5Stack 10-20 cm from the camera, so the QR fills about a third of the picture. Up to 30 s; Esc cancels. Frames stay on this machine and are deleted at once.'),signal});
+            ui.callbacks.onSetupCancel=()=>scanController?.abort();
+            try{return await scanPairingQr({camera,signal});}
+            finally{scanController=null;delete ui.callbacks.onSetupCancel;ui.clearSetup();}
+          };
+          const confirm=interactive&&ui?async({code})=>await ui.setupChoice({...deviceCodeChoice(code,t),signal:startupSignal})==='pair':undefined;
+          try{return await runRcDeviceScan(deviceCommand,remoteHost,t,{record:bookRecord,scan,confirm});}
+          catch(error){if(error.name==='AbortError')return error.message;throw error;}
+        }
+        if(deviceCommand)return runRcDevice(deviceCommand,remoteHost,t,{record:bookRecord});
+        // /rc permissions [on [30m|2h]|off]: el aparato emparejado responde tarjetas de permisos, sólo mientras esté armado.
+        const permissionsCommand=parseRcPermissions(action);
+        if(permissionsCommand)return runRcPermissions(permissionsCommand,remoteHost,t,{record:bookRecord});
+        if(!['','start','status','stop'].includes(action))throw Error('Use /rc [start|status|stop|relay on [30m|2h|8h]|relay off|device [CODE|scan [/dev/videoN]|forget]|permissions [on [30m|2h]|off]].');
         if(action==='stop')return humanTools.execute('RemoteControlClose',{});
         if(action==='status')return JSON.stringify(remoteHost?.status() || {enabled:false},null,2);
         if(!await cloudClient.credentials()) {