@milpa/comal 0.2.7 → 0.2.8

package/src/plugins.mjs

@@ -4,6 +4,7 @@ import { Operation, immutable, toolEffects } from './operations.mjs';
 import { defaultStateDir } from './compat.mjs';
 import { readPluginConfig, importPluginEntry, inspectPluginModule } from './plugin-config.mjs';
 import { normalizeNotice } from './plugin-notices.mjs';
+import { validateCases, contractOf, operationSurface } from './plugin-contract.mjs';
 import { t, registerMessages } from './i18n/index.mjs';
 
 registerMessages({
@@ -13,8 +14,19 @@ registerMessages({
 // 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 blame = (error, plugin) => Object.assign(error, { plugin });
 const idPattern = /^[a-z][a-z0-9]*(?:-[a-z0-9]+)*$/;
 const jsonCopy = value => JSON.parse(JSON.stringify(value));
+// A provided service in the surface: its type and, for an object or function, its own enumerable keys
+// with the type of each, read from property descriptors (no getter runs). Never the values.
+function serviceSurface(name, value) {
+  const kind = item => item === null ? 'null' : Array.isArray(item) ? 'array' : typeof item;
+  const type = kind(value);
+  if (!['object', 'function', 'array'].includes(type)) return { name, type };
+  try {
+    return { name, type, keys: Object.keys(value).sort().map(key => { const property = Object.getOwnPropertyDescriptor(value, key); return { key, type: !property ? 'missing' : 'get' in property || 'set' in property ? 'accessor' : kind(property.value) }; }) };
+  } catch { return { name, type, keys: null }; }
+}
 const configContract = (id, schema) => new Operation({ name: `${id}_config`, description: 'Plugin configuration', input_schema: schema, run: () => '' });
 
 export function parsePluginCommand(text = '') {
@@ -59,8 +71,33 @@ export class PluginRuntime {
     if (definition.hook_timeout_ms !== undefined && (!Number.isInteger(definition.hook_timeout_ms) || definition.hook_timeout_ms < 10 || definition.hook_timeout_ms > 5000)) throw new Error('hook_timeout_ms requiere 10–5000 ms.');
     const discovery = definition.discovery;
     if (discovery !== undefined && (!discovery || typeof discovery !== 'object' || Array.isArray(discovery) || Object.keys(discovery).some(key => !['description', 'tags'].includes(key)) || typeof discovery.description !== 'string' || discovery.description.length > 300 || discovery.tags && (!Array.isArray(discovery.tags) || discovery.tags.length > 12 || discovery.tags.some(tag => typeof tag !== 'string' || tag.length > 40)))) throw new Error('Discovery de plugin inválido.');
-    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 });
+    // Cases are part of the contract, not of loading: a plugin that loaded before cases existed must still
+    // load. A malformed `cases` export leaves the plugin without a statable contract (contract_invalid).
+    let cases = [], contractInvalid = null;
+    try { cases = validateCases(definition.cases); } catch (error) { contractInvalid = String(error?.message ?? error).slice(0, 2000); }
+    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, cases, contract_invalid: contractInvalid, activate: definition.activate });
+  }
+  // The contract of a scope: its definition and the operations it actually registered, by the short
+  // name the plugin passed to ctx.operation/ctx.command. Trusted: computed in the session's own process.
+  // When it cannot be stated (malformed cases, a case naming no operation, a surface that is not plain
+  // JSON) the plugin still serves and its contract is { id, invalid: reason }: never kept, never repaired.
+  #contractOf(scope) {
+    if (scope.contract) return scope.contract;
+    const { definition } = scope.item, observers = {};
+    for (const { event } of scope.listeners) observers[event] = (observers[event] ?? 0) + 1;
+    try {
+      const invalid = definition.contract_invalid ?? scope.casesInvalid;
+      if (invalid) throw new Error(invalid);
+      scope.contract = contractOf({ id: scope.id, version: definition.version, requires: definition.requires, provides: definition.provides, config_schema: definition.config_schema, tool_loading: definition.tool_loading, discovery: definition.discovery, hook_timeout_ms: definition.hook_timeout_ms, cases: definition.cases,
+        operations: [...scope.operations].map(([name, op]) => operationSurface(op.contract, scope.shortNames.get(name) ?? name)),
+        // A guard is consulted for every operation of its own plugin (#activate), so it covers all of them.
+        guards: { count: scope.guards.length, covers: scope.guards.length ? [...scope.shortNames.values()] : [] },
+        observers, services: [...scope.services].map(([name, service]) => serviceSurface(name, service.value)) });
+    } catch (error) { scope.contract = immutable({ id: scope.id, invalid: String(error?.message ?? error).slice(0, 2000) }); }
+    return scope.contract;
   }
+  /** The contract (plugin-contract.mjs) of the active generation of a plugin, or undefined. */
+  contract(id) { const scope = this.#instances.get(id); return scope?.active ? this.#contractOf(scope) : undefined; }
   register(definition, { config = {}, builtin = false, module, fingerprint } = {}) {
     if (this.#closing) throw new Error('Plugin runtime closed.');
     const manifest = this.#definition(definition);
@@ -70,7 +107,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, ...(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 } : {}) };
+      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 } : {}), ...(scope?.active && scope.contract?.invalid ? { contract_invalid: scope.contract.invalid } : {}), 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 } = {}) {
@@ -112,7 +149,25 @@ export class PluginRuntime {
     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, expect } = {}) {
+  // An import-phase failure is a load failure: it leaves an event naming the plugin. A trust-stale refusal
+  // is not one (the host shows it as pending_trust), and neither is a caller's abort.
+  async #importing(item, signal, expect) {
+    try { return await this.#import(item, signal, expect); }
+    catch (error) {
+      if (error?.code !== 'PLUGIN_TRUST_STALE' && !signal?.aborted) {
+        const live = this.#known.get(item.id);
+        if (live && !this.#instances.get(item.id)?.active) { live.state = 'failed'; }
+        if (live) live.error = error.message;
+        await this.#event({ id: item.id, state: 'failed', phase: 'import', error: error.message });
+      }
+      throw error;
+    }
+  }
+  // admit(stagedContract) is awaited after staging and before the commit (load with an id, reload):
+  // anything but true, or a throw, publishes nothing and rejects with PLUGIN_NOT_ADMITTED. It runs
+  // inside the runtime's queue, so it must not call load/enable/reload/disable/close.
+  async load(id, { signal, expect, admit } = {}) {
+    if (admit !== undefined && (typeof admit !== 'function' || !id)) throw new TypeError('admit requires a plugin id and a function.');
     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));
@@ -122,8 +177,8 @@ export class PluginRuntime {
       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} 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, 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();
+      for (const item of entries) { if (id) this.#dependents(item.id); candidates.push(await this.#importing(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.'); }, admit && { id, admit }); return this.status();
     });
   }
   #open() { if (this.#closing) throw new Error('Plugin runtime closed.'); }
@@ -137,14 +192,15 @@ export class PluginRuntime {
       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 no longer configured: ${id}`);
-      const candidate = item.entry ? await this.#import(item, signal, expect) : { ...item, disabled: false };
+      const candidate = item.entry ? await this.#importing(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 } = {}) {
+  reload(id, { signal, admit } = {}) {
+    if (admit !== undefined && typeof admit !== 'function') return Promise.reject(new TypeError('admit must be a function.'));
     return this.#exclusive(async () => {
       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();
+      this.#dependents(id); await this.#activate([await this.#importing(item, signal)], signal, [], undefined, admit && { id, admit }); return this.status();
     });
   }
   #plan(candidates, retiring = []) {
@@ -153,21 +209,21 @@ export class PluginRuntime {
     const availableItems = new Map([...this.#known.values(), ...candidates].map(item => [item.id, item]));
     for (const item of availableItems.values()) if (item.definition && !retiringIds.has(item.id) && (!item.disabled || selected.has(item.id))) {
       for (const name of item.definition.provides) {
-        const live = this.#services.get(name); if (live && !retiringIds.has(live.owner) && live.owner !== item.id && (selected.has(item.id) || !this.#instances.get(item.id)?.active)) throw new Error(`Servicio ocupado: ${name}`);
-        if (providers.has(name) && providers.get(name).id !== item.id) throw new Error(`Servicio duplicado: ${name}`);
+        const live = this.#services.get(name); if (live && !retiringIds.has(live.owner) && live.owner !== item.id && (selected.has(item.id) || !this.#instances.get(item.id)?.active)) throw blame(new Error(`Servicio ocupado: ${name}`), item.id);
+        if (providers.has(name) && providers.get(name).id !== item.id) throw blame(new Error(`Servicio duplicado: ${name}`), item.id);
         providers.set(name, selected.get(item.id) || item);
       }
     }
     const ordered = [], visiting = new Set(), done = new Set();
     const visit = item => {
-      if (done.has(item.id)) return; if (visiting.has(item.id)) throw new Error(`Dependencia cíclica de plugins: ${item.id}`);
-      if (!item.definition) throw new Error(`Plugin sin manifiesto confiado: ${item.id}`);
+      if (done.has(item.id)) return; if (visiting.has(item.id)) throw blame(new Error(`Dependencia cíclica de plugins: ${item.id}`), item.id);
+      if (!item.definition) throw blame(new Error(`Plugin sin manifiesto confiado: ${item.id}`), item.id);
       visiting.add(item.id);
       for (const name of item.definition.requires) {
         const live = this.#services.get(name);
         if (live && !retiringIds.has(live.owner) && live.owner !== item.id && !selected.has(live.owner)) continue;
         const provider = providers.get(name);
-        if (!provider) throw new Error(`Falta servicio requerido ${name} para ${item.id}.`);
+        if (!provider) throw blame(new Error(`Falta servicio requerido ${name} para ${item.id}.`), item.id);
         visit(provider);
       }
       visiting.delete(item.id); done.add(item.id);
@@ -176,7 +232,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: [], notices: [], 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(), shortNames: 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.'); };
@@ -193,6 +249,7 @@ export class PluginRuntime {
       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, summarize = definition.confirm_summary;
+      scope.shortNames.set(name, definition.name);
       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.
@@ -206,11 +263,13 @@ export class PluginRuntime {
       signal: scope.controller.signal,
       operation: definition => register(definition), command: definition => register(definition, true),
       service: name => { alive(); if (!item.definition.requires.includes(name) || !available.has(name)) throw new Error(`Servicio no declarado/disponible: ${name}`); return available.get(name).value; },
-      provide: (name, value) => { staging(); if (!item.definition.provides.includes(name) || scope.services.has(name)) throw new Error(`Servicio no declarado/duplicado: ${name}`); if (available.has(name) && available.get(name).owner !== item.id) throw new Error(`Servicio ocupado: ${name}`); scope.services.set(name, { owner: item.id, value }); },
+      provide: (name, value) => { staging(); if (!item.definition.provides.includes(name) || scope.services.has(name)) throw new Error(`Servicio no declarado/duplicado: ${name}`); if (available.has(name) && available.get(name).owner !== item.id) throw blame(new Error(`Servicio ocupado: ${name}`), item.id); scope.services.set(name, { owner: item.id, value }); },
       defer: disposer => { alive(); if (typeof disposer !== 'function') throw new Error('Cleanup requiere función.'); scope.disposers.push(disposer); },
       on: (event, listener) => {
-        alive(); if (!['operation:result', 'operation:decision', 'skill:started', 'skill:completed'].includes(event) || typeof listener !== 'function') throw new Error('Hook de plugin inválido.');
-        const watch = { event, listener }; scope.listeners.push(watch); if (scope.active) this.#watch(scope, watch, lease);
+        // Observers are part of the surface the house reads when it stages the plugin: one added after
+        // activation would serve without ever having been in the contract that was compared.
+        staging(); if (!['operation:result', 'operation:decision', 'skill:started', 'skill:completed'].includes(event) || typeof listener !== 'function') throw new Error('Hook de plugin inválido.');
+        const watch = { event, listener }; scope.listeners.push(watch); scope.contract = undefined;
       },
       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.
@@ -228,6 +287,10 @@ export class PluginRuntime {
       signal?.throwIfAborted();
       await item.definition.activate(context, item.config); signal?.throwIfAborted();
       for (const name of item.definition.provides) if (!scope.services.has(name)) throw new Error(`El plugin no publicó el servicio declarado: ${name}`);
+      // Cases name operations: only now are the plugin's operations known. Neither a case that names no
+      // operation nor a surface that is not plain JSON refuses the load; the contract then says it is invalid.
+      try { validateCases(item.definition.cases, scope.shortNames.values()); } catch (error) { scope.casesInvalid = String(error?.message ?? error).slice(0, 2000); }
+      scope.contract = undefined; this.#contractOf(scope);
       return scope;
     } catch (error) { await this.#retire(scope).catch(cleanup => error.cleanup = cleanup.message); throw error; }
     finally { signal?.removeEventListener('abort', abortActivation); }
@@ -247,22 +310,35 @@ export class PluginRuntime {
       });
     }));
   }
-  async #activate(candidates, signal, retiring = [], checkSource) {
-    const staged = [], previous = [...retiring], available = new Map(this.#services); let current, committed = false;
+  async #activate(candidates, signal, retiring = [], checkSource, admission) {
+    const staged = [], previous = [...retiring], available = new Map(this.#services); let current, committed = false, stage = 'plan'; const cleanupIds = [];
     try {
       const plan = this.#plan(candidates, retiring);
       for (const old of retiring) for (const name of old.services.keys()) available.delete(name);
       for (const item of plan) {
         const old = this.#instances.get(item.id); if (old?.active) { previous.push(old); for (const name of old.services.keys()) available.delete(name); }
       }
+      stage = 'stage';
       for (const item of plan) {
         current = item;
         const scope = await this.#stage(item, available, signal); staged.push(scope);
         for (const [name, service] of scope.services) available.set(name, service);
       }
-      signal?.throwIfAborted();
+      stage = 'source'; signal?.throwIfAborted();
       if (checkSource) await checkSource();
       signal?.throwIfAborted();
+      if (admission) {
+        stage = 'admit'; const target = staged.find(scope => scope.id === admission.id);
+        let verdict, refusal;
+        // admit sees everything the commit would publish and retire, not only its target.
+        const context = Object.freeze({ staged: Object.freeze(staged.map(scope => Object.freeze({ id: scope.id, contract: this.#contractOf(scope) }))), retiring: Object.freeze([...new Set(previous.map(scope => scope.id))].sort()) });
+        try { verdict = target ? await admission.admit(this.#contractOf(target), context) : undefined; } catch (error) { refusal = error; }
+        if (verdict !== true) throw Object.assign(new Error(`Plugin ${admission.id} was not admitted; nothing was published.`), { code: 'PLUGIN_NOT_ADMITTED', plugin: admission.id, verdict, ...(refusal ? { cause: refusal } : {}) });
+        signal?.throwIfAborted();
+        // The world may have moved while admit waited (a human reading a card): check the source again.
+        stage = 'source'; if (checkSource) await checkSource();
+        signal?.throwIfAborted();
+      }
       this.house.registry.replace(previous.flatMap(scope => [...scope.operations.keys()]), staged.flatMap(scope => [...scope.operations.values()]));
       this.#services = available;
       for (const old of retiring) { old.item.state = 'disabled'; old.item.disabled = true; }
@@ -276,15 +352,30 @@ export class PluginRuntime {
       committed = true;
       const cleanupTasks = previous.map(old => this.#retire(old));
       const cleanups = await Promise.allSettled(cleanupTasks), failed = cleanups.filter(result => result.status === 'rejected');
+      cleanups.forEach((result, index) => { if (result.status === 'rejected' && !cleanupIds.includes(previous[index].id)) cleanupIds.push(previous[index].id); });
       if (failed.length) throw new AggregateError(failed.map(result => result.reason), 'Falló limpieza de la generación anterior. La nueva sigue activa.');
-      for (const scope of staged) await this.#event({ id: scope.id, state: 'active', operations: [...scope.operations.keys()] });
+      for (const scope of staged) {
+        await this.#event({ id: scope.id, state: 'active', operations: [...scope.operations.keys()] });
+        if (scope.contract?.invalid) await this.#event({ id: scope.id, state: 'contract_invalid', error: scope.contract.invalid });
+      }
     } catch (error) {
+      // An abort is the caller's choice, not a plugin failure: unwind quietly and keep the previous state.
+      const aborted = signal?.aborted;
+      let blamed;
       if (!committed) {
         for (const scope of staged.reverse()) await this.#retire(scope).catch(() => {});
-        const item = current || candidates[0], live = item && this.#known.get(item.id);
-        if (live) { live.error = error.message; if (!this.#instances.get(item.id)?.active) live.state = 'failed'; }
+        blamed = stage === 'plan' ? error.plugin : stage === 'stage' ? current?.id : undefined;
+        const live = blamed && this.#known.get(blamed);
+        if (live) { live.error = error.message; if (!this.#instances.get(blamed)?.active) live.state = 'failed'; }
       }
-      await this.#event({ id: current?.id || candidates[0]?.id, state: committed ? 'cleanup_failed' : 'failed', error: error.message }); throw error;
+      if (aborted && !committed) throw error;
+      // A refusal by admit is the caller's verdict, not a plugin failure: journaled, nothing marked failed.
+      if (!committed && stage === 'admit' && error?.code === 'PLUGIN_NOT_ADMITTED') { await this.#event({ id: admission.id, state: 'not_admitted' }); throw error; }
+      if (committed) {
+        const ids = cleanupIds.length ? cleanupIds : [undefined];
+        for (const id of ids) await this.#event({ ...(id ? { id } : {}), state: 'cleanup_failed', phase: 'cleanup', error: error.message });
+      } else await this.#event({ ...(blamed ? { id: blamed } : {}), state: 'failed', phase: 'activate', error: error.message });
+      throw error;
     }
   }
   async #retire(scope) {

package/src/remote-permissions.mjs

@@ -119,6 +119,13 @@ export async function answerFromEitherSurface({ desk, questionId, name, input, c
   } finally { entry.close(); }
 }
 
+/** The terminal card for PermissionPolicy's confirm: shown => ui.confirm(...) on the given signal. It resolves
+ *  exactly what ui.confirm resolves (a boolean, or { allowed: true, remember } when the policy offered «always»);
+ *  why the card closed travels out of band, to the asking policy's own onOutcome. */
+export function screenTerminal(ui, name, input, { summary, edit, remember, onOutcome } = {}) {
+  return shown => ui.confirm(name, input, shown, { summary, edit, remember, ...(typeof onOutcome === 'function' ? { onOutcome } : {}) });
+}
+
 /** The terminal's line when the M5Stack decided a card. */
 export const deviceAnswerNotice = ({ allowed, tool }) => t('Answered on the M5Stack: {decision} · {tool}', { decision: t(allowed ? 'allowed once' : 'denied'), tool: String(tool ?? '') });
 

package/src/scoped-policy.mjs

@@ -1,5 +1,6 @@
 import {PermissionPolicy,BYPASS_PERMISSION_MODE,PERMISSION_MODES} from './permissions.mjs';
 import {digest,immutable} from './operations.mjs';
+import path from 'node:path';
 
 const fail=message=>Object.assign(new Error(message),{code:'SCOPED_POLICY_INVALID'});
 const modes=new Set([...PERMISSION_MODES,BYPASS_PERMISSION_MODE]);
@@ -17,7 +18,12 @@ export function scopedPolicy({parent,ceiling=capturePolicyCeiling(parent),cwd,in
   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});
+ // The parent's private locations (the --state-dir, wherever it is) are closed for the child's file tools too.
+ // One exception: a workspace the house created for the child inside such a location (an owned Git worktree
+ // under the state directory) is the child's own tree. A child that shares the parent's directory has none.
+ // A policy scoped again in the same directory (a stack of bindings) keeps the workspace its parent was given.
+ const own=typeof parent.cwd==='string'&&path.resolve(parent.cwd)!==path.resolve(cwd)?cwd:parent.ownWorkspace;
+ const initial=mode(),policy=new PermissionPolicy({mode:initial,dangerouslySkipPermissions:initial===BYPASS_PERMISSION_MODE,allowed:original.allowed,denied:original.denied,cwd,onDecision,privateLocations:[...(parent.privateExtra||[])],ownWorkspace:own});
  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},

package/src/sessions.mjs

@@ -89,6 +89,8 @@ export class SessionStore {
     if (rows[0]?.type !== 'session' || rows[0].id !== id || rows[0].cwd !== this.cwd) throw new Error('Invalid session identity for audit.');
     return { id, cwd: this.cwd, rows };
   }
+  // Optional host observer, called synchronously with (id, sealedRow) after each durable append; it cannot fail the append.
+  onAppend = null;
   getLoadProfile(){return this.lastLoadProfile?structuredClone(this.lastLoadProfile):null;}
   async append(id, record) {
     assertClassifierChannels([record]);
@@ -120,7 +122,9 @@ export class SessionStore {
         const row = sealRecord({ ...record, ...(mutex.recovered?{recovered_append_lock:mutex.recovered}:{}), timestamp: new Date().toISOString() }, sequence, previousHash);
         const bytes = Buffer.from(JSON.stringify(row) + '\n');
         for (let offset = 0; offset < bytes.length;) { const written = await file.write(bytes, offset, bytes.length - offset, size + offset); if (!written.bytesWritten) throw new Error('No se pudo completar el asiento del libro.'); offset += written.bytesWritten; }
-        await file.sync(); return row;
+        await file.sync();
+        try { this.onAppend?.(id, row); } catch {}
+        return row;
       } finally { await file?.close(); await mutex.release(); }
     });
     this.writers.set(id, next);

package/src/subagents.mjs

@@ -10,7 +10,7 @@ import { validateInput } from './tool-input.mjs';
 import { webToolDefinitions } from './web-tools.mjs';
 import { House, houseSnapshot } from './house.mjs';
 import { randomUUID } from 'node:crypto';
-import { digest,Operation } from './operations.mjs';
+import { digest,Operation,PLUGIN_REPAIR_OPERATION_NAMES } from './operations.mjs';
 import { processIdentity, processDead, acquireProcessLock } from './process-lock.mjs';
 import { ProviderScheduler } from './provider-scheduler.mjs';
 import { RUN_SOURCE, agentRuns, ensureAgentSession, turnOutcome, outcomeDigest, publicAgentRun } from './durable-agent-runs.mjs';
@@ -136,7 +136,7 @@ export class SubagentManager {
     if (requested.model && parent.model !== requested.model || requested.effort && (parent.effort || 'auto') !== requested.effort) throw Object.assign(new Error('Este host no ofrece un factory para otro modelo/effort hijo.'), { code: 'AGENT_PROVIDER_SCOPE' });
     return { provider: parent, descriptor: { provider: this.providerName, model: this.provider.model, effort: this.provider.effort || 'auto', contextWindow: this.provider.contextWindow || 45000, maxTokens: this.provider.maxTokens || 8192 }, budget_owner: null };
   }
-  toolScope(task) { return (task.tools || []).map(name => { const op = this.house.registry.get(name); if (!op || name.startsWith('Agent') || agentKind(task) !== 'general' && !this.exploreTools.has(name)) throw Object.assign(new Error(`Herramienta hija no admitida por el host: ${name}.`), { code: 'AGENT_TOOL_SCOPE' }); return { name, contract_digest: op.digest }; }); }
+  toolScope(task) { return (task.tools || []).map(name => { const op = this.house.registry.get(name); if (!op || name.startsWith('Agent') || PLUGIN_REPAIR_OPERATION_NAMES.includes(name) || agentKind(task) !== 'general' && !this.exploreTools.has(name)) throw Object.assign(new Error(`Herramienta hija no admitida por el host: ${name}.`), { code: 'AGENT_TOOL_SCOPE' }); return { name, contract_digest: op.digest }; }); }
   async prepareLaunch(name, input, tasks, options, captures) {
     const parentId = options.sessionId || this.getParentId(), invocationId = options.invocation_id || options.callId || randomUUID();
     return this.store.workTransaction(parentId, async () => {
@@ -331,7 +331,7 @@ export class SubagentManager {
     const actor = { id, kind: 'subagent', parent_session_id: parentId }, requested = run.tool_scope || [];
     for (const tool of requested) if (house.registry.get(tool.name)?.digest !== tool.contract_digest || kind === 'explore' && !this.exploreTools.has(tool.name)) throw Object.assign(new Error(`El contrato o admisión de ${tool.name} cambió; no se ejecutó.`), { code: 'AGENT_TOOL_SCOPE_CHANGED' });
     const extra = (run.workspace?evidenceOperations({store,house}).filter(tool=>tool.name==='EvidenceRead'):[...webToolDefinitions,...evidenceOperations({store,house})]).filter(tool=>inScope(tool.name));
-    const child = house.bind({ actor, sessionId: id, policy, onPermission, allowed: [...native, ...extra].map(tool => tool.name).concat(WORK_NAMES, requested.map(tool => tool.name), packs ? ['ToolPack'] : []).filter(inScope), resources: { workspace },
+    const child = house.bind({ actor, sessionId: id, policy, onPermission, allowed: [...native, ...extra].map(tool => tool.name).concat(WORK_NAMES, requested.map(tool => tool.name), packs ? ['ToolPack'] : []).filter(inScope).filter(name => !PLUGIN_REPAIR_OPERATION_NAMES.includes(name)), resources: { workspace },
       select: (name, context) => (!requested.some(tool => tool.name === name) || house.registry.get(name)?.digest === requested.find(tool => tool.name === name).contract_digest) && (!packs || packs.visible(name, id, actor)),
       frontier: async name => {if(runtime)await runtime.check();return !packs||packs.visible(name,id,actor);}, capture: () => packs?.capture(id, actor), unavailable: (name, context) => packs?.unavailable(name, context) });
     const setContext = context => policy.setContext({ actions: context.actions });

package/src/tools.mjs

@@ -102,14 +102,29 @@ export class WorkspaceTools {
         catch (err) { if (err.code !== 'ENOENT') throw err; suffix.unshift(path.basename(ancestor)); ancestor = path.dirname(ancestor); }
       }
     }
+    // An open plugin candidate's tree holds links to host modules (plugin-workbench.mjs): a path that enters
+    // the tree must also end in it, or a write through a link would land on the installed file.
+    const trees = this.policy?.candidateRoots ?? [];
+    if (trees.length) {
+      for (let ancestor = candidate; ; ancestor = path.dirname(ancestor)) {
+        let real = null; try { real = await realpath(ancestor); } catch {}
+        const tree = real && trees.find(root => this.inside(real, root));
+        if (tree && !this.inside(canonical, tree)) throw new Error('The path leaves the plugin candidate tree through a link to a host module; host modules are shared with the house and cannot be changed by a repair.');
+        if (path.dirname(ancestor) === ancestor) break;
+      }
+    }
     const workRoot = this.workRootOf(canonical);
     if (!this.inside(canonical) && !workRoot && !(readable && this.readRootOf(candidate) && this.inside(canonical, this.readRootOf(candidate)))) throw new Error('The symbolic link leaves the workspace.');
     if (this.sourceOwnership.contains(canonical)) throw new Error('Native source ownership state is protected.');
     const first = path.relative(this.cwd, canonical).split(path.sep)[0];
-    if (['.comal', '.harness'].includes(first)) throw new Error('Comal internal state is protected.');
+    // The one exception under Comal state: the exact tree of an open plugin candidate (plugin-repair.mjs).
+    const candidateTree = Boolean(workRoot) && this.policy?.candidateRootOf?.(canonical) === workRoot;
+    if (['.comal', '.harness'].includes(first) && !candidateTree) throw new Error('Comal internal state is protected.');
     // An added directory may be another Comal workspace: its state stays off-limits too.
     if (workRoot && holdsComalState(workRoot, canonical)) throw new Error('Comal internal state is protected.');
-    if (workRoot && this.policy?.isPrivate?.(canonical)) throw new Error('Path protected: private Comal location or a path an active plugin protects.');
+    // Private Comal locations (credentials, trust, rules, the --state-dir under any name) are closed everywhere,
+    // in the workspace too, except an open plugin candidate's tree inside the state directory.
+    if (this.policy?.isPrivate?.(canonical)) throw new Error('Path protected: private Comal location or a path an active plugin protects.');
     return canonical;
   }
   async text(file) {

package/src/tui/controller.mjs

@@ -356,6 +356,6 @@ export class InteractiveController {
   }
   async exit() {
     if (this.closed) return; this.closed = true; clearInterval(this.peerTimer);clearTimeout(this.imageTimer);this.runner.stopped = true; this.backend.interrupt();
-    this.ui.permission?.finish(false); await this.runner.processing;await this.peerProcessing; await this.flushDraft(); await this.queue.save(); this.ui.close();
+    this.ui.permission?.finish(false, 'closed'); await this.runner.processing;await this.peerProcessing; await this.flushDraft(); await this.queue.save(); this.ui.close();
   }
 }

package/src/tui/discovery.mjs

@@ -148,7 +148,7 @@ function argumentItems(command, args, context) {
     if (command === 'relay') return named(['status', 'new', 'start', 'stop', 'unlink', 'hub'], t("Swarm project of this repo; every step is a card you confirm"));
     if (command === 'timing') return named(['on', 'off'], t("Show or hide response timing after each answer"));
     if (command === 'mcp') return named(['status', 'list', 'config', 'reload', 'reconnect', 'add', 'remove'], t("Action on MCP servers"));
-    if (command === 'plugins') return named(['status', 'list', 'available', 'add', 'config', 'enable', 'disable', 'reload', 'run', 'allow', 'trust', 'untrust', 'remove'], t("Action on plugins"));
+    if (command === 'plugins') return named(['status', 'list', 'available', 'add', 'config', 'enable', 'disable', 'reload', 'run', 'allow', 'trust', 'untrust', 'remove', 'repairs', 'acts', 'revert'], t("Action on plugins"));
     if (command === 'chrome-workflow') return named(['auto', 'raw'], 'Saved per project; applies to the entry of this session');
     if (command === 'agent') return named(['explore', 'general','background'], t("Subagent type; complete the task afterwards"));
     if (command === 'inbox') return named(['status', 'accept', 'hold', 'refuse', 'release'], t("Mailbox control between sessions"));
@@ -157,7 +157,7 @@ function argumentItems(command, args, context) {
   if (position === 1) {
     if(command==='agents' && ['status','wait','stop','resume','background'].includes(first))return entries(context.agents,'id');
     if (command === 'mcp' && ['reconnect', 'remove'].includes(first)) return entries(context.mcpServers);
-    if (command === 'plugins' && ['enable', 'disable', 'reload', 'run', 'config', 'allow', 'untrust', 'remove'].includes(first)) return entries(context.plugins, 'id');
+    if (command === 'plugins' && ['enable', 'disable', 'reload', 'run', 'config', 'allow', 'untrust', 'remove', 'revert'].includes(first)) return entries(context.plugins, 'id');
     if (command === 'plugins' && first === 'add') return named(['chrome-lab', 'open-relay', 'omarchy'], 'Plugin bundled with Comal');
     if (command === 'inbox' && first === 'release') return named(['all'], t("Release held messages; does not change hold mode"));
     if (command === 'queue' && first === 'edit') return named((context.queue?.items || []).map((_, index) => String(index + 1)), t("Edit this pending message"));

package/src/tui/screen.mjs

@@ -401,13 +401,16 @@ export class TerminalScreen {
     const options = permission.choices.map((choice, index) => index === permission.choice ? (choice === 'no' ? tone.warning(`❯ ${labels[choice]}`) : tone.good(`❯ ${labels[choice]}`)) : `  ${labels[choice]}`);
     return [clip(t('  Always = save rule {v0}', { v0: permission.remember.rule }), columns - 1), '  ' + options.join('   '), tone.muted(clip(t('  Enter confirms · y once · {v0}u always for me · n/Esc denies', { v0: permission.choices.includes('project') ? t('p this project · ') : '' }), columns - 1))];
   }
-  async confirm(name, input, signal, { summary, remember, edit } = {}) {
-    if (signal?.aborted || this.closed) return false;
+  // onOutcome(why) says why the card closed — 'allowed', 'no' (the human's plain No), 'edit', 'interrupt',
+  // 'aborted', 'closed' or 'unknown' — without changing what confirm resolves to.
+  async confirm(name, input, signal, { summary, remember, edit, onOutcome } = {}) {
+    const tell = why => { try { onOutcome?.(why); } catch {} };
+    if (signal?.aborted || this.closed) { tell(signal?.aborted ? 'aborted' : 'closed'); return false; }
     if (this.selecting) this.setSelection(false);
     return measureHumanWait(new Promise(resolve => {
       let settled=false;
-      const finish = allowed => { if(settled)return;settled=true;signal?.removeEventListener('abort', abort);if(this.permission===question)this.permission = null;this.schedule();resolve(allowed); };
-      const abort = () => finish(false);
+      const finish = (allowed, why = allowed ? 'allowed' : 'unknown') => { if(settled)return;settled=true;signal?.removeEventListener('abort', abort);if(this.permission===question)this.permission = null;this.schedule();tell(why);resolve(allowed); };
+      const abort = () => finish(false, 'aborted');
       // remember: { rule, project } ofrece «sí, siempre»; la regla se muestra antes de elegir.
       const choices = remember?.rule ? ['once', ...(remember.project ? ['project'] : []), 'user', 'no'] : null;
       const question = { name, input, summary, edit: edit && typeof edit.field === 'string' && typeof edit.text === 'string' ? { field: edit.field, text: edit.text } : null, allowed: false, scroll: 0, finish, ...(choices ? { remember, choices, choice: choices.length - 1 } : {}) };
@@ -418,7 +421,7 @@ export class TerminalScreen {
   // pasa al composer con una instrucción. El humano lo corrige y lo envía; el modelo
   // vuelve a proponer la operación y la tarjeta nueva muestra el texto exacto otra vez.
   editPermission() {
-    const { name, edit } = this.permission; this.permission.finish(false);
+    const { name, edit } = this.permission; this.permission.finish(false, 'edit');
     const before = this.composer.text;
     try {
       this.composer.setText(before ? before + '\n\n' : '');
@@ -493,15 +496,15 @@ export class TerminalScreen {
       return;
     }
     if (key.ctrl && name === 'c' && this.overlay?.kind === 'palette' && !this.permission) { this.closeOverlay(); return; }
-    if (key.ctrl && name === 'c') { if (this.permission) this.permission.finish(false); if (this.busy) await this.callbacks.onAction?.('interrupt'); else if (this.composer.text) { this.composer.clear(); this.draftChanged(); } else await this.callbacks.onAction?.('exit'); return; }
+    if (key.ctrl && name === 'c') { if (this.permission) this.permission.finish(false, 'interrupt'); if (this.busy) await this.callbacks.onAction?.('interrupt'); else if (this.composer.text) { this.composer.clear(); this.draftChanged(); } else await this.callbacks.onAction?.('exit'); return; }
     if (this.permission) {
       const permission = this.permission, answer = choice => choice === 'project' || choice === 'user' ? { allowed: true, remember: choice } : choice === 'once';
-      if (name === 'escape' || name === 'n') permission.finish(false);
+      if (name === 'escape' || name === 'n') permission.finish(false, 'no');
       else if (name === 'y') permission.finish(true);
       else if (permission.choices && ((name === 'p' && permission.choices.includes('project')) || name === 'u')) permission.finish(answer(name === 'p' ? 'project' : 'user'));
       else if (permission.choices && (name === 'left' || name === 'right' || name === 'tab')) permission.choice = (permission.choice + (name === 'left' ? permission.choices.length - 1 : 1)) % permission.choices.length;
       else if (name === 'left' || name === 'right' || name === 'tab') permission.allowed = !permission.allowed;
-      else if (name === 'return') permission.finish(permission.choices ? answer(permission.choices[permission.choice]) : permission.allowed);
+      else if (name === 'return') { const value = permission.choices ? answer(permission.choices[permission.choice]) : permission.allowed; permission.finish(value, value ? 'allowed' : 'no'); }
       else if (name === 'pageup') this.permission.scroll = Math.max(0, this.permission.scroll - 10);
       else if (name === 'pagedown') this.permission.scroll += 10;
       else if (name === 'r') { this.permission.raw = !(this.permission.raw ?? this.rawView); this.permission.scroll = 0; }
@@ -823,7 +826,7 @@ export class TerminalScreen {
     if (this.closed) return; this.closed = true;
     this.agentStatus?.close();
     this.clearSetup();
-    this.permission?.finish(false); clearInterval(this.timer); clearTimeout(this.renderTimer); this.decoder?.close();
+    this.permission?.finish(false, 'closed'); clearInterval(this.timer); clearTimeout(this.renderTimer); this.decoder?.close();
     if (this.onData) this.input.off('data', this.onData); if (this.onResize) this.output.off('resize', this.onResize);
     if (this.started) { this.input.setRawMode?.(this.originalRaw); this.input.pause(); if (!this.suspended) this.output.write('\x1b[0m' + MOUSE_OFF + '\x1b[?2004l\x1b[?25h\x1b[?1049l'); }
     this.resolveFinished();