@milpa/comal 0.1.6 → 0.2.0

package/src/plugins.mjs

@@ -2,7 +2,16 @@ import path from 'node:path';
 import { randomUUID } from 'node:crypto';
 import { Operation, immutable, toolEffects } from './operations.mjs';
 import { defaultStateDir } from './compat.mjs';
-import { readPluginConfig, importPluginEntry } from './plugin-config.mjs';
+import { readPluginConfig, importPluginEntry, inspectPluginModule } from './plugin-config.mjs';
+import { normalizeNotice } from './plugin-notices.mjs';
+import { t, registerMessages } from './i18n/index.mjs';
+
+registerMessages({
+  'Plugin arguments must be a JSON object.': 'Los argumentos de plugin deben ser un objeto JSON.',
+  'Use /plugins [list|enable ID|disable ID|reload [ID]|run ID OPERATION {JSON}].': 'Usa /plugins [list|enable ID|disable ID|reload [ID]|run ID OPERACIÓN {JSON}].',
+});
+// Los errores del runtime pueden quedar en el estado que lee el modelo (PluginStatus):
+// inglés fijo. Sólo los errores de uso de /plugins pasan por t().
 
 const idPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const jsonCopy = value => JSON.parse(JSON.stringify(value));
@@ -14,8 +23,8 @@ export function parsePluginCommand(text = '') {
   if (action === 'reload' && !rest) return { name: 'PluginReload', input: {} };
   if (['enable', 'disable', 'reload'].includes(action) && idPattern.test(rest)) return { name: { enable: 'PluginEnable', disable: 'PluginDisable', reload: 'PluginReload' }[action], input: { id: rest } };
   const run = /^(\S+)\s+(\S+)(?:\s+([\s\S]+))?$/.exec(rest);
-  if (action === 'run' && run) { const input = JSON.parse(run[3] || '{}'); if (!input || Array.isArray(input) || typeof input !== 'object') throw new Error('Los argumentos de plugin deben ser un objeto JSON.'); return { name: 'PluginRun', input: { id: run[1], operation: run[2], arguments: input } }; }
-  throw new Error('Usa /plugins [list|enable ID|disable ID|reload [ID]|run ID OPERACIÓN {JSON}].');
+  if (action === 'run' && run) { const input = JSON.parse(run[3] || '{}'); if (!input || Array.isArray(input) || typeof input !== 'object') throw new Error(t('Plugin arguments must be a JSON object.')); return { name: 'PluginRun', input: { id: run[1], operation: run[2], arguments: input } }; }
+  throw new Error(t('Use /plugins [list|enable ID|disable ID|reload [ID]|run ID OPERATION {JSON}].'));
 }
 
 export class PluginRuntime {
@@ -24,11 +33,13 @@ export class PluginRuntime {
   #services = new Map();
   #queue = Promise.resolve();
   #closing = false;
-  constructor({ cwd, house, services = {}, configPath, onEvent = () => {} }) {
-    Object.assign(this, { cwd, house, onEvent });
+  // notify(notice): el host encola avisos de plugins (plugin-notices.mjs); sin él, ctx.notify responde unavailable.
+  constructor({ cwd, house, services = {}, configPath, onEvent = () => {}, notify }) {
+    Object.assign(this, { cwd, house, onEvent, notify });
     this.file = path.resolve(configPath || path.join(defaultStateDir(cwd), 'plugins.json'));
     for (const [name, value] of Object.entries(services)) this.#services.set(name, { owner: 'host', value });
   }
+  async #notify(notice) { if (typeof this.notify !== 'function') return { status: 'unavailable' }; try { return await this.notify(notice); } catch (error) { return { status: 'failed', error: String(error.message).slice(0, 200) }; } }
   #exclusive(task) { const next = this.#queue.catch(() => {}).then(task); this.#queue = next; return next; }
   async #event(event) { try { await this.onEvent({ type: 'plugin_status', ...event }); } catch {} }
   #definition(definition) {
@@ -41,7 +52,7 @@ export class PluginRuntime {
     return immutable({ id: definition.id, version: definition.version, requires: names(definition.requires || []), provides: names(definition.provides || []), tool_loading: definition.tool_loading || 'eager', hook_timeout_ms: definition.hook_timeout_ms ?? 1000, discovery: discovery ? structuredClone(discovery) : null, config_schema: definition.config_schema ? structuredClone(definition.config_schema) : null, activate: definition.activate });
   }
   register(definition, { config = {}, builtin = false, module, fingerprint } = {}) {
-    if (this.#closing) throw new Error('Runtime de plugins cerrado.');
+    if (this.#closing) throw new Error('Plugin runtime closed.');
     const manifest = this.#definition(definition);
     if (this.#known.has(manifest.id)) throw new Error(`Plugin duplicado: ${manifest.id}`);
     this.#known.set(manifest.id, { id: manifest.id, definition: manifest, config: immutable(jsonCopy(config)), builtin, module, fingerprint, state: 'registered', disabled: false });
@@ -49,7 +60,7 @@ export class PluginRuntime {
   status() {
     return { config_path: this.file, services: [...this.#services.keys()], plugins: [...this.#known.values()].map(item => {
       const scope = this.#instances.get(item.id);
-      return { id: item.id, version: item.definition?.version, builtin: item.builtin || false, state: item.state, module: item.module || item.entry?.module, fingerprint: item.fingerprint, tool_loading: item.definition?.tool_loading || 'eager', operations: scope?.active ? [...scope.operations.keys()] : [], requires: item.definition?.requires || [], provides: item.definition?.provides || [], active_calls: scope?.leases || 0, ...(item.error ? { error: item.error } : {}) };
+      return { id: item.id, version: item.definition?.version, builtin: item.builtin || false, state: item.state, module: item.module || item.entry?.module, fingerprint: item.fingerprint, ...(item.code_fingerprint ? { code_fingerprint: item.code_fingerprint } : {}), ...(item.trust ? { trust: item.trust } : {}), tool_loading: item.definition?.tool_loading || 'eager', operations: scope?.active ? [...scope.operations.keys()] : [], requires: item.definition?.requires || [], provides: item.definition?.provides || [], active_calls: scope?.leases || 0, ...(item.error ? { error: item.error } : {}) };
     }) };
   }
   async discover({ missing = true } = {}) {
@@ -63,49 +74,66 @@ export class PluginRuntime {
     }
     this.desired = source; return source;
   }
-  async initialize({ trust = false, signal } = {}) {
+  // trusted(entry, inspection) is the host's remembered human trust. It reads code, never imports it.
+  async initialize({ trust = false, trusted, signal } = {}) {
     await this.discover();
     if (trust) await this.load(undefined, { signal });
+    else if (trusted) for (const entry of this.desired.entries.filter(entry => entry.enabled)) {
+      const item = this.#known.get(entry.id); if (!item || item.builtin || this.#instances.get(entry.id)?.active) continue;
+      let verdict;
+      try { verdict = await trusted(entry, await inspectPluginModule(entry.module)); }
+      catch (error) { verdict = { status: 'unavailable', reasons: [error.message] }; }
+      item.trust = verdict;
+      if (verdict?.status !== 'trusted') { if (verdict?.status === 'stale') await this.#event({ id: entry.id, state: 'pending_trust', trust: verdict.status, error: `Trust no longer current (${verdict.reasons.join(', ')}). Use /plugins enable ${entry.id} to review it.` }); continue; }
+      try { await this.load(entry.id, { signal, expect: verdict.expect }); }
+      catch (error) { if (error.code === 'PLUGIN_TRUST_STALE') { item.state = 'pending_trust'; item.error = null; item.trust = { status: 'stale', reasons: ['code'] }; await this.#event({ id: entry.id, state: 'pending_trust', trust: 'stale', error: error.message }); } else if (signal?.aborted) throw error; }
+    }
     return this.status();
   }
-  async #import(item, signal) {
+  /** Inspect configured local code for a human trust decision. Never imports it. */
+  async inspect(id) {
+    await this.discover(); const entry = this.desired.entries.find(entry => entry.id === id);
+    if (!entry) throw new Error(`Local plugin not configured: ${id}`);
+    return { entry, code: await inspectPluginModule(entry.module) };
+  }
+  async #import(item, signal, expect) {
     signal?.throwIfAborted();
     if (!item.entry) return item;
-    const imported = await importPluginEntry({ ...item.entry, enabled: true }); signal?.throwIfAborted();
-    return { ...item, definition: this.#definition(imported.definition), config: immutable(jsonCopy(item.entry.config)), module: imported.module, fingerprint: imported.fingerprint };
+    const imported = await importPluginEntry({ ...item.entry, enabled: true }, { expect }); signal?.throwIfAborted();
+    return { ...item, definition: this.#definition(imported.definition), config: immutable(jsonCopy(item.entry.config)), module: imported.module, fingerprint: imported.fingerprint, code_fingerprint: imported.code_fingerprint, trust: expect ? { status: 'trusted' } : item.trust };
   }
-  async load(id, { signal } = {}) {
+  async load(id, { signal, expect } = {}) {
     return this.#exclusive(async () => {
       this.#open(); const source = await this.discover();
       const wanted = new Set(this.desired.entries.filter(entry => entry.enabled).map(entry => entry.id));
       const entries = id ? [this.desired.entries.some(entry => entry.id === id) ? this.#known.get(id) : undefined] : this.desired.entries.filter(entry => entry.enabled).map(entry => this.#known.get(entry.id));
-      if (entries.some(item => !item || item.builtin)) throw new Error('Plugin local no configurado o reservado.');
+      if (entries.some(item => !item || item.builtin)) throw new Error('Local plugin not configured or reserved.');
       const retiring = id ? [] : [...this.#instances.values()].filter(scope => scope.active && scope.item.entry && !wanted.has(scope.id));
       const changing = new Set([...entries.map(item => item.id), ...retiring.map(scope => scope.id)]);
-      for (const scope of this.#instances.values()) if (scope.active && !changing.has(scope.id) && [...scope.requiredOwners].some(owner => changing.has(owner))) throw new Error(`Plugin ${scope.id} depende de un proveedor que cambiará. Desactívalo primero.`);
+      for (const scope of this.#instances.values()) if (scope.active && !changing.has(scope.id) && [...scope.requiredOwners].some(owner => changing.has(owner))) throw new Error(`Plugin ${scope.id} depends on a provider that will change. Disable it first.`);
       const candidates = [];
-      for (const item of entries) { if (id) this.#dependents(item.id); candidates.push(await this.#import(item, signal)); }
-      await this.#activate(candidates, signal, retiring, async () => { if ((await readPluginConfig(this.file, { missing: true })).hash !== source.hash) throw new Error('La configuración de plugins cambió durante la activación; no se publicó.'); }); return this.status();
+      for (const item of entries) { if (id) this.#dependents(item.id); candidates.push(await this.#import(item, signal, id ? expect : undefined)); }
+      await this.#activate(candidates, signal, retiring, async () => { if ((await readPluginConfig(this.file, { missing: true })).hash !== source.hash) throw new Error('The plugin configuration changed during activation; nothing was published.'); }); return this.status();
     });
   }
-  #open() { if (this.#closing) throw new Error('Runtime de plugins cerrado.'); }
+  #open() { if (this.#closing) throw new Error('Plugin runtime closed.'); }
   #dependents(id) {
     const dependents = [...this.#instances.values()].filter(scope => scope.active && scope.id !== id && scope.requiredOwners.has(id));
-    if (dependents.length) throw new Error(`Plugin ${id} tiene consumidores activos: ${dependents.map(scope => scope.id).join(', ')}. Desactívalos primero.`);
+    if (dependents.length) throw new Error(`Plugin ${id} has active consumers: ${dependents.map(scope => scope.id).join(', ')}. Disable them first.`);
   }
-  enable(id, { signal } = {}) {
+  enable(id, { signal, expect } = {}) {
     return this.#exclusive(async () => {
-      this.#open(); const item = this.#known.get(id); if (!item) throw new Error(`Plugin desconocido: ${id}`);
+      this.#open(); const item = this.#known.get(id); if (!item) throw new Error(`Unknown plugin: ${id}`);
       if (this.#instances.get(id)?.active) return this.status();
       const source = item.entry ? await this.discover() : null;
-      if (source && !source.entries.some(entry => entry.id === id)) throw new Error(`Plugin ya no configurado: ${id}`);
-      const candidate = item.entry ? await this.#import(item, signal) : { ...item, disabled: false };
-      await this.#activate([candidate], signal, [], source ? async () => { if ((await readPluginConfig(this.file, { missing: true })).hash !== source.hash) throw new Error('La configuración de plugins cambió durante la activación; no se publicó.'); } : undefined); return this.status();
+      if (source && !source.entries.some(entry => entry.id === id)) throw new Error(`Plugin no longer configured: ${id}`);
+      const candidate = item.entry ? await this.#import(item, signal, expect) : { ...item, disabled: false };
+      await this.#activate([candidate], signal, [], source ? async () => { if ((await readPluginConfig(this.file, { missing: true })).hash !== source.hash) throw new Error('The plugin configuration changed during activation; nothing was published.'); } : undefined); return this.status();
     });
   }
   reload(id, { signal } = {}) {
     return this.#exclusive(async () => {
-      this.#open(); const item = this.#known.get(id); if (!item) throw new Error(`Plugin desconocido: ${id}`);
+      this.#open(); const item = this.#known.get(id); if (!item) throw new Error(`Unknown plugin: ${id}`);
       this.#dependents(id); await this.#activate([await this.#import(item, signal)], signal); return this.status();
     });
   }
@@ -138,7 +166,7 @@ export class PluginRuntime {
     candidates.forEach(visit); return ordered;
   }
   async #stage(item, available, signal) {
-    const scope = { id: item.id, item, generation: randomUUID(), state: 'loading', active: false, retired: false, leases: 0, waiters: [], operations: new Map(), services: new Map(), listeners: [], guards: [], removers: [], disposers: [], controller: new AbortController(), requiredOwners: new Set() };
+    const scope = { id: item.id, item, generation: randomUUID(), state: 'loading', active: false, retired: false, leases: 0, waiters: [], operations: new Map(), services: new Map(), listeners: [], guards: [], removers: [], disposers: [], notices: [], controller: new AbortController(), requiredOwners: new Set() };
     const abortActivation = () => scope.controller.abort(signal.reason);
     if (signal?.aborted) abortActivation(); else signal?.addEventListener('abort', abortActivation, { once: true });
     const alive = () => { if (scope.retired || !['loading', 'active'].includes(scope.state)) throw new Error('Scope de plugin retirado.'); };
@@ -146,15 +174,22 @@ export class PluginRuntime {
     const lease = async callback => { if (!scope.active || scope.retired) throw new Error('El plugin fue retirado; no se ejecutó.'); scope.leases++; try { return await callback(); } finally { if (!--scope.leases) scope.waiters.splice(0).forEach(resolve => resolve()); } };
     const register = (definition, human = false) => {
       staging();
-      for (const key of Object.keys(definition)) if (!['name', 'description', 'input_schema', 'output_schema', 'effects', 'run', ...(item.builtin ? ['permission'] : [])].includes(key)) throw new Error(`Contrato reservado al host: ${key}`);
+      for (const key of Object.keys(definition)) if (!['name', 'description', 'input_schema', 'output_schema', 'effects', 'run', 'confirm', 'confirm_summary', ...(item.builtin ? ['permission'] : [])].includes(key)) throw new Error(`Contrato reservado al host: ${key}`);
+      // confirm:'always' sólo puede subir el techo (pedir siempre al humano), nunca bajarlo.
+      if (Object.hasOwn(definition, 'confirm') && definition.confirm !== 'always') throw new Error("confirm de plugin sólo admite 'always'.");
+      if (Object.hasOwn(definition, 'confirm_summary') && typeof definition.confirm_summary !== 'function') throw new Error('confirm_summary de plugin debe ser una función.');
       if (Object.hasOwn(definition, 'permission') && (typeof definition.permission !== 'string' || !/^[A-Za-z][A-Za-z0-9_]{0,63}$/.test(definition.permission))) throw new Error('Un builtin requiere un permiso nominal válido; no puede omitir el juicio.');
       if (!/^[A-Za-z][A-Za-z0-9_]{0,31}$/.test(definition.name) || typeof definition.run !== 'function') throw new Error('Nombre/handler de operación de plugin inválido.');
       const name = item.builtin ? definition.name : `plugin__${item.id}__${definition.name}`;
       if (name.length > 64 || scope.operations.has(name)) throw new Error(`Operación duplicada o nombre demasiado largo: ${name}`);
-      const handler = definition.run;
+      const handler = definition.run, summarize = definition.confirm_summary;
       scope.operations.set(name, new Operation({ name, description: definition.description, input_schema: definition.input_schema, output_schema: definition.output_schema, revision: scope.generation, origin: { plugin: item.id, version: item.definition.version, generation: scope.generation, builtin: item.builtin || false, module_sha256: item.fingerprint || null, ...(!human && item.definition.tool_loading === 'deferred' ? { tool_loading: 'deferred', discovery: item.definition.discovery } : {}) }, effects: definition.effects || (item.builtin ? toolEffects(name) : toolEffects('__unknown_plugin')), audience: human ? 'human' : 'any', surfaces: human ? ['cli', 'tui'] : ['cli', 'tui', 'agent'], permission: item.builtin ? definition.permission ?? name : name, steps: false,
+        ...(definition.confirm ? { confirm: definition.confirm } : {}),
+        // El resumen corre con el mismo lease y la misma señal que la operación: si el plugin se retira, no se muestra.
+        ...(summarize ? { confirm_summary: (input, options = {}) => lease(() => summarize(immutable(jsonCopy(input)), Object.freeze({ signal: options.signal ? AbortSignal.any([options.signal, scope.controller.signal]) : scope.controller.signal }))) } : {}),
         run: (input, options) => lease(() => handler(immutable(jsonCopy(input)), Object.freeze({ signal: options.signal ? AbortSignal.any([options.signal, scope.controller.signal]) : scope.controller.signal,
-          ...(item.builtin ? { invocation_id: options.invocation_id, sessionId: options.sessionId, actor: options.actor ? immutable(jsonCopy(options.actor)) : null } : {}) }))) }));
+          ...(item.builtin ? { invocation_id: options.invocation_id, sessionId: options.sessionId, actor: options.actor ? immutable(jsonCopy(options.actor)) : null } : {}),
+          ...(item.builtin&&item.id==='delegation'&&['Agent','AgentBatch','AgentContinue','AgentResume'].includes(name)&&typeof options.revalidate==='function'?{revalidate:async request=>{alive();scope.controller.signal.throwIfAborted();return options.revalidate(request);}}:{}) }))) }));
       return name;
     };
     const context = Object.freeze({
@@ -168,6 +203,12 @@ export class PluginRuntime {
         const watch = { event, listener }; scope.listeners.push(watch); if (scope.active) this.#watch(scope, watch, lease);
       },
       guard: check => { staging(); if (typeof check !== 'function') throw new Error('Guarda requiere función.'); scope.guards.push(check); },
+      // Aviso a la conversación: información externa, nunca intención humana ni permiso.
+      notify: async input => {
+        alive(); const notice = normalizeNotice(input, { plugin: item.id, generation: scope.generation });
+        if (!scope.active) { if (scope.notices.length >= 16) return { status: 'full' }; return new Promise(resolve => scope.notices.push({ notice, resolve })); }
+        return this.#notify(notice);
+      },
     });
     scope.lease = lease;
     try {
@@ -220,6 +261,7 @@ export class PluginRuntime {
         this.#known.set(scope.id, scope.item); this.#instances.set(scope.id, scope);
         for (const watch of scope.listeners) this.#watch(scope, watch, scope.lease);
         for (const check of scope.guards) scope.removers.push(this.house.guard(`${scope.id}:${scope.generation}`, view => scope.active && scope.operations.has(view.operation) ? check(view) : undefined));
+        for (const { notice, resolve } of scope.notices.splice(0)) this.#notify(notice).then(resolve);
       }
       committed = true;
       const cleanupTasks = previous.map(old => this.#retire(old));
@@ -237,6 +279,7 @@ export class PluginRuntime {
   }
   async #retire(scope) {
     if (scope.retirement) return scope.retirement; scope.retired = true; scope.active = false; scope.state = 'unloading'; scope.controller.abort(new Error('Plugin retirado.'));
+    for (const { resolve } of scope.notices.splice(0)) resolve({ status: 'retired' });
     scope.removers.splice(0).forEach(remove => remove());
     scope.retirement = this.#cleanup(scope); return scope.retirement;
   }
@@ -249,7 +292,7 @@ export class PluginRuntime {
   }
   disable(id) {
     return this.#exclusive(async () => {
-      this.#open(); this.#dependents(id); const item = this.#known.get(id); if (!item) throw new Error(`Plugin desconocido: ${id}`);
+      this.#open(); this.#dependents(id); const item = this.#known.get(id); if (!item) throw new Error(`Unknown plugin: ${id}`);
       const scope = this.#instances.get(id); item.disabled = true; item.state = 'disabled';
       if (scope?.active) {
         this.house.registry.replace([...scope.operations.keys()], []);

package/src/private-fs.mjs

@@ -0,0 +1,40 @@
+import {mkdir,lstat,readFile,realpath} from 'node:fs/promises';
+import {spawn} from 'node:child_process';
+import {createInterface} from 'node:readline';
+import path from 'node:path';
+
+const fail=message=>Object.assign(new Error(message),{code:'PRIVATE_STATE_UNSAFE'});
+let broker,starting,sequence=0;
+async function windowsBroker(){
+ if(broker)return broker;if(starting)return starting;
+ starting=(async()=>{
+  const script=await readFile(new URL('./windows-private.ps1',import.meta.url),'utf8'),program=path.join(process.env.SystemRoot||'C:\\Windows','System32','WindowsPowerShell','v1.0','powershell.exe');
+  const child=spawn(program,['-NoLogo','-NoProfile','-NonInteractive','-ExecutionPolicy','Bypass','-EncodedCommand',Buffer.from(script,'utf16le').toString('base64')],{stdio:['pipe','pipe','pipe'],windowsHide:true});
+  const pending=new Map(),lines=createInterface({input:child.stdout});let diagnostic='';
+  const references=active=>{const method=active?'ref':'unref';child[method]();for(const stream of[child.stdin,child.stdout,child.stderr])stream[method]?.();};
+  child.stderr.on('data',data=>{if(diagnostic.length<2000)diagnostic+=data;});child.stdin.on('error',()=>{});
+  const stopped=()=>{for(const job of pending.values()){clearTimeout(job.timer);job.reject(fail('Windows private-state inspection stopped. '+diagnostic.slice(0,300)));}pending.clear();if(broker?.child===child)broker=undefined;};
+  child.on('error',stopped);child.on('close',stopped);
+  lines.on('line',line=>{let result;try{result=JSON.parse(line);}catch{stopped();child.kill();return;}const job=pending.get(result.id);if(!job)return;clearTimeout(job.timer);pending.delete(result.id);if(!pending.size)references(false);result.ok?job.resolve():job.reject(fail(result.error||'Windows private-state ACL does not verify.'));});
+  const result={child,request:(action,file)=>new Promise((resolve,reject)=>{
+   const id=++sequence;references(true);const timer=setTimeout(()=>{pending.delete(id);reject(fail('Windows ACL inspection exceeded its deadline.'));if(!pending.size)references(false);},15000);pending.set(id,{resolve,reject,timer});
+   child.stdin.write(JSON.stringify({id,action,path:path.resolve(file)})+'\n',error=>{if(error){clearTimeout(timer);pending.delete(id);reject(fail('Windows ACL inspection could not be sent.'));if(!pending.size)references(false);}});
+  })};references(false);broker=result;return result;
+ })();try{return await starting;}finally{starting=undefined;}
+}
+export async function ensurePrivateDirectory(directory){
+ if(process.platform==='win32')await(await windowsBroker()).request('ensure',directory);
+ else await mkdir(directory,{recursive:true,mode:0o700});
+}
+export async function assertPrivateDirectory(directory,info){
+ info ||= await lstat(directory);
+ if(!info.isDirectory()||info.isSymbolicLink()||await realpath(directory)!==path.resolve(directory))throw fail('Private state is not a canonical directory.');
+ if(process.platform==='win32')await(await windowsBroker()).request('directory',directory);
+ else if(info.mode&0o077||process.getuid&&info.uid!==process.getuid())throw fail('Private directory permissions or owner do not verify.');
+}
+export async function assertPrivateFile(file,info){
+ info ||= await lstat(file);
+ if(!info.isFile()||info.isSymbolicLink())throw fail('Private state is not a regular file.');
+ if(process.platform==='win32')await(await windowsBroker()).request('file',file);
+ else if(info.mode&0o077||process.getuid&&info.uid!==process.getuid())throw fail('Private file permissions or owner do not verify.');
+}

package/src/process-lock.mjs

@@ -3,6 +3,7 @@ import { open, lstat, unlink } from 'node:fs/promises';
 import { hostname } from 'node:os';
 import { randomUUID } from 'node:crypto';
 import { setTimeout as delay } from 'node:timers/promises';
+import { assertPrivateFile } from './private-fs.mjs';
 
 const optional = file => { try { return readFileSync(file,'utf8').trim(); } catch { return null; } };
 const start = pid => optional(`/proc/${pid}/stat`)?.split(') ').slice(1).join(') ').split(' ')[19] || null;
@@ -18,23 +19,33 @@ export function processDead(owner) {
   return Boolean(owner.start && current && owner.start!==current);
 }
 const fail = (message,code='SESSION_IN_USE') => Object.assign(new Error(message),{code});
-async function inspect(name) {
+async function inspect(name,fault=async()=>{}) {
+  const named=await lstat(name,{bigint:true});if(named.isSymbolicLink()||!named.isFile())throw fail('Unsafe lock type; no lock was removed.','LOCK_UNSAFE');
+  await fault('named',{path:name});
   const file=await open(name,constants.O_RDONLY | constants.O_NOFOLLOW);
   try {
-    const info=await file.stat();
-    if(!info.isFile() || info.size>4096 || info.mode & 0o077 || process.getuid && info.uid!==process.getuid())throw fail('Lock inseguro; no se retiró.','LOCK_UNSAFE');
-    const text=(await file.readFile('utf8')).trim(); let owner;
+    const info=await file.stat({bigint:true});await fault('opened',{path:name});
+    if(info.ino!==named.ino||info.dev!==named.dev||!await same(name,info))throw fail('Lock changed during observation; no owner was assumed.','LOCK_CHANGED');
+    if(!info.isFile() || info.size>4096n)throw fail('Unsafe lock object or size; no lock was removed.','LOCK_UNSAFE');
+    try{await assertPrivateFile(name,await file.stat());}catch{
+      if(!await same(name,info))throw fail('Lock changed during private inspection; no owner was assumed.','LOCK_CHANGED');
+      throw fail('Lock privacy does not verify; no lock was removed.','LOCK_UNSAFE');
+    }
+    if(!await same(name,info))throw fail('Lock changed during private inspection; no owner was assumed.','LOCK_CHANGED');
+    const bytes=Buffer.alloc(4097),{bytesRead}=await file.read(bytes,0,bytes.length,0);if(bytesRead>4096)throw fail('Lock exceeds its owner-record bound.','LOCK_UNSAFE');
+    const text=bytes.subarray(0,bytesRead).toString('utf8').trim();let owner;
     try{owner=JSON.parse(text);}catch{throw fail('Lock sin propietario verificable; no se retiró.','LOCK_UNKNOWN');}
     if(typeof owner==='number')owner={pid:owner}; // Legacy PID: only ESRCH proves death.
     if(!owner || !Number.isSafeInteger(owner.pid) || owner.pid<=0)throw fail('Lock sin propietario verificable; no se retiró.','LOCK_UNKNOWN');
+    if(!await same(name,info))throw fail('Lock changed while reading its owner; no owner was assumed.','LOCK_CHANGED');
     return {info,owner};
   } finally{await file.close();}
 }
-async function same(name,info){try{const current=await lstat(name);return !current.isSymbolicLink() && current.ino===info.ino && current.dev===info.dev;}catch(e){if(e.code==='ENOENT')return false;throw e;}}
+async function same(name,info){try{const current=await lstat(name,{bigint:true});return !current.isSymbolicLink() && current.ino===info.ino && current.dev===info.dev;}catch(e){if(e.code==='ENOENT')return false;throw e;}}
 
 // Only this exclusion gate may reclaim a dead owner. It is never automatically
 // reclaimed itself: two reapers must not unlink a replacement lock concurrently.
-export async function acquireProcessLock(name,{waitMs=0,validate=async()=>{}}={}) {
+export async function acquireProcessLock(name,{waitMs=0,validate=async()=>{},resource,fault=async()=>{}}={}) {
   const until=Date.now()+waitMs;
   for(;;){
     let file, recovered;
@@ -42,29 +53,29 @@ export async function acquireProcessLock(name,{waitMs=0,validate=async()=>{}}={}
     catch(error){
       if(error.code!=='EEXIST')throw error;
       let old;
-      try{old=await inspect(name);}catch(e){if(e.code==='ENOENT')continue;if(e.code==='LOCK_UNKNOWN' && Date.now()<until){await delay(10);continue;}throw e;}
+      try{old=await inspect(name,fault);}catch(e){if(e.code==='ENOENT')continue;if(['LOCK_UNKNOWN','LOCK_CHANGED'].includes(e.code)&&Date.now()<until){await delay(10);continue;}if(e.code==='LOCK_CHANGED')throw fail('The lock changed during observation; no owner was assumed or removed.');throw e;}
       if(processDead(old.owner)){
         let gate;
         try{gate=await open(`${name}.reclaim`,'wx',0o600);}
         catch(e){if(e.code!=='EEXIST')throw e;if(Date.now()>=until)throw fail('Recuperación de lock en uso o interrumpida; no se retiró.','LOCK_RECOVERY_BUSY');}
         if(gate)try{
           await gate.writeFile(JSON.stringify(processIdentity));await gate.sync();
-          const current=await inspect(name).catch(e=>{if(e.code==='ENOENT')return null;throw e;});
+          const current=await inspect(name,fault).catch(e=>{if(['ENOENT','LOCK_CHANGED'].includes(e.code))return null;throw e;});
           if(current && processDead(current.owner) && await same(name,current.info)){
-            await validate();
+            await validate(current.owner);
             if(await same(name,current.info)){
               await unlink(name);
               try{file=await open(name,'wx',0o600);recovered={path:name,owner:current.owner};}
               catch(e){if(e.code!=='EEXIST')throw e;}
             }
           }
-        } finally{const info=await gate.stat();if(await same(`${name}.reclaim`,info))await unlink(`${name}.reclaim`);await gate.close();}
+        } finally{const info=await gate.stat({bigint:true});if(await same(`${name}.reclaim`,info))await unlink(`${name}.reclaim`);await gate.close();}
       }
       if(!file){if(Date.now()>=until)throw fail('Sesión en uso o propietario no recuperable; no se retiró el lock.');await delay(10);continue;}
     }
-    const owner={...processIdentity,token:randomUUID()};
+    const owner={...processIdentity,token:randomUUID(),...(resource?{resource:structuredClone(resource)}:{})};
     try{await file.writeFile(JSON.stringify(owner));await file.sync();}
-    catch(error){const info=await file.stat();if(await same(name,info))await unlink(name);await file.close();throw error;}
-    return {file,recovered,release:async()=>{const info=await file.stat();try{if(await same(name,info))await unlink(name);}finally{await file.close();}}};
+    catch(error){const info=await file.stat({bigint:true});if(await same(name,info))await unlink(name);await file.close();throw error;}
+    return {file,recovered,release:async()=>{const info=await file.stat({bigint:true});try{if(await same(name,info))await unlink(name);}finally{await file.close();}}};
   }
 }

package/src/provider-auth.mjs

@@ -10,15 +10,26 @@ export const AUTH_PROVIDERS = Object.freeze([
   { id: 'codex', label: 'Codex / ChatGPT', method: 'device_code', subscription: true, protocol: 'openai', baseURL: 'https://chatgpt.com/backend-api/codex', documentation: 'https://learn.chatgpt.com/docs/auth' },
   { id: 'kimi', label: 'Kimi Code', method: 'device_code', experimental: true, thirdPartyMethod: 'subscription_key', subscription: true, protocol: 'openai', baseURL: 'https://api.kimi.com/coding/v1', apiKeyEnv: 'KIMI_CODE_API_KEY', documentation: 'https://www.kimi.com/en/help/kimi-code/membership-guide' },
   { id: 'minimax', label: 'MiniMax M Plan', method: 'subscription_key', subscription: true, protocol: 'anthropic', baseURL: 'https://api.minimax.io/anthropic', model: 'MiniMax-M3', apiKeyEnv: 'MINIMAX_SUBSCRIPTION_KEY', documentation: 'https://platform.minimax.io/docs/m-plan/quickstart' },
-  { id: 'grok', label: 'Grok / xAI API', method: 'api_key', subscription: false, protocol: 'openai', baseURL: 'https://api.x.ai/v1', apiKeyEnv: 'XAI_API_KEY', documentation: 'https://docs.x.ai/overview' }
+  { id: 'grok', label: 'Grok / xAI API', method: 'api_key', subscription: false, protocol: 'openai', baseURL: 'https://api.x.ai/v1', apiKeyEnv: 'XAI_API_KEY', documentation: 'https://docs.x.ai/overview' },
+  // Ollama Cloud expone una API compatible con OpenAI en /v1 y /api/show para
+  // descubrir la ventana. La llave sólo viaja en el header hacia ese origen.
+  { id: 'ollama', label: 'Ollama Cloud', method: 'api_key', subscription: false, protocol: 'openai', baseURL: 'https://ollama.com/', apiKeyEnv: 'OLLAMA_API_KEY', documentation: 'https://docs.ollama.com/cloud' }
 ].map(Object.freeze));
+const ALIASES = Object.freeze({ grokia: 'grok', xai: 'grok', chatgpt: 'codex', 'kimi-code': 'kimi', 'ollama-cloud': 'ollama' });
 const failure = (message, code = 'PROVIDER_AUTH_FAILED') => Object.assign(new Error(message), { code });
 function definition(name) {
   const id = String(name || '').toLowerCase();
-  const found = AUTH_PROVIDERS.find(item => item.id === ({ grokia: 'grok', xai: 'grok', chatgpt: 'codex', 'kimi-code': 'kimi' }[id] || id));
-  if (!found) throw failure('Unknown login provider: codex, kimi, minimax or grok.', 'PROVIDER_AUTH_UNKNOWN');
+  const found = AUTH_PROVIDERS.find(item => item.id === (Object.hasOwn(ALIASES, id) ? ALIASES[id] : id));
+  if (!found) throw failure('Unknown login provider: codex, kimi, minimax, grok or ollama.', 'PROVIDER_AUTH_UNKNOWN');
   return found;
 }
+export function authProviderDefinition(name) { return definition(name); }
+// Proveedores cuya credencial es una llave que el humano puede escribir en el
+// campo oculto de la TUI. Codex sólo admite su login de dispositivo.
+export function acceptsSecretLogin(name) {
+  const p = definition(name);
+  return p.id !== 'codex' && (p.method !== 'device_code' || Boolean(p.thirdPartyMethod));
+}
 export function authProviderDefaults(name) {
   const p = definition(name);
   return { authProvider: p.id, provider: p.protocol, protocol: p.protocol, baseURL: p.baseURL, ...(p.model ? { model: p.model } : {}) };

package/src/provider.mjs

@@ -53,9 +53,18 @@ export async function analyzeImages(provider, { prompt, media, signal, maxTokens
   return { answer: result.content.filter(block => block.type === 'text').map(block => block.text).join(''), usage: result.usage, model: provider.model };
 }
 
+// Sólo conteos y el nombre de la herramienta que estaba escribiéndose al cortarse.
+function truncationDetails(content = []) {
+  const blocks = content.filter(block => block && typeof block === 'object'), last = blocks.at(-1);
+  const sum = pick => blocks.reduce((total, block) => total + pick(block), 0);
+  return { text_chars: sum(block => block.type === 'text' ? (block.text || '').length : 0), reasoning_chars: sum(block => block.type === 'thinking' ? (block.thinking || '').length : 0),
+    tool_argument_chars: sum(block => block.type !== 'tool_use' ? 0 : block.truncated_input_chars ?? JSON.stringify(block.input ?? {}).length),
+    ...(last?.type === 'tool_use' && typeof last.name === 'string' && last.name ? { tool_name: last.name } : {}) };
+}
+
 function validateMessage(message) {
   if (!message || !Array.isArray(message.content) || !message.stop_reason) throw new Error('Incomplete model response.');
-  if(message.stop_reason==='max_tokens')throw Object.assign(new Error('Anthropic response truncated; no tools were executed.'),{code:'OUTPUT_LENGTH',usage:message.usage,usage_accounting:normalizeUsage('anthropic',message.usage)});
+  if(message.stop_reason==='max_tokens')throw Object.assign(new Error('Anthropic response truncated; no tools were executed.'),{code:'OUTPUT_LENGTH',usage:message.usage,usage_accounting:normalizeUsage('anthropic',message.usage),details:truncationDetails(message.content)});
   const ids = new Set();
   for (const block of message.content) {
     if (!block || typeof block.type !== 'string') throw new Error('Invalid content block.');
@@ -135,7 +144,7 @@ export class AnthropicProvider {
         else if (d.type === 'signature_delta') block.signature = (block.signature || '') + d.signature;
       } else if (event.type === 'content_block_stop') {
         if (!blocks.has(event.index)) throw new Error('Unknown block closure.');
-        if (partial.has(event.index)) blocks.get(event.index).input = JSON.parse(partial.get(event.index));
+        if (partial.has(event.index)) { const block = blocks.get(event.index), raw = partial.get(event.index); try { block.input = JSON.parse(raw); } catch { delete block.input; block.truncated_input_chars = raw.length; } }
         closed.add(event.index);
       } else if (event.type === 'message_delta') {
         if (!message) throw new Error('Delta without a message.');

package/src/read-only-check.mjs

@@ -31,8 +31,12 @@ export function readOnlyBashCheck(command) {
 
 // Known shipped observation implementations only, not arbitrary plugin/MCP hints.
 // Rechecking still goes through the live contract, guard and permission judge.
-const CHROME_LAB_READS = new Set(['Status', 'Deployment', 'Targets', 'ReadDOM', 'Assert', 'Contexts', 'Console'].map(name => `plugin__chrome-lab__${name}`));
+const CHROME_LAB_READS = new Set(['Status', 'Deployment', 'Targets', 'ReadDOM', 'Assert', 'Contexts', 'Console', 'WorkerDiagnostics'].map(name => `plugin__chrome-lab__${name}`));
 export const chromeLabObservation = operation => CHROME_LAB_READS.has(operation);
-export const readOnlyWorkCheck = (operation, args) => ['Read', 'Glob', 'Grep', 'ListDirectory', 'FileInfo', 'ChromeVerify'].includes(operation) || CHROME_LAB_READS.has(operation) || (operation === 'Bash' && Boolean(readOnlyBashCheck(args?.command)));
+// open-relay: lecturas del canal admin (sin mutación). Las acciones de la fase 2
+// (Reply, Ack, ApprovePlan, RejectPlan) no son observaciones: pasan por la tarjeta.
+const OPEN_RELAY_READS = new Set(['Status', 'Swarms', 'Swarm', 'Task', 'Inbox', 'Message', 'Plans', 'Plan', 'Jobs', 'Job', 'JobLogs', 'Receipt', 'Events', 'Dossier'].map(name => `plugin__open-relay__${name}`));
+export const openRelayObservation = operation => OPEN_RELAY_READS.has(operation);
+export const readOnlyWorkCheck = (operation, args) => ['Read', 'Glob', 'Grep', 'ListDirectory', 'FileInfo', 'ChromeVerify','SourceVerify'].includes(operation) || operation==='GitInspect'&&Boolean(args)&&Object.keys(args).length===0 || CHROME_LAB_READS.has(operation) || (operation === 'Bash' && Boolean(readOnlyBashCheck(args?.command)));
 export const RUNTIME_CHECK_IDS = Object.freeze(['target_id','pageId','page_id','context_id','contextId']);
-export const runtimeBoundReadCheck = (operation, args) => readOnlyWorkCheck(operation,args) && RUNTIME_CHECK_IDS.some(key => Object.hasOwn(args || {},key));
+export const runtimeBoundReadCheck = (operation, args) => readOnlyWorkCheck(operation,args) && (RUNTIME_CHECK_IDS.some(key => Object.hasOwn(args || {},key)) || operation==='plugin__chrome-lab__WorkerDiagnostics'&&Object.hasOwn(args||{},'connection_id')&&Object.hasOwn(args||{},'browser_endpoint_id'));

package/src/remote-control.mjs

@@ -26,8 +26,8 @@ const cancelled = () => Object.assign(new Error('Remote Control connection cance
 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;
+  constructor({client=new CloudClient(),onInput=async()=>{throw Error('Local queue unavailable.');},onStop=async()=>false,onNotice=()=>{},getWorkspace=null,socketFactory=(url,protocol)=>new WebSocket(url,protocol)}={}) {
+    Object.assign(this,{client,onInput,onStop,onNotice,getWorkspace,socketFactory});this.pending=[];this.turnId=null;this.stopped=true;this.transport='disconnected';this.processing=null;this.sending=null;this.lifecycle=null;this.starting=null;
   }
   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;}
@@ -48,7 +48,8 @@ export class RemoteHost {
         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});
+        const workspace=this.getWorkspace?await this.getWorkspace(session):null;this.assertCurrent(run,{starting:true});
+        const opened=await this.client.invoke('remote.sessions.open',{local_session_id:session.id,host_id:randomUUID(),label:boundText(session.name || 'Comal',80),features:['commands_v1','thinking_v1',...(this.getWorkspace?['workspace_v1']:[])]},{expectedAccount:run.account,signal:run.controller.signal});
         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.
@@ -56,6 +57,7 @@ export class RemoteHost {
         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);
+        if(workspace)this.publishWorkspace(workspace,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;
@@ -103,8 +105,30 @@ export class RemoteHost {
     }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;}}
   }
+  publishWorkspace(workspace,run=this.lifecycle) {
+    if(!this.current(run))return;
+    const {source,...content}=workspace,key=digest(content);
+    if(run.workspaceDigest===key)return;
+    if(this.pending.length>=512)throw Error('Remote workspace buffer full.');
+    this.pending.push({event_id:randomUUID(),event:{type:'workspace.snapshot',text:'',turn_id:this.turnId||'local',workspace}});
+    run.workspaceDigest=key;this.flush(run).catch(()=>{});
+  }
+  invalidateWorkspace() {
+    const run=this.lifecycle;if(!this.current(run)||!this.getWorkspace)return;
+    run.workspaceDirty=true;
+    if(run.workspaceTimer||run.workspaceLoading)return;
+    run.workspaceTimer=setTimeout(()=>{run.workspaceTimer=null;this.refreshWorkspace(run);},750);run.workspaceTimer.unref();
+  }
+  async refreshWorkspace(run=this.lifecycle) {
+    if(!this.current(run)||!this.getWorkspace||run.workspaceLoading)return;
+    run.workspaceLoading=true;run.workspaceDirty=false;
+    try {const workspace=await this.getWorkspace();if(this.current(run))this.publishWorkspace(workspace,run);}
+    catch {if(this.current(run))this.onNotice('Remote work state unavailable; local execution continues.');}
+    finally {run.workspaceLoading=false;if(this.current(run)&&run.workspaceDirty)this.invalidateWorkspace();}
+  }
   observe(event) {
     if(this.stopped)return;
+    if(['tool_result','house_waiting','house_answered','result'].includes(event.type))this.invalidateWorkspace();
     const append=projected=>this.pending.push({event_id:randomUUID(),event:projected});
     if(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;
@@ -139,6 +163,7 @@ export class RemoteHost {
   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(){
+    this.invalidateWorkspace();
     if(!this.stopped){this.pending.push({event_id:randomUUID(),event:{type:'turn.settled',text:'Local turn settled.',turn_id:this.turnId || 'local'}});this.flush().catch(()=>{});}
     clearTimeout(this.deltaTimer);this.deltaTimer=null;this.delta='';this.thinkingActive=false;this.turnId=null;this.pulse().catch(()=>{});
   }
@@ -172,7 +197,7 @@ export class RemoteHost {
   }
   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.lifecycle=null;this.starting=null;run.controller?.abort();clearTimeout(run.workspaceTimer);
     this.stopped=true;clearInterval(this.timer);clearTimeout(this.deltaTimer);clearTimeout(this.socketTimeout);this.socket?.close();this.socket=null;this.delta='';this.transport='disconnected';
     this.access=null;this.enablingToken=null;this.pending=[];this.turnId=null;this.processing=null;this.sending=null;this.pulsing=null;this.connecting=null;
     await this.revoke(run);return this.status();

package/src/remote-workspace.mjs

@@ -0,0 +1,50 @@
+import { foldWorkBook } from './work-plan.mjs';
+import { auditJournal } from './audit.mjs';
+
+const text = (value, bytes) => Buffer.from(String(value ?? '')).subarray(0, bytes).toString('utf8').replace(/\uFFFD$/, '');
+const reasons = {
+  'Una comprobación perdió vigencia en el libro.':'A recorded check is no longer current.',
+  'La evidencia de una dependencia cambió; vuelve a comprobar esta tarea.':'Dependency evidence changed; verify this task again.',
+  'Una dependencia perdió su cierre vigente.':'A dependency no longer has current completion evidence.',
+  'Espera una respuesta humana.':'Waiting for an answer in the local terminal.',
+};
+const states = new Set(['pending', 'in_progress', 'blocked', 'done', 'needs_verification']);
+const checkStates = new Set(['running', 'failed', 'refused', 'interrupted', 'not_dispatched']);
+
+/** Host projection only: no arguments, assertions, file contents, drafts or raw outputs. */
+export function projectRemoteWorkspace(session, context = {}) {
+  const rows = session.rows || [], journal = auditJournal(rows), book = foldWorkBook(session, context);
+  const counts = Object.fromEntries([...states].map(status => [status, book.tasks.filter(task => task.status === status).length]));
+  const tasks = [...book.tasks].sort((a, b) => ['in_progress', 'blocked', 'needs_verification', 'pending', 'done'].indexOf(a.status) - ['in_progress', 'blocked', 'needs_verification', 'pending', 'done'].indexOf(b.status)).slice(0, 24).map(task => ({
+    id: task.id, title: text(task.title, 180), criterion: text(task.criterion, 400),
+    status: journal.verified ? task.status : task.status === 'done' ? 'needs_verification' : task.status,
+    declared_status: states.has(task.declared_status) ? task.declared_status : 'pending',
+    phase: task.phase || 'implementation', reason: text(reasons[task.reason] || task.reason, 240), held_by: task.held_by.slice(0, 24),
+    checks_total: task.checks.length,
+    checks: task.checks.slice(0, 4).map(check => {
+      const step = book.steps.find(step => step.task_id === task.id && step.step_id === check.step_id);
+      const receipt = book.receipts.get(step?.receipt_id);
+      const status = journal.verified && book.checkValid(task, check, step) ? 'passed'
+        : step?.preflight_failure ? 'not_dispatched'
+        : step?.status === 'returned' ? 'stale'
+        : checkStates.has(step?.status) ? step.status : 'pending';
+      return { step_id: check.step_id, operation: text(check.operation, 128), status,
+        ...(receipt ? { receipt_id: receipt.invocation_id, receipt_row: receipt.evidence_row } : {}) };
+    }),
+  }));
+  const references = new Set([...book.steps.map(step => step.receipt_id), ...book.tasks.flatMap(task => task.receipt_ids || [])]);
+  const receipts = [...book.receipts.values()].filter(receipt => references.has(receipt.invocation_id)).slice(-8).reverse().map(receipt => ({
+    id: receipt.invocation_id, operation: text(receipt.operation, 128), status: receipt.status, row: receipt.evidence_row,
+  }));
+  if (!journal.verified) { const previousDone=counts.done; counts.done=0; counts.needs_verification+=previousDone; }
+  const result = {
+    version: 1, scope: 'recorded_work_execution', asked: 'unjudged',
+    source: { session_id: session.id, row: Math.max(0, rows.length - 1), sha256: journal.tip_sha256 || '0'.repeat(64), integrity: journal.verified ? 'verified_hash_chain' : journal.consistent ? 'legacy' : 'invalid' },
+    plan: book.plan ? { version: book.plan.version, objective: text(book.plan.objective, 1000) } : null,
+    counts, tasks_total: book.tasks.length, tasks, receipts,
+  };
+  // The stream has a 48 KiB event ceiling, including its transport envelope.
+  // Keep whole task/check records and disclose omissions through total counts.
+  while (Buffer.byteLength(JSON.stringify(result)) > 36000 && result.tasks.length) result.tasks.pop();
+  return result;
+}