@milpa/comal 0.2.3 → 0.2.5

package/src/remote-control.mjs

@@ -1,5 +1,9 @@
-import { createHash, randomUUID } from 'node:crypto';
+import { createHash, randomBytes, 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';
+import { failurePhrase, speechFrames, SpeechPacer, SPEECH_MAX_BYTES, SPEECH_MAX_BUFFERED, SPEECH_QUIET_AFTER_DELTA_MS, SPEECH_WINDOW_CEILING, SPEECH_WINDOW_MS, turnPhrase } from './remote-speech.mjs';
 
 const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
 export const remoteInputDigest = (session, request, text) => digest([session,request,text]);
@@ -17,7 +21,8 @@ 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
@@ -42,6 +47,9 @@ export const RELAY_SESSION_EVENTS = 2000, RELAY_SESSION_BYTES = 16 << 20, RELAY_
 // 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
@@ -49,15 +57,158 @@ const RELAY_REFUSALS = new Set(['INPUT_SCHEMA','REMOTE_FEATURE','REMOTE_RELAY','
 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;
+// What a phrase may be about (the contract's speech.schema.properties.about.enum).
+const SPEECH_ABOUT = new Set(['permission','failure','turn']);
+
+// 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,relay=null,onRelay=null,now=Date.now,socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
-    Object.assign(this,{client,onInput,onStop,onNotice,getWorkspace,relay,onRelay,now,socketFactory});this.answersUntil=0;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,speech=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,speech,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;
+    // Granito's voice: frames sent over the host socket in the last SPEECH_WINDOW_MS, the last delta, the render in course.
+    this.sentFrames=[];this.lastDeltaAt=-Infinity;this.speechRender=null;
+    this.speechPacer=new SpeechPacer({send:frame=>this.speechAvailable()&&this.cardFrame(frame),room:()=>this.speechRoom(),now:this.now});
+  }
+  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},speech:this.speechStatus()}:{})}:{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}));}catch{return false;}
+    this.noteFrame(frame.kind);return true;
+  }
+  /** Counts a frame sent over the host socket, for the relay's window; a delta also restarts the quiet speech waits for. */
+  noteFrame(kind){
+    const now=this.now();
+    this.sentFrames=this.sentFrames.filter(at=>now-at<SPEECH_WINDOW_MS);this.sentFrames.push(now);
+    if(kind==='delta')this.lastDeltaAt=now;
+  }
+  /** May a speech chunk go now without pushing the host past the relay's budget? */
+  speechRoom(){
+    if(this.transport!=='websocket'||this.socket?.readyState!==1)return false;
+    const now=this.now();
+    if(now-this.lastDeltaAt<SPEECH_QUIET_AFTER_DELTA_MS)return false;
+    this.sentFrames=this.sentFrames.filter(at=>now-at<SPEECH_WINDOW_MS);
+    if(this.sentFrames.length>=SPEECH_WINDOW_CEILING)return false;
+    return (this.socket.bufferedAmount??0)<SPEECH_MAX_BUFFERED;
   }
-  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}}:{})}:{enabled:false};}
+  /** Speech goes only where it cannot hurt: speech_v1 granted, a relay that said it accepts speech (an older one closes
+   *  the host socket on an unknown frame), the WebSocket transport, a paired device and a Piper voice. */
+  speechAvailable(){const run=this.lifecycle;return Boolean(this.current(run)&&run.speech&&run.speechRelay&&this.transport==='websocket'&&this.deviceInfo&&this.speech?.ready===true);}
+  speechStatus(){const run=this.lifecycle;if(this.speech?.ready!==true)return 'no_piper';if(!(run?.speech&&run?.speechRelay))return 'not_offered';return 'ready';}
+  /** Speaks a phrase on the paired device. Synchronous and fire-and-forget: rendering and sending never hold a turn or
+   *  the permission flow, and every failure is swallowed. A newer phrase replaces the one rendering or playing. */
+  sendSpeech(text,about){
+    try{
+      if(typeof text!=='string'||!text.trim()||!SPEECH_ABOUT.has(about)||!this.speechAvailable())return false;
+      this.speechRender?.abort();
+      const controller=new AbortController(),run=this.lifecycle;this.speechRender=controller;
+      Promise.resolve(this.speech.render(text,{signal:controller.signal})).then(pcm8=>{
+        if(this.speechRender!==controller||controller.signal.aborted||!this.current(run))return;
+        this.speechRender=null;
+        if(!Buffer.isBuffer(pcm8)||!pcm8.length||!this.speechAvailable())return;
+        this.speechPacer.play({frames:speechFrames({id:randomBytes(8).toString('hex'),about,pcm8:pcm8.subarray(0,SPEECH_MAX_BYTES)})});
+      }).catch(()=>{});
+      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();
+  }
+  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();}
@@ -87,12 +238,14 @@ 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 features=['commands_v1','thinking_v1',...(this.getWorkspace?['workspace_v1']:[]),...(this.relay?['relay_v1']:[]),...(this.relay&&this.onRelay?['relay_answers_v1']:[])];
+        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','speech_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 attempts=[features,features.filter(item=>item!=='relay_answers_v1'),features.filter(item=>!item.startsWith('relay_'))].filter((list,index,all)=>index===0||list.length<all[index-1].length);
+        // speech_v1 goes first (a backend before Granito's voice), then the device features with it.
+        const noDevice=features.filter(item=>item!=='device_v1'&&item!=='stats_v1'&&item!=='speech_v1');
+        const attempts=[features,features.filter(item=>item!=='speech_v1'),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;}
@@ -101,7 +254,7 @@ export class RemoteHost {
         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.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.speech=run.device&&granted('speech_v1');run.speechRelay=false;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();}
@@ -109,6 +262,7 @@ 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)){
@@ -151,9 +305,9 @@ 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);run.speechRelay=Array.isArray(m.accepts)&&m.accepts.includes('speech');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';}});
+      ws.addEventListener('close',()=>{clearTimeout(timeout);if(this.current(run)&&this.socket===ws){this.socket=null;this.transport='https-polling';run.speechRelay=false;this.speechPacer.cancel();}});
     }catch{/* HTTPS is already active. A later tick retries WSS. */}
     finally{if(this.connecting===marker){this.connecting=null;if(this.current(run))this.nextSocketAt=Date.now()+10000;}}
   }
@@ -165,6 +319,38 @@ 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;
@@ -215,8 +401,11 @@ export class RemoteHost {
   }
   observe(event) {
     if(this.stopped)return;
+    if(event.type==='tool_result'&&event.is_error===true&&!String(event.content??'').includes('HOUSE_REFUSED'))try{this.sendSpeech(failurePhrase(event.name),'failure');}catch{}
+    if(event.type==='result'&&event.turns>0&&typeof event.result==='string')try{const phrase=turnPhrase(event.result);if(phrase)this.sendSpeech(phrase,'turn');}catch{}
     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;
     }
@@ -229,7 +418,7 @@ export class RemoteHost {
     if(event.type==='text_delta'){
       if(this.transport==='websocket'&&this.socket?.readyState===1&&this.turnId){
         this.delta=boundText((this.delta || '')+event.text,32000);
-        if(!this.deltaTimer){const run=this.lifecycle;this.deltaTimer=setTimeout(()=>{if(!this.current(run))return;this.deltaTimer=null;const text=this.delta;this.delta='';if(this.socket?.readyState===1)for(let offset=0;offset<text.length;offset+=1800)this.socket.send(JSON.stringify({protocol:'comal.remote.v1',kind:'delta',turn_id:this.turnId,text:text.slice(offset,offset+1800)}));},120);}
+        if(!this.deltaTimer){const run=this.lifecycle;this.deltaTimer=setTimeout(()=>{if(!this.current(run))return;this.deltaTimer=null;const text=this.delta;this.delta='';if(this.socket?.readyState===1)for(let offset=0;offset<text.length;offset+=1800){this.socket.send(JSON.stringify({protocol:'comal.remote.v1',kind:'delta',turn_id:this.turnId,text:text.slice(offset,offset+1800)}));this.noteFrame('delta');}},120);}
       }
       return;
     }
@@ -247,16 +436,21 @@ export class RemoteHost {
     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)||!String(item.event?.type).startsWith('relay.')||!RELAY_REFUSALS.has(error.code))throw error;this.onNotice('Remote /relay event refused by the backend ('+error.code+'); /relay and /swarm in this terminal are unaffected.');}
+      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;const armed=run.answers&&this.answersUntil>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);});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){
@@ -266,6 +460,7 @@ 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);
@@ -274,11 +469,17 @@ export class RemoteHost {
         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.
         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,...(outcome?{outcome}:{})},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=>{
@@ -298,10 +499,19 @@ export class RemoteHost {
       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);clearTimeout(run.boardTimer);if(run.relaySink)this.relay?.detach(run.relaySink);
-    this.stopped=true;this.answersUntil=0;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();this.speechRender?.abort();this.speechRender=null;this.speechPacer.cancel();this.sentFrames=[];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,97 @@
+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',
+  'voice: ready': 'voz: lista',
+  'voice: no Piper (COMAL_PIPER_VOICE)': 'voz: sin Piper (COMAL_PIPER_VOICE)',
+  'voice: not available on this connection': 'voz: no disponible en esta conexión',
+});
+
+// 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;
+    const line = 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.');
+    const voice = { ready: t('voice: ready'), no_piper: t('voice: no Piper (COMAL_PIPER_VOICE)') }[host.speechStatus()] ?? t('voice: not available on this connection');
+    return line + '\n' + voice;
+  }
+  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) });
+}