@milpa/comal 0.1.7 → 0.2.0

package/src/secret-login.mjs

@@ -0,0 +1,68 @@
+import { t, registerMessages } from './i18n/index.mjs';
+import { authProviderDefinition, acceptsSecretLogin } from './provider-auth.mjs';
+
+registerMessages({
+  'API key for {provider}': 'Llave de API de {provider}',
+  'Subscription key for {provider}': 'Llave de suscripción de {provider}',
+  'Hidden field: nothing you type is shown, saved in history or sent to the model. Comal stores it only in its private credential store ({directory}). Esc cancels.': 'Campo oculto: lo que escribas no se muestra, no entra al historial ni se envía al modelo. Comal la guarda sólo en su almacén privado de credenciales ({directory}). Esc cancela.',
+  'Type or paste the key.': 'Escribe o pega la llave.',
+  'Login cancelled. No key was stored.': 'Login cancelado. No se guardó ninguna llave.',
+  'Use /login PROVIDER [--key | --api-key-env VARIABLE]. Never paste keys into the composer.': 'Usa /login PROVEEDOR [--key | --api-key-env VARIABLE]. Nunca pegues llaves en el compositor.',
+  '{provider} only supports browser sign-in.': '{provider} sólo admite inicio de sesión en el navegador.',
+  'The hidden key field needs the interactive terminal; use --api-key-env VARIABLE here.': 'El campo oculto de la llave necesita la terminal interactiva; aquí usa --api-key-env VARIABLE.',
+});
+
+const VARIABLE = /^[A-Za-z_][A-Za-z0-9_]*$/;
+
+/** Argumentos de /login después del proveedor. Sólo nombres, nunca valores. */
+export function parseLoginArguments(parts) {
+  if (!parts.length) return {};
+  if (parts.length === 1 && parts[0] === '--key') return { hidden: true };
+  if (parts.length === 2 && parts[0] === '--api-key-env' && VARIABLE.test(parts[1])) return { apiKeyEnv: parts[1] };
+  throw new Error(t('Use /login PROVIDER [--key | --api-key-env VARIABLE]. Never paste keys into the composer.'));
+}
+
+/**
+ * Quita las cabeceras de credencial que el adaptador ya puso con su copia de la
+ * llave. credentialFetch añade la vigente; si no, fetch une ambas en
+ * "Bearer X, Bearer X" y servidores estrictos (Ollama Cloud) responden 401.
+ */
+export function withoutCredentialHeaders(headers) {
+  const entries = headers instanceof Headers ? [...headers.entries()] : Array.isArray(headers) ? headers : Object.entries(headers || {});
+  return Object.fromEntries(entries.filter(([name]) => !['authorization', 'x-api-key'].includes(String(name).toLowerCase())));
+}
+
+const cancelled = () => Object.assign(new Error(t('Login cancelled. No key was stored.')), { name: 'AbortError', code: 'ABORT_ERR' });
+
+/** Pide la llave en el campo oculto de la TUI. Devuelve null si el humano cancela. */
+export async function promptSecret({ ui, provider, directory, signal }) {
+  const p = authProviderDefinition(provider);
+  const value = await ui.setupInput({
+    title: t(p.subscription ? 'Subscription key for {provider}' : 'API key for {provider}', { provider: p.label }),
+    description: t('Hidden field: nothing you type is shown, saved in history or sent to the model. Comal stores it only in its private credential store ({directory}). Esc cancels.', { directory: directory || '~/.config/comal/auth' }),
+    secret: true, signal,
+    // El campo oculto nunca muestra el mensaje del validador; sólo un aviso genérico.
+    validate: text => text.trim() ? true : t('Type or paste the key.'),
+  });
+  return typeof value === 'string' ? value.trim() : null;
+}
+
+/**
+ * Login de proveedor con tres entradas posibles para la llave:
+ * --api-key-env VAR (variable de entorno), la variable por omisión del proveedor
+ * si existe, o el campo oculto de la TUI (siempre con --key). La llave sólo pasa
+ * de la TUI al almacén de credenciales: no vuelve en el resultado, no entra en
+ * entradas de operaciones del libro y nunca se copia a process.env.
+ */
+export async function loginProvider({ authManager, ui, provider, apiKeyEnv, hidden = false, signal, onEvent, env = authManager.env || process.env }) {
+  const p = authProviderDefinition(provider);
+  if (hidden && !acceptsSecretLogin(p.id)) throw new Error(t('{provider} only supports browser sign-in.', { provider: p.label }));
+  const secretCapable = acceptsSecretLogin(p.id) && p.method !== 'device_code';
+  const useEnvironment = apiKeyEnv || !hidden && (!secretCapable || !ui || (p.apiKeyEnv && env[p.apiKeyEnv]));
+  if (useEnvironment) return authManager.login(p.id, { apiKeyEnv, signal, onEvent });
+  if (!ui) throw new Error(t('The hidden key field needs the interactive terminal; use --api-key-env VARIABLE here.'));
+  let secret = await promptSecret({ ui, provider: p.id, directory: authManager.directory, signal });
+  if (!secret) throw cancelled();
+  try { return await authManager.login(p.id, { secret, signal }); }
+  finally { secret = null; }
+}

package/src/session-bus.mjs

@@ -1,5 +1,6 @@
 import net from 'node:net';
 import { peerMessagePurpose, peerMessageHeader } from './peer-message-context.mjs';
+import { admitNotice, noticeCounts, noticeMailbox, noticeMessage, NOTICE_LIMITS } from './plugin-notices.mjs';
 import path from 'node:path';
 import os from 'node:os';
 import { constants } from 'node:fs';
@@ -23,7 +24,7 @@ function authority(value = {}, cwd) {
   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();
+    if (!['default', 'acceptEdits', 'plan', 'auto', 'bypassPermissions'].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();
@@ -311,18 +312,49 @@ export class SessionBus {
     return result;
   }
   async pending() {
-    if (!this.availability.available) return { count: 0, held: 0, total: 0, ...this.availability };
+    // Los avisos de plugins no dependen del transporte entre sesiones: viven en el libro.
+    let notices = null;
+    const sessionId = this.getSessionId();
+    if (UUID.test(sessionId || '')) { const counts = noticeCounts((await this.store.load(sessionId)).rows, this.inbound); if (counts.total) notices = counts; }
+    const extra = notices ? { notices } : {}, urgent = notices?.urgent || 0;
+    if (!this.availability.available) return { count: urgent, held: notices?.held || 0, total: notices?.total || 0, ...extra, ...this.availability };
     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 };
+    return { count: (this.inbound==='accept' ? state.live.length - held : 0) + urgent, held: held + (notices?.held || 0), total: state.live.length + (notices?.total || 0), ...extra };
+  }
+  /** Encola un aviso de plugin ya normalizado (plugin-notices.mjs). Nunca es intención humana. */
+  async notify(normalized) {
+    const id = this.getSessionId();
+    if (!UUID.test(id || '')) return { status: 'no_session' };
+    const result = await this.store.workTransaction(id, async () => {
+      const admitted = admitNotice((await this.store.load(id)).rows, normalized, { inbound: this.inbound });
+      if (admitted.notice) await this.store.append(id, { type: 'plugin_notice_received', source: 'plugin_host', notice: admitted.notice, grants_permission: false });
+      return admitted;
+    });
+    if (result.status === 'accepted' && result.notice.urgent) this._signal();
+    this._event({ type: 'plugin_notice_admitted', plugin: normalized.plugin, ref: normalized.ref, status: result.status });
+    return { status: result.status, ...(result.notice_id ? { notice_id: result.notice_id } : {}) };
+  }
+  async _drainNotices(id) {
+    if (this.inbound !== 'accept') return [];
+    const state = noticeMailbox((await this.store.load(id)).rows), result = [];
+    // Urgentes primero; el resto espera al siguiente turno si excede el tope por entrega.
+    for (const notice of [...state.ready].sort((a, b) => Number(b.urgent) - Number(a.urgent)).slice(0, NOTICE_LIMITS.perDrain)) {
+      const message = noticeMessage(notice);
+      const row = await this.store.append(id, { type: 'message', source: 'plugin_notice', notice_id: notice.notice_id, notice, message });
+      result.push({ kind: 'plugin_notice', id: notice.notice_id, notice, message, row });
+    }
+    return result;
   }
   async drain() {
-    if (!this.availability.available) return [];
+    const sessionId = this.getSessionId();
+    const notices = UUID.test(sessionId || '') && this.inbound === 'accept' ? await this.store.workTransaction(sessionId, () => this._drainNotices(sessionId)) : [];
+    if (!this.availability.available) return notices;
     const id = this.getSessionId(); this._paths(id);
-    if (this.inbound !== 'accept') return [];
+    if (this.inbound !== 'accept') return notices;
     return this.store.workTransaction(id, async () => {
-      if(this.inbound!=='accept')return [];
-      const session = await this.store.load(id), state = mailbox(session.rows), result = [];
+      if(this.inbound!=='accept')return notices;
+      const session = await this.store.load(id), state = mailbox(session.rows), result = [...notices];
       for (const peer of state.live) {
         if (peer.held && !state.released.has(peer.message_id)) continue;
         const purpose = peerMessagePurpose(peer), header = peerMessageHeader(peer);
@@ -339,6 +371,8 @@ export class SessionBus {
     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++; }
+      const notices = noticeMailbox((await this.store.load(sessionId)).rows);
+      for (const notice of notices.live) if (notice.held && !notices.released.has(notice.notice_id) && (id === 'all' || id === notice.notice_id)) { await this.store.append(sessionId, { type: 'plugin_notice_released', notice_id: notice.notice_id }); released++; }
       return released;
     });
     if (count && this.inbound === 'accept') this._signal(); return { released: count };

package/src/session-projections-candidate.mjs

@@ -0,0 +1,119 @@
+// Prospective host-only reader. Not imported by SessionStore, CLI or a workflow.
+// A projection is data, not execution/audit/permission authority.
+import {readFile} from 'node:fs/promises';
+import {performance} from 'node:perf_hooks';
+
+const jsonBytes=value=>Buffer.byteLength(JSON.stringify(value));
+const validHash=value=>typeof value==='string'&&/^[a-f0-9]{64}$/.test(value);
+const defaultState=()=>({stage:'new',status:'ready'});
+// Preserve the original SessionStore fold operations and their JS exceptions.
+// Only its private accumulated fold is reused; callers never receive it. A
+// string messages.slice() can succeed, then messages.push() can fail, or reset
+// can restore an array. No new schema is imposed on these records.
+function foldCompatibility(rows,header,prior){
+  let messages=prior?(Array.isArray(prior.messages)?prior.messages.slice():prior.messages):[];
+  const historyMessages=prior?prior.historyMessages.slice():[];
+  let metadata=prior?prior.metadata:header,goal=prior?.goal,queue=prior?.queue,draft=prior?prior.draft:'',draftAttachments=prior?prior.draftAttachments:[],compaction=prior?.compaction,projection=prior?.projection;
+  for (const row of rows) {
+    if (row.type === 'reset') { messages = []; historyMessages.length = 0; compaction = undefined; projection = undefined; }
+    if (row.type === 'compaction') { messages = row.messages.slice(); compaction = row; }
+    if (row.type === 'context_projection') { messages = row.messages.slice(); projection = row; compaction = row; }
+    if (row.type === 'context_rebase') { messages = row.messages.slice(); projection = undefined; compaction = undefined; }
+    if (row.type === 'message') { messages.push(row.message); historyMessages.push(row.message); }
+    if (row.type === 'model') metadata = { ...metadata, model: row.model };
+    if (row.type === 'provider') metadata = { ...metadata, provider: row.provider, model: row.model, ...(row.profile !== undefined ? {provider_profile:row.profile} : {}),...(row.connection ? {provider_connection:row.connection} : {}) };
+    if (row.type === 'goal') goal = row.goal;
+    if (row.type === 'queue') queue = row.snapshot;
+    if (row.type === 'draft') { draft = row.text; draftAttachments = row.attachments || []; }
+    if (row.type === 'name') metadata = { ...metadata, name: row.name };
+    if (row.type === 'parent') metadata = { ...metadata, parent_session_id: row.parent_session_id, subagent_type: row.subagent_type, name: row.description };
+  }
+  return{messages,historyMessages,metadata,goal,queue,draft,draftAttachments,compaction,projection};
+}
+export function createSessionProjectionReader({store,JournalCache,auditJournal,assertClassifierChannels,maxCachedBytes=16*1024*1024,maxIndexBytes=1024*1024,maxTasks=8,maxReceipts=64}={}) {
+  if(!store||typeof store.load!=='function'||typeof store.file!=='function'||!(store.writers instanceof Map)||typeof store.cwd!=='string'||typeof JournalCache!=='function'||typeof auditJournal!=='function'||typeof assertClassifierChannels!=='function')throw new TypeError('Explicit original host store and journal implementations required.');
+  for(const [name,value,limit] of [['maxCachedBytes',maxCachedBytes,64*1024*1024],['maxIndexBytes',maxIndexBytes,8*1024*1024],['maxTasks',maxTasks,64],['maxReceipts',maxReceipts,256]])if(!Number.isSafeInteger(value)||value<0||value>limit)throw new TypeError('Invalid bounded projection option: '+name);
+  let entry=null,journal=new JournalCache({maxBytes:maxCachedBytes}),pending=Promise.resolve();
+  const stats={reads:0,identical:0,extensions:0,full:0,fallbacks:0,failures:0,retained_buffer_bytes:0,retained_index_json_bytes:0,max_cached_buffer_bytes:2*maxCachedBytes,max_index_json_bytes:maxIndexBytes,max_tasks:maxTasks,max_receipts:maxReceipts,last:null};
+  // Native trim() admits blank lines at EOF, but appending after them makes
+  // them internal parser errors. Such bytes can cache equality, never a prefix.
+  const reusablePrefix=(bytes,records)=>{if(bytes.at(-1)!==10)return false;let n=0;for(let p=bytes.indexOf(10);p>=0;p=bytes.indexOf(10,p+1))n++;return n===records;};
+  const clear=()=>{entry=null;journal=new JournalCache({maxBytes:maxCachedBytes});stats.retained_buffer_bytes=0;stats.retained_index_json_bytes=0;};
+  const index=()=>({header:null,accepted:null,tasks:new Map(),receipts:new Map()});
+  const put=(map,key,value,cap)=>{if(map.has(key))map.delete(key);map.set(key,value);while(map.size>cap)map.delete(map.keys().next().value);};
+  function fold(view,rows,offset=0){
+    for(let i=0;i<rows.length;i++){
+      const row=rows[i],n=offset+i;if(!row)continue;
+      if(n===0)view.header=row;
+      if(row.type==='chrome_task_accepted'&&row.source==='workflow_host')view.accepted=row;
+      if(row.type==='chrome_task_checkpoint')put(view.tasks,row.task_digest,{row,n},maxTasks);
+      if(['house_proposal','house_started','house_receipt'].includes(row.type)&&typeof row.invocation_id==='string'){
+        const tuple=view.receipts.get(row.invocation_id)||{};
+        // A bounded recent index. Missing/evicted ancestors never become proof;
+        // explicit receipt queries fall back to the original complete reader.
+        tuple[row.type]={row,n};put(view.receipts,row.invocation_id,tuple,maxReceipts);
+      }
+    }
+    return view;
+  }
+  const size=(view,compatibility)=>jsonBytes({header:view.header,accepted:view.accepted,tasks:[...view.tasks],receipts:[...view.receipts],compatibility});
+  function identity(header,id){if(header?.type!=='session'||header.id!==id||header.cwd!==store.cwd)throw new Error('La sesión pertenece a otro directorio o es inválida.');}
+  async function fallback(id,query){
+    stats.fallbacks++;clear();const book=await store.load(id);
+    const view={header:book.rows[0],accepted:book.rows.findLast(row=>row.type==='chrome_task_accepted'&&row.source==='workflow_host'),tasks:new Map(),receipts:new Map()};
+    if(query.kind==='page'){const n=book.rows.findLastIndex(row=>row.type==='chrome_task_checkpoint'&&row.task_digest===query.taskDigest);if(n>=0)view.tasks.set(query.taskDigest,{row:book.rows[n],n});}
+    else for(let i=0;i<book.rows.length;i++){const row=book.rows[i];if(row.invocation_id===query.invocationId&&['house_proposal','house_started','house_receipt'].includes(row.type)){const tuple=view.receipts.get(query.invocationId)||{};tuple[row.type]={row,n:i};view.receipts.set(query.invocationId,tuple);}}
+    return result(view,book.journalAudit,query);
+  }
+  function result(view,audit,query){
+    const base={session:{id:view.header.id,cwd:view.header.cwd},journalAudit:audit};
+    if(query.kind==='page')return structuredClone({...base,accepted:view.accepted??null,checkpoint:view.tasks.get(query.taskDigest)?.row??null,state:view.tasks.get(query.taskDigest)?.row.state||defaultState()});
+    const tuple=view.receipts.get(query.invocationId)||{};
+    return structuredClone({...base,proposal:tuple.house_proposal?.row??null,started:tuple.house_started?.row??null,receipt:tuple.house_receipt?.row??null,indices:{proposal:tuple.house_proposal?.n??null,started:tuple.house_started?.n??null,receipt:tuple.house_receipt?.n??null}});
+  }
+  async function read(id,query){
+    const began=performance.now();stats.reads++;
+    try{
+      while(store.writers.has(id))await store.writers.get(id).catch(()=>{});
+      const bytes=await readFile(store.file(id));
+      if(!maxCachedBytes||!maxIndexBytes||bytes.length>maxCachedBytes)return await fallback(id,query);
+      let audit=journal.get(id,bytes),view,records,mode,compatibility;
+      if(entry?.id===id&&bytes.equals(entry.bytes)&&audit){view=entry.view;records=entry.records;compatibility=entry.compatibility;mode='identical';stats.identical++;}
+      else if(entry?.id===id&&entry.audit.verified&&entry.prefixSafe&&bytes.length>entry.bytes.length&&bytes.subarray(0,entry.bytes.length).equals(entry.bytes)&&bytes.subarray(entry.bytes.length).toString('utf8').trimEnd()){
+        // Do not trimStart: a blank line inserted after the verified prefix is
+        // invalid in the original full parser and must remain invalid here.
+        const suffix=bytes.subarray(entry.bytes.length).toString('utf8').trimEnd().split('\n').map(row=>JSON.parse(row));
+        const absolute=new Array(entry.records).concat(suffix);identity(entry.view.header,id);assertClassifierChannels(absolute);
+        compatibility=foldCompatibility(suffix,entry.view.header,entry.compatibility);
+        audit=journal.extend(id,bytes,absolute);
+        if(!audit)return await fallback(id,query);
+        view=fold({header:entry.view.header,accepted:entry.view.accepted,tasks:new Map(entry.view.tasks),receipts:new Map([...entry.view.receipts].map(([k,v])=>[k,{...v}]))},suffix,entry.records);
+        records=absolute.length;mode='verified-prefix';stats.extensions++;
+      } else {
+        const rows=bytes.toString('utf8').trim().split('\n').map(row=>JSON.parse(row));identity(rows[0],id);assertClassifierChannels(rows);
+        compatibility=foldCompatibility(rows.slice(1),rows[0]);
+        audit=audit||auditJournal(rows);view=fold(index(),rows);records=rows.length;mode='full';stats.full++;
+      }
+      identity(view.header,id);
+      const indexBytes=size(view,compatibility);
+      if(indexBytes>maxIndexBytes)return await fallback(id,query);
+      if(mode!=='identical')journal.set(id,bytes,audit);
+      if(audit.consistent){if(mode!=='identical')entry={id,bytes:Buffer.from(bytes),view,records,compatibility,prefixSafe:reusablePrefix(bytes,records),audit:structuredClone(audit)};stats.retained_buffer_bytes=2*bytes.length;stats.retained_index_json_bytes=indexBytes;}
+      else clear();
+      // A missing recent receipt or task may have been evicted; never credit
+      // absence from a bounded index as absence from the original book.
+      if(query.kind==='receipt'&&!view.receipts.get(query.invocationId)?.house_proposal||query.kind==='page'&&!view.tasks.has(query.taskDigest)&&view.tasks.size>=maxTasks)return await fallback(id,query);
+      stats.last={mode,bytes:bytes.length,records,index_json_bytes:indexBytes,elapsed_ms:performance.now()-began};
+      return result(view,audit,query);
+    }catch(error){stats.failures++;clear();throw error;}
+    finally{stats.last={...stats.last,elapsed_ms:performance.now()-began};}
+  }
+  // Serialize private cache updates; no journal writer, actor or permission is
+  // substituted, and original writer-drain semantics remain per read.
+  const serial=(id,query)=>{const next=pending.then(()=>read(id,query));pending=next.catch(()=>{});return next;};
+  return Object.freeze({
+    readPageState(id,taskDigest){if(!validHash(taskDigest))return Promise.reject(new TypeError('Exact accepted task digest required.'));return serial(id,{kind:'page',taskDigest});},
+    readReceipt(id,invocationId){if(typeof invocationId!=='string'||!/^[a-f0-9-]{36}$/.test(invocationId))return Promise.reject(new TypeError('Exact original invocation id required.'));return serial(id,{kind:'receipt',invocationId});},
+    status(){return structuredClone(stats);},clear(){return pending.then(()=>clear());},
+  });
+}

package/src/session-projections.mjs

@@ -0,0 +1,119 @@
+// Narrow host-only reader. A normal page workflow uses it only after explicit host opt-in.
+// A projection is data, not execution/audit/permission authority.
+import {readFile} from 'node:fs/promises';
+import {performance} from 'node:perf_hooks';
+
+const jsonBytes=value=>Buffer.byteLength(JSON.stringify(value));
+const validHash=value=>typeof value==='string'&&/^[a-f0-9]{64}$/.test(value);
+const defaultState=()=>({stage:'new',status:'ready'});
+// Preserve the original SessionStore fold operations and their JS exceptions.
+// Only its private accumulated fold is reused; callers never receive it. A
+// string messages.slice() can succeed, then messages.push() can fail, or reset
+// can restore an array. No new schema is imposed on these records.
+function foldCompatibility(rows,header,prior){
+  let messages=prior?(Array.isArray(prior.messages)?prior.messages.slice():prior.messages):[];
+  const historyMessages=prior?prior.historyMessages.slice():[];
+  let metadata=prior?prior.metadata:header,goal=prior?.goal,queue=prior?.queue,draft=prior?prior.draft:'',draftAttachments=prior?prior.draftAttachments:[],compaction=prior?.compaction,projection=prior?.projection;
+  for (const row of rows) {
+    if (row.type === 'reset') { messages = []; historyMessages.length = 0; compaction = undefined; projection = undefined; }
+    if (row.type === 'compaction') { messages = row.messages.slice(); compaction = row; }
+    if (row.type === 'context_projection') { messages = row.messages.slice(); projection = row; compaction = row; }
+    if (row.type === 'context_rebase') { messages = row.messages.slice(); projection = undefined; compaction = undefined; }
+    if (row.type === 'message') { messages.push(row.message); historyMessages.push(row.message); }
+    if (row.type === 'model') metadata = { ...metadata, model: row.model };
+    if (row.type === 'provider') metadata = { ...metadata, provider: row.provider, model: row.model, ...(row.profile !== undefined ? {provider_profile:row.profile} : {}),...(row.connection ? {provider_connection:row.connection} : {}) };
+    if (row.type === 'goal') goal = row.goal;
+    if (row.type === 'queue') queue = row.snapshot;
+    if (row.type === 'draft') { draft = row.text; draftAttachments = row.attachments || []; }
+    if (row.type === 'name') metadata = { ...metadata, name: row.name };
+    if (row.type === 'parent') metadata = { ...metadata, parent_session_id: row.parent_session_id, subagent_type: row.subagent_type, name: row.description };
+  }
+  return{messages,historyMessages,metadata,goal,queue,draft,draftAttachments,compaction,projection};
+}
+export function createSessionProjectionReader({store,JournalCache,auditJournal,assertClassifierChannels,maxCachedBytes=16*1024*1024,maxIndexBytes=1024*1024,maxTasks=8,maxReceipts=64}={}) {
+  if(!store||typeof store.load!=='function'||typeof store.file!=='function'||!(store.writers instanceof Map)||typeof store.cwd!=='string'||typeof JournalCache!=='function'||typeof auditJournal!=='function'||typeof assertClassifierChannels!=='function')throw new TypeError('Explicit original host store and journal implementations required.');
+  for(const [name,value,limit] of [['maxCachedBytes',maxCachedBytes,64*1024*1024],['maxIndexBytes',maxIndexBytes,8*1024*1024],['maxTasks',maxTasks,64],['maxReceipts',maxReceipts,256]])if(!Number.isSafeInteger(value)||value<0||value>limit)throw new TypeError('Invalid bounded projection option: '+name);
+  let entry=null,journal=new JournalCache({maxBytes:maxCachedBytes}),pending=Promise.resolve();
+  const stats={reads:0,identical:0,extensions:0,full:0,fallbacks:0,failures:0,retained_buffer_bytes:0,retained_index_json_bytes:0,max_cached_buffer_bytes:2*maxCachedBytes,max_index_json_bytes:maxIndexBytes,max_tasks:maxTasks,max_receipts:maxReceipts,last:null};
+  // Native trim() admits blank lines at EOF, but appending after them makes
+  // them internal parser errors. Such bytes can cache equality, never a prefix.
+  const reusablePrefix=(bytes,records)=>{if(bytes.at(-1)!==10)return false;let n=0;for(let p=bytes.indexOf(10);p>=0;p=bytes.indexOf(10,p+1))n++;return n===records;};
+  const clear=()=>{entry=null;journal=new JournalCache({maxBytes:maxCachedBytes});stats.retained_buffer_bytes=0;stats.retained_index_json_bytes=0;};
+  const index=()=>({header:null,accepted:null,tasks:new Map(),receipts:new Map()});
+  const put=(map,key,value,cap)=>{if(map.has(key))map.delete(key);map.set(key,value);while(map.size>cap)map.delete(map.keys().next().value);};
+  function fold(view,rows,offset=0){
+    for(let i=0;i<rows.length;i++){
+      const row=rows[i],n=offset+i;if(!row)continue;
+      if(n===0)view.header=row;
+      if(row.type==='chrome_task_accepted'&&row.source==='workflow_host')view.accepted=row;
+      if(row.type==='chrome_task_checkpoint')put(view.tasks,row.task_digest,{row,n},maxTasks);
+      if(['house_proposal','house_started','house_receipt'].includes(row.type)&&typeof row.invocation_id==='string'){
+        const tuple=view.receipts.get(row.invocation_id)||{};
+        // A bounded recent index. Missing/evicted ancestors never become proof;
+        // explicit receipt queries fall back to the original complete reader.
+        tuple[row.type]={row,n};put(view.receipts,row.invocation_id,tuple,maxReceipts);
+      }
+    }
+    return view;
+  }
+  const size=(view,compatibility)=>jsonBytes({header:view.header,accepted:view.accepted,tasks:[...view.tasks],receipts:[...view.receipts],compatibility});
+  function identity(header,id){if(header?.type!=='session'||header.id!==id||header.cwd!==store.cwd)throw new Error('La sesión pertenece a otro directorio o es inválida.');}
+  async function fallback(id,query){
+    stats.fallbacks++;clear();const book=await store.load(id);
+    const view={header:book.rows[0],accepted:book.rows.findLast(row=>row.type==='chrome_task_accepted'&&row.source==='workflow_host'),tasks:new Map(),receipts:new Map()};
+    if(query.kind==='page'){const n=book.rows.findLastIndex(row=>row.type==='chrome_task_checkpoint'&&row.task_digest===query.taskDigest);if(n>=0)view.tasks.set(query.taskDigest,{row:book.rows[n],n});}
+    else for(let i=0;i<book.rows.length;i++){const row=book.rows[i];if(row.invocation_id===query.invocationId&&['house_proposal','house_started','house_receipt'].includes(row.type)){const tuple=view.receipts.get(query.invocationId)||{};tuple[row.type]={row,n:i};view.receipts.set(query.invocationId,tuple);}}
+    return result(view,book.journalAudit,query);
+  }
+  function result(view,audit,query){
+    const base={session:{id:view.header.id,cwd:view.header.cwd},journalAudit:audit};
+    if(query.kind==='page')return structuredClone({...base,accepted:view.accepted??null,checkpoint:view.tasks.get(query.taskDigest)?.row??null,state:view.tasks.get(query.taskDigest)?.row.state||defaultState()});
+    const tuple=view.receipts.get(query.invocationId)||{};
+    return structuredClone({...base,proposal:tuple.house_proposal?.row??null,started:tuple.house_started?.row??null,receipt:tuple.house_receipt?.row??null,indices:{proposal:tuple.house_proposal?.n??null,started:tuple.house_started?.n??null,receipt:tuple.house_receipt?.n??null}});
+  }
+  async function read(id,query){
+    const began=performance.now();stats.reads++;
+    try{
+      while(store.writers.has(id))await store.writers.get(id).catch(()=>{});
+      const bytes=await readFile(store.file(id));
+      if(!maxCachedBytes||!maxIndexBytes||bytes.length>maxCachedBytes)return await fallback(id,query);
+      let audit=journal.get(id,bytes),view,records,mode,compatibility;
+      if(entry?.id===id&&bytes.equals(entry.bytes)&&audit){view=entry.view;records=entry.records;compatibility=entry.compatibility;mode='identical';stats.identical++;}
+      else if(entry?.id===id&&entry.audit.verified&&entry.prefixSafe&&bytes.length>entry.bytes.length&&bytes.subarray(0,entry.bytes.length).equals(entry.bytes)&&bytes.subarray(entry.bytes.length).toString('utf8').trimEnd()){
+        // Do not trimStart: a blank line inserted after the verified prefix is
+        // invalid in the original full parser and must remain invalid here.
+        const suffix=bytes.subarray(entry.bytes.length).toString('utf8').trimEnd().split('\n').map(row=>JSON.parse(row));
+        const absolute=new Array(entry.records).concat(suffix);identity(entry.view.header,id);assertClassifierChannels(absolute);
+        compatibility=foldCompatibility(suffix,entry.view.header,entry.compatibility);
+        audit=journal.extend(id,bytes,absolute);
+        if(!audit)return await fallback(id,query);
+        view=fold({header:entry.view.header,accepted:entry.view.accepted,tasks:new Map(entry.view.tasks),receipts:new Map([...entry.view.receipts].map(([k,v])=>[k,{...v}]))},suffix,entry.records);
+        records=absolute.length;mode='verified-prefix';stats.extensions++;
+      } else {
+        const rows=bytes.toString('utf8').trim().split('\n').map(row=>JSON.parse(row));identity(rows[0],id);assertClassifierChannels(rows);
+        compatibility=foldCompatibility(rows.slice(1),rows[0]);
+        audit=audit||auditJournal(rows);view=fold(index(),rows);records=rows.length;mode='full';stats.full++;
+      }
+      identity(view.header,id);
+      const indexBytes=size(view,compatibility);
+      if(indexBytes>maxIndexBytes)return await fallback(id,query);
+      if(mode!=='identical')journal.set(id,bytes,audit);
+      if(audit.consistent){if(mode!=='identical')entry={id,bytes:Buffer.from(bytes),view,records,compatibility,prefixSafe:reusablePrefix(bytes,records),audit:structuredClone(audit)};stats.retained_buffer_bytes=2*bytes.length;stats.retained_index_json_bytes=indexBytes;}
+      else clear();
+      // A missing recent receipt or task may have been evicted; never credit
+      // absence from a bounded index as absence from the original book.
+      if(query.kind==='receipt'&&!view.receipts.get(query.invocationId)?.house_proposal||query.kind==='page'&&!view.tasks.has(query.taskDigest)&&view.tasks.size>=maxTasks)return await fallback(id,query);
+      stats.last={mode,bytes:bytes.length,records,index_json_bytes:indexBytes,elapsed_ms:performance.now()-began};
+      return result(view,audit,query);
+    }catch(error){stats.failures++;clear();throw error;}
+    finally{stats.last={...stats.last,elapsed_ms:performance.now()-began};}
+  }
+  // Serialize private cache updates; no journal writer, actor or permission is
+  // substituted, and original writer-drain semantics remain per read.
+  const serial=(id,query)=>{const next=pending.then(()=>read(id,query));pending=next.catch(()=>{});return next;};
+  return Object.freeze({
+    readPageState(id,taskDigest){if(!validHash(taskDigest))return Promise.reject(new TypeError('Exact accepted task digest required.'));return serial(id,{kind:'page',taskDigest});},
+    readReceipt(id,invocationId){if(typeof invocationId!=='string'||!/^[a-f0-9-]{36}$/.test(invocationId))return Promise.reject(new TypeError('Exact original invocation id required.'));return serial(id,{kind:'receipt',invocationId});},
+    status(){return structuredClone(stats);},clear(){return pending.then(()=>clear());},
+  });
+}

package/src/session-read-cache.mjs

@@ -1,20 +1,40 @@
 // 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.
+import {sealRecord} from './audit.mjs';
+
 export class SessionJournalCache {
   #entry;
-  constructor({maxBytes=8*1024*1024}={}) {
+  constructor({maxBytes=16*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};
+    this.maxBytes=maxBytes;this.stats={hits:0,misses:0,prefix_hits:0,prefix_records:0,suffix_records: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;
   }
+  // Called only after the complete fresh file has been parsed and admitted.
+  // Match ALL old bytes through a complete line boundary. Recompute every new
+  // seal at its absolute original sequence; never trust a suffix's claimed tip.
+  extend(id,bytes,rows) {
+    const prior=this.#entry;
+    if(!prior||prior.id!==id||!prior.audit.verified||prior.bytes.at(-1)!==10||bytes.length<=prior.bytes.length||rows.length<=prior.audit.records||!bytes.subarray(0,prior.bytes.length).equals(prior.bytes))return null;
+    let previous=prior.audit.tip_sha256,sealed=prior.audit.sealed_records,legacy=prior.audit.legacy_records;const violations=[];
+    for(let i=prior.audit.records;i<rows.length;i++){
+      const {audit,...body}=rows[i],expected=sealRecord(body,i,previous).audit;
+      if(audit){
+        sealed++;
+        if(audit.version!==1||audit.sequence!==i||audit.previous_sha256!==previous||audit.sha256!==expected.sha256)violations.push({row:i,reason:'journal_hash_chain_mismatch'});
+      }else{legacy++;if(sealed)violations.push({row:i,reason:'unsealed_record_after_sealed_suffix'});}
+      previous=expected.sha256;
+    }
+    this.stats.prefix_hits++;this.stats.prefix_records+=prior.audit.records;this.stats.suffix_records+=rows.length-prior.audit.records;
+    return {scope:'local_journal_consistency',verified:rows.length>0&&!legacy&&!violations.length,consistent:!violations.length,records:rows.length,sealed_records:sealed,legacy_records:legacy,tip_sha256:previous,integrity:'local_hash_chain_not_signed',violations};
+  }
   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'};}
+  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',prefix_proof:'complete_prior_bytes_equal_and_absolute_suffix_seals_replayed'};}
 }

package/src/sessions.mjs

@@ -1,15 +1,20 @@
 import { performance } from 'node:perf_hooks';
 import { SessionJournalCache } from './session-read-cache.mjs';
-import { mkdir, open, readFile, readdir, unlink, stat } from 'node:fs/promises';
+import { open, readFile, readdir, unlink, stat, link } from 'node:fs/promises';
 import path from 'node:path';
 import { createHash, randomUUID } from 'node:crypto';
 import { defaultStateDir } from './compat.mjs';
 import { auditJournal, sealRecord } from './audit.mjs';
 import { acquireProcessLock } from './process-lock.mjs';
+import { assertClassifierChannels } from './event-channels.mjs';
+import { ensurePrivateDirectory } from './private-fs.mjs';
+import { t, registerMessages } from './i18n/index.mjs';
+
+registerMessages({'Invalid session ID.': 'ID de sesión inválido.'});
 
 export class SessionStore {
   #journalCache;
-  constructor({ cwd, stateDir = defaultStateDir(cwd), journalCacheBytes=8*1024*1024 }) {
+  constructor({ cwd, stateDir = defaultStateDir(cwd), journalCacheBytes=16*1024*1024 }) {
     this.cwd = cwd;
     this.dir = path.join(stateDir, 'sessions', createHash('sha256').update(cwd).digest('hex').slice(0, 16));
     this.writers = new Map();
@@ -17,20 +22,28 @@ export class SessionStore {
     this.lastLoadProfile=null;
   }
   file(id) {
-    if (!/^[a-f0-9-]{36}$/.test(id)) throw new Error('ID de sesión inválido.');
+    if (!/^[a-f0-9-]{36}$/.test(id)) throw new Error(t('Invalid session ID.'));
     return path.join(this.dir, `${id}.jsonl`);
   }
   async validateForRecovery(id) {
     // Do not go through load(): append's own writer promise may be awaiting us.
     const rows=(await readFile(this.file(id),'utf8')).trim().split('\n').map(JSON.parse);
+    assertClassifierChannels(rows);
     if(rows[0]?.type!=='session' || rows[0]?.id!==id || rows[0]?.cwd!==this.cwd || !auditJournal(rows).consistent)throw Object.assign(new Error('Libro inválido; no se retiró el lock ni se ejecutaron efectos.'),{code:'AUDIT_INVALID'});
   }
   async create(model, provider = 'anthropic') {
-    await mkdir(this.dir, { recursive: true, mode: 0o700 });
-    const id = randomUUID(), file = await open(this.file(id), 'wx', 0o600);
-    try { await file.writeFile(JSON.stringify(sealRecord({ type: 'session', id, cwd: this.cwd, model, provider, created_at: new Date().toISOString() }, 0)) + '\n'); await file.sync(); }
-    finally { await file.close(); }
-    return this.load(id);
+    return this.reserve({model,provider});
+  }
+  // Host-reserved identities publish a complete fsynced header atomically.
+  // An existing identity is observed, never truncated or initialized again.
+  async reserve({id=randomUUID(),model,provider='anthropic',created_at=new Date().toISOString()}) {
+    await ensurePrivateDirectory(this.dir);
+    const target=this.file(id),temporary=path.join(this.dir,'.birth-'+randomUUID()),file=await open(temporary,'wx',0o600);
+    try {await file.writeFile(JSON.stringify(sealRecord({type:'session',id,cwd:this.cwd,model,provider,created_at},0))+'\n');await file.sync();}finally{await file.close();}
+    try{await link(temporary,target);}catch(error){if(error.code!=='EEXIST')throw error;}finally{await unlink(temporary).catch(()=>{});}
+    const session=await this.load(id),header=session.rows[0];
+    if(!session.journalAudit.consistent||header.id!==id||header.cwd!==this.cwd||header.model!==model||header.provider!==provider)throw Object.assign(new Error('Reserved native session belongs to another identity/configuration.'),{code:'SESSION_IDENTITY_CONFLICT'});
+    return session;
   }
   async load(id) {
     const began=performance.now();
@@ -41,7 +54,8 @@ export class SessionStore {
     const waitDone=performance.now(),bytes=await readFile(this.file(id)),readDone=performance.now();
     this.lastLoadProfile.phase='parse';this.lastLoadProfile.bytes_read=bytes.length;
     const rows=bytes.toString('utf8').trim().split('\n').map(row=>JSON.parse(row)),parseDone=performance.now();
-    if (rows[0]?.type !== 'session' || rows[0].cwd !== this.cwd) throw new Error('La sesión pertenece a otro directorio o es inválida.');
+    if (rows[0]?.type !== 'session' || rows[0].id!==id || rows[0].cwd !== this.cwd) throw new Error('La sesión pertenece a otro directorio o es inválida.');
+    assertClassifierChannels(rows);
     this.lastLoadProfile.phase='fold';
     let messages = []; const historyMessages = []; let metadata = rows[0], goal, queue, draft = '', draftAttachments = [], compaction, projection;
     for (const row of rows.slice(1)) {
@@ -60,14 +74,24 @@ export class SessionStore {
     }
     this.lastLoadProfile.phase='audit';
     const foldDone=performance.now(),cachedAudit=this.#journalCache.get(id,bytes),cacheDone=performance.now();
-    const journalAudit=cachedAudit || auditJournal(rows),auditDone=performance.now();
+    const extendedAudit=cachedAudit?null:this.#journalCache.extend(id,bytes,rows);
+    const journalAudit=cachedAudit || extendedAudit || auditJournal(rows),auditDone=performance.now();
     if(!cachedAudit)this.#journalCache.set(id,bytes,journalAudit);
-    this.lastLoadProfile={pid:process.pid,session_id:id,status:'returned',phase:'complete',bytes_read:bytes.length,rows:rows.length,wait_writers_ms:waitDone-began,read_ms:readDone-waitDone,parse_ms:parseDone-readDone,fold_ms:foldDone-parseDone,cache_compare_ms:cacheDone-foldDone,audit_ms:auditDone-cacheDone,total_ms:performance.now()-began,audit_source:cachedAudit?'verified_identical_bytes':'full_journal_replay',cache:this.#journalCache.status()};
+    this.lastLoadProfile={pid:process.pid,session_id:id,status:'returned',phase:'complete',bytes_read:bytes.length,rows:rows.length,wait_writers_ms:waitDone-began,read_ms:readDone-waitDone,parse_ms:parseDone-readDone,fold_ms:foldDone-parseDone,cache_compare_ms:cacheDone-foldDone,audit_ms:auditDone-cacheDone,total_ms:performance.now()-began,audit_source:cachedAudit?'verified_identical_bytes':extendedAudit?'verified_identical_prefix_and_suffix_replay':'full_journal_replay',cache:this.#journalCache.status()};
     return { ...metadata, messages, historyMessages, compaction, projection, rows, journalAudit, goal, queue, draft, draftAttachments };
     }catch(error){this.lastLoadProfile={...this.lastLoadProfile,status:'failed',error_code:error.code || error.name,total_ms:performance.now()-began,cache:this.#journalCache.status()};throw error;}
   }
+  // Forensic read only: no provider, messages, goals or control state is folded.
+  // Runtime resume must always use load(), including its channel admission guard.
+  async readForAudit(id) {
+    while (this.writers.has(id)) await this.writers.get(id).catch(() => {});
+    const rows = (await readFile(this.file(id), 'utf8')).trim().split('\n').map(JSON.parse);
+    if (rows[0]?.type !== 'session' || rows[0].id !== id || rows[0].cwd !== this.cwd) throw new Error('Invalid session identity for audit.');
+    return { id, cwd: this.cwd, rows };
+  }
   getLoadProfile(){return this.lastLoadProfile?structuredClone(this.lastLoadProfile):null;}
   async append(id, record) {
+    assertClassifierChannels([record]);
     const previous = this.writers.get(id) || Promise.resolve();
     const next = previous.catch(() => {}).then(async () => {
       const name = this.file(id), lockPath = `${name}.append.lock`;

package/src/source-editor-role.mjs

@@ -0,0 +1,13 @@
+import {digest} from './operations.mjs';
+export const SOURCE_EDITOR_MECHANISM='comal-source-editor-v1';
+export const SOURCE_EDITOR_NAMES=Object.freeze(['Read','Write','Edit','Glob','Grep','ListDirectory','FileInfo','SourceDraft','SourceRetain','SourceRead','SourcePublish','EvidenceRead']);
+export const sourceEditorContract=contract=>{const {revision,...semantic}=contract;return digest(semantic);};
+export function preparedEditorRole(prepared,index){
+ if(!prepared)return null;
+ const task=(prepared.operation==='AgentBatch'?prepared.input?.tasks:[prepared.input])?.[index],role=prepared.editor_roles?.[index];
+ if(task?.work_tracking!=='parent')return role===undefined||role===null?null:undefined;
+ if(task.isolation!=='git'||!role||role.mechanism!==SOURCE_EDITOR_MECHANISM||typeof role.system!=='string'||!role.system.trim()||role.system_digest!==digest(role.system)||!Array.isArray(role.tools)||!role.tools.length||role.tools.some(t=>!SOURCE_EDITOR_NAMES.includes(t.name)||! /^[a-f0-9]{64}$/.test(t.semantic_digest))||new Set(role.tools.map(t=>t.name)).size!==role.tools.length)return undefined;
+ const expected=SOURCE_EDITOR_NAMES.filter(name=>!task.allowed_tools||task.allowed_tools.includes(name));if(digest(role.tools.map(t=>t.name))!==digest(expected))return undefined;
+ return role;
+}
+export function reservedEditorRole(prepared,index){const role=preparedEditorRole(prepared,index);if(role===undefined)return undefined;if(role===null)return null;const {system,...bound}=role;return bound;}