@milpa/comal 0.2.2 → 0.2.4

package/src/remote-control.mjs

@@ -1,5 +1,8 @@
 import { createHash, randomUUID } from 'node:crypto';
 import { CloudClient } from './cloud-client.mjs';
+import { readFileSync } from 'node:fs';
+import { PERMISSION_ACK_STATES, PERMISSION_OUTCOMES } from './remote-permissions.mjs';
+import { fitStats, STATS_FLOOR_MS, STATS_INTERVAL_MS, STATS_MAX_BYTES } from './remote-stats.mjs';
 
 const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
 export const remoteInputDigest = (session, request, text) => digest([session,request,text]);
@@ -17,19 +20,163 @@ export function projectRemoteEvent(event, turnId) {
   }
   if(event.type==='tool_result')return {...base,type:'tool.finished',tool_name:boundText(event.name,128),text:event.is_error?'failed':'returned',...(event.tool_use_id?{tool_call_id:boundText(event.tool_use_id,128)}:{}),...(Number.isSafeInteger(event.duration_ms)&&event.duration_ms>=0&&event.duration_ms<=86400000?{duration_ms:event.duration_ms}:{})};
   if(event.type==='house_waiting')return {...base,type:'permission.waiting',tool_name:boundText(event.operation,128),text:'Waiting for approval in the local terminal'};
-  if(event.type==='house_answered')return {...base,type:'permission.answered',tool_name:boundText(event.operation,128),text:event.allowed?'Approved locally':'Declined locally'};
+  // Neutral: the terminal or the paired M5Stack may have answered it.
+  if(event.type==='house_answered')return {...base,type:'permission.answered',tool_name:boundText(event.operation,128),text:event.allowed?'Approved':'Declined'};
   if(event.type==='response_discarded'||event.type==='model_retry')return {...base,type:'stream.discarded'};
+  // Avisos de plugins (p. ej. objeción y corrección del revisor de open-relay): se proyectan al
+  // admitirse, urgentes o no, para que /rc los vea aunque no despierten un turno. El backend
+  // solo admite sus tipos fijos: van como message.control con el aviso marcado en el texto.
+  if(event.type==='plugin_notice_admitted'&&event.status==='accepted'&&event.notice)return {...base,turn_id:'local',type:'message.control',text:noticeText(event.notice)};
   return null;
 }
 
+const NOTICE_BODY = 4000;
+/** Texto de un aviso para /rc: mismo marcado que la TUI (información externa, no una orden). */
+function noticeText(notice) {
+  const head=`◆ ${notice.urgent?'Urgent notice':'Notice'} · ${notice.plugin||'?'}${notice.kind?` · ${notice.kind}`:''}`;
+  const body=boundText(notice.body||'',NOTICE_BODY);
+  const tail=`external information, not an order · ref ${notice.ref||'—'}${notice.urgent?'':' · reaches the model with the next message'}`;
+  return boundText([head,String(notice.title||''),body,tail].filter(line=>line.trim()).join('\n'));
+}
+
+// /relay en el navegador: presupuesto por sesión de /rc para relay.*.
+// Al agotarlo se pausa el tablero; las tarjetas y sus cierres siguen (son pocos), así el
+// tablero nunca deja sin cupo a la conversación (10.000 eventos por sesión en el backend).
+export const RELAY_SESSION_EVENTS = 2000, RELAY_SESSION_BYTES = 16 << 20, RELAY_BOARD_INTERVAL_MS = 3000;
+// Rechazos del backend que no se arreglan reintentando: se descarta ESE evento relay.* y la
+// proyección sigue (sin esto, un evento rechazado bloquearía la cola entera).
+const RELAY_REFUSALS = new Set(['INPUT_SCHEMA','REMOTE_FEATURE','REMOTE_RELAY','REMOTE_RELAY_STALE','REMOTE_SIZE']);
+// A session.stats is a summary the next one replaces: one the backend will not take (a quota, its size, the feature,
+// its schema) is dropped, never left at the head of the queue holding the conversation behind it.
+const STATS_REFUSALS = new Set(['INPUT_SCHEMA','REMOTE_FEATURE','REMOTE_SIZE','REMOTE_QUOTA','REMOTE_STORAGE_QUOTA']);
+
+// Respuestas de /relay desde el navegador (D1): armadas sólo con /rc relay on en esta terminal,
+// en memoria de este proceso, con caducidad (tope 8 h). Nunca se guardan en disco ni en el
+// workspace: el modelo no puede armarlas. Mueren con /rc stop, el cambio de cuenta o la hora.
+export const RELAY_ARM_MAX_MS = 8 * 3600e3, RELAY_ARM_DEFAULT_MS = 30 * 60e3;
+// Estados de ACK de un control relay (el backend sólo los admite para kind=relay).
+const RELAY_ACK_STATES = new Set(['applied','stale','refused','expired']);
+// Tarjetas de permiso para el M5Stack: sólo por el WebSocket del host y mientras el armado está vivo;
+// el relay las reenvía al aparato emparejado y no las guarda, así que se reenvían cada 10 s mientras
+// la pregunta sigue abierta (cubre que el aparato se reconecte) y al instante cuando se conecta.
+export const CARD_RESEND_MS = 10000;
+// After an arm, a kept card goes once the pulse landed and again this long after: past the relay's 2 s arm cache.
+export const CARD_ARM_RECHECK_MS = 2500;
+const CARD_CLOSES_KEPT = 32;
+
+// Código de emparejamiento del M5Stack: Crockford en mayúsculas, XXXX-XXXX. O→0, I/L→1.
+const DEVICE_CODE=/^[0-9A-HJKMNP-TV-Z]{8}$/;
+export function normalizeDeviceCode(code){
+  const clean=String(code??'').toUpperCase().replace(/[\s-]+/g,'').replace(/O/g,'0').replace(/[IL]/g,'1');
+  if(!DEVICE_CODE.test(clean))throw Error('That is not a device code: expected 8 letters or digits (XXXX-XXXX).');
+  return clean.slice(0,4)+'-'+clean.slice(4);
+}
+
 const cancelled = () => Object.assign(new Error('Remote Control connection cancelled.'), {name:'AbortError',code:'REMOTE_CANCELLED'});
 const lifetimeSignal = (run,timeout=10000) => run?.controller ? AbortSignal.any([run.controller.signal,AbortSignal.timeout(timeout)]) : AbortSignal.timeout(timeout);
 
+let quickReplyList=null;
+/** The three fixed replies come from the device contract, read once. */
+function quickReplies(){return quickReplyList??=JSON.parse(readFileSync(new URL('../backend/contracts/remote-device-v1.json',import.meta.url),'utf8')).inputs.quick_reply.properties.text.enum;}
 export class RemoteHost {
-  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},getWorkspace=null,socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
-    Object.assign(this,{client,onInput,onStop,onNotice,getWorkspace,socketFactory});this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
+  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},getWorkspace=null,relay=null,onRelay=null,onDeviceConnected=null,onPermissionsDisarmed=null,onPermission=null,getStats=null,now=Date.now,socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
+    Object.assign(this,{client,onInput,onStop,onNotice,getWorkspace,relay,onRelay,onDeviceConnected,onPermissionsDisarmed,onPermission,getStats,now,socketFactory});this.cards=new Map();this.cardCloses=[];this.cardsSentAt=0;this.cardsShown=false;this.answersUntil=0;this.permissionUntil=0;this.permissionDevice=null;this.deviceInfo=null;this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
+  }
+  status(){const run=this.lifecycle;return this.session?{enabled:!this.stopped,url:this.url,session:this.session.id,transport:this.transport,permissions:'local_terminal_only',relay:run?.relay?(run.answers?'answers':'read_only'):'off',...(run?.answers?{relay_answers:{armed:this.armed(),until:this.armed()?this.answersUntil:null}}:{}),...(run?.device?{device:this.deviceInfo??null,permission_answers:{armed:this.permissionsArmed(),until:this.permissionsArmed()?this.permissionUntil:null}}:{})}:{enabled:false};}
+  deviceAvailable(){return Boolean(this.current(this.lifecycle)&&this.lifecycle.device);}
+  permissionsArmed(){return this.deviceAvailable()&&this.permissionUntil>this.now()&&Boolean(this.deviceInfo)&&this.deviceInfo.id===this.permissionDevice;}
+  /** The arm belongs to the device it was granted for: when that device is gone or another takes its place, it ends and the book hears why. */
+  dropArm(reason){
+    const was=this.permissionUntil>0;
+    this.permissionUntil=0;this.permissionDevice=null;
+    if(!was)return;
+    this.hideCards();
+    if(this.deviceAvailable())this.pulse().catch(()=>{});
+    if(this.onPermissionsDisarmed)try{this.onPermissionsDisarmed(reason);}catch{}
+  }
+  /** Recuerda el dispositivo de la última lectura de remote.state (page.session) o del emparejamiento; gana lo más reciente. */
+  noteSession(session){
+    if(!session||!('device' in session))return false;
+    const before=this.deviceInfo?.connected_at??null;
+    this.deviceInfo=session.device?{id:session.device.id,label:session.device.label,connected_at:session.device.connected_at??null}:null;
+    if(this.permissionUntil>0&&(this.deviceInfo?.id??null)!==this.permissionDevice)this.dropArm(this.deviceInfo?'device_changed':'device_gone');
+    const after=this.deviceInfo?.connected_at??null,changed=after!==null&&after!==before;
+    if(changed&&this.onDeviceConnected)try{this.onDeviceConnected(this.deviceInfo);}catch{}
+    if(changed){this.sendCards();this.publishStats({device:true}).catch(()=>{});}
+    return changed;
+  }
+  async pairDevice(code){
+    const normalized=normalizeDeviceCode(code);
+    if(!this.deviceAvailable())throw Error('Open /rc first, with a Comal backend that supports devices.');
+    const run=this.lifecycle;
+    const result=await this.client.invoke('remote.devices.pair.approve',{remote_session_id:this.session.id,code:normalized},{expectedAccount:this.account,signal:lifetimeSignal(run)});
+    this.assertCurrent(run);
+    this.deviceInfo={id:result.device_id,label:result.label,connected_at:this.deviceInfo?.id===result.device_id?this.deviceInfo.connected_at:null};
+    if(this.permissionUntil>0&&result.device_id!==this.permissionDevice)this.dropArm('device_changed');
+    return {device_id:result.device_id,label:result.label};
+  }
+  async forgetDevice(){
+    if(!this.deviceAvailable())throw Error('Open /rc first, with a Comal backend that supports devices.');
+    const run=this.lifecycle;
+    await this.client.invoke('remote.devices.revoke',{remote_session_id:this.session.id},{expectedAccount:this.account,signal:lifetimeSignal(run)});
+    this.permissionUntil=0;this.permissionDevice=null;this.hideCards();this.deviceInfo=null;this.pulse(run).catch(()=>{});
+  }
+  /** /rc permissions on [duración]: el aparato emparejado puede responder tarjetas hasta now+ms (60 s…8 h, y no más allá de la sesión). */
+  armPermissions(ms=RELAY_ARM_DEFAULT_MS){
+    if(!this.deviceAvailable())throw Error('Open /rc first, with a Comal backend that supports devices.');
+    if(!this.deviceInfo)throw Error('Pair a device first with /rc device CODE.');
+    const now=this.now(),expires=Number(this.session?.expires_at)*1000;
+    if(Number.isFinite(expires)&&expires<=now)throw Error('The /rc session has expired; open /rc again.');
+    let until=now+Math.min(Math.max(60e3,Math.floor(Number(ms)||RELAY_ARM_DEFAULT_MS)),RELAY_ARM_MAX_MS);
+    if(Number.isFinite(expires))until=Math.min(until,expires);
+    this.permissionUntil=until;this.permissionDevice=this.deviceInfo.id;
+    // A kept card goes only once the backend holds the arm (the relay refuses a card it cannot confirm armed), and
+    // again CARD_ARM_RECHECK_MS later, when an arm the relay read before this pulse is no longer fresh enough to use.
+    const run=this.lifecycle;
+    this.pulse(run).catch(()=>{}).then(()=>{if(!this.current(run)||!this.sendCards())return;this.cardsSentAt=this.now()-CARD_RESEND_MS+CARD_ARM_RECHECK_MS;});
+    return until;
+  }
+  /** One frame over the host WebSocket, only when it is the live transport. Never over remote.events.publish. */
+  cardFrame(frame){
+    if(this.transport!=='websocket'||this.socket?.readyState!==1)return false;
+    try{this.socket.send(JSON.stringify({protocol:'comal.remote.v1',...frame}));return true;}catch{return false;}
+  }
+  /** Permission card for the paired device (Task 10's buildDeviceCard). Nothing is kept or sent while not armed. */
+  sendCard(card){
+    if(!card||typeof card.question_id!=='string'||!this.permissionsArmed())return false;
+    this.cards.set(card.question_id,card);return this.sendCards();
   }
-  status(){return this.session?{enabled:!this.stopped,url:this.url,session:this.session.id,transport:this.transport,permissions:'local_terminal_only'}:{enabled:false};}
+  sendCards(){
+    if(!this.cards.size||!this.permissionsArmed())return false;
+    let sent=false;for(const card of this.cards.values())sent=this.cardFrame({kind:'card',card})||sent;
+    if(sent){this.cardsSentAt=this.now();this.cardsShown=true;}
+    return sent;
+  }
+  /** The arm ended (off, lapsed, the device gone): the device stops showing cards it can no longer answer.
+   *  They are kept, so a new arm while the question is still open shows them again. */
+  hideCards(){
+    if(!this.cards.size||!this.cardsShown)return;
+    let sent=true;for(const id of this.cards.keys())sent=this.cardFrame({kind:'card.close',question_id:id})&&sent;
+    if(sent)this.cardsShown=false;
+  }
+  /** The question was decided or dropped: the device stops showing it (on the next connection if the socket is down). */
+  closeCard(questionId){
+    const had=this.cards.delete(questionId);
+    if(this.cardFrame({kind:'card.close',question_id:questionId})||!had)return;
+    this.cardCloses.push(questionId);if(this.cardCloses.length>CARD_CLOSES_KEPT)this.cardCloses.shift();
+  }
+  flushCardCloses(){while(this.cardCloses.length&&this.cardFrame({kind:'card.close',question_id:this.cardCloses[0]}))this.cardCloses.shift();}
+  disarmPermissions(){this.permissionUntil=0;this.permissionDevice=null;this.hideCards();if(this.deviceAvailable())this.pulse().catch(()=>{});}
+  /** ¿Puede esta sesión de /rc responder tarjetas de /relay? (backend con relay_answers_v1). */
+  answersAvailable(){return Boolean(this.current(this.lifecycle)&&this.lifecycle.answers);}
+  armed(){return this.answersAvailable()&&this.answersUntil>this.now();}
+  /** /rc relay on [duración]: arma las respuestas del navegador hasta now+ms (tope 8 h). */
+  arm(ms=RELAY_ARM_DEFAULT_MS){
+    if(!this.answersAvailable())throw Error(this.lifecycle?.relay?'This Comal backend does not accept /relay answers from the browser yet.':'Open /rc in a session linked to /relay first.');
+    const span=Math.min(Math.max(60e3,Math.floor(Number(ms)||RELAY_ARM_DEFAULT_MS)),RELAY_ARM_MAX_MS);
+    this.answersUntil=this.now()+span;this.pulse().catch(()=>{});return this.answersUntil;
+  }
+  disarm(){this.answersUntil=0;if(this.current(this.lifecycle))this.pulse().catch(()=>{});}
   current(run,{starting=false}={}) {return this.lifecycle===run && (starting || !this.stopped) && !run?.controller?.signal.aborted;}
   assertCurrent(run,options){if(!this.current(run,options))throw cancelled();}
   async revoke(run) {
@@ -49,8 +196,22 @@ export class RemoteHost {
         if(!account)throw Error('Sign in with comal cloud login before enabling Remote Control.');
         run.account={origin:account.origin,user_id:account.user_id};run.enablingToken=account.token;
         const workspace=this.getWorkspace?await this.getWorkspace(session):null;this.assertCurrent(run,{starting:true});
-        const opened=await this.client.invoke('remote.sessions.open',{local_session_id:session.id,host_id:randomUUID(),label:boundText(session.name || 'Comal',80),features:['commands_v1','thinking_v1',...(this.getWorkspace?['workspace_v1']:[])]},{expectedAccount:run.account,signal:run.controller.signal});
+        const features=['commands_v1','thinking_v1',...(this.getWorkspace?['workspace_v1']:[]),...(this.relay?['relay_v1']:[]),...(this.relay&&this.onRelay?['relay_answers_v1']:[]),'device_v1','stats_v1'];
+        const open=list=>this.client.invoke('remote.sessions.open',{local_session_id:session.id,host_id:randomUUID(),label:boundText(session.name || 'Comal',80),features:list},{expectedAccount:run.account,signal:run.controller.signal});
+        // Un backend anterior rechaza la capacidad desconocida en el esquema de Milpa (no se crea
+        // sesión): se reintenta sin relay_answers_v1 (backend de la fase «ver») y después sin
+        // relay_v1 (backend anterior a /relay). /rc se abre igual con lo que el backend admite.
+        const noDevice=features.filter(item=>item!=='device_v1'&&item!=='stats_v1');
+        const attempts=[features,noDevice,noDevice.filter(item=>item!=='relay_answers_v1'),noDevice.filter(item=>!item.startsWith('relay_'))].filter((list,index,all)=>index===0||list.length<all[index-1].length);
+        let opened,used=attempts[0];
+        for(const [index,list] of attempts.entries()){
+          try{used=list;opened=await open(list);break;}
+          catch(error){if(error.code!=='INPUT_SCHEMA'||index===attempts.length-1)throw error;this.assertCurrent(run,{starting:true});}
+        }
+        run.relayRefused=Boolean(this.relay)&&!used.includes('relay_v1');
         run.session=opened.session;
+        const granted=feature=>used.includes(feature)&&(!Array.isArray(opened.session?.features)||opened.session.features.includes(feature));
+        run.relay=Boolean(this.relay)&&granted('relay_v1');run.answers=run.relay&&Boolean(this.onRelay)&&granted('relay_answers_v1');this.answersUntil=0;run.device=granted('device_v1');run.stats=Boolean(this.getStats)&&granted('stats_v1');this.permissionUntil=0;this.permissionDevice=null;this.deviceInfo=null;
         // Abort can race a successful response. Revoke a late-created grant even
         // when the local stop completed before its identifier became available.
         if(!this.current(run,{starting:true})){await this.revoke(run);throw cancelled();}
@@ -58,12 +219,14 @@ export class RemoteHost {
         await this.authorize(run);this.assertCurrent(run);await this.pulse(run);this.assertCurrent(run);
         this.transport='https-polling';this.connectSocket(run);
         if(workspace)this.publishWorkspace(workspace,run);
+        this.publishStats({},run).catch(()=>{});
+        if(run.relay){run.relaySink={extended:run.answers,relayBoard:(board,options)=>this.relayBoard(board,options,run),relayEvent:(type,relay)=>this.relayEvent(type,relay,run)};this.relay.attach(run.relaySink);}
         this.timer=setInterval(()=>this.tick(run),1000);this.timer.unref();
         for(const message of (session.historyMessages || []).slice(-20)){
           const event=message.role==='user'&&(typeof message.content==='string'||Array.isArray(message.content)&&message.content.some(block=>block.type==='text'))?{type:'user',text:typeof message.content==='string'?message.content:message.content.filter(block=>block.type==='text').map(block=>block.text).join('\n')}:message.role==='assistant'?{type:'assistant',message}:null;
           if(event)this.observe(event);
         }
-        this.onNotice('Remote Control: '+this.url+' · transcript stored on your Comal backend; permissions stay in this terminal.');
+        this.onNotice('Remote Control: '+this.url+' · transcript stored on your Comal backend; permissions stay in this terminal.'+(run.answers?' /relay is visible there; to answer its cards from the browser run /rc relay on here (off by default).':run.relay?' /relay is visible there read-only; answer its cards here.':run.relayRefused?' This backend does not show /relay yet.':''));
         return this.status();
       } catch(error) {
         if(this.lifecycle===run)await this.stop();else await this.revoke(run);
@@ -99,7 +262,7 @@ export class RemoteHost {
       const ws=this.socket=this.socketFactory(url.href,'comal.remote.v1');
       const timeout=this.socketTimeout=setTimeout(()=>ws.close(),10000);timeout.unref();
       ws.addEventListener('open',()=>{if(!this.current(run)||this.socket!==ws){ws.close();return;}ws.send(JSON.stringify({protocol:'comal.remote.v1',kind:'auth',ticket:ticket.ticket,after:'0'}));});
-      ws.addEventListener('message',event=>{if(!this.current(run)||this.socket!==ws)return;try{const m=JSON.parse(event.data);if(m.kind==='ready'){clearTimeout(timeout);this.transport='websocket';}}catch{ws.close();}});
+      ws.addEventListener('message',event=>{if(!this.current(run)||this.socket!==ws)return;try{const m=JSON.parse(event.data);if(m.kind==='ready'){clearTimeout(timeout);this.transport='websocket';this.flushCardCloses();this.sendCards();}else if(m.kind==='state'&&run.device)this.noteSession(m.session);}catch{ws.close();}});
       ws.addEventListener('error',()=>{});
       ws.addEventListener('close',()=>{clearTimeout(timeout);if(this.current(run)&&this.socket===ws){this.socket=null;this.transport='https-polling';}});
     }catch{/* HTTPS is already active. A later tick retries WSS. */}
@@ -113,6 +276,73 @@ export class RemoteHost {
     this.pending.push({event_id:randomUUID(),event:{type:'workspace.snapshot',text:'',turn_id:this.turnId||'local',workspace}});
     run.workspaceDigest=key;this.flush(run).catch(()=>{});
   }
+  /** session.stats (stats_v1). A change: at most once per 5 s. `force` (turn end): skips the 5 s but
+   *  not the unchanged check. `device` (a device connected): publishes even unchanged, since it has
+   *  not seen them. Never two publishes within 1 s: a request inside the gap waits for one timer,
+   *  which carries the strongest reason asked for. Never oversize; a getStats that fails or gives null publishes nothing. */
+  publishStats({force=false,device=false}={},run=this.lifecycle){
+    if(!this.current(run)||!run.stats||!this.getStats)return Promise.resolve(false);
+    const step=(run.statsChain||Promise.resolve()).then(()=>this.publishStatsNow({force:force||device,device},run)).catch(()=>false);
+    run.statsChain=step;return step;
+  }
+  async publishStatsNow({force,device},run){
+    if(!this.current(run))return false;
+    const now=this.now(),wait=run.statsAt?run.statsAt+(force?STATS_FLOOR_MS:STATS_INTERVAL_MS)-now:0;
+    if(wait>0){
+      const asked=run.statsAsked||{force:false,device:false};run.statsAsked={force:asked.force||force,device:asked.device||device};
+      if(!run.statsTimer||now+wait<run.statsTimerAt){
+        clearTimeout(run.statsTimer);run.statsTimerAt=now+wait;
+        run.statsTimer=setTimeout(()=>{const again=run.statsAsked||{};run.statsAsked=null;run.statsTimer=null;this.publishStats(again,run).catch(()=>{});},wait);run.statsTimer.unref?.();
+      }
+      return false;
+    }
+    const stats=fitStats(await this.getStats());
+    if(!this.current(run)||!stats)return false;
+    const key=JSON.stringify(stats);
+    if(Buffer.byteLength(key)>STATS_MAX_BYTES||(!device&&key===run.statsKey))return false;
+    const entry={event_id:randomUUID(),event:{type:'session.stats',text:'',turn_id:this.turnId||'local',stats}};
+    // The last summary wins in the buffer: an unsent one is replaced, never stacked.
+    const index=this.pending.findIndex((item,position)=>item.event.type==='session.stats'&&(position>0||!this.sending));
+    if(index>=0)this.pending[index]=entry;
+    else{if(this.pending.length>=512)return false;this.pending.push(entry);}
+    run.statsKey=key;run.statsAt=this.now();clearTimeout(run.statsTimer);run.statsTimer=null;run.statsAsked=null;
+    this.flush(run).catch(()=>{});return true;
+  }
+  /** Tablero de /swarm: coalescido (≥ 3 s), sin repetir huella y «el último gana» en el búfer. */
+  relayBoard(board,{now=false}={},run=this.lifecycle) {
+    if(!this.current(run)||!run.relay)return;
+    const {source,...content}=board,key=digest(content);
+    run.boardNext=key===run.boardDigest?null:board;run.boardNextKey=key;
+    if(!run.boardNext)return;
+    const wait=now?0:Math.max(0,(run.boardAt||0)+RELAY_BOARD_INTERVAL_MS-Date.now());
+    if(!wait){clearTimeout(run.boardTimer);run.boardTimer=null;this.pushRelayBoard(run);return;}
+    if(!run.boardTimer){run.boardTimer=setTimeout(()=>{run.boardTimer=null;this.pushRelayBoard(run);},wait);run.boardTimer.unref?.();}
+  }
+  pushRelayBoard(run=this.lifecycle) {
+    if(!this.current(run)||!run.boardNext||run.boardPaused)return;
+    let board=run.boardNext;const key=run.boardNextKey;run.boardNext=null;
+    if((run.relayEvents||0)>=RELAY_SESSION_EVENTS||(run.relayBytes||0)>=RELAY_SESSION_BYTES){
+      run.boardPaused=true;board={...board,swarms:[],paused:true,omitted:{swarms:board.swarms_total||0,tasks:0}};
+      this.onNotice('Remote /relay board paused: this /rc session reached its relay budget. Cards still reach the browser; /swarm here keeps the live board.');
+    }
+    // El backend no admite un tablero que retroceda en el tiempo de su foto.
+    const seen=Math.max(Number(board.source?.view_generated_at)||1,run.boardSeen||1);board={...board,source:{...board.source,view_generated_at:seen}};run.boardSeen=seen;
+    const entry={event_id:randomUUID(),event:{type:'relay.board',text:'',turn_id:'local',relay:board}};
+    if(Buffer.byteLength(JSON.stringify(board))>36000)return;
+    const index=this.pending.findIndex((item,position)=>item.event.type==='relay.board'&&(position>0||!this.sending));
+    if(index>=0)this.pending[index]=entry;
+    else{if(this.pending.length>=512)return;this.pending.push(entry);}
+    run.boardDigest=key;run.boardAt=Date.now();this.relayAccount(run,entry.event);this.flush(run).catch(()=>{});
+  }
+  /** relay.card, relay.card.page y relay.resolved: siempre salen (dentro del búfer de 512). */
+  relayEvent(type,relay,run=this.lifecycle) {
+    if(!this.current(run)||!run.relay)return false;
+    if(Buffer.byteLength(JSON.stringify(relay))>36000)return false;
+    if(this.pending.length>=512){this.onNotice('Remote /relay card skipped: outbound buffer full. The card stays in this terminal.');return false;}
+    const entry={event_id:randomUUID(),event:{type,text:'',turn_id:'local',relay}};
+    this.pending.push(entry);this.relayAccount(run,entry.event);this.flush(run).catch(()=>{});return true;
+  }
+  relayAccount(run,event){run.relayEvents=(run.relayEvents||0)+1;run.relayBytes=(run.relayBytes||0)+Buffer.byteLength(JSON.stringify(event));}
   invalidateWorkspace() {
     const run=this.lifecycle;if(!this.current(run)||!this.getWorkspace)return;
     run.workspaceDirty=true;
@@ -130,6 +360,7 @@ export class RemoteHost {
     if(this.stopped)return;
     if(['tool_result','house_waiting','house_answered','result'].includes(event.type))this.invalidateWorkspace();
     const append=projected=>this.pending.push({event_id:randomUUID(),event:projected});
+    if(['result','context_projection','usage_accounting'].includes(event.type))this.publishStats().catch(()=>{});
     if(event.type==='model_stream_progress'&&event.reasoning_chars>0&&!this.thinkingActive){
       this.thinkingActive=true;append({type:'thinking.started',turn_id:this.turnId||'local',text:'Thinking…'});this.flush().catch(()=>{});return;
     }
@@ -157,14 +388,24 @@ export class RemoteHost {
   async flush(run=this.lifecycle){
     if(!this.current(run))return;
     if(this.sending)return this.sending;
-    const work=(async()=>{while(this.current(run)&&this.pending.length){await this.call('remote.events.publish',this.pending[0],run);this.assertCurrent(run);this.pending.shift();}})();
+    const work=(async()=>{while(this.current(run)&&this.pending.length){
+      const item=this.pending[0];
+      try{await this.call('remote.events.publish',item,run);}
+      catch(error){
+        if(!this.current(run))throw error;
+        if(item.event?.type==='session.stats'&&STATS_REFUSALS.has(error.code)){/* dropped: the next summary replaces it */}
+        else if(String(item.event?.type).startsWith('relay.')&&RELAY_REFUSALS.has(error.code))this.onNotice('Remote /relay event refused by the backend ('+error.code+'); /relay and /swarm in this terminal are unaffected.');
+        else throw error;
+      }
+      this.assertCurrent(run);if(this.pending[0]===item)this.pending.shift();else{const index=this.pending.indexOf(item);if(index>=0)this.pending.splice(index,1);}
+    }})();
     this.sending=work;try{return await work;}finally{if(this.sending===work)this.sending=null;}
   }
-  pulse(run=this.lifecycle){const work=(this.pulsing || Promise.resolve()).catch(()=>{}).then(()=>{if(this.current(run))return this.call('remote.host.pulse',{status:this.turnId?'busy':'idle',turn_id:this.turnId},run);});this.pulsing=work;return work;}
+  pulse(run=this.lifecycle){const work=(this.pulsing || Promise.resolve()).catch(()=>{}).then(()=>{if(!this.current(run))return;const armed=run.answers&&this.answersUntil>this.now(),permitted=Boolean(run.device)&&this.permissionUntil>this.now();return this.call('remote.host.pulse',{status:this.turnId?'busy':'idle',turn_id:this.turnId,...(run.answers?{relay_answers:{armed,until:armed?Math.floor(this.answersUntil/1000):0}}:{}),...(run.device?{permission_answers:{armed:permitted,until:permitted?Math.floor(this.permissionUntil/1000):0}}:{})},run);});this.pulsing=work;return work;}
   async beginTurn(){this.turnId=randomUUID();if(!this.stopped)this.pulse().catch(error=>{if(error.code!=='REMOTE_CANCELLED')this.onNotice('Remote state unavailable: '+error.message);});}
   async endTurn(){
     this.invalidateWorkspace();
-    if(!this.stopped){this.pending.push({event_id:randomUUID(),event:{type:'turn.settled',text:'Local turn settled.',turn_id:this.turnId || 'local'}});this.flush().catch(()=>{});}
+    if(!this.stopped){this.pending.push({event_id:randomUUID(),event:{type:'turn.settled',text:'Local turn settled.',turn_id:this.turnId || 'local'}});this.flush().catch(()=>{});this.publishStats({force:true}).catch(()=>{});}
     clearTimeout(this.deltaTimer);this.deltaTimer=null;this.delta='';this.thinkingActive=false;this.turnId=null;this.pulse().catch(()=>{});
   }
   async validate(item){
@@ -174,18 +415,26 @@ export class RemoteHost {
     await this.call('remote.inputs.validate',{request_id:item.remote.request},run);this.assertCurrent(run);return true;
   }
   async tick(run=this.lifecycle){
+    if(this.current(run)&&this.cards.size){if(!this.permissionsArmed())this.hideCards();else if(this.now()-this.cardsSentAt>=CARD_RESEND_MS)this.sendCards();}
     if(!this.current(run)||this.processing)return this.processing;
     const work=(async()=>{
       await this.pulse(run);this.assertCurrent(run);await this.flush(run);this.assertCurrent(run);
       const page=await this.call('remote.inputs.claim',{},run);this.assertCurrent(run);
       for(const input of page.inputs){
-        this.assertCurrent(run);let state='accepted_locally',queue_item_id='';
+        this.assertCurrent(run);let state='accepted_locally',queue_item_id='',outcome=null;
         // Only admission errors are rejection. A lost ACK must redeliver the same input.
-        try {
+        if(input.kind==='relay'){({state,outcome}=await this.relayAnswer(input,run));}
+        else if(input.kind==='permission.answer'){({state,outcome}=await this.permissionAnswer(input,run));}
+        else try {
           if(input.kind==='stop'){if(input.turn_id!==this.turnId||!await this.onStop(input.turn_id))throw Error('Stale turn.');queue_item_id='stop:'+input.turn_id;}
+          else if(input.kind==='quick.reply'){const text=input.control?.text;if(typeof text!=='string'||!quickReplies().includes(text))throw Error('Unknown quick reply.');const accepted=await this.onInput({...input,text},{session:this.session.id,request:input.request_id});queue_item_id=accepted.id;}
           else {const accepted=await this.onInput(input,{session:this.session.id,request:input.request_id});queue_item_id=accepted.id;}
         }catch{state='rejected';}
-        this.assertCurrent(run);await this.call('remote.inputs.ack',{request_id:input.request_id,state,queue_item_id},run);
+        this.assertCurrent(run);
+        try{await this.call('remote.inputs.ack',{request_id:input.request_id,state,queue_item_id,...(outcome?{outcome}:{})},run);}
+        // The backend already settled this device input (expired or its device gone after the claim):
+        // it is not retried nor applied again; the local book row stays the record of what was decided here.
+        catch(error){if(input.kind!=='permission.answer'||error?.code!=='REMOTE_CONFLICT')throw error;}
       }
       if(!this.socket&&Date.now()>this.nextSocketAt)this.connectSocket(run);
     })().catch(error=>{
@@ -195,10 +444,29 @@ export class RemoteHost {
     });
     this.processing=work;try{return await work;}finally{if(this.processing===work)this.processing=null;}
   }
+  /** Control tipado del navegador sobre una tarjeta de /relay (kind=relay). Nunca entra en la cola
+   *  del modelo: lo revalida y aplica el broker local con las funciones de la TUI. */
+  async relayAnswer(input,run=this.lifecycle){
+    if(!run?.answers||!this.onRelay)return {state:'refused',outcome:'host_legacy'};
+    try{
+      const result=await this.onRelay(input,{session:this.session.id,epoch:this.session.host_epoch,armed:()=>this.armed(),validate:()=>this.validate({remote:{session:this.session.id,request:input.request_id}})});
+      const state=RELAY_ACK_STATES.has(result?.state)?result.state:'refused';
+      return {state,outcome:/^[a-z_]{1,64}$/.test(String(result?.outcome||''))?result.outcome:'host_error'};
+    }catch(error){if(!this.current(run))throw error;return {state:'refused',outcome:'host_error'};}
+  }
+  /** Answer to a permission card from the paired M5Stack (kind=permission.answer). Never enters the model's
+   *  queue: the PermissionDesk checks it again (arm, expiry, device, pending question, digest) and decides. */
+  async permissionAnswer(input,run=this.lifecycle){
+    if(!run?.device||!this.onPermission)return {state:'refused',outcome:'disarmed'};
+    try{
+      const result=await this.onPermission(input,{deviceId:this.permissionsArmed()?this.permissionDevice:null,armed:()=>this.permissionsArmed()});
+      return {state:PERMISSION_ACK_STATES.has(result?.state)?result.state:'refused',outcome:PERMISSION_OUTCOMES.has(result?.outcome)?result.outcome:'stale'};
+    }catch(error){if(!this.current(run))throw error;return {state:'refused',outcome:'stale'};}
+  }
   async stop(){
     const run=this.lifecycle || {session:this.session,account:this.account,enablingToken:this.enablingToken};
-    this.lifecycle=null;this.starting=null;run.controller?.abort();clearTimeout(run.workspaceTimer);
-    this.stopped=true;clearInterval(this.timer);clearTimeout(this.deltaTimer);clearTimeout(this.socketTimeout);this.socket?.close();this.socket=null;this.delta='';this.transport='disconnected';
+    this.lifecycle=null;this.starting=null;run.controller?.abort();clearTimeout(run.workspaceTimer);clearTimeout(run.boardTimer);clearTimeout(run.statsTimer);if(run.relaySink)this.relay?.detach(run.relaySink);
+    this.stopped=true;this.answersUntil=0;this.permissionUntil=0;this.permissionDevice=null;this.cards.clear();this.cardCloses=[];this.cardsSentAt=0;this.cardsShown=false;clearInterval(this.timer);clearTimeout(this.deltaTimer);clearTimeout(this.socketTimeout);this.socket?.close();this.socket=null;this.delta='';this.transport='disconnected';
     this.access=null;this.enablingToken=null;this.pending=[];this.turnId=null;this.processing=null;this.sending=null;this.pulsing=null;this.connecting=null;
     await this.revoke(run);return this.status();
   }

package/src/remote-device-card.mjs

@@ -0,0 +1,111 @@
+// Permission card for the paired M5Stack: what Comal wants to run, trimmed and sanitized so the
+// person sees what they approve. Pure module; the host wires it where the permission is armed.
+import { createHash } from 'node:crypto';
+import { readFileSync } from 'node:fs';
+import { digest } from './operations.mjs';
+
+const CARD = JSON.parse(readFileSync(new URL('../backend/contracts/remote-device-v1.json', import.meta.url), 'utf8')).card;
+const MAX_BYTES = CARD.maxBytes;
+const MAX_LINES = CARD.schema.properties.lines.maxItems;
+const LINE_CHARS = CARD.schema.properties.lines.items.maxLength;
+const TOOL_CHARS = CARD.schema.properties.tool.maxLength;
+const BASH_CHARS = 600;
+const BODY_LINES = 12;
+const SUMMARY_TITLE = 'Resumen declarado por la operación';
+
+// Same set as the terminal card (src/tui/present.mjs INVISIBLE): controls, bidi and format
+// characters. The terminal escapes them; the device strips them (tab and newline handled apart).
+const INVISIBLE = /[\x00-\x08\x0b-\x1f\x7f-\x9f\u200b-\u200f\u2028\u2029\u202a-\u202e\u2060-\u2064\u2066-\u2069\ufeff]/g;
+export const stripForDevice = text => String(text ?? '').replace(/\t/g, '  ').replace(INVISIBLE, '');
+
+const segmenter = new Intl.Segmenter(undefined, { granularity: 'grapheme' });
+const cpLength = text => Array.from(text).length;
+
+/** Pieces of at most `limit` code points; a grapheme cluster is kept whole when it fits. */
+function pieces(text, limit) {
+  const out = [];
+  let current = '', used = 0;
+  const push = (part, size) => {
+    if (used + size > limit) { out.push(current); current = ''; used = 0; }
+    current += part; used += size;
+  };
+  for (const { segment } of segmenter.segment(text)) {
+    const size = cpLength(segment);
+    if (size <= limit) push(segment, size);
+    else for (const point of Array.from(segment)) push(point, 1);
+  }
+  if (current || !out.length) out.push(current);
+  return out;
+}
+/** First `limit` code points, ending on a grapheme boundary. */
+function cut(text, limit) {
+  let used = 0, out = '';
+  for (const { segment } of segmenter.segment(text)) {
+    const size = cpLength(segment);
+    if (used + size > limit) return { text: out, cut: true };
+    out += segment; used += size;
+  }
+  return { text: out, cut: false };
+}
+// Characters removed by the strip are reported (state.stripped) so the card says it is not the raw text.
+const strip = (text, state) => { const raw = String(text ?? ''); const clean = stripForDevice(raw); if (raw.replace(INVISIBLE, '') !== raw) state.stripped = true; return clean; };
+const oneLine = (text, state) => strip(text, state).replace(/\n/g, ' ');
+const countLines = text => text === '' ? 0 : text.split('\n').length;
+
+function wrapped(text, maxChars, maxLines) {
+  const head = cut(text, maxChars);
+  const lines = head.text.split('\n').flatMap(line => pieces(line, LINE_CHARS));
+  return { lines: lines.slice(0, maxLines), truncated: head.cut || lines.length > maxLines };
+}
+/** Header line plus up to BODY_LINES prefixed lines, each cut to one device line. */
+function headed(header, body) {
+  const lines = [], flags = [];
+  const head = cut(header, LINE_CHARS); lines.push(head.text); flags.push(head.cut);
+  for (const [prefix, text] of body.slice(0, BODY_LINES)) {
+    const line = cut(prefix + text, LINE_CHARS); lines.push(line.text); flags.push(line.cut);
+  }
+  return { lines, truncated: flags.some(Boolean) || body.length > BODY_LINES };
+}
+const plainObject = value => value && typeof value === 'object' && !Array.isArray(value);
+
+function render({ tool, input, summary, overwrite }, state) {
+  if (typeof summary === 'string' && summary.trim()) {
+    const body = wrapped(strip(summary.trim(), state), BASH_CHARS, MAX_LINES - 1);
+    return { kind: 'summary', lines: [SUMMARY_TITLE, ...body.lines], truncated: body.truncated };
+  }
+  if (plainObject(input) && tool === 'Bash' && typeof input.command === 'string') return { kind: 'bash', ...wrapped(strip(input.command, state), BASH_CHARS, MAX_LINES) };
+  if (plainObject(input) && tool === 'Write' && typeof input.content === 'string') {
+    const content = strip(input.content, state);
+    const path = oneLine(input.file_path ?? '', state);
+    const body = (content === '' ? [] : content.split('\n')).map(line => ['', line]);
+    return { kind: 'write', ...headed(`${path} · ${overwrite === true ? 'reemplaza' : overwrite === false ? 'nueva' : '?'} · ${countLines(content)} líneas`, body) };
+  }
+  if (plainObject(input) && tool === 'Edit' && typeof input.old_string === 'string' && typeof input.new_string === 'string') {
+    const removed = strip(input.old_string, state), added = strip(input.new_string, state);
+    const body = [...(removed === '' ? [] : removed.split('\n')).map(line => ['- ', line]), ...(added === '' ? [] : added.split('\n')).map(line => ['+ ', line])];
+    return { kind: 'edit', ...headed(`${oneLine(input.file_path ?? '', state)} · +${countLines(added)} −${countLines(removed)}${input.replace_all === true ? ' · todas' : ''}`, body) };
+  }
+  return { kind: 'terminal', lines: [], truncated: true };
+}
+
+export function buildDeviceCard({ questionId, name, input, summary, overwrite, terminalOnly = false } = {}) {
+  // Only the exact built-in names render natively: a namespaced tool (mcp__x__Bash) is never a bash card.
+  // terminalOnly: a card the device may not answer (confirm:'always', plan mode) says only the tool name.
+  const state = { stripped: false };
+  const tool = String(name ?? '');
+  const rendered = terminalOnly ? { kind: 'terminal', lines: [], truncated: true } : render({ tool, input, summary, overwrite }, state);
+  const toolName = cut(strip(tool, state), TOOL_CHARS);
+  const card = {
+    question_id: questionId,
+    card_digest: createHash('sha256').update(JSON.stringify(['device-card/1', name, digest(input)])).digest('hex'),
+    tool: toolName.text,
+    kind: rendered.kind,
+    lines: rendered.lines,
+    truncated: rendered.truncated || toolName.cut || state.stripped,
+  };
+  if (rendered.kind === 'write' && typeof overwrite === 'boolean') card.overwrite = overwrite;
+  const size = () => Buffer.byteLength(JSON.stringify(card));
+  while (size() > MAX_BYTES && card.lines.length > 1) { card.lines.pop(); card.truncated = true; }
+  if (size() > MAX_BYTES) { card.kind = 'terminal'; card.lines = []; card.truncated = true; delete card.overwrite; }
+  return card;
+}

package/src/remote-device.mjs

@@ -0,0 +1,92 @@
+import { t as translate, registerMessages } from './i18n/index.mjs';
+import { isCameraPath } from './qr-scan.mjs';
+
+registerMessages({
+  'Scanning the pairing QR needs an interactive terminal; type the code instead: /rc device CODE.': 'Escanear el QR de emparejamiento necesita una terminal interactiva; escribe el código: /rc device CODE.',
+  'Not paired; nothing was sent.': 'No se emparejó; no se envió nada.',
+  'Scanning the M5Stack pairing QR': 'Escaneando el QR de emparejamiento del M5Stack',
+  '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.': 'Acerca el M5Stack a 10-20 cm de la cámara, que el QR ocupe un tercio de la imagen. Hasta 30 s; Esc cancela. Las imágenes se quedan en esta máquina y se borran al instante.',
+  'Pair this M5Stack?': '¿Emparejar este M5Stack?',
+  'The camera read the code {code}. Pair only if it is the code on the M5Stack\'s screen.': 'La cámara leyó el código {code}. Empareja sólo si es el código de la pantalla del M5Stack.',
+  'Pair {code}': 'Emparejar {code}',
+  'Do not pair': 'No emparejar',
+});
+
+// Forward the House's permission rows to the Remote Control projection.
+// Only the current session's waits and answers cross; subagent sessions stay local.
+const FORWARDED = new Set(['house_waiting', 'house_answered']);
+
+export function forwardHouseRow(row, { sessionId, remoteHost } = {}) {
+  if (!row || !FORWARDED.has(row.type) || row.session_id !== sessionId) return;
+  remoteHost?.observe(row);
+}
+
+/** /rc device [CODE|forget|scan [/dev/videoN]] → {kind:'status'|'forget'|'pair'|'scan', code?, camera?} or null when
+ * it is not that command. A scan camera that is not /dev/videoN throws. */
+export function parseRcDevice(action) {
+  const match = /^device(?:\s+(\S.*))?$/i.exec(String(action ?? '').trim());
+  if (!match) return null;
+  const arg = (match[1] || '').trim();
+  if (!arg) return { kind: 'status' };
+  if (arg.toLowerCase() === 'forget') return { kind: 'forget' };
+  const scan = /^scan(?:\s+(.+))?$/i.exec(arg);
+  if (scan) {
+    if (!scan[1]) return { kind: 'scan' };
+    const camera = scan[1].trim();
+    if (!isCameraPath(camera)) throw Error(translate('The camera must be a /dev/videoN device.'));
+    return { kind: 'scan', camera };
+  }
+  return { kind: 'pair', code: arg };
+}
+
+/** Runs a parsed /rc device command against the host; `t` translates. */
+export async function runRcDevice(parsed, host, t, { record } = {}) {
+  if (!host || host.stopped || !host.deviceAvailable()) throw Error(t('Open /rc first, with a Comal backend that supports devices.'));
+  if (parsed.kind === 'status') {
+    const device = host.status().device;
+    return device ? t('Device: {label} ({id}){connected}.', { label: device.label, id: device.id, connected: device.connected_at ? t(', connected {time}', { time: String(device.connected_at) }) : '' }) : t('No device paired.');
+  }
+  if (parsed.kind === 'forget') { const wasArmed = host.permissionsArmed(); await host.forgetDevice(); if (wasArmed) await record?.(ARM_ROW(false, 0)); return t('Device removed; its permission answers are off.'); }
+  const paired = await host.pairDevice(parsed.code);
+  return t('Device paired: {label} ({id}).', { label: paired.label, id: paired.device_id });
+}
+
+/** /rc device scan: the camera reads the device's pairing QR (only now, at most 30 s), the person confirms the code,
+ * and it pairs through runRcDevice's own path. `scan({camera})` → {code, camera}; `confirm({code, camera})` → boolean,
+ * absent without an interactive terminal (then it is refused before the camera turns on). */
+export async function runRcDeviceScan(parsed, host, t, { scan, confirm, record } = {}) {
+  if (typeof confirm !== 'function') throw Error(t('Scanning the pairing QR needs an interactive terminal; type the code instead: /rc device CODE.'));
+  if (!host || host.stopped || !host.deviceAvailable()) throw Error(t('Open /rc first, with a Comal backend that supports devices.'));
+  const found = await scan({ camera: parsed.camera });
+  if (!await confirm({ code: found.code, camera: found.camera })) return t('Not paired; nothing was sent.');
+  return runRcDevice({ kind: 'pair', code: found.code }, host, t, { record });
+}
+
+/** The yes/no card for a scanned code: "Do not pair" comes first and is highlighted, so Enter never pairs. */
+export function deviceCodeChoice(code, t) {
+  return { title: t('Pair this M5Stack?'), description: t('The camera read the code {code}. Pair only if it is the code on the M5Stack\'s screen.', { code }), items: [{ id: 'cancel', label: t('Do not pair') }, { id: 'pair', label: t('Pair {code}', { code }) }], selected: 'cancel' };
+}
+
+const ARM_ROW = (armed, until) => ({ type: 'remote_control', action: 'permissions.arm', armed, until: armed ? new Date(until).toISOString() : null });
+const clock = ms => new Date(ms).toLocaleTimeString([], { hour: '2-digit', minute: '2-digit', hour12: false });
+
+/** /rc permissions [on [N m|min|h]|off] → {kind:'status'|'off'|'on', ms} or null when it is not that command. */
+export function parseRcPermissions(action) {
+  const match = /^permissions(?:\s+(?:(off)|(on)(?:\s+(\d+(?:[.,]\d+)?)\s*(m|min|h)?)?))?$/i.exec(String(action ?? '').trim());
+  if (!match) return null;
+  if (match[1]) return { kind: 'off' };
+  if (!match[2]) return { kind: 'status' };
+  if (!match[3]) return { kind: 'on', ms: null };
+  return { kind: 'on', ms: Math.round(Number(match[3].replace(',', '.')) * (String(match[4] || 'm').toLowerCase() === 'h' ? 3600e3 : 60e3)) };
+}
+
+/** Runs a parsed /rc permissions command; `record(row)` appends the book row. */
+export async function runRcPermissions(parsed, host, t, { record } = {}) {
+  if (!host || host.stopped || !host.deviceAvailable()) throw Error(t('Open /rc first, with a Comal backend that supports devices.'));
+  const status = () => host.permissionsArmed() ? t('Permission answers from the M5Stack: armed until {time}.', { time: clock(host.permissionUntil) }) : t('Permission answers from the M5Stack: off.');
+  if (parsed.kind === 'status') return status();
+  if (parsed.kind === 'off') { host.disarmPermissions(); await record?.(ARM_ROW(false, 0)); return status(); }
+  const until = host.armPermissions(parsed.ms ?? undefined);
+  await record?.(ARM_ROW(true, until));
+  return t('M5Stack permission answers are armed until {time}. Each card\'s command or path goes through comal.milpahq.com to the device and is not stored.', { time: clock(until) });
+}