@milpa/comal 0.1.7 → 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/scope-ceiling.mjs

@@ -0,0 +1,56 @@
+import {digest,immutable} from './operations.mjs';
+export const SCOPE_MECHANISM='comal-house-scope-v1';
+export const scopeFailure=(message,code='HOUSE_SCOPE_UNAVAILABLE')=>Object.assign(new Error(message),{code});
+const id=value=>typeof value==='string'&&/^[A-Za-z0-9][A-Za-z0-9_.:-]{0,127}$/.test(value);
+export function guardIdentity(name,binding,token){
+ if(!id(name))throw scopeFailure('The guard needs a bounded host identity.','HOUSE_SCOPE_INVALID');
+ if(binding===undefined)return immutable({id:name,instance_token:token});
+ if(!id(binding?.revision)||binding.configuration_digest!=null&&!/^[a-f0-9]{64}$/.test(binding.configuration_digest))throw scopeFailure('The host guard implementation/configuration identity is invalid.','HOUSE_SCOPE_INVALID');
+ return immutable({id:name,revision:binding.revision,configuration_digest:binding.configuration_digest??null});
+}
+export function mechanismIdentity(name,binding){
+ if(!id(name)||!id(binding?.revision)||typeof binding.check!=='function'||!Array.isArray(binding.operations)||binding.operations.some(name=>name!=='*'&&!id(name))||binding.configuration_digest!=null&&!/^[a-f0-9]{64}$/.test(binding.configuration_digest))throw scopeFailure('The host mechanism identity is invalid.','HOUSE_SCOPE_INVALID');
+ return immutable({id:name,revision:binding.revision,operations:[...binding.operations],configuration_digest:binding.configuration_digest??null});
+}
+export function scopeCeiling(body){return immutable({...body,digest:digest(body)});}
+export function validateScopeCeiling(value,parent){
+ if(!value||typeof value!=='object')throw scopeFailure('The original scope ceiling is missing.','HOUSE_SCOPE_INVALID');
+ const{digest:stamp,...body}=value;
+ try{
+  if(body.schema!=='comal-scope-ceiling/1'||digest(body)!==stamp||!body.parent||typeof body.parent.house!=='string'||typeof body.parent.session_id!=='string'||digest(body.parent)!==digest(parent)||!Array.isArray(body.laws)||body.laws.length>64||!Array.isArray(body.guards)||body.guards.length>128||Buffer.byteLength(JSON.stringify(value))>1024*1024||Object.keys(body).some(key=>!['schema','parent','laws','guards'].includes(key)))throw Error();
+  for(const source of body.laws){
+   if(!source||typeof source.house!=='string'||typeof source.session_id!=='string'||typeof source.activation_id!=='string'||!/^[a-f0-9]{64}$/.test(source.mechanism_stamp||'')||!Array.isArray(source.mechanisms))throw Error();
+   const{plan_hash,...core}=source.plan||{};if(core.schema!=='comal-governance/v1'||digest(core)!==plan_hash||!Array.isArray(core.gates)||!Array.isArray(core.decisions))throw Error();
+   for(const entry of source.mechanisms){const identity=entry?.identity;if(!id(entry?.gate_id)||!id(identity?.id)||!id(identity?.revision)||!Array.isArray(identity.operations)||identity.operations.some(op=>op!=='*'&&!id(op)))throw Error();}
+  }
+  for(const guard of body.guards)if(!id(guard?.id)||!(id(guard.revision)&&guard.instance_token===undefined||guard.revision===undefined&&/^[a-f0-9-]{36}$/.test(guard.instance_token||'')))throw Error();
+ }catch{throw scopeFailure('The original scope ceiling or parent binding does not verify.','HOUSE_SCOPE_INVALID');}
+ return immutable(structuredClone(value));
+}
+
+// Local semantic audit of a recorded scope; never re-runs a guard or mechanism.
+export function auditScopeAuthority(rows,{cwd,id:sessionId}={}){
+ const violations=[],starts=new Map(),fault=(row,reason)=>violations.push({invocation_id:row.invocation_id,operation:row.operation,reason}),births=rows.filter(row=>row.type==='house_scope_bound');let birth,revoked=false,activeLaw;
+ for(const row of rows){
+  if(row.type==='house_scope_bound'){
+   if(birth)fault(row,'scope_birth_duplicated');
+   try{validateScopeCeiling(row.ceiling,{house:row.parent_house,session_id:row.parent_session_id});if(row.source!=='scope_host'||row.mechanism!==SCOPE_MECHANISM||row.ceiling_digest!==row.ceiling.digest||row.house!==cwd||row.session_id!==sessionId||!row.actor?.id||!['agent','subagent','human'].includes(row.actor.kind)||!/^[a-f0-9-]{36}$/.test(row.scope_id||''))throw Error();birth=row;}catch{fault(row,'scope_birth_invalid');}
+  }
+  if(row.type==='house_scope_revoked'){
+   if(row.source!=='scope_host'||row.mechanism!==SCOPE_MECHANISM||row.house!==cwd||row.session_id!==sessionId||birth&&row.scope_id!==birth.scope_id)fault(row,'scope_revocation_invalid');else revoked=true;
+  }
+  if(!birth)continue;
+  if(['house_proposal','house_started','house_receipt'].includes(row.type)&&digest(row.actor??null)!==digest(birth.actor))fault(row,'scope_actor_binding_mismatch');
+  if(row.type==='house_started')starts.set(row.invocation_id,{revoked,missingLaw:birth.ceiling.laws.length&&(!activeLaw||row.governance_plan_hash!==activeLaw.plan.plan_hash||row.mechanism_stamp!==activeLaw.mechanism_stamp||row.governance_activation_id!==activeLaw.activation_id)});
+  if(row.type==='house_receipt'&&['returned','failed'].includes(row.status)){const start=starts.get(row.invocation_id);if(start?.revoked)fault(row,'scope_dispatch_after_revocation');if(start?.missingLaw)fault(row,'scope_dispatch_without_original_law');}
+  if(row.type==='governance_activated')activeLaw=row.inherited_from?row:null;
+  if(row.type==='governance_activated'&&row.inherited_from){
+   try{if(!Array.isArray(row.inherited_from))throw Error();for(const source of birth.ceiling.laws){
+    const ref={house:source.house,session_id:source.session_id,plan_hash:source.plan.plan_hash,mechanism_stamp:source.mechanism_stamp,activation_id:source.activation_id},index=row.inherited_from.findIndex(value=>digest(value)===digest(ref));
+    if(index<0){fault(row,'scope_original_law_omitted');continue;}const prefix='scope'+index+':',scope=name=>prefix+(prefix.length+name.length>128?digest(name):name);
+    for(const gate of source.plan.gates){const actual=row.plan?.gates?.find(value=>value.id===scope(gate.id));if(!actual||actual.tier!==gate.tier||digest(actual.operations)!==digest(gate.operations)||actual.decision_id!==scope(gate.decision_id))fault(row,'scope_original_gate_changed');}
+   }}catch{fault(row,'scope_original_law_invalid');}
+  }
+ }
+ return{scope:'recorded_scope_identity_and_revocation',births:births.length,revoked,consistent:!violations.length,violations,executable_attestation:false};
+}

package/src/scoped-policy.mjs

@@ -0,0 +1,39 @@
+import {PermissionPolicy,BYPASS_PERMISSION_MODE,PERMISSION_MODES} from './permissions.mjs';
+import {digest,immutable} from './operations.mjs';
+
+const fail=message=>Object.assign(new Error(message),{code:'SCOPED_POLICY_INVALID'});
+const modes=new Set([...PERMISSION_MODES,BYPASS_PERMISSION_MODE]);
+export function capturePolicyCeiling(parent,intentions=parent.context?.intentions||[]){
+ return immutable({mode:parent.mode,allowed:[...parent.allowed],denied:[...parent.denied],intention_digest:digest(intentions)});
+}
+// Restoring a saved ceiling never restores startup bypass or grants from a child
+// prompt. Actual source root and local recorder belong to the scoped runtime.
+export function scopedPolicy({parent,ceiling=capturePolicyCeiling(parent),cwd,intentions=parent.context?.intentions||[],actions=[],readOnly=false,onDecision=()=>{}}){
+ if(!parent?.authorize||typeof cwd!=='string'||!modes.has(ceiling?.mode)||!['allowed','denied'].every(key=>Array.isArray(ceiling[key])&&ceiling[key].every(name=>typeof name==='string'))||ceiling.intention_digest&&ceiling.intention_digest!==digest(intentions))throw fail('The original policy ceiling or trusted human context does not verify.');
+ const original=immutable(structuredClone(ceiling)),trusted=immutable(structuredClone(intentions)),initialActions=immutable(structuredClone(actions));
+ const mode=()=>{
+  if(readOnly)return 'plan';const current=parent.mode,prior=original.mode;if(!modes.has(current))throw fail('The current parent mode is unavailable.');
+  if(prior===BYPASS_PERMISSION_MODE)return current===BYPASS_PERMISSION_MODE&&!parent.dangerouslySkipPermissions?'default':current;
+  if(current===BYPASS_PERMISSION_MODE)return prior;
+  return prior==='plan'||current==='plan'?'plan':prior==='default'||current==='default'?'default':prior==='auto'||current==='auto'?'auto':'acceptEdits';
+ };
+ const initial=mode(),policy=new PermissionPolicy({mode:initial,dangerouslySkipPermissions:initial===BYPASS_PERMISSION_MODE,allowed:original.allowed,denied:original.denied,cwd,onDecision});
+ Object.defineProperties(policy,{
+  mode:{get:mode},allowed:{get:()=>new Set(original.allowed.filter(name=>parent.allowed.has(name)))},denied:{get:()=>new Set([...original.denied,...parent.denied])},
+  classifier:{get:()=>parent.classifier},confirm:{get:()=>parent.confirm},rules:{get:()=>parent.rules},contractOf:{get:()=>parent.contractOf},ceiling:{value:original},
+ });
+ policy.setContext=context=>PermissionPolicy.prototype.setContext.call(policy,{intentions:structuredClone(trusted),actions:[...initialActions,...(context?.actions||[])].slice(-20)});
+ policy.setContext({actions:[]});return policy;
+}
+
+// A chain must retain each trusted human context as well as intersecting rule
+// sets/modes. Merely nesting scopedPolicy objects selects the newest context
+// for the classifier; a later broader request could then replace the old one.
+export function scopedPolicyStack({parent,bindings,cwd,onDecision=()=>{}}){
+ if(!Array.isArray(bindings)||!bindings.length)throw fail('A policy stack requires original native bindings.');
+ const scope=(parent,b)=>scopedPolicy({parent,ceiling:b.authority,cwd,intentions:b.inherited.intentions,actions:b.inherited.actions,onDecision});
+ const combined=bindings.reduce(scope,parent),unique=[...new Map(bindings.map(b=>[digest({authority:b.authority,inherited:b.inherited}),b])).values()],checks=unique.map(b=>scope(combined,b));
+ const setContext=combined.setContext.bind(combined);combined.setContext=context=>{setContext(context);for(const policy of checks)policy.setContext(context);};
+ combined.authorize=async(name,input,options)=>{let result;for(const policy of checks){result=await policy.authorize(name,input,options);if(!result.allowed)return result;}return result;};
+ return combined;
+}