@milpa/comal 0.0.0-stage → 0.1.1

package/src/remote-control.mjs

@@ -0,0 +1,172 @@
+import { createHash, randomUUID } from 'node:crypto';
+import { CloudClient } from './cloud-client.mjs';
+
+const digest = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+export const remoteInputDigest = (session, request, text) => digest([session,request,text]);
+const boundText = (text, max=30000) => Buffer.from(String(text || '')).subarray(0,max).toString('utf8').replace(/\uFFFD$/, '');
+
+/** Bounded projection; provider signatures, tool arguments/results and credentials stay local. */
+export function projectRemoteEvent(event, turnId) {
+  const base={turn_id:turnId || 'local',text:''};
+  if(event.type==='user')return {...base,type:'message.user',text:boundText(event.text)};
+  if(event.type==='assistant')return {...base,type:'message.assistant',text:boundText((event.message?.content || []).filter(b=>b.type==='text').map(b=>b.text).join(''))};
+  if(event.type==='result'&&event.turns===0&&typeof event.result==='string')return {...base,type:'message.control',text:boundText(event.result)};
+  if(event.type==='tool_use')return {...base,type:'tool.started',tool_name:boundText(event.name,128)};
+  if(event.type==='tool_result')return {...base,type:'tool.finished',tool_name:boundText(event.name,128),text:event.is_error?'failed':'returned'};
+  if(event.type==='response_discarded'||event.type==='model_retry')return {...base,type:'stream.discarded'};
+  return null;
+}
+
+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);
+
+export class RemoteHost {
+  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
+    Object.assign(this,{client,onInput,onStop,onNotice,socketFactory});this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
+  }
+  status(){return this.session?{enabled:!this.stopped,url:this.url,session:this.session.id,transport:this.transport,permissions:'local_terminal_only'}:{enabled:false};}
+  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) {
+    // A stopped pending open may still succeed upstream. Its original authority
+    // remains bound to that attempt, never to a replacement account or session.
+    if(!run?.session || !run.account || !run.enablingToken)return;
+    if(!run.revoking)run.revoking=Promise.resolve().then(()=>this.client.request(run.account.origin,'remote.sessions.close',{remote_session_id:run.session.id},run.enablingToken,AbortSignal.timeout(10000))).catch(()=>{});
+    await run.revoking;
+  }
+  async start(session) {
+    if(this.starting && this.current(this.starting,{starting:true}))return this.starting.promise;
+    if(!this.stopped)return this.status();
+    const run={controller:new AbortController()};this.lifecycle=run;this.starting=run;
+    run.promise=(async()=>{
+      try {
+        const account=await this.client.credentials();this.assertCurrent(run,{starting:true});
+        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 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']},{expectedAccount:run.account,signal:run.controller.signal});
+        run.session=opened.session;
+        // 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();}
+        this.account=run.account;this.enablingToken=run.enablingToken;this.session=opened.session;this.url=opened.url;this.stopped=false;
+        await this.authorize(run);this.assertCurrent(run);await this.pulse(run);this.assertCurrent(run);
+        this.transport='https-polling';this.connectSocket(run);
+        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.');
+        return this.status();
+      } catch(error) {
+        if(this.lifecycle===run)await this.stop();else await this.revoke(run);
+        throw error;
+      } finally {if(this.starting===run)this.starting=null;}
+    })();
+    return run.promise;
+  }
+  async authorize(run=this.lifecycle) {
+    this.assertCurrent(run);const session=this.session,account=this.account;
+    const ticket=await this.client.invoke('remote.stream.ticket',{remote_session_id:session.id,role:'host'},{expectedAccount:account,signal:lifetimeSignal(run)});
+    this.assertCurrent(run);
+    const access=await this.client.request(account.origin,'remote.stream.consume',{ticket:ticket.ticket,role:'host'},undefined,lifetimeSignal(run));
+    this.assertCurrent(run);this.access=access.access_token;this.expires=access.expires_at;
+  }
+  async call(operation,input={},run=this.lifecycle) {
+    this.assertCurrent(run);const account=this.account,session=this.session;
+    const current=await this.client.credentials();this.assertCurrent(run);
+    if(!current||current.origin!==account.origin||current.user_id!==account.user_id)throw Object.assign(Error('Comal account changed; Remote Control detached.'),{code:'REMOTE_REVOKED'});
+    if(this.expires<=Date.now()/1000+30)await this.authorize(run);
+    this.assertCurrent(run);
+    const result=await this.client.request(account.origin,operation,{remote_session_id:session.id,...input},this.access,lifetimeSignal(run));
+    this.assertCurrent(run);return result;
+  }
+  async connectSocket(run=this.lifecycle) {
+    if(!this.current(run)||this.socket||this.connecting)return;
+    const marker={run};this.connecting=marker;
+    try {
+      const account=this.account,session=this.session;
+      const ticket=await this.client.invoke('remote.stream.ticket',{remote_session_id:session.id,role:'host'},{expectedAccount:account,signal:lifetimeSignal(run)});
+      this.assertCurrent(run);
+      const url=new URL('/remote/host',account.origin);url.protocol=url.protocol==='https:'?'wss:':'ws:';
+      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('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. */}
+    finally{if(this.connecting===marker){this.connecting=null;if(this.current(run))this.nextSocketAt=Date.now()+10000;}}
+  }
+  observe(event) {
+    if(this.stopped)return;
+    const append=projected=>this.pending.push({event_id:randomUUID(),event:projected});
+    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;
+    }
+    if(event.type==='assistant'){
+      const thinking=(event.message?.content||[]).filter(block=>['thinking','openai_reasoning'].includes(block.type)).map(block=>block.thinking||block.text||'').join('\n');
+      if(thinking||this.thinkingActive)append({type:'thinking.finished',turn_id:this.turnId||'local',text:boundText(thinking||'Thinking complete.')});
+      this.thinkingActive=false;
+    }
+    if(['response_discarded','model_retry'].includes(event.type))this.thinkingActive=false;
+    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);}
+      }
+      return;
+    }
+    if(['assistant','response_discarded','model_retry'].includes(event.type)){clearTimeout(this.deltaTimer);this.deltaTimer=null;this.delta='';}
+    const projected=projectRemoteEvent(event,this.turnId);if(!projected)return;
+    if(this.pending.length>=512){this.onNotice('Remote projection paused: outbound buffer full. Local work continues.');this.stop().catch(()=>{});return;}
+    append(projected);this.flush().catch(()=>{});
+  }
+  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();}})();
+    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;}
+  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(){
+    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(()=>{});}
+    clearTimeout(this.deltaTimer);this.deltaTimer=null;this.delta='';this.thinkingActive=false;this.turnId=null;this.pulse().catch(()=>{});
+  }
+  async validate(item){
+    if(!item.remote)return true;
+    const run=this.lifecycle;
+    if(this.stopped||item.remote.session!==this.session.id)throw Error('Remote grant detached; queued input was not executed.');
+    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.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='';
+        // Only admission errors are rejection. A lost ACK must redeliver the same input.
+        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 {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);
+      }
+      if(!this.socket&&Date.now()>this.nextSocketAt)this.connectSocket(run);
+    })().catch(error=>{
+      if(!this.current(run))return;
+      if(['AUTH_INVALID','REMOTE_REVOKED','REMOTE_CLOSED','REMOTE_DENIED'].includes(error.code)){this.onNotice('Remote Control detached: '+error.message);this.stop().catch(()=>{});}
+      else if(Date.now()-(this.lastErrorAt||0)>30000){this.lastErrorAt=Date.now();this.onNotice('Remote relay reconnecting; local work continues.');}
+    });
+    this.processing=work;try{return await work;}finally{if(this.processing===work)this.processing=null;}
+  }
+  async stop(){
+    const run=this.lifecycle || {session:this.session,account:this.account,enablingToken:this.enablingToken};
+    this.lifecycle=null;this.starting=null;run.controller?.abort();
+    this.stopped=true;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/session-bus.mjs

@@ -0,0 +1,367 @@
+import net from 'node:net';
+import { peerMessagePurpose, peerMessageHeader } from './peer-message-context.mjs';
+import path from 'node:path';
+import os from 'node:os';
+import { constants } from 'node:fs';
+import { mkdir, lstat, open, readdir, rename, unlink, chmod } from 'node:fs/promises';
+import { createHash, randomBytes, randomUUID, timingSafeEqual } from 'node:crypto';
+
+const UUID = /^[a-f0-9]{8}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{4}-[a-f0-9]{12}$/i;
+const FRAME_LIMIT = 32768, MESSAGE_LIMIT = 16384, MAILBOX_LIMIT = 64, TTL = 24 * 60 * 60 * 1000;
+const uid = () => process.getuid?.();
+const fail = (code, message) => Object.assign(new Error(message), { code });
+const text = (value, limit = 200) => typeof value === 'string' ? value.slice(0, limit) : undefined;
+const strings = value => Array.isArray(value) ? [...new Set(value.filter(item => typeof item === 'string' && item.length <= 200))].slice(0, 128) : [];
+const alive = pid => { if (!Number.isSafeInteger(pid) || pid <= 0) return false; try { process.kill(pid, 0); return true; } catch (e) { return e.code === 'EPERM'; } };
+const hash = value => createHash('sha256').update(JSON.stringify(value)).digest('hex');
+function metadata(value = {}) {
+  return { name: text(value.name), provider: text(value.provider), model: text(value.model), profile: text(value.profile), capabilities: strings(value.capabilities), ...(value.effort?{effort:text(value.effort)}:{}), ...(value.authProvider?{authProvider:text(value.authProvider)}:{}) };
+}
+function authority(value = {}, cwd) {
+  // Captured from the sending host. Peer text is never authority or human intent.
+  const invalid = () => { throw fail('PEER_AUTHORITY_INVALID', 'La autoridad entre sesiones es inválida o excede sus límites.'); };
+  const normalize = input => {
+    if (!input || typeof input !== 'object' || Array.isArray(input)) return invalid();
+    const mode = input.mode === undefined ? 'plan' : input.mode;
+    if (!['default', 'acceptEdits', 'plan', 'auto'].includes(mode)) return invalid();
+    const list = key => {
+      const items = input[key] === undefined ? [] : input[key];
+      if (!Array.isArray(items) || items.length > 128 || items.some(item => typeof item !== 'string' || !item.length || item.length > 200)) return invalid();
+      return [...new Set(items)];
+    };
+    const workspace = input.cwd === undefined ? cwd : input.cwd;
+    if (typeof workspace !== 'string' || !workspace || workspace.length > 4096 || !path.isAbsolute(workspace)) return invalid();
+    return { mode, allowed: list('allowed'), denied: list('denied'), cwd: workspace };
+  };
+  const own = normalize(value), ceilings = value.ceilings === undefined ? [] : value.ceilings;
+  if (!Array.isArray(ceilings) || ceilings.length > 16) return invalid();
+  const normalized = ceilings.map(ceiling => {
+    if (!ceiling || Object.hasOwn(ceiling, 'ceilings')) return invalid();
+    return normalize(ceiling);
+  });
+  return { ...own, ceilings: normalized };
+}
+function publicPeer(record) {
+  return { id: record.id, ...metadata(record), cwd: record.cwd, state: record.state, inbound: record.inbound, pid: record.pid, started_at: record.started_at, updated_at: record.updated_at };
+}
+function mailbox(rows) {
+  const received = new Map(), delivered = new Set(), released = new Set(), subscriptions = new Map(), notified = new Set();
+  for (const row of rows) {
+    if (row.type === 'peer_message_received') received.set(row.peer.message_id, row.peer);
+    if (row.type === 'message' && row.source === 'peer_session') delivered.add(row.peer_message_id || row.peer?.message_id);
+    if (row.type === 'peer_message_released') released.add(row.message_id);
+    if (row.type === 'peer_idle_subscription') subscriptions.set(row.id, row);
+    if (row.type === 'peer_idle_notified') notified.add(row.id);
+  }
+  const live = [...received.values()].filter(item => !delivered.has(item.message_id) && item.expires_at > Date.now());
+  return { received, delivered, released, live, subscriptionsAll: [...subscriptions.values()], subscriptions: [...subscriptions.values()].filter(item => !notified.has(item.id) && item.expires_at > Date.now()) };
+}
+
+/** Local, same-user IPC. The private registry authenticates live instances; it is
+ * not a sandbox against other programs already running as this OS user. */
+export class SessionBus {
+  constructor({ store, getSessionId, getMetadata = () => ({}), getAuthority = () => ({}), getChain = () => ({}), directory = process.env.COMAL_PEER_DIR || path.join(os.homedir(), '.local/state/comal/peers'), inbound, onPending, onEvent, timeoutMs = 5000, ttlMs = TTL } = {}) {
+    if (!store || typeof getSessionId !== 'function') throw new TypeError('SessionBus requiere store y getSessionId.');
+    if (inbound !== undefined && !['accept', 'hold', 'refuse'].includes(inbound)) throw fail('PEER_INBOUND_INVALID', 'Usa accept, hold o refuse.');
+    Object.assign(this, { store, getSessionId, getMetadata, getAuthority, getChain, directory: path.resolve(directory), onPending, onEvent, timeoutMs, ttlMs: Math.min(TTL, Math.max(10, ttlMs)) });
+    this.state = 'idle'; this.inbound = inbound || 'accept'; this.inboundOverride = inbound; this.inboundConfigured = new Set(); this.sockets = new Set(); this._starting = undefined;
+  }
+  async _directory() {
+    await mkdir(this.directory, { recursive: true, mode: 0o700 });
+    const stat = await lstat(this.directory);
+    if (!stat.isDirectory() || stat.isSymbolicLink() || (uid() !== undefined && stat.uid !== uid()) || (stat.mode & 0o077)) throw fail('PEER_DIRECTORY_UNSAFE', 'El directorio de peers debe pertenecer al usuario y tener permisos 0700, sin symlinks.');
+  }
+  _paths(id) {
+    if (!UUID.test(id || '')) throw fail('PEER_ID_INVALID', 'Se requiere un UUID de sesión completo.');
+    return { registry: path.join(this.directory, `${id}.json`), socket: path.join(this.directory, `${id}.sock`) };
+  }
+  async _read(id, { socket = true } = {}) {
+    const paths = this._paths(id); let file;
+    try {
+      file = await open(paths.registry, constants.O_RDONLY | constants.O_NOFOLLOW);
+      const info = await file.stat();
+      if (!info.isFile() || info.size > FRAME_LIMIT || (uid() !== undefined && info.uid !== uid()) || (info.mode & 0o077)) throw fail('PEER_REGISTRY_UNSAFE', 'Registro de peer inseguro.');
+      const item = JSON.parse(await file.readFile('utf8'));
+      if (item.id !== id || item.uid !== uid() || item.version !== 1 || !/^[a-f0-9]{64}$/.test(item.token || '') || !alive(item.pid)) throw fail('PEER_OFFLINE', 'La instancia ya no está disponible.');
+      if (socket) {
+        const stat = await lstat(paths.socket);
+        if (!stat.isSocket() || stat.isSymbolicLink() || (uid() !== undefined && stat.uid !== uid()) || (stat.mode & 0o077)) throw fail('PEER_SOCKET_UNSAFE', 'Socket de peer inseguro.');
+      }
+      return item;
+    } catch (error) {
+      if (['ENOENT', 'ECONNREFUSED'].includes(error.code)) throw fail('PEER_OFFLINE', 'La instancia ya no está disponible.');
+      throw error;
+    } finally { await file?.close(); }
+  }
+  async _publish() {
+    const previous = this._publishing || Promise.resolve();
+    const next = previous.catch(() => {}).then(() => this._writeRegistry());
+    this._publishing = next;
+    try { return await next; } finally { if (this._publishing === next) this._publishing = undefined; }
+  }
+  async _writeRegistry() {
+    if (!this.server || this.closing) return;
+    const item = { version: 1, id: this.id, uid: uid(), pid: process.pid, token: this.token, instance: this.instance, cwd: this.store.cwd, ...metadata(this.getMetadata()), state: this.state, inbound: this.inbound, started_at: this.startedAt, updated_at: new Date().toISOString() };
+    const temporary = `${this.paths.registry}.${randomUUID()}.tmp`; let file;
+    try { file = await open(temporary, 'wx', 0o600); await file.writeFile(JSON.stringify(item)); await file.sync(); await file.close(); file = undefined; await rename(temporary, this.paths.registry); }
+    finally { await file?.close(); await unlink(temporary).catch(() => {}); }
+  }
+  async _own() {
+    const name = path.join(this.directory, `${this.id}.owner`), token = randomUUID();
+    for (let attempt = 0; attempt < 2; attempt++) {
+      try {
+        const file = await open(name, 'wx', 0o600);
+        this.owner = { file, name, token }; await file.writeFile(JSON.stringify({ pid: process.pid, token })); await file.sync(); return;
+      } catch (error) {
+        if (error.code !== 'EEXIST') throw error;
+        let file;
+        try {
+          file = await open(name, constants.O_RDONLY | constants.O_NOFOLLOW); const info = await file.stat();
+          if (!info.isFile() || info.size > 1024 || (uid() !== undefined && info.uid !== uid()) || (info.mode & 0o077)) throw fail('PEER_PATH_UNSAFE', 'Lock de peer inseguro.');
+          let owner; try { owner = JSON.parse(await file.readFile('utf8')); } catch { throw fail('PEER_SESSION_IN_USE', 'La sesión está iniciando en otra instancia.'); }
+          if (alive(owner.pid)) throw fail('PEER_SESSION_IN_USE', 'La sesión ya tiene una instancia de mensajería activa.');
+          const current = await lstat(name); if (current.ino !== info.ino || current.dev !== info.dev) continue;
+          await unlink(name);
+        } finally { await file?.close(); }
+      }
+    }
+    throw fail('PEER_SESSION_IN_USE', 'La sesión está iniciando en otra instancia.');
+  }
+  async start() {
+    if (this._starting) return this._starting;
+    this._starting = this._start();
+    try { return await this._starting; } finally { this._starting = undefined; }
+  }
+  async _start() {
+    const id = this.getSessionId();
+    if (this.server && this.id === id) return this;
+    if (this.server) await this.close();
+    await this._directory(); const paths = this._paths(id);
+    if (Buffer.byteLength(paths.socket) > 103) throw fail('PEER_SOCKET_PATH_LONG', 'COMAL_PEER_DIR produce una ruta de socket demasiado larga. Usa un directorio privado más corto.');
+    await this.store.load(id); // Never create or write another session's book.
+    Object.assign(this, { id, paths, token: randomBytes(32).toString('hex'), instance: randomUUID(), startedAt: new Date().toISOString(), closing: false });
+    try {
+    await this._own();
+    // Restore host controls before opening the socket: resumed refuse/hold has
+    // no temporary accept window. An explicit CLI override applies once per
+    // session in this instance; later setters remain authoritative on rebind.
+    await this.store.workTransaction(id, async () => {
+      const session = await this.store.load(id);
+      const previous = session.rows.findLast(row => row.type === 'peer_inbound' && row.source === 'session_host' && ['accept', 'hold', 'refuse'].includes(row.inbound));
+      const explicit = !this.inboundConfigured.has(id) && this.inboundOverride !== undefined;
+      this.inbound = explicit ? this.inboundOverride : previous?.inbound || 'accept';
+      if (explicit && previous?.inbound !== this.inbound) await this.store.append(id, { type: 'peer_inbound', source: 'session_host', inbound: this.inbound });
+      this.inboundConfigured.add(id);
+    });
+    try { await this._read(id); throw fail('PEER_SESSION_IN_USE', 'La sesión ya tiene una instancia de mensajería activa.'); }
+    catch (error) { if (error.code !== 'PEER_OFFLINE') throw error; }
+    // Stale sockets can only be removed after validating their type and owner.
+    for (const name of [paths.registry, paths.socket]) {
+      try { const stat = await lstat(name); if (stat.isSymbolicLink() || (uid() !== undefined && stat.uid !== uid()) || (name === paths.socket ? !stat.isSocket() : !stat.isFile())) throw fail('PEER_PATH_UNSAFE', 'No se reemplazará un path de peer inseguro.'); await unlink(name); }
+      catch (error) { if (error.code !== 'ENOENT') throw error; }
+    }
+    const server = net.createServer(socket => this._accept(socket)); this.server = server;
+    try {
+      await new Promise((resolve, reject) => { server.once('error', reject); server.listen(paths.socket, () => { server.removeListener('error', reject); resolve(); }); });
+      server.on('error', error => this._event({ type: 'error', code: error.code || 'PEER_SERVER_ERROR' }));
+      await chmod(paths.socket, 0o600); await this._publish();
+    } catch (error) { await this.close(); throw error; }
+    const pending = await this.pending(); if (pending.count) this._signal();
+    return this;
+    } catch (error) { await this.close(); throw error; }
+  }
+  async close() {
+    this.closing = true; await this._publishing?.catch(() => {});
+    const server = this.server; this.server = undefined;
+    for (const socket of this.sockets) socket.destroy(); this.sockets.clear();
+    if (server) await new Promise(resolve => server.close(resolve));
+    if (this.paths && this.token) {
+      try { const own = await this._read(this.id, { socket: false }); if (own.token === this.token) { await unlink(this.paths.registry).catch(() => {}); const stat = await lstat(this.paths.socket).catch(() => undefined); if (stat?.isSocket() && stat.uid === uid()) await unlink(this.paths.socket).catch(() => {}); } } catch {}
+    }
+    if (this.owner) {
+      const owner = this.owner; this.owner = undefined;
+      try { const current = await lstat(owner.name), original = await owner.file.stat(); if (!current.isSymbolicLink() && current.ino === original.ino && current.dev === original.dev) await unlink(owner.name); } catch {}
+      await owner.file.close();
+    }
+  }
+  _event(event) { try { this.onEvent?.(event); } catch {} }
+  _signal() { queueMicrotask(() => { try { Promise.resolve(this.onPending?.()).catch(() => {}); } catch {} }); }
+  async list({ capability, includeSelf = false } = {}) {
+    await this._directory(); if (this.server) await this._publish(); const result = [];
+    for (const name of await readdir(this.directory)) {
+      const id = name.endsWith('.json') ? name.slice(0, -5) : ''; if (!UUID.test(id)) continue;
+      if(!includeSelf && id===this.getSessionId())continue;
+      try { const peer = publicPeer(await this._read(id)); if (!capability || peer.capabilities.includes(capability)) result.push(peer); } catch {}
+    }
+    return result.sort((a, b) => a.id.localeCompare(b.id));
+  }
+  async _resolve(to) {
+    if (UUID.test(to || '')) return this._read(to);
+    if (typeof to !== 'string' || !to.length) throw fail('PEER_DESTINATION_REQUIRED', 'Especifica el UUID completo o nombre exacto de la sesión.');
+    const matches = (await this.list({includeSelf:true})).filter(peer => peer.name === to);
+    if (!matches.length) throw fail('PEER_NOT_FOUND', 'No hay una instancia activa con ese nombre.');
+    if (matches.length !== 1) throw fail('PEER_AMBIGUOUS', 'El nombre identifica varias sesiones; usa el UUID completo.');
+    return this._read(matches[0].id);
+  }
+  async send(input = {}, { signal } = {}) { return this._send(input, { signal }); }
+  async _send(input = {}, { signal, kind = 'message', chain, inheritedAuthority } = {}) {
+    await this.start(); if (signal?.aborted) throw fail('ABORT_ERR', 'Envío cancelado.');
+    const { to, message, request_id = randomUUID(), reply_to, notify_when_idle = false, required_capabilities = [] } = input;
+    if ((typeof message !== 'string' || !message.trim()) && !notify_when_idle) throw fail('PEER_MESSAGE_REQUIRED', 'Se requiere un mensaje o notify_when_idle.');
+    if (message !== undefined && (typeof message !== 'string' || Buffer.byteLength(message) > MESSAGE_LIMIT)) throw fail('PEER_MESSAGE_TOO_LARGE', 'El mensaje admite hasta 16 KiB de UTF-8.');
+    if (typeof request_id !== 'string' || !request_id || request_id.length > 128 || (reply_to !== undefined && (typeof reply_to !== 'string' || reply_to.length > 128))) throw fail('PEER_CORRELATION_INVALID', 'Correlación de mensaje inválida.');
+    if (!Array.isArray(required_capabilities) || required_capabilities.some(value => typeof value !== 'string' || value.length > 200) || required_capabilities.length > 128) throw fail('PEER_CAPABILITIES_INVALID', 'Capacidades requeridas inválidas.');
+    const target = await this._resolve(to);
+    if (target.id === this.id) throw Object.assign(fail('PEER_SELF_SEND', `No enviado: el destino ${target.name || target.id} (${target.id}) es ESTA misma sesión. No es un rechazo por busy: las otras sesiones ocupadas sí aceptan mensajes. Usa ListAgents para elegir otra instancia; si no aparece ninguna, abre otra terminal Comal o usa AnalyzeMedia aquí con provider.features.`), { details:{reason:'same_session',current_session_id:this.id,target_session_id:target.id,delivery:'not_sent',retryable:false} });
+    const missing = required_capabilities.filter(value => !target.capabilities.includes(value));
+    if (missing.length) throw fail('PEER_CAPABILITY_MISSING', `La sesión no ofrece: ${missing.join(', ')}.`);
+    await this._publish();
+    const message_id = randomUUID(), active = chain || this.getChain() || {};
+    const hop = active.root_id ? Number(active.hop || 0) + 1 : 0;
+    if (!Number.isSafeInteger(hop) || hop < 0 || hop > 8) throw fail('PEER_HOP_LIMIT', 'La cadena entre sesiones alcanzó ocho saltos.');
+    let capturedAuthority = authority(this.getAuthority(), this.store.cwd);
+    if (inheritedAuthority) {
+      const inherited = authority(inheritedAuthority, this.store.cwd), { ceilings, ...ceiling } = inherited;
+      const combined = [...capturedAuthority.ceilings, ceiling, ...ceilings];
+      capturedAuthority = authority({ ...capturedAuthority, ceilings: [...new Map(combined.map(item => [hash(item), item])).values()] }, this.store.cwd);
+    }
+    const envelope = { message_id, request_id, reply_to, content: message || '', notify_when_idle: Boolean(notify_when_idle), required_capabilities, authority: capturedAuthority, chain: { root_id: text(active.root_id, 128) || message_id, hop }, kind, expires_at: Date.now() + this.ttlMs };
+    const wire = { version: 1, from: this.id, instance: this.instance, token: this.token, to: target.id, target_instance: target.instance, envelope };
+    if (Buffer.byteLength(JSON.stringify(wire)) + 1 > FRAME_LIMIT) throw fail('PEER_FRAME_TOO_LARGE', 'El sobre de mensaje excede 32 KiB.');
+    await this.store.append(this.id, { type: 'peer_message_sending', peer: { ...envelope, from: { id: this.id, ...metadata(this.getMetadata()) }, to: target.id } });
+    let result;
+    try { result = await this._request(target, wire, signal); }
+    catch (error) {
+      error.request_id = request_id; error.message_id = message_id;
+      await this.store.append(this.id, { type: 'peer_message_send_failed', request_id, message_id, to: target.id, code: error.code, delivery: ['PEER_TIMEOUT', 'PEER_NO_ACK', 'ABORT_ERR'].includes(error.code) ? 'unknown' : 'unconfirmed' });
+      throw error;
+    }
+    await this.store.append(this.id, { type: 'peer_message_sent', peer: { ...envelope, message_id: result.message_id, from: { id: this.id, ...metadata(this.getMetadata()) }, to: target.id }, result });
+    this._event({ type: 'sent', ...result }); return result;
+  }
+  _request(target, wire, signal) {
+    return new Promise((resolve, reject) => {
+      const socket = net.createConnection(this._paths(target.id).socket); let buffer = Buffer.alloc(0), settled = false;
+      const finish = (error, result) => { if (settled) return; settled = true; clearTimeout(timer); signal?.removeEventListener('abort', cancel); socket.destroy(); error ? reject(error) : resolve(result); };
+      const cancel = () => finish(fail('ABORT_ERR', 'Envío cancelado; consulta el recibo antes de reintentar con otro request_id.'));
+      const timer = setTimeout(() => finish(fail('PEER_TIMEOUT', 'No llegó confirmación; reintenta con el mismo request_id para evitar duplicados.')), this.timeoutMs); timer.unref?.();
+      signal?.addEventListener('abort', cancel, { once: true }); if (signal?.aborted) return cancel();
+      socket.once('connect', () => socket.write(JSON.stringify(wire) + '\n'));
+      socket.on('data', chunk => {
+        buffer = Buffer.concat([buffer, chunk]); if (buffer.length > FRAME_LIMIT) return finish(fail('PEER_FRAME_TOO_LARGE', 'Respuesta IPC demasiado grande.'));
+        const end = buffer.indexOf(10); if (end < 0) return;
+        try { const result = JSON.parse(buffer.subarray(0, end)); if (!result.ok) return finish(fail(result.error?.code || 'PEER_REJECTED', result.error?.message || 'Mensaje rechazado.')); finish(undefined, result.result); }
+        catch { finish(fail('PEER_PROTOCOL_INVALID', 'Respuesta IPC inválida.')); }
+      });
+      socket.once('error', error => finish(fail(error.code === 'ECONNREFUSED' ? 'PEER_OFFLINE' : 'PEER_TRANSPORT_ERROR', 'No se pudo contactar a la instancia.')));
+      socket.once('close', () => finish(fail('PEER_NO_ACK', 'La instancia cerró sin confirmar la entrega; reutiliza request_id.')));
+    });
+  }
+  _accept(socket) {
+    this.sockets.add(socket); socket.once('close', () => this.sockets.delete(socket)); socket.on('error', () => {});
+    socket.setTimeout(this.timeoutMs, () => socket.destroy()); let buffer = Buffer.alloc(0), handled = false;
+    const respond = payload => { if (!socket.destroyed) socket.end(JSON.stringify(payload) + '\n'); };
+    socket.on('data', chunk => {
+      if (handled) return; buffer = Buffer.concat([buffer, chunk]);
+      if (buffer.length > FRAME_LIMIT) { handled = true; respond({ ok: false, error: { code: 'PEER_FRAME_TOO_LARGE', message: 'Frame IPC excede 32 KiB.' } }); return; }
+      const end = buffer.indexOf(10); if (end < 0) return; handled = true;
+      Promise.resolve().then(() => { const wire = JSON.parse(buffer.subarray(0, end)); if (buffer.subarray(end + 1).some(byte => byte !== 10 && byte !== 13)) throw fail('PEER_PROTOCOL_INVALID', 'Solo se admite un frame por conexión.'); return this._receive(wire); })
+        .then(result => respond({ ok: true, result }), error => respond({ ok: false, error: { code: error.code || 'PEER_PROTOCOL_INVALID', message: error.code ? error.message : 'Mensaje IPC inválido.' } }));
+    });
+  }
+  async _receive(wire) {
+    if (wire?.version !== 1 || wire.to !== this.id || wire.target_instance !== this.instance || !UUID.test(wire.from || '')) throw fail('PEER_PROTOCOL_INVALID', 'Destino o protocolo inválido.');
+    const sender = await this._read(wire.from);
+    if (sender.instance !== wire.instance || typeof wire.token !== 'string' || !/^[a-f0-9]{64}$/.test(wire.token) || !timingSafeEqual(Buffer.from(sender.token), Buffer.from(wire.token))) throw fail('PEER_IDENTITY_INVALID', 'La identidad emisora no corresponde a una instancia activa.');
+    const envelope = wire.envelope;
+    if (!envelope || !UUID.test(envelope.message_id || '') || typeof envelope.request_id !== 'string' || !envelope.request_id || envelope.request_id.length > 128 || typeof envelope.content !== 'string' || Buffer.byteLength(envelope.content) > MESSAGE_LIMIT || !Number.isFinite(envelope.expires_at) || envelope.expires_at <= Date.now() || envelope.expires_at > Date.now() + TTL + 1000 || !Number.isSafeInteger(envelope.chain?.hop) || envelope.chain.hop < 0 || envelope.chain.hop > 8 || typeof envelope.chain?.root_id !== 'string' || envelope.chain.root_id.length > 128 || (envelope.reply_to !== undefined && (typeof envelope.reply_to !== 'string' || envelope.reply_to.length > 128))) throw fail('PEER_ENVELOPE_INVALID', 'Sobre de mensaje inválido o expirado.');
+    if ((!envelope.content.trim() && !envelope.notify_when_idle) || !Array.isArray(envelope.required_capabilities) || envelope.required_capabilities.some(value => typeof value !== 'string' || value.length > 200) || envelope.required_capabilities.length > 128) throw fail('PEER_ENVELOPE_INVALID', 'Contenido o capacidades inválidas.');
+    const own = metadata(this.getMetadata()), missing = envelope.required_capabilities.filter(value => !own.capabilities.includes(value));
+    if (missing.length) throw fail('PEER_CAPABILITY_MISSING', `La sesión ya no ofrece: ${missing.join(', ')}.`);
+    // Registry identity is canonical; no caller-supplied name/provider/from is used.
+    const from = { id: sender.id, ...metadata(sender) };
+    const fingerprint = hash({ content: envelope.content, reply_to: envelope.reply_to, notify_when_idle: !!envelope.notify_when_idle, required_capabilities: envelope.required_capabilities });
+    let shouldSignal = false;
+    const result = await this.store.workTransaction(this.id, async () => {
+      const session = await this.store.load(this.id), state = mailbox(session.rows);
+      const duplicate = [...state.received.values()].find(item => item.from.id === sender.id && item.request_id === envelope.request_id);
+      const oldSubscription = state.subscriptionsAll.find(item => item.from.id === sender.id && item.request_id === envelope.request_id);
+      const previous = duplicate || oldSubscription;
+      if (previous) { if (previous.fingerprint !== fingerprint) throw fail('PEER_IDEMPOTENCY_CONFLICT', 'request_id ya identifica otro mensaje.'); return { id: previous.message_id || previous.id, message_id: previous.message_id || previous.id, request_id: envelope.request_id, from: sender.id, to: this.id, status: 'duplicate', expires_at: previous.expires_at }; }
+      if (this.inbound === 'refuse') throw fail('PEER_INBOUND_REFUSED', 'La sesión no acepta mensajes entrantes.');
+      if (state.live.length + state.subscriptions.length >= MAILBOX_LIMIT) throw fail('PEER_MAILBOX_FULL', 'El buzón alcanzó 64 mensajes pendientes.');
+      const peer = { message_id: envelope.message_id, request_id: envelope.request_id, reply_to: envelope.reply_to, required_capabilities:[...envelope.required_capabilities], from, to: this.id, content: envelope.content, authority: authority(envelope.authority, sender.cwd), chain: { root_id: envelope.chain.root_id, hop: envelope.chain.hop }, expires_at: envelope.expires_at, fingerprint, kind: envelope.kind === 'idle_notification' ? 'idle_notification' : 'message', held: this.inbound === 'hold', received_at: new Date().toISOString() };
+      if (envelope.content.trim()) { await this.store.append(this.id, { type: 'peer_message_received', peer }); shouldSignal = !peer.held; }
+      if (envelope.notify_when_idle) await this.store.append(this.id, { type: 'peer_idle_subscription', id: peer.message_id, message_id: peer.message_id, request_id: peer.request_id, from, fingerprint, expires_at: peer.expires_at, authority: peer.authority, chain: peer.chain });
+      return { id: peer.message_id, message_id: peer.message_id, request_id: peer.request_id, from: sender.id, to: this.id, status: peer.held ? 'held' : 'accepted', expires_at: peer.expires_at };
+    });
+    if (shouldSignal) this._signal();
+    this._event({ type: 'received', ...result });
+    if (envelope.notify_when_idle && this.state === 'idle' && this.inbound === 'accept') queueMicrotask(() => this._notifyIdle().catch(() => {}));
+    return result;
+  }
+  async pending() {
+    const id = this.getSessionId(); this._paths(id); const state = mailbox((await this.store.load(id)).rows);
+    const held = state.live.filter(item => item.held && !state.released.has(item.message_id)).length;
+    return { count: this.inbound==='accept' ? state.live.length - held : 0, held, total: state.live.length };
+  }
+  async drain() {
+    const id = this.getSessionId(); this._paths(id);
+    if (this.inbound !== 'accept') return [];
+    return this.store.workTransaction(id, async () => {
+      if(this.inbound!=='accept')return [];
+      const session = await this.store.load(id), state = mailbox(session.rows), result = [];
+      for (const peer of state.live) {
+        if (peer.held && !state.released.has(peer.message_id)) continue;
+        const purpose = peerMessagePurpose(peer), header = peerMessageHeader(peer);
+        const message = { role: 'user', content: [{ type: 'text', text: header + peer.content }] };
+        const row = await this.store.append(id, { type: 'message', source: 'peer_session', peer_message_id: peer.message_id, peer_purpose: purpose, peer, message });
+        result.push({ ...peer, purpose, id: peer.message_id, message, row });
+      }
+      return result;
+    });
+  }
+  async releaseHeld(id = 'all') {
+    const sessionId = this.getSessionId(); this._paths(sessionId);
+    const count = await this.store.workTransaction(sessionId, async () => {
+      const state = mailbox((await this.store.load(sessionId)).rows); let released = 0;
+      for (const peer of state.live) if (peer.held && !state.released.has(peer.message_id) && (id === 'all' || id === peer.message_id)) { await this.store.append(sessionId, { type: 'peer_message_released', message_id: peer.message_id }); released++; }
+      return released;
+    });
+    if (count && this.inbound === 'accept') this._signal(); return { released: count };
+  }
+  async setInbound(value) {
+    if (!['accept', 'hold', 'refuse'].includes(value)) throw fail('PEER_INBOUND_INVALID', 'Usa accept, hold o refuse.');
+    const id = this.getSessionId(); this._paths(id);
+    const previous = this._inboundSetting || Promise.resolve();
+    const next = previous.catch(() => {}).then(async () => {
+      await this.store.workTransaction(id, async () => {
+        await this.store.append(id, { type: 'peer_inbound', source: 'session_host', inbound: value });
+        if (this.getSessionId() === id) { this.inbound = value; this.inboundConfigured.add(id); }
+      });
+      if (this.server && this.id === id) await this._publish();
+      if (this.getSessionId() === id && value === 'accept' && (await this.pending()).count) this._signal();
+      return { inbound: value };
+    });
+    this._inboundSetting = next;
+    try { return await next; } finally { if (this._inboundSetting === next) this._inboundSetting = undefined; }
+  }
+  async setState(value) {
+    if (!['busy', 'idle'].includes(value)) throw fail('PEER_STATE_INVALID', 'Usa busy o idle.');
+    this.state = value; if (this.server) await this._publish();
+    if (value === 'idle' && this.server && this.inbound === 'accept') await this._notifyIdle();
+    return { state: this.state };
+  }
+  async _notifyIdle() {
+    if (this.notifying || !this.server) return; this.notifying = true;
+    try {
+      const state = mailbox((await this.store.load(this.id)).rows);
+      for (const subscription of state.subscriptions) {
+        try {
+          const result = await this._send({ to: subscription.from.id, message: `La sesión ${metadata(this.getMetadata()).name || this.id} está idle. Esta notificación confirma disponibilidad, no ejecución del encargo.`, request_id: `idle:${subscription.id}`, reply_to: subscription.id }, { kind: 'idle_notification', chain: subscription.chain, inheritedAuthority: subscription.authority });
+          await this.store.append(this.id, { type: 'peer_idle_notified', id: subscription.id, message_id: result.message_id });
+        } catch (error) { this._event({ type: 'idle_notification_failed', id: subscription.id, code: error.code }); }
+      }
+    } finally { this.notifying = false; }
+  }
+}

package/src/session-provider-settings.mjs

@@ -0,0 +1,39 @@
+import { selectProfile } from './provider-profiles.mjs';
+import { providerSettings } from './openai-provider.mjs';
+import { authProviderDefaults } from './provider-auth.mjs';
+
+// Only references to credentials enter session configuration. Tokens are
+// resolved separately and never copied into these settings or the ledger.
+export function sessionProviderSettings({ current, profiles, options: v = {}, env = process.env, maxTokens } = {}) {
+  const saved = current?.provider_connection;
+  const explicitEndpoint = Boolean(v.provider || v['base-url'] || v['auth-provider']);
+  const requested = v.profile || env.COMAL_PROFILE || (!explicitEndpoint ? current?.provider_profile || profiles.defaultProfile : null);
+  const selected = requested ? selectProfile(profiles, requested) : null;
+  const modelOverride=v.model || env.COMAL_MODEL || env.OPENAI_MODEL;
+  const effort = (same, fallback) => v.effort || env.COMAL_EFFORT || (same && (!modelOverride || modelOverride === current?.model) ? saved?.effort : null) || fallback || 'auto';
+  const common = { maxTokens, ...(v.thinking ? { thinking: v.thinking } : {}), ...(v.vision ? { vision: v.vision } : {}), ...(v['image-tokens'] ? { imageTokens: Number(v['image-tokens']) } : {}) };
+  const access=v['auth-provider']?authProviderDefaults(v['auth-provider']):null;
+  // An explicit login selects its transport, not just a credential to attach
+  // to the old profile's URL/model. Keep profile settings only for the same
+  // canonical auth provider; foreign profiles must not reach its adapter.
+  if(access && selected?.authProvider!==access.authProvider)return{
+    ...common,...access,model:v.model || (saved?.authProvider===access.authProvider?current.model:access.model),
+    baseURL:v['base-url'] || access.baseURL,effort:effort(saved?.authProvider===access.authProvider),
+    ...(selected?{overriddenProfile:selected.name}:{})
+  };
+  const sameProfile=selected && current?.provider_profile===selected.name;
+  const restored=sameProfile?{...(saved?.thinking?{thinking:saved.thinking}:{}),...(saved?.vision?{vision:saved.vision}:{}),...(saved?.imageTokens?{imageTokens:saved.imageTokens}:{})}:{};
+  if (selected) return { ...restored,...common, profile: selected, namedProfile: true, provider: selected.provider,
+    authProvider: access?.authProvider || selected.authProvider, model: v.model || (current?.provider_profile === selected.name ? current.model : selected.model),
+    baseURL: v['base-url'] || selected.baseURL, effort: effort(current?.provider_profile === selected.name, selected.effort) };
+  const hasEnvEndpoint = ['COMAL_PROVIDER', 'HARNESS_PROVIDER', 'COMAL_BASE_URL', 'HARNESS_BASE_URL', 'OPENAI_BASE_URL'].some(key => env[key]);
+  if (!explicitEndpoint && saved && !hasEnvEndpoint) {
+    const schema=saved.toolSchema?{toolSchema:structuredClone(saved.toolSchema)}:{};
+    const model = v.model || env.COMAL_MODEL || current.model;
+    if (saved.authProvider) return { ...common, ...schema, ...authProviderDefaults(saved.authProvider), model, baseURL: saved.baseURL, effort: effort(true), ...(saved.thinking && !v.thinking ? { thinking: saved.thinking } : {}),vision:v.vision || saved.vision || 'auto',imageTokens:Number(v['image-tokens'] || saved.imageTokens || 4096),capabilitiesConfigured:saved.capabilitiesConfigured || {} };
+    if (saved.provider === 'gemini') return { ...common, ...schema, provider: saved.provider, effort: effort(true), profile: { name: 'session', provider: saved.provider, baseURL: saved.baseURL, model, apiKeyEnv: saved.apiKeyEnv, capabilities: saved.capabilities, capabilitiesConfigured: saved.capabilitiesConfigured || saved.capabilities } };
+    return { ...schema, ...providerSettings({ provider: saved.provider, baseURL: saved.baseURL, model, thinking: v.thinking || saved.thinking, vision: v.vision || saved.vision, imageTokens: v['image-tokens'] || saved.imageTokens, effort: effort(true) }, env, current), maxTokens };
+  }
+  if (v.provider === 'gemini') return { ...common, provider: 'gemini', effort: effort(false), profile: { name: 'session', provider: 'gemini', model: v.model || env.COMAL_MODEL || env.GEMINI_MODEL || 'gemini-2.5-flash', ...(v['base-url'] ? { baseURL: v['base-url'] } : {}), capabilities: { vision: true, video: true, web_search: true } } };
+  return { ...providerSettings({ provider: v.provider, baseURL: v['base-url'], model: v.model, thinking: v.thinking, effort: effort(false), vision: v.vision, imageTokens: v['image-tokens'] }, env, current), maxTokens };
+}

package/src/session-read-cache.mjs

@@ -0,0 +1,20 @@
+// Cache computation, never authority or file state. Every lookup is preceded by
+// a new complete file read and requires exact bytes, not stat/mtime metadata.
+export class SessionJournalCache {
+  #entry;
+  constructor({maxBytes=8*1024*1024}={}) {
+    if(!Number.isSafeInteger(maxBytes)||maxBytes<0||maxBytes>64*1024*1024)throw new Error('journalCacheBytes debe ser un entero entre 0 y 64 MiB.');
+    this.maxBytes=maxBytes;this.stats={hits:0,misses:0,oversized:0,invalid:0};
+  }
+  get(id,bytes) {
+    if(this.#entry?.id===id && this.#entry.bytes.equals(bytes)){this.stats.hits++;return structuredClone(this.#entry.audit);}
+    this.stats.misses++;return null;
+  }
+  set(id,bytes,audit) {
+    if(!this.maxBytes || bytes.length>this.maxBytes){this.#entry=undefined;this.stats.oversized++;return;}
+    if(!audit.consistent){this.#entry=undefined;this.stats.invalid++;return;}
+    // No mutable buffer/audit handed to a caller can poison a future hit.
+    this.#entry={id,bytes:Buffer.from(bytes),audit:structuredClone(audit)};
+  }
+  status(){return {...this.stats,max_bytes:this.maxBytes,retained_bytes:this.#entry?.bytes.length ||0,entries:this.#entry?1:0,proof:'complete_file_bytes_equal'};}
+}